> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learnway.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Tutor

> Interactive AI tutor powered by Google Gemini with Redis response caching.

# AI Tutor

The AI Tutor allows learners to ask clarifying questions about specific lessons, request summaries, ask for quiz hints, or simplify complex topics.

***

## Ask the AI Tutor

Submit a predefined prompt type or a custom question for a lesson. Predefined prompt responses are cached in Redis for 24 hours.

### Endpoint

```http theme={null}
POST /api/v2/ai-tutor/ask
```

### Headers

```http theme={null}
Authorization: Bearer <jwt_access_token>
```

### Request Body

| Field            | Type     | Required | Description                                                  |
| :--------------- | :------- | :------- | :----------------------------------------------------------- |
| `lessonId`       | `string` | **Yes**  | UUID of the active lesson                                    |
| `promptType`     | `string` | **Yes**  | `EXPLAIN`, `SUMMARIZE`, `QUIZ_HINT`, `SIMPLIFY`, or `CUSTOM` |
| `customQuestion` | `string` | No       | Required if `promptType` is `CUSTOM` (max 500 characters)    |

```json theme={null}
{
  "lessonId": "9f1e8d7c-6b5a-4321-fedc-ba9876543210",
  "promptType": "EXPLAIN",
  "customQuestion": "Can you explain how gas fees work in this context?"
}
```

### Response (200 OK)

```json theme={null}
{
  "success": true,
  "data": {
    "requestId": "req-987213",
    "lessonId": "9f1e8d7c-6b5a-4321-fedc-ba9876543210",
    "promptType": "EXPLAIN",
    "answer": "Gas fees represent the computational effort required to execute operations on the blockchain...",
    "isCached": false,
    "remainingDailyQuota": 18
  },
  "message": "AI response returned successfully"
}
```

***

## Submit AI Feedback

Rate an AI response (helpful vs not helpful) to improve model tuning.

### Endpoint

```http theme={null}
POST /api/v2/ai-tutor/feedback
```

### Request Body

| Field       | Type     | Required | Description                             |
| :---------- | :------- | :------- | :-------------------------------------- |
| `requestId` | `string` | **Yes**  | ID from previous AI tutor response      |
| `rating`    | `number` | **Yes**  | `1` for thumbs up, `-1` for thumbs down |
| `comment`   | `string` | No       | Optional user feedback comment          |

```json theme={null}
{
  "requestId": "req-987213",
  "rating": 1,
  "comment": "Very clear explanation!"
}
```

### Response (200 OK)

```json theme={null}
{
  "success": true,
  "message": "Feedback recorded successfully"
}
```