promptkeep 0.1.0__py3-none-any.whl

promptkeep/__init__.py

@@ -0,0 +1,29 @@
+"""promptkeep: versioned prompt templates with lineage and run tracking.
+
+Public API:
+
+    from promptkeep import Prompt, prompt, wrap, configure, history
+"""
+
+from . import history
+from .config import configure, get_settings
+from .decorator import prompt
+from .integrations import wrap
+from .prompts import Prompt, RenderedText
+from .rendering import MissingVariableError, TemplateParseError, extract_placeholders
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Prompt",
+    "RenderedText",
+    "prompt",
+    "wrap",
+    "configure",
+    "get_settings",
+    "history",
+    "extract_placeholders",
+    "MissingVariableError",
+    "TemplateParseError",
+    "__version__",
+]

promptkeep/config.py

@@ -0,0 +1,82 @@
+"""Global library configuration: DB location, tracking on/off, strict rendering.
+
+Settings are resolved fresh on every access with a simple precedence:
+explicit ``configure()`` overrides win, then environment variables
+(``PROMPTKEEP_DB``, ``PROMPTKEEP_DISABLED``), then defaults.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Union
+
+DEFAULT_DB_FILENAME = ".promptkeep.db"
+
+# configure() overrides live here; guarded by a lock since wrapped clients
+# may resolve settings from multiple threads.
+_lock = threading.Lock()
+_overrides: dict = {}
+
+
+@dataclass(frozen=True)
+class Settings:
+    """A resolved, immutable snapshot of the library's configuration."""
+
+    db_path: Path
+    enabled: bool
+    strict: bool
+
+
+def configure(
+    db_path: Optional[Union[str, Path]] = None,
+    enabled: Optional[bool] = None,
+    strict: Optional[bool] = None,
+) -> None:
+    """Override library settings. Only the arguments you pass are changed.
+
+    - db_path: where the SQLite database lives (default: ./.promptkeep.db,
+      or the PROMPTKEEP_DB env var).
+    - enabled: turn persistence on/off entirely (default: on, unless
+      PROMPTKEEP_DISABLED is set). Rendering works either way.
+    - strict: raise on missing variables instead of leaving `{name}` literal
+      (default: False).
+    """
+    with _lock:
+        if db_path is not None:
+            _overrides["db_path"] = Path(db_path)
+        if enabled is not None:
+            _overrides["enabled"] = bool(enabled)
+        if strict is not None:
+            _overrides["strict"] = bool(strict)
+
+
+def get_settings() -> Settings:
+    """Resolve the current settings: configure() overrides > env vars > defaults."""
+    with _lock:
+        # DB path: explicit override, then $PROMPTKEEP_DB, then ./.promptkeep.db.
+        db_path = _overrides.get("db_path")
+        if db_path is None:
+            env_path = os.environ.get("PROMPTKEEP_DB")
+            db_path = Path(env_path) if env_path else Path.cwd() / DEFAULT_DB_FILENAME
+
+        # Tracking: on by default; $PROMPTKEEP_DISABLED=1/true/yes/on kills it.
+        enabled = _overrides.get("enabled")
+        if enabled is None:
+            disabled = os.environ.get("PROMPTKEEP_DISABLED", "").strip().lower()
+            enabled = disabled not in ("1", "true", "yes", "on")
+
+        # Rendering strictness: lenient unless explicitly opted in.
+        strict = _overrides.get("strict", False)
+        return Settings(db_path=db_path, enabled=enabled, strict=strict)
+
+
+def reset() -> None:
+    """Clear all configure() overrides and drop cached DB state. Mainly for tests."""
+    with _lock:
+        _overrides.clear()
+    from . import storage
+
+    storage.reset_caches()

promptkeep/decorator.py

