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.
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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file matrx_ai-0.5.75.tar.gz.
File metadata
- Download URL: matrx_ai-0.5.75.tar.gz
- Upload date:
- Size: 2.9 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a57e590dd0686e6dc3649b69ac70a5d370cba8aa710de07d9cbc8c36556fc707
|
|
| MD5 |
06c091e2493886a9c0180e64686bc501
|
|
| BLAKE2b-256 |
380480bc0a608d774b1351ba79fbfdb40858c44ad344fa347e7483937c34ea5b
|
Provenance
The following attestation bundles were made for matrx_ai-0.5.75.tar.gz:
Publisher:
publish-package.yml on AI-Matrix-Engine/aidream
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
matrx_ai-0.5.75.tar.gz -
Subject digest:
a57e590dd0686e6dc3649b69ac70a5d370cba8aa710de07d9cbc8c36556fc707 - Sigstore transparency entry: 2536880226
- Sigstore integration time:
-
Permalink:
AI-Matrix-Engine/aidream@0a62b0f5c901c213dcb3577f43d678553d50e102 -
Branch / Tag:
refs/tags/matrx-ai/v0.5.75 - Owner: https://github.com/AI-Matrix-Engine
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-package.yml@0a62b0f5c901c213dcb3577f43d678553d50e102 -
Trigger Event:
push
-
Statement type:
File details
Details for the file matrx_ai-0.5.75-py3-none-any.whl.
File metadata
- Download URL: matrx_ai-0.5.75-py3-none-any.whl
- Upload date:
- Size: 2.7 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d6e7c94ed7e5e653ee3951ec395d9387d1d090fd8d1f7f96520e2da60cbe11e8
|
|
| MD5 |
ac393fdd6ea4892ad270466e5a3e6c35
|
|
| BLAKE2b-256 |
c6b07a050047ba227080d7c2219a5cd7534b0caa5f0926eed4ec05156799b413
|
Provenance
The following attestation bundles were made for matrx_ai-0.5.75-py3-none-any.whl:
Publisher:
publish-package.yml on AI-Matrix-Engine/aidream
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
matrx_ai-0.5.75-py3-none-any.whl -
Subject digest:
d6e7c94ed7e5e653ee3951ec395d9387d1d090fd8d1f7f96520e2da60cbe11e8 - Sigstore transparency entry: 2536880286
- Sigstore integration time:
-
Permalink:
AI-Matrix-Engine/aidream@0a62b0f5c901c213dcb3577f43d678553d50e102 -
Branch / Tag:
refs/tags/matrx-ai/v0.5.75 - Owner: https://github.com/AI-Matrix-Engine
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-package.yml@0a62b0f5c901c213dcb3577f43d678553d50e102 -
Trigger Event:
push
-
Statement type:
