costkey 0.1.0__tar.gz

costkey-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.venv/
+venv/

costkey-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: costkey
+Version: 0.1.0
+Summary: Sentry for AI costs. Track every LLM call's cost, tokens, and latency with one line of code.
+Project-URL: Homepage, https://costkey.dev
+Project-URL: Repository, https://github.com/costkey/costkey-python
+Project-URL: Documentation, https://github.com/costkey/costkey-python
+Author-email: CostKey <hello@costkey.dev>
+License-Expression: MIT
+Keywords: ai,anthropic,cost,gemini,llm,observability,openai,tracking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Description-Content-Type: text/markdown
+
+# costkey
+
+> Sentry for AI costs. Track every LLM call's cost, tokens, and latency with one line of code.
+
+## Install
+
+```bash
+pip install costkey
+```
+
+## Quick Start
+
+```python
+import costkey
+
+costkey.init(dsn="https://ck_your_key@costkey.dev/your-project")
+
+# That's it. Every AI call is now tracked automatically.
+# Works with OpenAI, Anthropic, Google Gemini, Azure OpenAI.
+```
+
+## How It Works
+
+CostKey patches `httpx` and `requests` — the HTTP clients that every AI SDK uses under the hood. When your code calls any AI provider, CostKey automatically:
+
+1. **Detects** the AI provider from the URL
+2. **Extracts** token usage from the response
+3. **Captures** a stack trace (which function, which file, which line)
+4. **Computes** cost using built-in pricing for 30+ models
+5. **Ships** the event to your CostKey dashboard (async, non-blocking)
+
+## Tracing
+
+```python
+with costkey.start_trace(name="POST /api/search"):
+    intent = classify_intent(query)
+    results = search(query)
+    summary = summarize(results)
+# All 3 AI calls grouped under one trace
+```
+
+## Manual Context
+
+```python
+with costkey.with_context(task="summarize", team="search"):
+    response = openai.chat.completions.create(...)
+```
+
+## Privacy
+
+- Never captures API keys — request headers are never read
+- Auto-scrubs credentials from request/response bodies
+- `before_send` hook for custom PII scrubbing
+
+## License
+
+MIT

costkey-0.1.0/README.md

@@ -0,0 +1,57 @@
+# costkey
+
+> Sentry for AI costs. Track every LLM call's cost, tokens, and latency with one line of code.
+
+## Install
+
+```bash
+pip install costkey
+```
+
+## Quick Start
+
+```python
+import costkey
+
+costkey.init(dsn="https://ck_your_key@costkey.dev/your-project")
+
+# That's it. Every AI call is now tracked automatically.
+# Works with OpenAI, Anthropic, Google Gemini, Azure OpenAI.
+```
+
+## How It Works
+
+CostKey patches `httpx` and `requests` — the HTTP clients that every AI SDK uses under the hood. When your code calls any AI provider, CostKey automatically:
+
+1. **Detects** the AI provider from the URL
+2. **Extracts** token usage from the response
+3. **Captures** a stack trace (which function, which file, which line)
+4. **Computes** cost using built-in pricing for 30+ models
+5. **Ships** the event to your CostKey dashboard (async, non-blocking)
+
+## Tracing
+
+```python
+with costkey.start_trace(name="POST /api/search"):
+    intent = classify_intent(query)
+    results = search(query)
+    summary = summarize(results)
+# All 3 AI calls grouped under one trace
+```
+
+## Manual Context
+
+```python
+with costkey.with_context(task="summarize", team="search"):
+    response = openai.chat.completions.create(...)
+```
+
+## Privacy
+
+- Never captures API keys — request headers are never read
+- Auto-scrubs credentials from request/response bodies
+- `before_send` hook for custom PII scrubbing
+
+## License
+
+MIT

costkey-0.1.0/costkey/__init__.py

@@ -0,0 +1,13 @@
+from costkey.client import init, shutdown, flush, with_context, start_trace
+from costkey.client import register_extractor, register_pricing
+
+__version__ = "0.1.0"
+__all__ = [
+    "init",
+    "shutdown",
+    "flush",
+    "with_context",
+    "start_trace",
+    "register_extractor",
+    "register_pricing",
+]

costkey-0.1.0/costkey/client.py

