opentoken-sdk 0.1.0__tar.gz

opentoken_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: opentoken-sdk
+Version: 0.1.0
+Summary: OpenToken Python SDK
+Author-email: Nicole Chen <nchen55555@gmail.com>
+License: MIT
+Project-URL: Homepage, https://opentoken.bid
+Keywords: observability,llm,openai,anthropic,gemini,tokens,usage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: agents
+Requires-Dist: openai-agents>=0.17; extra == "agents"
+Provides-Extra: live
+Requires-Dist: openai-agents>=0.17; extra == "live"
+Requires-Dist: openai>=1.0; extra == "live"
+
+# Open Token Python SDK
+
+## Using `UsageReporter` directly
+
+If you want to report usage from any provider, use `UsageReporter` directly:
+
+```python
+from opentoken import UsageReporter
+
+reporter = UsageReporter(
+    open_token_api_key=os.environ["OPENTOKEN_API_KEY"],
+    tags={"service": "checkout-api", "env": "prod"},
+    batch=True,   # default; set False to POST one event at a time
+)
+
+response = your_provider_client.chat.completions.create(...)
+reporter.report_usage(response=response, latency_ms=..., tags={"workflow_id": "..."})
+```
+
+`report_usage(...)` enqueues the report on a bounded in-memory queue and
+returns immediately (~microseconds on the caller's thread). A background
+daemon thread drains the queue and POSTs to `/v1/usage:batch`. You don't
+manage the thread — it's started lazily on your first call and dies with
+the process.
+
+## OpenAI Agents SDK integration
+
+If you're using the OpenAI Agents SDK, register the tracing bridge once at
+startup and every `Runner.run(...)` will forward its LLM spans to
+OpenToken. You never call `report_usage` yourself.
+
+```python
+from opentoken import UsageReporter, with_tags
+from opentoken.integrations.agents import register_trace
+from agents import Agent, Runner
+
+# One-time setup — static tags apply to every event this reporter sends.
+reporter = UsageReporter(open_token_api_key=..., tags={"env": "prod"})
+register_trace(reporter)
+
+sales_agent = Agent(name="sales_agent", model="gpt-5.5", instructions="...")
+
+# Per-request handler — dynamic tags scoped to this one call.
+async def handle(customer_id, question):
+    with with_tags(customer_id=customer_id, agent_name="sales"):
+        return await Runner.run(sales_agent, question)
+```
+
+Every event that flows out of that `Runner.run` lands with the merged tag
+set — reporter defaults + whatever's active in the surrounding `with_tags`
+block.
+
+### `with_tags(**tags)` — dynamic per-request tags
+
+`with_tags` is the customer-facing knob for tags that vary per request:
+`customer_id`, `session_id`, `workflow`, whatever you want. It's a
+context manager backed by `contextvars`, so:
+
+- **Async-safe.** Concurrent tasks each maintain their own tag scope —
+  no cross-request bleed.
+- **Nested.** Inner blocks inherit outer tags and override on collisions.
+- **Works with both flows.** Whether the event is emitted by the Agents
+  integration or by a manual `reporter.report_usage(...)` call, the same
+  ambient stack is read.
+
+### Tag precedence (highest wins)
+
+For any event, tags merge in this order:
+
+1. `UsageReporter(tags=...)` — reporter defaults, static, process-wide
+2. `with_tags(...)` — ambient, request-scoped
+3. `report_usage(tags=...)` — per-call, most specific
+
+Later layers override earlier ones on key collisions.
+
+### What lands in `transactions.tags`
+
+Given the example above, one event would look like:
+
+```json
+{
+  "env":         "prod",           // reporter default
+  "customer_id": "cus_123",        // from with_tags
+  "agent_name":  "sales"           // from with_tags
+}
+```
+
+No auto-injected tags. What you write is what lands.
+
+## Failure modes
+
+- **HTTP failure (5xx, timeout, network blip).** The batch is retried up
+  to 3 times with exponential backoff + jitter, then dropped and logged.
+  The worker keeps running.
+- **Unexpected exception in the worker.** The worker's main loop catches
+  any exception, logs it, and continues. If the thread does die despite
+  that, the next `report_usage()` call starts a fresh one; only the event
+  in-flight at the time of the crash is lost — queued events are
+  preserved.
+- **Process death (SIGKILL, crash, sudden exit).** The in-memory queue is
+  lost. Long-lived servers are fine; short scripts should call
+  `reporter.flush()` before exit, or rely on the built-in `atexit` flush
+  (bounded to 5 seconds so slow OpenToken never hangs your process).
+
+Enable `logging.getLogger("opentoken")` to see retries, drops, and worker
+restarts. Call `reporter.stats()` any time to inspect `sent`, `dropped`,
+`retried`, `batches_flushed`, `worker_restarts`, `queue_depth`.
+
+## Response shape
+
+Both `/v1/usage` and `/v1/usage:batch` return the same positional bool
+array — one element per input event:
+
+```json
+{"results": [true, false, true]}
+```
+
+Each `true` means the event was accepted; each `false` means it failed
+(unknown model, missing usage block, etc.). The SDK counts `true` events
+toward `sent` and retries `false` events up to `max_retries` times, then
+counts still-failing events toward `dropped`.
+
+HTTP status is `200` for any well-formed request — individual event
+failures are surfaced inside `results`, not at the HTTP layer. The
+endpoints return `4xx` only for whole-request problems (auth, malformed
+JSON, oversized batch).

opentoken_sdk-0.1.0/README.md

@@ -0,0 +1,126 @@
+# Open Token Python SDK
+
+## Using `UsageReporter` directly
+
+If you want to report usage from any provider, use `UsageReporter` directly:
+
+```python
+from opentoken import UsageReporter
+
+reporter = UsageReporter(
+    open_token_api_key=os.environ["OPENTOKEN_API_KEY"],
+    tags={"service": "checkout-api", "env": "prod"},
+    batch=True,   # default; set False to POST one event at a time
+)
+
+response = your_provider_client.chat.completions.create(...)
+reporter.report_usage(response=response, latency_ms=..., tags={"workflow_id": "..."})
+```
+
+`report_usage(...)` enqueues the report on a bounded in-memory queue and
+returns immediately (~microseconds on the caller's thread). A background
+daemon thread drains the queue and POSTs to `/v1/usage:batch`. You don't
+manage the thread — it's started lazily on your first call and dies with
+the process.
+
+## OpenAI Agents SDK integration
+
+If you're using the OpenAI Agents SDK, register the tracing bridge once at
+startup and every `Runner.run(...)` will forward its LLM spans to
+OpenToken. You never call `report_usage` yourself.
+
+```python
+from opentoken import UsageReporter, with_tags
+from opentoken.integrations.agents import register_trace
+from agents import Agent, Runner
+
+# One-time setup — static tags apply to every event this reporter sends.
+reporter = UsageReporter(open_token_api_key=..., tags={"env": "prod"})
+register_trace(reporter)
+
+sales_agent = Agent(name="sales_agent", model="gpt-5.5", instructions="...")
+
+# Per-request handler — dynamic tags scoped to this one call.
+async def handle(customer_id, question):
+    with with_tags(customer_id=customer_id, agent_name="sales"):
+        return await Runner.run(sales_agent, question)
+```
+
+Every event that flows out of that `Runner.run` lands with the merged tag
+set — reporter defaults + whatever's active in the surrounding `with_tags`
+block.
+
+### `with_tags(**tags)` — dynamic per-request tags
+
+`with_tags` is the customer-facing knob for tags that vary per request:
+`customer_id`, `session_id`, `workflow`, whatever you want. It's a
+context manager backed by `contextvars`, so:
+
+- **Async-safe.** Concurrent tasks each maintain their own tag scope —
+  no cross-request bleed.
+- **Nested.** Inner blocks inherit outer tags and override on collisions.
+- **Works with both flows.** Whether the event is emitted by the Agents
+  integration or by a manual `reporter.report_usage(...)` call, the same
+  ambient stack is read.
+
+### Tag precedence (highest wins)
+
+For any event, tags merge in this order:
+
+1. `UsageReporter(tags=...)` — reporter defaults, static, process-wide
+2. `with_tags(...)` — ambient, request-scoped
+3. `report_usage(tags=...)` — per-call, most specific
+
+Later layers override earlier ones on key collisions.
+
+### What lands in `transactions.tags`
+
+Given the example above, one event would look like:
+
+```json
+{
+  "env":         "prod",           // reporter default
+  "customer_id": "cus_123",        // from with_tags
+  "agent_name":  "sales"           // from with_tags
+}
+```
+
+No auto-injected tags. What you write is what lands.
+
+## Failure modes
+
+- **HTTP failure (5xx, timeout, network blip).** The batch is retried up
+  to 3 times with exponential backoff + jitter, then dropped and logged.
+  The worker keeps running.
+- **Unexpected exception in the worker.** The worker's main loop catches
+  any exception, logs it, and continues. If the thread does die despite
+  that, the next `report_usage()` call starts a fresh one; only the event
+  in-flight at the time of the crash is lost — queued events are
+  preserved.
+- **Process death (SIGKILL, crash, sudden exit).** The in-memory queue is
+  lost. Long-lived servers are fine; short scripts should call
+  `reporter.flush()` before exit, or rely on the built-in `atexit` flush
+  (bounded to 5 seconds so slow OpenToken never hangs your process).
+
+Enable `logging.getLogger("opentoken")` to see retries, drops, and worker
+restarts. Call `reporter.stats()` any time to inspect `sent`, `dropped`,
+`retried`, `batches_flushed`, `worker_restarts`, `queue_depth`.
+
+## Response shape
+
+Both `/v1/usage` and `/v1/usage:batch` return the same positional bool
+array — one element per input event:
+
+```json
+{"results": [true, false, true]}
+```
+
+Each `true` means the event was accepted; each `false` means it failed
+(unknown model, missing usage block, etc.). The SDK counts `true` events
+toward `sent` and retries `false` events up to `max_retries` times, then
+counts still-failing events toward `dropped`.
+
+HTTP status is `200` for any well-formed request — individual event
+failures are surfaced inside `results`, not at the HTTP layer. The
+endpoints return `4xx` only for whole-request problems (auth, malformed
+JSON, oversized batch).

opentoken_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+# Distribution name on PyPI. Import name stays `opentoken` — the source
+# tree at `src/opentoken/` is unchanged. Users do `pip install opentoken-sdk`
+# and then `import opentoken`.
+name = "opentoken-sdk"
+version = "0.1.0"
+description = "OpenToken Python SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Nicole Chen", email = "nchen55555@gmail.com" },
+]
+keywords = ["observability", "llm", "openai", "anthropic", "gemini", "tokens", "usage"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    # `License ::` classifier intentionally omitted: PEP 639 (enforced by
+    # PyPI as of 2025) rejects uploads that declare a license via both
+    # the `license` field AND a `License ::` classifier. SPDX identifier
+    # lives on the `license` field above.
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "httpx"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "build",
+    "twine",
+]
+# OpenAI Agents SDK integration — `opentoken.integrations.agents`.
+agents = [
+    "openai-agents>=0.17",
+]
+# End-to-end live testing: real Agents SDK + real OpenAI + real backend.
+live = [
+    "openai-agents>=0.17",
+    "openai>=1.0",
+]
+
+[project.urls]
+Homepage = "https://opentoken.bid"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

