spanlens 0.1.0__py3-none-any.whl

spanlens/__init__.py

@@ -0,0 +1,48 @@
+"""Spanlens — agent tracing, LLM usage capture, and cost observability.
+
+Quick start::
+
+    from spanlens import SpanlensClient
+
+    client = SpanlensClient(api_key="sl_live_...")
+
+    with client.start_trace("rag_pipeline") as trace:
+        with trace.span("retrieval", span_type="retrieval") as span:
+            docs = retrieve(query)
+            span.end(output=docs)
+
+        with trace.span("generation", span_type="llm") as span:
+            from openai import OpenAI
+            response = OpenAI().chat.completions.create(...)
+            span.end(
+                output=response.choices[0].message.content,
+                prompt_tokens=response.usage.prompt_tokens,
+                completion_tokens=response.usage.completion_tokens,
+                total_tokens=response.usage.total_tokens,
+            )
+
+For proxy-mode (zero-code) instrumentation, see
+``spanlens.integrations.openai`` / ``anthropic`` / ``gemini``.
+"""
+
+from .client import SpanlensClient
+from .observe import observe, observe_anthropic, observe_gemini, observe_openai
+from .parsers import parse_anthropic_usage, parse_gemini_usage, parse_openai_usage
+from .span import SpanHandle
+from .trace import TraceHandle
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SpanHandle",
+    "SpanlensClient",
+    "TraceHandle",
+    "__version__",
+    "observe",
+    "observe_anthropic",
+    "observe_gemini",
+    "observe_openai",
+    "parse_anthropic_usage",
+    "parse_gemini_usage",
+    "parse_openai_usage",
+]

spanlens/client.py

