Building a session¶
/study/new builds a session out of the bank. POST /questions/builder takes
the filters; POST /questions/builder/describe takes a sentence instead.
The filters¶
| Field | Accepts |
|---|---|
category_ids |
Topics. Each expands to every category beneath it. |
state |
all, unused, incorrect, bookmarked |
count |
1 – 200 |
expected_count |
The count the page showed. If the bank moved underneath you, the build is refused rather than quietly giving you a different paper. |
difficulty |
easy, medium, hard |
algorithm |
random, adaptive, blueprint |
article_ids |
Only questions linked to this reading |
tag_ids |
AND — a question must carry all of them |
system_ids |
Organ systems. OR, matched through topic descendants |
explicit_ids |
Exactly these questions |
mode |
timed or learning |
time_limit_minutes, is_shared, is_repetition |
bookmarked reads the same stars as Favourites.
Building from a description¶
POST /questions/builder/describe takes free text — "neonatal jaundice, the
ones about exchange transfusion" — runs it through hybrid search, reranks the
result with the cross-encoder, and builds a paper from what comes back. It is
one of the few places reranking is applied; see
Reranking.
The three algorithms¶
random¶
The filters, shuffled. Nothing else.
blueprint¶
Draws a paper shaped to an examining board's published content outline: the domain weights decide how many questions come from where. Largest-remainder allocation, so a 40-question paper from percentage weights actually sums to 40. See Exams and blueprints.
adaptive¶
This is the Adaptive toggle, and it is the same ranking the "Ready for you" session uses.
What it selects. Unseen material fills the session first. Review — material you have seen and that is now due — fills at most 40% of it. "Due" means the estimated recall probability has fallen below 0.7.
How it ranks. Every candidate gets a priority:
- unseen:
(1 − accuracy on that topic) × blueprint weight - review:
(1 − recall) × blueprint weight
multiplied by a per-topic difficulty fit. Each pick then halves its own topic's priority, so a session spreads instead of burrowing.
Difficulty targeting. Readiness below 0.45 targets easy, below 0.78 targets medium, above that hard. A question at the wrong level is preferred against with a multiplier of 0.72 or 0.5 — never filtered out. There is always something to draw.
How evidence ages. Evidence decays exponentially with a 30-day half-life. Recall settles toward 0.85 after a correct answer and 0.25 after a wrong one, and both then decay toward 0.5 — a coin flip — not toward zero. Not having seen something for a year means you do not know whether you know it, which is a different statement from knowing you have forgotten it.
Blueprint weighting. If the learner has an active exam, that exam's blueprint weight scales each topic's priority. A topic the blueprint does not mention gets the median published weight rather than zero or maximum.
What it ignores. Only completed, non-expired, non-repetition attempts feed the ranking, and only those within the active exam's scope if one is set.
Ties. Candidates are scanned in question-id order and every tie resolves to the lowest id, so the preview and the committed session never disagree.
The design note behind all of this is Adaptive sessions.
Ready for you¶
GET /questions/builder/prepared returns the plan — the shape of the session,
the topics and the counts — without the question ids. It is a preview and
nothing more. POST to the same address recomputes the plan and commits a
session from that plan's own ids, so what you are given is what the page just
described rather than a second draw that happens to be similar.
How long it is. After three finished sessions, the length is the learner's own median finished-session length. Before that it is 20. Either way it is clamped to 5–60.
With no history at all — zero finished sessions — there is nothing to be adaptive about, so it draws a seeded blueprint-shaped paper instead.