Models

Core data models using msgspec.Struct.

Enums

Grade

Bases: int, Enum

Spike grade — maps to FSRS Rating.

Attributes:

Name	Type	Description
MISS		Failed recall (FSRS Again).
WEAK		Uncertain recall (FSRS Hard).
FIRE		Correct recall (FSRS Good).
STRONG		Perfect recall (FSRS Easy).

SynapseType

Bases: str, Enum

Types of synaptic connections between Neurons.

Attributes:

Name	Type	Description
REQUIRES		Directed — A requires understanding B.
EXTENDS		Directed — A extends B.
CONTRASTS		Bidirectional — A contrasts with B.
RELATES_TO		Bidirectional — general association.

is_bidirectional property

is_bidirectional: bool

Whether this synapse type creates edges in both directions.

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.

Data Models

Neuron

Bases: Struct

A unit of knowledge — the fundamental node in a Circuit.

Content is stored as Markdown with optional YAML-style frontmatter. Only minimal metadata is extracted into fields for indexing.

Attributes:

Name	Type	Description
id	str	Unique identifier (auto-generated as n-<hex12>).
content	str	Markdown content, optionally with YAML frontmatter.
type	str | None	Category tag (e.g. "concept", "fact", "procedure").
domain	str | None	Knowledge domain (e.g. "math", "french").
source	str | None	Origin URL or reference.
created_at	datetime	UTC timestamp, auto-set on creation.
updated_at	datetime	UTC timestamp, auto-set on creation and mutation.

create classmethod

create(content: str, **overrides: Any) -> Neuron

Create a Neuron from Markdown content, extracting frontmatter.

Generates a unique ID and parses YAML-style frontmatter for type, domain, and source fields. Explicit overrides take precedence over frontmatter values.

Parameters:

Name	Type	Description	Default
content	str	Markdown text, optionally starting with --- frontmatter.	required
**overrides	Any	Field overrides (id, type, domain, source).	{}

Returns:

Type	Description
Neuron	A new Neuron instance.

Synapse

Bases: Struct

A directed connection between two Neurons.

Bidirectional types (contrasts, relates_to) are stored as two Synapse objects — one in each direction. Weights may be asymmetric.

Attributes:

Name	Type	Description
pre	str	Source neuron ID (pre-synaptic).
post	str	Target neuron ID (post-synaptic).
type	SynapseType	Connection semantics (see SynapseType).
weight	float	Edge strength, updated by STDP (range: [weight_floor, weight_ceiling]).
co_fires	int	Number of times both endpoints fired within tau_stdp.
last_co_fire	datetime | None	Timestamp of the most recent co-fire event.
created_at	datetime	UTC timestamp, auto-set on creation.
updated_at	datetime	UTC timestamp, auto-set on creation and mutation.

Spike

Bases: Struct

A review event — an action potential in the Circuit.

Created by external layers (Quiz, CLI, etc.) and fed into Circuit.fire() to trigger FSRS update + propagation.

Attributes:

Name	Type	Description
neuron_id	str	The neuron being reviewed.
grade	Grade	Review quality (see Grade).
fired_at	datetime	UTC timestamp, auto-set to now.
session_id	str | None	Optional session identifier for grouping spikes.
notes	str | None	Optional free-text feedback captured with the review.

Plasticity

Bases: Struct

Tunable learning parameters — configurable per Circuit. Immutable.

Controls how activation propagates, how edges strengthen/weaken, and how pressure accumulates and decays.

Attributes:

Name	Type	Description
alpha	float	APPNP teleport probability (higher = more local).
propagation_steps	int	APPNP power-iteration steps.
tau_stdp	float	STDP time window in days.
a_plus	float	STDP LTP amplitude (pre-before-post strengthening).
a_minus	float	STDP LTD amplitude (post-before-pre weakening).
tau_m	float	LIF membrane time constant in days (pressure decay rate).
pressure_threshold	float	LIF pressure threshold for spontaneous review.
pressure_rest	float	LIF resting pressure.
pressure_reset	float	Pressure value after a neuron fires.
theta_pro	int	STC promotion threshold (co-fire count).
schema_factor	float	Bonus factor for schema-connected neurons.
weight_floor	float	Minimum allowed edge weight.
weight_ceiling	float	Maximum allowed edge weight.

Scaffold

Bases: Struct

Scaffolding state computed from Brain data.

Determines how much support a Learn session provides, based on FSRS state, graph context, and pressure.

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).

Quiz Models

QuizRequest

Bases: Struct

Input for quiz generation — what to ask and how.

Attributes:

Name	Type	Description
primary	str	Primary neuron ID to quiz on.
supporting	list[str]	Supporting neuron IDs for context.
scaffold	Scaffold	Scaffolding state for difficulty adaptation.
quiz_type	str | None	Question style — "recall", "recognition", "application", "synthesis", or None for auto.

QuizItem

Bases: Struct

A quiz question — generated by LLM or created manually.

Persisted in the quiz_items table with neuron associations in quiz_item_neurons (M:N via neuron_ids).

Attributes:

Name	Type	Description
id	str	Unique identifier (auto-generated as q-<hex12>).
question	str	The question text.
answer	str	The expected answer.
hints	list[str]	Progressive hints (reveal one at a time).
grading_criteria	str	Free-text criteria for LLM-based grading.
scaffold_level	ScaffoldLevel | None	The scaffold level this item was designed for.
neuron_ids	dict[str, QuizItemRole]	Mapping of neuron ID to role (primary/supporting).
created_at	datetime	UTC timestamp, auto-set on creation.

primary_neuron_ids property

primary_neuron_ids: list[str]

Neuron IDs with the PRIMARY role.

supporting_neuron_ids property

supporting_neuron_ids: list[str]

Neuron IDs with the SUPPORTING role.

QuizResult

Bases: Struct

Result of a quiz — per-neuron grades + overall.

Attributes:

Name	Type	Description
grades	dict[str, Grade]	Mapping of neuron ID to grade.
overall	Grade	Aggregate grade for the quiz.