Metadata-Version: 2.5
Name: lancelotwatch
Version: 0.1.0
Summary: Report per-customer AI usage to Lancelot. Wraps the OpenAI and Anthropic Python clients. No dependencies, never raises, never sees prompt content.
Project-URL: Homepage, https://lancelot.watch
Author: Lancelot
License-Expression: MIT
Keywords: ai,anthropic,cost,llm,margin,openai,stripe,usage
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# lancelotwatch

Report per-customer AI usage to [Lancelot](https://lancelot.watch) 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.

```bash
pip install lancelotwatch
```

Python 3.9 or newer.

## Wrap your client

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

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

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

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

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