gateforge-sdk 0.2.5__tar.gz → 0.2.6__tar.gz

{gateforge_sdk-0.2.5 → gateforge_sdk-0.2.6}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: gateforge-sdk
-Version: 0.2.5
-Summary: Privacy-first LLMOps SDK — Auto-init, tool/agent decorators, session management, nested conversation support
+Version: 0.2.6
+Summary: Privacy-first LLMOps SDK — Auto-init, decorators, session management, prompt system with cache
 Project-URL: Homepage, https://gateforge.dev
 Project-URL: Documentation, https://gateforge.dev/docs
 Project-URL: Repository, https://github.com/gateforge/gateforge-sdk

{gateforge_sdk-0.2.5 → gateforge_sdk-0.2.6}/gateforge/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__version__ = "0.2.5"
+__version__ = "0.2.6"
 
 # Auto-install spaCy model if missing (required for PII detection)
 def _ensure_spacy_model():
@@ -21,7 +21,7 @@ from gateforge.client import GatforgeClient
 from gateforge.context import trace, continue_session, session, tool, agent
 from gateforge.features import FeatureFlags
 from gateforge.options import CallOptions
-from gateforge.prompt import Prompt
+from gateforge.prompt import Prompt, PromptCache, PromptBuilder, get_prompt, set_prompt, get_prompt_cache
 from gateforge.response import GatforgeResponse
 from gateforge.tracing import configure_otel
 from gateforge.ab.engine import VariantAssignment
