Documentation Index
Fetch the complete documentation index at: https://septemberai.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
When two modules need to talk, they talk through a typed contract. This
page lists the contract types that matter — the ones that, if changed,
ripple across the codebase. The authoritative source for these types is
the engine repo itself; this page summarizes the shape and links to the
canonical locations.
If you’re about to add a new public surface that crosses a module
boundary, define the type here first, then implement against it. The
project’s CLAUDE.md mandates this — types in a central place, modules
import from there.
Content blocks
The fundamental unit of LLM communication. A message is a list of
content blocks; a model response is a list of content blocks.
Source: src/herald/engine_contracts/__init__.py (re-exports from
src/herald/types.py).
| Type | Purpose |
|---|
TextBlock | Plain text. Streamed as text_delta. |
ThinkingBlock | Internal reasoning. Streamed as thinking_delta. |
ToolUseBlock | A tool call request from the model. |
ToolResultBlock | The result fed back into context after a tool call. |
ImageBlock | An image input or output. |
class TextBlock:
type: Literal["text"]
text: str
class ToolUseBlock:
type: Literal["tool_use"]
id: str
name: str
input: dict
Messages
A turn or part of a turn.
| Type | Purpose |
|---|
Message | One conversation message. Has a role and a list of content blocks. |
LLMResponse | The non-streaming response shape from herald. |
StreamEvent | One chunk in a streaming response from herald. |
src/utility_directory/, src/herald/engine_contracts/.
| Type | Purpose |
|---|
ToolDef | A tool’s metadata: name, description, input schema. |
ToolCall | An invocation of a tool: name, input, optional id. |
Utility | The wrapper around a tool’s executable behavior. |
ToolDef is the schema the model sees in its system prompt. ToolCall
is what the model issues. Utility is what the Engine actually invokes.
Events
The vocabulary of the SSE stream and the in-process event bus.
Source: src/engine_core/events.py.
There are 32+ event types. The major families:
- Lifecycle —
ThreadLifecycle, TaskLifecycle.
- Content —
TextDelta, ThinkingDelta, ContentBlockStart,
ContentBlockStop.
- Tools —
ToolCall, ToolResult, ToolError.
- HITL —
HitlRequest, HitlResolved, PermissionPrompt.
- Memory —
WorkingMemoryUpdate, MemoryRetrieval.
- Compaction —
CompactionEvent.
- Diagnostics —
Heartbeat, Usage, Error, CacheHitRatioAlert.
Every event has a timestamp, a task_id, and a type. Concrete
fields vary by type.
Errors
Stable error codes used across the Engine.
Source: src/errors.py.
class ErrorCode(str, Enum):
INVALID_KEY = "INVALID_KEY"
KEY_ROTATION_PENDING = "KEY_ROTATION_PENDING"
TASK_NOT_FOUND = "TASK_NOT_FOUND"
HITL_REQUIRED = "HITL_REQUIRED"
LLM_PROVIDER_ERROR = "LLM_PROVIDER_ERROR"
LLM_RATE_LIMITED = "LLM_RATE_LIMITED"
CONTEXT_OVERFLOW = "CONTEXT_OVERFLOW"
PERMISSION_DENIED = "PERMISSION_DENIED"
MCP_CONNECTION_FAILED = "MCP_CONNECTION_FAILED"
MCP_TOKEN_EXPIRED = "MCP_TOKEN_EXPIRED"
MIGRATION_REQUIRED = "MIGRATION_REQUIRED"
# …
class EngineError(Exception):
code: ErrorCode
message: str
details: dict | None
Memory primitives
The records persisted in the brain.
Source: src/memory/.
| Type | Where | Purpose |
|---|
Episode | episodic_memory.py | An event with a description, value, tier, and embedding. |
KnowledgeFact | knowledge_store.py | A typed assertion (fact / rule / heuristic) with confidence and validity. |
SocialNode, SocialEdge | social_graph.py | People and their relationships. |
LogEntry, EntryType | working_memory.py | A single working-memory entry. |
Soul | soul.py (or via MemorySystem) | The user’s core identity. |
Channel state
Execution checkpoint.
Source: src/engine_core/channel_state.py.
class ChannelStateSnapshot:
task_id: str
snapshot_json: dict # serialized loop state
expires_at: datetime
Asset Directory
MCP connection and registry types.
Source: src/asset_directory/states.py, src/asset_directory/__init__.py.
| Type | Purpose |
|---|
ServerConfigPayload | Public-facing server registry entry. |
Connection | An active connection to an MCP server with credentials. |
ConnectionStatus | connected, pending_oauth, expired, failed, disconnected. |
ActionDef | An MCP action’s metadata and input schema. |
Rules
- Never inline a contract type. If a type crosses a module boundary,
it lives where the producing module exports it (or in a shared
engine_contracts module).
- Never break a public contract silently. Renaming or reshaping
ToolUseBlock, ErrorCode, or any event field is a breaking change
and needs a migration guide.
- Document new contract types deliberately. If you’re inventing a
new kind of block or a new error code, write down why and where it’s
used so the next reader doesn’t have to reverse-engineer the
decision.
See also
