promptdock 0.1.0__py3-none-any.whl

promptdock/__init__.py

@@ -0,0 +1,29 @@
+"""PromptDock: prompt versioning with immutable versions and movable tags."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from promptdock.client import Client
+from promptdock.errors import (
+    DatabaseUnavailableError,
+    GateFailedError,
+    MissingVariableError,
+    NotFoundError,
+    PromptDockError,
+)
+from promptdock.prompt import Prompt
+
+try:
+    __version__ = version("promptdock")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0"
+
+__all__ = [
+    "Client",
+    "DatabaseUnavailableError",
+    "GateFailedError",
+    "MissingVariableError",
+    "NotFoundError",
+    "Prompt",
+    "PromptDockError",
+    "__version__",
+]

promptdock/actor.py

@@ -0,0 +1,11 @@
+"""Who made a change: a self-reported name, like a git author. Not verified."""
+
+import getpass
+
+
+def default_actor() -> str | None:
+    """The OS username, or None if it cannot be determined."""
+    try:
+        return getpass.getuser() or None
+    except Exception:  # getuser raises if no user name is available (e.g. some containers)
+        return None

promptdock/backends/__init__.py

@@ -0,0 +1,5 @@
+"""Backends the ``Client`` talks to: the database directly, or a PromptDock server."""
+
+from promptdock.backends.base import Backend
+
+__all__ = ["Backend"]

promptdock/backends/base.py

@@ -0,0 +1,75 @@
+"""The interface every backend implements. Methods mirror ``promptdock.core.service``."""
+
+from collections.abc import Sequence
+from typing import Protocol
+
+from promptdock.models import (
+    EvalResult,
+    EvalResultIn,
+    Gate,
+    Leaderboard,
+    PromptInfo,
+    PromptVersion,
+    PromptVersionCreate,
+    Tag,
+    TagEvent,
+    VersionDiff,
+)
+
+
+class Backend(Protocol):
+    """Raises ``DatabaseUnavailableError`` when the store cannot be reached."""
+
+    def create_prompt(self, project: str, name: str, description: str | None) -> PromptInfo: ...
+
+    def get_prompt_info(self, project: str, name: str) -> PromptInfo: ...
+
+    def list_prompts(self, project: str) -> list[PromptInfo]: ...
+
+    def create_version(
+        self, project: str, name: str, data: PromptVersionCreate, actor: str | None
+    ) -> PromptVersion: ...
+
+    def get_version(self, project: str, name: str, version: int | None) -> PromptVersion: ...
+
+    def get_by_tag(self, project: str, name: str, tag: str) -> PromptVersion: ...
+
+    def list_versions(self, project: str, name: str) -> list[PromptVersion]: ...
+
+    def list_tags(self, project: str, name: str) -> list[Tag]: ...
+
+    def set_gate(
+        self, project: str, name: str, tag: str, gate: Gate | None, actor: str | None
+    ) -> Tag: ...
+
+    def promote(
+        self,
+        project: str,
+        name: str,
+        tag: str,
+        version: int,
+        actor: str | None,
+        reason: str | None,
+        force: bool,
+        strict: bool,
+    ) -> Tag: ...
+
+    def rollback(
+        self, project: str, name: str, tag: str, actor: str | None, reason: str | None
+    ) -> Tag: ...
+
+    def list_tag_events(self, project: str, name: str, tag: str | None) -> list[TagEvent]: ...
+
+    def add_eval_results(self, results: Sequence[EvalResultIn]) -> list[EvalResult]: ...
+
+    def leaderboard(
+        self, project: str, name: str, sort_by: str, descending: bool
+    ) -> Leaderboard: ...
+
+    def diff(self, project: str, name: str, a: int, b: int) -> VersionDiff: ...
+
+    def get_eval_results(
+        self, project: str, name: str, version: int | None
+    ) -> list[EvalResult]: ...
+
+    def close(self) -> None: ...

promptdock/backends/db.py

@@ -0,0 +1,117 @@
+"""Library mode: talk to Postgres directly through ``promptdock.core.service``."""
+
+from collections.abc import Callable, Iterator, Sequence
+from contextlib import contextmanager
+from typing import TypeVar
+
+from sqlalchemy.exc import InterfaceError, OperationalError
+from sqlalchemy.orm import Session
+
+from promptdock.core import compare, service
+from promptdock.db.engine import make_engine
+from promptdock.errors import DatabaseUnavailableError
+from promptdock.models import (
+    EvalResult,
+    EvalResultIn,
+    Gate,
+    Leaderboard,
+    PromptInfo,
+    PromptVersion,
+    PromptVersionCreate,
+    Tag,
+    TagEvent,
+    VersionDiff,
+)
+
+T = TypeVar("T")
+
+
+class DbBackend:
+    """Each call runs in its own transaction and commits on success."""
+
+    def __init__(self, database_url: str | None = None, connect_timeout: int = 10) -> None:
+        self._engine = make_engine(database_url, connect_timeout)
+
+    def run(self, fn: Callable[[Session], T]) -> T:
+        """Run ``fn`` in its own transaction, committing on success."""
+        with self._session() as session:
+            return fn(session)
+
+    @contextmanager
+    def _session(self) -> Iterator[Session]:
+        try:
+            with Session(self._engine) as session, session.begin():
+                yield session
+        except (OperationalError, InterfaceError) as exc:
+            raise DatabaseUnavailableError(f"Database unavailable: {exc.orig}") from exc
+
+    def create_prompt(self, project: str, name: str, description: str | None) -> PromptInfo:
+        return self.run(lambda s: service.create_prompt(s, name, description, project))
+
+    def get_prompt_info(self, project: str, name: str) -> PromptInfo:
+        return self.run(lambda s: service.get_prompt(s, name, project))
+
+    def list_prompts(self, project: str) -> list[PromptInfo]:
+        return self.run(lambda s: service.list_prompts(s, project))
+
+    def create_version(
+        self, project: str, name: str, data: PromptVersionCreate, actor: str | None
+    ) -> PromptVersion:
+        return self.run(lambda s: service.create_version(s, name, data, project, actor))
+
+    def get_version(self, project: str, name: str, version: int | None) -> PromptVersion:
+        return self.run(lambda s: service.get_version(s, name, version, project))
+
+    def get_by_tag(self, project: str, name: str, tag: str) -> PromptVersion:
+        return self.run(lambda s: service.get_by_tag(s, name, tag, project))
+
+    def list_versions(self, project: str, name: str) -> list[PromptVersion]:
+        return self.run(lambda s: service.list_versions(s, name, project))
+
+    def list_tags(self, project: str, name: str) -> list[Tag]:
+        return self.run(lambda s: service.list_tags(s, name, project))
+
+    def set_gate(
+        self, project: str, name: str, tag: str, gate: Gate | None, actor: str | None
+    ) -> Tag:
+        return self.run(lambda s: service.set_gate(s, name, tag, gate, project, actor))
+
+    def promote(
+        self,
+        project: str,
+        name: str,
+        tag: str,
+        version: int,
+        actor: str | None,
+        reason: str | None,
+        force: bool,
+        strict: bool,
+    ) -> Tag:
+        return self.run(
+            lambda s: service.promote(
+                s, name, tag, version, actor, reason, force, project, strict=strict
+            )
+        )
+
+    def rollback(
+        self, project: str, name: str, tag: str, actor: str | None, reason: str | None
+    ) -> Tag:
+        return self.run(lambda s: service.rollback(s, name, tag, actor, reason, project))
+
+    def list_tag_events(self, project: str, name: str, tag: str | None) -> list[TagEvent]:
+        return self.run(lambda s: service.list_tag_events(s, name, tag, project))
+
+    def add_eval_results(self, results: Sequence[EvalResultIn]) -> list[EvalResult]:
+        return self.run(lambda s: service.add_eval_results(s, results))
+
+    def leaderboard(self, project: str, name: str, sort_by: str, descending: bool) -> Leaderboard:
+        return self.run(lambda s: compare.leaderboard(s, name, sort_by, descending, project))
+
+    def diff(self, project: str, name: str, a: int, b: int) -> VersionDiff:
+        return self.run(lambda s: compare.diff(s, name, a, b, project))
+
+    def get_eval_results(self, project: str, name: str, version: int | None) -> list[EvalResult]:
+        return self.run(lambda s: service.get_eval_results(s, name, version, project))
+
+    def close(self) -> None:
+        self._engine.dispose()

promptdock/backends/http.py

@@ -0,0 +1,244 @@
+"""Server mode: talk to a ``promptdock serve`` instance over HTTP."""
+
+from collections.abc import Sequence
+from typing import Any, TypeVar
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, TypeAdapter
+
+from promptdock import errors
+from promptdock.models import (
+    CreatePromptRequest,
+    EvalResult,
+    EvalResultIn,
+    Gate,
+    Leaderboard,
+    PromoteRequest,
+    PromptInfo,
+    PromptVersion,
+    PromptVersionCreate,
+    RollbackRequest,
+    SetGateRequest,
+    Tag,
+    TagEvent,
+    VersionDiff,
+)
+
+M = TypeVar("M", bound=BaseModel)
+
+_ERROR_CLASSES: dict[str, type[errors.PromptDockError]] = {
+    name: cls
+    for name, cls in vars(errors).items()
+    if isinstance(cls, type) and issubclass(cls, errors.PromptDockError)
+}
+
+
+class HttpBackend:
+    """Implements the same methods as ``DbBackend`` by calling the REST API.
+
+    Server errors are raised as the same exception classes library mode raises.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str | None,
+        timeout: float = 5.0,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        headers = {"Authorization": f"Bearer {token}"} if token else {}
+        if http_client is None:
+            self._http = httpx.Client(base_url=base_url, headers=headers, timeout=timeout)
+        else:
+            http_client.headers.update(headers)
+            self._http = http_client
+        # Last response per prompt URL, for conditional requests (ETag / 304).
+        self._etags: dict[str, tuple[str, PromptVersion]] = {}
+
+    # --- prompts -------------------------------------------------------------------------
+
+    def create_prompt(self, project: str, name: str, description: str | None) -> PromptInfo:
+        body = CreatePromptRequest(name=name, description=description)
+        return self._call(PromptInfo, "POST", "/prompts", project, json=_dump(body))
+
+    def get_prompt_info(self, project: str, name: str) -> PromptInfo:
+        return self._call(PromptInfo, "GET", f"/prompts/{_q(name)}/info", project)
+
+    def list_prompts(self, project: str) -> list[PromptInfo]:
+        return self._call_list(PromptInfo, "GET", "/prompts", project)
+
+    # --- versions ------------------------------------------------------------------------
+
+    def create_version(
+        self, project: str, name: str, data: PromptVersionCreate, actor: str | None
+    ) -> PromptVersion:
+        path = f"/prompts/{_q(name)}/versions"
+        return self._call(
+            PromptVersion, "POST", path, project, json=_dump(data), headers=_actor(actor)
+        )
+
+    def get_version(self, project: str, name: str, version: int | None) -> PromptVersion:
+        if version is None:
+            return self._get_conditional(project, name, {})
+        path = f"/prompts/{_q(name)}/versions/{version}"
+        return self._call(PromptVersion, "GET", path, project)
+
+    def get_by_tag(self, project: str, name: str, tag: str) -> PromptVersion:
+        return self._get_conditional(project, name, {"tag": tag})
+
+    def list_versions(self, project: str, name: str) -> list[PromptVersion]:
+        return self._call_list(PromptVersion, "GET", f"/prompts/{_q(name)}/versions", project)
+
+    # --- tags ----------------------------------------------------------------------------
+
+    def list_tags(self, project: str, name: str) -> list[Tag]:
+        return self._call_list(Tag, "GET", f"/prompts/{_q(name)}/tags", project)
+
+    def set_gate(
+        self, project: str, name: str, tag: str, gate: Gate | None, actor: str | None
+    ) -> Tag:
+        path = f"/prompts/{_q(name)}/tags/{_q(tag)}/gate"
+        body = _dump(SetGateRequest(gate=gate))
+        return self._call(Tag, "PUT", path, project, json=body, headers=_actor(actor))
+
+    def promote(
+        self,
+        project: str,
+        name: str,
+        tag: str,
+        version: int,
+        actor: str | None,
+        reason: str | None,
+        force: bool,
+        strict: bool,
+    ) -> Tag:
+        body = PromoteRequest(version=version, reason=reason, force=force, strict=strict)
+        path = f"/prompts/{_q(name)}/tags/{_q(tag)}"
+        return self._call(Tag, "PUT", path, project, json=_dump(body), headers=_actor(actor))
+
+    def rollback(
+        self, project: str, name: str, tag: str, actor: str | None, reason: str | None
+    ) -> Tag:
+        body = RollbackRequest(reason=reason)
+        path = f"/prompts/{_q(name)}/tags/{_q(tag)}/rollback"
+        return self._call(Tag, "POST", path, project, json=_dump(body), headers=_actor(actor))
+
+    def list_tag_events(self, project: str, name: str, tag: str | None) -> list[TagEvent]:
+        if tag is None:
+            path = f"/prompts/{_q(name)}/events"
+        else:
+            path = f"/prompts/{_q(name)}/tags/{_q(tag)}/events"
+        return self._call_list(TagEvent, "GET", path, project)
+
+    # --- evals ---------------------------------------------------------------------------
+
+    def add_eval_results(self, results: Sequence[EvalResultIn]) -> list[EvalResult]:
+        body = [_dump(r) for r in results]
+        return self._call_list(EvalResult, "POST", "/evals", None, json=body)
+
+    def leaderboard(self, project: str, name: str, sort_by: str, descending: bool) -> Leaderboard:
+        params = {"sort": sort_by, "order": "desc" if descending else "asc"}
+        path = f"/prompts/{_q(name)}/leaderboard"
+        return self._call(Leaderboard, "GET", path, project, params=params)
+
+    def diff(self, project: str, name: str, a: int, b: int) -> VersionDiff:
+        path = f"/prompts/{_q(name)}/diff"
+        return self._call(VersionDiff, "GET", path, project, params={"a": a, "b": b})
+
+    def get_eval_results(self, project: str, name: str, version: int | None) -> list[EvalResult]:
+        params = {"version": version} if version is not None else {}
+        path = f"/prompts/{_q(name)}/evals"
+        return self._call_list(EvalResult, "GET", path, project, params=params)
+
+    def close(self) -> None:
+        self._http.close()
+
+    # --- plumbing ------------------------------------------------------------------------
+
+    def _get_conditional(self, project: str, name: str, params: dict[str, Any]) -> PromptVersion:
+        """GET /prompts/{name}, sending the last ETag so an unchanged prompt costs a 304."""
+        path = f"/prompts/{_q(name)}"
+        cache_key = f"{project}|{path}|{sorted(params.items())}"
+        headers = {}
+        previous = self._etags.get(cache_key)
+        if previous is not None:
+            headers["If-None-Match"] = previous[0]
+        response = self._send("GET", path, project, params=params, headers=headers)
+        if response.status_code == 304 and previous is not None:
+            return previous[1]
+        result = PromptVersion.model_validate(response.json())
+        if etag := response.headers.get("ETag"):
+            self._etags[cache_key] = (etag, result)
+        return result
+
+    def _call(self, model: type[M], method: str, path: str, project: str | None, **kw: Any) -> M:
+        return model.model_validate(self._send(method, path, project, **kw).json())
+
+    def _call_list(
+        self, model: type[M], method: str, path: str, project: str | None, **kw: Any
+    ) -> list[M]:
+        return TypeAdapter(list[model]).validate_python(  # type: ignore[valid-type]
+            self._send(method, path, project, **kw).json()
+        )
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        project: str | None,
+        *,
+        params: dict[str, Any] | None = None,
+        **kw: Any,
+    ) -> httpx.Response:
+        params = dict(params or {})
+        if project is not None:
+            params["project"] = project
+        try:
+            response = self._http.request(method, path, params=params, **kw)
+        except httpx.TransportError as exc:
+            raise errors.ServerUnavailableError(f"PromptDock server unreachable: {exc}") from exc
+        if response.status_code >= 400:
+            raise _to_error(response)
+        return response
+
+
+def _to_error(response: httpx.Response) -> errors.PromptDockError:
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = {}
+    error = payload.get("error") if isinstance(payload, dict) else None
+
+    if isinstance(error, dict):
+        cls = _ERROR_CLASSES.get(str(error.get("type")), errors.PromptDockError)
+        message = str(error.get("message", ""))
+        if cls is errors.GateFailedError:
+            return errors.GateFailedError(error["prompt"], error["tag"], list(error["failures"]))
+        if cls is errors.MissingVariableError:
+            return errors.InvalidInputError(message)
+        if cls is errors.DatabaseUnavailableError:
+            # The server is up but its database is not: from here, the server is unavailable.
+            return errors.ServerUnavailableError(message)
+        return cls(message)
+
+    if response.status_code == 422:
+        return errors.InvalidInputError(f"Invalid request: {payload.get('detail', payload)}")
+    if response.status_code == 401:
+        return errors.AuthenticationError("The server requires a token")
+    if response.status_code >= 500:
+        return errors.ServerUnavailableError(f"PromptDock server error {response.status_code}")
+    return errors.PromptDockError(f"Unexpected response {response.status_code}: {response.text}")
+
+
+def _actor(actor: str | None) -> dict[str, str]:
+    """X-Actor header; URL-encoded so names with any characters fit in a header."""
+    return {"X-Actor": quote(actor, safe="")} if actor else {}
+
+
+def _dump(model: BaseModel) -> Any:
+    return model.model_dump(mode="json", by_alias=True)
+
+
+def _q(segment: str) -> str:
+    return quote(segment, safe="")

