yamlgraph 0.3.9__py3-none-any.whl

yamlgraph/constants.py

@@ -0,0 +1,70 @@
+"""Type-safe constants for YAML graph configuration.
+
+Provides enums for node types, error handlers, and other magic strings
+used throughout the codebase to enable static type checking and IDE support.
+"""
+
+from enum import StrEnum
+
+
+class NodeType(StrEnum):
+    """Valid node types in YAML graph configuration."""
+
+    LLM = "llm"
+    ROUTER = "router"
+    TOOL = "tool"
+    AGENT = "agent"
+    PYTHON = "python"
+    MAP = "map"
+    TOOL_CALL = "tool_call"
+    INTERRUPT = "interrupt"
+    SUBGRAPH = "subgraph"
+    PASSTHROUGH = "passthrough"
+
+    @classmethod
+    def requires_prompt(cls, node_type: str) -> bool:
+        """Check if node type requires a prompt field.
+
+        Args:
+            node_type: The node type string
+
+        Returns:
+            True if the node type requires a prompt
+        """
+        return node_type in (cls.LLM, cls.ROUTER)
+
+
+class ErrorHandler(StrEnum):
+    """Valid on_error handling strategies."""
+
+    SKIP = "skip"  # Skip node and continue pipeline
+    RETRY = "retry"  # Retry with max_retries attempts
+    FAIL = "fail"  # Raise exception immediately
+    FALLBACK = "fallback"  # Try fallback provider
+
+    @classmethod
+    def all_values(cls) -> set[str]:
+        """Return all valid error handler values.
+
+        Returns:
+            Set of valid error handler strings
+        """
+        return {handler.value for handler in cls}
+
+
+class EdgeType(StrEnum):
+    """Valid edge types in graph configuration."""
+
+    SIMPLE = "simple"  # Direct edge from -> to
+    CONDITIONAL = "conditional"  # Edge with conditions
+
+
+class SpecialNodes(StrEnum):
+    """Special node names with semantic meaning."""
+
+    START = "__start__"
+    END = "__end__"
+
+
+# Re-export for convenience
+__all__ = ["NodeType", "ErrorHandler", "EdgeType", "SpecialNodes"]

yamlgraph/error_handlers.py

