Metadata-Version: 2.4
Name: tokeven
Version: 0.4.1
Summary: Privacy first cost visibility for Claude, ChatGPT, and Gemini API calls. Metrics only, and your provider keys and prompts stay on your machine.
Author-email: Tokeven <team@tokeven.com>
Maintainer-email: Tokeven <team@tokeven.com>
License-Expression: LicenseRef-Tokeven-Proprietary
Project-URL: Homepage, https://tokeven.com
Project-URL: Documentation, https://tokeven.com/docs
Project-URL: Pricing, https://tokeven.com/pricing
Project-URL: Privacy, https://tokeven.com/privacy
Project-URL: Security, https://tokeven.com/security
Project-URL: Changelog, https://tokeven.com/docs#changelog
Keywords: anthropic,claude,openai,gemini,llm,cost,observability,tokens,finops,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: xai
Requires-Dist: openai>=1.0; extra == "xai"
Provides-Extra: google-genai
Requires-Dist: google-genai>=1.0; extra == "google-genai"
Provides-Extra: requests
Requires-Dist: requests>=2.28; extra == "requests"
Provides-Extra: mcp
Requires-Dist: mcp<3.0,>=2.0; extra == "mcp"
Provides-Extra: proxy
Requires-Dist: starlette>=0.37; extra == "proxy"
Requires-Dist: uvicorn>=0.29; extra == "proxy"
Requires-Dist: pydantic-settings>=2.2; extra == "proxy"
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == "all"
Requires-Dist: openai>=1.0; extra == "all"
Requires-Dist: google-genai>=1.0; extra == "all"
Requires-Dist: mcp<3.0,>=2.0; extra == "all"
Requires-Dist: starlette>=0.37; extra == "all"
Requires-Dist: uvicorn>=0.29; extra == "all"
Requires-Dist: pydantic-settings>=2.2; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: httpx>=0.24; extra == "dev"
Requires-Dist: anthropic>=0.40; extra == "dev"
Requires-Dist: openai>=1.0; extra == "dev"
Requires-Dist: google-genai>=1.0; extra == "dev"
Requires-Dist: mcp<3.0,>=2.0; extra == "dev"
Requires-Dist: starlette>=0.37; extra == "dev"
Requires-Dist: uvicorn>=0.29; extra == "dev"
Requires-Dist: pydantic-settings>=2.2; extra == "dev"
Dynamic: license-file

# tokeven

<!-- mcp-name: com.tokeven/tokeven -->

Per prompt cost visibility for the Claude, OpenAI, and Google SDKs, without
Tokeven ever holding a provider key or seeing a prompt.

`tokeven` wraps the official provider SDKs. Your call goes to the provider
exactly as before, and the wrapper reads the `usage` block off the response and
pushes a small metrics event to your Tokeven dashboard. It also answers the
question that saves the most money, which is what a call is about to cost before
you send it.

- Website: https://tokeven.com
- Documentation: https://tokeven.com/docs
- Pricing: https://tokeven.com/pricing
- Free teardown tool, no account needed: https://tokeven.com/teardown

## Thirty seconds, no install, no account

```bash
uvx tokeven teardown
```

Reads the Claude Code session logs already on your machine, prices them against
live rates, and prints what you have actually been spending. It makes zero
network calls and asks for nothing. Paste the output at
https://tokeven.com/teardown for the breakdown by model, or keep it local.

## What it does

- Estimates cost and confidence across all three providers before you send a
  call, so model choice is an informed decision rather than a default.
- Records what each call actually cost, with cache aware pricing recomputed
  server side.
- Runs as an MCP server, so Claude Code can ask for an estimate directly.
- Ships a live cost widget for your shell prompt or status line, and a self
  hosted sidecar for capturing usage without an SDK wrapper.
- Suggests cheaper models and prompt level efficiency improvements, and always
  leaves the decision to you. Nothing is rerouted silently.

## Privacy

- Tokeven receives token counts and metadata such as model, latency, and a
  character count computed locally. Prompt and completion content never reaches
  Tokeven through this pipeline.
- Every outgoing event passes a strict key allowlist, so content cannot be
  transmitted by accident.
- Authentication to Tokeven uses a write only ingest token, which cannot read
  your data or manage your account. It is not a provider key, and Tokeven never
  asks for one.
