tokenwise-sdk 0.1.1__py3-none-any.whl

tokenwise/__init__.py

@@ -0,0 +1,55 @@
+"""Tokenwise SDK — metadata-only usage tracking for Anthropic and OpenAI.
+
+Swap one import line to start capturing per-call token/latency metadata:
+
+    from tokenwise import Anthropic        # instead of: from anthropic import Anthropic
+    client = Anthropic(api_key="sk-ant-...")
+
+The wrappers expose the identical interface to the official SDKs and forward
+every call untouched. After each response, metadata only (model, token counts,
+latency) is shipped to Tokenwise on a background thread — never any prompt or
+response content. If Tokenwise is unreachable the SDK fails silently and your
+AI calls are unaffected.
+
+Configuration (env or constructor kwargs ``tokenwise_key`` / ``tokenwise_url``):
+    TOKENWISE_API_KEY, TOKENWISE_API_URL, TOKENWISE_DISABLED
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from tokenwise._version import __version__
+
+# Provider wrappers are resolved lazily so that `anthropic` and `openai` are
+# OPTIONAL dependencies: importing tokenwise never requires both to be present.
+_LAZY = {
+    "Anthropic": ("tokenwise.anthropic", "Anthropic"),
+    "AsyncAnthropic": ("tokenwise.anthropic", "AsyncAnthropic"),
+    "OpenAI": ("tokenwise.openai", "OpenAI"),
+    "AsyncOpenAI": ("tokenwise.openai", "AsyncOpenAI"),
+}
+
+__all__ = ["Anthropic", "AsyncAnthropic", "OpenAI", "AsyncOpenAI", "__version__"]
+
+if TYPE_CHECKING:  # for type checkers / IDEs only
+    from tokenwise.anthropic import Anthropic, AsyncAnthropic
+    from tokenwise.openai import AsyncOpenAI, OpenAI
+
+
+def __getattr__(name: str):
+    target = _LAZY.get(name)
+    if target is None:
+        raise AttributeError(f"module 'tokenwise' has no attribute {name!r}")
+    module_name, attr = target
+    import importlib
+
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as exc:  # the official provider SDK isn't installed
+        provider = "anthropic" if "anthropic" in module_name else "openai"
+        raise ImportError(
+            f"Using tokenwise.{name} requires the '{provider}' package. "
+            f"Install it with:  pip install tokenwise-sdk[{provider}]"
+        ) from exc
+    return getattr(module, attr)

tokenwise/_capture.py

@@ -0,0 +1,90 @@
+"""Metadata extraction helpers shared by the provider wrappers.
+
+Everything here reads ONLY token-usage and model fields off a response object.
+No function in this module reads message content, choices text, deltas' text,
+system prompts, or tool definitions.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from tokenwise.client import TokenwiseClient
+from tokenwise.event import UsageEvent
+
+logger = logging.getLogger("tokenwise")
+
+
+def now_iso() -> str:
+    """Current UTC time as ISO-8601 with a trailing Z."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _int(obj: Any, name: str, default: int = 0) -> int:
+    value = getattr(obj, name, None)
+    try:
+        return int(value) if value is not None else default
+    except (TypeError, ValueError):
+        return default
+
+
+def anthropic_usage_fields(model: str, usage: Any) -> dict:
+    """Pull metadata from an Anthropic ``Usage``/``MessageDeltaUsage`` object."""
+    return {
+        "model": model,
+        "input_tokens": _int(usage, "input_tokens"),
+        "output_tokens": _int(usage, "output_tokens"),
+        "cache_read_input_tokens": _int(usage, "cache_read_input_tokens"),
+        "cache_creation_input_tokens": _int(usage, "cache_creation_input_tokens"),
+    }
+
+
+def openai_usage_fields(model: str, usage: Any) -> dict:
+    """Pull metadata from an OpenAI ``CompletionUsage`` object."""
+    cached = 0
+    details = getattr(usage, "prompt_tokens_details", None)
+    if details is not None:
+        cached = _int(details, "cached_tokens")
+    return {
+        "model": model,
+        "input_tokens": _int(usage, "prompt_tokens"),
+        "output_tokens": _int(usage, "completion_tokens"),
+        "cache_read_input_tokens": cached,
+        # OpenAI has no cache-creation concept; always 0.
+        "cache_creation_input_tokens": 0,
+    }
+
+
+def make_event(
+    provider: str,
+    endpoint: str,
+    fields: dict,
+    latency_ms: int,
+    streamed: bool,
+) -> UsageEvent:
+    return UsageEvent(
+        provider=provider,
+        endpoint=endpoint,
+        model=str(fields.get("model") or "unknown"),
+        input_tokens=int(fields.get("input_tokens", 0)),
+        output_tokens=int(fields.get("output_tokens", 0)),
+        cache_read_input_tokens=int(fields.get("cache_read_input_tokens", 0)),
+        cache_creation_input_tokens=int(fields.get("cache_creation_input_tokens", 0)),
+        latency_ms=latency_ms,
+        timestamp=now_iso(),
+        streamed=streamed,
+    )
+
+
+def safe_capture(client: TokenwiseClient, event_factory) -> None:
+    """Build and enqueue an event, swallowing any error.
+
+    ``event_factory`` is a zero-arg callable returning a UsageEvent, so that any
+    failure in extraction is contained here and never reaches the caller.
+    """
+    try:
+        client.capture(event_factory())
+    except Exception:
+        logger.debug("tokenwise: capture skipped due to error", exc_info=True)

tokenwise/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version."""
+
+__version__ = "0.1.1"

