spanlight 0.1.0__py3-none-any.whl

spanlight/_prompt_client.py

@@ -0,0 +1,241 @@
+"""Fetching prompts from ``GET /v1/prompts/{name}`` with a small revalidating cache.
+
+The cache is keyed by ``(name, label, version)``. A fresh entry is served without a request;
+an expired one is revalidated with ``If-None-Match``, so an unchanged prompt costs a ``304``.
+When the server cannot be reached or answers with an error, an expired entry keeps being
+served (a prompt outage must not become an application outage). With nothing cached, the
+caller's ``fallback`` is used; with no fallback either, :class:`PromptUnavailableError` is
+raised.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ._prompts import Prompt, PromptUnavailableError, fallback_prompt, prompt_from_wire
+from ._templates import InvalidTemplateError
+from ._version import __version__
+
+logger = logging.getLogger("spanlight")
+
+CacheKey = tuple[str, str, int | None]
+Fallback = str | Sequence[Mapping[str, Any]]
+
+_WARNING_INTERVAL = 60.0
+# Seconds a failed fetch is remembered, so callers queued behind it do not each time out.
+_FAILURE_MEMO = 5.0
+
+
+@dataclass
+class _Entry:
+    prompt: Prompt
+    etag: str | None
+    expires_at: float
+
+
+class _FetchError(Exception):
+    """Why one fetch failed; the message never contains the API key or the prompt body."""
+
+
+class PromptClient:
+    """Reads prompts for one Spanlight client. Reach it as ``Spanlight.prompts``.
+
+    Args:
+        base_url: URL of the prompts collection, e.g. ``http://localhost:8000/v1/prompts``.
+        api_key: Project API key with the ``prompts:read`` scope, or ``None``.
+        timeout: Per-request timeout in seconds.
+        cache_ttl: Seconds a fetched prompt is served without asking the server again.
+        transport: Optional custom ``httpx`` transport.
+        clock: Monotonic clock, replaceable in tests.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str | None,
+        timeout: float,
+        cache_ttl: float,
+        transport: httpx.BaseTransport | None = None,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+        self._ttl = cache_ttl
+        self._transport = transport
+        self._clock = clock
+        self._cache: dict[CacheKey, _Entry] = {}
+        self._locks: dict[CacheKey, threading.Lock] = {}
+        self._locks_guard = threading.Lock()
+        self._last_warning: dict[CacheKey, float] = {}
+        # Per key: until when a failed fetch is not retried, and why it failed.
+        self._failures: dict[CacheKey, tuple[float, str]] = {}
+        self._client: httpx.Client | None = None
+        self._client_guard = threading.Lock()
+
+    def get(
+        self,
+        name: str,
+        label: str = "production",
+        *,
+        version: int | None = None,
+        fallback: Fallback | None = None,
+    ) -> Prompt:
+        """Return a prompt version by label (default ``production``) or by number.
+
+        Args:
+            name: The prompt name, e.g. ``"support/answer"``.
+            label: The label to resolve; ignored when ``version`` is given.
+            version: A specific version number.
+            fallback: A text template, or a list of ``{"role", "content"}`` messages, used
+                when the prompt cannot be fetched and nothing is cached. The returned
+                prompt then has ``version=None``.
+
+        Returns:
+            The prompt. A cached copy is returned while fresh, and also after it expires
+            whenever the server cannot be reached.
+
+        Raises:
+            PromptUnavailableError: Nothing is cached, the fetch failed and there is no
+                valid ``fallback``; or ``name`` is empty or has an empty, ``.`` or ``..``
+                segment (no request is made).
+        """
+        key: CacheKey = (name, label, version)
+        if not _is_valid_name(name):
+            raise PromptUnavailableError(f"prompt {name!r} is unavailable: invalid prompt name")
+        entry = self._cache.get(key)
+        if entry is not None and self._clock() < entry.expires_at:
+            return entry.prompt
+        lock = self._lock_for(key)
+        if not lock.acquire(blocking=False):
+            if entry is not None:
+                # Another caller is refreshing this prompt; serve the expired copy rather than
+                # wait on the server.
+                return entry.prompt
+            lock.acquire()
+        try:
+            return self._get_locked(key, fallback)
+        finally:
+            lock.release()
+
+    def close(self) -> None:
+        """Close the HTTP connection pool. A later ``get`` opens a new one."""
+        with self._client_guard:
+            client, self._client = self._client, None
+        if client is not None:
+            client.close()
+
+    def _get_locked(self, key: CacheKey, fallback: Fallback | None) -> Prompt:
+        # Another thread may have refreshed the entry while this one waited.
+        entry = self._cache.get(key)
+        now = self._clock()
+        if entry is not None and now < entry.expires_at:
+            return entry.prompt
+        failure = self._failures.get(key)
+        if entry is None and failure is not None and now < failure[0]:
+            # A fetch failed moments ago; do not make this caller wait on the server too.
+            return self._without_cache(key, fallback, failure[1])
+        try:
+            return self._refresh(key, entry)
+        except _FetchError as error:
+            cause = str(error)
+        except Exception as error:
+            logger.debug("Unexpected error fetching prompt %r", key[0], exc_info=True)
+            cause = type(error).__name__
+        return self._recover(key, entry, fallback, cause)
+
+    def _lock_for(self, key: CacheKey) -> threading.Lock:
+        with self._locks_guard:
+            return self._locks.setdefault(key, threading.Lock())
+
+    def _refresh(self, key: CacheKey, entry: _Entry | None) -> Prompt:
+        response = self._request(key, entry.etag if entry is not None else None)
+        now = self._clock()
+        if response.status_code == 304 and entry is not None:
+            entry.expires_at = now + self._ttl
+            return entry.prompt
+        if response.status_code != 200:
+            raise _FetchError(f"HTTP {response.status_code}")
+        try:
+            prompt = prompt_from_wire(response.json())
+        except (ValueError, InvalidTemplateError) as error:
+            raise _FetchError(f"unreadable response ({error})") from None
+        self._cache[key] = _Entry(prompt, response.headers.get("ETag"), now + self._ttl)
+        self._failures.pop(key, None)
+        return prompt
+
+    def _request(self, key: CacheKey, etag: str | None) -> httpx.Response:
+        if not self._api_key:
+            raise _FetchError("no API key configured")
+        name, label, version = key
+        params = {"version": str(version)} if version is not None else {"label": label}
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": f"spanlight-python/{__version__}",
+        }
+        if etag is not None:
+            headers["If-None-Match"] = etag
+        url = f"{self._base_url}/{quote(name, safe='/')}"
+        try:
+            return self._http_client().get(url, params=params, headers=headers)
+        except httpx.HTTPError as error:
+            raise _FetchError(type(error).__name__) from None
+
+    def _recover(
+        self, key: CacheKey, entry: _Entry | None, fallback: Fallback | None, cause: str
+    ) -> Prompt:
+        name = key[0]
+        if entry is not None:
+            # Keep serving the stale copy and wait before asking again, so an outage does not
+            # put a request (and its timeout) on every call.
+            entry.expires_at = self._clock() + max(self._ttl, _FAILURE_MEMO)
+            self._warn(key, f"Spanlight: serving a cached copy of prompt {name!r} ({cause})")
+            return entry.prompt
+        # Remember the failure: briefly when the caller has nothing else (so concurrent callers
+        # do not each wait out a timeout), one TTL when a fallback covers the gap.
+        window = _FAILURE_MEMO if fallback is None else max(self._ttl, _FAILURE_MEMO)
+        self._failures[key] = (self._clock() + window, cause)
+        return self._without_cache(key, fallback, cause)
+
+    def _without_cache(self, key: CacheKey, fallback: Fallback | None, cause: str) -> Prompt:
+        """The fallback prompt, or :class:`PromptUnavailableError` when there is none."""
+        name = key[0]
+        if fallback is None:
+            raise PromptUnavailableError(f"prompt {name!r} is unavailable: {cause}")
+        try:
+            prompt = fallback_prompt(name, fallback)
+        except (InvalidTemplateError, TypeError) as error:
+            raise PromptUnavailableError(
+                f"prompt {name!r} is unavailable ({cause}) and its fallback is invalid: {error}"
+            ) from None
+        self._warn(key, f"Spanlight: using the fallback for prompt {name!r} ({cause})")
+        return prompt
+
+    def _warn(self, key: CacheKey, message: str) -> None:
+        now = self._clock()
+        last = self._last_warning.get(key)
+        if last is None or now - last >= _WARNING_INTERVAL:
+            self._last_warning[key] = now
+            logger.warning(message)
+
+    def _http_client(self) -> httpx.Client:
+        with self._client_guard:
+            if self._client is None:
+                self._client = httpx.Client(transport=self._transport, timeout=self._timeout)
+            return self._client
+
+
+def _is_valid_name(name: str) -> bool:
+    """Whether ``name`` can travel in the URL path: no empty, ``.`` or ``..`` segments."""
+    if not isinstance(name, str) or not name:
+        return False
+    return all(segment not in ("", ".", "..") for segment in name.split("/"))

