matrx-api

The Python client of every AI Matrx server. Sister of the TypeScript @ai-matrx/api: both are GENERATED from the same language-neutral server contract (aidream/api-contract/), so every operation, deployment route, auth tier, org rule and stream kind agrees across languages.

Depends on httpx only. Never imports aidream, never reads env vars: the host injects credentials, the organization and base URLs.

from matrx_api import MatrxApi, UserCredential
from matrx_api.generated import files

async with MatrxApi(credentials=lambda: UserCredential(token()), organization_id=org_id,
                    base_urls={"aidream": "http://localhost:8000"}) as api:
    meta = await files.get_file(api, path={"file_id": fid})
    async for frame in await some_domain.some_ndjson_op(api, body={...}):   # NDJSON -> parsed dicts
        ...

Behaviours: credentials on every call (user / guest / api_key / service / scoped, re-read per call); X-Organization-Id per the operation's org rule (required + missing -> OrganizationContextError before the wire; exempt never sends one); unique X-Request-Id; GET/HEAD retry with backoff on network failure, writes never; one MatrxApiError(status, code, message); NDJSON/SSE/bytes streams as async iterators (*_or_json operations return JsonOrStream).

Per-schema types: every generated domain module exports the contract's request/response schemas as TypedDicts (files.TYPES) and annotates body= / the return with them. route_prefix= (a string for every deployment, or {deployment: prefix}) is prepended to every path for callers that mount under a prefix. Installs on Python >=3.11.

Regenerate

python packages/matrx-api/scripts/generate.py          # after the contract changes
python packages/matrx-api/scripts/generate.py --check  # exit 1 on drift (also run by the tests)

Writes matrx_api/generated/<domain>.py (one module per x-matrx-domain) and matrx_api/deployments.py (CONTRACT_SHA256, default base URLs). RED (exit 1) on a missing/unknown x-matrx-* tag, an operation no deployment serves, or a domain-module collision. Never edit generated files.

Test

uv run pytest packages/matrx-api/tests