promptfuse 0.1.0__py3-none-any.whl

promptfuse/__init__.py

@@ -0,0 +1,14 @@
+"""Local prompt registry with a Langfuse-compatible read API."""
+
+from promptfuse.client import Promptfuse
+from promptfuse.errors import InvalidPromptRequest, PromptNotFound, PromptStoreError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "InvalidPromptRequest",
+    "PromptNotFound",
+    "PromptStoreError",
+    "Promptfuse",
+    "__version__",
+]

promptfuse/cache.py

@@ -0,0 +1,217 @@
+"""In-memory prompt cache with stale-while-revalidate refresh."""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from promptfuse.chain import load_prompt
+from promptfuse.errors import InvalidPromptRequest, PromptNotFound, PromptStoreError
+from promptfuse.models import PromptClient, clone_client, fallback_client
+from promptfuse.registry import Registry
+from promptfuse.snapshot import Snapshot
+
+CacheKey = tuple[str, str, str | int]
+
+
+@dataclass
+class _Entry:
+    client: PromptClient
+    expires_at: float
+    ttl: float
+    prompt_type: str
+    version: int | None
+    label: str | None
+
+
+class MemoryCache:
+    """Cache resolved prompt clients in front of a registry."""
+
+    def __init__(
+        self,
+        registry: Registry,
+        *,
+        ttl_seconds: float = 60,
+        clock: Callable[[], float] | None = None,
+        seed: Registry | None = None,
+        snapshot: Snapshot | None = None,
+    ) -> None:
+        self._registry = registry
+        self._seed = seed
+        self._snapshot = snapshot
+        self._ttl = ttl_seconds
+        self._clock = clock if clock is not None else time.monotonic
+        self._entries: dict[CacheKey, _Entry] = {}
+        self._inflight: set[CacheKey] = set()
+        self._lock = threading.Lock()
+
+    def get_prompt(
+        self,
+        name: str,
+        *,
+        version: int | None = None,
+        label: str | None = None,
+        type: str = "text",
+        cache_ttl_seconds: float | None = None,
+        fallback: str | list[Any] | None = None,
+    ) -> PromptClient:
+        if version is not None and label is not None:
+            raise InvalidPromptRequest("label and version are mutually exclusive")
+        ttl = self._ttl if cache_ttl_seconds is None else cache_ttl_seconds
+        if isinstance(ttl, bool) or not isinstance(ttl, (int, float)) or ttl < 0:
+            raise InvalidPromptRequest(f"invalid cache ttl: {ttl!r}")
+        key = _key(name, version, label)
+        if ttl == 0:
+            return self._load(key, name, version, label, type, fallback, remember=False, ttl=0)
+        now = self._clock()
+        with self._lock:
+            entry = self._entries.get(key)
+            if entry is not None and entry.expires_at > now and entry.prompt_type == type:
+                return clone_client(entry.client)
+            stale = entry if entry is not None and entry.prompt_type == type else None
+        if stale is not None:
+            self._schedule(key, stale)
+            return clone_client(stale.client)
+        return self._load(key, name, version, label, type, fallback, remember=True, ttl=ttl)
+
+    def invalidate_labels(self, name: str) -> None:
+        with self._lock:
+            for key in [key for key in self._entries if key[0] == name and key[1] == "label"]:
+                del self._entries[key]
+        if self._snapshot is not None:
+            self._snapshot.drop_labels(name)
+
+    def _load(
+        self,
+        key: CacheKey,
+        name: str,
+        version: int | None,
+        label: str | None,
+        prompt_type: str,
+        fallback: str | list[Any] | None,
+        *,
+        remember: bool,
+        ttl: float,
+    ) -> PromptClient:
+        try:
+            loaded = load_prompt(
+                self._registry,
+                name=name,
+                version=version,
+                label=label,
+                prompt_type=prompt_type,
+                snapshot=self._snapshot,
+                key=key,
+                seed=self._seed,
+                allow_snapshot=True,
+            )
+        except PromptNotFound:
+            if fallback is not None:
+                return fallback_client(name, fallback)
+            raise
+        except PromptStoreError:
+            if fallback is not None:
+                return fallback_client(name, fallback)
+            raise
+        if loaded.source == "snapshot":
+            self._remember(
+                key,
+                loaded.client,
+                expires_at=self._clock(),
+                ttl=self._ttl,
+                prompt_type=prompt_type,
+                version=version,
+                label=label,
+            )
+            return clone_client(loaded.client)
+        self._remember_success(key, loaded.client, prompt_type, version, label, remember, ttl)
+        return clone_client(loaded.client)
+
+    def _remember_success(
+        self,
+        key: CacheKey,
+        client: PromptClient,
+        prompt_type: str,
+        version: int | None,
+        label: str | None,
+        remember: bool,
+        ttl: float,
+    ) -> None:
+        if remember:
+            self._remember(
+                key,
+                client,
+                expires_at=self._clock() + ttl,
+                ttl=ttl,
+                prompt_type=prompt_type,
+                version=version,
+                label=label,
+            )
+        if self._snapshot is not None:
+            self._snapshot.put(key, client)
+
+    def _remember(
+        self,
+        key: CacheKey,
+        client: PromptClient,
+        *,
+        expires_at: float,
+        ttl: float,
+        prompt_type: str,
+        version: int | None,
+        label: str | None,
+    ) -> None:
+        with self._lock:
+            self._entries[key] = _Entry(
+                client=clone_client(client),
+                expires_at=expires_at,
+                ttl=ttl,
+                prompt_type=prompt_type,
+                version=version,
+                label=label,
+            )
+
+    def _schedule(self, key: CacheKey, entry: _Entry) -> None:
+        with self._lock:
+            if key in self._inflight:
+                return
+            self._inflight.add(key)
+        thread = threading.Thread(target=self._refresh, args=(key, entry), daemon=True)
+        thread.start()
+
+    def _refresh(self, key: CacheKey, entry: _Entry) -> None:
+        try:
+            try:
+                loaded = load_prompt(
+                    self._registry,
+                    name=key[0],
+                    version=entry.version,
+                    label=entry.label,
+                    prompt_type=entry.prompt_type,
+                    snapshot=self._snapshot,
+                    key=key,
+                    seed=self._seed,
+                    allow_snapshot=False,
+                )
+            except (PromptNotFound, PromptStoreError):
+                return
+            self._remember_success(
+                key,
+                loaded.client,
+                entry.prompt_type,
+                entry.version,
+                entry.label,
+                True,
+                entry.ttl,
+            )
+        finally:
+            with self._lock:
+                self._inflight.discard(key)
+
+
+def _key(name: str, version: int | None, label: str | None) -> CacheKey:
+    if version is not None:
+        return (name, "version", version)
+    return (name, "label", "production" if label is None else label)

