ganivra 0.1.0__tar.gz

ganivra-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.DS_Store
+.env
+.env.deploy
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.db
+*.egg-info/
+.release-venv/
+sdk/dist/
+sdk/build/
+frontend/node_modules/
+frontend/.next/
+frontend/dist/
+frontend/.wrangler/

ganivra-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ganivra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ganivra-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: ganivra
+Version: 0.1.0
+Summary: AI execution cost and unit-economics telemetry for the OpenAI Python SDK
+Project-URL: Homepage, https://ganivra.com
+Project-URL: Documentation, https://ganivra.com
+Author: Ganivra
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,cost,llm,observability,openai,unit-economics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: openai>=1.50
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == 'release'
+Requires-Dist: twine>=6.0; extra == 'release'
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Ganivra Python SDK
+
+Ganivra measures the cost and unit economics of AI executions without proxying
+model traffic or storing prompts and responses.
+
+## Install
+
+```bash
+python -m pip install ganivra
+```
+
+Ganivra requires Python 3.10 or newer and currently instruments synchronous
+OpenAI Responses API calls.
+
+## Initialize before creating the OpenAI client
+
+```python
+import ganivra
+from openai import OpenAI
+
+ganivra.init(api_key="gv_live_your_workspace_key")
+client = OpenAI()
+
+response = client.responses.create(
+    model="gpt-5",
+    input="Explain our refund policy simply.",
+)
+```
+
+Initialization automatically captures model, input/output/cached token counts,
+latency, status, error type, and environment. Ganivra creates execution and step
+IDs and exports the metadata on a bounded background queue.
+
+## Add business context for unit economics
+
+```python
+with ganivra.trace(
+    workflow="support_answer",
+    feature="support_chatbot",
+    customer_id="acme",
+    prompt_id="support_answer",
+    prompt_version="v1",
+    revenue_usd=0.10,
+):
+    response = client.responses.create(
+        model="gpt-5",
+        input="Explain our refund policy simply.",
+    )
+```
+
+Trace metadata is optional. It enables customer, feature, workflow, prompt, and
+margin reporting. Use pseudonymous identifiers where appropriate.
+
+## Configuration
+
+```python
+ganivra.init(
+    api_key="gv_live_your_workspace_key",
+    endpoint="https://api.ganivra.com",
+    environment="production",
+    queue_size=1000,
+    batch_size=20,
+    timeout_seconds=2.0,
+    max_retries=2,
+)
+```
+
+For local Ganivra development, set `endpoint="http://127.0.0.1:8000"`.
+Call `ganivra.flush()` in short-lived scripts when you want to wait briefly for
+queued telemetry.
+
+## Privacy and failure behavior
+
+- OpenAI requests continue going directly from your application to OpenAI.
+- Prompt and response bodies are never collected.
+- OpenAI API keys are never collected.
+- Telemetry failures never change the OpenAI result or exception your code sees.
+- A full queue or unavailable Ganivra endpoint drops telemetry instead of
+  blocking the application.
+
+Prefer the language-independent REST API when automatic Python instrumentation
+is not appropriate. The canonical API contract is documented at
+`docs/API.md` in the Ganivra project.

ganivra-0.1.0/README.md

