Sessions

Interaction modes for the Brain. The Circuit is the universal backend; Sessions define how you interact with it.

RetrievalResult dataclass

RetrievalResult(neuron_id: str, score: float, content: str, context_ids: list[str] = list(), sources: list[Source] = list())

A single retrieval result with metadata.

Attributes:

Name	Type	Description
neuron_id	str	The matched neuron's ID.
score	float	Relevance score (higher = better).
content	str	Neuron content (Markdown).
context_ids	list[str]	IDs of ensemble neighbors (N-hop context).
sources	list[Source]	Source records attached to this neuron (for citation).

Session

Session(circuit: Circuit, *, persist: bool = True)

Bases: ABC

Abstract base for Brain interaction sessions.

All sessions wrap a Circuit and can be either persistent (changes committed on close) or ephemeral (changes discarded on close).

Parameters:

Name	Type	Description	Default
circuit	Circuit	The Circuit to interact with.	required
persist	bool	Whether to commit changes on close.	True

close abstractmethod async

close() -> None

End the session. Persistent sessions commit weights.

reset abstractmethod

reset() -> None

Reset session state without closing.

QABotSession

QABotSession(circuit: Circuit, *, persist: bool = True, learning_rate: float = 0.1, exclude_seen: bool = True)

Bases: Session

RAG chat session with self-optimizing retrieval.

Provides intelligent retrieval that improves during the conversation:

• Negative feedback: follow-up similar queries penalize prior results
• Deduplication: already-returned neurons are excluded
• Accept: explicit positive feedback boosts neurons
• Persistent/ephemeral: choose whether to commit boosts on close

Example

session = QABotSession(circuit, persist=True)
results = await session.ask("What is a functor?")
await session.accept(["n-abc123"])  # this one was helpful
results = await session.ask("functor examples?")  # auto-penalizes prior
await session.close()  # commits boosts if persistent

Parameters:

Name	Type	Description	Default
circuit	Circuit	The Circuit (must have an embedder configured).	required
persist	bool	Commit retrieval boosts on close.	True
learning_rate	float	Feedback strength (default 0.1).	0.1
exclude_seen	bool	Skip already-returned neurons (default True).	True

turns property

turns: int

Number of ask() calls in this session.

stats property

stats: dict

Session statistics.

ask async

ask(query: str, *, limit: int = 10) -> list[RetrievalResult]

Ask a question. Returns scored, deduplicated results.

Automatically applies negative feedback if this is a follow-up to a similar prior query (implicit signal that prior results were insufficient).

accept async

accept(neuron_ids: list[str]) -> None

Mark neurons as helpful (positive feedback).

Boosts retrieval_boost with diminishing returns.

reset

reset() -> None

Reset session state (new topic). Does NOT reset boosts.

close async

close() -> None

End the session. Commits boosts if persistent.

IngestSession

IngestSession(circuit: Circuit, *, persist: bool = True, auto_relate: bool = True, auto_relate_limit: int = 5)

Bases: Session

Conversational knowledge curation session.

Lets a user (or agent) build and refine the knowledge graph through dialogue: add neurons, discover related concepts, create synapses, and merge duplicates. This is how conversational RAG curation works — the conversation directly improves retrieval quality by curating the graph structure.

Example

session = IngestSession(circuit)
n, related = await session.ingest(
    "# Functor\n\nA mapping between categories.",
    type="concept",
)
if related:
    await session.relate(n.id, related[0].id, SynapseType.REQUIRES)
print(session.stats)
await session.close()

Parameters:

Name	Type	Description	Default
circuit	Circuit	The Circuit to curate.	required
persist	bool	Commit retrieval boosts on close.	True
auto_relate	bool	Automatically search for related neurons on ingest.	True
auto_relate_limit	int	Max related neurons returned by ingest.	5

stats property

stats: dict

Session statistics.

ingest async

