doppel-sdk 0.1.0__py3-none-any.whl

doppel_sdk/__init__.py

@@ -0,0 +1,34 @@
+"""Official Doppel Python SDK.
+
+Wrap your existing provider client and every LLM call is captured and forwarded
+to Doppel — no change to your call sites.
+
+    from doppel_sdk import DoppelClient
+    from openai import OpenAI
+
+    doppel = DoppelClient(shadow_model="gpt-4o-mini")  # reads DOPPEL_API_KEY
+    client = doppel.wrap_openai(OpenAI())
+    client.chat.completions.create(model="gpt-4o", messages=[...])
+"""
+
+from __future__ import annotations
+
+from ._config import ImpactConfig
+from ._transport import flush
+from .client import DoppelClient
+from .interceptors.anthropic import wrap_anthropic
+from .interceptors.google import wrap_google
+from .interceptors.openai import wrap_openai
+from .interceptors.openrouter import wrap_openrouter
+
+__all__ = [
+    "DoppelClient",
+    "ImpactConfig",
+    "wrap_openai",
+    "wrap_openrouter",
+    "wrap_anthropic",
+    "wrap_google",
+    "flush",
+]
+
+__version__ = "0.1.0"

doppel_sdk/_config.py

@@ -0,0 +1,61 @@
+"""Configuration resolution for the Doppel SDK."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+DEFAULT_SERVER_URL = "https://api.doppel.in"
+
+
+@dataclass(frozen=True)
+class ImpactConfig:
+    """Fully-resolved configuration consumed by the interceptors."""
+
+    api_key: str
+    server_url: str
+    shadow_model: Optional[str]
+    debug: bool
+
+
+def _read_env(name: str) -> Optional[str]:
+    value = os.environ.get(name)
+    return value or None
+
+
+def _resolve_debug(option_debug: Optional[bool]) -> bool:
+    if option_debug is not None:
+        return option_debug
+    env = (_read_env("DOPPEL_DEBUG") or "").lower()
+    return env in ("1", "true")
+
+
+def resolve_config(
+    api_key: Optional[str] = None,
+    server_url: Optional[str] = None,
+    shadow_model: Optional[str] = None,
+    debug: Optional[bool] = None,
+) -> ImpactConfig:
+    """Resolve user-supplied options together with environment variables.
+
+    Resolution order (highest priority first):
+      - api_key      -> argument  >  DOPPEL_API_KEY
+      - server_url   -> argument  >  DOPPEL_SERVER_URL  >  https://api.doppel.in
+      - shadow_model -> argument (optional; chosen in the dashboard when omitted)
+      - debug        -> argument  >  DOPPEL_DEBUG ('1'/'true')
+    """
+    key = api_key or _read_env("DOPPEL_API_KEY")
+    if not key:
+        raise ValueError(
+            "[DoppelClient] Missing API key. Set the DOPPEL_API_KEY environment "
+            "variable (recommended) or pass api_key=... to DoppelClient()."
+        )
+
+    url = server_url or _read_env("DOPPEL_SERVER_URL") or DEFAULT_SERVER_URL
+    return ImpactConfig(
+        api_key=key,
+        server_url=url,
+        shadow_model=shadow_model,
+        debug=_resolve_debug(debug),
+    )

doppel_sdk/_transport.py

@@ -0,0 +1,81 @@
+"""Fire-and-forget run delivery.
+
+Runs are POSTed on a background thread pool so capture never blocks (or fails)
+the caller's request path. ``flush`` awaits in-flight deliveries before a
+short-lived process exits. Uses only the standard library — no dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.error
+import urllib.request
+from concurrent.futures import Future, ThreadPoolExecutor
+from typing import Any, Dict, Optional, Set
+
+from ._config import ImpactConfig
+
+logger = logging.getLogger("doppel_sdk")
+
+_SEND_TIMEOUT_SECONDS = 10
+_executor = ThreadPoolExecutor(max_workers=4, thread_name_prefix="doppel-sdk")
+_inflight: Set["Future[None]"] = set()
+
+
+def send_run(payload: Dict[str, Any], config: ImpactConfig) -> None:
+    """Queue a run for fire-and-forget delivery. Never raises."""
+    # Drop None values so the JSON matches the JS payloads (omitted, not null).
+    body = {k: v for k, v in payload.items() if v is not None}
+    try:
+        future = _executor.submit(_deliver, body, config)
+    except Exception as err:  # executor shut down, etc. — never raise into caller
+        logger.warning("[doppel-sdk] Failed to queue run (non-blocking): %s", err)
+        return
+    _inflight.add(future)
+    future.add_done_callback(_inflight.discard)
+
+
+def _deliver(payload: Dict[str, Any], config: ImpactConfig) -> None:
+    url = config.server_url.rstrip("/") + "/runs"
+    if config.debug:
+        logger.info("[doppel-sdk] Sending run to: %s", url)
+    try:
+        data = json.dumps(payload, default=_to_jsonable).encode("utf-8")
+        request = urllib.request.Request(
+            url,
+            data=data,
+            method="POST",
+            headers={"Content-Type": "application/json", "x-api-key": config.api_key},
+        )
+        with urllib.request.urlopen(request, timeout=_SEND_TIMEOUT_SECONDS) as resp:
+            status = getattr(resp, "status", None) or resp.getcode()
+            if status and status >= 400:
+                logger.warning("[doppel-sdk] Server returned non-OK: %s", status)
+            elif config.debug:
+                logger.info("[doppel-sdk] Run sent successfully: %s", status)
+    except urllib.error.HTTPError as err:
+        logger.warning("[doppel-sdk] Server returned non-OK: %s %s", err.code, err.reason)
+    except Exception as err:  # network/serialisation — never raise into caller
+        logger.warning("[doppel-sdk] Failed to send run (non-blocking): %s", err)
+
+
+def _to_jsonable(obj: Any) -> Any:
+    """Best-effort fallback for provider message objects that aren't plain dicts."""
+    for attr in ("model_dump", "dict", "to_dict"):
+        method = getattr(obj, attr, None)
+        if callable(method):
+            try:
+                return method()
+            except Exception:
+                pass
+    return str(obj)
+
+
+def flush(timeout: Optional[float] = None) -> None:
+    """Block until all in-flight run deliveries settle. Never raises."""
+    for future in list(_inflight):
+        try:
+            future.result(timeout)
+        except Exception:
+            pass

