Contracts¶
All data flowing between layers is a Pydantic model. The names below are part of the v1.0.0 stable contract surface (stability spec §1.4) — field rename = major bump, field addition with default = minor bump.
Run / Pipeline / Batch¶
Bases: BaseModel
Result of a runtime run.
Bases: BaseModel
A step in a sequential chain/pipeline.
Bases: BaseModel
Result of a chain/pipeline execution.
Bases: BaseModel
Result of a batch execution (multiple independent runs).
Configuration¶
Bases: BaseModel
Configuration for a single agent in a team.
Bases: BaseModel
Configuration for an Arcana Runtime.
Turn (arcana.contracts.turn)¶
The V2 separation principle: facts are what the LLM said, assessment is what the runtime concluded.
Bases: BaseModel
Raw facts from LLM response. NO runtime interpretation.
_parse_turn() ONLY populates this -- no inference, no heuristics. This is a 1:1 mapping of what the provider API returned.
Bases: BaseModel
Runtime's interpretation of the turn. Separate from facts.
_assess_turn() ONLY populates this. This is where completion detection, failure detection, and other runtime judgments live. Never mixed into TurnFacts.
LLM (arcana.contracts.llm)¶
Bases: BaseModel
A single message in a conversation.
property
¶
Lazily compute and cache the token estimate for this message.
Bases: str, Enum
Role of a message in a conversation.
Bases: BaseModel
Request to an LLM.
Bases: BaseModel
Response from an LLM.
Bases: BaseModel
A typed content block within a message.
Supports text, image, image_url, tool_use, tool_result, thinking, and document types. All type-specific fields are optional to allow flexible construction.
For images there are two canonical representations:
image-- Anthropic-native format usingsource(base64 / URL).image_url-- OpenAI-compatible format usingimage_urldict.
Both are first-class; the gateway providers convert as needed.
Bases: BaseModel
Configuration for a specific model.
Context (arcana.contracts.context)¶
Bases: BaseModel
A discrete block of context content.
Bases: BaseModel
Record of why context was composed this way for a single LLM call.
Every turn, the WorkingSetBuilder produces one of these. It answers: - Was anything compressed or dropped? - How full is the context window? - Where did the tokens go? - What information was lost?
Bases: BaseModel
Structured per-message evidence for context composition.
Every message in the input to WorkingSetBuilder produces one of these in the resulting ContextDecision. Answers, for each message: was it kept verbatim, compressed (and to what fidelity), dropped, or folded into a summary?
Bases: BaseModel
Report of how context was composed for a single LLM call.
Produced by WorkingSetBuilder and attached to RunResult, ChatResponse, TraceEvent, and StreamEvent for full visibility into context window usage.
Bases: BaseModel
Configuration for adaptive context compression strategy.
Defines thresholds for when to apply different compression levels based on context window utilization ratio.
Modes
- "adaptive": Select strategy based on utilization thresholds (default)
- "off": Never compress
- "always_compress": Always apply compression
Bases: str, Enum
Bases: BaseModel
Token allocation for a single LLM call.
Bases: BaseModel
The assembled context for a single LLM call.
Bases: BaseModel
What the current step needs.
Diagnosis (arcana.contracts.diagnosis)¶
Bases: BaseModel
Complete diagnosis of what went wrong and what to do about it.
Generate a structured recovery prompt for the LLM.
Pure method -- no side effects. Produces a human-readable summary that the LLM can use to adjust its next action.
Bases: str, Enum
What kind of mistake was made.
This is the semantic-layer classification: what went wrong and why.
It drives the recovery prompt shown to the LLM, complementing the
transport-layer ToolErrorCategory which drives the automatic retry loop.
Bases: str, Enum
Where in the pipeline the error originated.
Bases: str, Enum
What the system should do about the error.
Escalation curve (defaults): Attempt 1: RETRY_WITH_MODIFICATION Attempt 2: RETRY_WITH_MODIFICATION Attempt 3: SWITCH_TOOL or NARROW_SCOPE Attempt 4: ESCALATE Attempt 5: ABORT
Streaming (arcana.contracts.streaming)¶
Bases: BaseModel
Unified streaming event for Runtime and Graph execution.
Bases: str, Enum
Unified stream event types for both Runtime and Graph execution.
Cognitive (arcana.contracts.cognitive)¶
The opt-in cognitive primitives (recall, pin, unpin).
Bases: BaseModel
Request to recall an earlier turn.
turn is 1-indexed — the first user-visible turn is 1.
Bases: BaseModel
Structured recall result.
On success, found=True and messages contains the recovered
messages in trace order (each a role/content dict, optionally with
tool_calls). On failure, found=False and note carries a
human-readable, actionable explanation the LLM can reason about.
Errors are never raised as exceptions — they are always returned as structured tool results (Principle 5).
Bases: BaseModel
Request to pin content against future compression.
Bases: BaseModel
Structured pin result.
On success: pinned=True and pin_id is the opaque handle the LLM
uses with unpin. already_pinned is true when the same content was
already pinned (idempotent no-op).
On refusal: pinned=False and the remaining fields explain why. The
framework never auto-unpins; the LLM decides whether to unpin something
else, shrink the content, or proceed without pinning.
Bases: BaseModel
Request to remove a pin by pin_id.
Bases: BaseModel
Structured unpin result.