tokenburn 0.2.0__tar.gz

tokenburn-0.2.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: tokenburn
+Version: 0.2.0
+Summary: Local-first proxy for LLM spend visibility and control.
+License: MIT
+Keywords: llm,proxy,tokens,cost,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=12.0
+Provides-Extra: share
+Requires-Dist: jinja2>=3.0; extra == "share"
+Provides-Extra: proxy
+Requires-Dist: starlette>=0.37; extra == "proxy"
+Requires-Dist: uvicorn>=0.29; extra == "proxy"
+Requires-Dist: httpx>=0.25; extra == "proxy"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: jinja2>=3.0; extra == "dev"
+Requires-Dist: starlette>=0.37; extra == "dev"
+Requires-Dist: uvicorn>=0.29; extra == "dev"
+Requires-Dist: httpx>=0.25; extra == "dev"
+Provides-Extra: all
+Requires-Dist: jinja2>=3.0; extra == "all"
+Requires-Dist: starlette>=0.37; extra == "all"
+Requires-Dist: uvicorn>=0.29; extra == "all"
+Requires-Dist: httpx>=0.25; extra == "all"
+
+# TokenBurn
+
+> `htop` for your LLM spend — proxy-only.
+
+TokenBurn is a local-first HTTP proxy for LLM spend visibility and control.
+
+Route OpenAI-, Anthropic-, and Gemini-compatible traffic through a local proxy. TokenBurn logs usage locally, attributes cost by model/provider/program/tag, and turns raw traffic into actionable waste reports.
+
+**No hosted backend. No account. No prompt egress by default.**
+
+---
+
+## Install
+
+```bash
+pip install "tokenburn[proxy]"
+tokenburn proxy setup
+tokenburn proxy start --background
+```
+
+After setup, clients that support base URL overrides can route through TokenBurn with no app-specific SDK integration.
+
+---
+
+## What it does
+
+- **Proxy-based capture** — intercepts LLM traffic at the HTTP layer
+- **Cross-language** — works with Python, TypeScript, Go, curl, and anything else that can point at a base URL
+- **Cross-provider** — OpenAI, Anthropic, Gemini
+- **Local logs** — normalized JSONL logs under `~/.tokenburn/logs/`
+- **Spend reports** — model, provider, endpoint, program, and tag breakdowns
+- **Waste detection** — highlights expensive patterns worth fixing first
+- **Shareable output** — terminal and exported reports
+
+---
+
+## Core commands
+
+```bash
+tokenburn proxy setup
+tokenburn proxy start --background
+tokenburn proxy status
+tokenburn proxy stop
+
+tokenburn report
+tokenburn gain
+tokenburn share --open
+tokenburn doctor
+```
+
+---
+
+## Product direction
+
+TokenBurn is proxy-only.
+
+That means the product lives at the proxy boundary rather than inside application runtimes.
+
+The product lives at the network boundary, not inside app SDKs.
+
+---
+
+## Repo docs
+
+- `PROXY_TFF.md` — proxy technical design
+- `SPEC.md` — product and positioning
+- `keche.md` — project operating brief
+- `CLAUDE.md` — maintainer workflow notes
+
+---
+
+## License
+
+MIT

tokenburn-0.2.0/README.md

