zexl (Python SDK)
Shows how much of your AI spend did useful work. It records metadata about each model call and sends it to Zexl. Prompt and response text never leave your process.
Status: early release (0.1.0). Tested against mocked provider responses only; not yet run against live provider APIs.
Install and use
pip install zexl
export ZEXL_API_KEY="zx_<id>_<secret>.<salt>"
import zexl.auto # add once, at your application's entry point
That is the whole setup. Calls made through the openai and anthropic packages are recorded from then on.
Optional:
import zexl
zexl.set_customer("acct_123") # attribute spend to one of your customers (use an id)
with zexl.run("research"): # group calls into one run explicitly
...
@zexl.run() # or as a decorator
def summarise(doc): ...
with zexl.feature("checkout-bot"): # set the feature label without starting a run
...
zexl.flush() # before a short-lived process (serverless) exits
| Environment variable | Meaning | Default |
|---|---|---|
ZEXL_API_KEY |
Your key. Required | none |
ZEXL_ENV |
Environment tag for every call | production |
ZEXL_DISABLED |
1 turns the SDK off completely |
off |
ZEXL_ENDPOINT |
Intake URL | Zexl's hosted intake |
ZEXL_OPENAI_STREAM_USAGE |
1 asks OpenAI for token usage on streamed chat completions (see below) |
off |
What leaves your process
Everything the SDK sends is built from a fixed allowlist (src/zexl/_export.py, SCHEMA). This is the complete list:
| Sent | Examples |
|---|---|
| Provider, API and model names | openai, chat, gpt-4o |
| Token counts reported by the provider | input, output, cache read, cache write, reasoning |
| Character counts | system prompt, tool definitions, input, output |
| Timings | start, end, time to first token |
| Outcome | finish reason, HTTP status, exception class name, whether a stream completed |
| Tool names | the name of each tool the model called, and how many tools were defined |
| Salted hashes | of the request, system prompt, tool definitions, newest input, output, and each tool call |
| Run id and step number | generated locally |
| Labels you set | feature, customer, environment |
| SDK details | SDK version, and an 8-character check value derived from your salt |
Never sent: message text, system prompts, tool descriptions and schemas, tool arguments, tool results, model output, images, exception messages, your provider API keys, and the salt.
Things to know:
- Tool names and model names are sent as-is when they look like identifiers. Do not put secrets in tool names.
- The feature label defaults to
module.functionof the code that made the call. Set it yourself withzexl.feature()if your function names are sensitive. - Lengths are sent. Character and token counts reveal how long a prompt was, not what it said.
How the hashes work
The part of your key after the dot is a salt. It stays in your process and is never transmitted. Every hash is an HMAC-SHA256 keyed with that salt, cut to 128 bits. Without the salt a hash cannot be matched to text, including by Zexl, and hashes from different workspaces cannot be compared. If you lose the key, the salt cannot be recovered; a new salt starts a new hash history.
How this is tested
tests/test_leak.py plants canary strings in every place content can appear (system prompt, messages, images, tool definitions, tool arguments, tool results, responses, streamed chunks, error bodies), runs each supported call style, and fails if a canary or the salt appears in any byte the SDK sends. It also plants a deliberate leak to confirm the check would catch one.
Behaviour you can rely on
- Your calls are never blocked or changed. Capture runs around the provider call; delivery happens on a background thread. If Zexl's intake is down, records are dropped and your application carries on.
- Errors inside the SDK never reach your code. They are logged once on the
zexllogger at warning level. - Exceptions from the provider pass through untouched.
- Bounded memory. At most 2,048 records wait for delivery; beyond that the SDK drops records.
- Delivery is tried, not guaranteed. Records go out every 2 seconds or every 256 records. A send that times out, loses its connection, or gets a 429 or 5xx is tried once more after 1 second. If that also fails, the batch is dropped and the SDK waits before the next send, from 2 seconds up to 60 seconds while the outage lasts.
- No dependencies. The SDK uses only the Python standard library.
zexl.status() reports whether capture is on, which hooks are active, and how many records were sent or dropped.
Overhead
Measured with bench/overhead.py on a laptop (Python 3.12, 14 Nov 2026). The provider is a
mock inside the process, so these figures are the SDK's own work, not network time.
| Call | Time added per call (median) |
|---|---|
| Chat or messages call, 1 KB prompt | 0.05 ms |
| Async chat call, 1 KB prompt | 0.05 ms |
| Streamed chat call, 200 chunks | 0.32 ms for the whole stream |
| Agent step, 60 KB history and 10 tools | 0.23 ms |
| Agent step, 1 MB history | 1.4 ms |
Memory: a process that made 5,000 agent-step calls peaked 12 MB higher with the SDK on, and 16 MB higher when the intake was down the whole time. The queue holds at most 2,048 records; beyond that the SDK drops records, so memory does not keep growing.
Sending happens on a background thread and never delays your call.
What is recorded
| Provider | Covered |
|---|---|
| OpenAI | chat.completions.create, .parse, .stream; responses.create, .parse; streaming; with_raw_response; sync and async |
| Anthropic | messages.create, .parse, .stream; beta.messages; streaming; with_raw_response; sync and async |
Tested with openai 1.68 to 3.50 and anthropic 0.50 to 2.8, on Python 3.10 and 3.13.
Known limits:
- Streamed OpenAI chat completions report no token usage unless you pass
stream_options={"include_usage": True}. Without it Zexl estimates cost from character counts. SettingZEXL_OPENAI_STREAM_USAGE=1adds the option for you; it makes OpenAI send one extra final chunk with an emptychoiceslist, so check your stream-handling code first. with_streaming_responsecalls are recorded without response details, because the SDK does not read the body ahead of you.- Retries inside the provider SDK are invisible. A call that succeeded on its third attempt is one record.
- Not yet covered: the Bedrock, Vertex and Azure client variants are untested, and other providers and agent frameworks are not hooked.
Runs
A run is one unit of agent work. Without any code from you, the SDK groups calls into a run when each request continues the previous response (the usual agent loop), or uses previous_response_id. If your application already has an OpenTelemetry trace active, the trace is the run.
Automatic grouping does not work when your agent trims or summarises its message history, or for sub-agents with their own conversations: those appear as separate runs. Wrap the work in zexl.run() to group it.
Development
uv sync
uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest
Measure what the SDK adds to a call (time per call, peak memory), against a mock provider:
uv run python bench/overhead.py
Test against several provider SDK versions (from the repository root):
scripts/sdk-matrix.sh
Metadata
Release files for zexl 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 |
|---|---|---|---|---|
| zexl-0.1.0.tar.gz | 28.3 kB | Without provenance | Details for zexl-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| zexl-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for zexl-0.1.0-py3-none-any.whl |
Total release size: 62.8 kB
Release files / zexl-0.1.0.tar.gz
| Download URL | zexl-0.1.0.tar.gz |
|---|---|
| Size | 28.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b8ce6f5531f81d8c6d82419079633c3ed89fd273bf40e48d3668ce1e8a6c41e5
|
|
BLAKE2b-256 checksum How to use checksums |
9000f9b6eddf53f6b639d070b9a87618077adbd7e473dc2fe10a3b63f48d0a0a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Release files / zexl-0.1.0-py3-none-any.whl
| Download URL | zexl-0.1.0-py3-none-any.whl |
|---|---|
| Size | 34.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5a3f5dcf62f27ab4a8bd152ad8b495b9ea3cfc9ccfaf785b1526def3221d1945
|
|
BLAKE2b-256 checksum How to use checksums |
8bf70bb538f1803a4bd3b13b4701e93e2334a06e5d66af47e548e9af471b2022
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Security for zexl 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.