@@ -0,0 +1,89 @@
+"""Spanlens SDK entry point — wraps the transport and exposes ``start_trace()``."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from .trace import TraceHandle, create_trace
+from .transport import Transport
+
+
+class SpanlensClient:
+    """Single entry point for the Spanlens SDK.
+
+    Example:
+        >>> from spanlens import SpanlensClient
+        >>> client = SpanlensClient(api_key="sl_live_...")
+        >>> trace = client.start_trace("chat_session", metadata={"user_id": "u_42"})
+        >>> span = trace.span("call_openai", span_type="llm")
+        >>> # ... do work ...
+        >>> span.end(total_tokens=150, cost_usd=0.0023)
+        >>> trace.end(status="completed")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout_ms: int = 3000,
+        silent: bool = True,
+        on_error: Optional[Callable[[BaseException, str], None]] = None,
+    ) -> None:
+        if not api_key or not api_key.strip():
+            raise ValueError("[spanlens] api_key is required")
+
+        config: dict[str, Any] = {
+            "api_key": api_key,
+            "timeout_ms": timeout_ms,
+            "silent": silent,
+        }
+        if base_url is not None:
+            config["base_url"] = base_url
+        if on_error is not None:
+            config["on_error"] = on_error
+
+        self._transport = Transport(config)
+
+    def start_trace(
+        self,
+        name: str,
+        *,
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> TraceHandle:
+        """Start a new trace.
+
+        Returns immediately — ingest runs in the background. Use the returned
+        handle as a context manager to auto-end on scope exit::
+
+            with client.start_trace("rag_pipeline") as trace:
+                with trace.span("retrieval", span_type="retrieval") as span:
+                    ...
+        """
+        return create_trace(self._transport, name, metadata)
+
+    def close(self) -> None:
+        """Drain in-flight ingest calls and release the connection pool.
+
+        Optional — also runs automatically at interpreter shutdown via
+        ``atexit``. Call explicitly when you need to guarantee delivery (e.g.
+        in short-lived scripts that exit before the background pool flushes).
+        """
+        self._transport.close()
+
+    # Allow `with SpanlensClient(...) as c:` for tidy script lifetimes.
+    def __enter__(self) -> SpanlensClient:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    # ── Internal escape hatch for the integrations module ───────
+
+    @property
+    def _transport_internal(self) -> Transport:
+        """Exposed for wrappers (openai/anthropic auto-instrumentation)."""
+        return self._transport
+
+
+__all__ = ["SpanlensClient"]

spanlens/integrations/__init__.py

@@ -0,0 +1,40 @@
+"""Provider integrations — pre-configured clients pointed at the Spanlens proxy.
+
+Each helper requires its provider SDK as an *optional* dependency. Install
+with the matching extra::
+
+    pip install "spanlens[openai]"
+    pip install "spanlens[anthropic]"
+    pip install "spanlens[gemini]"
+    pip install "spanlens[all]"
+
+If the provider SDK is missing, the helper raises ``ImportError`` with the
+exact pip command needed.
+"""
+
+from .anthropic import (
+    DEFAULT_SPANLENS_ANTHROPIC_PROXY,
+    create_anthropic,
+)
+from .anthropic import (
+    with_prompt_version as with_anthropic_prompt_version,
+)
+from .gemini import DEFAULT_SPANLENS_GEMINI_PROXY, create_gemini
+from .openai import (
+    DEFAULT_SPANLENS_OPENAI_PROXY,
+    create_openai,
+)
+from .openai import (
+    with_prompt_version as with_openai_prompt_version,
+)
+
+__all__ = [
+    "DEFAULT_SPANLENS_ANTHROPIC_PROXY",
+    "DEFAULT_SPANLENS_GEMINI_PROXY",
+    "DEFAULT_SPANLENS_OPENAI_PROXY",
+    "create_anthropic",
+    "create_gemini",
+    "create_openai",
+    "with_anthropic_prompt_version",
+    "with_openai_prompt_version",
+]

spanlens/integrations/anthropic.py

@@ -0,0 +1,99 @@
+"""Anthropic client helper — pre-configured for the Spanlens proxy.
+
+Replaces::
+
+    from anthropic import Anthropic
+    client = Anthropic(
+        api_key=os.environ["SPANLENS_API_KEY"],
+        base_url="https://spanlens-server.vercel.app/proxy/anthropic",
+    )
+
+With::
+
+    from spanlens.integrations.anthropic import create_anthropic
+    client = create_anthropic()
+
+``anthropic`` is an *optional* dependency — install with
+``pip install "spanlens[anthropic]"``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+DEFAULT_SPANLENS_ANTHROPIC_PROXY = "https://spanlens-server.vercel.app/proxy/anthropic"
+PROMPT_VERSION_HEADER = "x-spanlens-prompt-version"
+
+
+def create_anthropic(
+    *,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    **kwargs: Any,
+) -> Any:
+    """Build an ``anthropic.Anthropic`` client whose requests flow through
+    the Spanlens proxy.
+
+    Args:
+        api_key: Spanlens API key. Defaults to ``SPANLENS_API_KEY`` env var.
+        base_url: Override the proxy URL — useful for self-hosted Spanlens.
+        **kwargs: Forwarded to ``anthropic.Anthropic(...)`` unchanged.
+
+    Raises:
+        ImportError: ``anthropic`` package is not installed.
+        ValueError: ``api_key`` not provided and ``SPANLENS_API_KEY`` unset.
+    """
+    try:
+        from anthropic import Anthropic
+    except ImportError as exc:  # pragma: no cover - import-time
+        raise ImportError(
+            "[spanlens] The `anthropic` package is required for create_anthropic(). "
+            'Install with: pip install "spanlens[anthropic]"'
+        ) from exc
+
+    resolved_key = api_key or os.environ.get("SPANLENS_API_KEY")
+    if not resolved_key:
+        raise ValueError(
+            "[spanlens] SPANLENS_API_KEY is not set. Pass api_key=... to "
+            "create_anthropic() or set the SPANLENS_API_KEY environment variable."
+        )
+
+    return Anthropic(
+        api_key=resolved_key,
+        base_url=base_url or DEFAULT_SPANLENS_ANTHROPIC_PROXY,
+        **kwargs,
+    )
+
+
+def with_prompt_version(prompt_version: str) -> dict[str, dict[str, str]]:
+    """Tag a single Anthropic request with a Spanlens prompt version.
+
+    Example::
+
+        from spanlens.integrations.anthropic import (
+            create_anthropic,
+            with_prompt_version,
+        )
+
+        client = create_anthropic()
+        msg = client.messages.create(
+            model="claude-3-5-sonnet-20241022",
+            max_tokens=1024,
+            messages=[...],
+            **with_prompt_version("greeter@latest"),
+        )
+
+    Args:
+        prompt_version: Raw UUID, ``"<name>@<version>"`` or
+            ``"<name>@latest"``.
+    """
+    return {"extra_headers": {PROMPT_VERSION_HEADER: prompt_version}}
+
+
+__all__ = [
+    "DEFAULT_SPANLENS_ANTHROPIC_PROXY",
+    "PROMPT_VERSION_HEADER",
+    "create_anthropic",
+    "with_prompt_version",
+]

spanlens/integrations/gemini.py

@@ -0,0 +1,119 @@
+"""Google Gemini client helper — pre-configured for the Spanlens proxy.
+
+The Google ``google-generativeai`` SDK uses a *module-level* configuration
+pattern (``genai.configure(api_key=..., transport=...)``) and routes through
+its own internal HTTP client; it does **not** support a per-instance
+``base_url`` the way OpenAI/Anthropic do.
+
+To make the proxy approach work, we expose ``create_gemini()`` which returns
+an ``httpx.Client`` pre-configured with the Spanlens proxy as ``base_url``
+plus an ``Authorization`` header carrying the Spanlens API key. The proxy
+in turn forwards to ``generativelanguage.googleapis.com`` and decodes the
+provider key on the server.
+
+Use the returned client to issue raw HTTP calls, OR use the proxy URL +
+your own ``google.generativeai`` ``client_options.api_endpoint`` override.
+
+``google-generativeai`` is an *optional* dependency for the
+``configure_gemini()`` variant — install with
+``pip install "spanlens[gemini]"``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+import httpx
+
+DEFAULT_SPANLENS_GEMINI_PROXY = "https://spanlens-server.vercel.app/proxy/gemini"
+
+
+def create_gemini(
+    *,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    timeout: float = 60.0,
+) -> httpx.Client:
+    """Return an ``httpx.Client`` pre-configured for the Spanlens Gemini proxy.
+
+    Use it to issue REST calls to Gemini through Spanlens::
+
+        client = create_gemini()
+        res = client.post(
+            "/v1beta/models/gemini-1.5-flash:generateContent",
+            json={"contents": [{"parts": [{"text": "Hello"}]}]},
+        )
+        print(res.json())
+
+    Args:
+        api_key: Spanlens API key. Defaults to ``SPANLENS_API_KEY`` env var.
+        base_url: Override the proxy URL — useful for self-hosted Spanlens.
+        timeout: Request timeout in seconds (LLM calls can be slow — default
+            60s).
+
+    Raises:
+        ValueError: ``api_key`` not provided and ``SPANLENS_API_KEY`` unset.
+    """
+    resolved_key = api_key or os.environ.get("SPANLENS_API_KEY")
+    if not resolved_key:
+        raise ValueError(
+            "[spanlens] SPANLENS_API_KEY is not set. Pass api_key=... to "
+            "create_gemini() or set the SPANLENS_API_KEY environment variable."
+        )
+
+    return httpx.Client(
+        base_url=base_url or DEFAULT_SPANLENS_GEMINI_PROXY,
+        headers={"Authorization": f"Bearer {resolved_key}"},
+        timeout=timeout,
+    )
+
+
+def configure_gemini(
+    *,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> None:
+    """Point ``google.generativeai`` at the Spanlens proxy globally.
+
+    This calls ``genai.configure()`` with the Spanlens proxy as the API
+    endpoint. After calling, all ``genai.GenerativeModel(...).generate_content(...)``
+    calls flow through Spanlens.
+
+    Note:
+        ``google.generativeai`` configures the endpoint *globally* per
+        process — use this in single-tenant scripts. For multi-tenant
+        servers, prefer the ``create_gemini()`` raw-HTTP client.
+
+    Raises:
+        ImportError: ``google-generativeai`` package is not installed.
+        ValueError: ``api_key`` not provided and ``SPANLENS_API_KEY`` unset.
+    """
+    try:
+        import google.generativeai as genai  # type: ignore[import-not-found]
+    except ImportError as exc:  # pragma: no cover - import-time
+        raise ImportError(
+            "[spanlens] The `google-generativeai` package is required for "
+            'configure_gemini(). Install with: pip install "spanlens[gemini]"'
+        ) from exc
+
+    resolved_key = api_key or os.environ.get("SPANLENS_API_KEY")
+    if not resolved_key:
+        raise ValueError(
+            "[spanlens] SPANLENS_API_KEY is not set. Pass api_key=... to "
+            "configure_gemini() or set the SPANLENS_API_KEY environment variable."
+        )
+
+    proxy = base_url or DEFAULT_SPANLENS_GEMINI_PROXY
+
+    # google.generativeai accepts api_endpoint via client_options. The path
+    # prefix (e.g. /v1beta) is added by the SDK; we only configure the host.
+    client_options: Any = {"api_endpoint": proxy}
+    genai.configure(api_key=resolved_key, client_options=client_options)
+
+
+__all__ = [
+    "DEFAULT_SPANLENS_GEMINI_PROXY",
+    "configure_gemini",
+    "create_gemini",
+]

spanlens/integrations/openai.py

@@ -0,0 +1,106 @@
+"""OpenAI client helper — pre-configured for the Spanlens proxy.
+
+Replaces::
+
+    from openai import OpenAI
+    client = OpenAI(
+        api_key=os.environ["SPANLENS_API_KEY"],
+        base_url="https://spanlens-server.vercel.app/proxy/openai/v1",
+    )
+
+With::
+
+    from spanlens.integrations.openai import create_openai
+    client = create_openai()
+
+The returned client behaves identically to ``OpenAI(...)`` — only the
+``base_url`` is redirected to the Spanlens proxy (which records the call,
+enforces quota, computes cost) and ``api_key`` defaults to
+``SPANLENS_API_KEY`` from the environment.
+
+``openai`` is an *optional* dependency — install with
+``pip install "spanlens[openai]"``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+DEFAULT_SPANLENS_OPENAI_PROXY = "https://spanlens-server.vercel.app/proxy/openai/v1"
+PROMPT_VERSION_HEADER = "x-spanlens-prompt-version"
+
+
+def create_openai(
+    *,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    **kwargs: Any,
+) -> Any:
+    """Build an ``openai.OpenAI`` client whose requests flow through the
+    Spanlens proxy.
+
+    Args:
+        api_key: Spanlens API key. Defaults to ``SPANLENS_API_KEY`` env var.
+        base_url: Override the proxy URL — useful for self-hosted Spanlens.
+        **kwargs: Forwarded to ``openai.OpenAI(...)`` unchanged.
+
+    Raises:
+        ImportError: ``openai`` package is not installed.
+        ValueError: ``api_key`` not provided and ``SPANLENS_API_KEY`` unset.
+    """
+    try:
+        from openai import OpenAI
+    except ImportError as exc:  # pragma: no cover - import-time
+        raise ImportError(
+            "[spanlens] The `openai` package is required for create_openai(). "
+            'Install with: pip install "spanlens[openai]"'
+        ) from exc
+
+    resolved_key = api_key or os.environ.get("SPANLENS_API_KEY")
+    if not resolved_key:
+        raise ValueError(
+            "[spanlens] SPANLENS_API_KEY is not set. Pass api_key=... to "
+            "create_openai() or set the SPANLENS_API_KEY environment variable."
+        )
+
+    return OpenAI(
+        api_key=resolved_key,
+        base_url=base_url or DEFAULT_SPANLENS_OPENAI_PROXY,
+        **kwargs,
+    )
+
+
+def with_prompt_version(prompt_version: str) -> dict[str, dict[str, str]]:
+    """Tag a single OpenAI request with a Spanlens prompt version.
+
+    Spread the result into the per-request ``extra_headers``::
+
+        from openai import OpenAI
+        from spanlens.integrations.openai import (
+            create_openai,
+            with_prompt_version,
+        )
+
+        client = create_openai()
+        res = client.chat.completions.create(
+            model="gpt-4o-mini",
+            messages=[...],
+            **with_prompt_version("chatbot-system@3"),
+        )
+
+    Args:
+        prompt_version: Either a raw ``prompt_versions.id`` UUID,
+            ``"<name>@<version>"`` (e.g. ``"chatbot-system@3"``), or
+            ``"<name>@latest"`` to always resolve to the latest version
+            server-side.
+    """
+    return {"extra_headers": {PROMPT_VERSION_HEADER: prompt_version}}
+
+
+__all__ = [
+    "DEFAULT_SPANLENS_OPENAI_PROXY",
+    "PROMPT_VERSION_HEADER",
+    "create_openai",
+    "with_prompt_version",
+]