@@ -0,0 +1,83 @@
+# Ganivra Python SDK
+
+Ganivra measures the cost and unit economics of AI executions without proxying
+model traffic or storing prompts and responses.
+
+## Install
+
+```bash
+python -m pip install ganivra
+```
+
+Ganivra requires Python 3.10 or newer and currently instruments synchronous
+OpenAI Responses API calls.
+
+## Initialize before creating the OpenAI client
+
+```python
+import ganivra
+from openai import OpenAI
+
+ganivra.init(api_key="gv_live_your_workspace_key")
+client = OpenAI()
+
+response = client.responses.create(
+    model="gpt-5",
+    input="Explain our refund policy simply.",
+)
+```
+
+Initialization automatically captures model, input/output/cached token counts,
+latency, status, error type, and environment. Ganivra creates execution and step
+IDs and exports the metadata on a bounded background queue.
+
+## Add business context for unit economics
+
+```python
+with ganivra.trace(
+    workflow="support_answer",
+    feature="support_chatbot",
+    customer_id="acme",
+    prompt_id="support_answer",
+    prompt_version="v1",
+    revenue_usd=0.10,
+):
+    response = client.responses.create(
+        model="gpt-5",
+        input="Explain our refund policy simply.",
+    )
+```
+
+Trace metadata is optional. It enables customer, feature, workflow, prompt, and
+margin reporting. Use pseudonymous identifiers where appropriate.
+
+## Configuration
+
+```python
+ganivra.init(
+    api_key="gv_live_your_workspace_key",
+    endpoint="https://api.ganivra.com",
+    environment="production",
+    queue_size=1000,
+    batch_size=20,
+    timeout_seconds=2.0,
+    max_retries=2,
+)
+```
+
+For local Ganivra development, set `endpoint="http://127.0.0.1:8000"`.
+Call `ganivra.flush()` in short-lived scripts when you want to wait briefly for
+queued telemetry.
+
+## Privacy and failure behavior
+
+- OpenAI requests continue going directly from your application to OpenAI.
+- Prompt and response bodies are never collected.
+- OpenAI API keys are never collected.
+- Telemetry failures never change the OpenAI result or exception your code sees.
+- A full queue or unavailable Ganivra endpoint drops telemetry instead of
+  blocking the application.
+
+Prefer the language-independent REST API when automatic Python instrumentation
+is not appropriate. The canonical API contract is documented at
+`docs/API.md` in the Ganivra project.

ganivra-0.1.0/ganivra/__init__.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import atexit
+import threading
+from typing import Any
+
+from .config import Config
+from .context import trace
+from .instrumentation import instrument_openai
+from .sender import BackgroundSender
+
+__all__ = ["init", "trace", "flush"]
+__version__ = "0.1.0"
+
+_lock = threading.Lock()
+_config: Config | None = None
+_sender: BackgroundSender | None = None
+
+
+def init(
+    *,
+    api_key: str,
+    endpoint: str = "https://api.ganivra.com",
+    environment: str = "production",
+    queue_size: int = 1_000,
+    batch_size: int = 20,
+    timeout_seconds: float = 2.0,
+    max_retries: int = 2,
+) -> None:
+    """Initialize best-effort telemetry and instrument OpenAI once per process."""
+
+    global _config, _sender
+    config = Config(
+        api_key=api_key,
+        endpoint=endpoint,
+        environment=environment,
+        queue_size=queue_size,
+        batch_size=batch_size,
+        timeout_seconds=timeout_seconds,
+        max_retries=max_retries,
+    )
+    with _lock:
+        previous = _sender
+        _config = config
+        _sender = BackgroundSender(config)
+        instrument_openai(_get_environment, _enqueue)
+    if previous is not None:
+        previous.shutdown(timeout=0.2)
+
+
+def _get_environment() -> str:
+    return _config.environment if _config else "production"
+
+
+def _enqueue(event: dict[str, Any]) -> None:
+    sender = _sender
+    if sender is not None:
+        sender.enqueue(event)
+
+
+def flush(timeout: float = 2.0) -> bool:
+    """Best-effort wait for queued telemetry, primarily useful in short scripts."""
+
+    sender = _sender
+    return True if sender is None else sender.flush(timeout)
+
+
+def _shutdown() -> None:
+    sender = _sender
+    if sender is not None:
+        sender.shutdown(timeout=0.5)
+
+
+def _state_for_testing() -> tuple[Config | None, BackgroundSender | None]:
+    return _config, _sender
+
+
+atexit.register(_shutdown)

ganivra-0.1.0/ganivra/config.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    api_key: str
+    endpoint: str = "https://api.ganivra.com"
+    environment: str = "production"
+    queue_size: int = 1_000
+    batch_size: int = 20
+    timeout_seconds: float = 2.0
+    max_retries: int = 2
+
+    def __post_init__(self) -> None:
+        if not self.api_key.strip():
+            raise ValueError("api_key must not be empty")
+        parsed = urlparse(self.endpoint)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+            raise ValueError("endpoint must be an http(s) URL")
+        if not self.environment.strip():
+            raise ValueError("environment must not be empty")
+        if self.queue_size < 1 or self.batch_size < 1:
+            raise ValueError("queue_size and batch_size must be positive")
+        if self.timeout_seconds <= 0 or self.max_retries < 0:
+            raise ValueError("invalid timeout or retry configuration")
+
+    @property
+    def events_url(self) -> str:
+        endpoint = self.endpoint.rstrip("/")
+        if endpoint.endswith("/v1/events"):
+            return endpoint
+        return f"{endpoint}/v1/events"

