# `ai.config` — Module Overview

> This document is partially auto-generated. Sections tagged `<!-- AUTO:id -->` are refreshed by the generator.
> Everything else is yours to edit freely and will never be overwritten.

<!-- AUTO:meta -->
## About This Document

This file is **partially auto-generated**. Sections wrapped in `<!-- AUTO:id -->` tags
are overwritten each time the generator runs. Everything else is yours to edit freely.

| Field | Value |
|-------|-------|
| Module | `matrx_ai/config` |
| Last generated | 2026-04-07 11:38 |
| Output file | `matrx_ai/config/MODULE_README.md` |
| Signature mode | `signatures` |

**To refresh auto-sections:**
```bash
python utils/code_context/generate_module_readme.py matrx_ai/config --mode signatures
```

**To add permanent notes:** Write anywhere outside the `<!-- AUTO:... -->` blocks.
<!-- /AUTO:meta -->

<!-- HUMAN-EDITABLE: This section is yours. Agents & Humans can edit this section freely — it will not be overwritten. -->

## Architecture

> **Fill this in.** Describe the execution flow and layer map for this module.
> See `utils/code_context/MODULE_README_SPEC.md` for the recommended format.
>
> Suggested structure:
>
> ### Layers
> | File | Role |
> |------|------|
> | `entry.py` | Public entry point — receives requests, returns results |
> | `engine.py` | Core dispatch logic |
> | `models.py` | Shared data types |
>
> ### Call Flow (happy path)
> ```
> entry_function() → engine.dispatch() → implementation()
> ```


<!-- AUTO:tree -->
## Directory Tree

> Auto-generated. 20 files across 1 directories.

```
matrx_ai/config/
├── MODULE_README.md
├── __init__.py
├── agent-definition-types.ts
├── ai-api-types.ts
├── config_utils.py
├── enums.py
├── extra_config.py
├── finish_reason.py
├── llm_params.py
├── media_config.py
├── message-types.ts
├── message_config.py
├── structured_input_config.py
├── structured_input_resolver.py
├── thinking_config.py
├── tools_config.py
├── tts_config.py
├── unified_config.py
├── unified_content.py
├── usage_config.py
# excluded: 4 .md
```
<!-- /AUTO:tree -->

<!-- AUTO:signatures -->
## API Signatures

> Auto-generated via `output_mode="signatures"`. ~5-10% token cost vs full source.
> For full source, open the individual files directly.

