Skip to main content

ambral-sdk (Python)

The Ambral Python SDK. Send usage events and read back itemized, explainable costs. Python 3.8+, no third-party dependencies (stdlib only).

Installs as the ambral-sdk distribution; imports as ambral.

pip install ambral-sdk

Usage

from ambral import Ambral

ambral = Ambral(api_key="YOUR_KEY")

result = ambral.track({
    "provider": "openai",
    "model": "gpt-4o",
    "inputTokens": 1_200_000,
    "outputTokens": 42_000,
})

# {"accepted": True, "pricingStatus": "priced", "cost": 3.42,
#  "explanation": "OpenAI → gpt-4o → version …: 1.2M input × $2.50 + …"}

Batch:

results = ambral.track_batch([
    {"provider": "openai", "model": "gpt-4o", "inputTokens": 1000, "outputTokens": 200},
    {"provider": "anthropic", "model": "claude-sonnet-4", "inputTokens": 500, "outputTokens": 100},
])

Idempotency

Every event carries an idempotency_key. Omit it and the SDK generates one; pass your own to make retries safe:

from ambral import idempotency_key

key = idempotency_key()
ambral.track({"provider": "openai", "model": "gpt-4o", "idempotencyKey": key})
ambral.track({"provider": "openai", "model": "gpt-4o", "idempotencyKey": key})  # safe retry

Configuration

Argument Default Notes
api_key — Required. Project API key from the dashboard.
base_url https://ambral.dev Point at a self-hosted instance.
retries 3 Retries network errors and 429/5xx with backoff.
timeout 10.0 Per-request timeout (seconds).
http UrllibHttpClient Inject a transport for testing.

Behavior

  • Cost is server-computed — you never send a price.
  • Unknown models are accepted (pricingStatus: "unpriced"), never rejected.
  • Client errors raise AmbralError; rate limits and server errors retry.
  • No prompts or completions are ever sent — only metadata and token counts.

See the event spec for the full field reference.

Metadata

Release files for ambral-sdk 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ambral-sdk 0.1.0
File Size Uploaded Provenance Actions
ambral_sdk-0.1.0.tar.gz 5.1 kB Without provenance Details for ambral_sdk-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ambral-sdk 0.1.0
File Interpreter ABI Platform Actions
ambral_sdk-0.1.0-py3-none-any.whl Python 3 none any Details for ambral_sdk-0.1.0-py3-none-any.whl

Total release size: 10.2 kB

Release files / ambral_sdk-0.1.0.tar.gz

Download URL ambral_sdk-0.1.0.tar.gz
Size 5.1 kB
Tags Source
SHA-256 checksum
How to use checksums
0e1b6bc1e84a0607e804f6ca9cc91af8649cc792ea738a144b85d9fd15df3368
BLAKE2b-256 checksum
How to use checksums
32ced19b961ddc63d65aa89e2e16d78dcdbce3499386e2ef4a67d929634ef058
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / ambral_sdk-0.1.0-py3-none-any.whl

Download URL ambral_sdk-0.1.0-py3-none-any.whl
Size 5.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5cdf34fdaecffade2d777d56c33647759afee52b1cbe87670f302c5b1717d32c
BLAKE2b-256 checksum
How to use checksums
63bd992e937615373dd25d460f9c52b54be04d13975b0ae39377ef85279019fa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for ambral-sdk 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page