tokenwise/anthropic.py

@@ -0,0 +1,226 @@
+"""Drop-in wrappers for the official ``anthropic`` SDK.
+
+``from tokenwise import Anthropic`` exposes the exact same interface as
+``anthropic.Anthropic``; only ``messages.create`` is instrumented. Every other
+attribute and method is delegated to the real client untouched, so any
+parameter the official SDK adds passes straight through.
+
+Streaming usage is captured transparently from the event stream
+(``message_start`` carries input/cache tokens; ``message_delta`` carries the
+final ``output_tokens``) — the caller's request is not modified.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from tokenwise import _capture as cap
+from tokenwise.client import get_client
+from tokenwise.config import resolve_config
+
+_PROVIDER = "anthropic"
+_ENDPOINT = "messages"
+
+
+def _new_real(async_: bool, args: tuple, kwargs: dict):
+    import anthropic  # imported lazily so `anthropic` is an optional dependency
+
+    cls = anthropic.AsyncAnthropic if async_ else anthropic.Anthropic
+    return cls(*args, **kwargs)
+
+
+# ── streaming proxies ──────────────────────────────────────────────────────────
+
+class _StreamAccumulator:
+    """Collects usage fields off Anthropic stream events. Reads no content."""
+
+    def __init__(self) -> None:
+        self.model = "unknown"
+        self.fields = {
+            "model": "unknown", "input_tokens": 0, "output_tokens": 0,
+            "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0,
+        }
+
+    def observe(self, event: Any) -> None:
+        # message_start: event.message has model + initial usage (input/cache).
+        message = getattr(event, "message", None)
+        if message is not None:
+            model = getattr(message, "model", None)
+            usage = getattr(message, "usage", None)
+            if usage is not None:
+                merged = cap.anthropic_usage_fields(model or self.fields["model"], usage)
+                # output_tokens in message_start is partial; keep our running value.
+                merged["output_tokens"] = self.fields["output_tokens"]
+                self.fields = merged
+        # message_delta: event.usage carries the final cumulative output_tokens.
+        usage = getattr(event, "usage", None)
+        if usage is not None and hasattr(usage, "output_tokens"):
+            self.fields["output_tokens"] = cap._int(usage, "output_tokens")
+
+
+class _SyncStreamProxy:
+    def __init__(self, stream: Any, tw, t0: float) -> None:
+        self._stream = stream
+        self._tw = tw
+        self._t0 = t0
+        self._acc = _StreamAccumulator()
+        self._done = False
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.__dict__["_stream"], name)
+
+    def __iter__(self):
+        try:
+            for event in self._stream:
+                self._acc.observe(event)
+                yield event
+        finally:
+            self._finish()
+
+    def __enter__(self):
+        self._stream.__enter__()
+        return self
+
+    def __exit__(self, *exc: Any):
+        try:
+            return self._stream.__exit__(*exc)
+        finally:
+            self._finish()
+
+    def _finish(self) -> None:
+        if self._done:
+            return
+        self._done = True
+        latency = int((time.perf_counter() - self._t0) * 1000)
+        cap.safe_capture(
+            self._tw,
+            lambda: cap.make_event(_PROVIDER, _ENDPOINT, self._acc.fields, latency, True),
+        )
+
+
+class _AsyncStreamProxy:
+    def __init__(self, stream: Any, tw, t0: float) -> None:
+        self._stream = stream
+        self._tw = tw
+        self._t0 = t0
+        self._acc = _StreamAccumulator()
+        self._done = False
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.__dict__["_stream"], name)
+
+    async def __aiter__(self):
+        try:
+            async for event in self._stream:
+                self._acc.observe(event)
+                yield event
+        finally:
+            self._finish()
+
+    async def __aenter__(self):
+        await self._stream.__aenter__()
+        return self
+
+    async def __aexit__(self, *exc: Any):
+        try:
+            return await self._stream.__aexit__(*exc)
+        finally:
+            self._finish()
+
+    def _finish(self) -> None:
+        if self._done:
+            return
+        self._done = True
+        latency = int((time.perf_counter() - self._t0) * 1000)
+        cap.safe_capture(
+            self._tw,
+            lambda: cap.make_event(_PROVIDER, _ENDPOINT, self._acc.fields, latency, True),
+        )
+
+
+# ── messages resource proxy ─────────────────────────────────────────────────────
+
+class _Messages:
+    def __init__(self, real: Any, tw, async_: bool) -> None:
+        self._real = real
+        self._tw = tw
+        self._async = async_
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.__dict__["_real"], name)
+
+    def create(self, *args: Any, **kwargs: Any):
+        if self._async:
+            return self._acreate(*args, **kwargs)
+        t0 = time.perf_counter()
+        result = self._real.create(*args, **kwargs)
+        if kwargs.get("stream"):
+            return _SyncStreamProxy(result, self._tw, t0)
+        latency = int((time.perf_counter() - t0) * 1000)
+        cap.safe_capture(
+            self._tw,
+            lambda: cap.make_event(
+                _PROVIDER, _ENDPOINT,
+                cap.anthropic_usage_fields(getattr(result, "model", "unknown"),
+                                           getattr(result, "usage", None)),
+                latency, False,
+            ),
+        )
+        return result
+
+    async def _acreate(self, *args: Any, **kwargs: Any):
+        t0 = time.perf_counter()
+        result = await self._real.create(*args, **kwargs)
+        if kwargs.get("stream"):
+            return _AsyncStreamProxy(result, self._tw, t0)
+        latency = int((time.perf_counter() - t0) * 1000)
+        cap.safe_capture(
+            self._tw,
+            lambda: cap.make_event(
+                _PROVIDER, _ENDPOINT,
+                cap.anthropic_usage_fields(getattr(result, "model", "unknown"),
+                                           getattr(result, "usage", None)),
+                latency, False,
+            ),
+        )
+        return result
+
+
+# ── top-level client wrappers ───────────────────────────────────────────────────
+
+class _BaseAnthropic:
+    _ASYNC = False
+
+    def __init__(
+        self,
+        *args: Any,
+        tokenwise_key: str | None = None,
+        tokenwise_url: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._client = _new_real(self._ASYNC, args, kwargs)
+        self._tw = get_client(resolve_config(tokenwise_key, tokenwise_url))
+        self._messages = _Messages(self._client.messages, self._tw, self._ASYNC)
+
+    @property
+    def messages(self) -> _Messages:
+        return self._messages
+
+    def __getattr__(self, name: str) -> Any:
+        client = self.__dict__.get("_client")
+        if client is None:
+            raise AttributeError(name)
+        return getattr(client, name)
+
+
+class Anthropic(_BaseAnthropic):
+    """Drop-in replacement for ``anthropic.Anthropic``."""
+
+    _ASYNC = False
+
+
+class AsyncAnthropic(_BaseAnthropic):
+    """Drop-in replacement for ``anthropic.AsyncAnthropic``."""
+
+    _ASYNC = True

tokenwise/client.py

@@ -0,0 +1,167 @@
+"""Internal client that buffers usage events and ships them in the background.
+
+Guarantees (all non-negotiable, see README):
+  * ``capture()`` never blocks the caller — it appends to an in-memory
+    ``deque`` under a short lock and returns immediately.
+  * If the Tokenwise API is slow or down, the caller's AI calls are unaffected;
+    sending happens only on a background daemon thread.
+  * The buffer is bounded at ``max_buffer`` events. ``deque(maxlen=...)`` drops
+    the OLDEST event silently when full — capture never raises, never waits.
+  * Failed sends are retried on the next flush; events are put back at the
+    front of the buffer (and may age out if the buffer keeps overflowing).
+
+A process-wide registry returns one shared client per (api_key, api_url) so
+that wrapping several SDK clients with the same key reuses one worker thread.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import threading
+from collections import deque
+from typing import TYPE_CHECKING
+
+from tokenwise.config import Config
+
+if TYPE_CHECKING:
+    from tokenwise.event import UsageEvent
+
+logger = logging.getLogger("tokenwise")
+
+
+class TokenwiseClient:
+    """Background, fail-silent shipper of :class:`UsageEvent` batches."""
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+        self._buffer: deque[UsageEvent] = deque(maxlen=config.max_buffer)
+        self._lock = threading.Lock()
+        self._wake = threading.Event()
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._http = None  # lazily created httpx.Client on the worker thread
+        self._started = False
+
+    # ── public ────────────────────────────────────────────────────────────────
+
+    def capture(self, event: UsageEvent) -> None:
+        """Enqueue an event. Never blocks, never raises."""
+        if not self._config.enabled:
+            return
+        try:
+            self._ensure_started()
+            with self._lock:
+                self._buffer.append(event)  # drops oldest if full (maxlen)
+            if len(self._buffer) >= self._config.batch_size:
+                self._wake.set()
+        except Exception:  # capture must never surface an error to the caller
+            logger.debug("tokenwise: capture failed (ignored)", exc_info=True)
+
+    def flush(self, timeout: float = 2.0) -> None:
+        """Best-effort synchronous flush (used by tests and atexit)."""
+        if not self._config.enabled:
+            return
+        self._ensure_started()
+        self._wake.set()
+        deadline = threading.Event()
+        # Poll until buffer drains or timeout elapses.
+        waited = 0.0
+        step = 0.05
+        while waited < timeout:
+            with self._lock:
+                if not self._buffer:
+                    return
+            deadline.wait(step)
+            waited += step
+
+    # ── lifecycle ───────────────────────────────────────────────────────────────
+
+    def _ensure_started(self) -> None:
+        if self._started:
+            return
+        with self._lock:
+            if self._started:
+                return
+            self._thread = threading.Thread(
+                target=self._run, name="tokenwise-worker", daemon=True
+            )
+            self._thread.start()
+            self._started = True
+            atexit.register(self._shutdown)
+
+    def _shutdown(self) -> None:
+        self._stop.set()
+        self._wake.set()
+        if self._thread is not None:
+            self._thread.join(timeout=self._config.http_timeout + 1.0)
+
+    # ── worker ──────────────────────────────────────────────────────────────────
+
+    def _run(self) -> None:
+        try:
+            import httpx
+
+            self._http = httpx.Client(timeout=self._config.http_timeout)
+        except Exception:
+            logger.debug("tokenwise: HTTP client unavailable; disabling sender",
+                         exc_info=True)
+            return
+
+        while not self._stop.is_set():
+            self._wake.wait(self._config.flush_interval)
+            self._wake.clear()
+            self._drain_and_send()
+
+        # Final drain on shutdown.
+        self._drain_and_send()
+        try:
+            self._http.close()
+        except Exception:
+            pass
+
+    def _drain_and_send(self) -> None:
+        while True:
+            with self._lock:
+                if not self._buffer:
+                    return
+                batch = []
+                for _ in range(min(self._config.batch_size, len(self._buffer))):
+                    batch.append(self._buffer.popleft())
+            if not self._send(batch):
+                # Re-queue at the front, preserving order; may age out if full.
+                with self._lock:
+                    self._buffer.extendleft(reversed(batch))
+                return  # back off until next flush cycle
+
+    def _send(self, batch: list[UsageEvent]) -> bool:
+        """POST a batch. Returns True on 2xx, False otherwise. Never raises."""
+        if self._http is None:
+            return False
+        try:
+            resp = self._http.post(
+                f"{self._config.api_url}/api/ingest/events",
+                json={"events": [e.to_dict() for e in batch]},
+                headers={"Authorization": f"Bearer {self._config.api_key}"},
+            )
+            return 200 <= resp.status_code < 300
+        except Exception:
+            logger.debug("tokenwise: send failed (will retry)", exc_info=True)
+            return False
+
+
+# ── process-wide registry ─────────────────────────────────────────────────────
+
+_registry: dict[tuple[str | None, str], TokenwiseClient] = {}
+_registry_lock = threading.Lock()
+
+
+def get_client(config: Config) -> TokenwiseClient:
+    """Return a shared client for this (api_key, api_url), creating one if needed."""
+    key = (config.api_key, config.api_url)
+    with _registry_lock:
+        client = _registry.get(key)
+        if client is None:
+            client = TokenwiseClient(config)
+            _registry[key] = client
+        return client

