Metadata-Version: 2.5
Name: matrx-api
Version: 0.1.1
Summary: Python client for every AI Matrx server, generated from the language-neutral server contract (sister of @ai-matrx/api)
Author-email: Matrx <admin@aimatrx.com>
License: MIT
Keywords: api-client,matrx,ndjson,openapi
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# 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.

```python
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
`TypedDict`s (`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`
