yamlgraph 0.3.9__py3-none-any.whl

yamlgraph/routing.py

@@ -0,0 +1,87 @@
+"""Routing utilities for LangGraph edge conditions.
+
+Provides factory functions for creating router functions that determine
+which node to route to based on state values and expressions.
+"""
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from langgraph.graph import END
+
+from yamlgraph.utils.conditions import evaluate_condition
+
+# Type alias for dynamic state
+GraphState = dict[str, Any]
+
+logger = logging.getLogger(__name__)
+
+
+def make_router_fn(targets: list[str]) -> Callable[[dict], str]:
+    """Create a router function that reads _route from state.
+
+    Used for type: router nodes with conditional edges to multiple targets.
+
+    NOTE: Use `state: dict` not `state: GraphState` - type hints cause
+    LangGraph to filter state fields. See docs/debug-router-type-hints.md
+
+    Args:
+        targets: List of valid target node names
+
+    Returns:
+        Router function that returns the target node name
+    """
+
+    def router_fn(state: dict) -> str:
+        route = state.get("_route")
+        logger.debug(f"Router: _route={route}, targets={targets}")
+        if route and route in targets:
+            logger.debug(f"Router: matched route {route}")
+            return route
+        # Default to first target
+        logger.debug(f"Router: defaulting to {targets[0]}")
+        return targets[0]
+
+    return router_fn
+
+
+def make_expr_router_fn(
+    edges: list[tuple[str, str]],
+    source_node: str,
+) -> Callable[[GraphState], str]:
+    """Create router that evaluates expression conditions.
+
+    Used for reflexion-style loops with expression-based conditions
+    like "critique.score < 0.8".
+
+    Args:
+        edges: List of (condition, target) tuples
+        source_node: Name of the source node (for logging)
+
+    Returns:
+        Router function that evaluates conditions and returns target
+    """
+
+    def expr_router_fn(state: GraphState) -> str:
+        # Check loop limit first
+        if state.get("_loop_limit_reached"):
+            return END
+
+        for condition, target in edges:
+            try:
+                if evaluate_condition(condition, state):
+                    logger.debug(
+                        f"Condition '{condition}' matched, routing to {target}"
+                    )
+                    return target
+            except ValueError as e:
+                logger.warning(f"Failed to evaluate condition '{condition}': {e}")
+        # No condition matched - this shouldn't happen with well-formed graphs
+        logger.warning(f"No condition matched for {source_node}, defaulting to END")
+        return END
+
+    return expr_router_fn
+
+
+__all__ = ["make_router_fn", "make_expr_router_fn"]

yamlgraph/schema_loader.py

