yamlgraph 0.3.9__py3-none-any.whl

yamlgraph/cli/graph_commands.py

@@ -0,0 +1,541 @@
+"""Graph commands for universal graph runner.
+
+Implements:
+- graph run <path> --var key=value
+- graph list
+- graph info <path>
+- graph lint <path>
+"""
+
+import sys
+from argparse import Namespace
+from pathlib import Path
+
+import yaml
+
+from yamlgraph.config import WORKING_DIR
+from yamlgraph.tools.graph_linter import lint_graph
+
+
+def parse_vars(var_list: list[str] | None) -> dict[str, str]:
+    """Parse --var key=value arguments into a dict.
+
+    Args:
+        var_list: List of "key=value" strings
+
+    Returns:
+        Dict mapping keys to values
+
+    Raises:
+        ValueError: If a var doesn't contain '='
+    """
+    if not var_list:
+        return {}
+
+    result = {}
+    for item in var_list:
+        if "=" not in item:
+            raise ValueError(f"Invalid var format: '{item}' (expected key=value)")
+        key, value = item.split("=", 1)
+        result[key] = value
+
+    return result
+
+
+def _display_result(result: dict, truncate: bool = True) -> None:
+    """Display result summary to console.
+
+    Args:
+        result: Graph execution result dict
+        truncate: Whether to truncate long values (default: True)
+    """
+    print("=" * 60)
+    print("RESULT")
+    print("=" * 60)
+
+    skip_keys = {"messages", "errors", "_loop_counts"}
+    for key, value in result.items():
+        if key.startswith("_") or key in skip_keys:
+            continue
+        if value is not None:
+            value_str = str(value)
+            if truncate and len(value_str) > 200:
+                value_str = value_str[:200] + "..."
+            print(f"  {key}: {value_str}")
+
+
+def _handle_export(graph_path: Path, result: dict) -> None:
+    """Handle optional result export.
+
+    Args:
+        graph_path: Path to the graph YAML file
+        result: Graph execution result dict
+    """
+    from yamlgraph.storage.export import export_result
+
+    with open(graph_path) as f:
+        graph_config = yaml.safe_load(f)
+
+    export_config = graph_config.get("exports", {})
+    if export_config:
+        paths = export_result(result, export_config)
+        if paths:
+            print("\n📁 Exported:")
+            for p in paths:
+                print(f"   {p}")
+
+
+def cmd_graph_run(args: Namespace) -> None:
+    """Run any graph with provided variables.
+
+    Usage:
+        yamlgraph graph run graphs/yamlgraph.yaml --var topic=AI --var style=casual
+    """
+    from yamlgraph.graph_loader import load_and_compile
+
+    graph_path = Path(args.graph_path)
+
+    if not graph_path.exists():
+        print(f"❌ Graph file not found: {graph_path}")
+        sys.exit(1)
+
+    # Parse variables
+    try:
+        initial_state = parse_vars(args.var)
+    except ValueError as e:
+        print(f"❌ {e}")
+        sys.exit(1)
+
+    print(f"\n🚀 Running graph: {graph_path.name}")
+    if initial_state:
+        print(f"   Variables: {initial_state}")
+    print()
+
+    try:
+        graph = load_and_compile(str(graph_path))
+        app = graph.compile()
+
+        # Add thread_id if provided
+        config = {}
+        if args.thread:
+            config["configurable"] = {"thread_id": args.thread}
+            initial_state["thread_id"] = args.thread
+
+        result = app.invoke(initial_state, config=config if config else None)
+
+        _display_result(result, truncate=not getattr(args, "full", False))
+
+        if args.export:
+            _handle_export(graph_path, result)
+
+        print()
+
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        sys.exit(1)
+
+
+def cmd_graph_list(args: Namespace) -> None:
+    """List available graphs in graphs/ directory."""
+    graphs_dir = Path("graphs")
+
+    if not graphs_dir.exists():
+        print("❌ graphs/ directory not found")
+        return
+
+    yaml_files = sorted(graphs_dir.glob("*.yaml"))
+
+    if not yaml_files:
+        print("No graphs found in graphs/")
+        return
+
+    print(f"\n📋 Available graphs ({len(yaml_files)}):\n")
+
+    for path in yaml_files:
+        try:
+            with open(path) as f:
+                config = yaml.safe_load(f)
+            description = config.get("description", "")
+            print(f"  {path.name}")
+            if description:
+                print(f"    {description[:60]}")
+        except Exception:
+            print(f"  {path.name} (invalid)")
+
+    print()
+
+
+def cmd_graph_info(args: Namespace) -> None:
+    """Show information about a graph."""
+    graph_path = Path(args.graph_path)
+
+    if not graph_path.exists():
+        print(f"❌ Graph file not found: {graph_path}")
+        sys.exit(1)
+
+    try:
+        with open(graph_path) as f:
+            config = yaml.safe_load(f)
+
+        name = config.get("name", graph_path.stem)
+        description = config.get("description", "No description")
+        state_class = config.get("state_class", "default")
+        nodes = config.get("nodes", {})
+        edges = config.get("edges", [])
+
+        print(f"\n📊 Graph: {name}")
+        print(f"   {description}")
+        print(f"\n   State: {state_class}")
+
+        # Show nodes
+        print(f"\n   Nodes ({len(nodes)}):")
+        for node_name, node_config in nodes.items():
+            node_type = node_config.get("type", "prompt")
+            print(f"     - {node_name} ({node_type})")
+
+        # Show edges
+        print(f"\n   Edges ({len(edges)}):")
+        for edge in edges:
+            from_node = edge.get("from", "?")
+            to_node = edge.get("to", "?")
+            condition = edge.get("condition", "")
+            if condition:
+                print(f"     {from_node} → {to_node} (conditional)")
+            else:
+                print(f"     {from_node} → {to_node}")
+
+        # Show required inputs if defined
+        inputs = config.get("inputs", {})
+        if inputs:
+            print(f"\n   Inputs ({len(inputs)}):")
+            for input_name, input_config in inputs.items():
+                required = input_config.get("required", False)
+                default = input_config.get("default", None)
+                req_str = " (required)" if required else f" (default: {default})"
+                print(f"     --var {input_name}=<value>{req_str}")
+
+        print()
+
+    except Exception as e:
+        print(f"❌ Error reading graph: {e}")
+        sys.exit(1)
+
+
+def cmd_graph_mermaid(args: Namespace) -> None:
+    """Generate Mermaid diagram from a graph."""
+    graph_path = Path(args.graph_path)
+
+    if not graph_path.exists():
+        print(f"❌ Graph file not found: {graph_path}")
+        sys.exit(1)
+
+    try:
+        with open(graph_path) as f:
+            config = yaml.safe_load(f)
+
+        mermaid = generate_mermaid(config)
+
+        if hasattr(args, "output") and args.output:
+            output_path = Path(args.output)
+            output_path.write_text(mermaid)
+            print(f"✅ Mermaid diagram written to {output_path}")
+        else:
+            print(mermaid)
+
+    except Exception as e:
+        print(f"❌ Error generating mermaid: {e}")
+        sys.exit(1)
+
+
+def generate_mermaid(config: dict) -> str:
+    """Generate Mermaid flowchart from graph config.
+
+    Args:
+        config: Parsed YAML graph configuration
+
+    Returns:
+        Mermaid flowchart diagram as string
+    """
+    lines = ["```mermaid", "flowchart TD"]
+
+    nodes = config.get("nodes", {})
+    edges = config.get("edges", [])
+
+    # Node shapes by type
+    node_shapes = {
+        "llm": ("[", "]"),  # Rectangle
+        "prompt": ("[", "]"),
+        "tool": ("[[", "]]"),  # Subroutine
+        "agent": ("{{", "}}"),  # Hexagon
+        "map": ("[/", "/]"),  # Parallelogram
+        "subgraph": ("[[", "]]"),  # Subroutine (composition)
+        "router": ("{", "}"),  # Diamond-ish
+        "interrupt": ("(", ")"),  # Stadium
+        "passthrough": ("([", "])"),  # Stadium
+    }
+
+    # Define nodes with shapes
+    for node_name, node_config in nodes.items():
+        node_type = node_config.get("type", "llm")
+        left, right = node_shapes.get(node_type, ("[", "]"))
+        # Escape quotes in node name for display
+        display_name = node_name.replace('"', "'")
+        lines.append(f'    {node_name}{left}"{display_name}"{right}')
+
+    lines.append("")
+
+    # Define edges
+    for edge in edges:
+        from_node = edge.get("from", "START")
+        to_node = edge.get("to", "END")
+        condition = edge.get("condition")
+        edge_type = edge.get("type")
+
+        # Map START/END to special nodes
+        from_id = "__start__" if from_node == "START" else from_node
+
+        # Handle list of targets (conditional routing)
+        if isinstance(to_node, list):
+            for target in to_node:
+                to_id = "__end__" if target == "END" else target
+                lines.append(f"    {from_id} -.-> {to_id}")
+        else:
+            to_id = "__end__" if to_node == "END" else to_node
+
+            if condition:
+                # Conditional edge with label
+                cond_label = condition if isinstance(condition, str) else "?"
+                lines.append(f"    {from_id} -->|{cond_label}| {to_id}")
+            elif edge_type == "conditional":
+                lines.append(f"    {from_id} -.-> {to_id}")
+            else:
+                lines.append(f"    {from_id} --> {to_id}")
+
+    lines.append("```")
+    return "\n".join(lines)
+
+
+def _validate_required_fields(config: dict) -> tuple[list[str], list[str]]:
+    """Validate required fields in graph config.
+
+    Args:
+        config: Parsed YAML configuration
+
+    Returns:
+        Tuple of (errors, warnings) lists
+    """
+    errors = []
+    warnings = []
+
+    if not config.get("name"):
+        errors.append("Missing required field: name")
+
+    if not config.get("nodes"):
+        errors.append("Missing required field: nodes")
+
+    if not config.get("edges"):
+        warnings.append("No edges defined")
+
+    return errors, warnings
+
+
+def _validate_edges(edges: list[dict], node_names: set[str]) -> list[str]:
+    """Validate edge references in graph config.
+
+    Args:
+        edges: List of edge configurations
+        node_names: Set of valid node names (including START/END)
+
+    Returns:
+        List of error messages
+    """
+    errors = []
+
+    for i, edge in enumerate(edges):
+        from_node = edge.get("from", "")
+        to_node = edge.get("to", "")
+
+        if from_node not in node_names:
+            errors.append(f"Edge {i + 1}: unknown 'from' node '{from_node}'")
+
+        # Handle conditional edges where 'to' is a list
+        if isinstance(to_node, list):
+            for t in to_node:
+                if t not in node_names:
+                    errors.append(f"Edge {i + 1}: unknown 'to' node '{t}'")
+        elif to_node not in node_names:
+            errors.append(f"Edge {i + 1}: unknown 'to' node '{to_node}'")
+
+    return errors
+
+
+def _validate_nodes(nodes: dict) -> list[str]:
+    """Validate node configurations.
+
+    Args:
+        nodes: Dict of node_name -> node_config
+
+    Returns:
+        List of warning messages
+    """
+    warnings = []
+
+    for node_name, node_config in nodes.items():
+        node_type = node_config.get("type", "llm")
+        if node_type == "agent" and not node_config.get("tools"):
+            warnings.append(f"Node '{node_name}': agent has no tools")
+
+    return warnings
+
+
+def _report_validation_result(
+    graph_path: Path,
+    config: dict,
+    errors: list[str],
+    warnings: list[str],
+) -> None:
+    """Report validation results and exit appropriately.
+
+    Args:
+        graph_path: Path to the graph file
+        config: Parsed graph configuration
+        errors: List of error messages
+        warnings: List of warning messages
+    """
+    name = config.get("name", graph_path.stem)
+    nodes = config.get("nodes", {})
+    edges = config.get("edges", [])
+
+    if errors:
+        print(f"\n❌ {graph_path.name} ({name}) - INVALID\n")
+        for err in errors:
+            print(f"   ✗ {err}")
+        for warn in warnings:
+            print(f"   ⚠ {warn}")
+        print()
+        sys.exit(1)
+    elif warnings:
+        print(f"\n⚠️  {graph_path.name} ({name}) - VALID with warnings\n")
+        for warn in warnings:
+            print(f"   ⚠ {warn}")
+        print()
+    else:
+        print(f"\n✅ {graph_path.name} ({name}) - VALID\n")
+        print(f"   Nodes: {len(nodes)}")
+        print(f"   Edges: {len(edges)}")
+        print()
+
+
+def cmd_graph_validate(args: Namespace) -> None:
+    """Validate a graph YAML file.
+
+    Checks:
+    - File exists and is valid YAML
+    - Required fields present (name, nodes, edges)
+    - Node references are valid
+    - Edge references match existing nodes
+    """
+    graph_path = Path(args.graph_path)
+
+    if not graph_path.exists():
+        print(f"❌ Graph file not found: {graph_path}")
+        sys.exit(1)
+
+    try:
+        with open(graph_path) as f:
+            config = yaml.safe_load(f)
+
+        # Run validations
+        errors, warnings = _validate_required_fields(config)
+
+        nodes = config.get("nodes", {})
+        edges = config.get("edges", [])
+        node_names = set(nodes.keys()) | {"START", "END"}
+
+        errors.extend(_validate_edges(edges, node_names))
+        warnings.extend(_validate_nodes(nodes))
+
+        # Report results
+        _report_validation_result(graph_path, config, errors, warnings)
+
+    except yaml.YAMLError as e:
+        print(f"❌ Invalid YAML: {e}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"❌ Error validating graph: {e}")
+        sys.exit(1)
+
+
+def cmd_graph_lint(args: Namespace) -> None:
+    """Lint graph YAML files for issues.
+
+    Checks:
+    - Missing state declarations for variables
+    - Undefined tool references
+    - Missing prompt files
+    - Unreachable nodes
+    - Invalid node types
+    """
+    total_errors = 0
+    total_warnings = 0
+
+    for graph_path_str in args.graph_path:
+        graph_path = Path(graph_path_str)
+
+        if not graph_path.exists():
+            print(f"❌ Graph file not found: {graph_path}")
+            total_errors += 1
+            continue
+
+        try:
+            result = lint_graph(graph_path, WORKING_DIR)
+
+            errors = [i for i in result.issues if i.severity == "error"]
+            warnings = [i for i in result.issues if i.severity == "warning"]
+
+            if result.valid and not warnings:
+                print(f"✅ {graph_path.name} - No issues found")
+            else:
+                status = "❌" if errors else "⚠️"
+                print(f"{status} {graph_path.name}")
+
+                for issue in result.issues:
+                    icon = "❌" if issue.severity == "error" else "⚠"
+                    print(f"   {icon} [{issue.code}] {issue.message}")
+                    if issue.fix:
+                        print(f"      Fix: {issue.fix}")
+
+            total_errors += len(errors)
+            total_warnings += len(warnings)
+
+        except Exception as e:
+            print(f"❌ Error linting {graph_path}: {e}")
+            total_errors += 1
+
+    # Summary
+    print()
+    if total_errors == 0 and total_warnings == 0:
+        print("✅ All graphs passed linting")
+    else:
+        print(f"Found {total_errors} error(s) and {total_warnings} warning(s)")
+        if total_errors > 0:
+            sys.exit(1)
+
+
+def cmd_graph_dispatch(args: Namespace) -> None:
+    """Dispatch to graph subcommands."""
+    if args.graph_command == "run":
+        cmd_graph_run(args)
+    elif args.graph_command == "list":
+        cmd_graph_list(args)
+    elif args.graph_command == "info":
+        cmd_graph_info(args)
+    elif args.graph_command == "validate":
+        cmd_graph_validate(args)
+    elif args.graph_command == "lint":
+        cmd_graph_lint(args)
+    elif args.graph_command == "mermaid":
+        cmd_graph_mermaid(args)
+    else:
+        print(f"Unknown graph command: {args.graph_command}")
+        sys.exit(1)

yamlgraph/cli/validators.py

@@ -0,0 +1,37 @@
+"""CLI validation functions.
+
+Provides argument validation for CLI commands.
+"""
+
+from yamlgraph.config import MAX_WORD_COUNT, MIN_WORD_COUNT
+from yamlgraph.utils.sanitize import sanitize_topic
+
+
+def validate_run_args(args) -> bool:
+    """Validate and sanitize run command arguments.
+
+    Args:
+        args: Parsed arguments namespace
+
+    Returns:
+        True if valid, False otherwise (prints error message)
+    """
+    # Sanitize topic
+    result = sanitize_topic(args.topic)
+    if not result.is_safe:
+        for warning in result.warnings:
+            print(f"❌ {warning}")
+        return False
+
+    # Update args with sanitized value
+    args.topic = result.value
+
+    # Print any warnings (e.g., truncation)
+    for warning in result.warnings:
+        print(f"⚠️  {warning}")
+
+    if args.word_count < MIN_WORD_COUNT or args.word_count > MAX_WORD_COUNT:
+        print(f"❌ Word count must be between {MIN_WORD_COUNT} and {MAX_WORD_COUNT}")
+        return False
+
+    return True

yamlgraph/config.py

@@ -0,0 +1,67 @@
+"""Centralized configuration for the yamlgraph package.
+
+Provides paths, settings, and environment configuration
+used across all modules.
+"""
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+# Package root (yamlgraph/ directory)
+PACKAGE_ROOT = Path(__file__).parent
+
+# Working directory (where the user runs the CLI from)
+WORKING_DIR = Path.cwd()
+
+# Load environment variables from current working directory
+# This ensures .env is found where the user runs yamlgraph, not in site-packages
+load_dotenv(WORKING_DIR / ".env")
+
+# Directory paths (relative to working directory)
+PROMPTS_DIR = WORKING_DIR / "prompts"
+GRAPHS_DIR = WORKING_DIR / "graphs"
+OUTPUTS_DIR = WORKING_DIR / "outputs"
+DATABASE_PATH = OUTPUTS_DIR / "yamlgraph.db"
+
+# Default graph configuration
+DEFAULT_GRAPH = GRAPHS_DIR / "yamlgraph.yaml"
+
+# LLM Configuration
+DEFAULT_TEMPERATURE = 0.7
+DEFAULT_MAX_TOKENS = 4096
+
+# Default models per provider (override with {PROVIDER}_MODEL env var)
+DEFAULT_MODELS = {
+    "anthropic": os.getenv("ANTHROPIC_MODEL", "claude-haiku-4-5"),
+    "mistral": os.getenv("MISTRAL_MODEL", "mistral-large-latest"),
+    "openai": os.getenv("OPENAI_MODEL", "gpt-4o"),
+}
+
+# Retry Configuration
+MAX_RETRIES = int(os.getenv("LLM_MAX_RETRIES", "3"))
+RETRY_BASE_DELAY = float(os.getenv("LLM_RETRY_DELAY", "1.0"))  # seconds
+RETRY_MAX_DELAY = float(os.getenv("LLM_RETRY_MAX_DELAY", "30.0"))  # seconds
+
+# CLI Constraints - configurable via environment
+MAX_TOPIC_LENGTH = int(os.getenv("YAMLGRAPH_MAX_TOPIC_LENGTH", "500"))
+MAX_WORD_COUNT = int(os.getenv("YAMLGRAPH_MAX_WORD_COUNT", "5000"))
+MIN_WORD_COUNT = int(os.getenv("YAMLGRAPH_MIN_WORD_COUNT", "50"))
+
+# Valid styles - can be extended via environment (comma-separated)
+_default_styles = "informative,casual,technical"
+VALID_STYLES = tuple(os.getenv("YAMLGRAPH_VALID_STYLES", _default_styles).split(","))
+
+# Input Sanitization Patterns
+# Characters that could be used for prompt injection
+DANGEROUS_PATTERNS = [
+    "ignore previous",
+    "ignore above",
+    "disregard",
+    "forget everything",
+    "new instructions",
+    "system:",
+    "<|",  # Token delimiters
+    "|>",
+]