# matrx_ai.db.ai_models — 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 | `packages/matrx-ai/matrx_ai/db/ai_models` |
| Last generated | 2026-07-02 12:19 |
| Output file | `packages/matrx-ai/matrx_ai/db/ai_models/MODULE_README.md` |
| Signature mode | `signatures` |

**To refresh auto-sections:**
```bash
python utils/code_context/generate_module_readme.py packages/matrx-ai/matrx_ai/db/ai_models --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. 5 files across 1 directories.

```
packages/matrx-ai/matrx_ai/db/ai_models/
├── MODULE_README.md
├── __init__.py
├── ai_model_base.py
├── ai_model_dto.py
├── ai_model_manager.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: packages/matrx-ai/matrx_ai/db/ai_models/ai_model_manager.py  [python]

  class AiModelManager(AiModelBase):
      def __new__(cls, *args: Any, **kwargs: Any) -> AiModelManager
      def __init__(self) -> None
      async def _initialize_runtime_data(self, item: Any) -> None
      async def load_all_models(self) -> list[Any]
      async def load_model(self, id_or_name: str) -> Any | None
      async def load_model_get_string_uuid(self, id_or_name: str) -> str | None


---
Filepath: packages/matrx-ai/matrx_ai/db/ai_models/ai_model_base.py  [python]

  AiModel = get_model('AiModel')
  class AiModelBase(BaseManager[AiModel]):
      def __init__(self, dto_class: type[Any] | None = None, view_class: type[Any] | None = None, fetch_on_init_limit: int = 0, fetch_on_init_with_warnings_off: str | None = None) -> None


---
Filepath: packages/matrx-ai/matrx_ai/db/ai_models/__init__.py  [python]



---
Filepath: packages/matrx-ai/matrx_ai/db/ai_models/ai_model_dto.py  [python]

  AiModel = get_model('AiModel')
  DEFAULT_MAX_TOKENS = 4096
  class AiModelDTO(BaseDTO):
      async def _initialize_dto(self, model: AiModel) -> None
      async def _process_core_data(self, ai_model_item: AiModel) -> None
      async def _process_metadata(self, ai_model_item)
      async def _initial_validation(self, ai_model_item)
      async def _final_validation(self)
      async def get_validated_dict(self)
```
<!-- /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/db/persistence.py` | `AiModelManager()` |
<!-- /AUTO:callers -->

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

**External packages:** matrx_ai, matrx_orm, matrx_utils
<!-- /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": "packages/matrx-ai/matrx_ai/db/ai_models",
  "mode": "signatures",
  "scope": null,
  "project_noise": null,
  "include_call_graph": true,
  "entry_points": null,
  "call_graph_exclude": null
}
```
<!-- /AUTO:config -->

<!-- AUTO:call_graph -->
## Call Graph

> Auto-generated. All Python files.
> Shows which functions call which. `async` prefix = caller is an async function.
> Method calls shown as `receiver.method()`. Private methods (`_`) excluded by default.

### Call graph: packages.matrx-ai.matrx_ai.db.ai_models.ai_model_manager

```
async packages.matrx-ai.matrx_ai.db.ai_models.ai_model_manager.load_all_models → self.load_items() (line 39)
  async packages.matrx-ai.matrx_ai.db.ai_models.ai_model_manager.load_model → _uuid.UUID(str(id_or_name)) (line 45)
  async packages.matrx-ai.matrx_ai.db.ai_models.ai_model_manager.load_model → self.load_items() (line 47)
  async packages.matrx-ai.matrx_ai.db.ai_models.ai_model_manager.load_model → self.load_by_id(id_or_name) (line 57)
  async packages.matrx-ai.matrx_ai.db.ai_models.ai_model_manager.load_model → ...get('type') (line 61)
  async packages.matrx-ai.matrx_ai.db.ai_models.ai_model_manager.load_model_get_string_uuid → self.load_model(id_or_name) (line 66)
  Global Scope → packages.matrx-ai.matrx_ai.db.ai_models.ai_model_manager.AiModelManager() (line 70)
```

### Call graph: packages.matrx-ai.matrx_ai.db.ai_models.ai_model_base

```
Global Scope → packages.matrx-ai.matrx_ai.db.ai_models.ai_model_base.get_model('AiModel') (line 5)
  Global Scope → packages.matrx-ai.matrx_ai.db.ai_models.ai_model_base.get_base('AiModelBase') (line 8)
```

### Call graph: packages.matrx-ai.matrx_ai.db.ai_models.ai_model_dto

```
Global Scope → packages.matrx-ai.matrx_ai.db.ai_models.ai_model_dto.get_model('AiModel') (line 12)
  Global Scope → packages.matrx-ai.matrx_ai.db.ai_models.ai_model_dto.frozenset({'mock-standard'}) (line 27)
  async packages.matrx-ai.matrx_ai.db.ai_models.ai_model_dto._process_core_data → json.loads(endpoints) (line 52)
  async packages.matrx-ai.matrx_ai.db.ai_models.ai_model_dto._process_core_data → packages.matrx-ai.matrx_ai.db.ai_models.ai_model_dto.ModelSkipError() (line 65)
  async packages.matrx-ai.matrx_ai.db.ai_models.ai_model_dto.get_validated_dict → self.to_dict() (line 111)
```
<!-- /AUTO:call_graph -->