@@ -0,0 +1,227 @@
+"""Error handling strategies for node execution.
+
+Provides strategy functions for different error handling modes:
+- skip: Continue without output
+- fail: Raise exception immediately
+- retry: Retry up to N times
+- fallback: Try fallback provider
+"""
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from yamlgraph.models import ErrorType, PipelineError
+
+logger = logging.getLogger(__name__)
+
+
+class NodeResult:
+    """Result of node execution with consistent structure.
+
+    Attributes:
+        success: Whether execution succeeded
+        output: The result value (if success)
+        error: PipelineError (if failure)
+        state_updates: Additional state updates
+    """
+
+    def __init__(
+        self,
+        success: bool,
+        output: Any = None,
+        error: PipelineError | None = None,
+        state_updates: dict | None = None,
+    ):
+        self.success = success
+        self.output = output
+        self.error = error
+        self.state_updates = state_updates or {}
+
+    def to_state_update(
+        self,
+        state_key: str,
+        node_name: str,
+        loop_counts: dict,
+    ) -> dict:
+        """Convert to LangGraph state update dict.
+
+        Args:
+            state_key: Key to store output under
+            node_name: Name of the node
+            loop_counts: Current loop counts
+
+        Returns:
+            State update dict with consistent structure
+        """
+        update = {
+            "current_step": node_name,
+            "_loop_counts": loop_counts,
+        }
+
+        if self.success:
+            update[state_key] = self.output
+        elif self.error:
+            # Always use 'errors' list for consistency
+            update["errors"] = [self.error]
+
+        update.update(self.state_updates)
+        return update
+
+
+def handle_skip(
+    node_name: str,
+    error: Exception,
+    loop_counts: dict,
+) -> NodeResult:
+    """Handle error with skip strategy.
+
+    Args:
+        node_name: Name of the node
+        error: The exception that occurred
+        loop_counts: Current loop counts
+
+    Returns:
+        NodeResult with empty output
+    """
+    logger.warning(f"Node {node_name} failed, skipping: {error}")
+    return NodeResult(success=True, output=None)
+
+
+def handle_fail(
+    node_name: str,
+    error: Exception,
+) -> None:
+    """Handle error with fail strategy.
+
+    Args:
+        node_name: Name of the node
+        error: The exception that occurred
+
+    Raises:
+        Exception: Always raises the original error
+    """
+    logger.error(f"Node {node_name} failed (on_error=fail): {error}")
+    raise error
+
+
+def handle_retry(
+    node_name: str,
+    execute_fn: Callable[[], tuple[Any, Exception | None]],
+    max_retries: int,
+) -> NodeResult:
+    """Handle error with retry strategy.
+
+    Args:
+        node_name: Name of the node
+        execute_fn: Function to execute (returns result, error)
+        max_retries: Maximum retry attempts
+
+    Returns:
+        NodeResult with output or error
+    """
+    last_exception: Exception | None = None
+
+    for attempt in range(1, max_retries + 1):
+        logger.info(f"Node {node_name} retry {attempt}/{max_retries}")
+        result, error = execute_fn()
+        if error is None:
+            return NodeResult(success=True, output=result)
+        last_exception = error
+
+    logger.error(f"Node {node_name} failed after {max_retries} attempts")
+    pipeline_error = PipelineError.from_exception(
+        last_exception or Exception("Unknown error"), node=node_name
+    )
+    return NodeResult(success=False, error=pipeline_error)
+
+
+def handle_fallback(
+    node_name: str,
+    execute_fn: Callable[[str | None], tuple[Any, Exception | None]],
+    fallback_provider: str,
+) -> NodeResult:
+    """Handle error with fallback strategy.
+
+    Args:
+        node_name: Name of the node
+        execute_fn: Function to execute with provider param
+        fallback_provider: Fallback provider to try
+
+    Returns:
+        NodeResult with output or error
+    """
+    logger.info(f"Node {node_name} trying fallback: {fallback_provider}")
+    result, fallback_error = execute_fn(fallback_provider)
+
+    if fallback_error is None:
+        return NodeResult(success=True, output=result)
+
+    logger.error(f"Node {node_name} failed with primary and fallback")
+    pipeline_error = PipelineError.from_exception(fallback_error, node=node_name)
+    return NodeResult(success=False, error=pipeline_error)
+
+
+def handle_default(
+    node_name: str,
+    error: Exception,
+) -> NodeResult:
+    """Handle error with default strategy (log and return error).
+
+    Args:
+        node_name: Name of the node
+        error: The exception that occurred
+
+    Returns:
+        NodeResult with error
+    """
+    logger.error(f"Node {node_name} failed: {error}")
+    pipeline_error = PipelineError.from_exception(error, node=node_name)
+    return NodeResult(success=False, error=pipeline_error)
+
+
+def check_requirements(
+    requires: list[str],
+    state: dict,
+    node_name: str,
+) -> PipelineError | None:
+    """Check if all required state keys are present.
+
+    Args:
+        requires: List of required state keys
+        state: Current state
+        node_name: Name of the node
+
+    Returns:
+        PipelineError if requirements not met, None otherwise
+    """
+    for req in requires:
+        if state.get(req) is None:
+            return PipelineError(
+                type=ErrorType.STATE_ERROR,
+                message=f"Missing required state: {req}",
+                node=node_name,
+                retryable=False,
+            )
+    return None
+
+
+def check_loop_limit(
+    node_name: str,
+    loop_limit: int | None,
+    current_count: int,
+) -> bool:
+    """Check if loop limit has been reached.
+
+    Args:
+        node_name: Name of the node
+        loop_limit: Maximum loop iterations (None = no limit)
+        current_count: Current iteration count
+
+    Returns:
+        True if limit reached, False otherwise
+    """
+    if loop_limit is not None and current_count >= loop_limit:
+        logger.warning(f"Node {node_name} hit loop limit ({loop_limit})")
+        return True
+    return False

yamlgraph/executor.py

