lancelotwatch
Report per-customer AI usage to Lancelot so you can see which customers make you money and which lose it. Wraps the official OpenAI and Anthropic Python clients, sync and async. No dependencies. Never raises into your app. Never sees prompt or completion content, only token counts.
pip install lancelotwatch
Python 3.9 or newer.
Wrap your client
from openai import OpenAI
from anthropic import Anthropic
from lancelotwatch import lancelot
lc = lancelot() # reads LANCELOT_API_KEY
# Per request: bind the client to the customer you are serving.
openai = lc.wrap_openai(OpenAI(), customer_id=user.id, feature="chat")
res = openai.chat.completions.create(model="gpt-5-mini", messages=messages)
anthropic = lc.wrap_anthropic(Anthropic(), customer_id=user.id, feature="summarize")
msg = anthropic.messages.create(model="claude-haiku-5-5", max_tokens=500, messages=messages)
AsyncOpenAI and AsyncAnthropic work the same way. Wrapping is cheap: wrap once per request with that request's customer, or once at startup with customer_id=lambda params: ... to read it from the call.
Streams work: stream=True, and the .stream() helpers (with client.messages.stream(...) as stream:). For OpenAI chat streams we set stream_options={"include_usage": True} for you so the last chunk carries token counts.
If you already pass user (OpenAI) or metadata={"user_id": ...} (Anthropic), you can skip customer_id and we use that.
The wrapped client is a thin stand-in for yours: every method works as before, but isinstance(wrapped, OpenAI) is false.
Or report usage yourself
lc.track(
"cus_123", # customer
"openai", # provider
"gpt-5-mini", # model
1200, # input tokens: the whole prompt, cache reads and writes included
300, # output tokens
cached_input_tokens=800, # optional: cache reads
cache_write_tokens=0, # optional: Anthropic 5-minute cache writes
cache_write_1h_tokens=0, # optional: Anthropic 1-hour cache writes
feature="search", # optional
idempotency_key=response.id, # optional, dedupes retries
)
Events are batched on a background thread and sent every two seconds or every 100 events. In serverless functions, call lc.flush() (or await lc.aflush()) before returning. Pending events are also flushed when the process exits.
Letting Lancelot act
When Lancelot (or you, from the dashboard) throttles, pauses or switches a customer to a cheaper model, the SDK applies it before each wrapped call:
lc = lancelot(enable_flags=True) # polls every 60s, fails open
- Throttle: the customer gets a set number of AI calls a minute. Calls beyond that raise
LancelotBlockedErrorwithreason == "throttled", so you can show your own message. - Pause: every call for that customer raises
LancelotBlockedErrorwithreason == "paused". - Cheaper model: if you approved a swap (for example
claude-sonnet-5-5toclaude-haiku-5-5), requests for that customer on the expensive model are sent with the cheaper one instead. Nothing else changes.
from lancelotwatch import LancelotBlockedError
try:
reply = openai.chat.completions.create(model="gpt-5", messages=messages)
except LancelotBlockedError as e:
return "You've hit your plan's limit for now." # e.customer_id, e.reason
If Lancelot is unreachable, everything is allowed: an outage on our side never blocks your product. Without enable_flags, Lancelot can only suggest these fixes.
Or check yourself: lc.get_flags(customer_id) returns CustomerFlags(throttled, paused, throttle_cpm, downgrade), and lc.model_for(customer_id, model) returns the model to call.
Emergency stop and budgets
With enable_flags, the SDK also guards your AI bill locally, inside your app, with no network request on the hot path:
- Emergency stop: a customer who suddenly makes too many calls (default 600 a minute) or spends too fast (default $50 in 5 minutes) is stopped for a cooldown (default 5 minutes). Calls raise
LancelotBlockedErrorwithreason == "runaway". Lancelot is told at once. - Budgets: a customer with an hourly or daily budget is held once they reach it, with
reason == "budget", until the period resets.
Set the limits in Lancelot under Agent → Settings → Emergency stop. To override them in one process, or turn the stop off:
lc = lancelot(enable_flags=True, breaker={"max_calls_per_minute": 2000})
quiet = Lancelot(enable_flags=True, breaker=False)
Counts are kept per process, so with many workers the limits are approximate. Lancelot's own detectors catch what one process can't see. Forked workers (gunicorn, multiprocessing) start fresh.
Customer IDs
Use the same ID you store in Stripe customer metadata.customer_id (or metadata.user_id), or the customer's email. That is how we join your model cost to their revenue.
Options
Lancelot(api_key=None, *, base_url=None, flush_interval=2.0, max_batch_size=100, max_queue_size=10_000, enable_flags=False, flags_interval=60.0, on_error=None, disabled=False, breaker=None)
Delivery problems go to on_error (default: a logging warning at most once a minute, logger lancelotwatch). disabled=True turns off all network activity, for tests.
Metadata
Release files for lancelotwatch 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 |
|---|---|---|---|---|
| lancelotwatch-0.1.0.tar.gz | 18.0 kB | Without provenance | Details for lancelotwatch-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lancelotwatch-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for lancelotwatch-0.1.0-py3-none-any.whl |
Total release size: 39.1 kB
Release files / lancelotwatch-0.1.0.tar.gz
| Download URL | lancelotwatch-0.1.0.tar.gz |
|---|---|
| Size | 18.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bb03015eecf0d2db08630296b99cb1176ba87d1fdd3b03c6fcdde847ef9a5f90
|
|
BLAKE2b-256 checksum How to use checksums |
a23f227f878e545337e727d79715fabd3d8e2c438714cffd062ba66838722823
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.4 {"installer":{"name":"uv","version":"0.11.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / lancelotwatch-0.1.0-py3-none-any.whl
| Download URL | lancelotwatch-0.1.0-py3-none-any.whl |
|---|---|
| Size | 21.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
307e590aee06b9afc81ab6734579934ffd705d6bcac1884a81d82d113a16f1f4
|
|
BLAKE2b-256 checksum How to use checksums |
a9eca443a28ee654f92399274e946af3fd31877bc408d5d69d3fee0aeb83330e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.4 {"installer":{"name":"uv","version":"0.11.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for lancelotwatch 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.