tokensor 0.1.0__py3-none-any.whl

tokensor/__init__.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+from typing import Any
+
+from tokensor._config import load_config
+from tokensor._client import TokensorClient
+from tokensor._adapters._openai import WrappedOpenAI, WrappedAsyncOpenAI
+from tokensor._adapters._anthropic import WrappedAnthropic, WrappedAsyncAnthropic
+
+_OPENAI_NAMES = {"OpenAI", "AzureOpenAI"}
+_ASYNC_OPENAI_NAMES = {"AsyncOpenAI", "AsyncAzureOpenAI"}
+_ANTHROPIC_NAMES = {"Anthropic"}
+_ASYNC_ANTHROPIC_NAMES = {"AsyncAnthropic"}
+
+
+def wrap(
+    client: Any,
+    *,
+    api_key: str | None = None,
+    host: str | None = None,
+    provider: str | None = None,
+    _async: bool = False,
+) -> Any:
+    """Wrap an OpenAI or Anthropic client to capture LLM call metadata.
+
+    Args:
+        client: An openai.OpenAI, openai.AsyncOpenAI, anthropic.Anthropic,
+                or anthropic.AsyncAnthropic instance.
+        api_key: Tokensor API key. Falls back to TOKENSOR_API_KEY env var.
+        host: Tokensor API host. Falls back to TOKENSOR_HOST env var or default.
+        provider: "openai" or "anthropic". Auto-detected from class name if omitted.
+        _async: Force async wrapper. Usually auto-detected from class name.
+
+    Returns:
+        A wrapped client with the same interface as the original.
+    """
+    config = load_config(api_key=api_key, host=host)
+    tokensor_client = TokensorClient(config)
+
+    class_name = type(client).__name__
+
+    resolved_provider = provider
+    resolved_async = _async
+
+    if resolved_provider is None:
+        if class_name in _OPENAI_NAMES:
+            resolved_provider = "openai"
+        elif class_name in _ASYNC_OPENAI_NAMES:
+            resolved_provider = "openai"
+            resolved_async = True
+        elif class_name in _ANTHROPIC_NAMES:
+            resolved_provider = "anthropic"
+        elif class_name in _ASYNC_ANTHROPIC_NAMES:
+            resolved_provider = "anthropic"
+            resolved_async = True
+        else:
+            tokensor_client.shutdown()
+            raise ValueError(
+                f"Cannot detect provider from class '{class_name}'. "
+                "Pass provider='openai' or provider='anthropic' explicitly."
+            )
+
+    if resolved_provider == "openai":
+        if resolved_async:
+            return WrappedAsyncOpenAI(client, tokensor_client)
+        return WrappedOpenAI(client, tokensor_client)
+    elif resolved_provider == "anthropic":
+        if resolved_async:
+            return WrappedAsyncAnthropic(client, tokensor_client)
+        return WrappedAnthropic(client, tokensor_client)
+    else:
+        tokensor_client.shutdown()
+        raise ValueError(f"Unknown provider '{resolved_provider}'. Use 'openai' or 'anthropic'.")

