Scaffold & Quiz¶
ZPD-inspired scaffolding and the Quiz protocol.
Scaffold Computation¶
compute_scaffold and its result types Scaffold / ScaffoldLevel
live in spikuit-tutor. As of v0.9.0 — the Stage 2 tutor
extraction — they are no longer part of the spikuit_core.appkit
contract: scaffolding reads FSRS card state, which the substrate no
longer holds. compute_scaffold reads card state from the tutor's
overlay store and graph topology from the substrate live, so it belongs
with the tutor application package. The appkit surface that adapters
program against is now Grade, Spike, QuizItem, QuizItemRole,
NeuronView, and the SubstrateView structural protocol.
compute_scaffold ¶
Compute scaffolding for a neuron from substrate state + FSRS cards.
Returns a Scaffold with: - level: how much support to provide - context: strong neighbor IDs (scaffolding material) - gaps: weak prerequisite IDs (should study first)
Scaffold ¶
Bases: Struct
Scaffolding state computed from substrate topology + FSRS cards.
Attributes:
| Name | Type | Description |
|---|---|---|
level |
ScaffoldLevel
|
Current support level. |
hints |
list[str]
|
Auto-generated hint strings. |
context |
list[str]
|
IDs of strong neighbors (scaffolding material). |
gaps |
list[str]
|
IDs of weak prerequisites (should study first). |
ScaffoldLevel ¶
Bases: str, Enum
How much support the learner needs (ZPD-inspired).
Attributes:
| Name | Type | Description |
|---|---|---|
FULL |
New or struggling — max hints, context, easy questions. |
|
GUIDED |
Progressing — hints on request, some context. |
|
MINIMAL |
Competent — harder questions, less hand-holding. |
|
NONE |
Mastered — application / synthesis level. |
Quiz Protocol¶
The BaseQuiz protocol and its concrete implementations live in
spikuit-tutor — core is LLM-free and the grader-bound quiz types
belong with the tutor application package (extracted from spikuit-cli
in v0.7.x).
BaseQuiz ¶
Bases: ABC
Base class for every Quiz v2 type.
Subclasses implement front, back, grade, and optionally
preferred_mode / grade_choices_spec. They are constructed with
enough state to render themselves; selection, scheduling, and
persistence are the caller's concern.
back
abstractmethod
¶
Return the answer side — shown after flip or submit.
grade
abstractmethod
¶
Grade a response. Return QuizResult with needs_tutor_grading set to True if the quiz type cannot grade mechanically.
preferred_mode ¶
Preferred render mode. Override for audio/image quizzes.
grade_choices_spec ¶
Grade choices shown to the learner. Default: empty (quiz type provides its own grade input widget).
submit
async
¶
Record a response and release anyone waiting on submission.
wait_for_submit
async
¶
Block until a response is submitted via submit.
Flashcard ¶
Bases: BaseQuiz
Self-graded flashcard over one neuron.
Front shows a scaffold-appropriate preview; back shows full content.
Grading is mechanical — the response's self_grade is the result.
FreeResponseQuiz ¶
FreeResponseQuiz(neuron: 'NeuronView', scaffold: 'Scaffold', *, question: str | None = None, rubric: str | None = None)
Bases: BaseQuiz
Open-ended prompt over one neuron.
grade() always returns needs_tutor_grading=True — the caller
must run an LLMGrader and feed the finished result back to the
tutor session via record_llm_graded.
Cloze ¶
Cloze(neuron: NeuronView, scaffold: Scaffold, *, title: str, body: str, term: str, meaning: str, direction: Direction, prod_title: str, prod_body: str)
Bases: BaseQuiz
Directional vocab recall over one vocab-shaped neuron.
Construct via :meth:try_build, which returns None when the neuron is
not cloze-shaped. The direction (recognition vs production) is chosen from
the scaffold level at construction time.