yamlgraph 0.1.1__py3-none-any.whl

yamlgraph/cli/__init__.py

@@ -0,0 +1,139 @@
+"""YamlGraph CLI - Command-line interface for yamlgraph.
+
+This package provides the CLI entry point and command implementations.
+
+Usage:
+    yamlgraph graph run graphs/yamlgraph.yaml --var topic="AI" --var style=casual
+    yamlgraph graph run graphs/router-demo.yaml --var message="hello"
+    yamlgraph graph list
+    yamlgraph list-runs
+    yamlgraph resume --thread-id abc123
+    yamlgraph trace --run-id <run-id>
+"""
+
+import argparse
+
+# Import submodules for package access
+from yamlgraph.cli import commands, validators
+from yamlgraph.cli.commands import (
+    cmd_export,
+    cmd_list_runs,
+    cmd_resume,
+    cmd_trace,
+)
+
+__all__ = [
+    # Submodules
+    "commands",
+    "validators",
+    # Entry points
+    "main",
+    "create_parser",
+]
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create and configure the CLI argument parser.
+
+    Returns:
+        Configured ArgumentParser for testing and main().
+    """
+    parser = argparse.ArgumentParser(
+        description="YAMLGraph - YAML-first LLM Pipeline Framework",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # List runs command
+    list_parser = subparsers.add_parser("list-runs", help="List recent runs")
+    list_parser.add_argument(
+        "--limit", "-l", type=int, default=10, help="Maximum runs to show"
+    )
+    list_parser.set_defaults(func=cmd_list_runs)
+
+    # Resume command
+    resume_parser = subparsers.add_parser("resume", help="Resume a pipeline")
+    resume_parser.add_argument(
+        "--thread-id", "-i", required=True, help="Thread ID to resume"
+    )
+    resume_parser.set_defaults(func=cmd_resume)
+
+    # Trace command
+    trace_parser = subparsers.add_parser("trace", help="Show execution trace")
+    trace_parser.add_argument(
+        "--run-id", "-r", help="Run ID (uses latest if not provided)"
+    )
+    trace_parser.add_argument(
+        "--verbose", "-v", action="store_true", help="Include timing details"
+    )
+    trace_parser.set_defaults(func=cmd_trace)
+
+    # Export command
+    export_parser = subparsers.add_parser("export", help="Export a run to JSON")
+    export_parser.add_argument(
+        "--thread-id", "-i", required=True, help="Thread ID to export"
+    )
+    export_parser.set_defaults(func=cmd_export)
+
+    # Graph command group (universal runner)
+    from yamlgraph.cli.graph_commands import cmd_graph_dispatch
+
+    graph_parser = subparsers.add_parser(
+        "graph", help="Universal graph runner and utilities"
+    )
+    graph_subparsers = graph_parser.add_subparsers(
+        dest="graph_command", help="Graph commands"
+    )
+
+    # graph run
+    graph_run_parser = graph_subparsers.add_parser("run", help="Run any graph")
+    graph_run_parser.add_argument("graph_path", help="Path to graph YAML file")
+    graph_run_parser.add_argument(
+        "--var",
+        "-v",
+        action="append",
+        default=[],
+        help="Set state variable (key=value), can repeat",
+    )
+    graph_run_parser.add_argument(
+        "--thread", "-t", type=str, default=None, help="Thread ID for persistence"
+    )
+    graph_run_parser.add_argument(
+        "--export", "-e", action="store_true", help="Export results to files"
+    )
+
+    # graph list
+    graph_subparsers.add_parser("list", help="List available graphs")
+
+    # graph info
+    graph_info_parser = graph_subparsers.add_parser(
+        "info", help="Show graph information"
+    )
+    graph_info_parser.add_argument("graph_path", help="Path to graph YAML file")
+
+    # graph validate
+    graph_validate_parser = graph_subparsers.add_parser(
+        "validate", help="Validate graph YAML schema"
+    )
+    graph_validate_parser.add_argument("graph_path", help="Path to graph YAML file")
+
+    graph_parser.set_defaults(func=cmd_graph_dispatch)
+
+    return parser
+
+
+def main():
+    """Main CLI entry point."""
+    parser = create_parser()
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        return
+
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

yamlgraph/cli/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running yamlgraph.cli as a module: python -m yamlgraph.cli"""
+
+from yamlgraph.cli import main
+
+if __name__ == "__main__":
+    main()

yamlgraph/cli/commands.py

