yamlgraph 0.3.9__py3-none-any.whl

scripts/demo_async_executor.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""Async Executor Demo - Showcases async graph execution with interrupts.
+
+Demonstrates:
+- Async graph loading with load_and_compile_async()
+- Async execution with run_graph_async()
+- Interrupt handling and Command(resume=...) flow
+- Real-time user interaction
+
+Usage:
+    # Interactive mode (real LLM + user input)
+    python scripts/demo_async_executor.py --interactive
+
+    # Verification mode (mock inputs for CI)
+    python scripts/demo_async_executor.py --verify
+
+    # Custom graph
+    python scripts/demo_async_executor.py --graph graphs/my-graph.yaml
+"""
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+# Add project root to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from langgraph.types import Command
+
+from yamlgraph.executor_async import load_and_compile_async, run_graph_async
+
+
+def print_banner(title: str) -> None:
+    """Print a styled banner."""
+    width = 50
+    print("┌" + "─" * width + "┐")
+    print(f"│ {title:<{width-1}}│")
+    print("├" + "─" * width + "┤")
+
+
+def print_footer() -> None:
+    """Print footer."""
+    print("└" + "─" * 50 + "┘")
+
+
+def get_interrupt_message(result: dict) -> str:
+    """Extract message from interrupt payload."""
+    if "__interrupt__" not in result:
+        return ""
+    interrupt = result["__interrupt__"][0]
+    value = interrupt.value
+    if isinstance(value, dict):
+        return value.get("question") or value.get("prompt") or str(value)
+    return str(value)
+
+
+async def run_demo(
+    graph_path: str,
+    interactive: bool = False,
+    mock_inputs: list[str] | None = None,
+) -> dict:
+    """Run the async executor demo.
+
+    Args:
+        graph_path: Path to YAML graph definition
+        interactive: If True, prompt for real user input
+        mock_inputs: List of mock inputs for verification mode
+
+    Returns:
+        Final state dict
+    """
+    mock_inputs = mock_inputs or ["TestUser", "Python"]
+    mock_index = 0
+
+    print_banner("🚀 Async Executor Demo")
+    print(f"│ Graph: {graph_path:<41}│")
+    print(f"│ Mode: {'interactive' if interactive else 'verify':<42}│")
+    print("│" + " " * 50 + "│")
+
+    # Load and compile
+    print("│ Loading graph...                                │")
+    try:
+        app = await load_and_compile_async(graph_path)
+        print("│ ✅ Compiled with memory checkpointer            │")
+    except FileNotFoundError:
+        print(f"│ ❌ Graph not found: {graph_path:<28}│")
+        print_footer()
+        return {"error": "Graph not found"}
+
+    print("│" + " " * 50 + "│")
+
+    # Config with thread_id for checkpointer
+    config = {"configurable": {"thread_id": "demo-async-001"}}
+
+    # Initial run
+    print("│ Running graph async...                          │")
+    result = await run_graph_async(app, {"input": "start"}, config)
+
+    # Show welcome if present
+    if welcome := result.get("welcome_message"):
+        preview = welcome[:40] + "..." if len(welcome) > 40 else welcome
+        print(f"│ 💬 Welcome: \"{preview}\"│")
+
+    # Interrupt loop
+    interrupt_count = 0
+    while "__interrupt__" in result:
+        interrupt_count += 1
+        message = get_interrupt_message(result)
+        print("│" + " " * 50 + "│")
+        print(f"│ ⏸️  INTERRUPT #{interrupt_count}: {message:<30}│")
+
+        # Get input
+        if interactive:
+            print("│" + " " * 50 + "│")
+            user_input = input("│ > ")
+        else:
+            user_input = mock_inputs[mock_index] if mock_index < len(mock_inputs) else "default"
+            mock_index += 1
+            print(f"│ > {user_input:<47}│")
+
+        # Resume
+        print("│" + " " * 50 + "│")
+        print("│ Resuming...                                     │")
+        result = await run_graph_async(app, Command(resume=user_input), config)
+
+    # Complete
+    print("│" + " " * 50 + "│")
+    print("│ ✅ Complete!                                     │")
+
+    # Show final response
+    response = result.get("greeting") or result.get("response") or result.get("output")
+    if response:
+        # Truncate for display
+        preview = response[:38] + "..." if len(response) > 38 else response
+        print(f"│ 📝 Response: \"{preview}\"│")
+
+    print_footer()
+
+    # Verification output
+    if not interactive:
+        print("\n📊 Final State:")
+        for key, value in result.items():
+            if not key.startswith("_") and value is not None:
+                val_str = str(value)[:50]
+                print(f"  {key}: {val_str}")
+
+    return result
+
+
+async def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(description="Async Executor Demo")
+    parser.add_argument(
+        "--graph",
+        default="graphs/interview-demo.yaml",
+        help="Path to YAML graph definition",
+    )
+    parser.add_argument(
+        "--interactive",
+        action="store_true",
+        help="Enable interactive mode with real user input",
+    )
+    parser.add_argument(
+        "--verify",
+        action="store_true",
+        help="Run in verification mode with mock inputs",
+    )
+    parser.add_argument(
+        "--inputs",
+        nargs="*",
+        default=["Alice", "async programming"],
+        help="Mock inputs for verification mode",
+    )
+    args = parser.parse_args()
+
+    # Verify mode is default if neither specified
+    interactive = args.interactive and not args.verify
+
+    result = await run_demo(
+        graph_path=args.graph,
+        interactive=interactive,
+        mock_inputs=args.inputs,
+    )
+
+    # Exit with error if graph failed
+    if "error" in result:
+        sys.exit(1)
+
+    # Verify expected state in verify mode
+    if args.verify:
+        print("\n🔍 Verification:")
+        checks = [
+            ("user_name", result.get("user_name")),
+            ("user_topic", result.get("user_topic")),
+            ("greeting", result.get("greeting")),
+        ]
+        all_pass = True
+        for field, value in checks:
+            status = "✅" if value else "❌"
+            print(f"  {status} {field}: {'present' if value else 'MISSING'}")
+            if not value:
+                all_pass = False
+
+        if not all_pass:
+            print("\n❌ Verification FAILED")
+            sys.exit(1)
+        print("\n✅ Verification PASSED")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

scripts/demo_interview_e2e.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""End-to-end test for interrupt node demo.
+
+This script tests the full interrupt/resume flow:
+1. Graph pauses at first interrupt (ask_name)
+2. Resume with "Alice"
+3. Graph pauses at second interrupt (ask_topic)
+4. Resume with "Python"
+5. LLM generates personalized greeting
+
+Can run as:
+- Automated test: python scripts/demo_interview_e2e.py
+- Interactive mode: python scripts/demo_interview_e2e.py --interactive
+"""
+
+import argparse
+import sys
+import uuid
+
+from langgraph.types import Command
+
+from yamlgraph.graph_loader import (
+    compile_graph,
+    get_checkpointer_for_graph,
+    load_graph_config,
+)
+
+
+def run_demo(interactive: bool = False) -> dict:
+    """Run the interview demo.
+
+    Args:
+        interactive: If True, prompt for user input. Otherwise use test values.
+
+    Returns:
+        Final state dict with greeting
+    """
+    print("\n" + "=" * 50)
+    print("🎤 YAMLGraph Interview Demo - Human-in-the-Loop")
+    print("=" * 50 + "\n")
+
+    # Load and compile graph
+    config = load_graph_config("graphs/interview-demo.yaml")
+    graph = compile_graph(config)
+    checkpointer = get_checkpointer_for_graph(config)
+    app = graph.compile(checkpointer=checkpointer)
+
+    # Generate unique thread ID
+    thread_id = str(uuid.uuid4())
+    run_config = {"configurable": {"thread_id": thread_id}}
+
+    print(f"Thread ID: {thread_id[:8]}...")
+    print()
+
+    # First invoke - LLM generates welcome, then hits first interrupt
+    result = app.invoke({}, run_config)
+    interrupt = result.get("__interrupt__")
+
+    if not interrupt:
+        raise RuntimeError("Expected interrupt at ask_name node")
+
+    # Show the LLM-generated welcome message
+    welcome = result.get("welcome_message", "")
+    if welcome:
+        print(f"🤖 {welcome}")
+        print()
+
+    question1 = interrupt[0].value
+    print(f"💬 {question1}")
+
+    if interactive:
+        answer1 = input("   Your answer: ").strip()
+    else:
+        answer1 = "Alice"
+        print(f"   Your answer: {answer1}")
+
+    print()
+
+    # Resume with first answer - hits second interrupt
+    result = app.invoke(Command(resume=answer1), run_config)
+    interrupt = result.get("__interrupt__")
+
+    if not interrupt:
+        raise RuntimeError("Expected interrupt at ask_topic node")
+
+    question2 = interrupt[0].value
+    print(f"💬 {question2}")
+
+    if interactive:
+        answer2 = input("   Your answer: ").strip()
+    else:
+        answer2 = "Python"
+        print(f"   Your answer: {answer2}")
+
+    print()
+
+    # Resume with second answer - completes graph
+    result = app.invoke(Command(resume=answer2), run_config)
+
+    # Verify no more interrupts
+    if result.get("__interrupt__"):
+        raise RuntimeError("Unexpected interrupt after ask_topic")
+
+    # Display result
+    print("-" * 50)
+    print("✨ Final Response:")
+    print("-" * 50)
+
+    greeting = result.get("greeting", "")
+    if greeting:
+        print(greeting)
+    else:
+        print("(No greeting generated)")
+
+    print()
+    print("=" * 50)
+    print("Demo complete!")
+    print("=" * 50 + "\n")
+
+    return result
+
+
+def verify_result(result: dict) -> bool:
+    """Verify the demo produced expected output.
+
+    Args:
+        result: Final state dict
+
+    Returns:
+        True if verification passed
+    """
+    errors = []
+
+    # Check state contains expected keys
+    if "user_name" not in result:
+        errors.append("Missing 'user_name' in state")
+    elif result["user_name"] != "Alice":
+        errors.append(f"Expected user_name='Alice', got '{result['user_name']}'")
+
+    if "user_topic" not in result:
+        errors.append("Missing 'user_topic' in state")
+    elif result["user_topic"] != "Python":
+        errors.append(f"Expected user_topic='Python', got '{result['user_topic']}'")
+
+    if "greeting" not in result:
+        errors.append("Missing 'greeting' in state")
+    elif not result["greeting"]:
+        errors.append("Greeting is empty")
+
+    # Check greeting mentions the user and topic
+    greeting = str(result.get("greeting", "")).lower()
+    if "alice" not in greeting:
+        errors.append("Greeting doesn't mention 'Alice'")
+    if "python" not in greeting:
+        errors.append("Greeting doesn't mention 'Python'")
+
+    if errors:
+        print("\n❌ Verification FAILED:")
+        for error in errors:
+            print(f"   - {error}")
+        return False
+
+    print("\n✅ Verification PASSED:")
+    print("   - State contains user_name='Alice'")
+    print("   - State contains user_topic='Python'")
+    print("   - Greeting mentions both user and topic")
+    return True
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(description="Interview demo E2E test")
+    parser.add_argument(
+        "--interactive",
+        "-i",
+        action="store_true",
+        help="Run in interactive mode (prompt for input)",
+    )
+    parser.add_argument(
+        "--verify",
+        "-v",
+        action="store_true",
+        help="Verify output after demo",
+    )
+    args = parser.parse_args()
+
+    try:
+        result = run_demo(interactive=args.interactive)
+
+        if args.verify or not args.interactive:
+            success = verify_result(result)
+            sys.exit(0 if success else 1)
+
+    except Exception as e:
+        print(f"\n❌ Demo failed: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

scripts/demo_streaming.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Streaming Demo - Showcases token-by-token LLM output.
+
+Demonstrates:
+- execute_prompt_streaming() async generator
+- Real-time token output to terminal
+- Collecting streamed tokens
+
+Usage:
+    # Interactive streaming
+    python scripts/demo_streaming.py
+
+    # With custom prompt
+    python scripts/demo_streaming.py --prompt "Tell me a short story about a robot"
+
+    # Verification mode (no LLM, mock output)
+    python scripts/demo_streaming.py --verify
+"""
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+# Add project root to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from yamlgraph.executor_async import execute_prompt_streaming
+
+
+def print_banner(title: str) -> None:
+    """Print a styled banner."""
+    width = 50
+    print("┌" + "─" * width + "┐")
+    print(f"│ {title:<{width-1}}│")
+    print("├" + "─" * width + "┤")
+
+
+def print_footer() -> None:
+    """Print footer."""
+    print("└" + "─" * 50 + "┘")
+
+
+async def run_streaming_demo(
+    user_prompt: str,
+    verify: bool = False,
+) -> str:
+    """Run the streaming demo.
+
+    Args:
+        user_prompt: What to ask the LLM
+        verify: If True, skip actual LLM call
+
+    Returns:
+        Full collected response
+    """
+    print_banner("🌊 Streaming Demo")
+    print(f"│ Prompt: {user_prompt[:40]:<41}│")
+    print("│" + " " * 50 + "│")
+
+    if verify:
+        # Mock streaming for verification
+        print("│ [Verify mode - mock streaming]                  │")
+        print("│" + " " * 50 + "│")
+        print("│ Response:                                        │")
+        print("│ ", end="")
+
+        mock_response = "Hello! This is a mock streaming response for testing purposes."
+        for char in mock_response:
+            print(char, end="", flush=True)
+            await asyncio.sleep(0.02)
+
+        print()
+        print("│" + " " * 50 + "│")
+        print_footer()
+        return mock_response
+
+    # Real streaming from LLM
+    print("│ Streaming response:                              │")
+    print("│" + " " * 50 + "│")
+
+    tokens_collected = []
+
+    # Create a simple prompt YAML on the fly by using greet prompt
+    # In real usage, you'd have a prompt file
+    try:
+        async for token in execute_prompt_streaming(
+            "greet",
+            variables={"name": "streaming demo user", "style": user_prompt},
+            provider="mistral",
+        ):
+            print(token, end="", flush=True)
+            tokens_collected.append(token)
+    except Exception as e:
+        print(f"\n│ ❌ Error: {e!s:.40}│")
+        print_footer()
+        return ""
+
+    full_response = "".join(tokens_collected)
+
+    print()
+    print("│" + " " * 50 + "│")
+    print(f"│ ✅ Received {len(tokens_collected)} chunks, {len(full_response)} chars│")
+    print_footer()
+
+    return full_response
+
+
+async def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(description="Streaming Demo")
+    parser.add_argument(
+        "--prompt",
+        default="casual and friendly",
+        help="Style for the greeting prompt",
+    )
+    parser.add_argument(
+        "--verify",
+        action="store_true",
+        help="Run in verification mode (mock output)",
+    )
+    args = parser.parse_args()
+
+    result = await run_streaming_demo(
+        user_prompt=args.prompt,
+        verify=args.verify,
+    )
+
+    if args.verify:
+        # Verification check
+        print("\n🔍 Verification:")
+        if len(result) > 0:
+            print("  ✅ Streaming produced output")
+        else:
+            print("  ❌ No output received")
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

scripts/run_interview_demo.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Demo script for human-in-the-loop interrupt nodes.
+
+This script demonstrates the interrupt feature:
+1. Graph pauses at interrupt nodes
+2. User provides input via terminal
+3. Graph resumes with user's response
+
+Usage:
+    python scripts/run_interview_demo.py
+"""
+
+import uuid
+
+from langgraph.types import Command
+
+from yamlgraph.graph_loader import (
+    compile_graph,
+    get_checkpointer_for_graph,
+    load_graph_config,
+)
+
+
+def run_interview():
+    """Run the interactive interview demo."""
+    print("\n" + "=" * 50)
+    print("🎤 YAMLGraph Interview Demo - Human-in-the-Loop")
+    print("=" * 50 + "\n")
+
+    # Load and compile graph
+    config = load_graph_config("graphs/interview-demo.yaml")
+    graph = compile_graph(config)
+
+    # Get checkpointer (required for interrupts)
+    checkpointer = get_checkpointer_for_graph(config)
+
+    # Compile with checkpointer
+    app = graph.compile(checkpointer=checkpointer)
+
+    # Generate unique thread ID for this session
+    thread_id = str(uuid.uuid4())
+    run_config = {"configurable": {"thread_id": thread_id}}
+
+    print("Starting interview...\n")
+
+    # Initial invocation - will hit first interrupt
+    state = {}
+    result = app.invoke(state, run_config)
+
+    # Loop through interrupts
+    while True:
+        # Check for interrupt
+        interrupt_info = result.get("__interrupt__")
+
+        if interrupt_info:
+            # Extract the interrupt payload (question)
+            payload = interrupt_info[0].value if interrupt_info else "Input needed:"
+            print(f"\n💬 {payload}")
+
+            # Get user input
+            user_response = input("   Your answer: ").strip()
+
+            if user_response.lower() in ("quit", "exit", "q"):
+                print("\n👋 Goodbye!")
+                return
+
+            # Resume with user's response
+            result = app.invoke(Command(resume=user_response), run_config)
+        else:
+            # No more interrupts - we're done
+            break
+
+    # Display final result
+    print("\n" + "-" * 50)
+    print("✨ Final Response:")
+    print("-" * 50)
+
+    greeting = result.get("greeting")
+    if greeting:
+        # Handle both string and Pydantic model responses
+        if hasattr(greeting, "content"):
+            print(greeting.content)
+        elif isinstance(greeting, str):
+            print(greeting)
+        else:
+            print(greeting)
+
+    print("\n" + "=" * 50)
+    print("Demo complete!")
+    print("=" * 50 + "\n")
+
+
+if __name__ == "__main__":
+    run_interview()

scripts/test_interrupt_fix.py

@@ -0,0 +1,26 @@
+"""Test FR-006: interrupt_output_mapping with subgraph."""
+from pathlib import Path
+from langgraph.checkpoint.memory import MemorySaver
+
+from yamlgraph.graph_loader import load_graph_config, compile_graph
+
+print("=== Testing FR-006: interrupt_output_mapping ===")
+parent_path = Path("graphs/interrupt-parent.yaml")
+config = load_graph_config(parent_path)
+state_graph = compile_graph(config)
+checkpointer = MemorySaver()
+parent_app = state_graph.compile(checkpointer=checkpointer)
+
+thread_config = {"configurable": {"thread_id": "test-fr006"}}
+
+result = parent_app.invoke({"user_input": "hello"}, thread_config)
+print("Parent result keys:", result.keys())
+print()
+print("child_phase:", result.get("child_phase"))
+print("child_data:", result.get("child_data"))
+print("__interrupt__:", "__interrupt__" in result)
+print()
+if "child_phase" in result and "child_data" in result:
+    print("✅ FR-006 SUCCESS: Child state mapped to parent!")
+else:
+    print("❌ FR-006 FAILED: Child state not in result")

tests/__init__.py

@@ -0,0 +1 @@
+"""Test suite for yamlgraph."""