doppel-sdk 0.1.0__tar.gz

doppel_sdk-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+node_modules
+dist
+.DS_Store
+*.log
+
+# JS SDK
+sdks/javascript/dist
+sdks/javascript/node_modules
+
+# Python SDK
+__pycache__/
+*.pyc
+.pytest_cache/
+sdks/python/*.egg-info
+sdks/python/dist
+sdks/python/.venv
+
+# Java SDK
+sdks/java/target
+sdks/java/.gradle
+sdks/java/build

doppel_sdk-0.1.0/PKG-INFO

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

@@ -0,0 +1,77 @@
+# 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/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-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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/doppel_sdk/interceptors/__init__.py

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

doppel_sdk-0.1.0/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