@@ -0,0 +1,232 @@
+"""CLI command implementations.
+
+Contains all cmd_* functions for CLI subcommands.
+"""
+
+import sys
+from argparse import Namespace
+from typing import Any
+
+from pydantic import BaseModel
+
+from yamlgraph.cli.validators import validate_run_args
+
+# Internal keys to skip when formatting results
+_INTERNAL_KEYS = frozenset(
+    {
+        "_route",
+        "_loop_counts",
+        "thread_id",
+        "current_step",
+        "errors",
+        "topic",
+        "style",
+        "word_count",
+    }
+)
+
+
+def _format_value(value: Any, max_length: int = 200) -> str:
+    """Format a single value for display.
+
+    Args:
+        value: The value to format (str, list, Pydantic model, etc.)
+        max_length: Maximum length before truncation
+
+    Returns:
+        Formatted string representation
+    """
+    if isinstance(value, BaseModel):
+        # Format Pydantic model as key: value pairs
+        lines = []
+        for field_name, field_value in value.model_dump().items():
+            formatted = _format_value(field_value, max_length)
+            lines.append(f"   {field_name}: {formatted}")
+        return "\n" + "\n".join(lines)
+
+    if isinstance(value, list):
+        # Format list items
+        if not value:
+            return "[]"
+        if len(value) <= 3:
+            return str(value)
+        return f"[{len(value)} items]"
+
+    if isinstance(value, str):
+        if len(value) > max_length:
+            return value[:max_length] + "..."
+        return value
+
+    return str(value)
+
+
+def _format_result(result: dict[str, Any]) -> None:
+    """Format and print pipeline result generically.
+
+    Iterates over all non-internal keys in the result dict
+    and prints their values. Works with any Pydantic model.
+
+    Args:
+        result: Pipeline result dict with arbitrary Pydantic models
+    """
+    for key, value in result.items():
+        if key in _INTERNAL_KEYS or value is None:
+            continue
+
+        print(f"\n📝 {key}:")
+        formatted = _format_value(value)
+        if formatted.startswith("\n"):
+            print(formatted)
+        else:
+            print(f"   {formatted}")
+
+
+def cmd_run(args: Namespace) -> None:
+    """Run the yamlgraph pipeline."""
+    if not validate_run_args(args):
+        sys.exit(1)
+
+    from yamlgraph.builder import run_pipeline
+    from yamlgraph.storage import YamlGraphDB, export_state
+    from yamlgraph.utils import get_run_url, is_tracing_enabled
+
+    print("\n🚀 Running yamlgraph pipeline")
+    print(f"   Topic: {args.topic}")
+    print(f"   Style: {args.style}")
+    print(f"   Words: {args.word_count}")
+    print()
+
+    # Run pipeline
+    result = run_pipeline(
+        topic=args.topic,
+        style=args.style,
+        word_count=args.word_count,
+    )
+
+    # Save to database
+    db = YamlGraphDB()
+    db.save_state(result["thread_id"], result, status="completed")
+    print(f"\n💾 Saved to database: thread_id={result['thread_id']}")
+
+    # Export to JSON
+    if args.export:
+        filepath = export_state(result)
+        print(f"📄 Exported to: {filepath}")
+
+    # Show results
+    print("\n" + "=" * 60)
+    print("RESULTS")
+    print("=" * 60)
+
+    _format_result(result)
+
+    # Show LangSmith link
+    if is_tracing_enabled():
+        if url := get_run_url():
+            print(f"\n🔗 LangSmith: {url}")
+
+    print()
+
+
+def cmd_list_runs(args: Namespace) -> None:
+    """List recent pipeline runs."""
+    from yamlgraph.storage import YamlGraphDB
+
+    db = YamlGraphDB()
+    runs = db.list_runs(limit=args.limit)
+
+    if not runs:
+        print("No runs found.")
+        return
+
+    print(f"\n📋 Recent runs ({len(runs)}):\n")
+    print(f"{'Thread ID':<12} {'Status':<12} {'Updated':<20}")
+    print("-" * 50)
+
+    for run in runs:
+        print(f"{run['thread_id']:<12} {run['status']:<12} {run['updated_at'][:19]}")
+
+    print()
+
+
+def cmd_resume(args: Namespace) -> None:
+    """Resume a pipeline from saved state."""
+    from yamlgraph.builder import build_resume_graph
+    from yamlgraph.storage import YamlGraphDB
+
+    db = YamlGraphDB()
+    state = db.load_state(args.thread_id)
+
+    if not state:
+        print(f"❌ No run found with thread_id: {args.thread_id}")
+        return
+
+    print(f"\n🔄 Resuming from: {state.get('current_step', 'unknown')}")
+
+    # Check what's already completed
+    if state.get("final_summary"):
+        print("✅ Pipeline already complete!")
+        return
+
+    # Show what will be skipped vs run
+    skipping = []
+    running = []
+    if state.get("generated"):
+        skipping.append("generate")
+    else:
+        running.append("generate")
+    if state.get("analysis"):
+        skipping.append("analyze")
+    else:
+        running.append("analyze")
+    running.append("summarize")  # Always runs if we get here
+
+    if skipping:
+        print(f"   Skipping: {', '.join(skipping)} (already in state)")
+    print(f"   Running: {', '.join(running)}")
+
+    graph = build_resume_graph().compile()
+    result = graph.invoke(state)
+
+    # Save updated state
+    db.save_state(args.thread_id, result, status="completed")
+    print("\n✅ Pipeline completed!")
+
+    if summary := result.get("final_summary"):
+        print(f"\n📊 Summary: {summary[:200]}...")
+
+
+def cmd_trace(args: Namespace) -> None:
+    """Show execution trace for a run."""
+    from yamlgraph.utils import get_latest_run_id, get_run_url, print_run_tree
+
+    run_id = args.run_id or get_latest_run_id()
+
+    if not run_id:
+        print("❌ No run ID provided and could not find latest run.")
+        return
+
+    print(f"\n📊 Execution trace for: {run_id}")
+    print("─" * 50)
+    print()
+    print_run_tree(run_id, verbose=args.verbose)
+
+    if url := get_run_url(run_id):
+        print(f"\n🔗 View in LangSmith: {url}")
+
+    print()
+
+
+def cmd_export(args: Namespace) -> None:
+    """Export a run to JSON."""
+    from yamlgraph.storage import YamlGraphDB, export_state
+
+    db = YamlGraphDB()
+    state = db.load_state(args.thread_id)
+
+    if not state:
+        print(f"❌ No run found with thread_id: {args.thread_id}")
+        return
+
+    filepath = export_state(state)
+    print(f"✅ Exported to: {filepath}")