@@ -0,0 +1,290 @@
+"""YAML Prompt Executor - Unified interface for LLM calls.
+
+This module provides a simple, reusable executor for YAML-defined prompts
+with support for structured outputs via Pydantic models.
+"""
+
+import logging
+import threading
+import time
+from pathlib import Path
+from typing import TypeVar
+
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import HumanMessage, SystemMessage
+from pydantic import BaseModel
+
+from yamlgraph.config import (
+    DEFAULT_TEMPERATURE,
+    MAX_RETRIES,
+    RETRY_BASE_DELAY,
+    RETRY_MAX_DELAY,
+)
+from yamlgraph.utils.llm_factory import create_llm
+from yamlgraph.utils.prompts import load_prompt
+from yamlgraph.utils.template import validate_variables
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=BaseModel)
+
+
+# Exceptions that are retryable
+RETRYABLE_EXCEPTIONS = (
+    "RateLimitError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "InternalServerError",
+    "ServiceUnavailableError",
+)
+
+
+def is_retryable(exception: Exception) -> bool:
+    """Check if an exception is retryable.
+
+    Args:
+        exception: The exception to check
+
+    Returns:
+        True if the exception should be retried
+    """
+    exc_name = type(exception).__name__
+    return exc_name in RETRYABLE_EXCEPTIONS or "rate" in exc_name.lower()
+
+
+def format_prompt(
+    template: str,
+    variables: dict,
+    state: dict | None = None,
+) -> str:
+    """Format a prompt template with variables.
+
+    Supports both simple {variable} placeholders and Jinja2 templates.
+    If the template contains Jinja2 syntax ({%, {{), uses Jinja2 rendering.
+
+    Args:
+        template: Template string with {variable} or Jinja2 placeholders
+        variables: Dictionary of variable values
+        state: Optional state dict for Jinja2 templates (accessible as {{ state.field }})
+
+    Returns:
+        Formatted string
+
+    Examples:
+        Simple format:
+            format_prompt("Hello {name}", {"name": "World"})
+
+        Jinja2 with variables:
+            format_prompt("{% for item in items %}{{ item }}{% endfor %}", {"items": [1, 2]})
+
+        Jinja2 with state:
+            format_prompt("Topic: {{ state.topic }}", {}, state={"topic": "AI"})
+    """
+    # Check for Jinja2 syntax
+    if "{%" in template or "{{" in template:
+        from jinja2 import Template
+
+        jinja_template = Template(template)
+        # Pass both variables and state to Jinja2
+        context = {"state": state or {}, **variables}
+        return jinja_template.render(**context)
+
+    # Fall back to simple format - stringify lists for compatibility
+    safe_vars = {
+        k: (", ".join(map(str, v)) if isinstance(v, list) else v)
+        for k, v in variables.items()
+    }
+    return template.format(**safe_vars)
+
+
+def execute_prompt(
+    prompt_name: str,
+    variables: dict | None = None,
+    output_model: type[T] | None = None,
+    temperature: float = DEFAULT_TEMPERATURE,
+    provider: str | None = None,
+    graph_path: "Path | None" = None,
+    prompts_dir: "Path | None" = None,
+    prompts_relative: bool = False,
+) -> T | str:
+    """Execute a YAML prompt with optional structured output.
+
+    Uses the singleton PromptExecutor for LLM caching.
+
+    Args:
+        prompt_name: Name of the prompt file (without .yaml)
+        variables: Variables to substitute in the template
+        output_model: Optional Pydantic model for structured output
+        temperature: LLM temperature setting
+        provider: LLM provider ("anthropic", "mistral", "openai").
+                 Can also be set in YAML metadata or PROVIDER env var.
+        graph_path: Path to graph file for relative prompt resolution
+        prompts_dir: Explicit prompts directory override
+        prompts_relative: If True, resolve prompts relative to graph_path
+
+    Returns:
+        Parsed Pydantic model if output_model provided, else raw string
+
+    Example:
+        >>> result = execute_prompt(
+        ...     "greet",
+        ...     variables={"name": "World", "style": "formal"},
+        ...     output_model=GenericReport,
+        ... )
+        >>> print(result.summary)
+    """
+    return get_executor().execute(
+        prompt_name=prompt_name,
+        variables=variables,
+        output_model=output_model,
+        temperature=temperature,
+        provider=provider,
+        graph_path=graph_path,
+        prompts_dir=prompts_dir,
+        prompts_relative=prompts_relative,
+    )
+
+
+# Default executor instance for LLM caching
+# Use get_executor() to access, or set_executor() for dependency injection
+_executor: "PromptExecutor | None" = None
+_executor_lock = threading.Lock()
+
+
+def get_executor() -> "PromptExecutor":
+    """Get the executor instance (thread-safe).
+
+    Returns the default singleton or a custom instance set via set_executor().
+
+    Returns:
+        PromptExecutor instance with LLM caching
+    """
+    global _executor
+    if _executor is None:
+        with _executor_lock:
+            # Double-check after acquiring lock
+            if _executor is None:
+                _executor = PromptExecutor()
+    return _executor
+
+
+class PromptExecutor:
+    """Reusable executor with LLM caching and retry logic."""
+
+    def __init__(self, max_retries: int = MAX_RETRIES):
+        self._max_retries = max_retries
+
+    def _get_llm(
+        self,
+        temperature: float = DEFAULT_TEMPERATURE,
+        provider: str | None = None,
+    ) -> BaseChatModel:
+        """Get or create cached LLM instance.
+
+        Uses llm_factory which handles caching internally.
+        """
+        return create_llm(temperature=temperature, provider=provider)
+
+    def _invoke_with_retry(
+        self, llm, messages, output_model: type[T] | None = None
+    ) -> T | str:
+        """Invoke LLM with exponential backoff retry.
+
+        Args:
+            llm: The LLM instance to use
+            messages: Messages to send
+            output_model: Optional Pydantic model for structured output
+
+        Returns:
+            LLM response (parsed model or string)
+
+        Raises:
+            Last exception if all retries fail
+        """
+        last_exception = None
+
+        for attempt in range(self._max_retries):
+            try:
+                if output_model:
+                    structured_llm = llm.with_structured_output(output_model)
+                    return structured_llm.invoke(messages)
+                else:
+                    response = llm.invoke(messages)
+                    return response.content
+
+            except Exception as e:
+                last_exception = e
+
+                if not is_retryable(e) or attempt == self._max_retries - 1:
+                    raise
+
+                # Exponential backoff with jitter
+                delay = min(RETRY_BASE_DELAY * (2**attempt), RETRY_MAX_DELAY)
+                logger.warning(
+                    f"LLM call failed (attempt {attempt + 1}/{self._max_retries}): {e}. "
+                    f"Retrying in {delay:.1f}s..."
+                )
+                time.sleep(delay)
+
+        raise last_exception
+
+    def execute(
+        self,
+        prompt_name: str,
+        variables: dict | None = None,
+        output_model: type[T] | None = None,
+        temperature: float = DEFAULT_TEMPERATURE,
+        provider: str | None = None,
+        graph_path: "Path | None" = None,
+        prompts_dir: "Path | None" = None,
+        prompts_relative: bool = False,
+    ) -> T | str:
+        """Execute a prompt using cached LLM with retry logic.
+
+        Same interface as execute_prompt() but with LLM caching and
+        automatic retry for transient failures.
+
+        Provider priority: parameter > YAML metadata > env var > default
+
+        Args:
+            prompt_name: Name of the prompt file (without .yaml)
+            variables: Variables to substitute in the template
+            output_model: Optional Pydantic model for structured output
+            temperature: LLM temperature setting
+            provider: LLM provider ("anthropic", "mistral", "openai")
+            graph_path: Path to graph file for relative prompt resolution
+            prompts_dir: Explicit prompts directory override
+            prompts_relative: If True, resolve prompts relative to graph_path
+
+        Raises:
+            ValueError: If required template variables are missing
+        """
+        variables = variables or {}
+
+        prompt_config = load_prompt(
+            prompt_name,
+            prompts_dir=prompts_dir,
+            graph_path=graph_path,
+            prompts_relative=prompts_relative,
+        )
+
+        # Validate all required variables are provided (fail fast)
+        full_template = prompt_config.get("system", "") + prompt_config.get("user", "")
+        validate_variables(full_template, variables, prompt_name)
+
+        # Extract provider from YAML metadata if not provided
+        if provider is None and "provider" in prompt_config:
+            provider = prompt_config["provider"]
+            logger.debug(f"Using provider from YAML metadata: {provider}")
+
+        system_text = format_prompt(prompt_config.get("system", ""), variables)
+        user_text = format_prompt(prompt_config["user"], variables)
+
+        messages = []
+        if system_text:
+            messages.append(SystemMessage(content=system_text))
+        messages.append(HumanMessage(content=user_text))
+
+        llm = self._get_llm(temperature=temperature, provider=provider)
+
+        return self._invoke_with_retry(llm, messages, output_model)