@@ -0,0 +1,74 @@
+# TokenBurn
+
+> `htop` for your LLM spend — proxy-only.
+
+TokenBurn is a local-first HTTP proxy for LLM spend visibility and control.
+
+Route OpenAI-, Anthropic-, and Gemini-compatible traffic through a local proxy. TokenBurn logs usage locally, attributes cost by model/provider/program/tag, and turns raw traffic into actionable waste reports.
+
+**No hosted backend. No account. No prompt egress by default.**
+
+---
+
+## Install
+
+```bash
+pip install "tokenburn[proxy]"
+tokenburn proxy setup
+tokenburn proxy start --background
+```
+
+After setup, clients that support base URL overrides can route through TokenBurn with no app-specific SDK integration.
+
+---
+
+## What it does
+
+- **Proxy-based capture** — intercepts LLM traffic at the HTTP layer
+- **Cross-language** — works with Python, TypeScript, Go, curl, and anything else that can point at a base URL
+- **Cross-provider** — OpenAI, Anthropic, Gemini
+- **Local logs** — normalized JSONL logs under `~/.tokenburn/logs/`
+- **Spend reports** — model, provider, endpoint, program, and tag breakdowns
+- **Waste detection** — highlights expensive patterns worth fixing first
+- **Shareable output** — terminal and exported reports
+
+---
+
+## Core commands
+
+```bash
+tokenburn proxy setup
+tokenburn proxy start --background
+tokenburn proxy status
+tokenburn proxy stop
+
+tokenburn report
+tokenburn gain
+tokenburn share --open
+tokenburn doctor
+```
+
+---
+
+## Product direction
+
+TokenBurn is proxy-only.
+
+That means the product lives at the proxy boundary rather than inside application runtimes.
+
+The product lives at the network boundary, not inside app SDKs.
+
+---
+
+## Repo docs
+
+- `PROXY_TFF.md` — proxy technical design
+- `SPEC.md` — product and positioning
+- `keche.md` — project operating brief
+- `CLAUDE.md` — maintainer workflow notes
+
+---
+
+## License
+
+MIT

