symfonic.core.contracts.types¶
types ¶
Phase 3 type definitions. All Pydantic BaseModel(frozen=True).
ActivationEvent ¶
Bases: BaseModel
A single memory node activated during spreading activation.
AskUserAnsweredEvent ¶
Bases: BaseModel
Fires when a resume call succeeds and the graph is unpaused.
AskUserExpiredEvent ¶
Bases: BaseModel
Would fire when a janitor sweeps an expired checkpoint.
.. warning:: Nothing constructs this today. There is no janitor. A handler written for it will never be called. It is kept declared rather than deleted because it is already exported, and because the shape is right if a sweeper is ever built.
The sweeper was deliberately NOT built (decision 2026-08-07). The
problem it was meant to solve -- a user who abandons an ask_user
question poisoning the thread forever -- is instead fixed where it
costs nothing and needs nothing to fire:
_close_unanswered_tool_calls(core/nodes/react.py) pairs the orphaned call on the wire, leaving the checkpoint untouched;ask_user_pending_is_current(core/nodes/elicitation.py) makes every router ignore a marker from an earlier run.
Both act on the next turn regardless of whether anything swept, and
critically both keep the checkpoint lossless -- so a user who
answers hours later can still resume. A janitor cannot: it writes a
NEW checkpoint, which voids the checkpoint_id the pause token
pins, destroying exactly that late answer. That trade-off is why
sweeping is opt-in work for an operator who wants it, not framework
behaviour.
AskUserQuestionEvent ¶
Bases: BaseModel
Emitted when the LLM calls the built-in ask_user tool.
The graph is paused at this point and will only advance when a
matching POST to /api/v1/resume/{pause_token} arrives.
ConsolidationScheduledEvent ¶
Bases: BaseModel
Emitted after consolidation is scheduled (background task, not yet complete).
ExtensionEvent ¶
Bases: BaseModel
Vendor-specific or custom event. Never dropped, never raises.
GraphEdgeCreatedEvent ¶
Bases: BaseModel
Emitted when a new edge is written during consolidation.
GraphNodeCreatedEvent ¶
Bases: BaseModel
Emitted when a new node is written to the graph during consolidation.
MemoryExtractedEvent ¶
Bases: BaseModel
Emitted when an extraction block is parsed from the stream.
MessageEndEvent ¶
Bases: BaseModel
End of message.
MessageStartEvent ¶
Bases: BaseModel
Start of a new message.
ResponseCompleteEvent ¶
Bases: BaseModel
Final clean response text — equivalent of AgentResponse.final_response.
SearchResultEvent ¶
Bases: BaseModel
Search result from external capability.
TextDeltaEvent ¶
Bases: BaseModel
Incremental text chunk from LLM.
ThinkingDeltaEvent ¶
Bases: BaseModel
Incremental thinking/reasoning chunk.
ToolCallDeltaEvent ¶
Bases: BaseModel
Incremental tool call arguments.
ToolCallStartEvent ¶
Bases: BaseModel
Tool call initiated by LLM.
A single logical tool call can legitimately produce two of these events
at different lifecycle points: "announced" when the model's own
streamed generation first reveals the tool call, and "executing"
when the runtime actually dispatches it (e.g. LangGraph's
on_tool_start). They carry different tool_call_id spaces (model
tool-call id vs. run id) and are not otherwise correlated -- consumers
that want exactly one "announce this to the user" signal per real tool
call should filter to a single phase rather than assume one event.
ToolProgressEvent ¶
Bases: BaseModel
Intermediate progress emitted by an async-generator tool.
Yielded between ToolCallStartEvent and the final
ToolResultEvent. Carries an opaque payload; the tool author
chooses the shape. sequence is monotonically increasing (0-indexed)
per tool_call_id so a consumer can detect drops.
The engine emits this when a registered tool is an
inspect.isasyncgenfunction: each non-final yield becomes one
ToolProgressEvent; the last yield becomes the existing
ToolResultEvent. Regular async def tools see zero
behaviour change.
ToolResultEvent ¶
Bases: BaseModel
Result returned from tool execution.
UsageEvent ¶
Bases: BaseModel
Token usage report.