flashlite 0.1.0__py3-none-any.whl

flashlite/templating/filters.py

@@ -0,0 +1,143 @@
+"""Custom Jinja filters for prompt templating."""
+
+import json
+from typing import Any
+
+from jinja2 import Environment
+
+
+def json_encode(value: Any, indent: int | None = None) -> str:
+    """
+    Encode a value as JSON string.
+
+    Usage in template: {{ data | json }}
+    """
+    return json.dumps(value, indent=indent, ensure_ascii=False)
+
+
+def json_encode_pretty(value: Any) -> str:
+    """
+    Encode a value as pretty-printed JSON.
+
+    Usage in template: {{ data | json_pretty }}
+    """
+    return json.dumps(value, indent=2, ensure_ascii=False)
+
+
+def truncate_words(value: str, max_words: int, suffix: str = "...") -> str:
+    """
+    Truncate string to a maximum number of words.
+
+    Usage in template: {{ text | truncate_words(100) }}
+    """
+    words = value.split()
+    if len(words) <= max_words:
+        return value
+    return " ".join(words[:max_words]) + suffix
+
+
+def truncate_chars(value: str, max_chars: int, suffix: str = "...") -> str:
+    """
+    Truncate string to a maximum number of characters.
+
+    Usage in template: {{ text | truncate_chars(500) }}
+    """
+    if len(value) <= max_chars:
+        return value
+    return value[: max_chars - len(suffix)] + suffix
+
+
+def escape_xml(value: str) -> str:
+    """
+    Escape XML special characters.
+
+    Usage in template: {{ text | escape_xml }}
+    """
+    replacements = [
+        ("&", "&amp;"),
+        ("<", "&lt;"),
+        (">", "&gt;"),
+        ('"', "&quot;"),
+        ("'", "&apos;"),
+    ]
+    result = value
+    for old, new in replacements:
+        result = result.replace(old, new)
+    return result
+
+
+def strip_tags(value: str) -> str:
+    """
+    Remove XML/HTML tags from string.
+
+    Usage in template: {{ html_content | strip_tags }}
+    """
+    import re
+
+    return re.sub(r"<[^>]+>", "", value)
+
+
+def bullet_list(items: list[str], bullet: str = "- ") -> str:
+    """
+    Format a list as bullet points.
+
+    Usage in template: {{ items | bullet_list }}
+    """
+    return "\n".join(f"{bullet}{item}" for item in items)
+
+
+def numbered_list(items: list[str], start: int = 1) -> str:
+    """
+    Format a list as numbered items.
+
+    Usage in template: {{ items | numbered_list }}
+    """
+    return "\n".join(f"{i}. {item}" for i, item in enumerate(items, start=start))
+
+
+def wrap_xml(value: str, tag: str) -> str:
+    """
+    Wrap content in XML tags.
+
+    Usage in template: {{ content | wrap_xml('context') }}
+    Produces: <context>content</context>
+    """
+    return f"<{tag}>{value}</{tag}>"
+
+
+def indent_text(value: str, spaces: int = 2, first_line: bool = True) -> str:
+    """
+    Indent text by a number of spaces.
+
+    Usage in template: {{ text | indent_text(4) }}
+    """
+    prefix = " " * spaces
+    lines = value.split("\n")
+    if first_line:
+        return "\n".join(prefix + line for line in lines)
+    else:
+        return lines[0] + "\n" + "\n".join(prefix + line for line in lines[1:])
+
+
+def default_if_empty(value: Any, default: Any) -> Any:
+    """
+    Return default if value is empty/falsy.
+
+    Usage in template: {{ maybe_empty | default_if_empty('N/A') }}
+    """
+    return value if value else default
+
+
+def register_default_filters(env: Environment) -> None:
+    """Register all default filters with a Jinja environment."""
+    env.filters["json"] = json_encode
+    env.filters["json_pretty"] = json_encode_pretty
+    env.filters["truncate_words"] = truncate_words
+    env.filters["truncate_chars"] = truncate_chars
+    env.filters["escape_xml"] = escape_xml
+    env.filters["strip_tags"] = strip_tags
+    env.filters["bullet_list"] = bullet_list
+    env.filters["numbered_list"] = numbered_list
+    env.filters["wrap_xml"] = wrap_xml
+    env.filters["indent_text"] = indent_text
+    env.filters["default_if_empty"] = default_if_empty

flashlite/templating/registry.py