doppel_sdk/_utils.py

@@ -0,0 +1,40 @@
+"""Small shared helpers for the interceptors."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+logger = logging.getLogger("doppel_sdk")
+
+
+def attr(obj: Any, name: str) -> Any:
+    """Read a field from a provider object whether it's a mapping or an object.
+
+    Real provider SDKs return pydantic models (attribute access); tests and some
+    runtimes use plain dicts. This tolerates both, returning None when absent.
+    """
+    if obj is None:
+        return None
+    if isinstance(obj, dict):
+        return obj.get(name)
+    return getattr(obj, name, None)
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def warn_capture(provider: str, err: Exception) -> None:
+    logger.warning(
+        "[doppel-sdk] Failed to capture %s run (non-blocking): %s", provider, err
+    )
+
+
+def is_sync_stream(obj: Any) -> bool:
+    return hasattr(obj, "__iter__") and not isinstance(obj, (str, bytes, list, tuple, dict))
+
+
+def is_async_stream(obj: Any) -> bool:
+    return hasattr(obj, "__aiter__")

doppel_sdk/client.py

@@ -0,0 +1,53 @@
+"""The DoppelClient facade."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from ._config import ImpactConfig, resolve_config
+from ._transport import flush as _flush
+from .interceptors.anthropic import wrap_anthropic
+from .interceptors.google import wrap_google
+from .interceptors.openai import wrap_openai
+from .interceptors.openrouter import wrap_openrouter
+
+
+class DoppelClient:
+    """Wraps provider clients so every LLM call is captured and sent to Doppel.
+
+    Configuration is read from arguments or the ``DOPPEL_API_KEY`` /
+    ``DOPPEL_SERVER_URL`` / ``DOPPEL_DEBUG`` environment variables.
+
+        doppel = DoppelClient(shadow_model="gpt-4o-mini")
+        client = doppel.wrap_openai(OpenAI())
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        shadow_model: Optional[str] = None,
+        server_url: Optional[str] = None,
+        debug: Optional[bool] = None,
+    ) -> None:
+        self._config: ImpactConfig = resolve_config(
+            api_key=api_key,
+            server_url=server_url,
+            shadow_model=shadow_model,
+            debug=debug,
+        )
+
+    def wrap_openai(self, client: Any) -> Any:
+        return wrap_openai(client, self._config)
+
+    def wrap_openrouter(self, client: Any) -> Any:
+        return wrap_openrouter(client, self._config)
+
+    def wrap_anthropic(self, client: Any) -> Any:
+        return wrap_anthropic(client, self._config)
+
+    def wrap_google(self, client: Any) -> Any:
+        return wrap_google(client, self._config)
+
+    def flush(self, timeout: Optional[float] = None) -> None:
+        """Block until all pending run deliveries settle. Never raises."""
+        _flush(timeout)

doppel_sdk/interceptors/__init__.py

@@ -0,0 +1 @@
+"""Provider interceptors for the Doppel SDK."""

doppel_sdk/interceptors/_openai_compat.py

@@ -0,0 +1,157 @@
+"""Shared engine for OpenAI-wire-compatible providers (OpenAI, OpenRouter).
+
+Handles sync and async clients (detected by whether ``create`` returns an
+awaitable) and both streaming and non-streaming calls. ``wrap_openai`` and
+``wrap_openrouter`` are thin presets over this.
+"""
+
+from __future__ import annotations
+
+import inspect
+import time
+from typing import Any, Dict, Optional
+
+from .._config import ImpactConfig
+from .._transport import send_run
+from .._utils import attr, is_async_stream, is_sync_stream, now_iso, warn_capture
+from ._stream import capture_async_stream, capture_sync_stream
+
+_MARKER = "_doppel_wrapped_openai_compat"
+
+
+def _vendor_from_model(model: Optional[str]) -> Optional[str]:
+    """OpenRouter model ids are namespaced `<author>/<model>` — return the author."""
+    if not model or "/" not in model:
+        return None
+    return model.split("/")[0].lower()
+
+
+def _chunk_content(chunk: Any) -> Optional[str]:
+    choices = attr(chunk, "choices")
+    if not choices:
+        return None
+    return attr(attr(choices[0], "delta"), "content")
+
+
+def _response_answer(response: Any) -> str:
+    choices = attr(response, "choices")
+    if not choices:
+        return ""
+    return attr(attr(choices[0], "message"), "content") or ""
+
+
+class _Spec:
+    def __init__(self, provider: str, derive_vendor: bool, capture_cost: bool):
+        self.provider = provider
+        self.derive_vendor = derive_vendor
+        self.capture_cost = capture_cost
+
+
+def wrap_openai_compatible(
+    client: Any,
+    config: ImpactConfig,
+    *,
+    provider: str,
+    derive_vendor: bool = False,
+    capture_cost: bool = False,
+) -> Any:
+    spec = _Spec(provider, derive_vendor, capture_cost)
+
+    try:
+        completions = client.chat.completions
+        original = completions.create
+    except AttributeError:
+        return client  # not an OpenAI-shaped client
+
+    if getattr(original, _MARKER, False):
+        return client
+
+    def emit(kwargs: Dict[str, Any], meta: Dict[str, Any], answer: str, usage: Any, model: Optional[str], start: float) -> None:
+        try:
+            payload: Dict[str, Any] = {
+                "timestamp": now_iso(),
+                "sessionId": meta.get("sessionId"),
+                "model": model or kwargs.get("model") or "",
+                "shadowModel": config.shadow_model,
+                "temperature": kwargs.get("temperature"),
+                "messages": kwargs.get("messages"),
+                "pdfCharsSent": meta.get("pdfCharsSent"),
+                "question": meta.get("question"),
+                "answer": answer,
+                "promptTokens": attr(usage, "prompt_tokens") or 0,
+                "completionTokens": attr(usage, "completion_tokens") or 0,
+                "totalTokens": attr(usage, "total_tokens") or 0,
+                "durationMs": int((time.time() - start) * 1000),
+            }
+            if spec.provider == "openrouter":
+                payload["provider"] = "openrouter"
+                if spec.derive_vendor:
+                    vendor = _vendor_from_model(payload["model"])
+                    if vendor:
+                        payload["vendor"] = vendor
+                if spec.capture_cost:
+                    cost = attr(usage, "cost")
+                    if cost is not None:
+                        payload["cost"] = cost
+            else:
+                payload["type"] = "llm-response"
+            send_run(payload, config)
+        except Exception as err:
+            warn_capture(spec.provider, err)
+
+    def stream_callbacks(kwargs: Dict[str, Any], meta: Dict[str, Any], start: float):
+        state: Dict[str, Any] = {"answer": "", "model": kwargs.get("model"), "usage": None}
+
+        def on_chunk(chunk: Any) -> None:
+            content = _chunk_content(chunk)
+            if isinstance(content, str):
+                state["answer"] += content
+            usage = attr(chunk, "usage")
+            if usage is not None:
+                state["usage"] = usage
+            model = attr(chunk, "model")
+            if model:
+                state["model"] = model
+
+        def on_done() -> None:
+            emit(kwargs, meta, state["answer"], state["usage"], state["model"], start)
+
+        return on_chunk, on_done
+
+    def patched(*args: Any, **kwargs: Any) -> Any:
+        meta = kwargs.pop("_impact_meta", None) or {}
+        is_streaming = bool(kwargs.get("stream"))
+
+        # Streams only report usage when stream_options.include_usage is set.
+        if is_streaming and "stream_options" not in kwargs:
+            kwargs = dict(kwargs)
+            kwargs["stream_options"] = {"include_usage": True}
+
+        start = time.time()
+        result = original(*args, **kwargs)
+
+        if inspect.isawaitable(result):
+            async def run_async() -> Any:
+                resolved = await result
+                if is_streaming:
+                    if not is_async_stream(resolved):
+                        return resolved
+                    on_chunk, on_done = stream_callbacks(kwargs, meta, start)
+                    return capture_async_stream(resolved, on_chunk, on_done)
+                emit(kwargs, meta, _response_answer(resolved), attr(resolved, "usage"), kwargs.get("model"), start)
+                return resolved
+
+            return run_async()
+
+        if is_streaming:
+            if not is_sync_stream(result):
+                return result
+            on_chunk, on_done = stream_callbacks(kwargs, meta, start)
+            return capture_sync_stream(result, on_chunk, on_done)
+
+        emit(kwargs, meta, _response_answer(result), attr(result, "usage"), kwargs.get("model"), start)
+        return result
+
+    setattr(patched, _MARKER, True)
+    completions.create = patched
+    return client

doppel_sdk/interceptors/_stream.py

@@ -0,0 +1,100 @@
+"""Streaming capture proxies.
+
+A provider stream is single-consumption, so we tee it: each chunk reaches both
+the caller and an accumulator, and a capture callback fires once iteration ends
+(or the caller abandons it). The proxy delegates every other attribute/method to
+the underlying stream so context-manager and helper methods keep working.
+"""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Callable, Iterator
+
+
+class _BaseStreamProxy:
+    def __init__(self, stream: Any, on_chunk: Callable[[Any], None], on_done: Callable[[], None]):
+        self._stream = stream
+        self._on_chunk = on_chunk
+        self._on_done = on_done
+        self._finished = False
+
+    def _finish(self) -> None:
+        if self._finished:
+            return
+        self._finished = True
+        try:
+            self._on_done()
+        except Exception:  # capture must never throw into the caller
+            pass
+
+    def _feed(self, chunk: Any) -> None:
+        try:
+            self._on_chunk(chunk)
+        except Exception:  # a bad chunk must not break iteration
+            pass
+
+    # Delegate everything else (e.g. `.response`, `.close()`) to the real stream.
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._stream, name)
+
+
+class SyncStreamProxy(_BaseStreamProxy):
+    def __iter__(self) -> Iterator[Any]:
+        return self._iterate()
+
+    def _iterate(self) -> Iterator[Any]:
+        try:
+            for chunk in self._stream:
+                self._feed(chunk)
+                yield chunk
+        finally:
+            self._finish()
+
+    def __enter__(self) -> "SyncStreamProxy":
+        enter = getattr(self._stream, "__enter__", None)
+        if callable(enter):
+            enter()
+        return self
+
+    def __exit__(self, *exc: Any) -> Any:
+        result = None
+        exit_ = getattr(self._stream, "__exit__", None)
+        if callable(exit_):
+            result = exit_(*exc)
+        self._finish()
+        return result
+
+
+class AsyncStreamProxy(_BaseStreamProxy):
+    def __aiter__(self) -> AsyncIterator[Any]:
+        return self._aiterate()
+
+    async def _aiterate(self) -> AsyncIterator[Any]:
+        try:
+            async for chunk in self._stream:
+                self._feed(chunk)
+                yield chunk
+        finally:
+            self._finish()
+
+    async def __aenter__(self) -> "AsyncStreamProxy":
+        aenter = getattr(self._stream, "__aenter__", None)
+        if aenter is not None:
+            await aenter()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> Any:
+        result = None
+        aexit = getattr(self._stream, "__aexit__", None)
+        if aexit is not None:
+            result = await aexit(*exc)
+        self._finish()
+        return result
+
+
+def capture_sync_stream(stream: Any, on_chunk: Callable[[Any], None], on_done: Callable[[], None]) -> SyncStreamProxy:
+    return SyncStreamProxy(stream, on_chunk, on_done)
+
+
+def capture_async_stream(stream: Any, on_chunk: Callable[[Any], None], on_done: Callable[[], None]) -> AsyncStreamProxy:
+    return AsyncStreamProxy(stream, on_chunk, on_done)

doppel_sdk/interceptors/anthropic.py

@@ -0,0 +1,127 @@
+"""Anthropic interceptor (``messages.create``), sync + async, streaming-aware."""
+
+from __future__ import annotations
+
+import inspect
+import time
+from typing import Any, Dict, Optional
+
+from .._config import ImpactConfig
+from .._transport import send_run
+from .._utils import attr, is_async_stream, is_sync_stream, warn_capture
+from ._stream import capture_async_stream, capture_sync_stream
+
+_MARKER = "_doppel_wrapped_anthropic"
+
+
+def _content_to_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return "".join(b if isinstance(b, str) else (attr(b, "text") or "") for b in content)
+    return ""
+
+
+def _prompt_from_messages(messages: Any) -> str:
+    if not messages:
+        return ""
+    return "\n".join(_content_to_text(attr(m, "content")) for m in messages)
+
+
+def _response_output(response: Any) -> str:
+    blocks = attr(response, "content") or []
+    return "".join(attr(b, "text") or "" for b in blocks if attr(b, "type") == "text")
+
+
+def wrap_anthropic(client: Any, config: ImpactConfig) -> Any:
+    """Intercept an ``Anthropic``/``AsyncAnthropic`` client's ``messages.create``."""
+    try:
+        messages_ns = client.messages
+        original = messages_ns.create
+    except AttributeError:
+        return client
+    if getattr(original, _MARKER, False):
+        return client
+
+    def emit(prompt: str, output: str, prompt_tokens: Optional[int], completion_tokens: Optional[int], model: Optional[str], kwargs: Dict[str, Any], start: float) -> None:
+        try:
+            total = (prompt_tokens or 0) + (completion_tokens or 0)
+            send_run(
+                {
+                    "prompt": prompt,
+                    "model": model or kwargs.get("model") or "",
+                    "shadowModel": config.shadow_model,
+                    "promptTokens": prompt_tokens or 0,
+                    "completionTokens": completion_tokens or 0,
+                    "totalTokens": total,
+                    "primaryResponse": {
+                        "output": output,
+                        "latencyMs": int((time.time() - start) * 1000),
+                        "tokens": total,
+                    },
+                },
+                config,
+            )
+        except Exception as err:
+            warn_capture("Anthropic", err)
+
+    def stream_callbacks(prompt: str, kwargs: Dict[str, Any], start: float):
+        state: Dict[str, Any] = {"output": "", "prompt_tokens": 0, "completion_tokens": 0, "model": kwargs.get("model")}
+
+        def on_chunk(event: Any) -> None:
+            etype = attr(event, "type")
+            if etype == "message_start":
+                message = attr(event, "message")
+                input_tokens = attr(attr(message, "usage"), "input_tokens")
+                if input_tokens is not None:
+                    state["prompt_tokens"] = input_tokens
+                model = attr(message, "model")
+                if model:
+                    state["model"] = model
+            elif etype == "content_block_delta":
+                text = attr(attr(event, "delta"), "text")
+                if isinstance(text, str):
+                    state["output"] += text
+            elif etype == "message_delta":
+                output_tokens = attr(attr(event, "usage"), "output_tokens")
+                if output_tokens is not None:
+                    state["completion_tokens"] = output_tokens
+
+        def on_done() -> None:
+            emit(prompt, state["output"], state["prompt_tokens"], state["completion_tokens"], state["model"], kwargs, start)
+
+        return on_chunk, on_done
+
+    def patched(*args: Any, **kwargs: Any) -> Any:
+        is_streaming = bool(kwargs.get("stream"))
+        prompt = _prompt_from_messages(kwargs.get("messages"))
+        start = time.time()
+        result = original(*args, **kwargs)
+
+        if inspect.isawaitable(result):
+            async def run_async() -> Any:
+                resolved = await result
+                if is_streaming:
+                    if not is_async_stream(resolved):
+                        return resolved
+                    on_chunk, on_done = stream_callbacks(prompt, kwargs, start)
+                    return capture_async_stream(resolved, on_chunk, on_done)
+                usage = attr(resolved, "usage")
+                emit(prompt, _response_output(resolved), attr(usage, "input_tokens"), attr(usage, "output_tokens"), attr(resolved, "model"), kwargs, start)
+                return resolved
+
+            return run_async()
+
+        if is_streaming:
+            if not is_sync_stream(result):
+                return result
+            on_chunk, on_done = stream_callbacks(prompt, kwargs, start)
+            return capture_sync_stream(result, on_chunk, on_done)
+
+        usage = attr(result, "usage")
+        emit(prompt, _response_output(result), attr(usage, "input_tokens"), attr(usage, "output_tokens"), attr(result, "model"), kwargs, start)
+        return result
+
+    setattr(patched, _MARKER, True)
+    messages_ns.create = patched
+    return client