ingest(content: str, *, type: str | None = None, domain: str | None = None, source: str | None = None, source_meta: Source | None = None, id: str | None = None) -> tuple[Neuron, list[Neuron]]

Add a neuron and discover related existing knowledge.

Creates the neuron, auto-embeds it (if an embedder is configured), and searches for related neurons via graph-weighted retrieval.

When source_meta is provided, the source is deduplicated by URL, created if new, and attached to the new neuron.

Parameters:

Name	Type	Description	Default
content	str	Markdown content for the new neuron.	required
type	str | None	Category tag (e.g. "concept").	None
domain	str | None	Knowledge domain (e.g. "math").	None
source	str | None	Origin URL or reference (legacy string field).	None
source_meta	Source | None	Structured Source for citation tracking.	None
id	str | None	Custom neuron ID (auto-generated if None).	None

Returns:

Type	Description
Neuron	Tuple of (new_neuron, related_neurons). Use
list[Neuron]	relate() to connect them.

relate async

relate(a: str, b: str, type: SynapseType = SynapseType.RELATES_TO, *, weight: float = 0.5) -> list[Synapse]

Create or strengthen a synapse between two neurons.

If the synapse already exists, its weight is increased by 0.1 (capped at plasticity.weight_ceiling). Bidirectional types create edges in both directions.

Parameters:

Name	Type	Description	Default
a	str	Source neuron ID.	required
b	str	Target neuron ID.	required
type	SynapseType	Connection semantics (default relates_to).	RELATES_TO
weight	float	Initial weight for new synapses.	0.5

Returns:

Type	Description
list[Synapse]	List of created or updated synapses.

search async

search(query: str, *, limit: int = 10) -> list[Neuron]

Search existing knowledge using graph-weighted retrieval.

Parameters:

Name	Type	Description	Default
query	str	Search text.	required
limit	int	Maximum results.	10

Returns:

Type	Description
list[Neuron]	Matching neurons sorted by relevance.

merge async

merge(source_ids: list[str], into_id: str) -> Neuron

Merge source neurons into a target neuron.

Transfers all synapses from source neurons to the target, appends their content with --- separators, then removes the source neurons.

Parameters:

Name	Type	Description	Default
source_ids	list[str]	IDs of neurons to merge (will be deleted).	required
into_id	str	ID of the target neuron (will be preserved).	required

Returns:

Type	Description
Neuron	The updated target neuron with merged content.

Raises:

Type	Description
ValueError	If the target neuron does not exist.

reset

reset() -> None

Reset session tracking state.

close async

close() -> None

End the session.

TutorSession moved to spikuit_cli.tutor in v0.6.3 — the core is LLM-free and the tutor orchestration belongs with the CLI.

TutorSession

TutorSession(circuit: 'Circuit', plan: ExamPlan, *, persist: bool = True)

Interprets an ExamPlan.

teach async

teach() -> ExamStep | None

Advance to the next step, returning None when exhausted.

record_response async

record_response(response: 'QuizResponse') -> TransitionResult

Grade the current step's quiz and return the next transition.

record_llm_graded async

record_llm_graded(result: 'QuizResult') -> TransitionResult

Accept a pre-graded QuizResult (from an LLMGrader) for the current step. Used when Quiz.grade() returned needs_tutor_grading=True.

record_follow_up async

record_follow_up(fu_result: FollowUpResult) -> TransitionResult

Record a follow-up result and either emit the next follow-up or advance past the step.

FollowUpResult is a distinct type from QuizResult — by design, these never reach circuit.fire.

close async

close() -> None

End the session. Any in-flight step with no grade is fired as MISS (matches legacy TutorSession behavior).

advance async

advance() -> TransitionResult

Commit the current step (fire FSRS) and advance the cursor.

Called by the caller after handling ADVANCE / REVEAL_ANSWER transitions. Kept separate from record_response so callers can interleave follow-ups / UI before committing.