ganivra-0.1.0/ganivra/context.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Iterator
+from uuid import uuid4
+
+
+@dataclass(frozen=True, slots=True)
+class TraceContext:
+    execution_id: str
+    workflow: str | None = None
+    feature: str | None = None
+    customer_id: str | None = None
+    conversation_id: str | None = None
+    user_id: str | None = None
+    prompt_id: str | None = None
+    prompt_version: str | None = None
+    revenue_usd: Decimal | float | None = None
+
+    def attributes(self) -> dict[str, str | float]:
+        return {
+            key: value
+            for key, value in {
+                "workflow": self.workflow,
+                "feature": self.feature,
+                "customer_id": self.customer_id,
+                "conversation_id": self.conversation_id,
+                "user_id": self.user_id,
+                "prompt_id": self.prompt_id,
+                "prompt_version": self.prompt_version,
+                "revenue_usd": float(self.revenue_usd) if self.revenue_usd is not None else None,
+            }.items()
+            if value is not None
+        }
+
+
+_current_trace: ContextVar[TraceContext | None] = ContextVar(
+    "ganivra_trace", default=None
+)
+
+
+def current_trace() -> TraceContext | None:
+    return _current_trace.get()
+
+
+def new_id(prefix: str) -> str:
+    return f"{prefix}_{uuid4().hex}"
+
+
+@contextmanager
+def trace(
+    *,
+    workflow: str | None = None,
+    feature: str | None = None,
+    customer_id: str | None = None,
+    conversation_id: str | None = None,
+    user_id: str | None = None,
+    prompt_id: str | None = None,
+    prompt_version: str | None = None,
+    revenue_usd: Decimal | float | None = None,
+    execution_id: str | None = None,
+) -> Iterator[TraceContext]:
+    parent = current_trace()
+    context = TraceContext(
+        execution_id=execution_id or new_id("exec"),
+        workflow=workflow if workflow is not None else getattr(parent, "workflow", None),
+        feature=feature if feature is not None else getattr(parent, "feature", None),
+        customer_id=(
+            customer_id
+            if customer_id is not None
+            else getattr(parent, "customer_id", None)
+        ),
+        conversation_id=(
+            conversation_id
+            if conversation_id is not None
+            else getattr(parent, "conversation_id", None)
+        ),
+        user_id=user_id if user_id is not None else getattr(parent, "user_id", None),
+        prompt_id=(
+            prompt_id if prompt_id is not None else getattr(parent, "prompt_id", None)
+        ),
+        prompt_version=(
+            prompt_version
+            if prompt_version is not None
+            else getattr(parent, "prompt_version", None)
+        ),
+        revenue_usd=(
+            revenue_usd
+            if revenue_usd is not None
+            else getattr(parent, "revenue_usd", None)
+        ),
+    )
+    token = _current_trace.set(context)
+    try:
+        yield context
+    finally:
+        _current_trace.reset(token)