spanlight/_prompts.py

@@ -0,0 +1,247 @@
+"""Prompts fetched from Spanlight, and their compiled form.
+
+A :class:`Prompt` is one immutable prompt version (or a local fallback). Compiling it fills in
+the variables and returns a :class:`CompiledPrompt`, which is also a context manager: spans
+started inside ``with compiled:`` are linked to the prompt version they used.
+
+The link lives in a :class:`~contextvars.ContextVar`, so it follows contextvars semantics: an
+``asyncio`` task created inside the block keeps the link for its whole life, and a thread does
+not see it at all. Wrap the creation of long-lived tasks in :func:`no_prompt` to keep their
+spans unlinked.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Iterator, Mapping, Sequence
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import Any
+
+from ._context import (
+    get_current_prompt_version_id,
+    restore_current_prompt_version_id,
+    set_current_prompt_version_id,
+)
+from ._templates import (
+    Kind,
+    Template,
+    compile,
+    extract_variables,
+    messages_from_wire,
+    template_from_wire,
+)
+
+# The `with compiled:` blocks open in the current context, innermost last: (prompt, token to
+# undo its link, link before it). Kept per context so threads and tasks entering the same
+# CompiledPrompt never pop each other's entries.
+_Entered = tuple["CompiledPrompt", Token[str | None], str | None]
+_entered: ContextVar[tuple[_Entered, ...]] = ContextVar("spanlight_entered_prompts", default=())
+
+
+@contextlib.contextmanager
+def no_prompt() -> Iterator[None]:
+    """Unlink spans started inside the block from any prompt version.
+
+    Use it around code that starts long-lived work (``asyncio.create_task``, a background
+    worker) from inside ``with compiled:``, which would otherwise inherit the link.
+    """
+    previous = get_current_prompt_version_id()
+    token = set_current_prompt_version_id(None)
+    try:
+        yield
+    finally:
+        restore_current_prompt_version_id(token, previous)
+
+
+class PromptUnavailableError(Exception):
+    """A prompt could not be fetched and there was neither a cached copy nor a fallback.
+
+    This is the one exception the SDK raises on purpose. Pass ``fallback=`` to
+    :meth:`PromptClient.get <spanlight.PromptClient.get>` to never see it.
+    """
+
+
+@dataclass(frozen=True)
+class CompiledPrompt:
+    """A prompt with its variables filled in.
+
+    Use ``text`` for a text prompt and ``messages`` (plain ``{"role", "content"}`` dicts, ready
+    for the OpenAI and Anthropic SDKs) for a chat prompt. Enter it with ``with compiled:`` to link
+    every span started inside the block to this prompt version, or pass it to a wrapped client
+    call as ``spanlight_prompt=compiled``. A fallback (no version) clears the link instead.
+
+    Attributes:
+        name: The prompt name.
+        version: The prompt version, or ``None`` for a local fallback.
+        prompt_version_id: The version id spans are linked to, or ``None`` for a fallback.
+        kind: ``"text"`` or ``"chat"``.
+        text: The compiled text of a text prompt.
+        messages: The compiled messages of a chat prompt.
+        variables_used: Variables the template uses, in first-appearance order.
+        unused_variables: Variables that were passed but not used, sorted.
+    """
+
+    name: str
+    version: int | None
+    prompt_version_id: str | None
+    kind: Kind
+    text: str | None
+    messages: list[dict[str, str]] | None
+    variables_used: tuple[str, ...]
+    unused_variables: tuple[str, ...]
+
+    def __enter__(self) -> CompiledPrompt:
+        previous = get_current_prompt_version_id()
+        token = set_current_prompt_version_id(self.prompt_version_id)
+        _entered.set((*_entered.get(), (self, token, previous)))
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        stack = _entered.get()
+        for index in range(len(stack) - 1, -1, -1):
+            prompt, token, previous = stack[index]
+            if prompt is self:
+                _entered.set(stack[:index] + stack[index + 1 :])
+                restore_current_prompt_version_id(token, previous)
+                return
+
+    async def __aenter__(self) -> CompiledPrompt:
+        return self.__enter__()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.__exit__(exc_type, exc, traceback)
+
+
+@dataclass(frozen=True)
+class Prompt:
+    """One prompt version as served by Spanlight, or a local fallback.
+
+    Attributes:
+        name: The prompt name.
+        version: The version number, or ``None`` when this is the fallback passed to ``get``.
+        version_id: The version's id, or ``None`` for a fallback.
+        kind: ``"text"`` or ``"chat"``.
+        template: The uncompiled template.
+        variables: Variables the template uses, in first-appearance order.
+        model_config: Model settings saved with the version (model, temperature, ...).
+        labels: Labels that point at this version.
+    """
+
+    name: str
+    version: int | None
+    version_id: str | None
+    kind: Kind
+    template: Template
+    variables: tuple[str, ...]
+    model_config: dict[str, Any] = field(default_factory=dict)
+    labels: tuple[str, ...] = ()
+
+    @property
+    def is_fallback(self) -> bool:
+        """Whether this prompt is the local fallback rather than a served version."""
+        return self.version is None
+
+    def compile(self, **variables: str | int | float) -> CompiledPrompt:
+        """Fill in the template's variables.
+
+        Values are strings; numbers and booleans are converted with ``str()``. Extra
+        variables are reported in ``unused_variables``, never rejected.
+
+        Raises:
+            MissingVariablesError: A variable the template uses was not given.
+            InvalidTemplateError: The template is malformed.
+            TemplateTooLargeError: The rendered prompt would exceed 256 KB.
+            TypeError: A value is not a string, number or boolean (``None`` included).
+        """
+        rendered = compile(self.template, _as_strings(variables))
+        messages = (
+            [{"role": message.role, "content": message.content} for message in rendered.messages]
+            if rendered.messages is not None
+            else None
+        )
+        return CompiledPrompt(
+            name=self.name,
+            version=self.version,
+            prompt_version_id=self.version_id,
+            kind=rendered.kind,
+            text=rendered.text,
+            messages=messages,
+            variables_used=rendered.variables_used,
+            unused_variables=rendered.unused_variables,
+        )
+
+
+def _as_strings(variables: Mapping[str, Any]) -> dict[str, str]:
+    """Template values as strings: numbers and booleans via ``str()``, anything else refused."""
+    converted: dict[str, str] = {}
+    for name, value in variables.items():
+        if isinstance(value, str):
+            converted[name] = value
+        elif isinstance(value, int | float):
+            converted[name] = str(value)
+        else:
+            raise TypeError(
+                f"variable {name!r} must be a string, number or boolean, not {type(value).__name__}"
+            )
+    return converted
+
+
+def prompt_from_wire(body: Any) -> Prompt:
+    """Build a :class:`Prompt` from a ``GET /v1/prompts/{name}`` response body.
+
+    Raises:
+        ValueError: The body does not have the documented shape.
+    """
+    if not isinstance(body, Mapping):
+        raise ValueError("prompt response is not a JSON object")
+    name, version, version_id = body.get("name"), body.get("version"), body.get("version_id")
+    if not isinstance(name, str) or not isinstance(version_id, str):
+        raise ValueError("prompt response lacks name or version_id")
+    if not isinstance(version, int) or isinstance(version, bool):
+        raise ValueError("prompt response lacks a version number")
+    template = template_from_wire(body.get("template"))
+    model_config = body.get("model_config")
+    labels = body.get("labels")
+    return Prompt(
+        name=name,
+        version=version,
+        version_id=version_id,
+        kind=template.kind,
+        template=template,
+        variables=extract_variables(template),
+        model_config=dict(model_config) if isinstance(model_config, Mapping) else {},
+        labels=tuple(str(label) for label in labels) if isinstance(labels, list) else (),
+    )
+
+
+def fallback_prompt(name: str, fallback: str | Sequence[Mapping[str, Any]]) -> Prompt:
+    """Build the ``version=None`` prompt used when nothing could be fetched or cached.
+
+    Raises:
+        InvalidTemplateError: ``fallback`` is not a valid text or chat template.
+    """
+    template = (
+        Template("text", text=fallback)
+        if isinstance(fallback, str)
+        else Template("chat", messages=messages_from_wire(list(fallback)))
+    )
+    return Prompt(
+        name=name,
+        version=None,
+        version_id=None,
+        kind=template.kind,
+        template=template,
+        variables=extract_variables(template),
+    )

spanlight/_request_hash.py

@@ -0,0 +1,58 @@
+"""Stable hash of a model request, used to group identical calls.
+
+The algorithm is shared with the server and must stay byte-for-byte identical
+to it: the first 32 hex characters of the SHA-256 of the canonical JSON
+(sorted keys, ``,`` and ``:`` separators, non-ASCII kept) of
+``{"model": model, "input": cleaned}``. ``cleaned`` is ``input`` without the
+top-level keys that change per call but not the prompt (streaming flags,
+identifiers, transport options); non-dict inputs are hashed as they are.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+# Top-level request keys that never change what the model is asked.
+_IGNORED_INPUT_KEYS = frozenset(
+    {
+        "stream",
+        "stream_options",
+        "user",
+        "metadata",
+        "idempotency_key",
+        "extra_headers",
+        "extra_query",
+        "extra_body",
+        "timeout",
+        "api_key",
+        "http_client",
+    }
+)
+
+
+def request_hash(model: str | None, value: Any) -> str | None:
+    """Return the 32-hex request hash, or ``None`` when ``value`` is ``None``.
+
+    Args:
+        model: The requested model name, or ``None`` when unknown.
+        value: The JSON-compatible request input (a dict of call parameters,
+            a string or a list).
+    """
+    if value is None:
+        return None
+    cleaned = (
+        {key: item for key, item in value.items() if key not in _IGNORED_INPUT_KEYS}
+        if isinstance(value, dict)
+        else value
+    )
+    canonical = json.dumps(
+        {"model": model, "input": cleaned},
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    )
+    # ``surrogatepass``, as on the server: a lone surrogate (a valid JSON escape, invalid
+    # UTF-8) is hashed instead of raising; every other string encodes exactly as UTF-8.
+    return hashlib.sha256(canonical.encode("utf-8", "surrogatepass")).hexdigest()[:32]

