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

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

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

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)

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.

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 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. This package lives in the aidream monorepo at github.com/AI-Matrix-Engine/aidream-current.

License

MIT.