@@ -0,0 +1,97 @@
+"""@prompt decorator for computed prompts.
+
+The decorated function returns the *raw template* (placeholders intact); the
+decorator turns each call into a Prompt object, using the call's arguments as
+the variables dict. Both raw and rendered live on the returned Prompt, so
+lineage and run tracking work exactly like literal prompts.
+"""
+
+from __future__ import annotations
+
+import functools
+import hashlib
+import inspect
+import textwrap
+from typing import Any, Callable, Optional
+
+from .prompts import Prompt
+
+
+def _function_source_hash(fn: Callable) -> Optional[str]:
+    """Hash the function's source so history can tell code changes apart from
+    same-code output changes. None when source isn't available (e.g. REPL)."""
+    try:
+        source = textwrap.dedent(inspect.getsource(fn))
+    except (OSError, TypeError):
+        return None
+    return hashlib.sha256(source.encode("utf-8")).hexdigest()
+
+
+def prompt(name: str, strict: Optional[bool] = None):
+    """Turn a template-building function into a Prompt factory.
+
+        @prompt(name="REVIEW_SYSTEM")
+        def review_sys_prompt(var1="some value"):
+            return "You are a reviewer. Focus on {var1}."
+
+        p = review_sys_prompt(var1="security")   # -> Prompt
+        p.raw    # the template the function returned
+        p.text   # rendered with the call's arguments
+
+    The version identity is the returned template text (content-hash dedup);
+    a hash of the function's source is stored alongside each version so
+    history can tell "code changed" apart from "same code, different output".
+    """
+    # Catch the bare-decorator mistake (@prompt without parentheses) early.
+    if callable(name):
+        raise TypeError(
+            '@prompt requires a name: use @prompt(name="MY_PROMPT") — '
+            "the name is the prompt's stable identity"
+        )
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError("@prompt requires a non-empty name string")
+
+    def decorate(fn: Callable[..., str]):
+        """Wrap fn so each call yields a Prompt built from its return value."""
+        # Computed once at decoration time; identical for every call.
+        fn_hash = _function_source_hash(fn)
+        signature = inspect.signature(fn)
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Prompt:
+            """Call fn, then package its returned template into a Prompt."""
+            # Capture the full call (including defaults) as the variables dict.
+            bound = signature.bind(*args, **kwargs)
+            bound.apply_defaults()
+            variables: dict = {}
+            for param_name, value in bound.arguments.items():
+                kind = signature.parameters[param_name].kind
+                if kind is inspect.Parameter.VAR_KEYWORD:
+                    # **kwargs entries become top-level variables.
+                    variables.update(value)
+                elif kind is inspect.Parameter.VAR_POSITIONAL:
+                    # *args recorded as a list under the parameter's name.
+                    variables[param_name] = list(value)
+                else:
+                    variables[param_name] = value
+
+            # The function's return value is the raw template.
+            template = fn(*args, **kwargs)
+            if not isinstance(template, str):
+                raise TypeError(
+                    f"@prompt function {fn.__name__!r} must return a template string,"
+                    f" got {type(template).__name__}"
+                )
+            return Prompt(
+                template,
+                variables,
+                name=name,
+                strict=strict,
+                source="decorator",
+                fn_source_hash=fn_hash,
+            )
+
+        wrapper.prompt_name = name  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorate

promptkeep/history.py