doppel_sdk/interceptors/google.py

@@ -0,0 +1,196 @@
+"""Google Gemini interceptor.
+
+Supports the new ``google-genai`` SDK (sync ``client.models`` + async
+``client.aio.models``, with ``generate_content`` / ``generate_content_stream``)
+and the legacy ``google-generativeai`` SDK (a ``GenerativeModel`` whose
+``generate_content`` takes ``stream=`` and which also exposes
+``generate_content_async``).
+"""
+
+from __future__ import annotations
+
+import inspect
+import time
+from typing import Any, Optional
+
+from .._config import ImpactConfig
+from .._transport import send_run
+from .._utils import attr, is_async_stream, is_sync_stream, now_iso, warn_capture
+from ._stream import capture_async_stream, capture_sync_stream
+
+_MARKER = "_doppel_wrapped_google"
+
+
+def _contents_to_text(contents: Any) -> str:
+    if contents is None:
+        return ""
+    if isinstance(contents, str):
+        return contents
+    if isinstance(contents, list):
+        return "\n".join(_contents_to_text(c) for c in contents)
+    text = attr(contents, "text")
+    if isinstance(text, str):
+        return text
+    parts = attr(contents, "parts")
+    if parts is not None:
+        return _contents_to_text(parts)
+    nested = attr(contents, "content")
+    if nested is not None:
+        return _contents_to_text(nested)
+    return ""
+
+
+def _text(obj: Any) -> str:
+    """`.text` is a property that can raise on non-text chunks — guard it."""
+    try:
+        value = attr(obj, "text")
+        return value if isinstance(value, str) else ""
+    except Exception:
+        return ""
+
+
+def _emit(config: ImpactConfig, contents: Any, answer: str, usage: Any, model: Optional[str], start: float) -> None:
+    try:
+        prompt_tokens = attr(usage, "prompt_token_count") or 0
+        completion_tokens = attr(usage, "candidates_token_count") or 0
+        total_tokens = attr(usage, "total_token_count")
+        send_run(
+            {
+                "provider": "google",
+                "timestamp": now_iso(),
+                "model": model or "",
+                "shadowModel": config.shadow_model,
+                "prompt": _contents_to_text(contents),
+                "answer": answer,
+                "promptTokens": prompt_tokens,
+                "completionTokens": completion_tokens,
+                "totalTokens": total_tokens if total_tokens is not None else prompt_tokens + completion_tokens,
+                "durationMs": int((time.time() - start) * 1000),
+            },
+            config,
+        )
+    except Exception as err:
+        warn_capture("Google", err)
+
+
+def _stream_callbacks(config: ImpactConfig, contents: Any, model: Optional[str], start: float):
+    state = {"answer": "", "usage": None, "model": model}
+
+    def on_chunk(chunk: Any) -> None:
+        state["answer"] += _text(chunk)
+        usage = attr(chunk, "usage_metadata")
+        if usage is not None:
+            state["usage"] = usage
+
+    def on_done() -> None:
+        _emit(config, contents, state["answer"], state["usage"], state["model"], start)
+
+    return on_chunk, on_done
+
+
+def _patch(namespace: Any, attr_name: str, builder: Any) -> None:
+    original = getattr(namespace, attr_name, None)
+    if not callable(original) or getattr(original, _MARKER, False):
+        return
+    patched = builder(original)
+    setattr(patched, _MARKER, True)
+    setattr(namespace, attr_name, patched)
+
+
+def _wrap_genai_namespace(ns: Any, config: ImpactConfig) -> None:
+    def unary(original):
+        def patched(*args, **kwargs):
+            start = time.time()
+            contents, model = kwargs.get("contents"), kwargs.get("model")
+            result = original(*args, **kwargs)
+            if inspect.isawaitable(result):
+                async def run():
+                    resolved = await result
+                    _emit(config, contents, _text(resolved), attr(resolved, "usage_metadata"), model, start)
+                    return resolved
+                return run()
+            _emit(config, contents, _text(result), attr(result, "usage_metadata"), model, start)
+            return result
+        return patched
+
+    def streaming(original):
+        def patched(*args, **kwargs):
+            start = time.time()
+            contents, model = kwargs.get("contents"), kwargs.get("model")
+            result = original(*args, **kwargs)
+            if inspect.isawaitable(result):
+                async def run():
+                    resolved = await result
+                    if not is_async_stream(resolved):
+                        return resolved
+                    on_chunk, on_done = _stream_callbacks(config, contents, model, start)
+                    return capture_async_stream(resolved, on_chunk, on_done)
+                return run()
+            if not is_sync_stream(result):
+                return result
+            on_chunk, on_done = _stream_callbacks(config, contents, model, start)
+            return capture_sync_stream(result, on_chunk, on_done)
+        return patched
+
+    _patch(ns, "generate_content", unary)
+    _patch(ns, "generate_content_stream", streaming)
+
+
+def _wrap_legacy_model(model: Any, config: ImpactConfig) -> None:
+    model_name = attr(model, "model_name")
+
+    def _contents(args, kwargs):
+        return args[0] if args else kwargs.get("contents")
+
+    def sync_gen(original):
+        def patched(*args, **kwargs):
+            start = time.time()
+            contents = _contents(args, kwargs)
+            result = original(*args, **kwargs)
+            if bool(kwargs.get("stream")) and is_sync_stream(result):
+                on_chunk, on_done = _stream_callbacks(config, contents, model_name, start)
+                return capture_sync_stream(result, on_chunk, on_done)
+            _emit(config, contents, _text(result), attr(result, "usage_metadata"), model_name, start)
+            return result
+        return patched
+
+    def async_gen(original):
+        def patched(*args, **kwargs):
+            start = time.time()
+            contents = _contents(args, kwargs)
+            streaming = bool(kwargs.get("stream"))
+            result = original(*args, **kwargs)
+            async def run():
+                resolved = await result
+                if streaming and is_async_stream(resolved):
+                    on_chunk, on_done = _stream_callbacks(config, contents, model_name, start)
+                    return capture_async_stream(resolved, on_chunk, on_done)
+                _emit(config, contents, _text(resolved), attr(resolved, "usage_metadata"), model_name, start)
+                return resolved
+            return run()
+        return patched
+
+    _patch(model, "generate_content", sync_gen)
+    _patch(model, "generate_content_async", async_gen)
+
+
+def wrap_google(client: Any, config: ImpactConfig) -> Any:
+    """Wrap a Google Gemini client (new ``google-genai`` or legacy
+    ``google-generativeai``). Returns the same client, mutated in place."""
+    models = getattr(client, "models", None)
+    if models is not None and hasattr(models, "generate_content"):
+        _wrap_genai_namespace(models, config)
+        aio = getattr(client, "aio", None)
+        aio_models = getattr(aio, "models", None) if aio is not None else None
+        if aio_models is not None:
+            _wrap_genai_namespace(aio_models, config)
+        return client
+
+    if hasattr(client, "generate_content"):
+        _wrap_legacy_model(client, config)
+        return client
+
+    raise ValueError(
+        "[doppel-sdk] wrap_google: unrecognised Google client. Pass a genai "
+        "Client (google-genai) or a GenerativeModel (google-generativeai)."
+    )

