yamlgraph 0.3.9__py3-none-any.whl

examples/npc/run_encounter.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""Run a multi-turn encounter with multiple NPCs.
+
+This script demonstrates the map node feature for parallel NPC processing.
+Each turn, ALL NPCs perceive, decide, and act in response to DM input.
+
+Usage:
+    python examples/npc/run_encounter.py
+
+    # With pre-created NPCs
+    python examples/npc/run_encounter.py --npc-dir npcs/
+"""
+
+import argparse
+import uuid
+from pathlib import Path
+
+import yaml
+from langgraph.types import Command
+
+from yamlgraph.graph_loader import (
+    compile_graph,
+    get_checkpointer_for_graph,
+    load_graph_config,
+)
+
+
+# ANSI colors
+class C:
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    CYAN = "\033[36m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    MAGENTA = "\033[35m"
+    RED = "\033[31m"
+    RESET = "\033[0m"
+
+
+def load_npcs(npc_dir: str | None) -> list[dict]:
+    """Load NPC data from directory or use defaults."""
+    if npc_dir:
+        npc_path = Path(npc_dir)
+        if npc_path.exists():
+            npcs = []
+            for f in npc_path.glob("*.yaml"):
+                with open(f) as fp:
+                    data = yaml.safe_load(fp)
+                    identity = data.get("identity", {})
+                    personality = data.get("personality", {})
+                    behavior = data.get("behavior", {})
+                    # Build structured NPC dict
+                    npc = {
+                        "name": identity.get("name", f.stem),
+                        "appearance": identity.get("appearance", ""),
+                        "voice": identity.get("voice", ""),
+                        "race": identity.get("race", ""),
+                        "character_class": identity.get("character_class", ""),
+                        "personality": personality,  # Keep as dict
+                        "behavior": behavior,  # Keep as dict
+                        "goals": behavior.get("goals", []),  # Keep as list
+                    }
+                    npcs.append(npc)
+            if npcs:
+                print(f"{C.GREEN}✓ Loaded {len(npcs)} NPCs from {npc_dir}{C.RESET}")
+                return npcs
+
+    # Default NPCs for demo
+    return [
+        {
+            "name": "Thorin Ironfoot",
+            "appearance": "A stocky dwarf with burn scars and a copper beard",
+            "voice": "Gruff, low rumble",
+            "personality": {
+                "traits": ["Stoic", "Hardworking", "Practical"],
+                "ideals": ["Quality craftsmanship", "Honest trade"],
+                "flaws": ["Distrustful of magic", "Stubborn"],
+                "disposition": "neutral",
+            },
+            "behavior": {
+                "combat_style": "defensive",
+                "goals": ["Run a successful smithy", "Find an apprentice"],
+            },
+            "goals": ["Run a successful smithy", "Find an apprentice"],
+            "race": "Dwarf",
+            "character_class": "Blacksmith",
+        },
+        {
+            "name": "Lyra Whisperwind",
+            "appearance": "A lithe elf with silver hair and piercing blue eyes",
+            "voice": "Melodic, speaks in riddles",
+            "personality": {
+                "traits": ["Curious", "Mischievous", "Observant"],
+                "ideals": ["Truth", "Knowledge"],
+                "flaws": ["Overly secretive", "Distrustful"],
+                "disposition": "curious",
+            },
+            "behavior": {
+                "combat_style": "ranged",
+                "goals": ["Uncover hidden truths", "Protect the ancient grove"],
+            },
+            "goals": ["Uncover hidden truths", "Protect the ancient grove"],
+            "race": "Elf",
+            "character_class": "Ranger",
+        },
+        {
+            "name": "Marcus the Bold",
+            "appearance": "A burly human with a thick black beard and battle scars",
+            "voice": "Booming laugh, speaks loudly",
+            "personality": {
+                "traits": ["Jovial", "Brave", "Loyal"],
+                "ideals": ["Glory", "Protecting the weak"],
+                "flaws": ["Reckless", "Overconfident"],
+                "disposition": "friendly",
+            },
+            "behavior": {
+                "combat_style": "aggressive",
+                "goals": ["Find glory in battle", "Earn gold for his family"],
+            },
+            "goals": ["Find glory in battle", "Earn gold for his family"],
+            "race": "Human",
+            "character_class": "Fighter",
+        },
+    ]
+
+
+def run_encounter():
+    """Run the interactive multi-NPC encounter."""
+    parser = argparse.ArgumentParser(description="Multi-NPC Encounter")
+    parser.add_argument("--npc-dir", "-n", help="Directory with NPC YAML files")
+    parser.add_argument(
+        "--location", "-l", default="The Rusty Anchor tavern", help="Location name"
+    )
+    args = parser.parse_args()
+
+    print(f"\n{C.BOLD}{'=' * 60}{C.RESET}")
+    print(f"{C.BOLD}⚔️  YAMLGraph Multi-NPC Encounter{C.RESET}")
+    print(f"{C.BOLD}{'=' * 60}{C.RESET}\n")
+
+    # Load graph
+    config = load_graph_config("examples/npc/encounter-multi.yaml")
+    graph = compile_graph(config)
+    checkpointer = get_checkpointer_for_graph(config)
+    app = graph.compile(checkpointer=checkpointer)
+
+    # Session setup
+    thread_id = str(uuid.uuid4())
+    run_config = {"configurable": {"thread_id": thread_id}}
+
+    # Initial state
+    npcs = load_npcs(args.npc_dir)
+    initial_state = {
+        "npcs": npcs,
+        "location": args.location,
+        "location_description": "A dimly lit tavern with rough wooden tables and the smell of ale",
+        "turn_number": 1,
+        "encounter_history": [],
+        "perceptions": [],
+        "decisions": [],
+        "narrations": [],
+    }
+
+    print(f"{C.CYAN}📍 Location: {args.location}{C.RESET}")
+    print(f"{C.CYAN}🎭 NPCs present:{C.RESET}")
+    for npc in npcs:
+        print(
+            f"   - {C.BOLD}{npc['name']}{C.RESET} ({npc['race']} {npc['character_class']})"
+        )
+    print(f"\n{C.DIM}Type 'end' to finish the encounter, 'quit' to exit.{C.RESET}\n")
+
+    # Start the graph
+    result = app.invoke(initial_state, run_config)
+    turn = 1
+
+    while True:
+        # Get interrupt message
+        state = app.get_state(run_config)
+        next_nodes = state.next if hasattr(state, "next") else []
+
+        if not next_nodes:
+            print(f"\n{C.GREEN}✓ Encounter complete!{C.RESET}")
+            break
+
+        # Show prompt
+        print(f"\n{C.MAGENTA}{'─' * 50}{C.RESET}")
+        print(f"{C.YELLOW}🎲 Turn {turn} - What happens?{C.RESET}")
+
+        # Get user input
+        try:
+            dm_input = input(f"{C.CYAN}DM> {C.RESET}").strip()
+        except (EOFError, KeyboardInterrupt):
+            print(f"\n{C.YELLOW}Encounter ended by user.{C.RESET}")
+            break
+
+        if dm_input.lower() == "quit":
+            print(f"\n{C.YELLOW}Farewell, Dungeon Master!{C.RESET}")
+            break
+
+        if not dm_input:
+            print(f"{C.DIM}(Describe what happens in the scene){C.RESET}")
+            continue
+
+        # Resume with DM input
+        print(f"\n{C.DIM}Processing all NPCs...{C.RESET}")
+        result = app.invoke(Command(resume=dm_input), run_config)
+
+        # Show results
+        if result.get("turn_summary"):
+            print(f"\n{C.GREEN}📜 Turn Summary:{C.RESET}")
+            print(result["turn_summary"])
+
+        if result.get("scene_image"):
+            print(f"\n{C.CYAN}🖼️  Image saved: {result['scene_image']}{C.RESET}")
+
+        if dm_input.lower() == "end":
+            print(f"\n{C.GREEN}✓ Encounter ended!{C.RESET}")
+            # Show history
+            history = result.get("encounter_history", [])
+            if history:
+                print(f"\n{C.CYAN}📚 Encounter History:{C.RESET}")
+                for i, summary in enumerate(history, 1):
+                    print(f"\n{C.DIM}Turn {i}:{C.RESET}")
+                    print(summary[:300] + "..." if len(summary) > 300 else summary)
+            break
+
+        turn += 1
+
+
+if __name__ == "__main__":
+    run_encounter()

examples/shared/replicate_tool.py

@@ -0,0 +1,238 @@
+"""Replicate image generation tool for storyboard workflow.
+
+Supports multiple models:
+- z-image: Fast, good for realistic/photographic (default)
+- hidream: Better for cartoons, illustrations, stylized art
+- p-image-edit: Image-to-image editing for character consistency
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Model configurations
+MODELS = {
+    "z-image": {
+        "id": "prunaai/z-image-turbo",
+        "width": 1344,
+        "height": 768,
+        "params": {
+            "guidance_scale": 0,
+            "num_inference_steps": 8,
+        },
+    },
+    "hidream": {
+        "id": "prunaai/hidream-l1-fast:f67f0ec7ef9fe91b74e8a68d34efaa9145bec28675cb190cbff8a70f0490256e",
+        "resolution": "1360 \u00d7 768 (Landscape)",
+        "params": {
+            "model_type": "fast",
+            "speed_mode": "Juiced \U0001f525 (more speed)",
+        },
+    },
+}
+
+DEFAULT_MODEL = "z-image"
+
+# Check if replicate is available
+try:
+    import replicate
+
+    REPLICATE_AVAILABLE = True
+except ImportError:
+    REPLICATE_AVAILABLE = False
+    logger.warning("replicate package not installed. Run: pip install replicate")
+
+
+@dataclass
+class ImageResult:
+    """Result from image generation."""
+
+    success: bool
+    path: str | None = None
+    error: str | None = None
+
+
+def generate_image(
+    prompt: str,
+    output_path: str | Path,
+    model_name: str = DEFAULT_MODEL,
+) -> ImageResult:
+    """Generate an image using Replicate API.
+
+    Args:
+        prompt: Text prompt for image generation
+        output_path: Path to save the generated image
+        model_name: Model to use ('z-image' or 'hidream')
+
+    Returns:
+        ImageResult with success status and path or error
+    """
+    if not REPLICATE_AVAILABLE:
+        return ImageResult(success=False, error="replicate package not installed")
+
+    api_token = os.environ.get("REPLICATE_API_TOKEN")
+    if not api_token:
+        return ImageResult(
+            success=False, error="REPLICATE_API_TOKEN not set in environment"
+        )
+
+    # Get model config
+    model_config = MODELS.get(model_name, MODELS[DEFAULT_MODEL])
+    model_id = model_config["id"]
+
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        logger.info(f"🎨 Generating image with {model_name}: {prompt[:50]}...")
+
+        # Build input params based on model
+        if model_name == "hidream":
+            input_params = {
+                "prompt": prompt,
+                "seed": -1,
+                "resolution": model_config["resolution"],
+                "output_format": "png",
+                "output_quality": 80,
+                "disable_safety_checker": True,
+                **model_config["params"],
+            }
+        else:
+            # z-image and default
+            input_params = {
+                "prompt": prompt,
+                "width": model_config.get("width", 1344),
+                "height": model_config.get("height", 768),
+                "output_format": "png",
+                "output_quality": 80,
+                "disable_safety_checker": True,
+                **model_config.get("params", {}),
+            }
+
+        # Run the model
+        client = replicate.Client(api_token=api_token)
+        output = client.run(model_id, input=input_params)
+
+        # output is typically a URL or file-like object
+        image_url = output if isinstance(output, str) else str(output)
+
+        # Download the image
+        logger.info(f"📥 Downloading image to {output_path}")
+        response = httpx.get(image_url, timeout=60.0)
+        response.raise_for_status()
+
+        output_path.write_bytes(response.content)
+        logger.info(f"✓ Image saved: {output_path}")
+
+        return ImageResult(success=True, path=str(output_path))
+
+    except Exception as e:
+        logger.error(f"Image generation failed: {e}")
+        return ImageResult(success=False, error=str(e))
+
+
+def edit_image(
+    input_image: str | Path,
+    prompt: str,
+    output_path: str | Path,
+    aspect_ratio: str = "16:9",
+    turbo: bool = True,
+    magic: float | None = None,
+) -> ImageResult:
+    """Edit an image using Replicate p-image-edit model.
+
+    Uses the input image as base and applies the prompt as modifications.
+    Great for maintaining character consistency across panels.
+
+    Args:
+        input_image: Path to the source image
+        prompt: Edit instructions (what to change/add)
+        output_path: Path to save the edited image
+        aspect_ratio: Output aspect ratio (default 16:9)
+        turbo: Use turbo mode for faster generation
+        magic: Prompt strength 0-1 (lower = more original, higher = more prompt)
+
+    Returns:
+        ImageResult with success status and path or error
+    """
+    if not REPLICATE_AVAILABLE:
+        return ImageResult(success=False, error="replicate package not installed")
+
+    api_token = os.environ.get("REPLICATE_API_TOKEN")
+    if not api_token:
+        return ImageResult(
+            success=False, error="REPLICATE_API_TOKEN not set in environment"
+        )
+
+    input_image = Path(input_image)
+    if not input_image.exists():
+        return ImageResult(success=False, error=f"Input image not found: {input_image}")
+
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        logger.info(f"✏️ Editing image: {prompt[:50]}...")
+
+        client = replicate.Client(api_token=api_token)
+
+        with open(input_image, "rb") as f:
+            input_params = {
+                "turbo": turbo,
+                "images": [f],
+                "prompt": prompt,
+                "aspect_ratio": aspect_ratio,
+                "disable_safety_checker": True,
+            }
+            if magic is not None:
+                input_params["magic"] = magic
+
+            output = client.run(
+                "prunaai/p-image-edit",
+                input=input_params,
+            )
+
+        # Save the output
+        with open(output_path, "wb") as out:
+            out.write(output.read())
+
+        logger.info(f"✓ Edited image saved: {output_path}")
+        return ImageResult(success=True, path=str(output_path))
+
+    except Exception as e:
+        logger.error(f"Image editing failed: {e}")
+        return ImageResult(success=False, error=str(e))
+
+
+def generate_storyboard_images(
+    panel_prompts: list[str],
+    output_dir: str | Path,
+    prefix: str = "panel",
+) -> list[ImageResult]:
+    """Generate multiple images for a storyboard.
+
+    Args:
+        panel_prompts: List of prompts for each panel
+        output_dir: Directory to save images
+        prefix: Filename prefix
+
+    Returns:
+        List of ImageResult for each panel
+    """
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    results = []
+    for i, prompt in enumerate(panel_prompts, 1):
+        output_path = output_dir / f"{prefix}_{i}.png"
+        result = generate_image(prompt, output_path)
+        results.append(result)
+
+    return results

examples/storyboard/__init__.py

@@ -0,0 +1 @@
+"""Storyboard example - demonstrates Python node for image generation."""