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_scaffold(scheduler: 'TutorScheduler', neuron_id: str) -> 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

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.

front abstractmethod

front() -> RenderedContent

Return the initial (question) side.

back abstractmethod

back() -> RenderedContent

Return the answer side — shown after flip or submit.

grade abstractmethod

grade(response: QuizResponse) -> QuizResult

Grade a response. Return QuizResult with needs_tutor_grading set to True if the quiz type cannot grade mechanically.

preferred_mode

preferred_mode() -> RenderMode

Preferred render mode. Override for audio/image quizzes.

grade_choices_spec

grade_choices_spec() -> list

Grade choices shown to the learner. Default: empty (quiz type provides its own grade input widget).

render

render() -> RenderResponse

Return the full render payload for an agent or TUI.

submit async

submit(response: QuizResponse) -> None

Record a response and release anyone waiting on submission.

wait_for_submit async

wait_for_submit() -> QuizResponse

Block until a response is submitted via submit.

Flashcard

Flashcard(neuron: NeuronView, scaffold: Scaffold)

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.

GeneratedQuiz

GeneratedQuiz(item: QuizItem, scaffold: Scaffold)

Bases: BaseQuiz

Render a stored QuizItem as a self-graded quiz.