@@ -0,0 +1,136 @@
+"""CostKey Python SDK — Sentry for AI costs."""
+from __future__ import annotations
+import uuid
+import logging
+from contextlib import contextmanager
+from contextvars import copy_context
+from typing import Any, Callable, Generator
+from costkey.types import CostKeyOptions, CostKeyEvent
+from costkey.transport import Transport
+from costkey.patch import patch, unpatch, _context, set_context, get_context
+from costkey.providers import register_extractor as _register_extractor
+from costkey.pricing import register_pricing as _register_pricing
+
+logger = logging.getLogger("costkey")
+
+_transport: Transport | None = None
+_initialized = False
+
+
+def _parse_dsn(dsn: str) -> tuple[str, str, str]:
+    """Parse DSN → (endpoint, auth_key, project_id)."""
+    from urllib.parse import urlparse
+    parsed = urlparse(dsn)
+    auth_key = parsed.username or ""
+    if not auth_key:
+        raise ValueError(f"[costkey] DSN missing auth key: {dsn}")
+    project_id = parsed.path.lstrip("/")
+    if not project_id:
+        raise ValueError(f"[costkey] DSN missing project ID: {dsn}")
+    endpoint = f"{parsed.scheme}://{parsed.hostname}"
+    if parsed.port:
+        endpoint += f":{parsed.port}"
+    endpoint += "/api/v1/events"
+    return endpoint, auth_key, project_id
+
+
+def init(dsn: str, *, capture_body: bool = True,
+         before_send: Callable[[CostKeyEvent], CostKeyEvent | None] | None = None,
+         max_batch_size: int = 50, flush_interval: float = 5.0,
+         debug: bool = False, default_context: dict[str, Any] | None = None) -> None:
+    """
+    Initialize CostKey. Call once at app startup.
+
+    >>> import costkey
+    >>> costkey.init(dsn="https://ck_abc123@costkey.dev/my-project")
+    >>> # That's it. Every AI call is now tracked.
+    """
+    global _transport, _initialized
+
+    if _initialized:
+        if debug:
+            logger.warning("[costkey] Already initialized, skipping")
+        return
+
+    endpoint, auth_key, project_id = _parse_dsn(dsn)
+
+    _transport = Transport(
+        endpoint=endpoint, auth_key=auth_key,
+        max_batch_size=max_batch_size, flush_interval=flush_interval,
+        debug=debug,
+    )
+
+    patch(
+        transport=_transport, project_id=project_id,
+        capture_body=capture_body, before_send=before_send,
+        default_context=default_context or {}, debug=debug,
+    )
+
+    _transport.start()
+    _initialized = True
+
+    if debug:
+        logger.info(f"[costkey] Initialized for project {project_id}")
+
+
+# Alias for MLflow familiarity
+autolog = init
+
+
+def shutdown() -> None:
+    """Flush pending events and restore original HTTP clients."""
+    global _transport, _initialized
+    if _transport:
+        _transport.flush()
+        _transport.stop()
+        _transport = None
+    unpatch()
+    _initialized = False
+
+
+def flush() -> None:
+    """Flush all pending events without shutting down."""
+    if _transport:
+        _transport.flush()
+
+
+@contextmanager
+def with_context(**kwargs: Any) -> Generator[None, None, None]:
+    """
+    Tag AI calls with custom context.
+
+    >>> with costkey.with_context(task="summarize", team="search"):
+    ...     openai.chat.completions.create(...)
+    """
+    parent = get_context()
+    merged = {**parent, **kwargs}
+    token = _context.set(merged)
+    try:
+        yield
+    finally:
+        _context.reset(token)
+
+
+@contextmanager
+def start_trace(name: str | None = None, trace_id: str | None = None) -> Generator[None, None, None]:
+    """
+    Start a trace. All AI calls inside are grouped under one trace ID.
+
+    >>> with costkey.start_trace(name="POST /api/search"):
+    ...     classify_intent(query)
+    ...     results = search(query)
+    ...     summary = summarize(results)
+    """
+    tid = trace_id or uuid.uuid4().hex
+    with with_context(traceId=tid, traceName=name):
+        yield
+
+
+def register_extractor(extractor: Any) -> None:
+    """Register a custom provider extractor."""
+    _register_extractor(extractor)
+
+
+def register_pricing(model: str, input_per_1m: float, output_per_1m: float, **kwargs: Any) -> None:
+    """Register custom model pricing."""
+    _register_pricing(model, input_per_1m, output_per_1m, **kwargs)

