Metadata-Version: 2.5
Name: zexl
Version: 0.1.0
Summary: See how much of your AI spend did useful work, without sending a single prompt.
Project-URL: Homepage, https://tryzexl.xyz
Author: Zexl
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,anthropic,cost,llm,observability,openai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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

```bash
pip install zexl
```

```bash
export ZEXL_API_KEY="zx_<id>_<secret>.<salt>"
```

```python
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:

```python
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

```bash
uv sync
```

```bash
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:

```bash
uv run python bench/overhead.py
```

Test against several provider SDK versions (from the repository root):

```bash
scripts/sdk-matrix.sh
```