ganivra-0.1.0/ganivra/instrumentation.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import functools
+import importlib
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+from .context import current_trace, new_id
+
+
+def _value(obj: Any, name: str, default: Any = None) -> Any:
+    if obj is None:
+        return default
+    if isinstance(obj, dict):
+        return obj.get(name, default)
+    return getattr(obj, name, default)
+
+
+def extract_usage(response: Any) -> dict[str, int]:
+    usage = _value(response, "usage")
+    input_tokens = int(_value(usage, "input_tokens", 0) or 0)
+    output_tokens = int(_value(usage, "output_tokens", 0) or 0)
+    details = _value(usage, "input_tokens_details")
+    cached_tokens = int(_value(details, "cached_tokens", 0) or 0)
+    total_tokens = int(
+        _value(usage, "total_tokens", input_tokens + output_tokens)
+        or input_tokens + output_tokens
+    )
+    return {
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "cached_tokens": cached_tokens,
+        "total_tokens": total_tokens,
+    }
+
+
+def build_event(
+    *,
+    response: Any,
+    requested_model: str | None,
+    latency_ms: float,
+    environment: str,
+    error: BaseException | None = None,
+) -> dict[str, Any]:
+    active_trace = current_trace()
+    usage = extract_usage(response) if error is None else extract_usage(None)
+    response_model = _value(response, "model")
+    return {
+        "event_id": new_id("evt"),
+        "execution_id": (
+            active_trace.execution_id if active_trace else new_id("exec")
+        ),
+        "step_id": new_id("step"),
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "provider": "openai",
+        "model": str(response_model or requested_model or "unknown"),
+        "operation": "responses.create",
+        **usage,
+        "latency_ms": round(max(latency_ms, 0), 3),
+        "status": "error" if error else "success",
+        "error_type": type(error).__name__ if error else None,
+        "environment": environment,
+        "attributes": active_trace.attributes() if active_trace else {},
+    }
+
+
+def _responses_class() -> type[Any] | None:
+    for module_name in (
+        "openai.resources.responses",
+        "openai.resources.responses.responses",
+    ):
+        try:
+            module = importlib.import_module(module_name)
+            candidate = getattr(module, "Responses", None)
+            if candidate is not None:
+                return candidate
+        except Exception:
+            continue
+    return None
+
+
+def instrument_openai(
+    get_environment: Callable[[], str],
+    enqueue: Callable[[dict[str, Any]], None],
+) -> bool:
+    responses_class = _responses_class()
+    if responses_class is None:
+        return False
+
+    original = getattr(responses_class, "create", None)
+    if original is None:
+        return False
+    if getattr(original, "_ganivra_instrumented", False):
+        return True
+
+    @functools.wraps(original)
+    def wrapped(self: Any, *args: Any, **kwargs: Any) -> Any:
+        started = time.perf_counter()
+        requested_model = kwargs.get("model")
+        try:
+            response = original(self, *args, **kwargs)
+        except BaseException as error:
+            try:
+                enqueue(
+                    build_event(
+                        response=None,
+                        requested_model=requested_model,
+                        latency_ms=(time.perf_counter() - started) * 1_000,
+                        environment=get_environment(),
+                        error=error,
+                    )
+                )
+            except Exception:
+                pass
+            raise
+
+        try:
+            enqueue(
+                build_event(
+                    response=response,
+                    requested_model=requested_model,
+                    latency_ms=(time.perf_counter() - started) * 1_000,
+                    environment=get_environment(),
+                )
+            )
+        except Exception:
+            pass
+        return response
+
+    setattr(wrapped, "_ganivra_instrumented", True)
+    setattr(wrapped, "_ganivra_original", original)
+    setattr(responses_class, "create", wrapped)
+    return True

ganivra-0.1.0/ganivra/py.typed

@@ -0,0 +1 @@
+

