API Models

Data models and schemas used across the API. All models use Pydantic unless noted as @dataclass.

Provider Models

Defined in providers/base.py.

Message

Field	Type	Required	Description
`role`	MessageRole	yes	`"system"`, `"user"`, `"assistant"`, `"tool"`
`content`	string	yes	Message text
`name`	string	no	Tool name (for tool messages)
`tool_call_id`	string	no	ID linking to a tool call
`tool_calls`	list[dict]	no	Tool calls requested by assistant

ToolCall

Field	Type	Description
`id`	string	Unique tool call ID
`name`	string	Tool function name
`arguments`	dict	Parsed arguments

StreamChunk

Field	Type	Description
`content`	string	Token text (may be empty)
`finish_reason`	string	`null`, `"stop"`, `"tool_calls"`
`tool_calls`	list[ToolCall]	Tool calls collected during stream

CompletionResult

Field	Type	Description
`content`	string	Generated text
`finish_reason`	string	`"stop"`, `"length"`, `"tool_calls"`
`tool_calls`	list[ToolCall]	Tool calls (if function calling)
`usage`	dict	`{"prompt_tokens": int, "completion_tokens": int, "total_tokens": int}`
`model`	string	Model ID used
`raw_response`	dict	Full provider response (debug)

ModelCapabilities (`@dataclass`)

Field	Type	Default	Description
`supports_tools`	bool	`false`	Function calling support
`supports_vision`	bool	`false`	Image input support
`supports_streaming`	bool	`true`	Streaming support
`supports_json_mode`	bool	`false`	JSON mode support
`context_window`	int	`4096`	Max input tokens
`max_output_tokens`	int	`null`	Max output tokens
`cost_per_1k_input`	float	`null`	Input cost in USD
`cost_per_1k_output`	float	`null`	Output cost in USD

Agent Models

Defined in agent/core.py.

AgentResult

Field	Type	Description
`task_id`	string	Short UUID for the task
`status`	AgentStatus	`"idle"`, `"planning"`, `"reasoning"`, `"executing"`, `"complete"`, `"failed"`, `"cancelled"`
`answer`	string	Final response text
`thinking`	string	Extracted `<think>` tag content
`has_thinking`	bool	Whether thinking was extracted
`plan_steps`	int	Number of plan steps executed
`reasoning_steps`	int	Number of reasoning steps
`tools_used`	list[string]	Names of tools invoked
`models_used`	list[string]	Model IDs used
`total_tokens`	int	Total token count
`total_time_ms`	float	Elapsed time in milliseconds
`trace`	list[dict]	Debug trace (optional)

AgentConfig (`@dataclass`)

Field	Type	Default	Description
`name`	string	`"agentx"`	Agent name
`user_id`	string	`null`	User identifier
`default_model`	string	`"llama3.2"`	Default model
`reasoning_model`	string	`null`	Override for reasoning
`drafting_model`	string	`null`	Override for drafting
`max_iterations`	int	`20`	Max task iterations
`timeout_seconds`	float	`300.0`	Task timeout
`enable_planning`	bool	`true`	Enable task planning
`enable_reasoning`	bool	`true`	Enable reasoning strategies
`enable_drafting`	bool	`false`	Enable drafting
`enable_memory`	bool	`true`	Enable memory system
`enable_tools`	bool	`true`	Enable MCP tools
`default_reasoning_strategy`	string	`"auto"`	Strategy: `"auto"`, `"cot"`, `"tot"`, `"react"`, `"reflection"`
`allowed_tools`	list[string]	`null`	Whitelist tools (null = all)
`blocked_tools`	list[string]	`null`	Blacklist tools
`max_tool_rounds`	int	`10`	Max tool round-trips

Memory Models

Defined in kit/agent_memory/models.py.

Turn

Field	Type	Default	Description
`id`	string	auto UUID	Turn identifier
`conversation_id`	string	required	Parent conversation
`index`	int	required	Position in conversation
`timestamp`	datetime	now (UTC)	When the turn occurred
`role`	string	required	`"user"`, `"assistant"`, `"system"`, `"tool"`
`content`	string	required	Message content
`embedding`	list[float]	`null`	Vector embedding
`token_count`	int	`null`	Token count
`metadata`	dict	`{}`	Extra data (model, latency, etc.)
`channel`	string	`"_global"`	Memory channel

Entity

Field	Type	Default	Description
`id`	string	auto UUID	Entity identifier
`name`	string	required	Entity name
`type`	string	required	`"Person"`, `"Organization"`, `"Concept"`, etc.
`aliases`	list[string]	`[]`	Alternative names
`description`	string	`null`	Entity description
`embedding`	list[float]	`null`	Vector embedding
`salience`	float	`0.5`	Importance score (0–1)
`properties`	dict	`{}`	Arbitrary key-value properties
`first_seen`	datetime	now	When first encountered
`last_accessed`	datetime	now	Last retrieval time
`access_count`	int	`0`	Retrieval count
`channel`	string	`"_global"`	Memory channel

Fact

