# `ai.providers` — 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/providers` |
| Last generated | 2026-04-07 11:38 |
| Output file | `matrx_ai/providers/MODULE_README.md` |
| Signature mode | `signatures` |


**Child READMEs detected** (signatures collapsed — see links for detail):

| README | |
|--------|---|
| [`matrx_ai/providers/data_sync/MODULE_README.md`](matrx_ai/providers/data_sync/MODULE_README.md) | last generated 2026-04-07 11:38 |
| [`matrx_ai/providers/eleven_labs/MODULE_README.md`](matrx_ai/providers/eleven_labs/MODULE_README.md) | last generated 2026-04-07 11:38 |
| [`matrx_ai/providers/generic_openai/MODULE_README.md`](matrx_ai/providers/generic_openai/MODULE_README.md) | last generated 2026-04-07 11:38 |
| [`matrx_ai/providers/google/MODULE_README.md`](matrx_ai/providers/google/MODULE_README.md) | last generated 2026-04-07 11:38 |
**To refresh auto-sections:**
```bash
python utils/code_context/generate_module_readme.py matrx_ai/providers --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. 57 files across 11 directories.

```
matrx_ai/providers/
├── MODULE_README.md
├── __init__.py
├── anthropic/
│   ├── __init__.py
│   ├── anthropic_api.py
│   ├── client.py
│   ├── translator.py
├── base_translator.py
├── cerebras/
│   ├── __init__.py
│   ├── cerebras_api.py
│   ├── client.py
│   ├── translator.py
├── data_sync/
│   ├── MODULE_README.md
│   ├── __init__.py
│   ├── cerebras_model_sync.py
│   ├── google_model_sync.py
│   ├── groq_model_sync.py
│   ├── model_sync.py
│   ├── openai_model_sync.py
│   ├── together_model_sync.py
│   ├── xai_model_sync.py
├── eleven_labs/
│   ├── MODULE_README.md
│   ├── __init__.py
│   ├── client.py
│   ├── direct_dialogue.py
│   ├── elevenlabs_api.py
│   ├── tts_streaming.py
├── errors.py
├── generic_openai/
│   ├── MODULE_README.md
│   ├── __init__.py
│   ├── generic_openai_api.py
│   ├── huggingface_api.py
│   ├── test_huggingface.py
│   ├── translator.py
├── google/
│   ├── MODULE_README.md
│   ├── __init__.py
│   ├── google_api.py
│   ├── google_client.py
│   ├── google_video_api.py
│   ├── sample_podcast_direct.py
│   ├── translator.py
├── groq/
│   ├── __init__.py
│   ├── client.py
│   ├── groq_api.py
│   ├── translator.py
├── openai/
│   ├── __init__.py
│   ├── client.py
│   ├── openai_api.py
│   ├── translator.py
├── together/
│   ├── __init__.py
│   ├── client.py
│   ├── together_api.py
│   ├── translator.py
├── unified_client.py
├── xai/
│   ├── __init__.py
│   ├── client.py
│   ├── translator.py
│   ├── xai_api.py
# excluded: 5 .md
```
<!-- /AUTO:tree -->

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

> Auto-generated via `output_mode="{mode}"`. ~5-10% token cost vs full source.
> For full source, open the individual files directly.
> Submodules with their own `MODULE_README.md` are collapsed to a single stub line.

```
---
Filepath: matrx_ai/providers/base_translator.py  [python]

  class BaseTranslator:
      def __init__(self, debug: bool = False)
      def get_system_text(self, config: 'UnifiedConfig') -> str | None



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




---
Filepath: matrx_ai/providers/unified_client.py  [python]

  API_CLASS_TO_ENDPOINT = {23 keys}
  class UnifiedAIClient:
      def __init__(self)
      async def execute(self, request: AIMatrixRequest) -> dict[str, Any]
      async def translate_request(self, request: AIMatrixRequest) -> dict[str, Any]
      def translate_response(self, provider: Literal['openai', 'anthropic', 'gemini', 'together', 'groq', 'xai', 'cerebras', 'huggingface', 'generic_openai'], response: dict[str, Any]) -> UnifiedResponse