@@ -423,10 +423,15 @@ __all__ = [
     "wrap_openai",
     "wrap_anthropic",
     "wrap_gemini",
-    # Prompt library
+    # Prompt library (Phase 3)
+    "Prompt",
+    "PromptCache",
+    "PromptBuilder",
+    "get_prompt",
+    "set_prompt",
+    "get_prompt_cache",
     "get_prompt",
     "get_prompts",
-    "Prompt",
     # Conversation tracing
     "trace",
     "continue_session",

gateforge_sdk-0.2.6/gateforge/prompt.py

@@ -0,0 +1,537 @@
+"""
+Phase 3: Prompt System
+
+Provides:
+- Prompt class for versioned prompts with metadata
+- PromptCache for multi-level caching (memory + file + backend)
+- PromptBuilder for prompt composition
+- get_prompt() for fetching prompts from backend
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any, List
+from pathlib import Path
+
+
+@dataclass
+class Prompt:
+    """
+    Represents a versioned prompt with metadata.
+    
+    Attributes:
+        name: Prompt identifier (e.g., "agent-system")
+        content: The actual prompt text
+        version: Version number
+        variables: Dictionary of variable names to default values
+        metadata: Additional metadata (tags, author, created_at, etc.)
+        source: Where the prompt came from ("cache", "backend", "file", "builder")
+    """
+    name: str
+    content: str
+    version: int = 1
+    variables: Dict[str, Any] = field(default_factory=dict)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    source: str = "unknown"
+    
+    def render(self, **overrides: Any) -> str:
+        """
+        Render the prompt with variable substitution.
+        
+        Variables in content should be formatted as {{variable_name}}.
+        
+        Args:
+            **overrides: Variable values to override defaults
+        
+        Returns:
+            Rendered prompt string
+        
+        Usage::
+            prompt = Prompt(
+                name="greeting",
+                content="Hello, {{name}}! You are {{role}}.",
+                variables={"name": "User", "role": "a developer"}
+            )
+            rendered = prompt.render(name="Alice")
+            # → "Hello, Alice! You are a developer."
+        """
+        variables = {**self.variables, **overrides}
+        result = self.content
+        
+        for name, value in variables.items():
+            placeholder = "{{" + name + "}}"
+            result = result.replace(placeholder, str(value))
+        
+        return result
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize prompt to dictionary."""
+        return {
+            "name": self.name,
+            "content": self.content,
+            "version": self.version,
+            "variables": self.variables,
+            "metadata": self.metadata,
+            "source": self.source,
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> Prompt:
+        """Deserialize prompt from dictionary."""
+        return cls(
+            name=data["name"],
+            content=data["content"],
+            version=data.get("version", 1),
+            variables=data.get("variables", {}),
+            metadata=data.get("metadata", {}),
+            source=data.get("source", "unknown"),
+        )
+    
+    def fingerprint(self) -> str:
+        """Generate a unique fingerprint for this prompt (for caching)."""
+        content = json.dumps(self.to_dict(), sort_keys=True)
+        return hashlib.sha256(content.encode()).hexdigest()[:16]
+    
+    def __str__(self) -> str:
+        return f"Prompt(name={self.name}, version={self.version}, source={self.source})"
+
+
+# ---------------------------------------------------------------------------
+# PromptCache - Multi-level caching
+# ---------------------------------------------------------------------------
+
+class PromptCache:
+    """
+    Multi-level cache for prompts.
+    
+    Levels:
+    1. Memory (L1) - TTL default 5 minutes
+    2. File (L2) - TTL default 1 hour
+    3. Backend (L3) - Source of truth
+    
+    Usage::
+        cache = PromptCache(memory_ttl=300, file_ttl=3600)
+        
+        # Get from cache (auto-fetches if missing/expired)
+        prompt = cache.get("agent-system", version=2)
+        
+        # Set manually
+        cache.set(prompt)
+        
+        # Clear cache
+        cache.clear()
+        cache.clear_memory()
+        cache.clear_file()
+        
+        # Check if exists
+        if cache.has("agent-system"):
+            prompt = cache.get("agent-system")
+    """
+    
+    def __init__(
+        self,
+        memory_ttl: int = 300,  # 5 minutes
+        file_ttl: int = 3600,  # 1 hour
+        cache_dir: Optional[str] = None,
+    ):
+        """
+        Initialize PromptCache.
+        
+        Args:
+            memory_ttl: TTL for in-memory cache (seconds)
+            file_ttl: TTL for file cache (seconds)
+            cache_dir: Directory for file cache (default: ~/.gateforge/prompts)
+        """
+        self._memory_cache: Dict[str, Dict[str, Any]] = {}
+        self._memory_ttl = memory_ttl
+        self._file_ttl = file_ttl
+        
+        # File cache directory
+        if cache_dir is None:
+            cache_dir = os.path.join(Path.home(), ".gateforge", "prompts")
+        self._cache_dir = Path(cache_dir)
+        self._cache_dir.mkdir(parents=True, exist_ok=True)
+    
+    def _memory_key(self, name: str, version: Optional[int]) -> str:
+        """Generate memory cache key."""
+        v = version if version is not None else "latest"
+        return f"{name}:{v}"
+    
+    def _file_path(self, name: str, version: Optional[int]) -> Path:
+        """Generate file cache path."""
+        v = version if version is not None else "latest"
+        safe_name = name.replace("/", "_").replace("\\", "_")
+        return self._cache_dir / f"{safe_name}_v{v}.json"
+    
+    def has(self, name: str, version: Optional[int] = None) -> bool:
+        """
+        Check if prompt exists in cache (not expired).
+        
+        Args:
+            name: Prompt name
+            version: Prompt version (None for latest = version 1)
+        
+        Returns:
+            True if exists and not expired
+        """
+        # If version is None, default to version 1 (latest for new prompts)
+        if version is None:
+            version = 1
+        
+        key = self._memory_key(name, version)
+        
+        # Check memory
+        if key in self._memory_cache:
+            entry = self._memory_cache[key]
+            if time.time() - entry["timestamp"] < self._memory_ttl:
+                return True
+            else:
+                del self._memory_cache[key]
+        
+        # Check file
+        file_path = self._file_path(name, version)
+        if file_path.exists():
+            try:
+                with open(file_path, "r") as f:
+                    entry = json.load(f)
+                if time.time() - entry["timestamp"] < self._file_ttl:
+                    return True
+                else:
+                    file_path.unlink()
+            except (json.JSONDecodeError, KeyError):
+                file_path.unlink()
+        
+        return False
+    
+    def get(self, name: str, version: Optional[int] = None) -> Optional[Prompt]:
+        """
+        Get prompt from cache (returns None if missing/expired).
+        
+        Args:
+            name: Prompt name
+            version: Prompt version (None for latest = version 1)
+        
+        Returns:
+            Prompt if found and not expired, None otherwise
+        """
+        # If version is None, default to version 1 (latest for new prompts)
+        if version is None:
+            version = 1
+        
+        key = self._memory_key(name, version)
+        
+        # Check memory (L1)
+        if key in self._memory_cache:
+            entry = self._memory_cache[key]
+            if time.time() - entry["timestamp"] < self._memory_ttl:
+                prompt = Prompt.from_dict(entry["data"])
+                prompt.source = "memory_cache"
+                return prompt
+            else:
+                del self._memory_cache[key]
+        
+        # Check file (L2)
+        file_path = self._file_path(name, version)
+        if file_path.exists():
+            try:
+                with open(file_path, "r") as f:
+                    entry = json.load(f)
+                if time.time() - entry["timestamp"] < self._file_ttl:
+                    prompt = Prompt.from_dict(entry["data"])
+                    prompt.source = "file_cache"
+                    # Promote to memory
+                    self._memory_cache[key] = {
+                        "data": entry["data"],
+                        "timestamp": time.time(),
+                    }
+                    return prompt
+                else:
+                    file_path.unlink()
+            except (json.JSONDecodeError, KeyError):
+                file_path.unlink()
+        
+        return None
+    
+    def set(self, prompt: Prompt, version: Optional[int] = None) -> None:
+        """
+        Set prompt in cache (both memory and file).
+        
+        Args:
+            prompt: Prompt to cache
+            version: Override version (uses prompt.version if None)
+        """
+        v = version if version is not None else prompt.version
+        key = self._memory_key(prompt.name, v)
+        timestamp = time.time()
+        
+        # Set memory (L1)
+        self._memory_cache[key] = {
+            "data": prompt.to_dict(),
+            "timestamp": timestamp,
+        }
+        
+        # Set file (L2)
+        file_path = self._file_path(prompt.name, v)
+        with open(file_path, "w") as f:
+            json.dump({
+                "data": prompt.to_dict(),
+                "timestamp": timestamp,
+            }, f, indent=2)
+    
+    def delete(self, name: str, version: Optional[int] = None) -> bool:
+        """
+        Delete prompt from cache.
+        
+        Args:
+            name: Prompt name
+            version: Prompt version (None for all versions)
+        
+        Returns:
+            True if deleted, False if not found
+        """
+        deleted = False
+        
+        # Delete from memory
+        if version is not None:
+            key = self._memory_key(name, version)
+            if key in self._memory_cache:
+                del self._memory_cache[key]
+                deleted = True
+        else:
+            # Delete all versions
+            keys_to_delete = [k for k in self._memory_cache if k.startswith(f"{name}:")]
+            for key in keys_to_delete:
+                del self._memory_cache[key]
+                deleted = True
+        
+        # Delete from file
+        pattern = name.replace("/", "_").replace("\\", "_")
+        for file_path in self._cache_dir.glob(f"{pattern}_v*.json"):
+            file_path.unlink()
+            deleted = True
+        
+        return deleted
+    
+    def clear(self) -> None:
+        """Clear all caches (memory + file)."""
+        self._memory_cache.clear()
+        for file_path in self._cache_dir.glob("*.json"):
+            file_path.unlink()
+    
+    def clear_memory(self) -> None:
+        """Clear memory cache only."""
+        self._memory_cache.clear()
+    
+    def clear_file(self) -> None:
+        """Clear file cache only."""
+        for file_path in self._cache_dir.glob("*.json"):
+            file_path.unlink()
+    
+    def stats(self) -> Dict[str, Any]:
+        """Get cache statistics."""
+        memory_count = len(self._memory_cache)
+        file_count = len(list(self._cache_dir.glob("*.json")))
+        
+        return {
+            "memory_count": memory_count,
+            "file_count": file_count,
+            "memory_ttl": self._memory_ttl,
+            "file_ttl": self._file_ttl,
+            "cache_dir": str(self._cache_dir),
+        }
+
+
+# ---------------------------------------------------------------------------
+# PromptBuilder - Composition
+# ---------------------------------------------------------------------------
+
+class PromptBuilder:
+    """
+    Builder for composing prompts from multiple sources.
+    
+    Usage::
+        builder = PromptBuilder()
+        builder.add_system("You are a helpful assistant")
+        builder.add_user("What's the weather?")
+        builder.add_variable("location", "Madrid")
+        builder.add(gateforge.get_prompt("domain-expert"))
+        prompt = builder.build()
+    """
+    
+    def __init__(self, name: str = "composed-prompt"):
+        """
+        Initialize PromptBuilder.
+        
+        Args:
+            name: Name for the composed prompt
+        """
+        self._name = name
+        self._parts: List[Dict[str, str]] = []
+        self._variables: Dict[str, Any] = {}
+        self._metadata: Dict[str, Any] = {}
+    
+    def add_system(self, text: str) -> PromptBuilder:
+        """Add system message."""
+        self._parts.append({"role": "system", "content": text})
+        return self
+    
+    def add_user(self, text: str) -> PromptBuilder:
+        """Add user message."""
+        self._parts.append({"role": "user", "content": text})
+        return self
+    
+    def add_assistant(self, text: str) -> PromptBuilder:
+        """Add assistant message (for few-shot examples)."""
+        self._parts.append({"role": "assistant", "content": text})
+        return self
+    
+    def add(self, content: str | Prompt) -> PromptBuilder:
+        """
+        Add content or another prompt.
+        
+        Args:
+            content: String or Prompt to add
+        
+        Returns:
+            Self for chaining
+        """
+        if isinstance(content, Prompt):
+            self._parts.append({"role": "system", "content": content.content})
+            self._variables.update(content.variables)
+            self._metadata.update(content.metadata)
+        else:
+            self._parts.append({"role": "system", "content": content})
+        return self
+    
+    def add_variable(self, name: str, value: Any) -> PromptBuilder:
+        """Add a variable for rendering."""
+        self._variables[name] = value
+        return self
+    
+    def add_variables(self, variables: Dict[str, Any]) -> PromptBuilder:
+        """Add multiple variables."""
+        self._variables.update(variables)
+        return self
+    
+    def set_metadata(self, key: str, value: Any) -> PromptBuilder:
+        """Set metadata field."""
+        self._metadata[key] = value
+        return self
+    
+    def build(self, version: int = 1) -> Prompt:
+        """
+        Build the final prompt.
+        
+        Args:
+            version: Version number for the composed prompt
+        
+        Returns:
+            Prompt object with all parts combined
+        """
+        # Combine all parts into content
+        content_parts = []
+        for part in self._parts:
+            role = part["role"].upper()
+            text = part["content"]
+            content_parts.append(f"[{role}]\n{text}\n")
+        
+        content = "\n".join(content_parts)
+        
+        return Prompt(
+            name=self._name,
+            content=content,
+            version=version,
+            variables=self._variables,
+            metadata=self._metadata,
+            source="builder",
+        )
+    
+    def build_and_render(self, version: int = 1, **overrides: Any) -> str:
+        """
+        Build and render the prompt in one step.
+        
+        Args:
+            version: Version number
+            **overrides: Variable overrides
+        
+        Returns:
+            Rendered prompt string
+        """
+        prompt = self.build(version)
+        return prompt.render(**overrides)
+
+
+# ---------------------------------------------------------------------------
+# Global cache instance
+# ---------------------------------------------------------------------------
+
+_default_cache: Optional[PromptCache] = None
+
+
+def get_prompt_cache() -> PromptCache:
+    """Get or create the default prompt cache."""
+    global _default_cache
+    if _default_cache is None:
+        _default_cache = PromptCache()
+    return _default_cache
+
+
+def get_prompt(
+    name: str,
+    version: Optional[int] = None,
+    cache: Optional[PromptCache] = None,
+    force_refresh: bool = False,
+) -> Optional[Prompt]:
+    """
+    Get a prompt by name and version.
+    
+    Currently returns None (backend not implemented).
+    Use PromptBuilder for local composition.
+    
+    Args:
+        name: Prompt name
+        version: Prompt version (None for latest)
+        cache: Optional cache instance (uses default if None)
+        force_refresh: Force refresh from backend (ignore cache)
+    
+    Returns:
+        Prompt if found, None otherwise
+    
+    Usage::
+        prompt = gateforge.get_prompt("agent-system", version=2)
+        if prompt:
+            print(prompt.content)
+    """
+    # TODO: Implement backend API call
+    # For now, check cache only
+    cache = cache or get_prompt_cache()
+    
+    if force_refresh:
+        # Delete from cache and re-fetch (TODO: backend call)
+        cache.delete(name, version)
+    
+    return cache.get(name, version)
+
+
+def set_prompt(
+    prompt: Prompt,
+    cache: Optional[PromptCache] = None,
+) -> None:
+    """
+    Set a prompt in the cache.
+    
+    Args:
+        prompt: Prompt to cache
+        cache: Optional cache instance (uses default if None)
+    
+    Usage::
+        prompt = Prompt(name="test", content="Hello", version=1)
+        gateforge.set_prompt(prompt)
+    """
+    cache = cache or get_prompt_cache()
+    cache.set(prompt)

{gateforge_sdk-0.2.5 → gateforge_sdk-0.2.6}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gateforge-sdk"
-version = "0.2.5"
-description = "Privacy-first LLMOps SDK — Auto-init, tool/agent decorators, session management, nested conversation support"
+version = "0.2.6"
+description = "Privacy-first LLMOps SDK — Auto-init, decorators, session management, prompt system with cache"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.10"