costkey-0.1.0/costkey/patch.py

@@ -0,0 +1,285 @@
+"""Monkey-patch HTTP clients to intercept AI provider calls."""
+from __future__ import annotations
+import json
+import time
+import uuid
+import re
+import logging
+from contextvars import ContextVar
+from typing import Any, Callable
+from costkey.types import CostKeyEvent, NormalizedUsage, Provider
+from costkey.providers import find_extractor
+from costkey.stack import capture_call_site
+from costkey.pricing import compute_cost
+from costkey.transport import Transport
+
+logger = logging.getLogger("costkey")
+
+# Context var for tracing / manual context
+_context: ContextVar[dict[str, Any]] = ContextVar("costkey_context", default={})
+
+# Secret patterns to scrub from bodies
+_SECRET_PATTERNS = [
+    re.compile(r"^sk-[a-zA-Z0-9]{20,}$"),
+    re.compile(r"^sk-ant-[a-zA-Z0-9\-]{20,}$"),
+    re.compile(r"^AIza[a-zA-Z0-9_\-]{30,}$"),
+    re.compile(r"^Bearer\s+.{20,}$"),
+    re.compile(r"^eyJ[a-zA-Z0-9_\-]{20,}"),
+]
+_SECRET_KEYS = frozenset({
+    "api_key", "apikey", "api-key", "secret", "secret_key",
+    "token", "access_token", "refresh_token", "password",
+    "authorization", "auth", "private_key",
+})
+
+
+def _scrub(obj: Any) -> Any:
+    if obj is None:
+        return None
+    if isinstance(obj, str):
+        for pat in _SECRET_PATTERNS:
+            if pat.match(obj):
+                return "[REDACTED]"
+        return obj
+    if isinstance(obj, list):
+        return [_scrub(item) for item in obj]
+    if isinstance(obj, dict):
+        return {
+            k: "[REDACTED]" if k.lower() in _SECRET_KEYS else _scrub(v)
+            for k, v in obj.items()
+        }
+    return obj
+
+
+class _PatchState:
+    def __init__(self) -> None:
+        self.transport: Transport | None = None
+        self.project_id: str = ""
+        self.capture_body: bool = True
+        self.before_send: Callable | None = None
+        self.default_context: dict[str, Any] = {}
+        self.debug: bool = False
+        self._original_httpx_send: Any = None
+        self._original_httpx_async_send: Any = None
+        self._original_requests_send: Any = None
+        self.patched = False
+
+
+_state = _PatchState()
+
+
+def patch(transport: Transport, project_id: str, capture_body: bool,
+          before_send: Callable | None, default_context: dict[str, Any], debug: bool) -> None:
+    if _state.patched:
+        return
+
+    _state.transport = transport
+    _state.project_id = project_id
+    _state.capture_body = capture_body
+    _state.before_send = before_send
+    _state.default_context = default_context
+    _state.debug = debug
+
+    _patch_httpx()
+    _patch_requests()
+    _state.patched = True
+
+
+def unpatch() -> None:
+    _unpatch_httpx()
+    _unpatch_requests()
+    _state.patched = False
+
+
+def _patch_httpx() -> None:
+    try:
+        import httpx
+
+        _state._original_httpx_send = httpx.Client.send
+
+        def patched_send(self: Any, request: Any, **kwargs: Any) -> Any:
+            url = str(request.url)
+            extractor = find_extractor(url)
+
+            if not extractor:
+                return _state._original_httpx_send(self, request, **kwargs)
+
+            call_site = capture_call_site()
+            ctx = {**_state.default_context, **_context.get()}
+            start = time.perf_counter()
+
+            request_body = None
+            if request.content:
+                try:
+                    request_body = json.loads(request.content)
+                except Exception:
+                    pass
+
+            response = _state._original_httpx_send(self, request, **kwargs)
+            duration_ms = (time.perf_counter() - start) * 1000
+
+            try:
+                response_body = response.json()
+            except Exception:
+                response_body = None
+
+            _process(extractor, url, request.method, response.status_code,
+                     request_body, response_body, duration_ms, call_site, ctx)
+
+            return response
+
+        httpx.Client.send = patched_send
+
+        # Also patch async client
+        _state._original_httpx_async_send = httpx.AsyncClient.send
+
+        async def patched_async_send(self: Any, request: Any, **kwargs: Any) -> Any:
+            url = str(request.url)
+            extractor = find_extractor(url)
+
+            if not extractor:
+                return await _state._original_httpx_async_send(self, request, **kwargs)
+
+            call_site = capture_call_site()
+            ctx = {**_state.default_context, **_context.get()}
+            start = time.perf_counter()
+
+            request_body = None
+            if request.content:
+                try:
+                    request_body = json.loads(request.content)
+                except Exception:
+                    pass
+
+            response = await _state._original_httpx_async_send(self, request, **kwargs)
+            duration_ms = (time.perf_counter() - start) * 1000
+
+            try:
+                response_body = response.json()
+            except Exception:
+                response_body = None
+
+            _process(extractor, url, request.method, response.status_code,
+                     request_body, response_body, duration_ms, call_site, ctx)
+
+            return response
+
+        httpx.AsyncClient.send = patched_async_send
+
+    except ImportError:
+        if _state.debug:
+            logger.debug("[costkey] httpx not installed, skipping patch")
+
+
+def _unpatch_httpx() -> None:
+    try:
+        import httpx
+        if _state._original_httpx_send:
+            httpx.Client.send = _state._original_httpx_send
+        if _state._original_httpx_async_send:
+            httpx.AsyncClient.send = _state._original_httpx_async_send
+    except ImportError:
+        pass
+
+
+def _patch_requests() -> None:
+    try:
+        import requests
+
+        _state._original_requests_send = requests.Session.send
+
+        def patched_send(self: Any, request: Any, **kwargs: Any) -> Any:
+            url = str(request.url)
+            extractor = find_extractor(url)
+
+            if not extractor:
+                return _state._original_requests_send(self, request, **kwargs)
+
+            call_site = capture_call_site()
+            ctx = {**_state.default_context, **_context.get()}
+            start = time.perf_counter()
+
+            request_body = None
+            if request.body:
+                try:
+                    request_body = json.loads(request.body)
+                except Exception:
+                    pass
+
+            response = _state._original_requests_send(self, request, **kwargs)
+            duration_ms = (time.perf_counter() - start) * 1000
+
+            try:
+                response_body = response.json()
+            except Exception:
+                response_body = None
+
+            _process(extractor, url, request.method, response.status_code,
+                     request_body, response_body, duration_ms, call_site, ctx)
+
+            return response
+
+        requests.Session.send = patched_send
+
+    except ImportError:
+        if _state.debug:
+            logger.debug("[costkey] requests not installed, skipping patch")
+
+
+def _unpatch_requests() -> None:
+    try:
+        import requests
+        if _state._original_requests_send:
+            requests.Session.send = _state._original_requests_send
+    except ImportError:
+        pass
+
+
+def _process(extractor: Any, url: str, method: str, status_code: int | None,
+             request_body: Any, response_body: Any,
+             duration_ms: float, call_site: Any, ctx: dict[str, Any]) -> None:
+    try:
+        usage = extractor.extract_usage(response_body) if response_body else None
+        model = extractor.extract_model(request_body, response_body)
+        cost_usd = compute_cost(model, usage) if model and usage else None
+
+        event = CostKeyEvent(
+            id=uuid.uuid4().hex,
+            timestamp=time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime()),
+            project_id=_state.project_id,
+            provider=extractor.provider,
+            model=model,
+            url=url,
+            method=method,
+            status_code=status_code,
+            usage=usage,
+            cost_usd=cost_usd,
+            duration_ms=round(duration_ms, 2),
+            streaming=False,
+            call_site=call_site,
+            context=ctx,
+            request_body=_scrub(request_body) if _state.capture_body else None,
+            response_body=_scrub(response_body) if _state.capture_body else None,
+        )
+
+        if _state.before_send:
+            try:
+                event = _state.before_send(event)
+            except Exception:
+                if _state.debug:
+                    logger.warning("[costkey] before_send threw, dropping event")
+                return
+
+        if event and _state.transport:
+            _state.transport.enqueue(event)
+    except Exception:
+        if _state.debug:
+            logger.warning("[costkey] Error processing event", exc_info=True)
+
+
+def get_context() -> dict[str, Any]:
+    return _context.get()
+
+
+def set_context(ctx: dict[str, Any]) -> None:
+    _context.set(ctx)