---
Filepath: matrx_ai/providers/errors.py  [python]

  class RetryableError:
      def get_backoff_delay(self, attempt: int) -> float
  def _extract_status_code(exception: Exception) -> int | None
  def _retry_after_from_status(status_code: int) -> float
  def _classify_by_status(status_code: int, provider: str, message: str) -> RetryableError
  def _fallback_classify(error_str: str, provider: str) -> RetryableError
  def classify_google_error(exception: Exception) -> RetryableError
  def classify_openai_error(exception: Exception) -> RetryableError
  def classify_anthropic_error(exception: Exception) -> RetryableError
  def classify_provider_error(provider: str, exception: Exception) -> RetryableError



---
Filepath: matrx_ai/providers/together/client.py  [python]

  def get_together_client() -> AsyncTogether



---
Filepath: matrx_ai/providers/together/__init__.py  [python]




---
Filepath: matrx_ai/providers/together/together_api.py  [python]

  DEBUG_OVERRIDE = False
  class TogetherChat:
      def __init__(self, debug: bool = False)
      def to_provider_config(self, config: UnifiedConfig, profile: ResolvedCallProfile) -> dict[str, Any]
      def to_unified_response(self, response: Any, model: str = '') -> UnifiedResponse
      async def execute(self, unified_config: UnifiedConfig, profile: ResolvedCallProfile, debug: bool = False) -> UnifiedResponse
      async def _execute_non_streaming(self, config_data: dict[str, Any], emitter: Emitter, model: str) -> UnifiedResponse
      async def _execute_streaming(self, config_data: dict[str, Any], emitter: Emitter, model: str) -> UnifiedResponse



---
Filepath: matrx_ai/providers/together/translator.py  [python]

  class TogetherTranslator(BaseTranslator):
      def __init__(self, debug: bool = False)
      def to_together(self, config: UnifiedConfig) -> dict[str, Any]
      def from_together(self, response: Any) -> UnifiedResponse



---
Submodule: matrx_ai/providers/google/  [6 files — full detail in matrx_ai/providers/google/MODULE_README.md]

---
Filepath: matrx_ai/providers/groq/client.py  [python]

  def get_groq_client() -> AsyncGroq



---
Filepath: matrx_ai/providers/groq/__init__.py  [python]




---
Filepath: matrx_ai/providers/groq/groq_api.py  [python]

  DEBUG_OVERRIDE = False
  class GroqChat:
      def __init__(self, debug: bool = False)
      def to_provider_config(self, config: UnifiedConfig, profile: ResolvedCallProfile) -> dict[str, Any]
      def to_unified_response(self, response: Any, model: str = '') -> UnifiedResponse
      async def execute(self, unified_config: UnifiedConfig, profile: ResolvedCallProfile, debug: bool = False) -> UnifiedResponse
      async def _execute_tts(self, unified_config: UnifiedConfig, emitter: Emitter, matrx_model_name: str) -> UnifiedResponse
      async def _execute_non_streaming(self, config_data: dict[str, Any], emitter: Emitter, model: str) -> UnifiedResponse
      async def _execute_streaming(self, config_data: dict[str, Any], emitter: Emitter, model: str) -> UnifiedResponse



---
Filepath: matrx_ai/providers/groq/translator.py  [python]

  class GroqTranslator(BaseTranslator):
      def __init__(self, debug: bool = False)
      def to_groq(self, config: UnifiedConfig) -> dict[str, Any]
      def from_groq(self, response: Any) -> UnifiedResponse



---
Submodule: matrx_ai/providers/eleven_labs/  [5 files — full detail in matrx_ai/providers/eleven_labs/MODULE_README.md]

---
Filepath: matrx_ai/providers/xai/client.py  [python]

  def get_xai_client() -> AsyncOpenAI



---
Filepath: matrx_ai/providers/xai/__init__.py  [python]




---
Filepath: matrx_ai/providers/xai/translator.py  [python]

  class XAITranslator(BaseTranslator):
      def __init__(self, debug: bool = False)
      def to_xai(self, config: UnifiedConfig) -> dict[str, Any]
      def from_xai(self, response: Any) -> UnifiedResponse