- `tokeven reconcile` reads your provider's billing report with a provider ADMIN
  key. That key is read from this machine's environment, used here, and never
  transmitted. Tokeven has no endpoint that accepts it. Only daily totals are
  sent.
- `TOKEVEN_ACTOR` is opt in and off by default. If you set it, the label you
  choose is attached to your events so your team can see who drives spend. It is
  a label you pick, not something derived from your prompts.
- Two features are opt in exceptions that do send prompt text you explicitly hand
  them, because rewriting a prompt requires reading it: the prompt revision tool
  on the website and `advisor.improve()`. Both are disclosed at the point of use.
  Details at https://tokeven.com/privacy
- If any part of the instrumentation fails, your provider call is returned
  unchanged. Tokeven is designed not to break your application.

## Install

```bash
pip install tokeven                  # wrapper, advisor, CLI, widget
pip install "tokeven[anthropic]"     # with the Anthropic SDK
pip install "tokeven[openai]"        # with the OpenAI SDK
pip install "tokeven[google-genai]"  # with the Google SDK
pip install "tokeven[xai]"           # for xAI / Grok (uses the OpenAI SDK)
pip install "tokeven[mcp]"           # with the MCP server
pip install "tokeven[proxy]"         # with the self hosted sidecar
pip install "tokeven[all]"           # everything
```

For the command line tools on their own, without touching a project environment:

```bash
pipx install tokeven
```

## Quickstart

Wrap your existing provider client. Configuration is read from the environment:
`TOKEVEN_INGEST_TOKEN`, `TOKEVEN_BASE_URL`, `TOKEVEN_PROJECT`, `TOKEVEN_MODE`,
`TOKEVEN_ACTOR`.

```python
from anthropic import Anthropic
from tokeven import TokevenAnthropic

client = TokevenAnthropic(Anthropic(), project="billing-agent")

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.content)   # unchanged Anthropic response

client.flush()   # optional: force-push buffered events before exit
```

`TokevenOpenAI` and `TokevenGemini` wrap the OpenAI and Google SDKs the same way.

For xAI / Grok, use `TokevenXAI`. Grok is served over the OpenAI SDK against
`api.x.ai`, so there is no separate xAI package to install:

```python
from tokeven import TokevenXAI

client = TokevenXAI(project="research-agent")   # reads XAI_API_KEY

resp = client.chat.completions.create(
    model="grok-4.6",
    messages=[{"role": "user", "content": "Hello"}],
)
```

`wrap()` recognises Grok too, including a client you built yourself:

```python
from openai import OpenAI
from tokeven import wrap

client = wrap(OpenAI(base_url="https://api.x.ai/v1", api_key="..."))
```

Two Grok pricing quirks worth knowing, both handled for you: cached input is
priced per model rather than as one family-wide discount, and every Grok model
charges double — input *and* output — once a prompt reaches 200,000 tokens.

## First run

Set your write only ingest token:

```bash
export TOKEVEN_INGEST_TOKEN="tkv_ing_..."
export TOKEVEN_BASE_URL="https://api.tokeven.com"
```

Create a token at https://tokeven.com/settings

Estimate the cost of a call before you send it:

```bash
tokeven estimate --model claude-opus-4-8 "your prompt here"
```

The estimate runs entirely on your machine and needs no account at all.

## Use it from Claude Code (MCP)

The advisor runs as an MCP server, so Claude can price a call before it makes
one. It is listed in the MCP registry as `com.tokeven/tokeven`, or add it by
hand:

```bash
claude mcp add tokeven -- uvx --with 'mcp>=2.0,<3.0' tokeven mcp
```

`tokeven mcp` and `tokeven-mcp` are the same server; the subcommand form is what
registry installs launch.

The MCP server estimates and advises. It does not track: nothing it does emits a
usage event, because `wrap()` and the sidecar are the only capture paths.
`tokeven status` reports which of those are actually live on this machine.

## Is it actually tracking? (`tokeven status`)

Instrumentation that is configured but inert looks exactly like instrumentation
that works, so there is one command that says which it is:

```bash
tokeven status
```