costkey-0.1.0/costkey/pricing.py

@@ -0,0 +1,65 @@
+"""Model pricing — cost per 1M tokens in USD."""
+from __future__ import annotations
+from costkey.types import NormalizedUsage
+
+# (input_per_1M, output_per_1M, cache_read_per_1M, cache_write_per_1M)
+_PRICING: dict[str, tuple[float, float, float | None, float | None]] = {
+    "gpt-4o": (2.5, 10, None, None),
+    "gpt-4o-mini": (0.15, 0.6, None, None),
+    "gpt-4-turbo": (10, 30, None, None),
+    "gpt-4": (30, 60, None, None),
+    "gpt-3.5-turbo": (0.5, 1.5, None, None),
+    "o1": (15, 60, None, None),
+    "o1-mini": (3, 12, None, None),
+    "o3": (10, 40, None, None),
+    "o3-mini": (1.1, 4.4, None, None),
+    "o4-mini": (1.1, 4.4, None, None),
+    "claude-opus-4-0-20250514": (15, 75, 1.5, 18.75),
+    "claude-sonnet-4-0-20250514": (3, 15, 0.3, 3.75),
+    "claude-sonnet-4-5-20250514": (3, 15, 0.3, 3.75),
+    "claude-haiku-3-5-20241022": (0.8, 4, 0.08, 1),
+    "claude-3-5-sonnet-20241022": (3, 15, 0.3, 3.75),
+    "claude-3-opus-20240229": (15, 75, 1.5, 18.75),
+    "gemini-2.0-flash": (0.1, 0.4, None, None),
+    "gemini-2.0-flash-lite": (0.02, 0.1, None, None),
+    "gemini-1.5-pro": (1.25, 5, None, None),
+    "gemini-1.5-flash": (0.075, 0.3, None, None),
+    "gemini-2.5-pro": (1.25, 10, None, None),
+    "gemini-2.5-flash": (0.15, 0.6, None, None),
+}
+
+
+def _find_pricing(model: str) -> tuple[float, float, float | None, float | None] | None:
+    if model in _PRICING:
+        return _PRICING[model]
+    parts = model.split("-")
+    for i in range(len(parts) - 1, 0, -1):
+        prefix = "-".join(parts[:i])
+        if prefix in _PRICING:
+            return _PRICING[prefix]
+    return None
+
+
+def compute_cost(model: str, usage: NormalizedUsage) -> float | None:
+    pricing = _find_pricing(model)
+    if pricing is None:
+        return None
+
+    inp, out, cache_r, cache_w = pricing
+    cost = 0.0
+    if usage.input_tokens is not None:
+        cost += (usage.input_tokens / 1_000_000) * inp
+    if usage.output_tokens is not None:
+        cost += (usage.output_tokens / 1_000_000) * out
+    if usage.cache_read_tokens is not None and cache_r is not None:
+        cost += (usage.cache_read_tokens / 1_000_000) * cache_r
+    if usage.cache_creation_tokens is not None and cache_w is not None:
+        cost += (usage.cache_creation_tokens / 1_000_000) * cache_w
+
+    return round(cost, 6)
+
+
+def register_pricing(model: str, input_per_1m: float, output_per_1m: float,
+                      cache_read_per_1m: float | None = None,
+                      cache_write_per_1m: float | None = None) -> None:
+    _PRICING[model] = (input_per_1m, output_per_1m, cache_read_per_1m, cache_write_per_1m)