ganivra-0.1.0/ganivra/sender.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import json
+import queue
+import threading
+import time
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+from urllib.request import Request, urlopen
+
+from .config import Config
+
+
+def _user_agent() -> str:
+    try:
+        package_version = version("ganivra")
+    except PackageNotFoundError:
+        package_version = "development"
+    return f"ganivra-python/{package_version}"
+
+
+@dataclass(slots=True)
+class SenderStats:
+    queued: int = 0
+    sent: int = 0
+    dropped: int = 0
+    failed_batches: int = 0
+
+
+class BackgroundSender:
+    """Bounded, best-effort delivery that never raises on the caller thread."""
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+        self.queue: queue.Queue[dict[str, Any]] = queue.Queue(config.queue_size)
+        self.stats = SenderStats()
+        self._stop = threading.Event()
+        self._thread = threading.Thread(
+            target=self._run, name="ganivra-telemetry", daemon=True
+        )
+        self._thread.start()
+
+    def enqueue(self, event: dict[str, Any]) -> None:
+        try:
+            self.queue.put_nowait(event)
+            self.stats.queued += 1
+        except Exception:
+            self.stats.dropped += 1
+
+    def flush(self, timeout: float = 2.0) -> bool:
+        deadline = time.monotonic() + max(timeout, 0)
+        while self.queue.unfinished_tasks and time.monotonic() < deadline:
+            time.sleep(0.005)
+        return self.queue.unfinished_tasks == 0
+
+    def shutdown(self, timeout: float = 1.0) -> None:
+        self._stop.set()
+        self.flush(timeout)
+        self._thread.join(timeout=max(timeout, 0))
+
+    def _run(self) -> None:
+        while not self._stop.is_set() or not self.queue.empty():
+            try:
+                first = self.queue.get(timeout=0.1)
+            except queue.Empty:
+                continue
+            batch = [first]
+            while len(batch) < self.config.batch_size:
+                try:
+                    batch.append(self.queue.get_nowait())
+                except queue.Empty:
+                    break
+
+            delivered = False
+            try:
+                delivered = self._deliver(batch)
+            except Exception:
+                delivered = False
+            finally:
+                for _ in batch:
+                    self.queue.task_done()
+
+            if delivered:
+                self.stats.sent += len(batch)
+            else:
+                self.stats.dropped += len(batch)
+                self.stats.failed_batches += 1
+
+    def _deliver(self, events: list[dict[str, Any]]) -> bool:
+        payload = json.dumps({"events": events}, separators=(",", ":")).encode()
+        request = Request(
+            self.config.events_url,
+            data=payload,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.config.api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": _user_agent(),
+            },
+        )
+        for attempt in range(self.config.max_retries + 1):
+            try:
+                with urlopen(request, timeout=self.config.timeout_seconds) as response:
+                    if 200 <= response.status < 300:
+                        return True
+            except Exception:
+                pass
+            if attempt < self.config.max_retries:
+                time.sleep(0.1 * (2**attempt))
+        return False