@@ -0,0 +1,117 @@
+"""Query the lineage and run history of a prompt by name.
+
+The read-side API: storage returns raw dict rows; this module shapes them
+into typed, immutable dataclasses that are pleasant to work with.
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from . import storage
+
+
+@dataclass(frozen=True)
+class VersionInfo:
+    """One version of a prompt's template, as recorded in the lineage."""
+
+    version: int
+    template: str
+    template_hash: str
+    source: str
+    fn_source_hash: Optional[str]
+    created_at: str
+
+
+@dataclass(frozen=True)
+class RunInfo:
+    """One recorded execution: which version ran, with what, and what came back."""
+
+    id: int
+    prompt_name: str
+    version: int
+    variables: Optional[Dict[str, Any]]
+    rendered_text: str
+    provider: str
+    model: Optional[str]
+    request_params: Optional[Dict[str, Any]]
+    response_id: Optional[str]
+    output_text: Optional[str]
+    prompt_tokens: Optional[int]
+    completion_tokens: Optional[int]
+    total_tokens: Optional[int]
+    latency_ms: Optional[int]
+    status: str
+    error: Optional[str]
+    created_at: str
+
+
+def _load_json(value: Optional[str]):
+    """Decode a stored JSON column; malformed/missing data becomes None."""
+    if value is None:
+        return None
+    try:
+        return json.loads(value)
+    except (ValueError, TypeError):
+        return None
+
+
+def versions(name: str) -> List[VersionInfo]:
+    """All versions of a prompt, oldest first."""
+    return [
+        VersionInfo(
+            version=row["version"],
+            template=row["template"],
+            template_hash=row["template_hash"],
+            source=row["source"],
+            fn_source_hash=row["fn_source_hash"],
+            created_at=row["created_at"],
+        )
+        for row in storage.fetch_versions(name)
+    ]
+
+
+def diff(name: str, old: int, new: int) -> str:
+    """Unified diff between two versions of a prompt's template."""
+    # Load the lineage once and validate both requested versions exist.
+    by_number = {v.version: v for v in versions(name)}
+    for wanted in (old, new):
+        if wanted not in by_number:
+            raise ValueError(f"prompt {name!r} has no version {wanted}")
+    lines = difflib.unified_diff(
+        by_number[old].template.splitlines(),
+        by_number[new].template.splitlines(),
+        fromfile=f"{name} v{old}",
+        tofile=f"{name} v{new}",
+        lineterm="",
+    )
+    return "\n".join(lines)
+
+
+def runs(name: str, version: Optional[int] = None, limit: int = 50) -> List[RunInfo]:
+    """Recorded runs for a prompt (optionally one version), newest first."""
+    return [
+        RunInfo(
+            id=row["id"],
+            prompt_name=row["prompt_name"],
+            version=row["version"],
+            variables=_load_json(row["variables"]),
+            rendered_text=row["rendered_text"],
+            provider=row["provider"],
+            model=row["model"],
+            request_params=_load_json(row["request_params"]),
+            response_id=row["response_id"],
+            output_text=row["output_text"],
+            prompt_tokens=row["prompt_tokens"],
+            completion_tokens=row["completion_tokens"],
+            total_tokens=row["total_tokens"],
+            latency_ms=row["latency_ms"],
+            status=row["status"],
+            error=row["error"],
+            created_at=row["created_at"],
+        )
+        for row in storage.fetch_runs(name, version=version, limit=limit)
+    ]

promptkeep/integrations/__init__.py

@@ -0,0 +1,33 @@
+"""Provider integrations. `wrap()` is the public entry point."""
+
+from __future__ import annotations
+
+
+def wrap(target):
+    """Wrap an OpenAI client class or instance so Prompt objects work as
+    message content and every call is recorded as a run.
+
+        from openai import OpenAI
+        from promptkeep import wrap
+
+        OpenAI = wrap(OpenAI)          # wrap the class...
+        client = OpenAI(api_key=...)   # ...then use it exactly as before
+
+        # or wrap a live client:
+        client = wrap(OpenAI(api_key=...))
+    """
+    from .openai_wrapper import wrap_openai_class, wrap_openai_instance
+
+    if isinstance(target, type):
+        return wrap_openai_class(target)
+    chat = getattr(target, "chat", None)
+    completions = getattr(chat, "completions", None)
+    if completions is not None and hasattr(completions, "create"):
+        return wrap_openai_instance(target)
+    raise TypeError(
+        "wrap() expects an OpenAI client class or instance"
+        f" (an object with .chat.completions.create); got {target!r}"
+    )
+
+
+__all__ = ["wrap"]