costkey-0.1.0/costkey/providers.py

@@ -0,0 +1,133 @@
+"""Provider extractors — detect AI providers by URL and extract usage from responses."""
+from __future__ import annotations
+from urllib.parse import urlparse
+from typing import Any, Protocol
+from costkey.types import Provider, NormalizedUsage
+
+
+class ProviderExtractor(Protocol):
+    provider: Provider
+    def match(self, url: str) -> bool: ...
+    def extract_usage(self, body: Any) -> NormalizedUsage | None: ...
+    def extract_model(self, request_body: Any, response_body: Any) -> str | None: ...
+
+
+def _as_int(val: Any) -> int | None:
+    if isinstance(val, (int, float)) and not isinstance(val, bool):
+        return int(val)
+    return None
+
+
+class OpenAIExtractor:
+    provider = Provider.OPENAI
+
+    def match(self, url: str) -> bool:
+        host = urlparse(url).hostname or ""
+        return host == "api.openai.com" or host.endswith(".openai.azure.com")
+
+    def extract_usage(self, body: Any) -> NormalizedUsage | None:
+        if not isinstance(body, dict):
+            return None
+        usage = body.get("usage")
+        if not isinstance(usage, dict):
+            return None
+
+        input_t = _as_int(usage.get("prompt_tokens")) or _as_int(usage.get("input_tokens"))
+        output_t = _as_int(usage.get("completion_tokens")) or _as_int(usage.get("output_tokens"))
+        total_t = _as_int(usage.get("total_tokens"))
+        if total_t is None and input_t is not None and output_t is not None:
+            total_t = input_t + output_t
+
+        details = usage.get("completion_tokens_details") or usage.get("output_tokens_details") or {}
+        reasoning = _as_int(details.get("reasoning_tokens")) if isinstance(details, dict) else None
+
+        return NormalizedUsage(
+            input_tokens=input_t, output_tokens=output_t, total_tokens=total_t,
+            reasoning_tokens=reasoning,
+        )
+
+    def extract_model(self, request_body: Any, response_body: Any) -> str | None:
+        if isinstance(response_body, dict) and isinstance(response_body.get("model"), str):
+            return response_body["model"]
+        if isinstance(request_body, dict) and isinstance(request_body.get("model"), str):
+            return request_body["model"]
+        return None
+
+
+class AnthropicExtractor:
+    provider = Provider.ANTHROPIC
+
+    def match(self, url: str) -> bool:
+        host = urlparse(url).hostname or ""
+        return host == "api.anthropic.com"
+
+    def extract_usage(self, body: Any) -> NormalizedUsage | None:
+        if not isinstance(body, dict):
+            return None
+        usage = body.get("usage")
+        if not isinstance(usage, dict):
+            return None
+
+        input_t = _as_int(usage.get("input_tokens"))
+        output_t = _as_int(usage.get("output_tokens"))
+        total_t = (input_t or 0) + (output_t or 0) if input_t is not None or output_t is not None else None
+
+        return NormalizedUsage(
+            input_tokens=input_t, output_tokens=output_t, total_tokens=total_t,
+            cache_read_tokens=_as_int(usage.get("cache_read_input_tokens")),
+            cache_creation_tokens=_as_int(usage.get("cache_creation_input_tokens")),
+        )
+
+    def extract_model(self, request_body: Any, response_body: Any) -> str | None:
+        if isinstance(response_body, dict) and isinstance(response_body.get("model"), str):
+            return response_body["model"]
+        if isinstance(request_body, dict) and isinstance(request_body.get("model"), str):
+            return request_body["model"]
+        return None
+
+
+class GoogleExtractor:
+    provider = Provider.GOOGLE
+
+    def match(self, url: str) -> bool:
+        host = urlparse(url).hostname or ""
+        return host == "generativelanguage.googleapis.com" or host.endswith("-aiplatform.googleapis.com")
+
+    def extract_usage(self, body: Any) -> NormalizedUsage | None:
+        if not isinstance(body, dict):
+            return None
+        meta = body.get("usageMetadata")
+        if not isinstance(meta, dict):
+            return None
+
+        input_t = _as_int(meta.get("promptTokenCount"))
+        output_t = _as_int(meta.get("candidatesTokenCount"))
+        total_t = _as_int(meta.get("totalTokenCount"))
+        if total_t is None and input_t is not None and output_t is not None:
+            total_t = input_t + output_t
+
+        return NormalizedUsage(
+            input_tokens=input_t, output_tokens=output_t, total_tokens=total_t,
+            reasoning_tokens=_as_int(meta.get("thoughtsTokenCount")),
+            cache_read_tokens=_as_int(meta.get("cachedContentTokenCount")),
+        )
+
+    def extract_model(self, request_body: Any, response_body: Any) -> str | None:
+        if isinstance(response_body, dict) and isinstance(response_body.get("modelVersion"), str):
+            return response_body["modelVersion"]
+        return None
+
+
+# Registry
+_extractors: list[ProviderExtractor] = [OpenAIExtractor(), AnthropicExtractor(), GoogleExtractor()]
+
+
+def find_extractor(url: str) -> ProviderExtractor | None:
+    for ext in _extractors:
+        if ext.match(url):
+            return ext
+    return None
+
+
+def register_extractor(extractor: ProviderExtractor) -> None:
+    _extractors.append(extractor)