opentoken_sdk-0.1.0/setup.cfg

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

opentoken_sdk-0.1.0/src/opentoken/__init__.py

@@ -0,0 +1,5 @@
+"""OpenToken Python SDK."""
+
+from opentoken.reporter import UsageReporter, with_tags
+
+__all__ = ["UsageReporter", "with_tags"]

opentoken_sdk-0.1.0/src/opentoken/constants.py

@@ -0,0 +1,19 @@
+"""SDK-wide constants."""
+
+DEFAULT_OPENTOKEN_BASE_URL = "https://opentoken.bid"
+
+# Batching defaults — internal defaults for UsageReporter. Both are
+# overridable via the constructor; batching itself is opt-in via
+# `batch=True` (which is the default).
+DEFAULT_BATCH_SIZE = 100
+DEFAULT_FLUSH_INTERVAL_MS = 500
+
+# Retry defaults — bounded so a persistent poison batch can't stall
+# the worker forever. See `_send_batch_with_retries`.
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_RETRY_INITIAL_DELAY_S = 0.1
+DEFAULT_RETRY_BACKOFF_MULTIPLIER = 4.0
+
+# atexit flush timeout — bounded so a slow OpenToken can't hang a
+# customer's Lambda/CLI at process exit.
+DEFAULT_ATEXIT_FLUSH_TIMEOUT_S = 5.0