tokensor/_adapters/_anthropic.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+from tokensor._client import TokensorClient
+from tokensor._hash import endpoint_hash
+from tokensor._models import EventPayload
+
+
+def _record_message(
+    tokensor_client: TokensorClient,
+    h: str,
+    model: str,
+    messages: list | None,
+    max_tokens: int | None,
+    called_at: datetime,
+    start: float,
+    response: Any | None,
+    exc: Exception | None,
+) -> None:
+    if response is not None:
+        status_code: int | None = 200
+        input_tokens = getattr(response.usage, "input_tokens", 0) or 0
+        output_tokens = getattr(response.usage, "output_tokens", 0) or 0
+        cache_creation_tokens = getattr(response.usage, "cache_creation_input_tokens", 0) or 0
+        cache_read_tokens = getattr(response.usage, "cache_read_input_tokens", 0) or 0
+        finish_reason = getattr(response, "stop_reason", None)
+    else:
+        status_code = getattr(exc, "status_code", None)
+        input_tokens = 0
+        output_tokens = 0
+        cache_creation_tokens = 0
+        cache_read_tokens = 0
+        finish_reason = None
+
+    latency_ms = int((time.monotonic() - start) * 1000)
+    event = EventPayload(
+        called_at=called_at,
+        model=model,
+        endpoint_hash=h,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cache_creation_tokens=cache_creation_tokens,
+        cache_read_tokens=cache_read_tokens,
+        message_count=len(messages) if messages is not None else None,
+        max_tokens=max_tokens,
+        finish_reason=finish_reason,
+        latency_ms=latency_ms,
+        status_code=status_code,
+    )
+    tokensor_client.enqueue(event)
+
+
+class _Messages:
+    def __init__(self, original_messages, tokensor_client: TokensorClient) -> None:
+        self._messages = original_messages
+        self._tokensor = tokensor_client
+
+    def create(self, model: str, messages: list | None = None, max_tokens: int | None = None, **kwargs) -> Any:
+        h = endpoint_hash(depth=2)
+        start = time.monotonic()
+        called_at = datetime.now(timezone.utc)
+        response, exc_to_raise = None, None
+        try:
+            response = self._messages.create(
+                model=model, messages=messages, max_tokens=max_tokens, **kwargs
+            )
+        except Exception as e:
+            exc_to_raise = e
+        _record_message(self._tokensor, h, model, messages, max_tokens, called_at, start, response, exc_to_raise)
+        if exc_to_raise is not None:
+            raise exc_to_raise
+        return response
+
+
+class _AsyncMessages:
+    def __init__(self, original_messages, tokensor_client: TokensorClient) -> None:
+        self._messages = original_messages
+        self._tokensor = tokensor_client
+
+    async def create(self, model: str, messages: list | None = None, max_tokens: int | None = None, **kwargs) -> Any:
+        h = endpoint_hash(depth=2)
+        start = time.monotonic()
+        called_at = datetime.now(timezone.utc)
+        response, exc_to_raise = None, None
+        try:
+            response = await self._messages.create(
+                model=model, messages=messages, max_tokens=max_tokens, **kwargs
+            )
+        except Exception as e:
+            exc_to_raise = e
+        _record_message(self._tokensor, h, model, messages, max_tokens, called_at, start, response, exc_to_raise)
+        if exc_to_raise is not None:
+            raise exc_to_raise
+        return response
+
+
+class WrappedAnthropic:
+    """Wraps anthropic.Anthropic to capture call metadata."""
+
+    def __init__(self, client: Any, tokensor_client: TokensorClient) -> None:
+        self._client = client
+        self._tokensor = tokensor_client
+        self.messages = _Messages(client.messages, tokensor_client)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)
+
+
+class WrappedAsyncAnthropic:
+    """Wraps anthropic.AsyncAnthropic to capture call metadata."""
+
+    def __init__(self, client: Any, tokensor_client: TokensorClient) -> None:
+        self._client = client
+        self._tokensor = tokensor_client
+        self.messages = _AsyncMessages(client.messages, tokensor_client)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)

