# matrx-ai

Unified multi-provider AI client, orchestration, and tool system for Python. One `UnifiedAIClient` that speaks to 12+ provider SDKs (OpenAI, Anthropic, Google, Groq, Cerebras, xAI, Together, ElevenLabs, Hugging Face, Cohere, Fireworks, Replicate) through a common `UnifiedConfig` / `UnifiedMessage` / `UnifiedResponse` contract, with streaming, tool calls, agents, and an orchestrator that runs a model until its task is complete.

## Install

```bash
pip install matrx-ai
```

Python 3.13+ required. Depends on `matrx-utils`, `matrx-connect`, `matrx-graph`, plus the provider SDKs. Host applications inject their own ORM models at startup via `matrx_ai.configure(...)`.

## What's in the box

- **Unified client** (`UnifiedAIClient`): one async interface over every supported provider; request translation + response normalization handled by per-provider adapters.
- **Config + message types**: `UnifiedConfig`, `UnifiedMessage`, `MessageList`, `UnifiedResponse`, enums (`Provider`, `Role`, `ContentType`, `FinishReason`), usage trackers (`TokenUsage`, `TimingUsage`, `ToolCallUsage`).
- **Orchestrator**: `AIMatrixRequest`, `CompletedRequest`, `execute_until_complete(...)` — autonomous multi-turn execution with tool loops.
- **Agents** (`matrx_ai.agents`): template + session-based agent system; caching; services.
- **Tools** (`matrx_ai.tools`): registry + built-in implementations (`ctx_patch`, `ctx_create`, shell, code, …). All host-specific integration points (ContextManifest, writeback persistence, test helpers) come in via `configure()`.
- **Context** (`matrx_ai.context`): re-exports `AppContext` + `Emitter` from `matrx-connect`.
- **Persistence** (`matrx_ai.db`): Supabase-backed conversation/request storage. ORM models are host-injected.
- **Providers** (`matrx_ai.providers`): per-provider translators, request shaping, streaming adapters, parameter modifiers (e.g. GPT-5 strips `temperature`/`top_p`).

## Usage

### One-shot call

```python
from matrx_ai import UnifiedAIClient, UnifiedConfig, UnifiedMessage, Provider, Role

client = UnifiedAIClient()
config = UnifiedConfig(
    provider=Provider.ANTHROPIC,
    ai_model="claude-sonnet-4-6",
    messages=[UnifiedMessage(role=Role.USER, content="Summarize the Magna Carta.")],
    stream=False,
)
response = await client.run(config)
print(response.text)
```

### Streaming

```python
config = UnifiedConfig(
    provider=Provider.OPENAI,
    ai_model="gpt-4o",
    messages=[UnifiedMessage(role=Role.USER, content="Explain RAFT.")],
    stream=True,
)
async for chunk in client.stream(config):
    print(chunk.delta, end="", flush=True)
```

### Autonomous execution (tools + multi-turn)

```python
from matrx_ai import execute_until_complete, AIMatrixRequest

request = AIMatrixRequest(
    config=config,
    tools=["web_search", "code_executor"],
    max_iterations=10,
)
completed = await execute_until_complete(request)
print(completed.final_response.text)
print(completed.timing_usage, completed.token_usage)
```

## Host integration — `matrx_ai.configure(...)`

matrx-ai is designed to be embedded in a larger application (like aidream) that supplies ORM models, settings, and context-object classes. It is also designed to run **without** any of that configuration — most features work on their own; the DB-dependent ones raise `ExtNotConfiguredError` at call time if the host didn't wire them up.

```python
import matrx_ai

matrx_ai.configure(
    db_models={"AiModel": AiModel, "CxConversation": CxConversation, ...},
    db_bases={"CxConversationBase": CxConversationBase, ...},
    db_instances={"guest_executions_manager": guest_manager},
    db_extras={"ContentBlocksDTO": ContentBlocksDTO},
    settings=settings,
    get_supabase_client=get_async_supabase_client,
    # Context-object model classes (used by ctx_patch / ctx_create tools)
    context_object_cls=ContextObject,
    context_object_type_cls=ContextObjectType,
    context_source_cls=ContextSource,
    persist_mode_cls=PersistMode,
    context_manifest_cls=ContextManifest,
    load_manifest_from_ctx=load_manifest_from_ctx,
    schedule_context_writeback=schedule_writeback,
    # …anything else the host wants to make available
)
```

This is the reference implementation of the "capability-within, injection-without" pattern used throughout the Matrx family — the package stores injected values in a module-level `_ext` registry; feature code retrieves them at call time via `get_ext("…")`. `import matrx_ai` always works in a minimal environment; only features that need a specific injection will raise if it's missing.

## Dependency posture

Hard deps: `matrx-utils`, `matrx-connect`, `matrx-graph`, plus the provider SDKs (Anthropic, OpenAI, Google GenAI, Groq, Cerebras, xAI, Together, Cohere, Fireworks, Replicate, Tiktoken) and core libs (`pydantic`, `httpx`, `aiohttp`, `supabase`, `asyncpg`, `json-repair`, `numpy`, `rich`).

matrx-ai does **not** depend on `matrx-orm`. The host app that embeds matrx-ai may use matrx-orm (aidream does), but matrx-ai itself accepts ORM model classes through `configure(db_models=..., db_bases=..., ...)` rather than importing them.

## Replaces

The old root-level `ai/` folder in the aidream monorepo. matrx-ai is now the canonical AI layer.

## Contributing

See [CLAUDE.md](CLAUDE.md) for package-specific rules (including the `_ext` injection pattern and the forbidden-imports list). Deep per-subsystem docs live in [`matrx_ai/MODULE_README.md`](matrx_ai/MODULE_README.md). This package lives in the aidream monorepo at [github.com/AI-Matrix-Engine/aidream-current](https://github.com/AI-Matrix-Engine/aidream-current/tree/main/packages/matrx-ai).

## License

MIT.