@@ -0,0 +1,240 @@
+"""Dynamic Pydantic model generation from YAML schema definitions.
+
+This module enables defining output schemas in YAML prompt files,
+making prompts fully self-contained with their expected output structure.
+
+Example YAML schema:
+    schema:
+      name: MyOutputModel
+      fields:
+        title:
+          type: str
+          description: "The output title"
+        confidence:
+          type: float
+          constraints: {ge: 0.0, le: 1.0}
+"""
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import Field, create_model
+
+# =============================================================================
+# Type Resolution
+# =============================================================================
+
+# Mapping from type strings to Python types
+TYPE_MAP: dict[str, type] = {
+    "str": str,
+    "int": int,
+    "float": float,
+    "bool": bool,
+    "Any": Any,
+}
+
+
+def resolve_type(type_str: str, field_name: str | None = None) -> type:
+    """Resolve a type string to a Python type.
+
+    Supports:
+        - Basic types: str, int, float, bool, Any
+        - Generic types: list[str], list[int], dict[str, str]
+
+    Args:
+        type_str: Type string like "str", "list[str]", "dict[str, Any]"
+        field_name: Optional field name for better error messages
+
+    Returns:
+        Python type annotation
+
+    Raises:
+        ValueError: If type string is not recognized
+    """
+    # Check basic types first
+    if type_str in TYPE_MAP:
+        return TYPE_MAP[type_str]
+
+    # Handle list[T] pattern
+    list_match = re.match(r"list\[(\w+)\]", type_str)
+    if list_match:
+        inner_type = resolve_type(list_match.group(1), field_name)
+        return list[inner_type]
+
+    # Handle dict[K, V] pattern
+    dict_match = re.match(r"dict\[(\w+),\s*(\w+)\]", type_str)
+    if dict_match:
+        key_type = resolve_type(dict_match.group(1), field_name)
+        value_type = resolve_type(dict_match.group(2), field_name)
+        return dict[key_type, value_type]
+
+    # Provide helpful error with supported types
+    supported = ", ".join(TYPE_MAP.keys())
+    context = f" for field '{field_name}'" if field_name else ""
+    raise ValueError(
+        f"Unknown type: '{type_str}'{context}. "
+        f"Supported types: {supported}, list[T], dict[K, V]"
+    )
+
+
+# =============================================================================
+# Model Building
+# =============================================================================
+
+
+def build_pydantic_model(schema: dict) -> type:
+    """Build a Pydantic model dynamically from a schema dict.
+
+    Args:
+        schema: Schema definition with 'name' and 'fields' keys
+            Example:
+                {
+                    "name": "MyOutputModel",
+                    "fields": {
+                        "title": {"type": "str", "description": "..."},
+                        "score": {"type": "float", "constraints": {"ge": 0}},
+                    }
+                }
+
+    Returns:
+        Dynamically created Pydantic model class
+    """
+    model_name = schema["name"]
+    field_definitions = {}
+
+    for field_name, field_def in schema["fields"].items():
+        # Resolve the type - pass field_name for better error messages
+        field_type = resolve_type(field_def["type"], field_name)
+
+        # Handle optional fields
+        is_optional = field_def.get("optional", False)
+        if is_optional:
+            field_type = field_type | None
+
+        # Build Field kwargs
+        field_kwargs: dict[str, Any] = {}
+
+        if "description" in field_def:
+            field_kwargs["description"] = field_def["description"]
+
+        if "default" in field_def:
+            field_kwargs["default"] = field_def["default"]
+        elif is_optional:
+            field_kwargs["default"] = None
+
+        # Add constraints (ge, le, min_length, max_length, etc.)
+        if constraints := field_def.get("constraints"):
+            field_kwargs.update(constraints)
+
+        # Create field tuple: (type, Field(...))
+        if field_kwargs:
+            field_definitions[field_name] = (field_type, Field(**field_kwargs))
+        else:
+            field_definitions[field_name] = (field_type, ...)
+
+    return create_model(model_name, **field_definitions)
+
+
+# JSON Schema type mapping
+JSON_SCHEMA_TYPE_MAP: dict[str, type] = {
+    "string": str,
+    "integer": int,
+    "number": float,
+    "boolean": bool,
+    "array": list,
+    "object": dict,
+}
+
+
+def build_pydantic_model_from_json_schema(
+    schema: dict, model_name: str = "DynamicOutput"
+) -> type:
+    """Build a Pydantic model from a JSON Schema-style definition.
+
+    Args:
+        schema: JSON Schema with 'type: object' and 'properties'
+        model_name: Name for the generated model
+
+    Returns:
+        Dynamically created Pydantic model class
+    """
+    if schema.get("type") != "object":
+        raise ValueError("output_schema must have type: object")
+
+    properties = schema.get("properties", {})
+    required = set(schema.get("required", []))
+
+    field_definitions = {}
+
+    for field_name, field_def in properties.items():
+        json_type = field_def.get("type", "string")
+        description = field_def.get("description", "")
+
+        # Handle array types
+        if json_type == "array":
+            items = field_def.get("items", {})
+            item_type = JSON_SCHEMA_TYPE_MAP.get(items.get("type", "string"), str)
+            field_type = list[item_type]
+        # Handle enum types
+        elif "enum" in field_def:
+            field_type = str  # Enums become str in Pydantic
+        else:
+            field_type = JSON_SCHEMA_TYPE_MAP.get(json_type, str)
+
+        # Check if required
+        is_optional = field_name not in required
+        if is_optional:
+            field_type = field_type | None
+
+        # Build Field
+        field_kwargs: dict[str, Any] = {}
+        if description:
+            field_kwargs["description"] = description
+        if is_optional:
+            field_kwargs["default"] = None
+
+        if field_kwargs:
+            field_definitions[field_name] = (field_type, Field(**field_kwargs))
+        else:
+            field_definitions[field_name] = (field_type, ...)
+
+    return create_model(model_name, **field_definitions)
+
+
+# =============================================================================
+# YAML Loading
+# =============================================================================
+
+
+def load_schema_from_yaml(yaml_path: str | Path) -> type | None:
+    """Load a Pydantic model from a prompt YAML file's schema block.
+
+    Supports two formats:
+    1. Native format (schema: with name/fields)
+    2. JSON Schema format (output_schema: with type/properties)
+
+    Args:
+        yaml_path: Path to the YAML prompt file
+
+    Returns:
+        Dynamically created Pydantic model, or None if no schema defined
+    """
+    with open(yaml_path) as f:
+        config = yaml.safe_load(f)
+
+    # Check for native format first
+    if "schema" in config:
+        return build_pydantic_model(config["schema"])
+
+    # Check for JSON Schema format (output_schema)
+    if "output_schema" in config:
+        # Generate model name from file name
+        path = Path(yaml_path)
+        model_name = "".join(word.title() for word in path.stem.split("_")) + "Output"
+        return build_pydantic_model_from_json_schema(
+            config["output_schema"], model_name
+        )
+
+    return None

