gobby 0.2.5__py3-none-any.whl

gobby/prompts/loader.py

@@ -0,0 +1,346 @@
+"""
+Prompt template loader with multi-level override support.
+
+Implements prompt loading with precedence:
+1. Inline config (deprecated, for backwards compatibility)
+2. Config path (explicit path in config)
+3. Project file (.gobby/prompts/)
+4. Global file (~/.gobby/prompts/)
+5. Bundled default (src/gobby/prompts/defaults/)
+6. Python constant (strangler fig fallback)
+"""
+
+import logging
+import re
+from collections.abc import Callable
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .models import PromptTemplate
+
+logger = logging.getLogger(__name__)
+
+# Default location for bundled prompts
+DEFAULTS_DIR = Path(__file__).parent / "defaults"
+
+
+class PromptLoader:
+    """Loads prompt templates from multiple sources with override precedence.
+
+    Usage:
+        loader = PromptLoader(project_dir=Path("."))
+        template = loader.load("expansion/system")
+        rendered = loader.render("expansion/system", {"tdd_mode": True})
+    """
+
+    def __init__(
+        self,
+        project_dir: Path | None = None,
+        global_dir: Path | None = None,
+        defaults_dir: Path | None = None,
+    ):
+        """Initialize the prompt loader.
+
+        Args:
+            project_dir: Project root directory (for .gobby/prompts)
+            global_dir: Global config directory (defaults to ~/.gobby)
+            defaults_dir: Directory for bundled defaults (auto-detected)
+        """
+        self.project_dir = project_dir
+        self.global_dir = global_dir or Path.home() / ".gobby"
+        self.defaults_dir = defaults_dir or DEFAULTS_DIR
+
+        # Build search paths in priority order
+        self._search_paths: list[Path] = []
+        if project_dir:
+            self._search_paths.append(project_dir / ".gobby" / "prompts")
+        self._search_paths.append(self.global_dir / "prompts")
+        self._search_paths.append(self.defaults_dir)
+
+        # Template cache
+        self._cache: dict[str, PromptTemplate] = {}
+
+        # Fallback registry for strangler fig pattern
+        self._fallbacks: dict[str, Callable[[], str]] = {}
+
+    def register_fallback(self, path: str, getter: Callable[[], str]) -> None:
+        """Register a Python constant fallback for a template path.
+
+        Used for strangler fig pattern - if template file doesn't exist,
+        fall back to the original Python constant.
+
+        Args:
+            path: Template path (e.g., "expansion/system")
+            getter: Callable that returns the fallback string
+        """
+        self._fallbacks[path] = getter
+
+    def clear_cache(self) -> None:
+        """Clear the template cache."""
+        self._cache.clear()
+
+    def _find_template_file(self, path: str) -> Path | None:
+        """Find a template file in search paths.
+
+        Args:
+            path: Template path (e.g., "expansion/system")
+
+        Returns:
+            Path to template file if found, None otherwise
+        """
+        # Add .md extension if not present
+        if not path.endswith(".md"):
+            path = f"{path}.md"
+
+        for search_dir in self._search_paths:
+            template_path = search_dir / path
+            if template_path.exists():
+                return template_path
+
+        return None
+
+    def _parse_frontmatter(self, content: str) -> tuple[dict[str, Any], str]:
+        """Parse YAML frontmatter from template content.
+
+        Args:
+            content: Raw file content
+
+        Returns:
+            Tuple of (frontmatter dict, body content)
+        """
+        # Match YAML frontmatter between --- markers
+        frontmatter_pattern = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+        match = frontmatter_pattern.match(content)
+
+        if match:
+            try:
+                frontmatter = yaml.safe_load(match.group(1)) or {}
+                body = content[match.end() :]
+                return frontmatter, body
+            except yaml.YAMLError as e:
+                logger.warning(f"Failed to parse frontmatter: {e}")
+                return {}, content
+
+        return {}, content
+
+    def load(self, path: str) -> PromptTemplate:
+        """Load a prompt template by path.
+
+        Args:
+            path: Template path (e.g., "expansion/system")
+
+        Returns:
+            PromptTemplate instance
+
+        Raises:
+            FileNotFoundError: If template not found and no fallback registered
+        """
+        # Check cache first
+        if path in self._cache:
+            return self._cache[path]
+
+        # Try to find template file
+        template_file = self._find_template_file(path)
+
+        if template_file:
+            content = template_file.read_text(encoding="utf-8")
+            frontmatter, body = self._parse_frontmatter(content)
+
+            template = PromptTemplate.from_frontmatter(
+                name=path,
+                frontmatter=frontmatter,
+                content=body.strip(),
+                source_path=template_file,
+            )
+            self._cache[path] = template
+            logger.debug(f"Loaded prompt template '{path}' from {template_file}")
+            return template
+
+        # Fall back to registered Python constant
+        if path in self._fallbacks:
+            fallback_content = self._fallbacks[path]()
+            template = PromptTemplate(
+                name=path,
+                description=f"Fallback for {path}",
+                content=fallback_content,
+                source_path=None,
+            )
+            self._cache[path] = template
+            logger.debug(f"Using fallback for prompt template '{path}'")
+            return template
+
+        raise FileNotFoundError(f"Prompt template not found: {path}")
+
+    def render(
+        self,
+        path: str,
+        context: dict[str, Any] | None = None,
+        strict: bool = False,
+    ) -> str:
+        """Load and render a template with context.
+
+        Args:
+            path: Template path
+            context: Variables to inject into template
+            strict: If True, raise on missing required variables
+
+        Returns:
+            Rendered template string
+
+        Raises:
+            FileNotFoundError: If template not found
+            ValueError: If strict=True and required variables missing
+        """
+        template = self.load(path)
+        ctx = template.get_default_context()
+
+        if context:
+            ctx.update(context)
+
+        # Validate required variables
+        if strict:
+            errors = template.validate_context(ctx)
+            if errors:
+                raise ValueError(f"Template validation failed: {'; '.join(errors)}")
+
+        # Render with Jinja2
+        return self._render_jinja(template.content, ctx)
+
+    def _render_jinja(self, template_str: str, context: dict[str, Any]) -> str:
+        """Render a template string with Jinja2.
+
+        Uses a safe subset of Jinja2 features.
+
+        Args:
+            template_str: Template content with Jinja2 syntax
+            context: Context dict for rendering
+
+        Returns:
+            Rendered string
+        """
+        try:
+            from jinja2 import Environment, StrictUndefined, UndefinedError
+
+            # Create a restricted Jinja2 environment
+            env = Environment(  # nosec B701 - generating raw text prompts, not HTML
+                autoescape=False,
+                undefined=StrictUndefined,
+                # Disable dangerous features
+                extensions=[],
+            )
+
+            # Add safe filters
+            env.filters["default"] = lambda v, d="": d if v is None else v
+
+            template = env.from_string(template_str)
+            return template.render(**context)
+
+        except UndefinedError as e:
+            logger.warning(f"Template rendering error (undefined variable): {e}")
+            # Fall back to simple string formatting for undefined vars
+            return self._render_simple(template_str, context)
+        except ImportError:
+            # Jinja2 not available, use simple formatting
+            logger.debug("Jinja2 not available, using simple format")
+            return self._render_simple(template_str, context)
+        except Exception as e:
+            logger.warning(f"Template rendering error: {e}")
+            return self._render_simple(template_str, context)
+
+    def _render_simple(self, template_str: str, context: dict[str, Any]) -> str:
+        """Simple string formatting fallback.
+
+        Handles {variable} placeholders using str.format().
+
+        Args:
+            template_str: Template with {var} placeholders
+            context: Context dict
+
+        Returns:
+            Rendered string
+        """
+        try:
+            return template_str.format(**context)
+        except KeyError:
+            # Return as-is if formatting fails
+            return template_str
+
+    def exists(self, path: str) -> bool:
+        """Check if a template exists.
+
+        Args:
+            path: Template path
+
+        Returns:
+            True if template exists (file or fallback)
+        """
+        return self._find_template_file(path) is not None or path in self._fallbacks
+
+    def list_templates(self, category: str | None = None) -> list[str]:
+        """List available template paths.
+
+        Args:
+            category: Optional category to filter (e.g., "expansion")
+
+        Returns:
+            List of template paths
+        """
+        templates: set[str] = set()
+
+        for search_dir in self._search_paths:
+            if not search_dir.exists():
+                continue
+
+            for md_file in search_dir.rglob("*.md"):
+                rel_path = md_file.relative_to(search_dir)
+                # Remove .md extension for path
+                template_path = str(rel_path.with_suffix(""))
+
+                if category is None or template_path.startswith(f"{category}/"):
+                    templates.add(template_path)
+
+        # Add registered fallbacks
+        for fallback_path in self._fallbacks:
+            if category is None or fallback_path.startswith(f"{category}/"):
+                templates.add(fallback_path)
+
+        return sorted(templates)
+
+
+# Module-level cached loader instance
+@lru_cache(maxsize=1)
+def get_default_loader() -> PromptLoader:
+    """Get or create the default prompt loader.
+
+    Returns:
+        Cached PromptLoader instance
+    """
+    return PromptLoader()
+
+
+def load_prompt(path: str) -> PromptTemplate:
+    """Convenience function to load a prompt using default loader.
+
+    Args:
+        path: Template path
+
+    Returns:
+        PromptTemplate
+    """
+    return get_default_loader().load(path)
+
+
+def render_prompt(path: str, context: dict[str, Any] | None = None) -> str:
+    """Convenience function to render a prompt using default loader.
+
+    Args:
+        path: Template path
+        context: Variables for rendering
+
+    Returns:
+        Rendered string
+    """
+    return get_default_loader().render(path, context)