tokensor/_adapters/_openai.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+from tokensor._client import TokensorClient
+from tokensor._hash import endpoint_hash
+from tokensor._models import EventPayload
+
+
+def _record_completion(
+    tokensor_client: TokensorClient,
+    h: str,
+    model: str,
+    messages: list | None,
+    max_tokens: int | None,
+    called_at: datetime,
+    start: float,
+    response: Any | None,
+    exc: Exception | None,
+) -> None:
+    if response is not None:
+        status_code: int | None = 200
+        input_tokens = getattr(response.usage, "prompt_tokens", 0) or 0
+        output_tokens = getattr(response.usage, "completion_tokens", 0) or 0
+        finish_reason = (
+            getattr(response.choices[0], "finish_reason", None) if response.choices else None
+        )
+    else:
+        status_code = getattr(exc, "status_code", None)
+        input_tokens = 0
+        output_tokens = 0
+        finish_reason = None
+
+    latency_ms = int((time.monotonic() - start) * 1000)
+    event = EventPayload(
+        called_at=called_at,
+        model=model,
+        endpoint_hash=h,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        message_count=len(messages) if messages is not None else None,
+        max_tokens=max_tokens,
+        finish_reason=finish_reason,
+        latency_ms=latency_ms,
+        status_code=status_code,
+    )
+    tokensor_client.enqueue(event)
+
+
+class _ChatCompletions:
+    def __init__(self, original_chat, tokensor_client: TokensorClient) -> None:
+        self._chat = original_chat
+        self._tokensor = tokensor_client
+
+    @property
+    def completions(self):
+        return self
+
+    def create(self, model: str, messages: list | None = None, max_tokens: int | None = None, **kwargs) -> Any:
+        h = endpoint_hash(depth=2)
+        start = time.monotonic()
+        called_at = datetime.now(timezone.utc)
+        response, exc_to_raise = None, None
+        try:
+            response = self._chat.completions.create(
+                model=model, messages=messages, max_tokens=max_tokens, **kwargs
+            )
+        except Exception as e:
+            exc_to_raise = e
+        _record_completion(self._tokensor, h, model, messages, max_tokens, called_at, start, response, exc_to_raise)
+        if exc_to_raise is not None:
+            raise exc_to_raise
+        return response
+
+
+class _AsyncChatCompletions:
+    def __init__(self, original_chat, tokensor_client: TokensorClient) -> None:
+        self._chat = original_chat
+        self._tokensor = tokensor_client
+
+    @property
+    def completions(self):
+        return self
+
+    async def create(self, model: str, messages: list | None = None, max_tokens: int | None = None, **kwargs) -> Any:
+        h = endpoint_hash(depth=2)
+        start = time.monotonic()
+        called_at = datetime.now(timezone.utc)
+        response, exc_to_raise = None, None
+        try:
+            response = await self._chat.completions.create(
+                model=model, messages=messages, max_tokens=max_tokens, **kwargs
+            )
+        except Exception as e:
+            exc_to_raise = e
+        _record_completion(self._tokensor, h, model, messages, max_tokens, called_at, start, response, exc_to_raise)
+        if exc_to_raise is not None:
+            raise exc_to_raise
+        return response
+
+
+class WrappedOpenAI:
+    """Wraps openai.OpenAI to capture call metadata."""
+
+    def __init__(self, client: Any, tokensor_client: TokensorClient) -> None:
+        self._client = client
+        self._tokensor = tokensor_client
+        self.chat = _ChatCompletions(client.chat, tokensor_client)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)
+
+
+class WrappedAsyncOpenAI:
+    """Wraps openai.AsyncOpenAI to capture call metadata."""
+
+    def __init__(self, client: Any, tokensor_client: TokensorClient) -> None:
+        self._client = client
+        self._tokensor = tokensor_client
+        self.chat = _AsyncChatCompletions(client.chat, tokensor_client)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)

