# matrx_ai.providers.generic_openai — Module Overview


## IMPORTANT: Do not edit auto-generated sections.

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

**To refresh auto-sections:**
```bash
python utils/code_context/generate_module_readme.py matrx_ai/providers/generic_openai --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. 6 files across 1 directories.

```
matrx_ai/providers/generic_openai/
├── MODULE_README.md
├── __init__.py
├── generic_openai_api.py
├── huggingface_api.py
├── test_huggingface.py
├── translator.py
# excluded: 1 .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/providers/generic_openai/huggingface_api.py  [python]

  HUGGINGFACE_BASE_URL = os.environ.get('HUGGING_FACE_ENDPOINT_URL', 'https://a2w7lbho0x93g7kf.us-east-1.aws.endpoints.huggingface.cloud')
  class HuggingFaceChat(GenericOpenAIChat):
      def __init__(self, debug: bool = False)


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



---
Filepath: matrx_ai/providers/generic_openai/generic_openai_api.py  [python]

  DEBUG_OVERRIDE = False
  class GenericOpenAIChat:
      def __init__(self, base_url: str, api_key_env: str = 'HUGGING_FACE_TOKEN_ID', provider_name: str = 'generic_openai', api_key: str | None = None, 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/generic_openai/translator.py  [python]

  class GenericOpenAITranslator(BaseTranslator):
      def __init__(self, debug: bool = False)
      def to_generic_openai(self, config: UnifiedConfig, provider_name: str = 'generic_openai') -> dict[str, Any]
      def from_generic_openai(self, response: Any, provider_name: str = 'generic_openai') -> UnifiedResponse


---
Filepath: matrx_ai/providers/generic_openai/test_huggingface.py  [python]

  BASE_URL = os.environ.get('HUGGING_FACE_ENDPOINT_URL', 'https://a2w7lbho0x93g7kf.us-east-1.aws.endpoints.huggingface.cloud')
  API_KEY = os.environ.get('HUGGING_FACE_TOKEN_ID', '')
  MODEL = os.environ.get('HUGGING_FACE_MODEL_NAME', 'tgi')
  MAX_TOKENS = 3000
  def _make_client()
  async def test_non_streaming() -> None
  async def test_streaming(messages: list[dict[str, str]], *, tts: bool = True, thinking_tts: bool = False) -> None
  async def token_generator()
```
<!-- /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` | `GenericOpenAITranslator()` |
<!-- /AUTO:callers -->

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

**External packages:** dotenv, matrx_connect, matrx_utils, openai, temp
**Internal modules:** matrx_ai.config, matrx_ai.context, matrx_ai.providers, 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/generic_openai",
  "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 -->
