yamlgraph 0.3.9__py3-none-any.whl

yamlgraph/tools/langsmith_tools.py

@@ -0,0 +1,125 @@
+"""LangSmith tools for agent use.
+
+Provides tool wrappers for LangSmith functions, enabling agents
+to inspect previous runs, check for errors, and implement
+self-correcting behavior.
+
+Example YAML configuration:
+    tools:
+      check_last_run:
+        type: python
+        module: yamlgraph.tools.langsmith_tools
+        function: get_run_details_tool
+        description: "Get status and errors from a pipeline run"
+
+      get_errors:
+        type: python
+        module: yamlgraph.tools.langsmith_tools
+        function: get_run_errors_tool
+        description: "Get detailed error info from a run"
+
+      failed_runs:
+        type: python
+        module: yamlgraph.tools.langsmith_tools
+        function: get_failed_runs_tool
+        description: "List recent failed runs"
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from yamlgraph.utils.langsmith import (
+    get_failed_runs,
+    get_run_details,
+    get_run_errors,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def get_run_details_tool(run_id: str | None = None) -> dict[str, Any]:
+    """Get detailed information about a LangSmith run.
+
+    This tool wrapper returns run details in a format suitable for
+    agent consumption.
+
+    Args:
+        run_id: Run ID to inspect. If not provided, uses the latest run.
+
+    Returns:
+        Dict with run details or error message:
+        - id: Run identifier
+        - name: Run name (usually the graph/pipeline name)
+        - status: "success", "error", or "pending"
+        - error: Error message if status is "error"
+        - start_time: When the run started (ISO format)
+        - end_time: When the run completed (ISO format)
+        - inputs: The input data for the run
+        - outputs: The output data from the run
+        - run_type: Type of run (chain, llm, tool, etc.)
+    """
+    result = get_run_details(run_id)
+    if result is None:
+        return {"error": "Could not retrieve run details", "success": False}
+
+    result["success"] = True
+    return result
+
+
+def get_run_errors_tool(run_id: str | None = None) -> dict[str, Any]:
+    """Get all errors from a run and its child nodes.
+
+    This tool retrieves error information from both the parent run
+    and all child runs (individual nodes in the graph).
+
+    Args:
+        run_id: Run ID to inspect. If not provided, uses the latest run.
+
+    Returns:
+        Dict with error information:
+        - success: Whether the query succeeded
+        - error_count: Number of errors found
+        - errors: List of error dicts, each with:
+            - node: Name of the failed node
+            - error: Error message
+            - run_type: Type of the failed run
+    """
+    errors = get_run_errors(run_id)
+    return {
+        "success": True,
+        "error_count": len(errors),
+        "errors": errors,
+        "has_errors": len(errors) > 0,
+    }
+
+
+def get_failed_runs_tool(
+    limit: int = 10,
+    project_name: str | None = None,
+) -> dict[str, Any]:
+    """Get recent failed runs from the LangSmith project.
+
+    This tool helps identify patterns in failures across multiple runs.
+
+    Args:
+        limit: Maximum number of failed runs to return (default: 10)
+        project_name: LangSmith project name. Uses default if not provided.
+
+    Returns:
+        Dict with failed run information:
+        - success: Whether the query succeeded
+        - failed_count: Number of failed runs found
+        - runs: List of failed run summaries, each with:
+            - id: Run identifier
+            - name: Run name
+            - error: Error message
+            - start_time: When the run started (ISO format)
+    """
+    runs = get_failed_runs(project_name=project_name, limit=limit)
+    return {
+        "success": True,
+        "failed_count": len(runs),
+        "runs": runs,
+    }

yamlgraph/tools/nodes.py

@@ -0,0 +1,126 @@
+"""Node factories for tool and agent nodes.
+
+This module provides functions to create graph nodes that execute
+shell tools, either deterministically (tool nodes) or via LLM
+decision-making (agent nodes).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from yamlgraph.models.schemas import ErrorType, PipelineError
+from yamlgraph.tools.shell import ShellToolConfig, execute_shell_tool
+from yamlgraph.utils.expressions import resolve_template
+
+# Type alias for state - dynamic TypedDict at runtime
+GraphState = dict[str, Any]
+
+logger = logging.getLogger(__name__)
+
+
+def resolve_state_variable(template: str, state: dict[str, Any]) -> str:
+    """Resolve {state.path.to.value} to actual state value.
+
+    Note: Uses consolidated resolve_template from expressions module.
+
+    Args:
+        template: String with {state.key} or {state.nested.key} placeholders
+        state: Current graph state
+
+    Returns:
+        Resolved value (preserves type: lists, dicts, etc.)
+    """
+    value = resolve_template(template, state)
+    # resolve_template returns the template unchanged if not a state expression
+    if value is template:
+        return template
+    # Preserve the original type - don't convert to string
+    # This allows lists and dicts to be passed to Jinja2 templates correctly
+    return value
+
+
+def resolve_variables(
+    variables_config: dict[str, str],
+    state: dict[str, Any],
+) -> dict[str, Any]:
+    """Resolve all variable templates against state.
+
+    Args:
+        variables_config: Dict of {var_name: template_string}
+        state: Current graph state
+
+    Returns:
+        Dict of {var_name: resolved_value}
+    """
+    resolved = {}
+    for key, template in variables_config.items():
+        resolved[key] = resolve_state_variable(template, state)
+    return resolved
+
+
+def create_tool_node(
+    node_name: str,
+    node_config: dict[str, Any],
+    tools: dict[str, ShellToolConfig],
+) -> Callable[[GraphState], dict]:
+    """Create a node that executes a shell tool.
+
+    Args:
+        node_name: Name of the node in the graph
+        node_config: Node configuration from YAML
+        tools: Registry of available tools
+
+    Returns:
+        Node function that executes the tool
+
+    Raises:
+        KeyError: If tool name not in registry
+    """
+    tool_name = node_config["tool"]
+    tool_config = tools[tool_name]  # Raise KeyError if not found
+    state_key = node_config.get("state_key", node_name)
+    on_error = node_config.get("on_error", "fail")
+    variables_template = node_config.get("variables", {})
+
+    def node_fn(state: GraphState) -> dict:
+        """Execute the shell tool and return state update."""
+        # Resolve variables from state
+        variables = resolve_variables(variables_template, state)
+
+        logger.info(f"🔧 Executing tool: {tool_name}")
+        result = execute_shell_tool(tool_config, variables)
+
+        if not result.success:
+            logger.warning(f"Tool {tool_name} failed: {result.error}")
+
+            if on_error == "skip":
+                # Return with error tracked but don't raise
+                errors = list(state.get("errors") or [])
+                errors.append(
+                    PipelineError(
+                        node=node_name,
+                        type=ErrorType.UNKNOWN_ERROR,
+                        message=result.error or "Tool execution failed",
+                    )
+                )
+                return {
+                    state_key: None,
+                    "current_step": node_name,
+                    "errors": errors,
+                }
+            else:
+                # on_error == "fail" - raise exception
+                raise RuntimeError(
+                    f"Tool '{tool_name}' failed in node '{node_name}': {result.error}"
+                )
+
+        logger.info(f"✓ Tool {tool_name} completed")
+        return {
+            state_key: result.output,
+            "current_step": node_name,
+        }
+
+    return node_fn