doppel_sdk/interceptors/openai.py

@@ -0,0 +1,17 @@
+"""OpenAI interceptor (and the OpenAI-compatible family)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._config import ImpactConfig
+from ._openai_compat import wrap_openai_compatible
+
+
+def wrap_openai(client: Any, config: ImpactConfig) -> Any:
+    """Intercept an ``OpenAI``/``AsyncOpenAI`` client's ``chat.completions.create``.
+
+    Captures sync and async calls, streaming and non-streaming. Returns the same
+    client (mutated in place); wrapping is idempotent.
+    """
+    return wrap_openai_compatible(client, config, provider="openai")

doppel_sdk/interceptors/openrouter.py

@@ -0,0 +1,20 @@
+"""OpenRouter interceptor — OpenAI-wire-compatible with vendor + cost capture."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._config import ImpactConfig
+from ._openai_compat import wrap_openai_compatible
+
+
+def wrap_openrouter(client: Any, config: ImpactConfig) -> Any:
+    """Intercept an OpenAI SDK client pointed at OpenRouter.
+
+    Tags runs as ``provider='openrouter'``, derives the model author as
+    ``vendor`` from the namespaced model id, and captures OpenRouter's real USD
+    ``usage.cost`` when present. Handles sync/async and streaming.
+    """
+    return wrap_openai_compatible(
+        client, config, provider="openrouter", derive_vendor=True, capture_cost=True
+    )