promptfuse/chain.py

@@ -0,0 +1,58 @@
+"""Read a primary registry, then the disk snapshot, then a YAML seed."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from promptfuse.errors import PromptNotFound, PromptStoreError
+from promptfuse.models import PromptClient
+from promptfuse.registry import Registry
+from promptfuse.snapshot import Snapshot
+
+Source = Literal["primary", "snapshot", "seed"]
+
+
+@dataclass(frozen=True)
+class LoadedPrompt:
+    client: PromptClient
+    source: Source
+
+
+def load_prompt(
+    registry: Registry,
+    *,
+    name: str,
+    version: int | None,
+    label: str | None,
+    prompt_type: str,
+    snapshot: Snapshot | None,
+    key: tuple[str, str, str | int],
+    seed: Registry | None,
+    allow_snapshot: bool,
+) -> LoadedPrompt:
+    """Resolve a prompt from the primary store.
+
+    ``PromptNotFound`` from a healthy primary store propagates. ``PromptStoreError``
+    tries the snapshot, then ``seed``, and then propagates.
+    """
+
+    try:
+        client = registry.get_prompt(name, version=version, label=label, type=prompt_type)
+    except PromptStoreError as exc:
+        if allow_snapshot and snapshot is not None:
+            try:
+                snapped = snapshot.get(key)
+            except PromptStoreError:
+                snapped = None
+            if snapped is not None and snapped.type == prompt_type:
+                return LoadedPrompt(snapped, "snapshot")
+        if seed is not None:
+            try:
+                seeded = seed.get_prompt(name, version=version, label=label, type=prompt_type)
+            except (PromptNotFound, PromptStoreError):
+                seeded = None
+            if seeded is not None:
+                return LoadedPrompt(seeded, "seed")
+        raise exc
+    return LoadedPrompt(client, "primary")

promptfuse/client.py

@@ -0,0 +1,108 @@
+"""Public promptfuse client."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from promptfuse.cache import MemoryCache
+from promptfuse.errors import InvalidPromptRequest
+from promptfuse.models import PromptClient
+from promptfuse.registry import Registry
+from promptfuse.snapshot import Snapshot
+from promptfuse.stores.sqlite import SqliteStore
+from promptfuse.stores.yaml import YamlStore
+
+
+class Promptfuse:
+    """Local prompt registry with a Langfuse-compatible prompt API."""
+
+    def __init__(
+        self,
+        *,
+        yaml_dir: Path | str | None = None,
+        sqlite_path: Path | str | None = None,
+        snapshot_path: Path | str | None = None,
+        cache_ttl_seconds: float = 60,
+        import_yaml: bool = False,
+    ) -> None:
+        if yaml_dir is None and sqlite_path is None:
+            raise InvalidPromptRequest("yaml_dir or sqlite_path is required")
+        self._yaml = YamlStore(yaml_dir) if yaml_dir is not None else None
+        self._sqlite = SqliteStore(sqlite_path) if sqlite_path is not None else None
+        if self._sqlite is not None:
+            primary = self._sqlite
+            seed = Registry(self._yaml) if self._yaml is not None else None
+        else:
+            primary = self._yaml
+            seed = None
+        if primary is None:
+            raise InvalidPromptRequest("yaml_dir or sqlite_path is required")
+        self._registry = Registry(primary)
+        snapshot = Snapshot(snapshot_path) if snapshot_path is not None else None
+        self._cache = MemoryCache(
+            self._registry,
+            ttl_seconds=cache_ttl_seconds,
+            seed=seed,
+            snapshot=snapshot,
+        )
+        if import_yaml:
+            self.import_yaml()
+
+    def get_prompt(
+        self,
+        name: str,
+        *,
+        version: int | None = None,
+        label: str | None = None,
+        type: str = "text",
+        cache_ttl_seconds: float | None = None,
+        fallback: str | list[Any] | None = None,
+    ) -> PromptClient:
+        return self._cache.get_prompt(
+            name,
+            version=version,
+            label=label,
+            type=type,
+            cache_ttl_seconds=cache_ttl_seconds,
+            fallback=fallback,
+        )
+
+    def create_prompt(
+        self,
+        name: str,
+        *,
+        type: str,
+        prompt: Any,
+        labels: list[str] | None = None,
+        config: dict[str, Any] | None = None,
+        tags: list[str] | None = None,
+        commit_message: str | None = None,
+    ) -> PromptClient:
+        client = self._registry.create_prompt(
+            name,
+            type=type,
+            prompt=prompt,
+            labels=labels,
+            config=config,
+            tags=tags,
+            commit_message=commit_message,
+        )
+        self._cache.invalidate_labels(name)
+        return client
+
+    def update_prompt(self, name: str, *, version: int, new_labels: list[str]) -> PromptClient:
+        client = self._registry.update_prompt(name, version=version, new_labels=new_labels)
+        self._cache.invalidate_labels(name)
+        return client
+
+    def import_yaml(self) -> None:
+        """Copy the YAML tree into the primary SQLite store."""
+
+        if self._yaml is None or self._sqlite is None:
+            raise InvalidPromptRequest("import_yaml requires yaml_dir and sqlite_path")
+        self._registry.import_records(self._yaml)
+        names = set(self._yaml.list_names())
+        names.update(name for name, _label, _version in self._yaml.label_assignments())
+        for name in names:
+            self._cache.invalidate_labels(name)