```
---
Filepath: matrx_ai/config/enums.py  [python]

  class Role(StrEnum):
  class ContentType(StrEnum):
  class Provider(StrEnum):


---
Filepath: matrx_ai/config/message_config.py  [python]

  class UnifiedMessage:
      def parse_content(content_data: str | list[Any]) -> list[UnifiedContent]
      def from_dict(cls, data: dict[str, Any]) -> 'UnifiedMessage'
      def from_cx_message(cls, message) -> 'UnifiedMessage'
      def from_openai_item(cls, item: OpenAIResponseOutputItem) -> Optional['UnifiedMessage']
      def from_openai_modified(cls, items: list[dict[str, Any]]) -> Optional['UnifiedMessage']
      def from_anthropic_content(cls, role: str, content: list[dict[str, Any]], id: str) -> Optional['UnifiedMessage']
      def to_google_content(self) -> dict[str, Any] | None
      def to_openai_items(self) -> list[dict[str, Any]] | dict[str, Any] | None
      def to_openai_items_modified(self) -> list[dict[str, Any]]
      def to_anthropic_blocks(self) -> list[dict[str, Any]]
      def replace_variables(self, variables: dict[str, Any]) -> None
      def to_storage_dict(self) -> dict[str, Any]
      def get_output(self) -> str
      def attach_ephemeral(self, block: str) -> None
      def detach_ephemeral(self) -> None
      def strip_keep_fresh_blocks(self) -> list[UnifiedContent]
  class MessageList:
      def __post_init__(self)
      def __iter__(self)
      def __len__(self)
      def __getitem__(self, index)
      def __setitem__(self, index, value)
      def append(self, message: Union['UnifiedMessage', dict[str, Any]]) -> None
      def extend(self, messages: Union[list['UnifiedMessage'], 'MessageList']) -> None
      def insert(self, index: int, message: Union['UnifiedMessage', dict[str, Any]]) -> None
      def pop(self, index: int = -1) -> 'UnifiedMessage'
      def remove(self, message: 'UnifiedMessage') -> None
      def clear(self) -> None
      def filter_by_role(self, *roles: str) -> 'MessageList'
      def exclude_roles(self, *roles: str) -> 'MessageList'
      def has_role(self, role: str) -> bool
      def get_last_by_role(self, role: str) -> Optional['UnifiedMessage']
      def get_last_output(self) -> str
      def count_by_role(self, role: str) -> int
      def attach_ephemeral_to_last_user(self, block: str) -> None
      def detach_ephemeral_from_last_user(self) -> None
      def strip_keep_fresh_from_last_user(self) -> list
      def append_user_text(self, text: str, **kwargs) -> None
      def append_or_extend_user_text(self, text: str, **kwargs) -> None
      def append_or_extend_user_items(self, items: list[dict[str, Any]]) -> None
      def append_or_extend_user_input(self, user_input: str | list[dict[str, Any]]) -> None
      def _is_last_message_user(self) -> bool
      def append_assistant_text(self, text: str, **kwargs) -> None
      def to_list(self) -> list['UnifiedMessage']
      def to_dict_list(self) -> list[dict[str, Any]]
      def replace_variables(self, variables: dict[str, Any]) -> None


---
Filepath: matrx_ai/config/thinking_config.py  [python]

  class ThinkingConfig:
      def to_openai_reasoning(self) -> Reasoning
      def to_google_thinking_legacy(self) -> dict[str, Any]
      def to_google_thinking_3(self, model_name: str | None = None) -> dict[str, Any]
      def to_anthropic_thinking(self, current_max_tokens: int | None = None) -> dict[str, Any] | None
      def to_anthropic_adaptive_thinking(self, current_max_tokens: int | None = None) -> dict[str, Any] | None
      def to_cerebras_reasoning(self) -> str | None
      def to_cerebras_thinking_params(self) -> dict[str, Any]
      def from_settings(cls, settings: Any) -> 'ThinkingConfig'


---
Filepath: matrx_ai/config/__init__.py  [python]



---
Filepath: matrx_ai/config/usage_config.py  [python]

  class PricingTier:
  class ModelPricing:
      def get_tier(self, total_input_tokens: int) -> PricingTier | None
  class ModelUsageSummary:
  class UsageTotals:
  class AggregatedUsage:
      def to_dict(self) -> dict[str, Any]
  class TokenUsage:
      def total_tokens(self) -> int
      def calculate_cost(self, pricing_lookup: dict[str, ModelPricing] | None = None) -> float | None
      def __add__(self, other: TokenUsage) -> TokenUsage
      def from_gemini(cls, usage_metadata: dict[str, Any], matrx_model_name: str = '', provider_model_name: str = '', response_id: str = '') -> TokenUsage
      def from_openai(cls, usage: OpenAIResponseUsage, matrx_model_name: str, provider_model_name: str, response_id: str = '') -> TokenUsage
      def from_anthropic(cls, usage: AnthropicUsage, matrx_model_name: str, response_id: str = '') -> TokenUsage
      def aggregate_by_model(usage_list: list[TokenUsage]) -> AggregatedUsage
  async def warm_pricing_lookup() -> dict[str, ModelPricing]
  def _get_db_pricing_lookup() -> dict[str, ModelPricing]


---
Filepath: matrx_ai/config/message-types.ts  [typescript]

  export interface TextBlock
  export interface ImageBlock
  export interface AudioBlock
  export interface VideoBlock
  export interface YouTubeVideoBlock
  export interface DocumentBlock
  interface StructuredInputBase
  export interface WebpageInputBlock extends StructuredInputBase
  export interface NotesInputBlock extends StructuredInputBase
  export interface TaskInputBlock extends StructuredInputBase
  export interface FullTableBookmark
  export interface TableColumnBookmark
  export interface TableRowBookmark
  export interface TableCellBookmark
  export type TableBookmark = | FullTableBookmark | TableColumnBookmark | TableRowBookmark | TableCellBookmark
  export interface TableInputBlock extends StructuredInputBase
  export interface FullListBookmark
  export interface ListGroupBookmark
  export interface ListItemBookmark
  export type ListBookmark = | FullListBookmark | ListGroupBookmark | ListItemBookmark
  export interface ListInputBlock extends StructuredInputBase
  export type DataRefTable = | "notes" | "tasks" | "projects" | "workspaces" | "organizations" | "contacts" | "contact_groups"
  export interface DbRecordRef
  export interface DbQueryRef
  export interface DbFieldRef
  export type DataRef = DbRecordRef | DbQueryRef | DbFieldRef
  export interface DataInputBlock extends StructuredInputBase
  export type ContentBlock = // Media | TextBlock | ImageBlock | AudioBlock | VideoBlock | YouTubeVideoBlock | DocumentBlock // Structured inputs | WebpageInputBlock | NotesInputBlock | TaskInputBlock | TableInputBlock | ListInputBlock | DataInputBlock
  export type UserInput = string | ContentBlock[]


---
Filepath: matrx_ai/config/structured_input_resolver.py  [python]

  async def _resolve_one(block: _StructuredInputBase) -> None
  def _emit_block_warnings(block: _StructuredInputBase) -> None
  def inject_editable_tools(messages: 'MessageList', config: 'UnifiedConfig') -> None
  async def resolve_structured_inputs(messages: 'MessageList') -> None
  async def _send() -> None


---
Filepath: matrx_ai/config/tools_config.py  [python]

  class ToolCallContent:
      def get_output(self) -> str
      def to_google(self) -> dict[str, Any]
      def to_openai(self) -> dict[str, Any]
      def to_anthropic(self) -> dict[str, Any]
      def _sanitize_metadata(self, metadata: dict[str, Any]) -> dict[str, Any]
      def to_dict(self) -> dict[str, Any]
      def to_storage_dict(self) -> dict[str, Any]
      def __repr__(self) -> str
      def from_google(cls, part: Part) -> Optional['ToolCallContent']
      def from_openai(cls, item: OpenAIResponseFunctionToolCall) -> Optional['ToolCallContent']
      def from_anthropic(cls, content_block: dict[str, Any]) -> Optional['ToolCallContent']
  class ToolResultContent:
      def get_output(self) -> str
      def to_google(self) -> dict[str, Any]
      def to_openai(self) -> dict[str, Any]
      def to_anthropic(self) -> dict[str, Any]
      def to_storage_dict(self) -> dict[str, Any]
      def from_google(cls, part: Part) -> Optional['ToolResultContent']


---
Filepath: matrx_ai/config/structured_input_config.py  [python]

  StructuredInputContent = WebpageInputContent | NotesInputContent | TaskInputContent | TableInputContent | ListInputContent | DataInputContent | C ...
  class _StructuredInputBase:
      def editable_tools(self) -> frozenset[str]
      def get_output(self) -> str
      def _provider_text(self) -> str | None
      async def resolve(self) -> None
      def to_openai(self) -> dict[str, Any] | None
      def to_anthropic(self) -> dict[str, Any] | None
      def to_google(self) -> dict[str, Any] | None
  class WebpageInputContent(_StructuredInputBase):
      async def resolve(self) -> None
      def to_storage_dict(self) -> dict[str, Any]
  class NotesInputContent(_StructuredInputBase):
      async def resolve(self) -> None
      def to_storage_dict(self) -> dict[str, Any]
  class TaskInputContent(_StructuredInputBase):
      async def resolve(self) -> None
      def to_storage_dict(self) -> dict[str, Any]
  class TableInputContent(_StructuredInputBase):
      async def resolve(self) -> None
      def to_storage_dict(self) -> dict[str, Any]
  class ListInputContent(_StructuredInputBase):
      async def resolve(self) -> None
      def to_storage_dict(self) -> dict[str, Any]
  class DataInputContent(_StructuredInputBase):
      async def resolve(self) -> None
      def to_storage_dict(self) -> dict[str, Any]
  class ContextInputContent(_StructuredInputBase):
      def to_storage_dict(self) -> dict[str, Any]
  def _webpage_to_xml(url: str, title: str | None, content: str) -> str
  def _webpage_failure_xml(url: str, reason: str) -> str
  def reconstruct_structured_input(block: dict[str, Any]) -> StructuredInputContent | None


---
Filepath: matrx_ai/config/tts_config.py  [python]

  class TTSSpeaker:
      def from_dict(cls, data: dict[str, str]) -> TTSSpeaker
      def to_dict(self) -> dict[str, str]
  class TTSVoiceConfig:
      def from_config(cls, settings: Any) -> TTSVoiceConfig | None
      def from_dict(cls, data: dict[str, Any]) -> TTSVoiceConfig
      def is_multi_speaker(self) -> bool
      def is_dialogue(self) -> bool
      def is_configured(self) -> bool
      def _primary_voice(self) -> str | None
      def strip_speaker_labels(self, text: str) -> str
      def validate_speaker_names(self, google_contents: list[dict[str, Any]]) -> None
      def to_google(self, google_contents: list[dict[str, Any]]) -> Any
      def to_openai(self) -> dict[str, str]
      def to_openai_model_and_voice(self, model: str | None = None) -> tuple[str, str]
      def to_groq(self) -> dict[str, str]
      def to_groq_model_and_voice(self, model: str | None = None) -> tuple[str, str]
      def to_xai(self) -> dict[str, str]
      def to_elevenlabs(self, text: str | None = None, model: str | None = None) -> tuple[list[list[dict[str, str]]], str]
      def to_storage_dict(self) -> dict[str, Any]
  class OpenAITTSRegistry:
      def resolve_model(cls, model: Optional[str] = None) -> str
      def resolve_voice(cls, voice: Optional[str] = None, model: Optional[str] = None) -> str
      def resolve(cls, model: Optional[str] = None, voice: Optional[str] = None) -> tuple[str, str]
      def is_valid_voice(cls, voice: str, model: Optional[str] = None) -> bool
      def voices_for_model(cls, model: Optional[str] = None) -> list[str]
  class GroqTTSRegistry:
      def resolve_model(cls, model: Optional[str] = None) -> str
      def resolve_voice(cls, voice: Optional[str] = None, model: Optional[str] = None) -> str
      def resolve(cls, model: Optional[str] = None, voice: Optional[str] = None) -> tuple[str, str]
      def resolve_format(cls, response_format: Optional[str] = None) -> str
      def is_valid_voice(cls, voice: str, model: Optional[str] = None) -> bool
      def voices_for_model(cls, model: Optional[str] = None) -> list[str]
      def supports_vocal_directions(cls, model: Optional[str] = None) -> bool
      def validate_input_length(cls, text: str) -> str
  class GoogleTTSRegistry:
      def resolve_model(cls, model: Optional[str] = None) -> str
      def resolve_voice(cls, voice: Optional[str] = None, model: Optional[str] = None) -> str
      def resolve(cls, model: Optional[str] = None, voice: Optional[str] = None) -> tuple[str, str]
      def is_valid_voice(cls, voice: str, model: Optional[str] = None) -> bool
      def voices_for_model(cls, model: Optional[str] = None) -> list[str]
      def display_name(cls, voice: str) -> str
      def voice_description(cls, voice: str) -> Optional[str]
      def voices_by_quality(cls, quality: str) -> list[str]
      def validate_speakers(cls, speakers: list[dict]) -> list[dict]
  class XAITTSRegistry:
      def resolve_voice(cls, voice: Optional[str] = None) -> str
      def resolve(cls, model: Optional[str] = None, voice: Optional[str] = None) -> tuple[str, str]
      def resolve_language(cls, language: Optional[str] = None) -> str
      def resolve_codec(cls, codec: Optional[str] = None) -> str
      def resolve_sample_rate(cls, sample_rate: Optional[int] = None) -> int
      def resolve_bit_rate(cls, bit_rate: Optional[int] = None, codec: Optional[str] = None) -> Optional[int]
      def resolve_output_format(cls, codec: Optional[str] = None, sample_rate: Optional[int] = None, bit_rate: Optional[int] = None) -> dict
      def is_valid_voice(cls, voice: str) -> bool
      def voices(cls) -> list[str]
      def voice_description(cls, voice: str) -> Optional[dict[str, str]]
      def languages(cls) -> dict[str, str]
      def validate_text_length(cls, text: str, truncate: bool = False) -> str
  class DialogueTurn:
      def from_dict(cls, data: dict[str, str]) -> DialogueTurn
      def to_dict(self) -> dict[str, str]
      def to_elevenlabs_input(self) -> dict[str, str]
  class ElevenLabsDialogueRegistry:
      def resolve_model(cls, model: Optional[str] = None) -> str
      def batch_turns(cls, turns: list[DialogueTurn]) -> list[list[DialogueTurn]]
      def is_valid_model(cls, model: str) -> bool


---
Filepath: matrx_ai/config/agent-definition-types.ts  [typescript]

  export type Role = | "user" | "assistant" | "tool" | "system" | "developer" | "output"
  export type StoredRole = "user" | "assistant" | "tool"
  export interface ThinkingBlock
  export interface ToolCallBlock
  export interface ToolResultBlock
  export interface CodeExecutionBlock
  export interface CodeExecutionResultBlock
  export interface WebSearchCallBlock
  export type ConversationBlock = // ── User-sendable blocks (ContentBlock) ── | TextBlock | ImageBlock | AudioBlock | VideoBlock | YouTubeVideoBlock | DocumentBlock | WebpageInputBlock | NotesInputBlock | TaskInputBlock | TableInputBlock | ListInputBlock | DataInputBlock // ── Assistant-only blocks ── | ThinkingBlock | ToolCallBlock | CodeExecutionBlock | CodeExecutionResultBlock | WebSearchCallBlock // ── Tool-role blocks ── | ToolResultBlock
  export interface ConversationMessage
  export interface UserMessage extends ConversationMessage
  export interface AssistantMessage extends ConversationMessage
  export interface ToolMessage extends ConversationMessage
  export type RoleMessage = UserMessage | AssistantMessage | ToolMessage
  export interface AgentDefinitionMessage
  export type AgentDefinitionMessages = AgentDefinitionMessage[]


---
Filepath: matrx_ai/config/extra_config.py  [python]

  class CodeExecutionContent:
      def to_google(self) -> dict[str, Any]
      def to_openai(self) -> dict[str, Any] | None
      def to_anthropic(self) -> dict[str, Any] | None
      def to_storage_dict(self) -> dict[str, Any]
      def from_google(cls, part: Part) -> Optional['CodeExecutionContent']
  class CodeExecutionResultContent:
      def to_google(self) -> dict[str, Any]
      def to_openai(self) -> dict[str, Any] | None
      def to_anthropic(self) -> dict[str, Any] | None
      def to_storage_dict(self) -> dict[str, Any]
      def from_google(cls, part: Part) -> Optional['CodeExecutionResultContent']
  class WebSearchCallContent:
      def get_output(self) -> str | None
      def from_openai(cls, content_item: OpenAIResponseFunctionWebSearch) -> Optional['WebSearchCallContent']
      def to_openai(self) -> dict[str, Any]
      def to_anthropic(self) -> dict[str, Any]
      def to_google(self) -> dict[str, Any]
      def to_storage_dict(self) -> dict[str, Any]


---
Filepath: matrx_ai/config/finish_reason.py  [python]

  class FinishReason(StrEnum):
      def is_success(self) -> bool
      def is_truncated(self) -> bool
      def is_retryable(self) -> bool
      def is_error(self) -> bool
      def from_google(cls, google_reason: Any) -> 'FinishReason'
      def from_anthropic(cls, stop_reason: str) -> 'FinishReason'
      def to_anthropic(cls, finish_reason: 'FinishReason') -> str


---
Filepath: matrx_ai/config/llm_params.py  [python]

  class LLMParams(BaseModel):
      # fields: model: str | None = None, max_output_tokens: int | None = None, temperature: float | None = None, top_p: float | None = None, top_k: int | None = None, tool_choice: Literal['none', 'auto', 'required'] | None = None, parallel_tool_calls: bool | None = None, reasoning_effort: Literal['auto', 'none', 'minimal', 'low', 'medium', 'high', 'xhigh'] | None = None, reasoning_summary: Literal['concise', 'detailed', 'never', 'auto', 'always'] | None = None, thinking_level: Literal['minimal', 'low', 'medium', 'high'] | None = None, include_thoughts: bool | None = None, thinking_budget: int | None = None, clear_thinking: bool | None = None, disable_reasoning: bool | None = None, response_format: dict[str, Any] | None = None, stop_sequences: list[str] | None = None, stream: bool | None = None, store: bool | None = None, verbosity: str | None = None, internal_web_search: bool | None = None, internal_url_context: bool | None = None, size: str | None = None, quality: str | None = None, count: int | None = None, tts_voice: str | list[dict[str, str]] | None = None, audio_format: str | None = None, seconds: str | None = None, fps: int | None = None, steps: int | None = None, seed: int | None = None, guidance_scale: int | None = None, output_quality: int | None = None, negative_prompt: str | None = None, output_format: str | None = None, width: int | None = None, height: int | None = None, frame_images: list | None = None, reference_images: list | None = None, image_loras: list | None = None, disable_safety_checker: bool | None = None
      def _remap_deprecated(cls, data: Any) -> Any


---
Filepath: matrx_ai/config/media_config.py  [python]

  MediaKind = Literal['image', 'audio', 'video', 'document', 'youtube']
  MediaContent = ImageContent | AudioContent | VideoContent | YouTubeVideoContent | DocumentContent
  class ImageContent:
      def __post_init__(self)
      def get_output(self) -> str | None
      def to_google(self) -> dict[str, Any] | None
      def to_openai(self) -> dict[str, Any] | None
      def to_anthropic(self) -> dict[str, Any] | None
      def from_google(cls, part: Part) -> Optional['ImageContent']
      def to_dict(self, truncate_base64: bool = True) -> dict[str, Any]
      def to_storage_dict(self) -> dict[str, Any]
      def __repr__(self) -> str
  class AudioContent:
      def __post_init__(self)
      def get_output(self) -> str | None
      def get_transcription(self, force_refresh: bool = False) -> str | None
      def to_dict(self, truncate_base64: bool = True) -> dict[str, Any]
      def to_storage_dict(self) -> dict[str, Any]
      def __repr__(self) -> str
      def to_google(self) -> dict[str, Any] | None
      def to_openai(self) -> dict[str, Any] | None
      def to_anthropic(self) -> dict[str, Any] | None
      def from_google(cls, part: Part, audio_format: str | None = None) -> Optional['AudioContent']
  class VideoContent:
      def __post_init__(self)
      def get_output(self) -> str | None
      def to_dict(self, truncate_base64: bool = True) -> dict[str, Any]
      def to_storage_dict(self) -> dict[str, Any]
      def __repr__(self) -> str
      def to_google(self) -> dict[str, Any] | None
      def to_openai(self) -> dict[str, Any] | None
      def to_anthropic(self) -> dict[str, Any] | None
      def from_google(cls, part: Part) -> Optional['VideoContent']
  class YouTubeVideoContent:
      def get_output(self) -> str
      def to_storage_dict(self) -> dict[str, Any]
      def to_google(self) -> dict[str, Any] | None
      def to_openai(self) -> dict[str, Any] | None
      def to_anthropic(self) -> dict[str, Any] | None
      def from_google(cls, part: Part) -> Optional['YouTubeVideoContent']
  class DocumentContent:
      def __post_init__(self)
      def get_output(self) -> str | None
      def to_dict(self, truncate_base64: bool = True) -> dict[str, Any]
      def to_storage_dict(self) -> dict[str, Any]
      def __repr__(self) -> str
      def to_google(self) -> dict[str, Any] | None
      def to_openai(self) -> dict[str, Any] | None
      def to_anthropic(self) -> dict[str, Any] | None
      def from_google(cls, part: Part) -> Optional['DocumentContent']
  def reconstruct_media_content(block: dict[str, Any]) -> MediaContent | None


---
Filepath: matrx_ai/config/config_utils.py  [python]

  def truncate_base64_in_dict(d: Any, min_length: int = 100) -> Any


---
Filepath: matrx_ai/config/unified_config.py  [python]

  class UnifiedConfig:
      def __post_init__(self)
      def tts_voice_config(self) -> TTSVoiceConfig | None
      def _resolve_message_patterns(self) -> None
      def _normalize_system_instruction(raw: str | dict | SystemInstruction | None) -> SystemInstruction | None
      def resolved_system_instruction(self) -> str | None
      def from_dict(cls, data: dict[str, Any]) -> 'UnifiedConfig'
      def _normalize_tool_choice(self, tool_choice: Any) -> Literal['none', 'auto', 'required'] | None
      def to_dict(self) -> dict[str, Any]
      def to_storage_dict(self) -> dict[str, Any]
      def append_user_message(self, text: str, **kwargs) -> None
      def append_or_extend_user_text(self, text: str, **kwargs) -> None
      def append_or_extend_user_input(self, user_input: str | list[dict[str, Any]]) -> None
      def replace_variables(self, variables: dict[str, Any]) -> None
      def apply_overrides(self, overrides: LLMParams) -> None
      def get_last_output(self) -> str
  class UnifiedResponse:
      def __post_init__(self)
      def to_dict(self) -> dict[str, Any]
  def _parse_custom_tools(raw: list) -> list


---
Filepath: matrx_ai/config/ai-api-types.ts  [typescript]

  export interface TextBlock
  export interface ImageBlock
  export interface AudioBlock
  export interface VideoBlock
  export interface YouTubeVideoBlock
  export interface DocumentBlock
  interface StructuredInputBase
  export interface WebpageInputBlock extends StructuredInputBase
  export interface NotesInputBlock extends StructuredInputBase
  export interface TaskInputBlock extends StructuredInputBase
  export interface FullTableBookmark
  export interface TableColumnBookmark
  export interface TableRowBookmark
  export interface TableCellBookmark
  export type TableBookmark = | FullTableBookmark | TableColumnBookmark | TableRowBookmark | TableCellBookmark
  export interface TableInputBlock extends StructuredInputBase
  export interface FullListBookmark
  export interface ListGroupBookmark
  export interface ListItemBookmark
  export type ListBookmark = | FullListBookmark | ListGroupBookmark | ListItemBookmark
  export interface ListInputBlock extends StructuredInputBase
  export interface DbRecordRef
  export interface DbQueryRef
  export interface DbFieldRef
  export type DataRef = DbRecordRef | DbQueryRef | DbFieldRef
  export type DataRefTable = | "notes" | "tasks" | "projects" | "workspaces" | "organizations" | "contacts" | "contact_groups"
  export interface DataInputBlock extends StructuredInputBase
  export type ContentBlock = | TextBlock | ImageBlock | AudioBlock | VideoBlock | YouTubeVideoBlock | DocumentBlock | WebpageInputBlock | NotesInputBlock | TaskInputBlock | TableInputBlock | ListInputBlock | DataInputBlock
  export interface LLMParams
  export interface IdeFileState
  export interface IdeDiagnostic
  export interface IdeGitState
  export interface IdeWorkspaceState
  export interface IdeState
  export type ContextObjectType = | "text" | "file_url" | "json" | "db_ref" | "user" | "org" | "workspace" | "project" | "task"
  export type ContextValue = | string | number | boolean | Record<string, unknown> | unknown[]
  export interface ActiveScope
  export interface AgentStartRequest
  export interface CustomToolInputSchema
  export interface CustomTool
  export interface ConversationContinueRequest
  export interface ClientToolResult
  export interface ToolResultsRequest
  export interface ToolResultsResponse
  export interface ContextPolicy
  export interface CtxGetFullResult
  export interface CtxGetPageResult
  export interface CtxGetSummaryResult
  export type CtxGetResult = | CtxGetFullResult | CtxGetPageResult | CtxGetSummaryResult
  export interface MessageEvent
  export interface ChunkEvent
  export interface ToolDelegatedEvent
  export interface StructuredInputWarningEvent
  export interface DataEvent
  export interface EndEvent
  export interface ErrorEvent
  export type StreamEvent = | MessageEvent | ChunkEvent | ToolDelegatedEvent | StructuredInputWarningEvent | DataEvent | EndEvent | ErrorEvent


---
Filepath: matrx_ai/config/unified_content.py  [python]

  UnifiedContent = TextContent | ImageContent | AudioContent | VideoContent | YouTubeVideoContent | DocumentContent | ToolCallContent | Too ...
  class TextContent:
      def get_output(self) -> str
      def replace_variables(self, variables: dict[str, Any]) -> None
      def append_text(self, text: str, separator: str = '\n') -> None
      def attach_ephemeral(self, block: str) -> None
      def detach_ephemeral(self) -> None
      def to_google(self) -> dict[str, Any]
      def to_openai(self, role: str | None = None) -> dict[str, Any]
      def to_anthropic(self) -> dict[str, Any]
      def _sanitize_metadata(self, metadata: dict[str, Any]) -> dict[str, Any]
      def to_dict(self) -> dict[str, Any]
      def to_storage_dict(self) -> dict[str, Any]
      def __repr__(self) -> str
      def from_openai(cls, content_item: OpenAIResponseOutputText, id: str) -> Optional['TextContent']
      def from_openai_modified(cls, content_item: dict[str, Any]) -> Optional['TextContent']
      def from_google(cls, part: Part) -> Optional['TextContent']
      def from_anthropic(cls, content_block: dict[str, Any]) -> Optional['TextContent']
  class ThinkingContent:
      def get_output(self) -> str
      def _sanitize_signature(self) -> str
      def to_dict(self) -> dict[str, Any]
      def to_storage_dict(self) -> dict[str, Any]
      def __repr__(self) -> str
      def to_google(self) -> dict[str, Any] | None
      def to_openai(self) -> dict[str, Any] | None
      def to_anthropic(self) -> dict[str, Any] | None
      def from_google(cls, part: Part) -> Optional['ThinkingContent']
      def from_anthropic(cls, content_block: dict[str, Any]) -> Optional['ThinkingContent']
      def from_openai(cls, item: OpenAIResponseReasoningItem) -> Optional['ThinkingContent']
  def reconstruct_content(block: dict[str, Any]) -> UnifiedContent
```
<!-- /AUTO:signatures -->