tokensor/_client.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+import functools
+import logging
+import queue
+import threading
+import time
+from typing import Callable, TypeVar
+
+import httpx
+
+from tokensor._config import TokensorConfig
+from tokensor._models import EventPayload, events_to_batch_payload
+
+logger = logging.getLogger("tokensor")
+
+_SENTINEL = object()
+_MAX_RETRIES = 3
+_RETRY_DELAYS = (0.5, 1.0, 2.0)
+
+F = TypeVar("F", bound=Callable)
+
+
+def _retryable(max_retries: int = _MAX_RETRIES, delays: tuple = _RETRY_DELAYS) -> Callable[[F], F]:
+    """Decorator: retry on httpx errors or 5xx responses; discard permanently on 4xx."""
+    def decorator(fn: F) -> F:
+        @functools.wraps(fn)
+        def wrapper(self, events: list[EventPayload]) -> None:
+            for attempt in range(max_retries):
+                try:
+                    result = fn(self, events)
+                    if result is not None and result < 500:
+                        return  # success or permanent 4xx (already logged inside fn)
+                    if result is not None:
+                        # 5xx — fall through to retry
+                        logger.warning(
+                            "Tokensor: server error %d for %d events (attempt %d/%d)",
+                            result, len(events), attempt + 1, max_retries,
+                        )
+                except Exception as exc:
+                    logger.warning(
+                        "Tokensor: network error sending %d events (attempt %d/%d): %s",
+                        len(events), attempt + 1, max_retries, exc,
+                    )
+
+                if attempt < max_retries - 1:
+                    time.sleep(delays[attempt])
+
+            logger.error(
+                "Tokensor: permanently dropping %d events after %d retries",
+                len(events), max_retries,
+            )
+        return wrapper  # type: ignore[return-value]
+    return decorator
+
+
+class TokensorClient:
+    """HTTP sender with a background batch queue thread."""
+
+    def __init__(self, config: TokensorConfig) -> None:
+        self._config = config
+        self._queue: queue.Queue = queue.Queue()
+        self._stop_event = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def __enter__(self) -> "TokensorClient":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.shutdown()
+
+    def enqueue(self, event: EventPayload) -> None:
+        """Add event to the batch queue. Returns immediately."""
+        self._queue.put_nowait(event)
+
+    def shutdown(self) -> None:
+        """Signal the background thread to stop, flush remaining events, and wait."""
+        self._stop_event.set()
+        self._queue.put_nowait(_SENTINEL)  # Wake the thread if it's blocked on get()
+        self._thread.join(timeout=10)
+
+    def _run(self) -> None:
+        batch: list[EventPayload] = []
+        deadline = time.monotonic() + self._config.flush_interval
+
+        while True:
+            timeout = max(0.001, deadline - time.monotonic())
+            try:
+                item = self._queue.get(timeout=timeout)
+            except queue.Empty:
+                # flush_interval elapsed — send whatever we have
+                if batch:
+                    self._send(batch)
+                    batch = []
+                deadline = time.monotonic() + self._config.flush_interval
+                continue
+
+            if item is _SENTINEL:
+                # Drain any remaining items enqueued before shutdown
+                try:
+                    while True:
+                        item2 = self._queue.get_nowait()
+                        if item2 is not _SENTINEL:
+                            batch.append(item2)
+                except queue.Empty:
+                    pass
+                if batch:
+                    self._send(batch)
+                break
+
+            batch.append(item)
+            if len(batch) >= self._config.batch_size:
+                self._send(batch)
+                batch = []
+                deadline = time.monotonic() + self._config.flush_interval
+
+    @_retryable()
+    def _send(self, events: list[EventPayload]) -> int | None:
+        """POST a batch to the API. Returns status_code; decorator handles retries."""
+        resp = httpx.post(
+            f"{self._config.host}/v1/events/batch",
+            json=events_to_batch_payload(events),
+            headers={"X-Tokensor-Key": self._config.api_key},
+            timeout=5.0,
+        )
+        if 400 <= resp.status_code < 500:
+            logger.error(
+                "Tokensor: dropping %d events — server rejected with %d",
+                len(events), resp.status_code,
+            )
+        return resp.status_code

tokensor/_config.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class TokensorConfig:
+    api_key: str
+    host: str = "https://api.tokensor.com"
+    batch_size: int = 50
+    flush_interval: float = 2.0
+
+
+def load_config(
+    api_key: str | None = None,
+    host: str | None = None,
+    batch_size: int | None = None,
+    flush_interval: float | None = None,
+) -> TokensorConfig:
+    resolved_key = api_key or os.environ.get("TOKENSOR_API_KEY")
+    if not resolved_key:
+        raise ValueError(
+            "Tokensor API key is required. Pass api_key= or set TOKENSOR_API_KEY environment variable."
+        )
+    return TokensorConfig(
+        api_key=resolved_key,
+        host=host if host is not None else os.environ.get("TOKENSOR_HOST", "https://api.tokensor.com"),
+        batch_size=batch_size if batch_size is not None else int(os.environ.get("TOKENSOR_BATCH_SIZE", "50")),
+        flush_interval=flush_interval if flush_interval is not None else float(os.environ.get("TOKENSOR_FLUSH_INTERVAL", "2.0")),
+    )

tokensor/_hash.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+import hashlib
+import inspect
+
+
+def endpoint_hash(depth: int = 2) -> str:
+    """Return a SHA256 hex string identifying the call site at `depth` frames up.
+
+    Uses the function's first line number (co_firstlineno) so the hash is stable
+    across multiple calls from the same function, regardless of which line within
+    the function makes the LLM call.
+
+    depth=0: endpoint_hash itself (rarely useful)
+    depth=1: the direct caller of this function
+    depth=2: the caller's caller (default — identifies the user's call site)
+    """
+    frame = inspect.currentframe()
+    try:
+        target = frame
+        for _ in range(depth):
+            if target.f_back is None:
+                break
+            target = target.f_back
+        key = (
+            f"{target.f_code.co_filename}:"
+            f"{target.f_code.co_name}:"
+            f"{target.f_code.co_firstlineno}"
+        )
+    finally:
+        del frame
+
+    return hashlib.sha256(key.encode()).hexdigest()

