Skip to content

Data models

The structured types produced and consumed by caw. See Concepts for how they fit together.

Trajectory

Trajectory dataclass 

Trajectory(agent: str, model: str = '', session_id: str = '', created_at: str = '', completed_at: str = '', usage_limited: bool = False, system_prompt: str = '', reasoning: str = '', mcp_servers: list[MCPServer] = list(), turns: list[Turn] = list(), usage: UsageStats = UsageStats(), duration_ms: int = 0, metadata: dict[str, Any] = dict())

Complete record of a session.

usage tracks this agent's own token usage. Use total_usage to get the accumulated usage including all nested subagent trajectories.

result property 

result: str

The final result from the last turn.

total_usage property 

total_usage: UsageStats

Accumulated usage: own + all nested subagent trajectories (recursive).

subagent_trajectories property 

subagent_trajectories: list[Trajectory]

All subagent trajectories across all turns.

is_usage_limited property 

is_usage_limited: bool

Whether the session ended due to a usage limit.

Set by Session.end() using the provider's detect_usage_limit.

is_complete property 

is_complete: bool

Whether the session completed normally.

A trajectory is complete when it has been finalized (completed_at is set by Session.end()) and was not usage-limited. Mid-session snapshots written by append_turn have an empty completed_at and are therefore not considered complete.

Turn

Turn dataclass 

Turn(input: str, output: list[ContentBlock] = list(), usage: UsageStats = UsageStats(), duration_ms: int = 0)

A single turn: user sends a message, agent responds.

result property 

result: str

Last text block's content.

tool_calls property 

tool_calls: list[ToolUse]

All tool calls made during this turn.

Content blocks

TextBlock dataclass 

TextBlock(text: str)

A block of text output from the agent.

ThinkingBlock dataclass 

ThinkingBlock(text: str)

A block of thinking/reasoning output from the agent.

ToolUse dataclass 

ToolUse(id: str, name: str, arguments: dict[str, Any] = dict(), output: str = '', is_error: bool = False, subagent_trajectory: Trajectory | None = None)

A tool invocation paired with its result.

ContentBlock module-attribute 

ContentBlock = Union[TextBlock, ThinkingBlock, ToolUse]

UsageStats

UsageStats dataclass 

UsageStats(input_tokens: int = 0, output_tokens: int = 0, cache_read_tokens: int = 0, cache_write_tokens: int = 0, cost_usd: float = 0.0)

Token usage and cost statistics.

total_tokens property 

total_tokens: int

Total tokens consumed (input + output).

Model & tool selection

ModelTier

Bases: Enum

Abstract model selection tiers.

Each provider maps these to concrete model identifiers:

agent = Agent(model=ModelTier.STRONGEST)  # provider picks its best model
agent = Agent(model=ModelTier.FAST)        # provider picks its fast model
agent = Agent(model="claude-opus-4-6")     # explicit model string still works

ToolGroup

Bases: Flag

Abstract tool permission groups.

Combine with | (union) and - (subtract) to build permission sets:

ToolGroup.READER | ToolGroup.EXEC          # read + execute only
ToolGroup.ALL - ToolGroup.WRITER            # everything except writes
ToolGroup.ALL - ToolGroup.INTERACTION       # default for automated pipelines

Configuration types

AgentSpec dataclass 

AgentSpec(name: str = '', description: str = '', system_prompt: str = '', model: str = '', reasoning: str = '', tools: ToolGroup | None = None, tool_servers: list[Any] = list(), mcp_servers: list[MCPServer] = list(), subagents: list['AgentSpec'] = list(), metadata: dict[str, Any] = dict())

Configuration for a subagent.

MCPServer dataclass 

MCPServer(name: str, command: str = '', args: list[str] = list(), env: dict[str, str] = dict(), url: str = '')

Configuration for an MCP server.

For stdio transport, set command/args/env. For HTTP transport, set url (command/args/env are ignored).

MCPTool dataclass 

MCPTool(name: str, description: str = '', server: str = '', input_schema: dict[str, Any] = dict())

Descriptor for a tool provided by an MCP server.

InteractiveResult dataclass 

InteractiveResult(exit_code: int, output: str = '')

Result from an interactive agent session.

session_id property 

session_id: str | None

Extract the session ID from Claude Code's exit output, if present.