yamlgraph/cli/deprecation.py

@@ -0,0 +1,92 @@
+"""Deprecation utilities for CLI commands.
+
+Provides DeprecationError exception and helpers for migrating
+old commands to the universal graph runner.
+
+Term 'backward compatibility' signals refactoring need per project guidelines.
+
+Example:
+    >>> from yamlgraph.cli.deprecation import DeprecationError, deprecated_command
+    >>>
+    >>> def cmd_old_command(args):
+    ...     # Signal this command needs refactoring
+    ...     deprecated_command("old", "graph run graphs/new.yaml --var x=y")
+    ...
+    >>> # Running raises:
+    >>> # DeprecationError: DEPRECATED: 'old' is deprecated.
+    >>> # Use 'graph run graphs/new.yaml --var x=y' instead.
+"""
+
+
+class DeprecationError(Exception):
+    """Raised when a deprecated command is used.
+
+    Signals "Refactor me" - deprecated commands should be removed.
+
+    Attributes:
+        old_command: The deprecated command being used
+        new_command: The replacement command to use instead
+    """
+
+    def __init__(self, old_command: str, new_command: str):
+        self.old_command = old_command
+        self.new_command = new_command
+        message = (
+            f"DEPRECATED: '{old_command}' is deprecated. Use '{new_command}' instead."
+        )
+        super().__init__(message)
+
+
+# Command mappings: old command -> graph path
+COMMAND_MAPPINGS = {
+    "route": "graphs/router-demo.yaml",
+    "refine": "graphs/reflexion-demo.yaml",
+    "git-report": "graphs/git-report.yaml",
+    "memory-demo": "graphs/memory-demo.yaml",
+}
+
+# Variable mappings: old command -> arg name -> var name
+ARG_MAPPINGS = {
+    "route": {"message": "message"},
+    "refine": {"topic": "topic"},
+    "git-report": {"query": "input"},
+    "memory-demo": {"input": "input"},
+}
+
+
+def get_replacement_command(old_command: str, args: dict[str, str]) -> str | None:
+    """Get the replacement graph run command.
+
+    Args:
+        old_command: The deprecated command name
+        args: Dict of argument values
+
+    Returns:
+        Replacement command string, or None if unknown command
+    """
+    graph_path = COMMAND_MAPPINGS.get(old_command)
+    if not graph_path:
+        return None
+
+    # Build --var arguments
+    var_args = []
+    arg_mapping = ARG_MAPPINGS.get(old_command, {})
+    for arg_name, var_name in arg_mapping.items():
+        if arg_name in args:
+            var_args.append(f"--var {var_name}={args[arg_name]}")
+
+    var_str = " ".join(var_args)
+    return f"graph run {graph_path} {var_str}".strip()
+
+
+def deprecated_command(old_command: str, new_command: str) -> None:
+    """Raise DeprecationError for a deprecated command.
+
+    Args:
+        old_command: The deprecated command being used
+        new_command: The replacement command suggestion
+
+    Raises:
+        DeprecationError: Always raised to signal deprecation
+    """
+    raise DeprecationError(old_command, new_command)