AI Mode and the tutor

Two separate features. Different endpoints, different prompts, different limits, different rules about what they may say.

AI Mode — /ai

A persistent multi-turn chat, scoped to the library the learner can already see: articles, article sections, questions and flashcards.

It retrieves first and generates second. retrieve() runs hybrid search across each corpus — up to 6 per kind, 14 sources in total — optionally reranked by the cross-encoder, with a boost for a pair an educator has already tied together.

Citations are checked after the fact. Every [[kind:ref]] marker the model writes is matched against the shortlist that was actually retrieved, and stripped if it was invented. Retrieval decides what may be cited; the model does not.

The four answer modes

Mode	When	What the learner sees
chat	Small talk, or a question about the assistant itself	An answer. No retrieval, no shortlist, no citations, no thread name.
sourced	Best similarity ≥ 0.55	An answer grounded in named library sources.
adjacent	Between 0.50 and 0.55	An answer that says the library covers something nearby rather than this.
open	Below 0.50, or nothing retrieved	An answer with no sources, and it says so.

Small talk is detected before retrieval, deliberately: a greeting scores 0.46–0.51 against a clinical corpus, which straddles the adjacency threshold, so the closeness gate cannot be the guard.

The measurement behind 0.55 and 0.50 is in Retrieval thresholds.

Practice from a conversation

"Test me on DKA" is answered deterministically in code, with no model call. A conversation can also be turned into a session with POST /ai/conversations/{id}/practice — always in learning mode, never exam.

Limits and shape

• 60 messages a day per learner (ai_mode_daily:{user_id}:{date})
• The last 8 messages of the thread are sent as history
• With AI_MODE_ENGINE=agent, answers come back through a structured schema — mechanism, bedside bullets, an optional check-yourself question — rather than hoping the model follows a markdown template. Any failure falls back to the plain prompt path. See AI Mode agent.

The tutor — the drawer beside a question

A question-scoped explainer, not a library-wide chat. It is given:

• the stem and the options
• the correct answer and the explanation, and it is explicitly allowed to reveal them
• up to 4 semantically similar questions, with their answers
• any figures attached to the question, read through the vision model

It offers three follow-up chips after each turn.

Limit: 30 messages a day per learner (teach_chat_daily:{user_id}:{date}).

When the tutor is refused

Because it holds the answer key:

• During an exam-mode attempt — refused outright, always.
• During a study-mode attempt — allowed, unless an administrator has turned the tutor_in_quiz site flag off.
• Reviewing a finished attempt — always allowed. The answer is already out.

GET /teach/prompt (moderator-only) returns the literal system prompt, so what the tutor has been told can be audited rather than guessed at.