opentoken_sdk-0.1.0/src/opentoken/integrations/__init__.py

@@ -0,0 +1,14 @@
+"""Framework-specific bridges.
+
+Each submodule is an integration with an agent/LLM framework whose
+architecture prevents us from observing calls at the provider-SDK layer
+(e.g. the framework owns the OpenAI client internally). The bridges are
+thin wrappers around the framework's official observability hooks that
+forward usage to `opentoken.UsageReporter`.
+
+Each integration is guarded by an ImportError-friendly try/except at
+its import site so the base SDK stays lightweight — customers install
+the extra only if they use that framework:
+
+    pip install "opentoken[agents]"    # OpenAI Agents SDK
+"""

opentoken_sdk-0.1.0/src/opentoken/integrations/agents.py

@@ -0,0 +1,181 @@
+"""OpenAI Agents SDK integration.
+
+The Agents SDK owns its own OpenAI client internally, so wrapping the
+provider SDK doesn't help. Instead, we register a `TracingProcessor`
+with the Agents SDK — it fires a callback on every span, including the
+LLM-generation spans that carry `model` + `usage`. We forward each of
+those to `UsageReporter.report_usage(...)`.
+
+Usage (customer's app):
+
+    from opentoken import UsageReporter
+    from opentoken.integrations.agents import register_trace
+
+    reporter = UsageReporter(open_token_api_key=..., tags={"env": "prod"})
+    register_trace(reporter)
+
+    # customer's Agents SDK code is unchanged
+    result = await Runner.run(agent, "hi")
+
+`register_trace(...)` registers the processor with the Agents SDK's
+global trace registry. Every subsequent `Runner.run(...)` flows through
+it.
+
+Requires `openai-agents` — install with `pip install "opentoken[agents]"`.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Optional
+
+from opentoken.reporter import UsageReporter
+
+if TYPE_CHECKING:
+    from agents.tracing import Span, Trace
+
+logger = logging.getLogger("opentoken")
+
+
+class OpenTokenTracingProcessor:
+    """Bridges Agents SDK trace spans to `UsageReporter`.
+
+    Implements the Agents SDK `TracingProcessor` interface (duck-typed to
+    avoid importing `agents` at module load — the import happens lazily
+    when the class is instantiated). Only LLM-generation spans emit
+    reports; agent/handoff/function/guardrail spans are ignored.
+
+    Thread-safety: `on_span_end` runs on the Agents SDK's tracing thread.
+    `report_usage` is thread-safe (non-blocking `queue.put_nowait`), so
+    the callback returns in microseconds.
+    """
+
+    def __init__(self, reporter: UsageReporter, extra_tags: Optional[dict[str, str]] = None):
+        # Import lazily to keep base `opentoken` importable without
+        # `openai-agents` installed. Users who never call register_trace()
+        # never pay the import cost.
+        from agents.tracing import GenerationSpanData, ResponseSpanData  # noqa: F401
+
+        self._reporter = reporter
+        self._extra_tags = dict(extra_tags or {})
+        self._GenerationSpanData = GenerationSpanData
+        self._ResponseSpanData = ResponseSpanData
+
+    # ---- TracingProcessor interface (Agents SDK duck-types this) --------
+
+    def on_trace_start(self, trace: "Trace") -> None:  # noqa: D401
+        return None
+
+    def on_trace_end(self, trace: "Trace") -> None:  # noqa: D401
+        return None
+
+    def on_span_start(self, span: "Span") -> None:  # noqa: D401
+        return None
+
+    def on_span_end(self, span: "Span") -> None:
+        try:
+            model, usage = self._extract(span.span_data)
+        except Exception:
+            # A malformed / unexpected span shape must never crash the
+            # Agents SDK trace pipeline. Log and continue.
+            logger.exception("opentoken: failed to extract usage from span")
+            return
+
+        if not model or not isinstance(usage, dict):
+            return
+
+        # Only `extra_tags` set at `register_trace(...)` land here. Agent
+        # name, span type, and any per-run context (customer_id, workflow,
+        # ...) are the customer's job to add via `with_tags(...)` around
+        # their `Runner.run(...)` call — keeps this layer opinion-free and
+        # lets the customer decide what they want tagged. The endpoint is
+        # already distinguishable server-side via the model + usage shape,
+        # so we don't tag span_type either.
+        tags = dict(self._extra_tags) if self._extra_tags else None
+        self._reporter.report_usage(
+            model=model,
+            usage=usage,
+            latency_ms=_span_latency_ms(span),
+            client_request_id=f"agents-{span.span_id}",
+            tags=tags,
+        )
+
+    def shutdown(self) -> None:
+        # Best-effort flush so events survive process exit even without atexit.
+        try:
+            self._reporter.flush()
+        except Exception:
+            logger.exception("opentoken: flush on shutdown failed")
+
+    def force_flush(self) -> None:
+        try:
+            self._reporter.flush()
+        except Exception:
+            logger.exception("opentoken: force_flush failed")
+
+    # ---- Internals ------------------------------------------------------
+
+    def _extract(self, data: Any) -> tuple[Optional[str], Optional[dict]]:
+        """Pull (model, usage) out of a span's data payload.
+
+        Handles the two LLM-emitting span types today. Silently returns
+        (None, None) for other span types — agent/handoff/tool/etc.
+        """
+        if isinstance(data, self._GenerationSpanData):
+            # GenerationSpanData is the legacy Chat Completions shape.
+            return data.model, data.usage
+
+        if isinstance(data, self._ResponseSpanData):
+            # ResponseSpanData wraps the OpenAI Responses API. Model lives
+            # on `response.model`; usage may be on `data.usage` (already
+            # extracted by Agents SDK) or on `response.usage`.
+            resp = data.response
+            model = getattr(resp, "model", None) if resp is not None else None
+            usage = data.usage
+            if usage is None and resp is not None:
+                raw = getattr(resp, "usage", None)
+                if raw is not None:
+                    if hasattr(raw, "model_dump"):
+                        try:
+                            usage = raw.model_dump(mode="json")
+                        except TypeError:
+                            usage = raw.model_dump()
+                    elif isinstance(raw, dict):
+                        usage = raw
+            return model, usage
+
+        return None, None
+
+
+def _span_latency_ms(span: Any) -> Optional[int]:
+    """Best-effort span duration in ms. Returns None if either timestamp is missing."""
+    started = getattr(span, "started_at", None)
+    ended = getattr(span, "ended_at", None)
+    if started is None or ended is None:
+        return None
+    try:
+        import datetime as _dt
+        if isinstance(started, str):
+            started = _dt.datetime.fromisoformat(started.replace("Z", "+00:00"))
+        if isinstance(ended, str):
+            ended = _dt.datetime.fromisoformat(ended.replace("Z", "+00:00"))
+        return int((ended - started).total_seconds() * 1000)
+    except Exception:
+        return None
+
+
+def register_trace(
+    reporter: UsageReporter,
+    extra_tags: Optional[dict[str, str]] = None,
+) -> OpenTokenTracingProcessor:
+    """Register `OpenTokenTracingProcessor` with the Agents SDK.
+
+    After this call, every Agents SDK `Runner.run(...)` in this process
+    forwards its LLM spans to `reporter`. Returns the processor instance
+    so callers can hold a reference (rarely needed).
+    """
+    from agents.tracing import add_trace_processor  # lazy import
+
+    processor = OpenTokenTracingProcessor(reporter, extra_tags=extra_tags)
+    add_trace_processor(processor)
+    return processor

opentoken_sdk-0.1.0/src/opentoken/reporter.py

@@ -0,0 +1,438 @@
+"""Usage reporting client."""
+
+from __future__ import annotations
+
+import atexit
+import contextlib
+import contextvars
+import logging
+import os
+import queue
+import random
+import threading
+import time
+import uuid
+from typing import Iterator, Optional
+
+import httpx
+
+from opentoken.constants import (
+    DEFAULT_ATEXIT_FLUSH_TIMEOUT_S,
+    DEFAULT_BATCH_SIZE,
+    DEFAULT_FLUSH_INTERVAL_MS,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_OPENTOKEN_BASE_URL,
+    DEFAULT_RETRY_BACKOFF_MULTIPLIER,
+    DEFAULT_RETRY_INITIAL_DELAY_S,
+)
+from opentoken.schemas import UsageReport
+
+logger = logging.getLogger("opentoken")
+
+
+# ---- Ambient (per-request) tags -----------------------------------------
+#
+# Populated by the `with_tags(...)` context manager below; read inside
+# `report_usage(...)` and merged into every event emitted from within the
+# block. Uses a ContextVar so concurrent async tasks each see their own
+# scope — no cross-request bleed.
+#
+# The integrations layer (e.g. `integrations/agents.py`) calls
+# `report_usage` on the customer's behalf, so ambient tags are the only
+# way for the customer to attach per-request tags to Agents-emitted
+# events without touching the reporter directly.
+_ambient_tags: contextvars.ContextVar[dict[str, str]] = contextvars.ContextVar(
+    "opentoken_ambient_tags", default={},
+)
+
+
+@contextlib.contextmanager
+def with_tags(**tags: str) -> Iterator[None]:
+    """Attach dynamic tags to every event emitted inside this block.
+
+    Async-safe via `contextvars` — concurrent tasks each maintain their
+    own tag scope. Nested calls stack: an inner `with_tags(...)` inherits
+    outer tags and adds/overrides on collisions.
+
+    Typical use — request-scoped tags that vary per call:
+
+        async def handle(customer_id, question):
+            with with_tags(customer_id=customer_id, session_id="s_abc"):
+                return await Runner.run(sales_agent, question)
+
+    Works with both the Agents SDK integration (which calls `report_usage`
+    on your behalf) and with manual `reporter.report_usage(...)` calls —
+    the same ambient stack is read either way.
+
+    All values are stringified so any JSON-serializable primitive is
+    accepted at the call site (numbers, bools, UUIDs, ...) and lands as a
+    string tag in `transactions.tags`.
+    """
+    current = _ambient_tags.get()
+    merged = {**current, **{k: str(v) for k, v in tags.items()}}
+    token = _ambient_tags.set(merged)
+    try:
+        yield
+    finally:
+        _ambient_tags.reset(token)
+
+
+class UsageReporter:
+    """Enqueue usage reports and drain them from a daemon worker thread.
+
+    The producer (`report_usage`) never blocks — it pushes to a bounded
+    in-memory queue and returns in microseconds. A single background
+    thread drains the queue, batches events, POSTs them to OpenToken with
+    bounded retries, and re-enqueues in-flight events if the worker hits
+    an unexpected error.
+
+    Customers do not manage the thread. It starts lazily on the first
+    `report_usage` call and dies with the process. Call `stats()` to
+    inspect counters; enable `logging.getLogger("opentoken")` to see
+    warnings for retries, drops, and worker restarts.
+    """
+
+    def __init__(
+        self,
+        open_token_api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        tags: Optional[dict[str, str]] = None,
+        batch: bool = True,
+        batch_size: int = DEFAULT_BATCH_SIZE,
+        flush_interval_ms: int = DEFAULT_FLUSH_INTERVAL_MS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = 2.0,
+        http_client=None,
+        max_queue_size: int = 1000,
+    ) -> None:
+        self.open_token_api_key = open_token_api_key or os.environ.get("OPENTOKEN_API_KEY")
+        self.base_url = (base_url or os.environ.get("OPENTOKEN_BASE_URL") or DEFAULT_OPENTOKEN_BASE_URL).rstrip("/")
+        self.tags = dict(tags or {})
+        self.batch = batch
+        self.batch_size = max(1, batch_size)
+        self.flush_interval_ms = max(0, flush_interval_ms)
+        self.max_retries = max(1, max_retries)
+        self.timeout = timeout
+        self.http_client = http_client
+
+        self._queue: queue.Queue[Optional[UsageReport]] = queue.Queue(maxsize=max_queue_size)
+        self._worker: Optional[threading.Thread] = None
+        self._worker_lock = threading.Lock()
+        self._in_flight_batch: Optional[list[UsageReport]] = None
+        self._stats = {
+            "sent": 0,
+            "dropped": 0,
+            "retried": 0,
+            "batches_flushed": 0,
+            "worker_restarts": 0,
+        }
+        self._closed = False
+
+        atexit.register(self._atexit_flush)
+
+    def report_usage(
+        self,
+        response: Optional[dict] = None,
+        model: Optional[str] = None,
+        usage: Optional[dict] = None,
+        parent_request_id: Optional[str] = None,
+        latency_ms: Optional[int] = None,
+        client_request_id: Optional[str] = None,
+        tags: Optional[dict[str, str]] = None,
+    ) -> bool:
+        if not self.open_token_api_key:
+            return False
+
+        # Tag merge order (highest wins on collision):
+        #   1. reporter defaults (self.tags)  — static, process-wide
+        #   2. ambient (with_tags)            — dynamic, request-scoped
+        #   3. per-call `tags` arg            — most specific
+        # Integrations use #3 for tags they know deterministically about
+        # the span; customer-facing dynamic context flows through #2.
+        ambient = _ambient_tags.get()
+        merged_tags: Optional[dict[str, str]] = None
+        if self.tags or ambient or tags:
+            merged_tags = {}
+            if self.tags:
+                merged_tags.update(self.tags)
+            if ambient:
+                merged_tags.update(ambient)
+            if tags:
+                merged_tags.update(tags)
+
+        # Auto-generate an idempotency key when the caller doesn't supply one.
+        # This survives full end-to-end retries (network hiccup → SDK resends
+        # the same event → server dedupes at the transactions layer) and
+        # Redis redeliveries inside the server (worker crash → XAUTOCLAIM
+        # hands the same event to another worker → ON CONFLICT drops the
+        # duplicate insert). Both properties rely on the key being stable
+        # for the lifetime of an event, so we generate it here at the
+        # earliest point where the event exists.
+        if client_request_id is None:
+            client_request_id = str(uuid.uuid4())
+
+        report = UsageReport(
+            response=response,
+            model=model,
+            usage=usage,
+            parent_request_id=parent_request_id,
+            latency_ms=latency_ms,
+            client_request_id=client_request_id,
+            tags=merged_tags,
+        )
+
+        try:
+            self._queue.put_nowait(report)
+        except queue.Full:
+            self._stats["dropped"] += 1
+            return False
+
+        self._ensure_worker()
+        return True
+
+    def stats(self) -> dict[str, int]:
+        """Snapshot of counters. Safe to call from any thread."""
+        snapshot = dict(self._stats)
+        snapshot["queue_depth"] = self._queue.qsize()
+        return snapshot
+
+    def flush(self) -> None:
+        self._queue.join()
+
+    def close(self, timeout: Optional[float] = None) -> None:
+        if self._worker is None or not self._worker.is_alive():
+            return
+        try:
+            self._queue.put_nowait(None)
+        except queue.Full:
+            # Queue is full; drain one item so the pill can go in.
+            try:
+                self._queue.get_nowait()
+                self._queue.task_done()
+                self._queue.put_nowait(None)
+            except (queue.Empty, queue.Full):
+                pass
+        self._worker.join(timeout=timeout if timeout is not None else self.timeout)
+        self._worker = None
+        self._closed = True
+
+    # ---- Internal ------------------------------------------------------
+
+    def _atexit_flush(self) -> None:
+        if self._closed:
+            return
+        try:
+            self.close(timeout=DEFAULT_ATEXIT_FLUSH_TIMEOUT_S)
+        except Exception:
+            pass
+
+    def _ensure_worker(self) -> None:
+        # Lock guards against two concurrent first-callers each starting a worker.
+        with self._worker_lock:
+            if self._worker is not None and self._worker.is_alive():
+                return
+            self._worker = threading.Thread(target=self._run_worker, daemon=True)
+            self._worker.start()
+
+    def _run_worker(self) -> None:
+        while True:
+            # Outer try catches unexpected exceptions (bugs). If we die
+            # mid-send, re-enqueue the in-flight batch and keep looping.
+            try:
+                # Block for at least one event.
+                first = self._queue.get()
+                if first is None:
+                    self._queue.task_done()
+                    return
+
+                batch = [first]
+                shutdown_pending = False
+
+                # Accumulate more events up to batch_size or flush_interval_ms.
+                if self.batch and self.batch_size > 1:
+                    deadline = time.monotonic() + self.flush_interval_ms / 1000
+                    while len(batch) < self.batch_size:
+                        timeout = deadline - time.monotonic()
+                        if timeout <= 0:
+                            break
+                        try:
+                            item = self._queue.get(timeout=timeout)
+                        except queue.Empty:
+                            break
+                        if item is None:
+                            shutdown_pending = True
+                            self._queue.task_done()
+                            break
+                        batch.append(item)
+
+                # Unified send path — picks endpoint + payload shape from
+                # `self.batch`. Manages its own stats, never raises.
+                self._in_flight_batch = batch
+                try:
+                    self._send_with_retries(batch)
+                finally:
+                    for _ in batch:
+                        self._queue.task_done()
+                    self._in_flight_batch = None
+
+                if shutdown_pending:
+                    return
+
+            except Exception:
+                # A bug in the worker loop itself. Log, re-enqueue, continue.
+                logger.exception("worker unexpected error; re-enqueueing in-flight batch")
+                self._stats["worker_restarts"] += 1
+                if self._in_flight_batch is not None:
+                    for item in reversed(self._in_flight_batch):
+                        try:
+                            self._queue.put_nowait(item)
+                        except queue.Full:
+                            self._stats["dropped"] += 1
+                    self._in_flight_batch = None
+
+    def _send_with_retries(self, events: list[UsageReport]) -> None:
+        """POST events with bounded retries. Manages stats; never raises.
+
+        Endpoint + payload shape depend on `self.batch`:
+          - batch=True  → POST {"events": [...]} to /v1/usage:batch
+          - batch=False → POST single event body to /v1/usage
+        Both endpoints return `{"results": [bool, ...]}` (positional), so the
+        retry logic is identical: successful events are counted; failed
+        events shrink into `remaining` and are re-sent on the next attempt.
+
+        Retry semantics:
+          - 2xx with results     → count sent; retry failed events only.
+          - 2xx without results  → treat as full success (backwards-compat safety).
+          - 4xx (not 429)        → drop remaining as a client error, no retry.
+          - 429                  → honor Retry-After (or backoff jitter), retry all remaining.
+          - 5xx / network / timeout → retry all remaining.
+          - Exhausted            → drop still-failing events.
+        """
+        url = (
+            f"{self.base_url}/v1/usage:batch" if self.batch
+            else f"{self.base_url}/v1/usage"
+        )
+        remaining = list(events)
+        delay = DEFAULT_RETRY_INITIAL_DELAY_S
+
+        for attempt in range(1, self.max_retries + 1):
+            try:
+                payload = (
+                    {"events": [r.to_payload() for r in remaining]} if self.batch
+                    else remaining[0].to_payload()
+                )
+                resp = self._post(url, payload)
+                status = getattr(resp, "status_code", 0)
+
+                if 200 <= status < 300:
+                    results = _parse_results(resp)
+                    if results is None or len(results) != len(remaining):
+                        # Server didn't return a positional bool array — treat as full success.
+                        self._stats["sent"] += len(remaining)
+                        self._stats["batches_flushed"] += 1
+                        return
+
+                    self._stats["sent"] += sum(1 for ok in results if ok)
+                    failed = [ev for ev, ok in zip(remaining, results) if not ok]
+                    if not failed:
+                        self._stats["batches_flushed"] += 1
+                        return
+
+                    logger.warning(
+                        "%d/%d events failed (attempt %d/%d), retrying failures",
+                        len(failed), len(remaining), attempt, self.max_retries,
+                    )
+                    remaining = failed
+                    # Fall through to backoff before next attempt.
+
+                elif status == 429:
+                    if attempt >= self.max_retries:
+                        logger.warning("429 rate-limited, retries exhausted; dropping %d events", len(remaining))
+                        self._stats["dropped"] += len(remaining)
+                        return
+                    retry_after = _parse_retry_after(_get_header(resp, "Retry-After"))
+                    sleep_for = retry_after if retry_after is not None else _jittered(delay)
+                    logger.warning("429 rate-limited (attempt %d/%d), sleeping %.2fs", attempt, self.max_retries, sleep_for)
+                    time.sleep(sleep_for)
+                    self._stats["retried"] += len(remaining)
+                    delay *= DEFAULT_RETRY_BACKOFF_MULTIPLIER
+                    continue
+
+                elif 400 <= status < 500:
+                    logger.warning("HTTP %d — client error, dropping %d events", status, len(remaining))
+                    self._stats["dropped"] += len(remaining)
+                    return
+
+                else:
+                    # 5xx — fall through to retry
+                    logger.warning("HTTP %d (attempt %d/%d)", status, attempt, self.max_retries)
+
+            except Exception as exc:
+                logger.warning("send failed (attempt %d/%d): %s", attempt, self.max_retries, exc)
+
+            if attempt < self.max_retries:
+                time.sleep(_jittered(delay))
+                self._stats["retried"] += len(remaining)
+                delay *= DEFAULT_RETRY_BACKOFF_MULTIPLIER
+
+        logger.warning("retries exhausted, dropping %d events", len(remaining))
+        self._stats["dropped"] += len(remaining)
+
+    def _post(self, url: str, payload: dict):
+        headers = {"Authorization": f"Bearer {self.open_token_api_key}"}
+        if self.http_client is not None:
+            return self.http_client.post(
+                url,
+                json=payload,
+                headers=headers,
+                timeout=self.timeout,
+            )
+        with httpx.Client(timeout=self.timeout) as client:
+            return client.post(url, json=payload, headers=headers)
+
+
+def _jittered(delay: float) -> float:
+    """Full-jitter backoff — [0.5, 1.5) × delay — avoids retry storms."""
+    return delay * (0.5 + random.random())
+
+
+def _get_header(resp, name: str) -> Optional[str]:
+    headers = getattr(resp, "headers", None)
+    if headers is None:
+        return None
+    try:
+        return headers.get(name)
+    except AttributeError:
+        return None
+
+
+def _parse_retry_after(header: Optional[str]) -> Optional[float]:
+    """Parse Retry-After. Only handles the integer-seconds form; HTTP-date is rare."""
+    if not header:
+        return None
+    try:
+        return float(header)
+    except (TypeError, ValueError):
+        return None
+
+
+def _parse_results(resp) -> Optional[list[bool]]:
+    """Extract `{"results": [bool, ...]}` from either endpoint's response.
+
+    Both `/v1/usage` and `/v1/usage:batch` return the same shape (single
+    endpoint returns a 1-element list). Returns None when the body is
+    missing, unparseable, or doesn't contain a bool array — callers treat
+    that as "assume full success" for backwards compatibility.
+    """
+    if not hasattr(resp, "json"):
+        return None
+    try:
+        body = resp.json()
+    except Exception:
+        return None
+    if not isinstance(body, dict):
+        return None
+    results = body.get("results")
+    if not isinstance(results, list):
+        return None
+    return [bool(r) for r in results]

opentoken_sdk-0.1.0/src/opentoken/schemas.py

@@ -0,0 +1,32 @@
+"""SDK payload schemas."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class UsageReport:
+    response: Optional[dict] = None
+    model: Optional[str] = None
+    usage: Optional[dict] = None
+    parent_request_id: Optional[str] = None
+    latency_ms: Optional[int] = None
+    client_request_id: Optional[str] = None
+    tags: Optional[dict[str, str]] = None
+
+    def to_payload(self) -> dict:
+        return {
+            key: value
+            for key, value in {
+                "response": self.response,
+                "model": self.model,
+                "usage": self.usage,
+                "parent_request_id": self.parent_request_id,
+                "latency_ms": self.latency_ms,
+                "client_request_id": self.client_request_id,
+                "tags": self.tags,
+            }.items()
+            if value is not None
+        }

