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 viaconfigure(). - Context (
matrx_ai.context): re-exportsAppContext+Emitterfrommatrx-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 stripstemperature/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.
For a client host, get_jwt may be a synchronous or asynchronous zero-argument provider. matrx-ai resolves it at each authenticated server request and does not cache its result. Once a host configures that provider, a failure or missing token refuses the authenticated request instead of falling back to anonymous access. Without a provider, the public tool-catalog fetch remains unauthenticated.
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.
1 maintainer
Release files for matrx-ai 0.5.377
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| matrx_ai-0.5.377.tar.gz | 4.0 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| matrx_ai-0.5.377-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 7.6 MB
Release files / matrx_ai-0.5.377.tar.gz
| Download URL | matrx_ai-0.5.377.tar.gz |
|---|---|
| Size | 4.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
21b90dc2b97ae04f50ac0b6e1ea19bec9005a0658e3f0feeeb0b427eb409c027
|
|
BLAKE2b-256 checksum How to use checksums |
2488dadb858a13037fad570a0040f1be8d1205ddd5849583d5e75a6bf46352a5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / matrx_ai-0.5.377-py3-none-any.whl
| Download URL | matrx_ai-0.5.377-py3-none-any.whl |
|---|---|
| Size | 3.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
deda5b3b6dc8c910afd628818e453bb3bb285c7bd8a91e1c19349c62f8b261ee
|
|
BLAKE2b-256 checksum How to use checksums |
9f554438d83ef62432759994c81e9d5a2f3eac023e32fc7371568fd2f7c6e6c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency log