costkey-0.1.0/costkey/stack.py

@@ -0,0 +1,45 @@
+"""Stack trace capture — auto-attribute AI calls to code."""
+from __future__ import annotations
+import traceback
+from costkey.types import CallSite, StackFrame
+
+_INTERNAL = ("costkey/", "site-packages/costkey")
+
+
+def capture_call_site() -> CallSite | None:
+    raw = traceback.format_stack()
+    frames: list[StackFrame] = []
+
+    for line in reversed(raw):
+        line = line.strip()
+        if not line.startswith("File "):
+            continue
+        # Parse: File "path", line N, in func
+        parts = line.split(", ")
+        if len(parts) < 3:
+            continue
+
+        file_name = parts[0].replace('File "', "").rstrip('"')
+        if any(p in file_name for p in _INTERNAL):
+            continue
+
+        line_num = None
+        func_name = None
+        for p in parts[1:]:
+            if p.startswith("line "):
+                try:
+                    line_num = int(p.replace("line ", ""))
+                except ValueError:
+                    pass
+            elif p.startswith("in "):
+                func_name = p.replace("in ", "").strip()
+
+        frames.append(StackFrame(
+            function_name=func_name,
+            file_name=file_name,
+            line_number=line_num,
+        ))
+
+    if not frames:
+        return None
+    return CallSite(raw="".join(raw), frames=frames)