Field	Type	Default	Description
`id`	string	auto UUID	Fact identifier
`claim`	string	required	The factual claim
`claim_hash`	string	auto	SHA256 hash for duplicate detection
`confidence`	float	`0.8`	Confidence score (0–1)
`source`	string	required	`"extraction"`, `"user_stated"`, `"inferred"`
`source_turn_id`	string	`null`	Turn this fact was extracted from
`entity_ids`	list[string]	`[]`	Linked entities
`embedding`	list[float]	`null`	Vector embedding
`created_at`	datetime	now	Creation time
`channel`	string	`"_global"`	Memory channel
`last_accessed`	datetime	now	Last retrieval time
`access_count`	int	`0`	Retrieval count
`salience`	float	`0.5`	Importance score
`temporal_context`	string	`null`	`"current"`, `"past"`, `"future"`
`superseded_at`	datetime	`null`	When superseded by correction
`superseded_by_id`	string	`null`	ID of superseding fact
`supersedes_id`	string	`null`	ID of fact this supersedes
`flagged_for_review`	bool	`false`	Flagged for contradiction review

Goal

Field	Type	Default	Description
`id`	string	auto UUID	Goal identifier
`description`	string	required	Goal description
`status`	string	`"active"`	`"active"`, `"completed"`, `"abandoned"`, `"blocked"`
`priority`	int	`3`	Priority 1–5
`parent_goal_id`	string	`null`	Parent goal for hierarchy
`embedding`	list[float]	`null`	Vector embedding
`created_at`	datetime	now	Creation time
`deadline`	datetime	`null`	Optional deadline
`channel`	string	`"_global"`	Memory channel

Strategy

Field	Type	Default	Description
`id`	string	auto UUID	Strategy identifier
`description`	string	required	Strategy description
`context_pattern`	string	required	Matching pattern (regex/keywords)
`tool_sequence`	list[string]	`[]`	Ordered tool names
`embedding`	list[float]	`null`	Vector embedding
`success_count`	int	`0`	Successful uses
`failure_count`	int	`0`	Failed uses
`last_used`	datetime	`null`	Last invocation
`channel`	string	`"_global"`	Memory channel

MemoryBundle

Aggregated retrieval result returned by AgentMemory.remember().

Field	Type	Description
`relevant_turns`	list[dict]	Recent relevant conversation turns
`entities`	list[dict]	Matching entities
`facts`	list[dict]	Relevant facts
`strategies`	list[dict]	Applicable strategies
`active_goals`	list[dict]	Current active goals
`user_context`	dict	User-level context

Has a to_context_string() method that formats the bundle for LLM prompt injection.

Prompt Models

Defined in prompts/models.py.

PromptSection

Field	Type	Description
`id`	string	Unique section identifier
`name`	string	Display name
`type`	SectionType	`"persona"`, `"task"`, `"format"`, `"constraints"`, `"examples"`, `"context"`, `"custom"`
`content`	string	Prompt text
`enabled`	bool	Whether active in composition
`order`	int	Sort order within profile

PromptProfile

Field	Type	Description
`id`	string	Unique profile identifier
`name`	string	Display name
`description`	string	Usage description
`sections`	list[PromptSection]	Ordered sections
`is_default`	bool	Whether this is the default profile

GlobalPrompt

Field	Type	Description
`content`	string	Global prompt text
`enabled`	bool	Whether active

PromptConfig

Combines all prompt components for a request.

Field	Type	Description
`global_prompt`	GlobalPrompt	Core persona prompt
`profile`	PromptProfile	Selected profile
`mcp_tools_prompt`	string	Auto-generated tools prompt
`structured_output`	StructuredOutputConfig	Output constraints
`additional_context`	string	Request-specific context
`system_override`	string	Replaces entire system prompt

Composition order: Global prompt → MCP tools → Profile sections → Additional context.

MCP Models

ServerConfig (`@dataclass`, defined in `mcp/server_registry.py`)

Field	Type	Description
`name`	string	Server identifier
`transport`	TransportType	`"stdio"`, `"sse"`, `"streamable_http"`
`command`	string	Command for stdio transport
`args`	list[string]	Command arguments
`env`	dict	Environment variables (resolved from `$VAR` syntax)
`url`	string	URL for SSE/HTTP transport
`headers`	dict	HTTP headers (env vars resolved)

ToolInfo (`@dataclass`, defined in `mcp/tool_executor.py`)

Field	Type	Description
`name`	string	Tool name
`description`	string	Tool description
`input_schema`	dict	JSON Schema for parameters
`server_name`	string	Source server

ResourceInfo (`@dataclass`, defined in `mcp/client.py`)

Field	Type	Description
`uri`	string	Resource URI
`name`	string	Resource name
`description`	string	Resource description
`mime_type`	string	Content type
`server_name`	string	Source server

SSE Event Schemas

Events emitted by POST /api/agent/chat/stream:

Event	Schema
`start`	`{"task_id": string, "model": string}`
`chunk`	`{"content": string}`
`tool_call`	`{"tool": string, "arguments": dict}`
`tool_result`	`{"tool": string, "content": string}`
`done`	`{"task_id": string, "thinking": string?, "has_thinking": bool, "total_time_ms": float, "session_id": string}`
`error`	`{"error": string}`