One design principle carries the whole system: the curriculum and the mastery state live outside the model — deterministic, versioned, queryable in Postgres. The LLM tutors inside a bounded turn. It never chooses the curriculum, and it never decides mastery. Everything on this page is a consequence of that split.
The diagram shows a student browser exchanging turns with the tutor runtime, which runs six modes (solve, question, research, guide, chat, vision) over two engines separated by a seam: a custom pipeline and a LangGraph engine. Every exchange with the curriculum and mastery store, a Postgres database, passes through the non-spoiling gate. Two satellites attach with dashed lines: the teacher platform (assign, curate, heatmap) and the eval harness (readiness and socratic facades).
Every turn traverses the same graph. The reveal policy is resolved before any text exists; the draft is checked after the text exists; a leaking draft loops back instead of shipping. The animation below plays the traversal — including one rejected draft.
The graph runs policy, context, generate, detect. A flagged draft goes to regen and back through context and generate for a second detection pass. A clean draft goes to deliver, then assess, then advance_hint, which loops back into context for the next turn.
Per session, student, and concept the tutor persists a finite-state machine over eight student states and a position on a four-rung hint ladder. The rules are deliberately small: saying “I don’t know” twice in a row escalates one rung; demanding the answer never does; and no rung can exceed the disclosure ceiling set by the reveal policy. Play the scripted lesson to watch all three rules fire.
—
—
—
rung metacognitive
disclosure in use 1 / 6
ceiling fixed by policy — personas and demands cannot move it
Personas restyle the voice; the ceiling is policy.
Interactive figure. Eight turns of a scripted physics lesson step through the student state machine: new, exploring, partial, stuck (twice, after two I-don’t-know turns, which escalates the hint ladder one rung), answer_seeking (after a demand for the answer, which does not escalate the ladder), misconception, ready_for_step, and mastered after a passed mini-check. A persona selector switches the tone of the tutor lines between socratic, coach, and examiner while the disclosure ceiling line never moves.
The gate is not a prompt asking the model to behave. It is a scorer with thresholds, a term list with categories, and a ceiling matrix — all outside the model, all testable. If a policy string is unknown, the resolver fails safe to LOCKED.
Leak-risk score: 0 means no detected answer leakage; 1 means a clear leak. At or above the threshold, the reply is discarded and regenerated.
The tutor may build a worked partial, but it never reveals the final answer.
On a hit: discard the draft, rewrite it, and run every check again.
The tutor may diagnose and point in a direction, but never carry the learner through the solution.
On a hit: discard the draft, rewrite it, and run every check again.
Lower threshold = stricter policy. LOCKED regenerates sooner than GUIDED.
Detection runs in three layers: forbidden-term overlap, semantic similarity, then an independent leak-risk check.
| # | category | behavior |
|---|---|---|
| 1 | result values — the final number or expression of the active task | block |
| 2 | solution procedures — named algorithms and step recipes | block |
| 3 | target concept terms — the vocabulary the lesson builds toward | block |
| 4 | formula identifiers — named formulas and their canonical forms | block |
| 5 | paraphrase equivalents — near-synonyms and rewordings of the above | block |
| 6 | misconception phrasings — wrong-but-common student formulations | gentle correction |
| 7 | unlocked vocabulary — terms the student already earned or introduced | allow |
Matching is German-compound-safe: a blocked stem embedded inside a compound word still trips the check.
| policy | diagnostic | conceptual | directional | scaffolded | worked partial | reveal |
|---|---|---|---|---|---|---|
| FREE | ● | ● | ● | ● | ● | ● |
| TEACHER_OVERRIDE | ● | ● | ● | ● | ● | ● |
| REVIEW | ● | ● | ● | ● | ● | — |
| GUIDED | ● | ● | ● | ● | ● | — |
| PRACTICE | ● | ● | ● | ● | — | — |
| LOCKED | ● | ● | ● | — | — | — |
LOCKED caps at a directional hint — the tutor may point, never carry. Six policies, six levels, one lookup; no generation-time judgment call about what may be revealed.
Before any turn, the runtime reads the prerequisite graph and the mastery state. What the tutor may assume — and what it must probe first — is decided here, not in the prompt.
Select a roster entry to overlay its mastery state on the slice.
Seven concepts connected by prerequisite edges: Vectors feeds Velocity and Mass, both feed Newton II, which feeds Acceleration and Friction, which feed Application. Selecting class average, Alex, or Sam recolors each node green, amber, or red by mastery score and updates a commentary line describing what the tutor does with that state.
A hard prerequisite blocks: the concept stays locked until the prerequisite is mastered. A soft prerequisite warns: the concept opens, but the tutor knows the footing is thin and probes before assuming. The readiness ratio — mastered prerequisites over total — decides whether a node shows as ready, available, or blocked, and struggling students are routed back along the same edges.
Prerequisite edges are generated deterministically: within each competence area of the Austrian curriculum, subcompetencies form a chain ordered by grade — the spiral the curriculum itself prescribes. No LLM sits in that loop; the graph is reproducible from the curriculum CSV files. The result is generated and teacher-curated, versioned; per-edge provenance tooling is ongoing work.
The class heatmap stores rows under HMAC pseudonyms and names as AES-GCM ciphertext. The key is derived from a teacher passphrase that never leaves the browser — so the server cannot decrypt what it stores.
The teacher’s passphrase derives the key locally. It is never transmitted.
Only pseudonyms and ciphertext arrive. The server cannot recover a student name.
The heatmap returns ciphertext. Decryption happens inside the teacher’s browser.
Sequence: the teacher enters a passphrase in the browser; PBKDF2-SHA256 with 600,000 iterations derives an AES-GCM-256 key that stays in memory. The browser sends HMAC pseudonyms and ciphertext to the server, which stores them but cannot decrypt. On load, ciphertext returns to the browser, where decryption happens and real names render. The server-side region is marked: it sees pseudonyms and ciphertext only.
Every learning mechanism and safeguard shown here can be explored with a teacher, school, or ministry team. Email works best.
Qriouso is funded by netidee — the internet funding programme of the Internet Privatstiftung Austria, supporting open internet projects made in Austria.