---
Filepath: matrx_ai/providers/xai/xai_api.py  [python]

  DEBUG_OVERRIDE = False
  class XAIChat:
      def __init__(self, debug: bool = False)
      def to_provider_config(self, config: UnifiedConfig, profile: ResolvedCallProfile) -> dict[str, Any]
      def to_unified_response(self, response: Any, model: str = '') -> UnifiedResponse
      async def execute(self, unified_config: UnifiedConfig, profile: ResolvedCallProfile, debug: bool = False) -> UnifiedResponse
      async def _execute_tts(self, unified_config: UnifiedConfig, emitter: Emitter, matrx_model_name: str) -> UnifiedResponse
      async def _execute_non_streaming(self, config_data: dict[str, Any], emitter: Emitter, model: str) -> UnifiedResponse
      async def _execute_streaming(self, config_data: dict[str, Any], emitter: Emitter, model: str) -> UnifiedResponse



---
Submodule: matrx_ai/providers/data_sync/  [8 files — full detail in matrx_ai/providers/data_sync/MODULE_README.md]

---
Submodule: matrx_ai/providers/generic_openai/  [5 files — full detail in matrx_ai/providers/generic_openai/MODULE_README.md]

---
Filepath: matrx_ai/providers/anthropic/anthropic_api.py  [python]

  DEBUG_OVERRIDE = False
  class AnthropicChat:
      def __init__(self, debug: bool = False)
      def to_provider_config(self, config: UnifiedConfig, profile: ResolvedCallProfile) -> dict[str, Any]
      def to_unified_response(self, response: Any, matrx_model_name: str = '') -> UnifiedResponse
      async def execute(self, unified_config: UnifiedConfig, profile: ResolvedCallProfile, debug: bool = False) -> UnifiedResponse
      async def _execute_non_streaming(self, config_data: dict[str, Any], emitter: Emitter, matrx_model_name: str) -> UnifiedResponse
      async def _execute_streaming(self, config_data: dict[str, Any], emitter: Emitter, matrx_model_name: str) -> UnifiedResponse
      async def _handle_event(self, event: Any, emitter: Emitter)
      async def _handle_content_block(self, block: Any, emitter: Emitter)
      async def _debug_event(self, event: Any)



---
Filepath: matrx_ai/providers/anthropic/client.py  [python]

  def get_anthropic_client() -> anthropic.AsyncAnthropic



---
Filepath: matrx_ai/providers/anthropic/__init__.py  [python]




---
Filepath: matrx_ai/providers/anthropic/translator.py  [python]

  class AnthropicTranslator(BaseTranslator):
      def __init__(self, debug: bool = False)
      def to_anthropic(self, config: UnifiedConfig, profile: ResolvedCallProfile) -> dict[str, Any]
      def from_anthropic(self, response: dict[str, Any], matrx_model_name: str) -> UnifiedResponse



---
Filepath: matrx_ai/providers/cerebras/client.py  [python]

  def get_cerebras_client() -> AsyncCerebras



---
Filepath: matrx_ai/providers/cerebras/__init__.py  [python]




---
Filepath: matrx_ai/providers/cerebras/translator.py  [python]

  class CerebrasTranslator(BaseTranslator):
      def __init__(self, debug: bool = False)
      def to_cerebras(self, config: UnifiedConfig) -> dict[str, Any]
      def from_cerebras(self, response: Any) -> UnifiedResponse



---
Filepath: matrx_ai/providers/cerebras/cerebras_api.py  [python]

  DEBUG_OVERRIDE = False
  class CerebrasChat:
      def __init__(self, debug: bool = False)
      def to_provider_config(self, config: UnifiedConfig, profile: ResolvedCallProfile) -> dict[str, Any]
      def to_unified_response(self, response: Any, model: str = '') -> UnifiedResponse
      async def execute(self, unified_config: UnifiedConfig, profile: ResolvedCallProfile, debug: bool = False) -> UnifiedResponse
      async def _execute_non_streaming(self, config_data: dict[str, Any], emitter: Emitter, model: str) -> UnifiedResponse
      async def _execute_streaming(self, config_data: dict[str, Any], emitter: Emitter, model: str) -> UnifiedResponse