yamlgraph/tools/python_tool.py

@@ -0,0 +1,179 @@
+"""Python function loader for type: python nodes.
+
+This module enables YAML graphs to call arbitrary Python functions
+by specifying the module path and function name.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PythonToolConfig:
+    """Configuration for a Python tool.
+
+    Attributes:
+        module: Full module path (e.g., "examples.storyboard.nodes.image_node")
+        function: Function name within the module
+        description: Human-readable description
+    """
+
+    module: str
+    function: str
+    description: str = ""
+
+
+def load_python_function(config: PythonToolConfig) -> Callable:
+    """Load a Python function from module path.
+
+    Args:
+        config: Python tool configuration
+
+    Returns:
+        The loaded function
+
+    Raises:
+        ImportError: If module cannot be imported
+        AttributeError: If function not found in module
+    """
+    # Ensure current working directory is in path for project imports
+    cwd = os.getcwd()
+    if cwd not in sys.path:
+        sys.path.insert(0, cwd)
+
+    try:
+        module = importlib.import_module(config.module)
+    except ImportError as e:
+        logger.error(f"Failed to import module: {config.module}")
+        raise ImportError(f"Cannot import module '{config.module}': {e}") from e
+
+    try:
+        func = getattr(module, config.function)
+    except AttributeError as e:
+        logger.error(f"Function not found: {config.function} in {config.module}")
+        raise AttributeError(
+            f"Function '{config.function}' not found in module '{config.module}'"
+        ) from e
+
+    if not callable(func):
+        raise TypeError(f"'{config.function}' in '{config.module}' is not callable")
+
+    logger.debug(f"Loaded Python function: {config.module}.{config.function}")
+    return func
+
+
+def parse_python_tools(tools_config: dict[str, Any]) -> dict[str, PythonToolConfig]:
+    """Parse Python tools from YAML tools section.
+
+    Only extracts tools with type: python.
+
+    Args:
+        tools_config: Dict from YAML tools: section
+
+    Returns:
+        Registry mapping tool names to PythonToolConfig objects
+    """
+    registry: dict[str, PythonToolConfig] = {}
+
+    for name, config in tools_config.items():
+        if config.get("type") != "python":
+            continue
+
+        if "module" not in config or "function" not in config:
+            logger.warning(
+                f"Python tool '{name}' missing 'module' or 'function', skipping"
+            )
+            continue
+
+        registry[name] = PythonToolConfig(
+            module=config["module"],
+            function=config["function"],
+            description=config.get("description", ""),
+        )
+
+    return registry
+
+
+def create_python_node(
+    node_name: str,
+    node_config: dict[str, Any],
+    python_tools: dict[str, PythonToolConfig],
+) -> Callable[[dict[str, Any]], dict]:
+    """Create a node that executes a Python function.
+
+    The function receives the full state dict and should return
+    a partial state update dict.
+
+    Args:
+        node_name: Name of the node in the graph
+        node_config: Node configuration from YAML
+        python_tools: Registry of available Python tools
+
+    Returns:
+        Node function that executes the Python function
+    """
+    tool_name = node_config.get("tool") or node_config.get("function")
+    if not tool_name:
+        raise ValueError(f"Python node '{node_name}' must specify 'tool' or 'function'")
+
+    if tool_name not in python_tools:
+        raise KeyError(f"Python tool '{tool_name}' not found in tools registry")
+
+    tool_config = python_tools[tool_name]
+    state_key = node_config.get("state_key", node_name)
+    on_error = node_config.get("on_error", "fail")
+
+    # Load the function at node creation time
+    func = load_python_function(tool_config)
+
+    def node_fn(state: dict[str, Any]) -> dict:
+        """Execute the Python function and return state update."""
+        logger.info(f"🐍 Executing Python node: {node_name} -> {tool_name}")
+
+        try:
+            result = func(state)
+
+            # If function returns a dict, merge with node metadata
+            if isinstance(result, dict):
+                result["current_step"] = node_name
+                return result
+            else:
+                # Function returned a single value, store in state_key
+                return {
+                    state_key: result,
+                    "current_step": node_name,
+                }
+
+        except Exception as e:
+            logger.error(f"Python node {node_name} failed: {e}")
+
+            if on_error == "skip":
+                from yamlgraph.models import ErrorType, PipelineError
+
+                errors = list(state.get("errors") or [])
+                errors.append(
+                    PipelineError(
+                        node=node_name,
+                        type=ErrorType.UNKNOWN_ERROR,
+                        message=str(e),
+                    )
+                )
+                return {
+                    state_key: None,
+                    "current_step": node_name,
+                    "errors": errors,
+                }
+            else:
+                raise
+
+    node_fn.__name__ = f"{node_name}_python_node"
+    return node_fn

yamlgraph/tools/shell.py

@@ -0,0 +1,205 @@
+"""Shell tool executor for running commands with variable substitution.
+
+This module provides the core shell tool execution functionality,
+allowing YAML-defined tools to run shell commands with parsed output.
+
+Security Model:
+    Variables are sanitized with shlex.quote() to prevent shell injection.
+    The command template itself is trusted (from YAML config), but all
+    user-provided variable values are escaped before substitution.
+
+    Example:
+        command: "git log --author={author}"
+        variables: {"author": "$(rm -rf /)"}
+        → Executed: git log --author='$(rm -rf /)'  (safely quoted)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shlex
+import subprocess
+from dataclasses import dataclass, field
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ShellToolConfig:
+    """Configuration for a shell tool.
+
+    Attributes:
+        command: Shell command with {variable} placeholders
+        description: Human-readable description for LLM tool selection
+        parse: Output parsing mode - 'text', 'json', or 'none'
+        timeout: Max seconds before command is killed
+        working_dir: Directory to run command in
+        env: Additional environment variables
+        success_codes: Exit codes considered successful
+    """
+
+    command: str
+    description: str = ""
+    parse: str = "text"  # text | json | none
+    timeout: int = 30
+    working_dir: str = "."
+    env: dict[str, str] = field(default_factory=dict)
+    success_codes: list[int] = field(default_factory=lambda: [0])
+
+
+@dataclass
+class ToolResult:
+    """Result from executing a shell tool.
+
+    Attributes:
+        success: Whether the command succeeded
+        output: Parsed output (str, dict, or None based on parse mode)
+        error: Error message if failed
+    """
+
+    success: bool
+    output: Any = None
+    error: str | None = None
+
+
+def sanitize_variables(variables: dict[str, Any]) -> dict[str, str]:
+    """Sanitize variable values for safe shell substitution.
+
+    Uses shlex.quote() to escape values, preventing shell injection.
+
+    Args:
+        variables: Raw variable values
+
+    Returns:
+        Sanitized variables safe for shell interpolation
+    """
+    sanitized = {}
+    for key, value in variables.items():
+        if value is None:
+            sanitized[key] = ""
+        elif isinstance(value, (list, dict)):
+            # Convert complex types to JSON, then quote
+            sanitized[key] = shlex.quote(json.dumps(value))
+        else:
+            sanitized[key] = shlex.quote(str(value))
+    return sanitized
+
+
+def execute_shell_tool(
+    config: ShellToolConfig,
+    variables: dict[str, Any],
+    sanitize: bool = True,
+) -> ToolResult:
+    """Execute shell command with variable substitution.
+
+    Args:
+        config: Tool configuration with command template
+        variables: Values to substitute into command placeholders
+        sanitize: Whether to sanitize variables with shlex.quote (default True)
+
+    Returns:
+        ToolResult with success status and parsed output or error
+    """
+    # Sanitize variables to prevent shell injection
+    safe_vars = sanitize_variables(variables) if sanitize else variables
+
+    # Substitute variables into command
+    try:
+        command = config.command.format(**safe_vars)
+    except KeyError as e:
+        return ToolResult(
+            success=False,
+            error=f"Missing variable: {e}",
+        )
+
+    logger.debug(f"Executing: {command}")
+
+    # Build environment
+    env = os.environ.copy()
+    env.update(config.env)
+
+    try:
+        # Security: shell=True is required for command templates with pipes/redirects.
+        # All user-provided variables are sanitized via shlex.quote() in sanitize_variables()
+        # before substitution, preventing shell injection attacks. The command template
+        # itself comes from trusted YAML configuration, not user input.
+        result = subprocess.run(
+            command,
+            shell=True,  # nosec B602
+            capture_output=True,
+            text=True,
+            timeout=config.timeout,
+            cwd=config.working_dir,
+            env=env,
+        )
+    except subprocess.TimeoutExpired:
+        return ToolResult(
+            success=False,
+            error=f"Command timed out after {config.timeout} seconds",
+        )
+    except Exception as e:
+        return ToolResult(
+            success=False,
+            error=f"Execution error: {e}",
+        )
+
+    # Check exit code
+    if result.returncode not in config.success_codes:
+        return ToolResult(
+            success=False,
+            output=result.stdout,
+            error=result.stderr or f"Exit code {result.returncode}",
+        )
+
+    # Parse output
+    output = result.stdout
+    if config.parse == "json":
+        try:
+            output = json.loads(output)
+        except json.JSONDecodeError as e:
+            return ToolResult(
+                success=False,
+                error=f"JSON parse error: {e}",
+            )
+    elif config.parse == "none":
+        output = None
+
+    return ToolResult(success=True, output=output)
+
+
+def parse_tools(tools_config: dict[str, Any]) -> dict[str, ShellToolConfig]:
+    """Parse tools: section from YAML into ShellToolConfig registry.
+
+    Only parses shell tools (type: shell or no type specified with command).
+    Skips Python tools (type: python).
+
+    Args:
+        tools_config: Dict from YAML tools: section
+
+    Returns:
+        Registry mapping tool names to ShellToolConfig objects
+    """
+    registry: dict[str, ShellToolConfig] = {}
+
+    for name, config in tools_config.items():
+        # Skip Python tools
+        if config.get("type") == "python":
+            continue
+        # Skip tools without command (invalid shell tools)
+        if "command" not in config:
+            continue
+
+        registry[name] = ShellToolConfig(
+            command=config["command"],
+            description=config.get("description", ""),
+            parse=config.get("parse", "text"),
+            timeout=config.get("timeout", 30),
+            working_dir=config.get("working_dir", "."),
+            env=config.get("env", {}),
+            success_codes=config.get("success_codes", [0]),
+        )
+
+    return registry