Metadata-Version: 2.4
Name: tokeven
Version: 0.1.0
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: 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>=1.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>=1.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>=1.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

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

## 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.
- 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[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`.

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

## 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.

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

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.

## 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
