tokeven 0.1.0__tar.gz

tokeven-0.1.0/LICENSE

@@ -0,0 +1,27 @@
+Tokeven Client Software License
+
+Copyright (c) 2026 Tokeven. All rights reserved.
+
+Permission is granted to any person obtaining a copy of this software to install,
+execute, and use it for the purpose of instrumenting their own applications and
+reporting usage metrics to the Tokeven service.
+
+The following are not permitted without prior written permission from Tokeven:
+
+  1. Redistribution of this software, in source or binary form, whether modified
+     or unmodified.
+  2. Modification, adaptation, reverse engineering, decompilation, or disassembly
+     of this software, except to the extent that applicable law expressly permits
+     it despite this limitation.
+  3. Use of this software to build or operate a product that competes with the
+     Tokeven service.
+  4. Sublicensing, sale, rental, lease, or transfer of this software.
+
+This software is provided "as is", without warranty of any kind, express or
+implied, including but not limited to the warranties of merchantability, fitness
+for a particular purpose, and noninfringement. In no event shall the authors or
+copyright holders be liable for any claim, damages, or other liability, whether
+in an action of contract, tort, or otherwise, arising from, out of, or in
+connection with the software or the use or other dealings in the software.
+
+Questions about licensing: team@tokeven.com

tokeven-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+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

tokeven-0.1.0/README.md

@@ -0,0 +1,170 @@
+# 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

tokeven-0.1.0/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tokeven"
+version = "0.1.0"
+description = "Privacy first cost visibility for Claude, ChatGPT, and Gemini API calls. Metrics only, and your provider keys and prompts stay on your machine."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "LicenseRef-Tokeven-Proprietary"
+license-files = ["LICENSE"]
+authors = [{ name = "Tokeven", email = "team@tokeven.com" }]
+maintainers = [{ name = "Tokeven", email = "team@tokeven.com" }]
+keywords = [
+    "anthropic", "claude", "openai", "gemini", "llm", "cost",
+    "observability", "tokens", "finops", "mcp",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.24",
+]
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.40"]
+openai = ["openai>=1.0"]
+google-genai = ["google-genai>=1.0"]
+requests = ["requests>=2.28"]
+mcp = ["mcp>=1.0"]
+proxy = ["starlette>=0.37", "uvicorn>=0.29", "pydantic-settings>=2.2"]
+all = [
+    "anthropic>=0.40",
+    "openai>=1.0",
+    "google-genai>=1.0",
+    "mcp>=1.0",
+    "starlette>=0.37",
+    "uvicorn>=0.29",
+    "pydantic-settings>=2.2",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "httpx>=0.24",
+    "anthropic>=0.40",
+    "openai>=1.0",
+    "google-genai>=1.0",
+    "mcp>=1.0",
+    "starlette>=0.37",
+    "uvicorn>=0.29",
+    "pydantic-settings>=2.2",
+]
+
+[project.scripts]
+tokeven = "tokeven.cli:main"
+tokeven-mcp = "tokeven.mcp_server:main"
+tokeven-widget = "tokeven.widget.cli:main"
+tokeven-proxy = "tokeven.proxy.main:main"
+
+[project.urls]
+Homepage = "https://tokeven.com"
+Documentation = "https://tokeven.com/docs"
+Pricing = "https://tokeven.com/pricing"
+Privacy = "https://tokeven.com/privacy"
+Security = "https://tokeven.com/security"
+Changelog = "https://tokeven.com/docs#changelog"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+tokeven = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "--import-mode=importlib"
+asyncio_mode = "auto"

tokeven-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tokeven-0.1.0/src/tokeven/__init__.py

@@ -0,0 +1,112 @@
+"""Tokeven client SDK -- privacy-first, metric-only instrumentation.
+
+Public API::
+
+    from tokeven import TokevenAnthropic, TokevenOpenAI, TokevenGemini, TokevenConfig
+
+The wrappers capture only token counts + metadata (never prompt/response text),
+fail open (instrumentation errors never break underlying calls), and push
+batched events to Tokeven using a write-only ingest token.
+"""
+
+from __future__ import annotations
+
+from .advisor import (
+    CONFIDENCE_GREEN,
+    CONFIDENCE_YELLOW,
+    AdvisorResult,
+    ImproveResult,
+    ModelOption,
+    classify_task,
+    detect_modality,
+    estimate,
+    estimate_cost,
+    estimate_output_tokens,
+    format_options_table,
+    improve,
+    optimize_prompt,
+)
+from .client import TokevenAnthropic, wrap
+from .config import MODE_PER_PROMPT, MODE_PER_SESSION, TokevenConfig
+from .efficiency import (
+    Nudge,
+    cache_nudge,
+    compact_conversation,
+    estimate_messages_tokens,
+    estimate_tokens,
+    max_tokens_nudge,
+    model_mix_nudge,
+    pick_model,
+    prompt_length_nudge,
+    should_compact,
+    streaming_nudge,
+)
+from .entitlements import fetch_entitlements, is_entitled
+from .gemini_client import TokevenGemini
+from .guardrails import (
+    GuardConfig,
+    IdleReaper,
+    post_tool_use_reset,
+    pre_tool_use_decision,
+    touch_heartbeat,
+)
+from .openai_client import TokevenOpenAI
+from .registry import (
+    TIER_DEEP,
+    TIER_QUICK,
+    TIER_STANDARD,
+    all_models,
+    get_model,
+    model_id_for_tier,
+    tier_to_model_id,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "TokevenAnthropic",
+    "TokevenOpenAI",
+    "TokevenGemini",
+    "wrap",
+    "TokevenConfig",
+    "AdvisorResult",
+    "ModelOption",
+    "CONFIDENCE_GREEN",
+    "CONFIDENCE_YELLOW",
+    "classify_task",
+    "detect_modality",
+    "estimate",
+    "estimate_cost",
+    "estimate_output_tokens",
+    "format_options_table",
+    "optimize_prompt",
+    "improve",
+    "ImproveResult",
+    "fetch_entitlements",
+    "is_entitled",
+    "MODE_PER_PROMPT",
+    "MODE_PER_SESSION",
+    "pick_model",
+    "compact_conversation",
+    "should_compact",
+    "estimate_tokens",
+    "estimate_messages_tokens",
+    "Nudge",
+    "max_tokens_nudge",
+    "prompt_length_nudge",
+    "cache_nudge",
+    "streaming_nudge",
+    "model_mix_nudge",
+    "all_models",
+    "get_model",
+    "model_id_for_tier",
+    "tier_to_model_id",
+    "TIER_QUICK",
+    "TIER_STANDARD",
+    "TIER_DEEP",
+    "GuardConfig",
+    "IdleReaper",
+    "pre_tool_use_decision",
+    "post_tool_use_reset",
+    "touch_heartbeat",
+]