yamlgraph/storage/__init__.py

@@ -0,0 +1,20 @@
+"""Storage utilities for persistence and export."""
+
+from yamlgraph.storage.checkpointer_factory import expand_env_vars, get_checkpointer
+from yamlgraph.storage.database import YamlGraphDB
+from yamlgraph.storage.export import (
+    export_state,
+    export_summary,
+    list_exports,
+    load_export,
+)
+
+__all__ = [
+    "YamlGraphDB",
+    "export_state",
+    "export_summary",
+    "expand_env_vars",
+    "get_checkpointer",
+    "list_exports",
+    "load_export",
+]

yamlgraph/storage/checkpointer.py

@@ -0,0 +1,72 @@
+"""LangGraph native checkpointer integration.
+
+Provides SQLite-based checkpointing for graph state persistence,
+enabling time travel, replay, and resume from any checkpoint.
+"""
+
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from langgraph.checkpoint.sqlite import SqliteSaver
+from langgraph.graph.state import CompiledStateGraph
+
+from yamlgraph.config import DATABASE_PATH
+
+
+def get_checkpointer(db_path: str | Path | None = None) -> SqliteSaver:
+    """Get a SQLite checkpointer for graph compilation.
+
+    The checkpointer enables:
+    - Automatic state persistence after each node
+    - Time travel via get_state_history()
+    - Resume from any checkpoint
+    - Fault tolerance with pending writes
+
+    Args:
+        db_path: Path to SQLite database file.
+                 Defaults to outputs/yamlgraph.db
+
+    Returns:
+        SqliteSaver instance for use with graph.compile()
+
+    Example:
+        >>> checkpointer = get_checkpointer()
+        >>> graph = workflow.compile(checkpointer=checkpointer)
+        >>> result = graph.invoke(input, {"configurable": {"thread_id": "abc"}})
+    """
+    if db_path is None:
+        db_path = DATABASE_PATH
+
+    path = Path(db_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    conn = sqlite3.connect(str(path), check_same_thread=False)
+    return SqliteSaver(conn)
+
+
+def get_state_history(
+    graph: CompiledStateGraph,
+    thread_id: str,
+) -> list[Any]:
+    """Get checkpoint history for a thread.
+
+    Returns checkpoints in reverse chronological order (most recent first).
+
+    Args:
+        graph: Compiled graph with checkpointer
+        thread_id: Thread identifier to query
+
+    Returns:
+        List of StateSnapshot objects, or empty list if thread doesn't exist
+
+    Example:
+        >>> history = get_state_history(graph, "my-thread")
+        >>> for snapshot in history:
+        ...     print(f"Step {snapshot.metadata.get('step')}: {snapshot.values}")
+    """
+    config = {"configurable": {"thread_id": thread_id}}
+    try:
+        return list(graph.get_state_history(config))
+    except Exception:
+        return []

yamlgraph/storage/checkpointer_factory.py

@@ -0,0 +1,123 @@
+"""Checkpointer factory for YAML-configured persistence.
+
+Creates checkpointer instances from YAML configuration with support for:
+- Multiple backends (memory, sqlite, redis)
+- Environment variable expansion for secrets
+- Sync and async modes for Redis
+"""
+
+import os
+import re
+from typing import Any
+
+from langgraph.checkpoint.base import BaseCheckpointSaver
+
+
+def expand_env_vars(value: Any) -> Any:
+    """Expand ${VAR} patterns in string.
+
+    Args:
+        value: Value to expand. Non-strings pass through unchanged.
+
+    Returns:
+        String with ${VAR} patterns replaced by environment values.
+        Missing vars keep original ${VAR} pattern.
+    """
+    if not isinstance(value, str):
+        return value
+
+    def replacer(match: re.Match) -> str:
+        var_name = match.group(1)
+        return os.environ.get(var_name, match.group(0))
+
+    return re.sub(r"\$\{([^}]+)\}", replacer, value)
+
+
+def get_checkpointer(
+    config: dict | None,
+    *,
+    async_mode: bool = False,
+) -> BaseCheckpointSaver | None:
+    """Create checkpointer from config.
+
+    Args:
+        config: Checkpointer configuration dict with keys:
+            - type: "memory" | "sqlite" | "redis" (default: "memory")
+            - url: Redis connection URL (for redis type)
+            - path: SQLite file path (for sqlite type)
+            - ttl: TTL in minutes (for redis type, default: 60)
+        async_mode: If True, return async-compatible saver for FastAPI/async usage
+
+    Returns:
+        Configured checkpointer or None if config is None
+
+    Raises:
+        ValueError: If unknown checkpointer type
+        ImportError: If redis type used without yamlgraph[redis] installed
+    """
+    if not config:
+        return None
+
+    cp_type = config.get("type", "memory")
+
+    if cp_type == "redis":
+        url = expand_env_vars(config.get("url", ""))
+        ttl = config.get("ttl", 60)
+
+        try:
+            if async_mode:
+                from langgraph.checkpoint.redis.aio import (
+                    AsyncRedisSaver,
+                )
+
+                saver = AsyncRedisSaver.from_conn_string(
+                    url,
+                    ttl={"default_ttl": ttl},
+                )
+                # For async, caller must await saver.asetup()
+            else:
+                from langgraph.checkpoint.redis import RedisSaver
+
+                saver = RedisSaver.from_conn_string(
+                    url,
+                    ttl={"default_ttl": ttl},
+                )
+                saver.setup()
+
+            return saver
+        except ImportError as e:
+            raise ImportError(
+                "Install redis support: pip install yamlgraph[redis]"
+            ) from e
+
+    elif cp_type == "sqlite":
+        path = expand_env_vars(config.get("path", ":memory:"))
+
+        if async_mode:
+            # MemorySaver supports both sync and async operations
+            # For production async SQLite, use AsyncSqliteSaver with aiosqlite
+            # but that requires async context management which complicates the API
+            import logging
+
+            if path != ":memory:":
+                logging.getLogger(__name__).info(
+                    f"Using MemorySaver for async mode (sqlite path '{path}' ignored). "
+                    "For persistent async storage, use Redis checkpointer."
+                )
+            from langgraph.checkpoint.memory import MemorySaver
+
+            return MemorySaver()
+        else:
+            import sqlite3
+
+            from langgraph.checkpoint.sqlite import SqliteSaver
+
+            conn = sqlite3.connect(path, check_same_thread=False)
+            return SqliteSaver(conn)
+
+    elif cp_type == "memory":
+        from langgraph.checkpoint.memory import MemorySaver
+
+        return MemorySaver()
+
+    raise ValueError(f"Unknown checkpointer type: {cp_type}")