tokensor 0.1.0__tar.gz

tokensor-0.1.0/.env.example

@@ -0,0 +1,2 @@
+TOKENSOR_API_KEY=ts_your_key_here
+TOKENSOR_HOST=https://api.tokensor.com

tokensor-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.coverage
+htmlcov/
+*.egg-info/
+dist/
+build/
+.env
+*.log

tokensor-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,66 @@
+# 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/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "tokensor"
+version = "0.1.0"
+description = "LLM token observability SDK — wraps OpenAI and Anthropic clients to capture metadata"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [
+    { name = "Tokensor", email = "hello@tokensor.com" },
+]
+keywords = ["llm", "observability", "openai", "anthropic", "tokens", "cost"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.28",
+]
+
+[project.urls]
+Homepage = "https://tokensor.com"
+Repository = "https://github.com/tokensor/tokensor"
+"Bug Tracker" = "https://github.com/tokensor/tokensor/issues"
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+anthropic = ["anthropic>=0.30"]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=6.0",
+    "openai>=1.0",
+    "anthropic>=0.30",
+    "respx>=0.21",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tokensor"]

tokensor-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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