gobby/prompts/models.py

@@ -0,0 +1,113 @@
+"""
+Prompt template data models.
+
+Contains dataclasses for representing prompt templates with metadata.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+
+@dataclass
+class VariableSpec:
+    """Specification for a template variable.
+
+    Attributes:
+        type: Variable type (str, int, bool, list, dict)
+        default: Default value if not provided
+        description: Human-readable description
+        required: Whether the variable must be provided
+    """
+
+    type: Literal["str", "int", "bool", "list", "dict"] = "str"
+    default: Any = None
+    description: str = ""
+    required: bool = False
+
+
+@dataclass
+class PromptTemplate:
+    """A loaded prompt template with metadata.
+
+    Attributes:
+        name: Template identifier (e.g., "expansion/system")
+        description: Human-readable description
+        variables: Variable specifications from frontmatter
+        content: Raw template content (with Jinja2 syntax)
+        source_path: Path the template was loaded from (None for fallbacks)
+        version: Template version for compatibility checking
+    """
+
+    name: str
+    description: str = ""
+    variables: dict[str, VariableSpec] = field(default_factory=dict)
+    content: str = ""
+    source_path: Path | None = None
+    version: str = "1.0"
+
+    @classmethod
+    def from_frontmatter(
+        cls,
+        name: str,
+        frontmatter: dict[str, Any],
+        content: str,
+        source_path: Path | None = None,
+    ) -> "PromptTemplate":
+        """Create a PromptTemplate from parsed frontmatter.
+
+        Args:
+            name: Template name/path
+            frontmatter: Parsed YAML frontmatter
+            content: Template content after frontmatter
+            source_path: Source file path
+
+        Returns:
+            PromptTemplate instance
+        """
+        # Parse variables from frontmatter
+        variables: dict[str, VariableSpec] = {}
+        if "variables" in frontmatter:
+            for var_name, var_spec in frontmatter["variables"].items():
+                if isinstance(var_spec, dict):
+                    variables[var_name] = VariableSpec(
+                        type=var_spec.get("type", "str"),
+                        default=var_spec.get("default"),
+                        description=var_spec.get("description", ""),
+                        required=var_spec.get("required", False),
+                    )
+                else:
+                    # Simple form: just a default value
+                    variables[var_name] = VariableSpec(default=var_spec)
+
+        return cls(
+            name=name,
+            description=frontmatter.get("description", ""),
+            variables=variables,
+            content=content,
+            source_path=source_path,
+            version=frontmatter.get("version", "1.0"),
+        )
+
+    def get_default_context(self) -> dict[str, Any]:
+        """Get default values for all variables.
+
+        Returns:
+            Dict of variable names to their default values
+        """
+        return {name: spec.default for name, spec in self.variables.items()}
+
+    def validate_context(self, context: dict[str, Any]) -> list[str]:
+        """Validate that required variables are provided.
+
+        Args:
+            context: Context dict being passed to render
+
+        Returns:
+            List of error messages (empty if valid)
+        """
+        errors: list[str] = []
+        for name, spec in self.variables.items():
+            if spec.required and name not in context:
+                errors.append(f"Required variable '{name}' not provided")
+        return errors