@@ -0,0 +1,165 @@
+"""Template registry for managing prompt templates."""
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Template
+
+from ..types import TemplateError
+
+
+class TemplateRegistry:
+    """
+    Registry for managing prompt templates.
+
+    Supports:
+    - Loading templates from files
+    - Registering templates by name
+    - Namespaced template names (e.g., 'prompts.system.default')
+    - Template versioning via content hashing
+    """
+
+    def __init__(self) -> None:
+        self._templates: dict[str, Template] = {}
+        self._sources: dict[str, str] = {}  # name -> original source
+        self._hashes: dict[str, str] = {}  # name -> content hash
+
+    def register(self, name: str, template: Template | str) -> None:
+        """
+        Register a template by name.
+
+        Args:
+            name: Template name (can use dots for namespacing)
+            template: Jinja Template object or template string
+        """
+        if isinstance(template, str):
+            source = template
+            template = Template(template)
+        else:
+            source = template.source if hasattr(template, "source") else ""
+
+        self._templates[name] = template
+        self._sources[name] = source
+        self._hashes[name] = self._compute_hash(source)
+
+    def get(self, name: str) -> Template:
+        """
+        Get a template by name.
+
+        Args:
+            name: Template name
+
+        Returns:
+            The Jinja Template
+
+        Raises:
+            TemplateError: If template not found
+        """
+        if name not in self._templates:
+            raise TemplateError(f"Template not found: {name}")
+        return self._templates[name]
+
+    def render(self, name: str, variables: dict[str, Any] | None = None) -> str:
+        """
+        Render a template by name.
+
+        Args:
+            name: Template name
+            variables: Variables to pass to template
+
+        Returns:
+            Rendered template string
+        """
+        template = self.get(name)
+        return template.render(**(variables or {}))
+
+    def has(self, name: str) -> bool:
+        """Check if a template exists."""
+        return name in self._templates
+
+    def list_templates(self, prefix: str | None = None) -> list[str]:
+        """
+        List registered template names.
+
+        Args:
+            prefix: Optional prefix to filter by (e.g., 'prompts.')
+
+        Returns:
+            List of template names
+        """
+        names = list(self._templates.keys())
+        if prefix:
+            names = [n for n in names if n.startswith(prefix)]
+        return sorted(names)
+
+    def get_hash(self, name: str) -> str:
+        """
+        Get the content hash of a template.
+
+        Useful for reproducibility tracking.
+        """
+        if name not in self._hashes:
+            raise TemplateError(f"Template not found: {name}")
+        return self._hashes[name]
+
+    def get_source(self, name: str) -> str:
+        """Get the original source of a template."""
+        if name not in self._sources:
+            raise TemplateError(f"Template not found: {name}")
+        return self._sources[name]
+
+    def _compute_hash(self, source: str) -> str:
+        """Compute SHA256 hash of template source."""
+        return hashlib.sha256(source.encode()).hexdigest()[:16]
+
+    def load_from_directory(
+        self,
+        directory: Path | str,
+        prefix: str = "",
+        extensions: tuple[str, ...] = (".jinja", ".j2", ".txt", ".md"),
+    ) -> int:
+        """
+        Load all templates from a directory.
+
+        Template names are derived from file paths:
+        - 'prompts/system/default.jinja' -> 'system.default'
+        - With prefix='prompts': 'prompts.system.default'
+
+        Args:
+            directory: Directory to load from
+            prefix: Prefix to add to template names
+            extensions: File extensions to load
+
+        Returns:
+            Number of templates loaded
+        """
+        directory = Path(directory)
+        if not directory.exists():
+            raise TemplateError(f"Template directory not found: {directory}")
+
+        count = 0
+        for file_path in directory.rglob("*"):
+            if file_path.is_file() and file_path.suffix in extensions:
+                # Convert path to template name
+                relative = file_path.relative_to(directory)
+                # Remove extension and convert path separators to dots
+                name_parts = list(relative.parts)
+                name_parts[-1] = relative.stem  # Remove extension from last part
+                name = ".".join(name_parts)
+
+                if prefix:
+                    name = f"{prefix}.{name}"
+
+                # Load and register
+                source = file_path.read_text()
+                self.register(name, source)
+                count += 1
+
+        return count
+
+    def clear(self) -> None:
+        """Remove all registered templates."""
+        self._templates.clear()
+        self._sources.clear()
+        self._hashes.clear()

flashlite/tools/__init__.py

@@ -0,0 +1,74 @@
+"""Tool/function calling helpers for Flashlite.
+
+This module provides utilities for:
+- Defining tools using decorators (@tool) or Pydantic models
+- Converting tools to OpenAI/Anthropic formats
+- Running tool execution loops for agentic patterns
+
+Example:
+    from flashlite import Flashlite
+    from flashlite.tools import tool, run_tool_loop
+
+    @tool()
+    def get_weather(location: str, unit: str = "celsius") -> str:
+        '''Get the current weather for a location.'''
+        # Implementation
+        return f"Weather in {location}: 72°F"
+
+    @tool()
+    def search_web(query: str, max_results: int = 5) -> list[str]:
+        '''Search the web for information.'''
+        return ["result1", "result2"]
+
+    client = Flashlite(default_model="gpt-4o")
+
+    # Run tool loop
+    result = await run_tool_loop(
+        client=client,
+        messages=[{"role": "user", "content": "What's the weather in NYC?"}],
+        tools=[get_weather, search_web],
+    )
+    print(result.content)
+"""
+
+from .definitions import (
+    ToolDefinition,
+    ToolRegistry,
+    format_tool_result,
+    get_tool_definition,
+    tool,
+    tool_from_pydantic,
+    tools_to_anthropic,
+    tools_to_openai,
+)
+from .execution import (
+    ToolCall,
+    ToolLoopResult,
+    ToolResult,
+    build_tool_registry,
+    execute_tool,
+    execute_tools_parallel,
+    extract_tool_calls,
+    run_tool_loop,
+)
+
+__all__ = [
+    # Definitions
+    "tool",
+    "tool_from_pydantic",
+    "ToolDefinition",
+    "ToolRegistry",
+    "get_tool_definition",
+    "tools_to_openai",
+    "tools_to_anthropic",
+    "format_tool_result",
+    # Execution
+    "ToolCall",
+    "ToolResult",
+    "ToolLoopResult",
+    "run_tool_loop",
+    "execute_tool",
+    "execute_tools_parallel",
+    "extract_tool_calls",
+    "build_tool_registry",
+]