tokenburn-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tokenburn"
+version = "0.2.0"
+description = "Local-first proxy for LLM spend visibility and control."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+keywords = ["llm", "proxy", "tokens", "cost", "observability"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "click>=8.0",
+    "rich>=12.0",
+]
+
+[project.optional-dependencies]
+share = ["jinja2>=3.0"]
+proxy = ["starlette>=0.37", "uvicorn>=0.29", "httpx>=0.25"]
+dev = ["pytest", "pytest-cov", "pytest-asyncio", "jinja2>=3.0", "starlette>=0.37", "uvicorn>=0.29", "httpx>=0.25"]
+all = ["jinja2>=3.0", "starlette>=0.37", "uvicorn>=0.29", "httpx>=0.25"]
+
+[project.scripts]
+tokenburn = "tokenburn.cli:cli"
+
+[tool.setuptools.package-data]
+tokenburn = ["templates/*.j2", "py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+
+[tool.setuptools.packages.find]
+include = ["tokenburn*"]

tokenburn-0.2.0/setup.cfg

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

tokenburn-0.2.0/tokenburn/__init__.py

@@ -0,0 +1,142 @@
+"""TokenBurn - LLM token waste detector SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from tokenburn.classify import classify_entries_async
+
+__version__ = "0.1.0"
+
+
+def wrap(
+    client: Any,
+    default_tags: Optional[str] = None,
+    log_preview: bool = True,
+) -> Any:
+    """Wrap an OpenAI or Anthropic client to log all LLM calls.
+
+    Supports sync and async clients for OpenAI and Anthropic.
+
+    Usage:
+        import openai
+        import anthropic
+        from tokenburn import wrap
+
+        # Sync
+        client = wrap(openai.OpenAI())
+        # Use client as normal - all calls are logged
+
+        # Async
+        async_client = wrap(openai.AsyncOpenAI())
+        response = await async_client.chat.completions.create(...)
+
+        # Anthropic (sync + async both supported)
+        anth = wrap(anthropic.Anthropic())
+        anth_async = wrap(anthropic.AsyncAnthropic())
+    """
+    from tokenburn.wrapper import wrap as _wrap
+
+    return _wrap(client, default_tags=default_tags, log_preview=log_preview)
+
+
+def log_raw(
+    provider: str,
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+    cache_read_tokens: int = 0,
+    cache_creation_tokens: int = 0,
+    max_tokens_set: int | None = None,
+    system_prompt_hash: str | None = None,
+    tool_count: int = 0,
+    tool_schema_tokens: int = 0,
+    tags: str | None = None,
+    streaming: bool = False,
+    duration_ms: int | None = None,
+    error: bool = False,
+    error_type: str | None = None,
+    request_id: str | None = None,
+    caller: str | None = None,
+) -> None:
+    """Log an LLM call manually (for apps that can't use wrap()).
+
+    Never raises — silently swallows errors to avoid breaking the caller.
+    """
+    try:
+        from datetime import datetime, timezone
+        from tokenburn.logger import log_entry
+
+        entry: dict[str, Any] = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "provider": provider,
+            "model": model,
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+            "cache_read_tokens": cache_read_tokens,
+            "cache_creation_tokens": cache_creation_tokens,
+            "streaming": streaming,
+            "error": error,
+        }
+        if max_tokens_set is not None:
+            entry["max_tokens_set"] = max_tokens_set
+        if system_prompt_hash is not None:
+            entry["system_prompt_hash"] = system_prompt_hash
+        if tool_count:
+            entry["tool_count"] = tool_count
+        if tool_schema_tokens:
+            entry["tool_schema_tokens"] = tool_schema_tokens
+        if tags is not None:
+            entry["tags"] = tags
+        if duration_ms is not None:
+            entry["duration_ms"] = duration_ms
+        if error_type is not None:
+            entry["error_type"] = error_type
+        if request_id is not None:
+            entry["request_id"] = request_id
+        if caller is not None:
+            entry["call_site"] = {"file": caller, "function": "", "line": 0}
+        else:
+            from tokenburn.wrapper import _get_call_site
+            cs = _get_call_site()
+            if cs is not None:
+                entry["call_site"] = cs
+
+        log_entry(entry)
+    except Exception:
+        pass
+
+
+def compress_history(
+    messages: list,
+    max_tokens: int = 8000,
+    keep_recent: int = 5,
+    summarizer_model: str = "gpt-4o-mini",
+    api_key: Optional[str] = None,
+) -> list:
+    """Compress a message history by summarizing old messages.
+
+    Partitions messages into system messages (preserved verbatim at the top)
+    and conversation messages. Keeps the most recent `keep_recent` conversation
+    messages unchanged. Older conversation messages are summarized into a single
+    system message when they would exceed the token budget.
+
+    Args:
+        messages: List of chat messages (dicts with 'role' and 'content').
+        max_tokens: Target token budget. Returns unchanged if already fits.
+        keep_recent: Number of recent conversation messages to keep verbatim.
+        summarizer_model: OpenAI model used for summarization.
+        api_key: Optional OpenAI API key (uses env var if None).
+
+    Returns:
+        Compressed list of messages, or the original list if no compression needed.
+    """
+    from tokenburn.compress import compress_history as _compress_history
+
+    return _compress_history(
+        messages,
+        max_tokens=max_tokens,
+        keep_recent=keep_recent,
+        summarizer_model=summarizer_model,
+        api_key=api_key,
+    )

tokenburn-0.2.0/tokenburn/adapters/__init__.py

@@ -0,0 +1,32 @@
+"""LLM provider adapters for usage extraction and streaming handling."""
+
+from tokenburn.adapters.openai import (
+    UsageResult as OpenAIUsageResult,
+    OpenAIEventHandler,
+    extract_from_response as openai_extract,
+)
+from tokenburn.adapters.anthropic import (
+    AnthropicUsageResult,
+    AnthropicEventHandler,
+    extract_from_response as anthropic_extract,
+)
+from tokenburn.adapters.gemini import (
+    GeminiUsageResult,
+    GeminiEventHandler,
+    extract_from_response as gemini_extract,
+)
+
+__all__ = [
+    # Result dataclasses
+    "OpenAIUsageResult",
+    "AnthropicUsageResult",
+    "GeminiUsageResult",
+    # Streaming event handlers
+    "OpenAIEventHandler",
+    "AnthropicEventHandler",
+    "GeminiEventHandler",
+    # Non-streaming extraction
+    "openai_extract",
+    "anthropic_extract",
+    "gemini_extract",
+]

tokenburn-0.2.0/tokenburn/adapters/anthropic.py

@@ -0,0 +1,226 @@
+# tokenburn/adapters/anthropic.py
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AnthropicUsageResult:
+    """Normalized usage extracted from an Anthropic response."""
+    input_tokens: int | None
+    output_tokens: int | None
+    cache_read_tokens: int
+    cache_creation_tokens: int
+    thinking_tokens: int | None  # Estimated from thinking text chars // 4 (Anthropic doesn't report separately)
+    tool_calls_made: int | None
+    total_tokens: int | None = None  # Always None — Anthropic doesn't report it; field exists for parity with OpenAI
+    raw_usage: dict | None = None
+    usage_source: str = "provider_response"
+    model_served: str | None = None
+    request_id: str | None = None
+    response_id: str | None = None  # msg_... message ID from API response
+    stop_reason: str | None = None  # end_turn, tool_use, max_tokens, etc.
+
+    @property
+    def usage_status(self) -> str:
+        if self.input_tokens is not None and self.output_tokens is not None:
+            return "exact"
+        return "missing"
+
+    @property
+    def computed_total_tokens(self) -> int | None:
+        """Compute total from input + output since Anthropic doesn't report it.
+
+        Note: this is input_tokens + output_tokens, which EXCLUDES cache tokens
+        (Anthropic's input_tokens does not include cache_read/cache_creation).
+        Returns None when either component is missing rather than falling back
+        to an ambiguous value.
+        """
+        if self.input_tokens is not None and self.output_tokens is not None:
+            return self.input_tokens + self.output_tokens
+        return None
+
+    def apply_to_entry(self, entry: dict) -> None:
+        """Write normalized fields into a log entry dict."""
+        entry["input_tokens"] = self.input_tokens
+        entry["output_tokens"] = self.output_tokens
+        entry["total_tokens"] = self.computed_total_tokens
+        entry["cache_read_tokens"] = self.cache_read_tokens
+        entry["cache_creation_tokens"] = self.cache_creation_tokens
+        entry["thinking_tokens"] = self.thinking_tokens
+        entry["raw_usage"] = self.raw_usage
+        entry["usage_source"] = self.usage_source
+        entry["usage_status"] = self.usage_status
+        if self.model_served:
+            entry["model"] = self.model_served
+        if self.request_id:
+            entry["request_id"] = self.request_id
+        if self.response_id:
+            entry["response_id"] = self.response_id
+            # Dual-write: also set request_id for backwards compatibility
+            # with existing log entries and downstream code that reads request_id.
+            if not self.request_id:
+                entry["request_id"] = self.response_id
+        if self.tool_calls_made is not None:
+            entry["tool_calls_made"] = self.tool_calls_made
+        if self.stop_reason is not None:
+            entry["stop_reason"] = self.stop_reason
+
+
+def extract_from_response(body: dict) -> AnthropicUsageResult:
+    """Extract usage from a non-streaming Anthropic Messages API response body."""
+    usage = body.get("usage") or {}
+    content = body.get("content") or []
+
+    thinking_chars = sum(
+        len(block.get("thinking") or "")
+        for block in content
+        if isinstance(block, dict) and block.get("type") == "thinking"
+    )
+
+    tool_calls = sum(
+        1 for block in content
+        if isinstance(block, dict) and block.get("type") == "tool_use"
+    )
+
+    return AnthropicUsageResult(
+        input_tokens=usage.get("input_tokens"),
+        output_tokens=usage.get("output_tokens"),
+        cache_read_tokens=usage.get("cache_read_input_tokens", 0),
+        cache_creation_tokens=usage.get("cache_creation_input_tokens", 0),
+        thinking_tokens=thinking_chars // 4 if thinking_chars > 0 else None,
+        tool_calls_made=tool_calls,
+        raw_usage=usage if usage else None,
+        usage_source="provider_response",
+        model_served=body.get("model"),
+        response_id=body.get("id"),  # msg_... is a response identifier
+        stop_reason=body.get("stop_reason"),
+    )
+
+
+def create_stream_handler() -> AnthropicEventHandler:
+    """Factory: create a fresh AnthropicEventHandler for a new stream."""
+    return AnthropicEventHandler()
+
+
+class AnthropicEventHandler:
+    """Handles parsed SSE events for Anthropic Messages API.
+
+    Receives dicts from SSEStreamBuffer and accumulates usage state.
+
+    Events handled:
+    - message_start        -> input_tokens, cache tokens, model, response_id
+    - content_block_start  -> tool_calls_made counter (type == "tool_use")
+    - content_block_delta  -> thinking char accumulation (type == "thinking_delta")
+    - message_delta        -> output_tokens, stop_reason
+    - error                -> error_type, error_message
+    """
+
+    def __init__(self) -> None:
+        self._finalized_result: AnthropicUsageResult | None = None
+
+        self.model_served: str | None = None
+        self.response_id: str | None = None
+        self.input_tokens: int | None = None
+        self.output_tokens: int | None = None
+        self.cache_read_tokens: int = 0
+        self.cache_creation_tokens: int = 0
+        self._thinking_chars: int = 0
+        self._tool_call_count: int = 0
+        self._raw_usage_parts: dict = {}
+        self.error_type: str | None = None
+        self.error_message: str | None = None
+        self.stop_reason: str | None = None
+
+    def handle(self, event: dict) -> None:
+        """Process a single parsed SSE event dict."""
+        if self._finalized_result is not None:
+            logger.warning("AnthropicEventHandler.handle() called after finalize() — event dropped")
+            return
+
+        event_type = event.get("type")
+        if event_type == "message_start":
+            self._handle_message_start(event)
+        elif event_type == "content_block_start":
+            self._handle_content_block_start(event)
+        elif event_type == "content_block_delta":
+            self._handle_content_block_delta(event)
+        elif event_type == "message_delta":
+            self._handle_message_delta(event)
+        elif event_type == "error":
+            self._handle_error(event)
+        # message_stop, ping, content_block_stop: no action needed
+
+    def finalize(self) -> AnthropicUsageResult:
+        """Called when the stream ends. Returns accumulated usage.
+
+        Idempotent: caches the result on first call.
+        tool_calls_made is None when input_tokens is None (no message_start received).
+        """
+        if self._finalized_result is not None:
+            return self._finalized_result
+
+        self._finalized_result = AnthropicUsageResult(
+            input_tokens=self.input_tokens,
+            output_tokens=self.output_tokens,
+            cache_read_tokens=self.cache_read_tokens,
+            cache_creation_tokens=self.cache_creation_tokens,
+            thinking_tokens=self._thinking_chars // 4 if self._thinking_chars > 0 else None,
+            tool_calls_made=self._tool_call_count if self.input_tokens is not None else None,
+            raw_usage=dict(self._raw_usage_parts) if self._raw_usage_parts else None,
+            usage_source="provider_stream_final",
+            model_served=self.model_served,
+            response_id=self.response_id,
+            stop_reason=self.stop_reason,
+        )
+        return self._finalized_result
+
+    def apply_to_entry(self, entry: dict) -> None:
+        """Finalize and write accumulated streaming state to a log entry.
+
+        Does NOT set endpoint_family — that must be set by integration code.
+        """
+        self.finalize().apply_to_entry(entry)
+        if self.error_type is not None:
+            entry["error"] = True
+            entry["error_type"] = self.error_type
+
+    def _handle_message_start(self, event: dict) -> None:
+        message = event.get("message") or {}
+        self.model_served = message.get("model")
+        self.response_id = message.get("id")
+        usage = message.get("usage") or {}
+        self.input_tokens = usage.get("input_tokens")
+        self.cache_read_tokens = usage.get("cache_read_input_tokens", 0)
+        self.cache_creation_tokens = usage.get("cache_creation_input_tokens", 0)
+        self._raw_usage_parts["message_start"] = usage
+
+    def _handle_content_block_start(self, event: dict) -> None:
+        block = event.get("content_block") or {}
+        if block.get("type") == "tool_use":
+            self._tool_call_count += 1
+
+    def _handle_content_block_delta(self, event: dict) -> None:
+        delta = event.get("delta") or {}
+        if delta.get("type") == "thinking_delta":
+            self._thinking_chars += len(delta.get("thinking", ""))
+
+    def _handle_message_delta(self, event: dict) -> None:
+        """Note: Anthropic only sends cache tokens in message_start.
+        We intentionally skip cache token extraction from message_delta."""
+        usage = event.get("usage") or {}
+        if "output_tokens" in usage:
+            self.output_tokens = usage["output_tokens"]
+        self._raw_usage_parts["message_delta"] = usage
+        stop_reason = event.get("delta", {}).get("stop_reason")
+        if stop_reason is not None:
+            self.stop_reason = stop_reason
+
+    def _handle_error(self, event: dict) -> None:
+        error = event.get("error") or {}
+        self.error_type = error.get("type")
+        self.error_message = error.get("message")