# 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 | `"lmstudio:llama3.2"` | Default model (`provider:model` format) |
| `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}` |