tokenwise/config.py

@@ -0,0 +1,66 @@
+"""Configuration resolution for the Tokenwise SDK.
+
+Precedence for every setting: explicit constructor argument > environment
+variable > built-in default.
+
+Environment variables:
+  TOKENWISE_API_KEY   Tokenwise ingest key (``tw_...``). Required to send
+                      events; if absent the SDK runs in disabled mode and
+                      the wrapped AI calls work exactly as normal.
+  TOKENWISE_API_URL   Base URL of the Tokenwise API
+                      (default ``https://tokenwise-production-aa59.up.railway.app``).
+  TOKENWISE_DISABLED  If set to a truthy value ("1", "true", "yes", "on"),
+                      a global kill switch that disables all capture.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+DEFAULT_API_URL = "https://tokenwise-production-aa59.up.railway.app"
+
+# Tuning constants — conservative defaults that keep the SDK invisible to the
+# host application. None of these ever block the caller's thread.
+DEFAULT_MAX_BUFFER = 1_000      # events retained when the API is unreachable
+DEFAULT_BATCH_SIZE = 50         # events per POST
+DEFAULT_FLUSH_INTERVAL = 1.0    # seconds between background flush attempts
+DEFAULT_HTTP_TIMEOUT = 5.0      # seconds; background only, never blocks caller
+
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def _env_truthy(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in _TRUTHY
+
+
+@dataclass(frozen=True)
+class Config:
+    """Resolved SDK configuration."""
+
+    api_key: str | None
+    api_url: str
+    disabled: bool
+    max_buffer: int = DEFAULT_MAX_BUFFER
+    batch_size: int = DEFAULT_BATCH_SIZE
+    flush_interval: float = DEFAULT_FLUSH_INTERVAL
+    http_timeout: float = DEFAULT_HTTP_TIMEOUT
+
+    @property
+    def enabled(self) -> bool:
+        """True only when capture should actually run."""
+        return not self.disabled and bool(self.api_key)
+
+
+def resolve_config(
+    api_key: str | None = None,
+    api_url: str | None = None,
+) -> Config:
+    """Build a :class:`Config` from explicit args, env vars, then defaults."""
+    key = api_key or os.environ.get("TOKENWISE_API_KEY") or None
+    url = api_url or os.environ.get("TOKENWISE_API_URL") or DEFAULT_API_URL
+    return Config(
+        api_key=key,
+        api_url=url.rstrip("/"),
+        disabled=_env_truthy("TOKENWISE_DISABLED"),
+    )

tokenwise/event.py

@@ -0,0 +1,31 @@
+"""The usage event — the SDK's privacy boundary.
+
+This dataclass is the ONLY thing the SDK ever transmits. It has fields for
+token counts and timing metadata and **deliberately no field anywhere for
+prompt text, response text, system prompts, tool definitions, or any other
+user content**. Capture code constructs one of these from a response's usage
+block; there is structurally nowhere to put content even by accident.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+
+@dataclass(frozen=True)
+class UsageEvent:
+    """Metadata-only record of a single AI API call."""
+
+    provider: str           # "anthropic" | "openai"
+    model: str
+    input_tokens: int
+    output_tokens: int
+    cache_read_input_tokens: int
+    cache_creation_input_tokens: int
+    latency_ms: int
+    timestamp: str          # ISO-8601 UTC, e.g. "2026-05-30T15:42:01Z"
+    endpoint: str           # "messages" | "chat.completions"
+    streamed: bool          # latency_ms is total stream duration when True
+
+    def to_dict(self) -> dict:
+        return asdict(self)