promptdock/cache.py

@@ -0,0 +1,111 @@
+"""In-memory TTL cache with a last-known-good fallback and an optional snapshot file."""
+
+import json
+import logging
+import os
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from promptdock.models import PromptVersion
+
+logger = logging.getLogger("promptdock")
+
+
+@dataclass
+class _Entry:
+    value: PromptVersion
+    fetched_at: float
+    immutable: bool
+    stale: bool
+
+
+class PromptCache:
+    """Caches prompt versions by lookup key.
+
+    Entries for a tag (or "latest") are fresh for ``ttl`` seconds. Entries fetched by
+    version number never expire, because versions never change. Expired entries are kept
+    as the last known good copy for when the database is unreachable.
+
+    If ``snapshot_path`` is set, every fetched version is also written to that JSON file
+    so a freshly started process can fall back to it before its first successful read.
+    """
+
+    def __init__(
+        self,
+        ttl: float,
+        snapshot_path: str | Path | None = None,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.ttl = ttl
+        self.snapshot_path = Path(snapshot_path) if snapshot_path is not None else None
+        self._clock = clock
+        self._entries: dict[str, _Entry] = {}
+        self._lock = threading.Lock()
+
+    def get_fresh(self, key: str) -> tuple[PromptVersion, bool] | None:
+        """``(value, is_stale)`` if the entry has not expired, else None."""
+        with self._lock:
+            entry = self._entries.get(key)
+        if entry is None:
+            return None
+        if entry.immutable or self._clock() - entry.fetched_at < self.ttl:
+            return entry.value, entry.stale
+        return None
+
+    def get_stale(self, key: str) -> PromptVersion | None:
+        """Last known good value from memory, else from the snapshot file."""
+        with self._lock:
+            entry = self._entries.get(key)
+        if entry is not None:
+            return entry.value
+        return self._read_snapshot().get(key)
+
+    def put(
+        self, key: str, value: PromptVersion, *, immutable: bool = False, stale: bool = False
+    ) -> None:
+        """Store a value. ``stale=True`` re-stores a last-known-good copy while the database
+        is down, so it is served (and the database retried) once per TTL, not every call."""
+        with self._lock:
+            previous = self._entries.get(key)
+            self._entries[key] = _Entry(value, self._clock(), immutable, stale)
+        if not stale and (previous is None or previous.value.id != value.id):
+            self._write_snapshot(key, value)
+
+    def invalidate(self, prefix: str = "") -> None:
+        """Expire entries whose key starts with ``prefix`` (all entries by default).
+
+        They stay available as last-known-good copies.
+        """
+        with self._lock:
+            for key, entry in self._entries.items():
+                if key.startswith(prefix) and not entry.immutable:
+                    entry.fetched_at = float("-inf")
+
+    def _read_snapshot(self) -> dict[str, PromptVersion]:
+        if self.snapshot_path is None or not self.snapshot_path.exists():
+            return {}
+        try:
+            raw = json.loads(self.snapshot_path.read_text(encoding="utf-8"))
+            return {key: PromptVersion.model_validate(value) for key, value in raw.items()}
+        except (OSError, ValueError) as exc:
+            logger.warning("Ignoring unreadable prompt snapshot %s: %s", self.snapshot_path, exc)
+            return {}
+
+    def _write_snapshot(self, key: str, value: PromptVersion) -> None:
+        if self.snapshot_path is None:
+            return
+        with self._lock:
+            try:
+                data: dict[str, object] = {}
+                if self.snapshot_path.exists():
+                    data = json.loads(self.snapshot_path.read_text(encoding="utf-8"))
+                data[key] = value.model_dump(mode="json", by_alias=True)
+                self.snapshot_path.parent.mkdir(parents=True, exist_ok=True)
+                tmp = self.snapshot_path.with_suffix(self.snapshot_path.suffix + ".tmp")
+                tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")
+                os.replace(tmp, self.snapshot_path)
+            except (OSError, ValueError) as exc:
+                logger.warning("Could not write prompt snapshot %s: %s", self.snapshot_path, exc)