spanlight/_scores.py

@@ -0,0 +1,57 @@
+"""Building the ``POST /v1/scores`` payload for one score.
+
+Scores are recorded with :func:`spanlight.score` and sent by the background exporter. Each
+score gets a UUIDv7 ``id`` when it is recorded, so a retried request can never store it twice.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+
+from ._ids import new_uuid7
+from ._serialize import JsonValue
+
+logger = logging.getLogger("spanlight")
+
+ScoreValue = float | int | bool | str
+
+
+def build_score(
+    trace_id: str,
+    name: str,
+    value: ScoreValue,
+    *,
+    span_id: str | None = None,
+    comment: str | None = None,
+) -> dict[str, JsonValue] | None:
+    """Return the wire form of one score, or ``None`` (with a warning) when it cannot be sent.
+
+    A ``bool`` stays a JSON boolean, which makes the server infer a boolean score stored as
+    1 or 0. A ``str`` becomes ``string_value`` (a categorical score). Numbers must be finite.
+    """
+    if not isinstance(trace_id, str) or not isinstance(name, str):
+        logger.warning("Spanlight: score() needs a string trace_id and name; score dropped")
+        return None
+    payload: dict[str, JsonValue] = {"id": new_uuid7(), "trace_id": trace_id, "name": name}
+    if isinstance(value, bool):
+        payload["value"] = value
+    elif isinstance(value, int | float):
+        if not math.isfinite(value):
+            logger.warning("Spanlight: score %r has a non-finite value; score dropped", name)
+            return None
+        payload["value"] = value
+    elif isinstance(value, str):
+        payload["string_value"] = value
+    else:
+        logger.warning(
+            "Spanlight: score %r has an unsupported value type %s; score dropped",
+            name,
+            type(value).__name__,
+        )
+        return None
+    if span_id is not None:
+        payload["span_id"] = span_id
+    if comment is not None:
+        payload["comment"] = comment
+    return payload