tokenwise/openai.py

@@ -0,0 +1,243 @@
+"""Drop-in wrappers for the official ``openai`` SDK.
+
+``from tokenwise import OpenAI`` exposes the exact same interface as
+``openai.OpenAI``; only ``chat.completions.create`` is instrumented. Everything
+else delegates to the real client untouched.
+
+Streaming nuance: OpenAI only returns ``usage`` on a streamed response when the
+request carries ``stream_options={"include_usage": True}``. Per product
+decision we inject that option **only when the caller did not supply their own
+``stream_options``**, and we parse the trailing usage-only chunk defensively
+(its ``choices`` list is empty — we never index into it).
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from tokenwise import _capture as cap
+from tokenwise.client import get_client
+from tokenwise.config import resolve_config
+
+_PROVIDER = "openai"
+_ENDPOINT = "chat.completions"
+
+
+def _new_real(async_: bool, args: tuple, kwargs: dict):
+    import openai  # lazy import → openai is an optional dependency
+
+    cls = openai.AsyncOpenAI if async_ else openai.OpenAI
+    return cls(*args, **kwargs)
+
+
+def _maybe_inject_usage(kwargs: dict) -> None:
+    """Add stream_options.include_usage only if the caller gave no stream_options."""
+    if kwargs.get("stream") and kwargs.get("stream_options") is None:
+        kwargs["stream_options"] = {"include_usage": True}
+
+
+class _StreamAccumulator:
+    """Collects model + usage off chat-completion chunks. Reads no content."""
+
+    def __init__(self) -> None:
+        self.model = "unknown"
+        self.usage = None
+
+    def observe(self, chunk: Any) -> None:
+        model = getattr(chunk, "model", None)
+        if model:
+            self.model = model
+        usage = getattr(chunk, "usage", None)  # None on all but the final chunk
+        if usage is not None:
+            self.usage = usage
+
+    def fields(self) -> dict:
+        if self.usage is None:
+            return {"model": self.model, "input_tokens": 0, "output_tokens": 0,
+                    "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}
+        return cap.openai_usage_fields(self.model, self.usage)
+
+
+class _SyncStreamProxy:
+    def __init__(self, stream: Any, tw, t0: float) -> None:
+        self._stream = stream
+        self._tw = tw
+        self._t0 = t0
+        self._acc = _StreamAccumulator()
+        self._done = False
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.__dict__["_stream"], name)
+
+    def __iter__(self):
+        try:
+            for chunk in self._stream:
+                self._acc.observe(chunk)
+                yield chunk
+        finally:
+            self._finish()
+
+    def __enter__(self):
+        self._stream.__enter__()
+        return self
+
+    def __exit__(self, *exc: Any):
+        try:
+            return self._stream.__exit__(*exc)
+        finally:
+            self._finish()
+
+    def _finish(self) -> None:
+        if self._done:
+            return
+        self._done = True
+        latency = int((time.perf_counter() - self._t0) * 1000)
+        cap.safe_capture(
+            self._tw,
+            lambda: cap.make_event(_PROVIDER, _ENDPOINT, self._acc.fields(), latency, True),
+        )
+
+
+class _AsyncStreamProxy:
+    def __init__(self, stream: Any, tw, t0: float) -> None:
+        self._stream = stream
+        self._tw = tw
+        self._t0 = t0
+        self._acc = _StreamAccumulator()
+        self._done = False
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.__dict__["_stream"], name)
+
+    async def __aiter__(self):
+        try:
+            async for chunk in self._stream:
+                self._acc.observe(chunk)
+                yield chunk
+        finally:
+            self._finish()
+
+    async def __aenter__(self):
+        await self._stream.__aenter__()
+        return self
+
+    async def __aexit__(self, *exc: Any):
+        try:
+            return await self._stream.__aexit__(*exc)
+        finally:
+            self._finish()
+
+    def _finish(self) -> None:
+        if self._done:
+            return
+        self._done = True
+        latency = int((time.perf_counter() - self._t0) * 1000)
+        cap.safe_capture(
+            self._tw,
+            lambda: cap.make_event(_PROVIDER, _ENDPOINT, self._acc.fields(), latency, True),
+        )
+
+
+# ── resource proxies: client.chat.completions.create ────────────────────────────
+
+class _Completions:
+    def __init__(self, real: Any, tw, async_: bool) -> None:
+        self._real = real
+        self._tw = tw
+        self._async = async_
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.__dict__["_real"], name)
+
+    def create(self, *args: Any, **kwargs: Any):
+        if self._async:
+            return self._acreate(*args, **kwargs)
+        streaming = bool(kwargs.get("stream"))
+        if streaming:
+            _maybe_inject_usage(kwargs)
+        t0 = time.perf_counter()
+        result = self._real.create(*args, **kwargs)
+        if streaming:
+            return _SyncStreamProxy(result, self._tw, t0)
+        latency = int((time.perf_counter() - t0) * 1000)
+        cap.safe_capture(
+            self._tw,
+            lambda: cap.make_event(
+                _PROVIDER, _ENDPOINT,
+                cap.openai_usage_fields(getattr(result, "model", "unknown"),
+                                        getattr(result, "usage", None)),
+                latency, False,
+            ),
+        )
+        return result
+
+    async def _acreate(self, *args: Any, **kwargs: Any):
+        streaming = bool(kwargs.get("stream"))
+        if streaming:
+            _maybe_inject_usage(kwargs)
+        t0 = time.perf_counter()
+        result = await self._real.create(*args, **kwargs)
+        if streaming:
+            return _AsyncStreamProxy(result, self._tw, t0)
+        latency = int((time.perf_counter() - t0) * 1000)
+        cap.safe_capture(
+            self._tw,
+            lambda: cap.make_event(
+                _PROVIDER, _ENDPOINT,
+                cap.openai_usage_fields(getattr(result, "model", "unknown"),
+                                        getattr(result, "usage", None)),
+                latency, False,
+            ),
+        )
+        return result
+
+
+class _Chat:
+    def __init__(self, real: Any, tw, async_: bool) -> None:
+        self._real = real
+        self._completions = _Completions(real.completions, tw, async_)
+
+    @property
+    def completions(self) -> _Completions:
+        return self._completions
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.__dict__["_real"], name)
+
+
+class _BaseOpenAI:
+    _ASYNC = False
+
+    def __init__(
+        self,
+        *args: Any,
+        tokenwise_key: str | None = None,
+        tokenwise_url: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._client = _new_real(self._ASYNC, args, kwargs)
+        self._tw = get_client(resolve_config(tokenwise_key, tokenwise_url))
+        self._chat = _Chat(self._client.chat, self._tw, self._ASYNC)
+
+    @property
+    def chat(self) -> _Chat:
+        return self._chat
+
+    def __getattr__(self, name: str) -> Any:
+        client = self.__dict__.get("_client")
+        if client is None:
+            raise AttributeError(name)
+        return getattr(client, name)
+
+
+class OpenAI(_BaseOpenAI):
+    """Drop-in replacement for ``openai.OpenAI``."""
+
+    _ASYNC = False
+
+
+class AsyncOpenAI(_BaseOpenAI):
+    """Drop-in replacement for ``openai.AsyncOpenAI``."""
+
+    _ASYNC = True

tokenwise_sdk-0.1.1.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: tokenwise-sdk
+Version: 0.1.1
+Summary: Metadata-only usage tracking for Anthropic and OpenAI — swap one import line.
+Project-URL: Homepage, https://tokenwise.io
+Project-URL: Documentation, https://docs.tokenwise.io
+Author: Tokenwise
+License: MIT
+Keywords: anthropic,cost,llm,observability,openai,tokens,usage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.23
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.40; extra == 'dev'
+Requires-Dist: openai>=1.40; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Tokenwise Python SDK
+
+Metadata-only usage tracking for Anthropic and OpenAI. Swap **one import line**
+and every API call's token counts and latency flow to your Tokenwise dashboard
+— with **zero access to your prompts or responses**.
+
+```diff
+- from anthropic import Anthropic
++ from tokenwise import Anthropic
+```
+
+Your code is otherwise unchanged: the wrapper exposes the identical interface,
+forwards every call to the official SDK, and returns its response untouched.
+
+## Why it's safe
+
+- **Metadata only.** The SDK reads exactly: `model`, `input_tokens`,
+  `output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens`,
+  `latency_ms`, `timestamp`, `endpoint`. It never reads or transmits prompt
+  text, response text, system prompts, or tool definitions. (Contrast with
+  proxy-based tools, which see all your traffic.)
+- **Non-blocking.** Events are queued and sent on a background daemon thread.
+  If Tokenwise is slow or down, your AI calls complete normally.
+- **Fail-silent + bounded.** Up to 1,000 events buffer when offline; the oldest
+  drop silently if the buffer fills. Capture never raises, never waits.
+
+## Install
+
+```bash
+pip install tokenwise-sdk[anthropic]   # if you use Anthropic
+pip install tokenwise-sdk[openai]      # if you use OpenAI
+pip install tokenwise-sdk[anthropic,openai]
+```
+
+`anthropic` and `openai` are optional extras — install only what you use.
+
+## Configure
+
+Set your Tokenwise key (from the dashboard, looks like `tw_...`):
+
+```bash
+export TOKENWISE_API_KEY=tw_your_key
+# optional:
+export TOKENWISE_API_URL=https://tokenwise-production-aa59.up.railway.app   # default
+export TOKENWISE_DISABLED=true                       # emergency kill switch
+```
+
+Precedence for every setting: constructor argument > environment variable >
+default. If no key is configured the SDK runs disabled and your AI calls behave
+exactly as the official SDK.
+
+## Usage
+
+```python
+# Pattern 1 — key from environment
+import os
+os.environ["TOKENWISE_API_KEY"] = "tw_abc123"
+from tokenwise import Anthropic
+client = Anthropic(api_key="sk-ant-...")
+msg = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=256,
+    messages=[{"role": "user", "content": "Hello"}],
+)
+
+# Pattern 2 — key passed explicitly
+from tokenwise import Anthropic
+client = Anthropic(api_key="sk-ant-...", tokenwise_key="tw_abc123")
+
+# Pattern 3 — OpenAI
+from tokenwise import OpenAI
+client = OpenAI(api_key="sk-...", tokenwise_key="tw_abc123")
+client.chat.completions.create(
+    model="gpt-5.4",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+Streaming and async work the same way:
+
+```python
+# Streaming (sync) — usage captured on stream completion
+with client.messages.create(..., stream=True) as stream:
+    for event in stream:
+        ...
+
+# Async
+from tokenwise import AsyncAnthropic
+client = AsyncAnthropic(api_key="sk-ant-...", tokenwise_key="tw_abc123")
+msg = await client.messages.create(...)
+```
+
+## What's instrumented (v1)
+
+| Provider | Method | Streaming |
+|----------|--------|-----------|
+| Anthropic | `messages.create` | ✅ usage read from the event stream (request unchanged) |
+| OpenAI | `chat.completions.create` | ✅ see note below |
+
+Other methods pass through and work, but aren't yet recorded. (OpenAI Responses
+API and legacy completions are planned.)
+
+### Note on OpenAI streaming
+
+OpenAI only returns token usage on a streamed response when the request includes
+`stream_options={"include_usage": True}`. When you stream **without** supplying
+your own `stream_options`, Tokenwise injects it for you so usage can be captured.
+This adds one final usage-only chunk (with an empty `choices` list) to the
+stream. If you already pass `stream_options`, Tokenwise respects yours and does
+not modify the request (in that case usage is captured only if you enabled it).
+
+### Latency semantics
+
+For non-streaming calls, `latency_ms` is the wall-clock time of the call. For
+streaming calls it is the **total stream duration** (until the last chunk is
+consumed), which includes time your code spends between chunks — events from
+streaming calls carry `streamed: true` so this is distinguishable.
+
+## License
+
+MIT

tokenwise_sdk-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+tokenwise/__init__.py,sha256=6mqEA1o9s3Tx8vautqX1d7psARfzjzt10CxAFqqbU9I,2234
+tokenwise/_capture.py,sha256=GFYUqeKSjl2fIQgvVPR7OinO3xkpvTDlGK0w0uI3e38,3073
+tokenwise/_version.py,sha256=1fcON3TaH_saTfQzv-QWlGmS61oADXGsc-A7KNbVS4Y,80
+tokenwise/anthropic.py,sha256=Grjf5RhB8wKnWWYMP-FIKAkLGJ2sxA_PjvJyJyskIS8,7811
+tokenwise/client.py,sha256=Hi4PLZFzSFP4p0pWZMaFljgYC1295Xp7GANU1kkF0m4,6719
+tokenwise/config.py,sha256=m-tXSxpvZC_SQrGVdYG4VHXIxQ99S7QtbsrWYTydtM4,2397
+tokenwise/event.py,sha256=82PSQFb63qqBd8h8cTNBj2bl8v0tSUaqgNgulW0v8wA,1111
+tokenwise/openai.py,sha256=L_D7G9fdyl140gSqjpY8FBpaTHJt9wkt3BXKyAcxv60,7725
+tokenwise_sdk-0.1.1.dist-info/METADATA,sha256=_m8sVPdOrSxT0PhlR8dzUQdWMW18F8kuEBLvLJiLJto,5248
+tokenwise_sdk-0.1.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tokenwise_sdk-0.1.1.dist-info/RECORD,,

tokenwise_sdk-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any