yamlgraph 0.1.1__py3-none-any.whl

yamlgraph/error_handlers.py

@@ -0,0 +1,226 @@
+"""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 typing import Any, Callable
+
+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,275 @@
+"""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 typing import Type, 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,
+) -> 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.
+
+    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,
+    )
+
+
+# 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
+
+
+def set_executor(executor: "PromptExecutor | None") -> None:
+    """Set a custom executor instance for dependency injection (thread-safe).
+
+    Useful for testing or when you need different executor configurations.
+
+    Args:
+        executor: Custom PromptExecutor instance, or None to reset to default
+    """
+    global _executor
+    with _executor_lock:
+        _executor = 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,
+    ) -> 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
+
+        Raises:
+            ValueError: If required template variables are missing
+        """
+        variables = variables or {}
+
+        prompt_config = load_prompt(prompt_name)
+
+        # 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)

yamlgraph/executor_async.py

@@ -0,0 +1,122 @@
+"""Async Prompt Executor - Async interface for LLM calls.
+
+This module provides async versions of execute_prompt for use in
+async contexts like web servers or concurrent pipelines.
+
+Note: This is a foundation module. The underlying LLM calls still
+use sync HTTP clients wrapped with run_in_executor.
+"""
+
+import asyncio
+import logging
+from typing import Type, TypeVar
+
+from langchain_core.messages import HumanMessage, SystemMessage
+from pydantic import BaseModel
+
+from yamlgraph.config import DEFAULT_TEMPERATURE
+from yamlgraph.executor import format_prompt, load_prompt
+from yamlgraph.utils.llm_factory import create_llm
+from yamlgraph.utils.llm_factory_async import invoke_async
+from yamlgraph.utils.template import validate_variables
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=BaseModel)
+
+
+async def execute_prompt_async(
+    prompt_name: str,
+    variables: dict | None = None,
+    output_model: Type[T] | None = None,
+    temperature: float = DEFAULT_TEMPERATURE,
+    provider: str | None = None,
+) -> T | str:
+    """Execute a YAML prompt asynchronously.
+
+    Async version of execute_prompt for use in async contexts.
+
+    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")
+
+    Returns:
+        Parsed Pydantic model if output_model provided, else raw string
+
+    Example:
+        >>> result = await execute_prompt_async(
+        ...     "greet",
+        ...     variables={"name": "World"},
+        ...     output_model=GenericReport,
+        ... )
+    """
+    variables = variables or {}
+
+    # Load and validate prompt (sync - file I/O is fast)
+    prompt_config = load_prompt(prompt_name)
+
+    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))
+
+    # Create LLM (cached via factory)
+    llm = create_llm(temperature=temperature, provider=provider)
+
+    # Invoke asynchronously
+    return await invoke_async(llm, messages, output_model)
+
+
+async def execute_prompts_concurrent(
+    prompts: list[dict],
+) -> list[BaseModel | str]:
+    """Execute multiple prompts concurrently.
+
+    Useful for parallel LLM calls in pipelines.
+
+    Args:
+        prompts: List of dicts with keys:
+            - prompt_name: str (required)
+            - variables: dict (optional)
+            - output_model: Type[BaseModel] (optional)
+            - temperature: float (optional)
+            - provider: str (optional)
+
+    Returns:
+        List of results in same order as input prompts
+
+    Example:
+        >>> results = await execute_prompts_concurrent([
+        ...     {"prompt_name": "summarize", "variables": {"text": "..."}},
+        ...     {"prompt_name": "analyze", "variables": {"text": "..."}},
+        ... ])
+    """
+    tasks = []
+    for prompt_config in prompts:
+        task = execute_prompt_async(
+            prompt_name=prompt_config["prompt_name"],
+            variables=prompt_config.get("variables"),
+            output_model=prompt_config.get("output_model"),
+            temperature=prompt_config.get("temperature", DEFAULT_TEMPERATURE),
+            provider=prompt_config.get("provider"),
+        )
+        tasks.append(task)
+
+    return await asyncio.gather(*tasks)
+
+
+__all__ = ["execute_prompt_async", "execute_prompts_concurrent"]