costkey-0.1.0/costkey/transport.py

@@ -0,0 +1,127 @@
+"""Batched async transport — ships events to costkey.dev. Never blocks. Never throws."""
+from __future__ import annotations
+import json
+import threading
+import logging
+from typing import Any
+import httpx
+from costkey.types import CostKeyEvent
+
+logger = logging.getLogger("costkey")
+
+
+class Transport:
+    def __init__(self, endpoint: str, auth_key: str, max_batch_size: int,
+                 flush_interval: float, debug: bool):
+        self._endpoint = endpoint
+        self._auth_key = auth_key
+        self._max_batch_size = max_batch_size
+        self._flush_interval = flush_interval
+        self._debug = debug
+        self._queue: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._timer: threading.Timer | None = None
+        self._max_queue = 500
+
+    def start(self) -> None:
+        self._schedule_flush()
+
+    def stop(self) -> None:
+        if self._timer:
+            self._timer.cancel()
+            self._timer = None
+
+    def enqueue(self, event: CostKeyEvent) -> None:
+        with self._lock:
+            if len(self._queue) >= self._max_queue:
+                self._queue.pop(0)
+                if self._debug:
+                    logger.warning("[costkey] Queue full, dropping oldest event")
+
+            self._queue.append(self._serialize(event))
+
+            if len(self._queue) >= self._max_batch_size:
+                self._do_flush()
+
+    def flush(self) -> None:
+        with self._lock:
+            self._do_flush()
+
+    def _schedule_flush(self) -> None:
+        self._timer = threading.Timer(self._flush_interval, self._tick)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _tick(self) -> None:
+        with self._lock:
+            self._do_flush()
+        self._schedule_flush()
+
+    def _do_flush(self) -> None:
+        if not self._queue:
+            return
+
+        batch = self._queue[:self._max_batch_size]
+        self._queue = self._queue[self._max_batch_size:]
+
+        payload = {"sdkVersion": "python-0.1.0", "events": batch}
+
+        try:
+            resp = httpx.post(
+                self._endpoint,
+                json=payload,
+                headers={
+                    "Authorization": f"Bearer {self._auth_key}",
+                    "User-Agent": "costkey-python/0.1.0",
+                },
+                timeout=10,
+            )
+            if resp.status_code == 429:
+                self._queue = batch + self._queue
+                if self._debug:
+                    logger.warning("[costkey] Rate limited, will retry")
+            elif not resp.is_success and self._debug:
+                logger.warning(f"[costkey] Ingest returned {resp.status_code}")
+        except Exception as e:
+            if self._debug:
+                logger.warning(f"[costkey] Failed to send events: {e}")
+
+    def _serialize(self, event: CostKeyEvent) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "id": event.id,
+            "timestamp": event.timestamp,
+            "projectId": event.project_id,
+            "provider": event.provider.value,
+            "model": event.model,
+            "url": event.url,
+            "method": event.method,
+            "statusCode": event.status_code,
+            "usage": None,
+            "costUsd": event.cost_usd,
+            "durationMs": event.duration_ms,
+            "streaming": event.streaming,
+            "streamTiming": None,
+            "callSite": None,
+            "context": event.context,
+            "requestBody": event.request_body,
+            "responseBody": event.response_body,
+        }
+        if event.usage:
+            d["usage"] = {
+                "inputTokens": event.usage.input_tokens,
+                "outputTokens": event.usage.output_tokens,
+                "totalTokens": event.usage.total_tokens,
+                "reasoningTokens": event.usage.reasoning_tokens,
+                "cacheReadTokens": event.usage.cache_read_tokens,
+                "cacheCreationTokens": event.usage.cache_creation_tokens,
+            }
+        if event.call_site:
+            d["callSite"] = {
+                "raw": event.call_site.raw,
+                "frames": [
+                    {"functionName": f.function_name, "fileName": f.file_name,
+                     "lineNumber": f.line_number, "columnNumber": None}
+                    for f in event.call_site.frames
+                ],
+            }
+        return d

