API: Tutor¶

Базовый URL: http://localhost:8001. Префикс: /api/tutor.

Auth: Bearer JWT.
Гейт: MEDICAL_ASSISTANT_ENABLED=true + роль из LEARNING_ROLES.
Admin ingest: дополнительно admin / super_admin.

При выключенном ассистенте — 503 Medical Assistant is disabled.

POST /api/tutor/ask¶

Задать вопрос репетитору.

Request

{
  "question": "What are first-line ACS steps?",
  "language": "en",
  "session_id": null
}

Поле	Тип	Обязательно	Описание
`question`	string	да	1–4000 символов
`language`	string \| null	нет	`en` / `ru` (иначе язык сессии / default)
`session_id`	UUID \| null	нет	Продолжить сессию; `null` — создать новую

Response 200

{
  "answer": "...",
  "confidence": 0.72,
  "sources": [{"title": "...", "text": "...", "similarity": 0.8, "language": "en"}],
  "language": "en",
  "session_id": "…"
}

Пишет сообщения в сессию и запись прогресса module=tutor.

GET /api/tutor/sessions¶

Список своих сессий (до 50, по updated_at desc).

Response 200

{
  "items": [
    {"id": "…", "title": "…", "language": "en", "updated_at": "2026-07-24T00:00:00+00:00"}
  ]
}

GET /api/tutor/sessions/{session_id}¶

История сообщений сессии (только владелец).

Response 200

{
  "id": "…",
  "title": "…",
  "language": "en",
  "messages": [
    {
      "id": "…",
      "role": "user",
      "content": "…",
      "sources": null,
      "created_at": "…"
    }
  ]
}

404 — сессия не найдена.

DELETE /api/tutor/sessions/{session_id}¶

Удалить сессию. 204 без тела. 404 если чужая / нет.

POST /api/tutor/knowledge/ingest¶

Admin upsert документов в RAG.

Request

{
  "documents": [
    {
      "id": "optional-id",
      "title": "ACS — initial steps",
      "category": "guidelines",
      "language": "en",
      "text": "Obtain ECG within 10 minutes…"
    }
  ]
}

text или content обязателен хотя бы у одного документа. language нормализуется к en|ru.

Response 200

{
  "upserted": 1,
  "external_upserted": 0,
  "ids": ["admin_en_…"],
  "mode": "local"
}

400 — нет текста. 503 — RAG выключен.

GET /api/tutor/knowledge/status¶

Статус RAG без секретов.

Response 200

{
  "enabled": true,
  "mode": "local",
  "collection": "medical_knowledge",
  "external_configured": false,
  "hybrid_local_weight": 0.5,
  "admin_uploads": 3,
  "admin_uploads_by_language": {"en": 2, "ru": 1},
  "languages": ["en", "ru"]
}

Пример curl¶

curl -s -X POST http://localhost:8001/api/tutor/ask \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"question":"Тропонин при ОКС","language":"ru"}'