promptfuse/errors.py

@@ -0,0 +1,17 @@
+"""Errors raised by the prompt registry."""
+
+
+class PromptfuseError(Exception):
+    """Base error for promptfuse."""
+
+
+class PromptNotFound(PromptfuseError):
+    """The name, label, version, or prompt type does not resolve."""
+
+
+class InvalidPromptRequest(PromptfuseError):
+    """The request or the stored prompt breaks the registry rules."""
+
+
+class PromptStoreError(PromptfuseError):
+    """The store could not be read or written."""

promptfuse/models.py

@@ -0,0 +1,259 @@
+"""Prompt clients and Langfuse-style ``{{variable}}`` compilation."""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from promptfuse.errors import InvalidPromptRequest
+
+PromptType = str
+ChatItem = dict[str, Any]
+
+
+def find_variable_names(content: str) -> list[str]:
+    """Return ``{{name}}`` placeholders in ``content``, in order."""
+
+    names: list[str] = []
+    index = 0
+    while index < len(content):
+        found = _parse_variable(content, index)
+        if found is None:
+            break
+        names.append(found[0])
+        index = found[2]
+    return names
+
+
+def compile_template(content: str, data: Mapping[str, Any] | None = None) -> str:
+    """Substitute ``{{variable}}`` values.
+
+    A missing name is left unchanged, including its braces. ``None`` becomes
+    an empty string. Surrounding whitespace inside the braces is ignored.
+    """
+
+    if data is None:
+        return content
+    pieces: list[str] = []
+    index = 0
+    while index < len(content):
+        found = _parse_variable(content, index)
+        if found is None:
+            pieces.append(content[index:])
+            break
+        name, start, end = found
+        pieces.append(content[index:start])
+        if name in data:
+            value = data[name]
+            pieces.append("" if value is None else str(value))
+        else:
+            pieces.append(content[start:end])
+        index = end
+    return "".join(pieces)
+
+
+def _parse_variable(content: str, start_index: int) -> tuple[str, int, int] | None:
+    opening = content.find("{{", start_index)
+    if opening == -1:
+        return None
+    closing = content.find("}}", opening + 2)
+    if closing == -1:
+        return None
+    name = content[opening + 2 : closing].strip()
+    return name, opening, closing + 2
+
+
+def normalize_prompt(prompt_type: str, prompt: Any) -> str | list[ChatItem]:
+    """Return the stored form of a text or chat prompt."""
+
+    if prompt_type == "text":
+        if not isinstance(prompt, str):
+            raise InvalidPromptRequest("a text prompt must be a string")
+        return prompt
+    if prompt_type == "chat":
+        if not isinstance(prompt, list):
+            raise InvalidPromptRequest("a chat prompt must be a list of messages")
+        return [_normalize_chat_item(item) for item in prompt]
+    raise InvalidPromptRequest(f"unknown prompt type: {prompt_type!r}")
+
+
+def _normalize_chat_item(item: Any) -> ChatItem:
+    if not isinstance(item, dict):
+        raise InvalidPromptRequest("a chat item must be a mapping")
+    kind = item.get("type")
+    if kind == "placeholder" or (kind is None and "name" in item and "role" not in item):
+        if "role" in item or "content" in item:
+            raise InvalidPromptRequest("a placeholder must not include role or content")
+        name = item.get("name")
+        if not isinstance(name, str) or not name:
+            raise InvalidPromptRequest("a placeholder name must be a non-empty string")
+        return {"type": "placeholder", "name": name}
+    if kind not in (None, "message"):
+        raise InvalidPromptRequest(f"unknown chat item type: {kind!r}")
+    role = item.get("role")
+    content = item.get("content")
+    if not isinstance(role, str) or not isinstance(content, str):
+        raise InvalidPromptRequest("a chat message needs string role and content")
+    return {"type": "message", "role": role, "content": content}
+
+
+@dataclass(frozen=True)
+class TextPrompt:
+    """A text prompt client."""
+
+    name: str
+    version: int
+    prompt: str
+    config: dict[str, Any]
+    labels: tuple[str, ...]
+    tags: tuple[str, ...]
+    commit_message: str | None
+    is_fallback: bool = False
+
+    @property
+    def type(self) -> str:
+        return "text"
+
+    @property
+    def variables(self) -> list[str]:
+        return find_variable_names(self.prompt)
+
+    def compile(self, **kwargs: Any) -> str:
+        return compile_template(self.prompt, kwargs)
+
+
+@dataclass(frozen=True)
+class ChatPrompt:
+    """A chat prompt client."""
+
+    name: str
+    version: int
+    stored_messages: tuple[tuple[tuple[str, Any], ...], ...]
+    config: dict[str, Any]
+    labels: tuple[str, ...]
+    tags: tuple[str, ...]
+    commit_message: str | None
+    is_fallback: bool = False
+
+    @property
+    def type(self) -> str:
+        return "chat"
+
+    @property
+    def prompt(self) -> list[ChatItem]:
+        return [dict(item) for item in self.stored_messages]
+
+    @property
+    def variables(self) -> list[str]:
+        names: list[str] = []
+        for item in self.prompt:
+            if item.get("type") == "message":
+                names.extend(find_variable_names(item["content"]))
+        return names
+
+    def compile(self, **kwargs: Any) -> list[dict[str, Any]]:
+        compiled: list[dict[str, Any]] = []
+        for item in self.prompt:
+            if item["type"] == "message":
+                compiled.append(
+                    {
+                        "role": item["role"],
+                        "content": compile_template(item["content"], kwargs),
+                    }
+                )
+                continue
+            name = item["name"]
+            if name not in kwargs:
+                compiled.append({"type": "placeholder", "name": name})
+                continue
+            value = kwargs[name]
+            if isinstance(value, list):
+                for entry in value:
+                    if isinstance(entry, dict):
+                        copied = dict(entry)
+                        content = copied.get("content", "")
+                        if isinstance(content, str):
+                            copied["content"] = compile_template(content, kwargs)
+                        compiled.append(copied)
+                    else:
+                        compiled.append({"role": "NOT_GIVEN", "content": str(entry)})
+            else:
+                compiled.append({"role": "NOT_GIVEN", "content": str(value)})
+        return compiled
+
+
+PromptClient = TextPrompt | ChatPrompt
+
+
+def make_client(
+    *,
+    name: str,
+    version: int,
+    prompt_type: str,
+    prompt: str | list[ChatItem],
+    config: Mapping[str, Any] | None = None,
+    labels: list[str] | tuple[str, ...] = (),
+    tags: list[str] | tuple[str, ...] = (),
+    commit_message: str | None = None,
+    is_fallback: bool = False,
+) -> PromptClient:
+    """Build a prompt client from stored fields."""
+
+    stored_config = copy.deepcopy(dict(config or {}))
+    stored_labels = tuple(sorted(labels))
+    stored_tags = tuple(tags)
+    if prompt_type == "text":
+        if not isinstance(prompt, str):
+            raise InvalidPromptRequest("a text prompt must be a string")
+        return TextPrompt(
+            name=name,
+            version=version,
+            prompt=prompt,
+            config=stored_config,
+            labels=stored_labels,
+            tags=stored_tags,
+            commit_message=commit_message,
+            is_fallback=is_fallback,
+        )
+    if prompt_type == "chat":
+        normalized = normalize_prompt("chat", prompt)
+        assert isinstance(normalized, list)
+        frozen = tuple(tuple(sorted(item.items())) for item in normalized)
+        return ChatPrompt(
+            name=name,
+            version=version,
+            stored_messages=frozen,
+            config=stored_config,
+            labels=stored_labels,
+            tags=stored_tags,
+            commit_message=commit_message,
+            is_fallback=is_fallback,
+        )
+    raise InvalidPromptRequest(f"unknown prompt type: {prompt_type!r}")
+
+
+def fallback_client(name: str, fallback: str | list[Any]) -> PromptClient:
+    """Build the client used when the cache and the stores cannot answer."""
+
+    if isinstance(fallback, str):
+        prompt_type: str = "text"
+        prompt: str | list[ChatItem] = fallback
+    elif isinstance(fallback, list):
+        prompt_type = "chat"
+        prompt = normalize_prompt("chat", fallback)
+    else:
+        raise InvalidPromptRequest("fallback must be a string or a list of messages")
+    return make_client(
+        name=name,
+        version=0,
+        prompt_type=prompt_type,
+        prompt=prompt,
+        is_fallback=True,
+    )
+
+
+def clone_client(client: PromptClient) -> PromptClient:
+    """Return a detached copy of a cached client."""
+
+    return copy.deepcopy(client)