<!-- AUTO:callers -->
## Upstream Callers

> Auto-discovered by scanning all project files that import from this module.
> Set `ENTRY_POINTS` in `generate_readme.py` to pin specific functions.

| Caller | Calls |
|--------|-------|
| `matrx_ai/agents/definition.py` | `AggregatedUsage()` |
| `matrx_ai/orchestrator/requests.py` | `AggregatedUsage()` |
| `matrx_ai/processing/audio/audio_preprocessing.py` | `AudioContent()` |
| `matrx_ai/providers/eleven_labs/elevenlabs_api.py` | `AudioContent()` |
| `matrx_ai/providers/google/google_api.py` | `AudioContent()` |
| `matrx_ai/providers/google/translator.py` | `AudioContent()` |
| `matrx_ai/providers/groq/groq_api.py` | `AudioContent()` |
| `matrx_ai/providers/openai/openai_api.py` | `AudioContent()` |
| `matrx_ai/providers/xai/xai_api.py` | `AudioContent()` |
| `matrx_ai/tests/groq_transcription_test.py` | `AudioContent()` |
| `matrx_ai/providers/google/translator.py` | `CodeExecutionContent()` |
| `matrx_ai/providers/google/translator.py` | `CodeExecutionResultContent()` |
| `matrx_ai/providers/google/translator.py` | `DocumentContent()` |
| `matrx_ai/providers/eleven_labs/elevenlabs_api.py` | `ElevenLabsDialogueRegistry()` |
| `matrx_ai/orchestrator/executor.py` | `FinishReason()` |
| `matrx_ai/orchestrator/recovery_logic.py` | `FinishReason()` |
| `matrx_ai/providers/anthropic/translator.py` | `FinishReason()` |
| `matrx_ai/providers/cerebras/translator.py` | `FinishReason()` |
| `matrx_ai/providers/generic_openai/generic_openai_api.py` | `FinishReason()` |
| `matrx_ai/providers/generic_openai/translator.py` | `FinishReason()` |
| `matrx_ai/providers/google/translator.py` | `FinishReason()` |
| `matrx_ai/providers/groq/groq_api.py` | `FinishReason()` |
| `matrx_ai/providers/groq/translator.py` | `FinishReason()` |
| `matrx_ai/providers/openai/translator.py` | `FinishReason()` |
| `matrx_ai/providers/together/together_api.py` | `FinishReason()` |
| `matrx_ai/providers/together/translator.py` | `FinishReason()` |
| `matrx_ai/providers/xai/translator.py` | `FinishReason()` |
| `matrx_ai/providers/xai/xai_api.py` | `FinishReason()` |
| `matrx_ai/providers/groq/groq_api.py` | `GroqTTSRegistry()` |
| `matrx_ai/providers/google/google_api.py` | `ImageContent()` |
| `matrx_ai/providers/google/translator.py` | `ImageContent()` |
| `matrx_ai/agents/definition.py` | `LLMParams()` |
| `matrx_ai/agents/resolver.py` | `LLMParams()` |
| `matrx_ai/tests/test_cerebras_thinking_params.py` | `LLMParams()` |
| `matrx_ai/tests/test_llm_params_drift.py` | `LLMParams()` |
| `matrx_ai/orchestrator/executor.py` | `MessageList()` |
| `matrx_ai/orchestrator/requests.py` | `MessageList()` |
| `matrx_ai/processing/audio/audio_preprocessing.py` | `MessageList()` |
| `matrx_ai/providers/openai/openai_api.py` | `OpenAITTSRegistry()` |
| `matrx_ai/db/ai_models/ai_model_manager.py` | `PricingTier()` |
| `matrx_ai/providers/openai/translator.py` | `Role()` |
| `matrx_ai/processing/audio/audio_preprocessing.py` | `TextContent()` |
| `matrx_ai/providers/cerebras/cerebras_api.py` | `TextContent()` |
| `matrx_ai/providers/cerebras/translator.py` | `TextContent()` |
| `matrx_ai/providers/generic_openai/generic_openai_api.py` | `TextContent()` |
| `matrx_ai/providers/generic_openai/translator.py` | `TextContent()` |
| `matrx_ai/providers/google/translator.py` | `TextContent()` |
| `matrx_ai/providers/groq/groq_api.py` | `TextContent()` |
| `matrx_ai/providers/groq/translator.py` | `TextContent()` |
| `matrx_ai/providers/openai/translator.py` | `TextContent()` |
| `matrx_ai/providers/together/together_api.py` | `TextContent()` |
| `matrx_ai/providers/together/translator.py` | `TextContent()` |
| `matrx_ai/providers/xai/translator.py` | `TextContent()` |
| `matrx_ai/providers/xai/xai_api.py` | `TextContent()` |
| `matrx_ai/tests/groq_transcription_test.py` | `TextContent()` |
| `matrx_ai/tests/test_cerebras_thinking_params.py` | `TextContent()` |
| `matrx_ai/providers/anthropic/translator.py` | `ThinkingConfig()` |
| `matrx_ai/providers/cerebras/translator.py` | `ThinkingConfig()` |
| `matrx_ai/providers/google/translator.py` | `ThinkingConfig()` |
| `matrx_ai/providers/openai/translator.py` | `ThinkingConfig()` |
| `matrx_ai/tests/test_cerebras_thinking_params.py` | `ThinkingConfig()` |
| `matrx_ai/providers/cerebras/cerebras_api.py` | `ThinkingContent()` |
| `matrx_ai/providers/cerebras/translator.py` | `ThinkingContent()` |
| `matrx_ai/providers/google/translator.py` | `ThinkingContent()` |
| `matrx_ai/providers/openai/translator.py` | `ThinkingContent()` |
| `matrx_ai/__init__.py` | `TokenUsage()` |
| `matrx_ai/agent_runners/research.py` | `TokenUsage()` |
| `matrx_ai/agents/definition.py` | `TokenUsage()` |
| `matrx_ai/orchestrator/executor.py` | `TokenUsage()` |
| `matrx_ai/orchestrator/requests.py` | `TokenUsage()` |
| `matrx_ai/processing/audio/audio_preprocessing.py` | `TokenUsage()` |
| `matrx_ai/providers/anthropic/translator.py` | `TokenUsage()` |
| `matrx_ai/providers/cerebras/translator.py` | `TokenUsage()` |
| `matrx_ai/providers/eleven_labs/elevenlabs_api.py` | `TokenUsage()` |
| `matrx_ai/providers/generic_openai/generic_openai_api.py` | `TokenUsage()` |
| `matrx_ai/providers/generic_openai/translator.py` | `TokenUsage()` |
| `matrx_ai/providers/google/translator.py` | `TokenUsage()` |
| `matrx_ai/providers/groq/groq_api.py` | `TokenUsage()` |
| `matrx_ai/providers/groq/translator.py` | `TokenUsage()` |
| `matrx_ai/providers/openai/openai_api.py` | `TokenUsage()` |
| `matrx_ai/providers/openai/translator.py` | `TokenUsage()` |
| `matrx_ai/providers/together/together_api.py` | `TokenUsage()` |
| `matrx_ai/providers/together/translator.py` | `TokenUsage()` |
| `matrx_ai/providers/xai/translator.py` | `TokenUsage()` |
| `matrx_ai/providers/xai/xai_api.py` | `TokenUsage()` |
| `matrx_ai/tools/handle_tool_calls.py` | `TokenUsage()` |
| `matrx_ai/tools/implementations/_summarize_helper.py` | `TokenUsage()` |
| `matrx_ai/tools/models.py` | `TokenUsage()` |
| `matrx_ai/tools/tests/mimic_model_tests.py` | `TokenUsage()` |
| `matrx_ai/orchestrator/executor.py` | `ToolCallContent()` |
| `matrx_ai/providers/cerebras/cerebras_api.py` | `ToolCallContent()` |
| `matrx_ai/providers/cerebras/translator.py` | `ToolCallContent()` |
| `matrx_ai/providers/generic_openai/generic_openai_api.py` | `ToolCallContent()` |
| `matrx_ai/providers/generic_openai/translator.py` | `ToolCallContent()` |
| `matrx_ai/providers/google/translator.py` | `ToolCallContent()` |
| `matrx_ai/providers/groq/groq_api.py` | `ToolCallContent()` |
| `matrx_ai/providers/groq/translator.py` | `ToolCallContent()` |
| `matrx_ai/providers/openai/translator.py` | `ToolCallContent()` |
| `matrx_ai/providers/together/together_api.py` | `ToolCallContent()` |
| `matrx_ai/providers/together/translator.py` | `ToolCallContent()` |
| `matrx_ai/providers/xai/translator.py` | `ToolCallContent()` |
| `matrx_ai/providers/xai/xai_api.py` | `ToolCallContent()` |
| `matrx_ai/orchestrator/executor.py` | `ToolResultContent()` |
| `matrx_ai/orchestrator/requests.py` | `ToolResultContent()` |
| `matrx_ai/providers/cerebras/translator.py` | `ToolResultContent()` |
| `matrx_ai/providers/generic_openai/translator.py` | `ToolResultContent()` |
| `matrx_ai/providers/google/translator.py` | `ToolResultContent()` |
| `matrx_ai/providers/groq/translator.py` | `ToolResultContent()` |
| `matrx_ai/providers/together/translator.py` | `ToolResultContent()` |
| `matrx_ai/providers/xai/translator.py` | `ToolResultContent()` |
| `matrx_ai/agents/DEPRECATED_prompts_manager.py` | `UnifiedConfig()` |
| `matrx_ai/agents/definition.py` | `UnifiedConfig()` |
| `matrx_ai/agents/resolver.py` | `UnifiedConfig()` |
| `matrx_ai/agents/types.py` | `UnifiedConfig()` |
| `matrx_ai/db/agx_manager.py` | `UnifiedConfig()` |
| `matrx_ai/db/cx_managers.py` | `UnifiedConfig()` |
| `matrx_ai/db/tests/db_tests.py` | `UnifiedConfig()` |
| `matrx_ai/orchestrator/executor.py` | `UnifiedConfig()` |
| `matrx_ai/orchestrator/parallel_executor.py` | `UnifiedConfig()` |
| `matrx_ai/orchestrator/requests.py` | `UnifiedConfig()` |
| `matrx_ai/providers/anthropic/anthropic_api.py` | `UnifiedConfig()` |
| `matrx_ai/providers/anthropic/translator.py` | `UnifiedConfig()` |
| `matrx_ai/providers/base_translator.py` | `UnifiedConfig()` |
| `matrx_ai/providers/cerebras/cerebras_api.py` | `UnifiedConfig()` |
| `matrx_ai/providers/cerebras/translator.py` | `UnifiedConfig()` |
| `matrx_ai/providers/eleven_labs/elevenlabs_api.py` | `UnifiedConfig()` |
| `matrx_ai/providers/generic_openai/generic_openai_api.py` | `UnifiedConfig()` |
| `matrx_ai/providers/generic_openai/translator.py` | `UnifiedConfig()` |
| `matrx_ai/providers/google/google_api.py` | `UnifiedConfig()` |
| `matrx_ai/providers/google/google_video_api.py` | `UnifiedConfig()` |
| `matrx_ai/providers/google/translator.py` | `UnifiedConfig()` |
| `matrx_ai/providers/groq/groq_api.py` | `UnifiedConfig()` |
| `matrx_ai/providers/groq/translator.py` | `UnifiedConfig()` |
| `matrx_ai/providers/openai/openai_api.py` | `UnifiedConfig()` |
| `matrx_ai/providers/openai/translator.py` | `UnifiedConfig()` |
| `matrx_ai/providers/together/together_api.py` | `UnifiedConfig()` |
| `matrx_ai/providers/together/translator.py` | `UnifiedConfig()` |
| `matrx_ai/providers/xai/translator.py` | `UnifiedConfig()` |
| `matrx_ai/providers/xai/xai_api.py` | `UnifiedConfig()` |
| `matrx_ai/tests/execution_test.py` | `UnifiedConfig()` |
| `matrx_ai/tests/test_cerebras_thinking_params.py` | `UnifiedConfig()` |
| `matrx_ai/tests/test_llm_params_drift.py` | `UnifiedConfig()` |
| `matrx_ai/tools/implementations/_summarize_helper.py` | `UnifiedConfig()` |
| `matrx_ai/agents/definition.py` | `UnifiedMessage()` |
| `matrx_ai/db/conversation_rebuild.py` | `UnifiedMessage()` |
| `matrx_ai/orchestrator/executor.py` | `UnifiedMessage()` |
| `matrx_ai/orchestrator/requests.py` | `UnifiedMessage()` |
| `matrx_ai/processing/audio/audio_preprocessing.py` | `UnifiedMessage()` |
| `matrx_ai/providers/anthropic/translator.py` | `UnifiedMessage()` |
| `matrx_ai/providers/cerebras/translator.py` | `UnifiedMessage()` |
| `matrx_ai/providers/eleven_labs/elevenlabs_api.py` | `UnifiedMessage()` |
| `matrx_ai/providers/generic_openai/generic_openai_api.py` | `UnifiedMessage()` |
| `matrx_ai/providers/generic_openai/translator.py` | `UnifiedMessage()` |
| `matrx_ai/providers/google/google_video_api.py` | `UnifiedMessage()` |
| `matrx_ai/providers/google/translator.py` | `UnifiedMessage()` |
| `matrx_ai/providers/groq/groq_api.py` | `UnifiedMessage()` |
| `matrx_ai/providers/groq/translator.py` | `UnifiedMessage()` |
| `matrx_ai/providers/openai/openai_api.py` | `UnifiedMessage()` |
| `matrx_ai/providers/openai/translator.py` | `UnifiedMessage()` |
| `matrx_ai/providers/together/together_api.py` | `UnifiedMessage()` |
| `matrx_ai/providers/together/translator.py` | `UnifiedMessage()` |
| `matrx_ai/providers/xai/translator.py` | `UnifiedMessage()` |
| `matrx_ai/providers/xai/xai_api.py` | `UnifiedMessage()` |
| `matrx_ai/tests/groq_transcription_test.py` | `UnifiedMessage()` |
| `matrx_ai/tests/openai/openai_small_tests.py` | `UnifiedMessage()` |
| `matrx_ai/tests/test_cerebras_thinking_params.py` | `UnifiedMessage()` |
| `matrx_ai/orchestrator/executor.py` | `UnifiedResponse()` |
| `matrx_ai/orchestrator/recovery_logic.py` | `UnifiedResponse()` |
| `matrx_ai/orchestrator/requests.py` | `UnifiedResponse()` |
| `matrx_ai/providers/__init__.py` | `UnifiedResponse()` |
| `matrx_ai/providers/anthropic/anthropic_api.py` | `UnifiedResponse()` |
| `matrx_ai/providers/anthropic/translator.py` | `UnifiedResponse()` |
| `matrx_ai/providers/cerebras/cerebras_api.py` | `UnifiedResponse()` |
| `matrx_ai/providers/cerebras/translator.py` | `UnifiedResponse()` |
| `matrx_ai/providers/eleven_labs/elevenlabs_api.py` | `UnifiedResponse()` |
| `matrx_ai/providers/generic_openai/generic_openai_api.py` | `UnifiedResponse()` |
| `matrx_ai/providers/generic_openai/translator.py` | `UnifiedResponse()` |
| `matrx_ai/providers/google/google_api.py` | `UnifiedResponse()` |
| `matrx_ai/providers/google/google_video_api.py` | `UnifiedResponse()` |
| `matrx_ai/providers/google/translator.py` | `UnifiedResponse()` |
| `matrx_ai/providers/groq/groq_api.py` | `UnifiedResponse()` |
| `matrx_ai/providers/groq/translator.py` | `UnifiedResponse()` |
| `matrx_ai/providers/openai/openai_api.py` | `UnifiedResponse()` |
| `matrx_ai/providers/openai/translator.py` | `UnifiedResponse()` |
| `matrx_ai/providers/together/together_api.py` | `UnifiedResponse()` |
| `matrx_ai/providers/together/translator.py` | `UnifiedResponse()` |
| `matrx_ai/providers/unified_client.py` | `UnifiedResponse()` |
| `matrx_ai/providers/xai/translator.py` | `UnifiedResponse()` |
| `matrx_ai/providers/xai/xai_api.py` | `UnifiedResponse()` |
| `matrx_ai/providers/google/google_video_api.py` | `VideoContent()` |
| `matrx_ai/providers/google/translator.py` | `VideoContent()` |
| `matrx_ai/providers/openai/translator.py` | `WebSearchCallContent()` |
| `matrx_ai/providers/xai/xai_api.py` | `XAITTSRegistry()` |
| `matrx_ai/providers/cerebras/translator.py` | `YouTubeVideoContent()` |
| `matrx_ai/providers/generic_openai/translator.py` | `YouTubeVideoContent()` |
| `matrx_ai/providers/google/translator.py` | `YouTubeVideoContent()` |
| `matrx_ai/providers/groq/translator.py` | `YouTubeVideoContent()` |
| `matrx_ai/providers/together/translator.py` | `YouTubeVideoContent()` |
| `matrx_ai/providers/xai/translator.py` | `YouTubeVideoContent()` |
| `matrx_ai/orchestrator/executor.py` | `inject_editable_tools()` |
| `matrx_ai/orchestrator/executor.py` | `resolve_structured_inputs()` |
<!-- /AUTO:callers -->

<!-- AUTO:dependencies -->
## Dependencies

**External packages:** anthropic, google, matrx_connect, matrx_scraper, matrx_utils, openai, pydantic, rich
**Internal modules:** matrx_ai.context, matrx_ai.db, matrx_ai.instructions, matrx_ai.media, matrx_ai.processing, matrx_ai.tools
<!-- /AUTO:dependencies -->

<!-- AUTO:config -->
## Generation Config

> Auto-managed. Contains the exact parameters used to generate this README.
> Used by parent modules to auto-refresh this file when it is stale.
> Do not edit manually — changes will be overwritten on the next run.

```json
{
  "subdirectory": "matrx_ai/config",
  "mode": "signatures",
  "scope": null,
  "project_noise": null,
  "include_call_graph": false,
  "entry_points": null,
  "call_graph_exclude": [
    "tests"
  ],
  "signatures_exclude": [
    "tests",
    "db",
    "local_data",
    "docs"
  ]
}
```
<!-- /AUTO:config -->