opentoken_sdk-0.1.0/src/opentoken_sdk.egg-info/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: opentoken-sdk
+Version: 0.1.0
+Summary: OpenToken Python SDK
+Author-email: Nicole Chen <nchen55555@gmail.com>
+License: MIT
+Project-URL: Homepage, https://opentoken.bid
+Keywords: observability,llm,openai,anthropic,gemini,tokens,usage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: agents
+Requires-Dist: openai-agents>=0.17; extra == "agents"
+Provides-Extra: live
+Requires-Dist: openai-agents>=0.17; extra == "live"
+Requires-Dist: openai>=1.0; extra == "live"
+
+# Open Token Python SDK
+
+## Using `UsageReporter` directly
+
+If you want to report usage from any provider, use `UsageReporter` directly:
+
+```python
+from opentoken import UsageReporter
+
+reporter = UsageReporter(
+    open_token_api_key=os.environ["OPENTOKEN_API_KEY"],
+    tags={"service": "checkout-api", "env": "prod"},
+    batch=True,   # default; set False to POST one event at a time
+)
+
+response = your_provider_client.chat.completions.create(...)
+reporter.report_usage(response=response, latency_ms=..., tags={"workflow_id": "..."})
+```
+
+`report_usage(...)` enqueues the report on a bounded in-memory queue and
+returns immediately (~microseconds on the caller's thread). A background
+daemon thread drains the queue and POSTs to `/v1/usage:batch`. You don't
+manage the thread — it's started lazily on your first call and dies with
+the process.
+
+## OpenAI Agents SDK integration
+
+If you're using the OpenAI Agents SDK, register the tracing bridge once at
+startup and every `Runner.run(...)` will forward its LLM spans to
+OpenToken. You never call `report_usage` yourself.
+
+```python
+from opentoken import UsageReporter, with_tags
+from opentoken.integrations.agents import register_trace
+from agents import Agent, Runner
+
+# One-time setup — static tags apply to every event this reporter sends.
+reporter = UsageReporter(open_token_api_key=..., tags={"env": "prod"})
+register_trace(reporter)
+
+sales_agent = Agent(name="sales_agent", model="gpt-5.5", instructions="...")
+
+# Per-request handler — dynamic tags scoped to this one call.
+async def handle(customer_id, question):
+    with with_tags(customer_id=customer_id, agent_name="sales"):
+        return await Runner.run(sales_agent, question)
+```
+
+Every event that flows out of that `Runner.run` lands with the merged tag
+set — reporter defaults + whatever's active in the surrounding `with_tags`
+block.
+
+### `with_tags(**tags)` — dynamic per-request tags
+
+`with_tags` is the customer-facing knob for tags that vary per request:
+`customer_id`, `session_id`, `workflow`, whatever you want. It's a
+context manager backed by `contextvars`, so:
+
+- **Async-safe.** Concurrent tasks each maintain their own tag scope —
+  no cross-request bleed.
+- **Nested.** Inner blocks inherit outer tags and override on collisions.
+- **Works with both flows.** Whether the event is emitted by the Agents
+  integration or by a manual `reporter.report_usage(...)` call, the same
+  ambient stack is read.
+
+### Tag precedence (highest wins)
+
+For any event, tags merge in this order:
+
+1. `UsageReporter(tags=...)` — reporter defaults, static, process-wide
+2. `with_tags(...)` — ambient, request-scoped
+3. `report_usage(tags=...)` — per-call, most specific
+
+Later layers override earlier ones on key collisions.
+
+### What lands in `transactions.tags`
+
+Given the example above, one event would look like:
+
+```json
+{
+  "env":         "prod",           // reporter default
+  "customer_id": "cus_123",        // from with_tags
+  "agent_name":  "sales"           // from with_tags
+}
+```
+
+No auto-injected tags. What you write is what lands.
+
+## Failure modes
+
+- **HTTP failure (5xx, timeout, network blip).** The batch is retried up
+  to 3 times with exponential backoff + jitter, then dropped and logged.
+  The worker keeps running.
+- **Unexpected exception in the worker.** The worker's main loop catches
+  any exception, logs it, and continues. If the thread does die despite
+  that, the next `report_usage()` call starts a fresh one; only the event
+  in-flight at the time of the crash is lost — queued events are
+  preserved.
+- **Process death (SIGKILL, crash, sudden exit).** The in-memory queue is
+  lost. Long-lived servers are fine; short scripts should call
+  `reporter.flush()` before exit, or rely on the built-in `atexit` flush
+  (bounded to 5 seconds so slow OpenToken never hangs your process).
+
+Enable `logging.getLogger("opentoken")` to see retries, drops, and worker
+restarts. Call `reporter.stats()` any time to inspect `sent`, `dropped`,
+`retried`, `batches_flushed`, `worker_restarts`, `queue_depth`.
+
+## Response shape
+
+Both `/v1/usage` and `/v1/usage:batch` return the same positional bool
+array — one element per input event:
+
+```json
+{"results": [true, false, true]}
+```
+
+Each `true` means the event was accepted; each `false` means it failed
+(unknown model, missing usage block, etc.). The SDK counts `true` events
+toward `sent` and retries `false` events up to `max_retries` times, then
+counts still-failing events toward `dropped`.
+
+HTTP status is `200` for any well-formed request — individual event
+failures are surfaced inside `results`, not at the HTTP layer. The
+endpoints return `4xx` only for whole-request problems (auth, malformed
+JSON, oversized batch).

opentoken_sdk-0.1.0/src/opentoken_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/opentoken/__init__.py
+src/opentoken/constants.py
+src/opentoken/reporter.py
+src/opentoken/schemas.py
+src/opentoken/integrations/__init__.py
+src/opentoken/integrations/agents.py
+src/opentoken_sdk.egg-info/PKG-INFO
+src/opentoken_sdk.egg-info/SOURCES.txt
+src/opentoken_sdk.egg-info/dependency_links.txt
+src/opentoken_sdk.egg-info/requires.txt
+src/opentoken_sdk.egg-info/top_level.txt

opentoken_sdk-0.1.0/src/opentoken_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

opentoken_sdk-0.1.0/src/opentoken_sdk.egg-info/requires.txt

@@ -0,0 +1,13 @@
+httpx
+
+[agents]
+openai-agents>=0.17
+
+[dev]
+pytest
+build
+twine
+
+[live]
+openai-agents>=0.17
+openai>=1.0

opentoken_sdk-0.1.0/src/opentoken_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+opentoken