doppel_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: doppel-sdk
+Version: 0.1.0
+Summary: Official Doppel Python SDK
+License: MIT
+Keywords: api,doppel,llm,sdk,shadow,testing
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# doppel-sdk — Python
+
+Official Doppel SDK for Python. Wrap your existing LLM client and every call is
+captured and forwarded to Doppel — no change to your call sites.
+
+Supports **OpenAI**, **OpenRouter** (and the OpenAI-compatible family: DeepSeek,
+Qwen, Grok, Mistral, …), **Anthropic**, and **Google Gemini** — across **sync
+and async** clients, and **streaming and non-streaming** calls. Zero runtime
+dependencies.
+
+## Install
+
+```bash
+pip install doppel-sdk
+```
+
+## Usage
+
+```python
+from doppel_sdk import DoppelClient
+from openai import OpenAI
+
+# Reads DOPPEL_API_KEY from the environment (or pass api_key=...).
+doppel = DoppelClient(shadow_model="gpt-4o-mini")
+
+client = doppel.wrap_openai(OpenAI())
+client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+Other providers:
+
+```python
+doppel.wrap_anthropic(Anthropic())        # messages.create
+doppel.wrap_google(genai.Client())        # google-genai (or a GenerativeModel)
+doppel.wrap_openrouter(OpenAI(base_url=".../openrouter"))
+```
+
+Async clients (`AsyncOpenAI`, `AsyncAnthropic`, `client.aio.models`) work the
+same way — the interceptor detects and handles them automatically. Streaming
+calls are captured too; for OpenAI/OpenRouter the SDK auto-enables
+`stream_options.include_usage` so token usage is recorded.
+
+In short-lived processes (serverless, CLI), flush pending deliveries before exit:
+
+```python
+doppel.flush()
+```
+
+## Configuration
+
+| Setting | Argument | Environment variable | Default |
+|---|---|---|---|
+| API key | `api_key` | `DOPPEL_API_KEY` | — (required) |
+| Server URL | `server_url` | `DOPPEL_SERVER_URL` | `https://api.doppel.in` |
+| Shadow model | `shadow_model` | — | none (chosen in the dashboard) |
+| Debug logs | `debug` | `DOPPEL_DEBUG` (`1`/`true`) | off |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Publishing
+
+Pushing a `py-v*` tag runs the tests, builds, and publishes to PyPI (trusted
+publishing — no token):
+
+```bash
+# bump version in pyproject.toml first, then:
+git tag py-v0.1.0
+git push origin py-v0.1.0
+```