It reports which capture paths are live (and that the MCP server is an estimator,
not a tracker), the resolved `base_url` and where that value came from, the ingest
token prefix and its source, whether `base_url` is reachable, how many events are
sitting undelivered in the local durable queue, and a plain verdict on whether
anything is being tracked right now. It needs no login, works offline
(`--offline` skips the reachability probes), never prints your full token, and
exits non zero when it finds problems so you can use it in a script. `--json`
gives the same report machine readably.

## The sidecar (optional)

If you would rather not wrap an SDK, run the self hosted sidecar and point your
provider base URL at it. It forwards every request to the provider verbatim and
captures usage on a fail open side channel. Provider keys and prompt content
never reach Tokeven.

```bash
pip install "tokeven[proxy]"
tokeven-proxy
```

Point each SDK at the proxy in place of its provider:

| Provider | Base URL |
|---|---|
| Anthropic | `http://localhost:7779` |
| OpenAI | `http://localhost:7779/v1` |
| Google | `http://localhost:7779` |
| xAI / Grok | `http://localhost:7779/xai/v1` |

Grok is namespaced because xAI serves OpenAI's exact paths, so the proxy has no
other way to tell the two apart. It costs nothing: reaching `api.x.ai` already
requires a custom base URL. The `/xai` segment is stripped before forwarding, so
xAI sees the request your SDK built.

A container image and an example `docker-compose.yml` ship alongside this package.

## The live cost widget (optional)

A one line spend gauge for your shell prompt, tmux, or editor status line. It
reuses your dashboard login, never an ingest token or a provider key.

```bash
tokeven-widget            # print one status line and exit
tokeven-widget watch      # poll and reprint on an interval
```

## What is and is not tracked

Tokeven sees the traffic you instrument. Calls made through the provider
consoles, through the Anthropic Workbench, or from applications you have not
wrapped will not appear on the dashboard.

`tokeven reconcile` tells you how big that gap actually is. It reads your
provider's own daily cost report and pushes the totals, so the dashboard can show
what fraction of your real bill Tokeven can see instead of just warning you that
some of it is missing.

```bash
export ANTHROPIC_ADMIN_KEY=...      # or OPENAI_ADMIN_KEY; stays on this machine
tokeven reconcile --days 30         # add --dry-run to look before sending
```

Anthropic and OpenAI expose a billing API to an organization admin key. Google's
cost data lives in Cloud Billing exports and xAI has no equivalent endpoint, so
for those, export a CSV from the provider console:

```bash
tokeven reconcile --csv billing.csv --provider google
```

## Who is spending it

By default the only link from a call to a person is the ingest token that pushed
it, so a team sharing one token — or a CI pipeline — shows up as a single
anonymous bucket. Set `TOKEVEN_ACTOR` to label calls:

```bash
export TOKEVEN_ACTOR="zoe@example.com"   # or "zoe", or "build-agent-7"
```

If the label matches a team member's email, the dashboard attributes the spend to
them; if it matches nobody, it is reported under the label itself rather than
guessed at. Opt in, and unset by default.

## Free and paid

Everything this package does on your machine is free, and there is no trial clock
on it. That includes pre send cost estimates, the model picker, efficiency
suggestions, the MCP server, the sidecar, and the live cost widget. A free
Tokeven account adds a dashboard covering 1,000 tracked calls per month.

The paid tier is priced as gainshare. Tokeven earns 10 percent of verified
savings, measured per call against live token prices rather than a frozen
baseline, and you keep the other 90 percent. If you save nothing, you pay
nothing, and the fee falls automatically when model prices fall. There is no per
seat charge.

Paid adds:

- Unlimited tracked calls
- Prompt revision suggestions
- Organization wide savings dashboard and per person savings tracking
- Analytics across all three providers
- Embeddable widgets
- n8n and webhook integrations
- CSV, JSON, and API export

Enterprise terms, including capped arrangements for teams that budget fixed line
items, SSO, and custom retention, are handled case by case.

If you are weighing the paid tier or want a hand sizing what you would actually
save, email team@tokeven.com. We are happy to look at your numbers with you, and
there is no obligation attached to asking. Full pricing detail is at
https://tokeven.com/pricing

## License

Proprietary. The full terms ship in the `LICENSE` file bundled with this
package. Questions: team@tokeven.com
