Skip to main content

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 LancelotBlockedError with reason == "throttled", so you can show your own message.
  • Pause: every call for that customer raises LancelotBlockedError with reason == "paused".
  • Cheaper model: if you approved a swap (for example claude-sonnet-5-5 to claude-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 LancelotBlockedError with reason == "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)

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

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

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