tokensor/_models.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+from dataclasses import dataclass, asdict
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class EventPayload:
+    called_at: datetime
+    model: str
+    endpoint_hash: str
+    input_tokens: int
+    output_tokens: int
+    cache_creation_tokens: int = 0
+    cache_read_tokens: int = 0
+    message_count: int | None = None
+    max_tokens: int | None = None
+    finish_reason: str | None = None
+    latency_ms: int | None = None
+    status_code: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["called_at"] = self.called_at.isoformat()
+        return d
+
+
+def events_to_batch_payload(events: list[EventPayload]) -> dict[str, Any]:
+    return {"events": [e.to_dict() for e in events]}

tokensor-0.1.0.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: tokensor
+Version: 0.1.0
+Summary: LLM token observability SDK — wraps OpenAI and Anthropic clients to capture metadata
+Project-URL: Homepage, https://tokensor.com
+Project-URL: Repository, https://github.com/tokensor/tokensor
+Project-URL: Bug Tracker, https://github.com/tokensor/tokensor/issues
+Author-email: Tokensor <hello@tokensor.com>
+License: MIT
+Keywords: anthropic,cost,llm,observability,openai,tokens
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.28
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.30; extra == 'dev'
+Requires-Dist: openai>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# tokensor
+
+LLM token observability for Python. Wraps your OpenAI or Anthropic client to capture call metadata (model, tokens, cost) and forward it to your Tokensor dashboard — one line of code, zero latency overhead.
+
+## Install
+
+```bash
+pip install tokensor
+# With OpenAI support:
+pip install "tokensor[openai]"
+# With Anthropic support:
+pip install "tokensor[anthropic]"
+```
+
+## Quickstart
+
+Get your API key from [app.tokensor.com](https://app.tokensor.com) → Settings → API Keys.
+
+**OpenAI:**
+
+```python
+import os
+import openai
+import tokensor
+
+client = tokensor.wrap(
+    openai.OpenAI(),
+    api_key=os.environ["TOKENSOR_API_KEY"],
+)
+
+# Use exactly like openai.OpenAI()
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+**Anthropic:**
+
+```python
+import os
+import anthropic
+import tokensor
+
+client = tokensor.wrap(
+    anthropic.Anthropic(),
+    api_key=os.environ["TOKENSOR_API_KEY"],
+)
+
+message = client.messages.create(
+    model="claude-3-5-haiku-latest",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `TOKENSOR_API_KEY` | yes | Your Tokensor API key |
+| `TOKENSOR_HOST` | no | Override API host (default: `https://api.tokensor.com`) |
+
+## License
+
+MIT

tokensor-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+tokensor/__init__.py,sha256=hKbYWcvB9a2AO_RoY7Eki9XWkaCU-Hk7qOM1nQZ9f84,2680
+tokensor/_client.py,sha256=FmSw2rAKij_9QjD80Fn9Qnmx94RuOVWQwFKXooubLig,4721
+tokensor/_config.py,sha256=ZfLj2igjKpl2H4qj2ELx4vybXLMQUkzlfM_DMOOb6qE,1046
+tokensor/_hash.py,sha256=u2vSyuMxJExI-RTKCmB_GkYQ1puDvqTqmdPOp2UY1Ts,1011
+tokensor/_models.py,sha256=IINuudIUIF9n3Y0A6j-eLwFePx1iRbbqEHhnJbPtOMI,779
+tokensor/_adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tokensor/_adapters/_anthropic.py,sha256=uwy_ze4BG31MwWzgLPOonYXnNKUlYfwehS_dgD9v0m4,4304
+tokensor/_adapters/_openai.py,sha256=1wBVy4OFkmXm3_iQ_54spk-kisWzjBtJ55z1yJoWU-s,4151
+tokensor-0.1.0.dist-info/METADATA,sha256=iJHcqN8Y73AE_8CrYD7yNfiSZSwDOa2H26Zya3jku-g,2820
+tokensor-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tokensor-0.1.0.dist-info/RECORD,,

tokensor-0.1.0.dist-info/WHEEL

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