Skip to main content

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.function of the code that made the call. Set it yourself with zexl.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 zexl logger 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. Setting ZEXL_OPENAI_STREAM_USAGE=1 adds the option for you; it makes OpenAI send one extra final chunk with an empty choices list, so check your stream-handling code first.
  • with_streaming_response calls 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)

Source distribution for zexl 0.1.0
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)

Table of built distributions (wheels) for zexl 0.1.0
File Interpreter ABI Platform Actions
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.

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