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_urlincludes the/v1prefix (e.g.https://host:8443/v1).- Async:
from aitrix.sdk import AsyncAitrix— identical API withawait.
Governance metadata (resp.aitrix_metadata)
| Field | Meaning |
|---|---|
request_id |
correlate with gateway audit logs |
provider_selected / model_resolved |
what actually served the request |
cost_usd / input_cost_usd / output_cost_usd |
billed cost |
pii_detected / redaction_applied / entity_types_detected |
DLP outcome |
input_violation / output_violation / output_action |
guardrail outcome |
policy_rule_id |
which policy rule matched |
is_agent |
agent-session flag |
cached |
served from semantic cache |
latency |
{ total_ms, input_guardrails_ms, provider_ms, output_guardrails_ms, pii_ms } |
tokens |
{ prompt, completion, total } |
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:
...
| Exception | Trigger |
|---|---|
AuthenticationError |
401 |
PermissionDeniedError |
403 policy-rule denial (POLICY_DENIED, IMPLICIT_DENY, …) |
PolicyBlockError |
guardrail/DLP/content block, INTEGRATION_FAILURE |
QuotaExceededError |
402 / quota codes |
RateLimitError |
429 |
ModelNotFoundError |
404/400 unknown model (suggested_model, allowed_models) |
UpstreamError |
502 provider failure |
APIError |
other 5xx |
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=Falseor your ownhttp_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
Metadata
Release files for aitrix-sdk-py 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aitrix_sdk_py-0.1.0.tar.gz | 18.8 kB | Without provenance | Details for aitrix_sdk_py-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aitrix_sdk_py-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for aitrix_sdk_py-0.1.0-py3-none-any.whl |
Total release size: 34.6 kB
Release files / aitrix_sdk_py-0.1.0.tar.gz
| Download URL | aitrix_sdk_py-0.1.0.tar.gz |
|---|---|
| Size | 18.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3fdbba5236b374396213610535c5405d2540944b998c29d05a1f8ae51bc84147
|
|
BLAKE2b-256 checksum How to use checksums |
b189ede7a303b9ee9f917ebb1a7294f743c824e7643a6d93d3425b20ef459dda
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.13
|
Release files / aitrix_sdk_py-0.1.0-py3-none-any.whl
| Download URL | aitrix_sdk_py-0.1.0-py3-none-any.whl |
|---|---|
| Size | 15.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4e9081a746983eeb559a9032c2b56b0392366ee78f6843b445862d1f237de0e3
|
|
BLAKE2b-256 checksum How to use checksums |
d9ec46821e058711d0d090dc9f6bfc017f54dbbd20eff1573d975b0c1ea246c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.13
|
Security for aitrix-sdk-py 0.1.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.