doppel_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+doppel_sdk/__init__.py,sha256=4fUqoQvbwEY4y9d6PVF6VcbVGYwsFyx_kc57e3GpqcE,921
+doppel_sdk/_config.py,sha256=3X0xle-gnqKL1lVu37Yuj9-oOUodNTA59cQO5a3AmHM,1796
+doppel_sdk/_transport.py,sha256=KVN3dbhRVQXspbT7hO4eYfZugYU4OsE8caZ9EN_fjTw,3095
+doppel_sdk/_utils.py,sha256=oS4DNO08UdMUxewTsRujnA1jCH6NR0nOYn7BbYV4TFc,1115
+doppel_sdk/client.py,sha256=RJ1-B8_-N6xzXzHgp6dxtS0De-P8ONLefuCtoZtHElM,1705
+doppel_sdk/interceptors/__init__.py,sha256=CRyjcAUzWfOrEmtHdS-p3PHDBci4UD0PO00i-4Erk3U,48
+doppel_sdk/interceptors/_openai_compat.py,sha256=Cn_ASl6d4CiUkAJtRtSDFmVY8lNtieMtquQcda6mh7w,5722
+doppel_sdk/interceptors/_stream.py,sha256=RnqqYspmnhr2y7UfB9RShZhsS5cterBjh80v22jK434,3118
+doppel_sdk/interceptors/anthropic.py,sha256=QjK6rzARhvwCZhzWTuV4xWQnpShsAgFOK77Z_tikmDM,5053
+doppel_sdk/interceptors/google.py,sha256=H4gkSD_bGVHuYnvH01tZf5HHBE-Km2oR0G0QLoFgGG4,7504
+doppel_sdk/interceptors/openai.py,sha256=UeqkqBy1nbkVEMscS9bMRNE-Lm23VQZX0DWUC3baDeg,568
+doppel_sdk/interceptors/openrouter.py,sha256=Ynmv44hEhzCEWB189qsq0qGE31-tON6kqQYee9B9R30,711
+doppel_sdk-0.1.0.dist-info/METADATA,sha256=YUxgW9gkxu8pPl6OVWuVbtvlXB7GZQ8LcUazaeTMTes,2416
+doppel_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+doppel_sdk-0.1.0.dist-info/RECORD,,

doppel_sdk-0.1.0.dist-info/WHEEL

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