costkey-0.1.0/costkey/types.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable, Optional
+
+
+class Provider(str, Enum):
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    GOOGLE = "google"
+    AZURE = "azure"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class NormalizedUsage:
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    total_tokens: int | None = None
+    reasoning_tokens: int | None = None
+    cache_read_tokens: int | None = None
+    cache_creation_tokens: int | None = None
+
+
+@dataclass
+class StackFrame:
+    function_name: str | None = None
+    file_name: str | None = None
+    line_number: int | None = None
+
+
+@dataclass
+class CallSite:
+    raw: str = ""
+    frames: list[StackFrame] = field(default_factory=list)
+
+
+@dataclass
+class StreamTiming:
+    ttft: float | None = None
+    tps: float | None = None
+    stream_duration: float | None = None
+    chunk_count: int = 0
+
+
+@dataclass
+class CostKeyEvent:
+    id: str = ""
+    timestamp: str = ""
+    project_id: str = ""
+    provider: Provider = Provider.UNKNOWN
+    model: str | None = None
+    url: str = ""
+    method: str = "POST"
+    status_code: int | None = None
+    usage: NormalizedUsage | None = None
+    cost_usd: float | None = None
+    duration_ms: float = 0
+    streaming: bool = False
+    stream_timing: StreamTiming | None = None
+    call_site: CallSite | None = None
+    context: dict[str, Any] = field(default_factory=dict)
+    request_body: Any = None
+    response_body: Any = None
+
+
+@dataclass
+class CostKeyOptions:
+    dsn: str = ""
+    capture_body: bool = True
+    before_send: Callable[[CostKeyEvent], CostKeyEvent | None] | None = None
+    max_batch_size: int = 50
+    flush_interval: float = 5.0
+    debug: bool = False
+    default_context: dict[str, Any] = field(default_factory=dict)

costkey-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "costkey"
+version = "0.1.0"
+description = "Sentry for AI costs. Track every LLM call's cost, tokens, and latency with one line of code."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "CostKey", email = "hello@costkey.dev" }]
+keywords = ["ai", "llm", "cost", "tracking", "observability", "openai", "anthropic", "gemini"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.urls]
+Homepage = "https://costkey.dev"
+Repository = "https://github.com/costkey/costkey-python"
+Documentation = "https://github.com/costkey/costkey-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["costkey"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]