Aitrix Python SDK (aitrix-sdk-py)

A thin, typed, OpenAI-compatible client for the Aitrix gateway. The hard part — governance (multi-engine DLP/PII, policy + quota, trajectory) — is server-side. This SDK just exposes the contract: an OpenAI-shaped response plus inline governance metadata, and a stable, typed error taxonomy.

Install

pip install aitrix-sdk-py

Single runtime dependency: httpx; ships a typed wheel (py.typed), no install-time code. Full user guide.

Self-hosted / air-gapped gateways can serve this same wheel from the gateway's built-in private index instead of public PyPI:

pip install --extra-index-url https://<your-gateway>/sdk/simple/ \
            --trusted-host <your-gateway> aitrix-sdk-py

--extra-index-url pulls aitrix-sdk-py from your gateway and httpx from PyPI. Drop --trusted-host for a CA-trusted cert. Browse https://<your-gateway>/sdk/ for the portal + user guide.

Usage

from aitrix.sdk import Aitrix

client = Aitrix(api_key="sk-...", base_url="https://gateway.example/v1")
resp = client.chat.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "hi"}],
)

print(resp.content)                          # assistant text
print(resp.aitrix_metadata.cost_usd)         # what it cost
print(resp.aitrix_metadata.pii_detected)     # was PII found/redacted
print(resp.aitrix_metadata.latency.total_ms) # latency breakdown
print(resp.usage.prompt_tokens)              # real token split

• client.chat.completions.create(...) is a deliberate OpenAI drop-in alias.
• Config resolves from args → env (AITRIX_API_KEY, AITRIX_BASE_URL) → default.
• base_url includes the /v1 prefix (e.g. https://host:8443/v1).
• Async: from aitrix.sdk import AsyncAitrix — identical API with await.

Governance metadata (resp.aitrix_metadata)

Unknown fields a newer server adds are preserved on aitrix_metadata.raw and ignored by the typed fields (forward-compatible).

Error handling

Every error subclasses AitrixError and carries status_code, code, request_id:

from aitrix.sdk import Aitrix, PolicyBlockError, QuotaExceededError, RateLimitError

try:
    resp = client.chat.create(model="...", messages=[...])
except PolicyBlockError as e:
    print("blocked:", e.code, e.policy_result)
except QuotaExceededError as e:
    print("out of budget:", e.request_id)
except RateLimitError:
    ...

Streaming

stream = client.chat.create(model="openai/gpt-4o-mini",
                            messages=[{"role": "user", "content": "hi"}], stream=True)
for piece in stream:          # yields assistant text deltas
    print(piece, end="", flush=True)
print(stream.aitrix_metadata.cost_usd)   # governance metadata from the final chunk
print(stream.usage.total_tokens)

Async: s = await client.chat.create(..., stream=True) then async for piece in s.

The gateway runs the full governance pipeline before streaming, so all guardrails apply — the response is complete (and checked) before the first chunk. You get the OpenAI SSE wire-format and final aitrix_metadata, but not token-by-token latency yet (true passthrough is future work).

Listing models

for m in client.models.list(provider="openai", capability="vision"):
    print(m.id, m.context_window, m.input_cost_per_token)

Filters: family (substring of id), capability (thinking / web_search / vision), provider.

Notes

• For self-signed gateways in testing, pass verify=False or your own http_client=httpx.Client(...).

License & contact

Apache-2.0 — see LICENSE. The SDK is a thin open client; the governance pipeline it talks to is the Aitrix gateway.

Questions, support, security reports: info@aitrix.ai