ganivra-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ganivra"
+version = "0.1.0"
+description = "AI execution cost and unit-economics telemetry for the OpenAI Python SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ganivra" }]
+keywords = ["ai", "llm", "openai", "observability", "cost", "unit-economics"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = ["openai>=1.50"]
+
+[project.urls]
+Homepage = "https://ganivra.com"
+Documentation = "https://ganivra.com"
+
+[project.optional-dependencies]
+test = ["pytest>=8.0"]
+release = ["build>=1.2", "twine>=6.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["ganivra"]
+
+[tool.hatch.build.targets.sdist]
+include = ["ganivra", "tests", "README.md", "LICENSE", "pyproject.toml"]

ganivra-0.1.0/tests/test_sdk.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import json
+import threading
+from types import SimpleNamespace
+
+import pytest
+
+import ganivra
+from ganivra.config import Config
+from ganivra.context import trace
+from ganivra.instrumentation import build_event, extract_usage, instrument_openai
+from ganivra.sender import BackgroundSender
+
+
+def test_initialization_validates_configuration(monkeypatch: pytest.MonkeyPatch) -> None:
+    created: list[Config] = []
+
+    class FakeSender:
+        def __init__(self, config: Config) -> None:
+            created.append(config)
+
+        def shutdown(self, timeout: float) -> None:
+            pass
+
+        def flush(self, timeout: float) -> bool:
+            return True
+
+    monkeypatch.setattr(ganivra, "BackgroundSender", FakeSender)
+    monkeypatch.setattr(ganivra, "instrument_openai", lambda *_: True)
+    ganivra.init(api_key="test_key", endpoint="http://localhost:8000", environment="test")
+
+    assert created[-1].events_url == "http://localhost:8000/v1/events"
+    assert created[-1].environment == "test"
+    with pytest.raises(ValueError):
+        ganivra.init(api_key="", endpoint="http://localhost:8000")
+
+
+def test_extracts_response_usage_including_cached_tokens() -> None:
+    response = SimpleNamespace(
+        usage=SimpleNamespace(
+            input_tokens=120,
+            output_tokens=30,
+            total_tokens=150,
+            input_tokens_details=SimpleNamespace(cached_tokens=80),
+        )
+    )
+    assert extract_usage(response) == {
+        "input_tokens": 120,
+        "output_tokens": 30,
+        "cached_tokens": 80,
+        "total_tokens": 150,
+    }
+
+
+def test_trace_context_propagates_and_reuses_execution_id() -> None:
+    with trace(
+        workflow="support_answer",
+        feature="chat",
+        customer_id="acme",
+        prompt_id="support_answer",
+        prompt_version="v17",
+        revenue_usd=0.10,
+    ) as ctx:
+        first = build_event(
+            response={"model": "gpt-5", "usage": {}},
+            requested_model=None,
+            latency_ms=1,
+            environment="test",
+        )
+        second = build_event(
+            response={"model": "gpt-5", "usage": {}},
+            requested_model=None,
+            latency_ms=1,
+            environment="test",
+        )
+
+    assert first["execution_id"] == second["execution_id"] == ctx.execution_id
+    assert first["attributes"] == {
+        "workflow": "support_answer",
+        "feature": "chat",
+        "customer_id": "acme",
+        "prompt_id": "support_answer",
+        "prompt_version": "v17",
+        "revenue_usd": 0.10,
+    }
+    assert first["step_id"] != second["step_id"]
+
+
+def test_call_without_trace_gets_an_execution_id() -> None:
+    event = build_event(
+        response={"model": "gpt-5", "usage": {}},
+        requested_model=None,
+        latency_ms=1,
+        environment="test",
+    )
+    assert event["execution_id"].startswith("exec_")
+
+
+def test_openai_instrumentation_observes_success_and_error(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    events: list[dict] = []
+
+    class Responses:
+        def create(self, **kwargs):
+            if kwargs.get("model") == "broken":
+                raise RuntimeError("provider failed")
+            return SimpleNamespace(
+                model=kwargs["model"],
+                usage=SimpleNamespace(input_tokens=10, output_tokens=2, total_tokens=12),
+            )
+
+    monkeypatch.setattr("ganivra.instrumentation._responses_class", lambda: Responses)
+    assert instrument_openai(lambda: "test", events.append)
+
+    response = Responses().create(model="gpt-5", input="secret prompt")
+    assert response.model == "gpt-5"
+    assert events[0]["operation"] == "responses.create"
+    assert events[0]["input_tokens"] == 10
+    assert "secret prompt" not in json.dumps(events[0])
+
+    with pytest.raises(RuntimeError, match="provider failed"):
+        Responses().create(model="broken", input="also secret")
+    assert events[1]["status"] == "error"
+    assert events[1]["error_type"] == "RuntimeError"
+
+
+def test_telemetry_failure_never_changes_openai_result(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    expected = object()
+
+    class Responses:
+        def create(self, **kwargs):
+            return expected
+
+    def unavailable(_: dict) -> None:
+        raise OSError("telemetry unavailable")
+
+    monkeypatch.setattr("ganivra.instrumentation._responses_class", lambda: Responses)
+    instrument_openai(lambda: "test", unavailable)
+    assert Responses().create(model="gpt-5", input="hello") is expected
+
+
+def test_background_sender_posts_batches(monkeypatch: pytest.MonkeyPatch) -> None:
+    received: list[tuple[str | None, dict]] = []
+    ready = threading.Event()
+
+    class Response:
+        status = 202
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *_):
+            return False
+
+    def fake_urlopen(request, timeout):
+        received.append(
+            (request.get_header("Authorization"), json.loads(request.data.decode()))
+        )
+        ready.set()
+        return Response()
+
+    monkeypatch.setattr("ganivra.sender.urlopen", fake_urlopen)
+    sender = BackgroundSender(
+        Config(
+            api_key="workspace_secret",
+            endpoint="http://telemetry.test",
+            max_retries=0,
+        )
+    )
+    try:
+        sender.enqueue({"event_id": "evt_1"})
+        assert ready.wait(2)
+        assert sender.flush(1)
+        assert received == [
+            ("Bearer workspace_secret", {"events": [{"event_id": "evt_1"}]})
+        ]
+    finally:
+        sender.shutdown()