API: Tutor¶

Base URL: http://localhost:8001. Prefix: /api/tutor.

Auth: Bearer JWT.
Gate: MEDICAL_ASSISTANT_ENABLED=true plus a LEARNING_ROLES role.
Admin ingest: also requires admin / super_admin.

When disabled → 503 Medical Assistant is disabled.

POST /api/tutor/ask¶

Ask the tutor a question.

Request

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

Field	Type	Required	Description
`question`	string	yes	1–4000 characters
`language`	string \| null	no	`en` / `ru` (else session / default)
`session_id`	UUID \| null	no	Continue a session; `null` creates one

Response 200

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

Persists chat messages and a progress row with module=tutor.

GET /api/tutor/sessions¶

List your sessions (up to 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}¶

Session message history (owner only).

Response 200

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

404 if not found.

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

Delete a session. 204 empty body. 404 if missing / not yours.

POST /api/tutor/knowledge/ingest¶

Admin upsert into RAG.

Request

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

At least one document needs text or content. language normalizes to en|ru.

Response 200

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

400 — no text. 503 — RAG disabled.

GET /api/tutor/knowledge/status¶

RAG status without secrets.

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 example¶

curl -s -X POST http://localhost:8001/api/tutor/ask \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"question":"Troponin in ACS","language":"en"}'