---
Filepath: matrx_ai/providers/openai/client.py  [python]

  def get_openai_client() -> AsyncOpenAI



---
Filepath: matrx_ai/providers/openai/__init__.py  [python]




---
Filepath: matrx_ai/providers/openai/openai_api.py  [python]

  DEBUG_OVERRIDE = False
  class OpenAIChat:
      def __init__(self, debug: bool = False)
      def to_provider_config(self, config: UnifiedConfig, profile: ResolvedCallProfile) -> dict[str, Any]
      def to_unified_response(self, response: OpenAIResponse, matrx_model_name: str) -> UnifiedResponse
      async def execute(self, unified_config: UnifiedConfig, profile: ResolvedCallProfile, debug: bool = False) -> UnifiedResponse
      async def _execute_tts(self, unified_config: UnifiedConfig, emitter: Emitter, matrx_model_name: str) -> UnifiedResponse
      async def _execute_non_streaming(self, config_data: dict[str, Any], emitter: Emitter, matrx_model_name: str) -> UnifiedResponse
      async def _execute_streaming(self, config_data: dict[str, Any], emitter: Emitter, matrx_model_name: str) -> UnifiedResponse
      async def _handle_event(self, event: Any, emitter: Emitter)
      async def _debug_event(self, event: Any)



---
Filepath: matrx_ai/providers/openai/translator.py  [python]

  class OpenAITranslator(BaseTranslator):
      def __init__(self, debug: bool = False)
      def to_openai(self, config: UnifiedConfig, profile: ResolvedCallProfile) -> dict[str, Any]
      def from_openai(self, response: OpenAIResponse, matrx_model_name: str) -> UnifiedResponse
      def _build_unified_messages(self, output_items: list[OpenAIResponseOutputItem]) -> list[UnifiedMessage]
```
<!-- /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/tests/test_cerebras_thinking_params.py` | `CerebrasTranslator()` |
| `matrx_ai/tests/test_cerebras_thinking_params.py` | `GenericOpenAITranslator()` |
| `matrx_ai/tests/test_cerebras_thinking_params.py` | `GroqTranslator()` |
| `matrx_ai/tests/openai/openai_translation_test.py` | `OpenAITranslator()` |
| `matrx_ai/orchestrator/concurrent_engine.py` | `RetryableError()` |
| `matrx_ai/orchestrator/executor.py` | `RetryableError()` |
| `matrx_ai/tests/test_error_handling.py` | `RetryableError()` |
| `matrx_ai/tests/test_cerebras_thinking_params.py` | `TogetherTranslator()` |
| `matrx_ai/__init__.py` | `UnifiedAIClient()` |
| `matrx_ai/orchestrator/executor.py` | `UnifiedAIClient()` |
| `matrx_ai/tests/prompts/agent_comparison.py` | `UnifiedAIClient()` |
| `matrx_ai/tests/prompts/prompt_to_config.py` | `UnifiedAIClient()` |
| `matrx_ai/tests/test_translations.py` | `UnifiedAIClient()` |
| `matrx_ai/tests/test_cerebras_thinking_params.py` | `XAITranslator()` |
| `matrx_ai/tests/test_error_handling.py` | `classify_anthropic_error()` |
| `matrx_ai/tests/test_error_handling.py` | `classify_google_error()` |
| `matrx_ai/tests/test_error_handling.py` | `classify_openai_error()` |
| `matrx_ai/orchestrator/concurrent_engine.py` | `classify_provider_error()` |
| `matrx_ai/orchestrator/executor.py` | `classify_provider_error()` |
| `matrx_ai/tests/test_error_handling.py` | `classify_provider_error()` |
<!-- /AUTO:callers -->

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

**External packages:** anthropic, cerebras, dotenv, elevenlabs, google, google_client, groq, httpx, matrx_connect, matrx_utils, openai, rich, temp, together
**Internal modules:** matrx_ai._ext, matrx_ai.config, matrx_ai.context, matrx_ai.db, matrx_ai.local_data, matrx_ai.media, matrx_ai.orchestrator, 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/providers",
  "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 -->
