yamlgraph 0.1.1__py3-none-any.whl

examples/__init__.py

@@ -0,0 +1 @@
+"""Examples package - sample projects demonstrating framework features."""

examples/storyboard/__init__.py

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

examples/storyboard/generate_videos.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+"""Generate video clips from consecutive image pairs.
+
+Takes a folder of images, sorts alphabetically, and generates
+video clips for each consecutive pair (1→2, 2→3, 3→4, etc.)
+
+Usage:
+    python examples/storyboard/generate_videos.py outputs/storyboard/20260117_112419/animated
+
+Options:
+    --pattern GLOB     File pattern to match (default: *.png)
+    --prompt TEXT      Prompt for video generation
+    --fps INT          Frames per second (default: 16)
+    --frames INT       Number of frames (default: 81)
+    --resolution STR   Resolution: 480p, 720p (default: 480p)
+    --dry-run          Show what would be generated without running
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import subprocess
+import sys
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+logger = logging.getLogger(__name__)
+
+# Check if replicate is available
+try:
+    import replicate
+
+    REPLICATE_AVAILABLE = True
+except ImportError:
+    REPLICATE_AVAILABLE = False
+
+
+def generate_video_clip(
+    first_image: Path,
+    last_image: Path,
+    output_path: Path,
+    prompt: str = "",
+    fps: int = 16,
+    num_frames: int = 81,
+    resolution: str = "480p",
+) -> bool:
+    """Generate a video clip between two images.
+
+    Args:
+        first_image: Starting frame
+        last_image: Ending frame
+        output_path: Where to save the video
+        prompt: Optional prompt describing the motion
+        fps: Frames per second
+        num_frames: Total number of frames
+        resolution: Output resolution (480p, 720p)
+
+    Returns:
+        True if successful
+    """
+    if not REPLICATE_AVAILABLE:
+        logger.error("replicate package not installed. Run: pip install replicate")
+        return False
+
+    api_token = os.environ.get("REPLICATE_API_TOKEN")
+    if not api_token:
+        logger.error("REPLICATE_API_TOKEN not set")
+        return False
+
+    try:
+        logger.info(f"🎬 Generating: {first_image.name} → {last_image.name}")
+
+        client = replicate.Client(api_token=api_token)
+
+        with open(first_image, "rb") as f1, open(last_image, "rb") as f2:
+            output = client.run(
+                "wan-video/wan-2.2-i2v-fast",
+                input={
+                    "image": f1,
+                    "last_image": f2,
+                    "prompt": prompt or "Smooth camera motion, cinematic transition",
+                    "go_fast": True,
+                    "num_frames": num_frames,
+                    "resolution": resolution,
+                    "sample_shift": 12,
+                    "frames_per_second": fps,
+                    "interpolate_output": False,
+                    "lora_scale_transformer": 1,
+                    "lora_scale_transformer_2": 1,
+                },
+            )
+
+        # Save the video
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, "wb") as f:
+            f.write(output.read())
+
+        logger.info(f"✓ Saved: {output_path}")
+        return True
+
+    except Exception as e:
+        logger.error(f"✗ Failed: {e}")
+        return False
+
+
+def get_prompt_for_pair(
+    metadata: dict | None,
+    img1_name: str,
+    img2_name: str,
+) -> str:
+    """Try to extract relevant prompt from metadata."""
+    if not metadata:
+        return ""
+
+    # Parse panel number from filename
+    # e.g., "panel_1_first_frame.png" → panel 1
+    for panel in metadata.get("panels", []):
+        prompts = panel.get("prompts", {})
+
+        # If transitioning within same panel, use the prompts
+        if f"panel_{panel['index']}" in img1_name:
+            if "first_frame" in img1_name and "original" in img2_name:
+                return prompts.get("original", "")
+            if "original" in img1_name and "last_frame" in img2_name:
+                return prompts.get("last_frame", "")
+            if "first_frame" in img1_name and "last_frame" in img2_name:
+                return prompts.get("last_frame", "")
+
+    return ""
+
+
+def concatenate_videos(video_paths: list[Path], output_path: Path) -> bool:
+    """Concatenate multiple video clips into one using ffmpeg.
+
+    Args:
+        video_paths: List of video files in order
+        output_path: Output file path
+
+    Returns:
+        True if successful
+    """
+    if not video_paths:
+        return False
+
+    # Create concat file list in the same directory
+    concat_file = output_path.parent / "concat_list.txt"
+    with open(concat_file, "w") as f:
+        for video in video_paths:
+            f.write(f"file '{video.name}'\n")
+
+    try:
+        result = subprocess.run(
+            [
+                "ffmpeg",
+                "-y",  # Overwrite
+                "-f",
+                "concat",
+                "-safe",
+                "0",
+                "-i",
+                "concat_list.txt",  # Use relative name since cwd is set
+                "-c",
+                "copy",
+                output_path.name,  # Use relative name
+            ],
+            capture_output=True,
+            text=True,
+            cwd=str(output_path.parent),  # Ensure string path
+        )
+
+        concat_file.unlink()  # Clean up
+
+        if result.returncode != 0:
+            logger.error(f"ffmpeg error: {result.stderr}")
+            return False
+
+        return True
+
+    except FileNotFoundError:
+        logger.error("ffmpeg not found. Install with: brew install ffmpeg")
+        return False
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate video clips from consecutive image pairs"
+    )
+    parser.add_argument(
+        "folder",
+        type=Path,
+        help="Folder containing images",
+    )
+    parser.add_argument(
+        "--pattern",
+        default="*.png",
+        help="Glob pattern for images (default: *.png)",
+    )
+    parser.add_argument(
+        "--prompt",
+        default="",
+        help="Prompt for all video generations",
+    )
+    parser.add_argument(
+        "--fps",
+        type=int,
+        default=16,
+        help="Frames per second (default: 16)",
+    )
+    parser.add_argument(
+        "--frames",
+        type=int,
+        default=81,
+        help="Number of frames (default: 81)",
+    )
+    parser.add_argument(
+        "--resolution",
+        default="480p",
+        choices=["480p", "720p"],
+        help="Output resolution (default: 480p)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be generated without running",
+    )
+    args = parser.parse_args()
+
+    folder = args.folder
+    if not folder.exists():
+        logger.error(f"❌ Folder not found: {folder}")
+        sys.exit(1)
+
+    # Find images (alphabetically sorted)
+    images = sorted(folder.glob(args.pattern))
+    if not images:
+        logger.error(f"❌ No images matching '{args.pattern}' in {folder}")
+        sys.exit(1)
+
+    # Filter out non-frame images
+    images = [img for img in images if img.name not in ("character.png",)]
+
+    logger.info(f"📁 Found {len(images)} images in {folder} (alphabetical order)")
+    for img in images:
+        logger.info(f"   {img.name}")
+
+    # Load metadata if available
+    metadata_path = folder / "animated_character_story.json"
+    metadata = None
+    if metadata_path.exists():
+        metadata = json.loads(metadata_path.read_text())
+        logger.info(f"📝 Loaded metadata from {metadata_path.name}")
+
+    # Create output folder
+    videos_folder = folder / "videos"
+    if not args.dry_run:
+        videos_folder.mkdir(exist_ok=True)
+
+    # Generate videos for consecutive pairs
+    pairs = list(zip(images[:-1], images[1:]))
+    logger.info(f"\n🎬 Generating {len(pairs)} video clips (parallel):")
+
+    # Build list of jobs
+    jobs = []
+    for i, (img1, img2) in enumerate(pairs, 1):
+        output_name = f"clip_{i:02d}_{img1.stem}_to_{img2.stem}.mp4"
+        output_path = videos_folder / output_name
+        prompt = args.prompt or get_prompt_for_pair(metadata, img1.name, img2.name)
+
+        logger.info(f"   [{i}] {img1.name} → {img2.name}")
+        if prompt:
+            logger.info(f"       Prompt: {prompt[:50]}...")
+
+        jobs.append(
+            {
+                "index": i,
+                "img1": img1,
+                "img2": img2,
+                "output_path": output_path,
+                "prompt": prompt,
+            }
+        )
+
+    if args.dry_run:
+        for job in jobs:
+            logger.info(f"   Would save: {job['output_path']}")
+        sys.exit(0)
+
+    # Parallel generation
+    generated_clips = []
+
+    def run_job(job):
+        success = generate_video_clip(
+            first_image=job["img1"],
+            last_image=job["img2"],
+            output_path=job["output_path"],
+            prompt=job["prompt"],
+            fps=args.fps,
+            num_frames=args.frames,
+            resolution=args.resolution,
+        )
+        return job["index"], job["output_path"], success
+
+    with ThreadPoolExecutor(max_workers=4) as executor:
+        futures = {executor.submit(run_job, job): job for job in jobs}
+
+        for future in as_completed(futures):
+            idx, output_path, success = future.result()
+            if success:
+                generated_clips.append((idx, output_path))
+
+    # Sort by index and collect paths
+    generated_clips.sort(key=lambda x: x[0])
+    clip_paths = [path for _, path in generated_clips]
+
+    logger.info(f"\n✅ Generated {len(clip_paths)}/{len(pairs)} video clips")
+
+    # Concatenate into final video
+    if len(clip_paths) > 1:
+        final_output = videos_folder / "final_combined.mp4"
+        logger.info(f"\n🎞️  Concatenating clips into {final_output.name}...")
+
+        if concatenate_videos(clip_paths, final_output):
+            logger.info(f"✅ Final video: {final_output}")
+        else:
+            logger.warning("⚠️  Concatenation failed, individual clips available")
+
+    logger.info(f"📂 Output: {videos_folder}")
+
+
+if __name__ == "__main__":
+    main()

examples/storyboard/nodes/__init__.py

@@ -0,0 +1,10 @@
+"""Storyboard nodes package."""
+
+from .image_node import generate_images_node
+from .replicate_tool import generate_image, generate_storyboard_images
+
+__all__ = [
+    "generate_images_node",
+    "generate_image",
+    "generate_storyboard_images",
+]

examples/storyboard/nodes/animated_character_node.py

@@ -0,0 +1,248 @@
+"""Animated character storyboard node.
+
+Workflow:
+1. If no reference_image provided, generate character.png from character_prompt
+2. For each panel:
+   - Original: img2img from character/reference (magic=0.25 for consistency)
+   - First frame: img2img from original
+   - Last frame: img2img from original
+
+This ensures character consistency across all panels.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from .replicate_tool import edit_image, generate_image
+
+logger = logging.getLogger(__name__)
+
+GraphState = dict[str, Any]
+
+
+def generate_animated_character_images(state: GraphState) -> dict:
+    """Generate animated character-consistent storyboard images.
+
+    Workflow:
+    1. If no reference_image: generate character.png from character_prompt
+    2. For each panel:
+       - Original: img2img from character/reference
+       - First frame: img2img from original
+       - Last frame: img2img from original
+
+    Args:
+        state: Graph state with 'story', 'animated_panels', and optional 'reference_image'
+
+    Returns:
+        State update with 'images', 'character_image', 'output_dir'
+    """
+    story = state.get("story")
+    animated_panels = state.get("animated_panels", [])
+
+    if not story:
+        logger.error("No story in state")
+        return {
+            "current_step": "generate_animated_character_images",
+            "images": [],
+            "error": "No story in state",
+        }
+
+    # Handle Pydantic model or dict
+    if hasattr(story, "model_dump"):
+        story_dict = story.model_dump()
+    elif isinstance(story, dict):
+        story_dict = story
+    else:
+        story_dict = {}
+
+    character_prompt = story_dict.get("character_prompt", "")
+    if not character_prompt:
+        logger.error("No character_prompt in story")
+        return {
+            "current_step": "generate_animated_character_images",
+            "images": [],
+            "error": "No character_prompt provided",
+        }
+
+    if not animated_panels:
+        logger.error("No animated_panels in state")
+        return {
+            "current_step": "generate_animated_character_images",
+            "images": [],
+            "error": "No animated panels to generate",
+        }
+
+    # Sort by _map_index if present
+    if animated_panels and isinstance(animated_panels[0], dict):
+        animated_panels = sorted(
+            animated_panels,
+            key=lambda x: x.get("_map_index", 0) if isinstance(x, dict) else 0,
+        )
+
+    # Create output directory
+    thread_id = state.get("thread_id", datetime.now().strftime("%Y%m%d_%H%M%S"))
+    output_dir = Path("outputs/storyboard") / thread_id / "animated"
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    model_name = state.get("model", "z-image")
+    reference_image = state.get("reference_image")
+    reference_path = Path(reference_image) if reference_image else None
+
+    logger.info(f"🎬 Generating animated character storyboard in {output_dir}")
+    logger.info(f"🖼️  Using model: {model_name}")
+
+    # If no reference provided, generate a character image first
+    if not reference_path:
+        character_path = output_dir / "character.png"
+        logger.info("🎭 Generating character base image...")
+        char_result = generate_image(
+            prompt=character_prompt,
+            output_path=character_path,
+            model_name=model_name,
+        )
+        if char_result.success:
+            reference_path = character_path
+            logger.info(f"✓ Character image created: {character_path}")
+        else:
+            logger.error(f"Character generation failed: {char_result.error}")
+            return {
+                "current_step": "generate_animated_character_images",
+                "images": [],
+                "error": f"Character generation failed: {char_result.error}",
+            }
+    else:
+        logger.info(f"🎭 Using reference image: {reference_path}")
+
+    # Generate frames for each panel
+    # Each panel: img2img from character/reference, then img2img for first/last
+    total_images = len(animated_panels) * 3
+    logger.info(
+        f"🎞️  Generating {total_images} frames ({len(animated_panels)} panels × 3)"
+    )
+
+    all_results: list[dict] = []
+
+    for panel_idx, panel in enumerate(animated_panels, 1):
+        if hasattr(panel, "model_dump"):
+            panel_dict = panel.model_dump()
+        elif isinstance(panel, dict):
+            panel_dict = panel
+        else:
+            logger.warning(f"Panel {panel_idx} has unexpected type: {type(panel)}")
+            continue
+
+        panel_result = {"panel": panel_idx, "frames": {}}
+
+        # Step 1: Generate ORIGINAL image via img2img from character/reference
+        original_prompt = panel_dict.get("original", "")
+        if not original_prompt:
+            logger.warning(f"Panel {panel_idx} missing original prompt")
+            continue
+
+        # Combine character + scene for consistency
+        full_original_prompt = f"{character_prompt}, {original_prompt}"
+        original_path = output_dir / f"panel_{panel_idx}_original.png"
+        logger.info(f"📸 Panel {panel_idx} original: {original_prompt[:50]}...")
+
+        # Use img2img from reference for character consistency
+        # magic=0.25 preserves more of the reference (lower = more original)
+        original_result = edit_image(
+            input_image=reference_path,
+            prompt=full_original_prompt,
+            output_path=original_path,
+            aspect_ratio="16:9",
+            magic=0.25,
+        )
+
+        if not original_result.success:
+            logger.error(f"Panel {panel_idx} original failed: {original_result.error}")
+            continue
+
+        panel_result["frames"]["original"] = str(original_path)
+        logger.info(f"✓ Panel {panel_idx} original created")
+
+        # Step 2: Generate first_frame via img2img from original
+        first_prompt = panel_dict.get("first_frame", "")
+        if first_prompt:
+            first_path = output_dir / f"panel_{panel_idx}_first_frame.png"
+            logger.info(f"📸 Panel {panel_idx} first_frame: {first_prompt[:50]}...")
+
+            first_result = edit_image(
+                input_image=original_path,
+                prompt=first_prompt,
+                output_path=first_path,
+                aspect_ratio="16:9",
+            )
+
+            if first_result.success and first_result.path:
+                panel_result["frames"]["first_frame"] = first_result.path
+            else:
+                logger.error(
+                    f"Panel {panel_idx} first_frame failed: {first_result.error}"
+                )
+                panel_result["frames"]["first_frame"] = None
+
+        # Step 3: Generate last_frame via img2img from original
+        last_prompt = panel_dict.get("last_frame", "")
+        if last_prompt:
+            last_path = output_dir / f"panel_{panel_idx}_last_frame.png"
+            logger.info(f"📸 Panel {panel_idx} last_frame: {last_prompt[:50]}...")
+
+            last_result = edit_image(
+                input_image=original_path,
+                prompt=last_prompt,
+                output_path=last_path,
+                aspect_ratio="16:9",
+            )
+
+            if last_result.success and last_result.path:
+                panel_result["frames"]["last_frame"] = last_result.path
+            else:
+                logger.error(
+                    f"Panel {panel_idx} last_frame failed: {last_result.error}"
+                )
+                panel_result["frames"]["last_frame"] = None
+
+        all_results.append(panel_result)
+
+    # Save metadata
+    frame_keys = ["first_frame", "original", "last_frame"]
+    metadata_path = output_dir / "animated_character_story.json"
+    metadata = {
+        "concept": state.get("concept", ""),
+        "title": story_dict.get("title", ""),
+        "narrative": story_dict.get("narrative", ""),
+        "character_prompt": character_prompt,
+        "reference_image": str(reference_path) if reference_path else None,
+        "panels": [
+            {
+                "index": r["panel"],
+                "frames": r["frames"],
+                "prompts": {
+                    k: animated_panels[r["panel"] - 1].get(k, "")
+                    if isinstance(animated_panels[r["panel"] - 1], dict)
+                    else ""
+                    for k in frame_keys
+                },
+            }
+            for r in all_results
+        ],
+        "generated_at": datetime.now().isoformat(),
+    }
+    metadata_path.write_text(json.dumps(metadata, indent=2))
+    logger.info(f"📝 Metadata saved: {metadata_path}")
+
+    success_count = sum(1 for r in all_results for path in r["frames"].values() if path)
+    logger.info(f"✅ Generated {success_count}/{total_images} images")
+
+    return {
+        "current_step": "generate_animated_character_images",
+        "character_image": str(reference_path),
+        "images": all_results,
+        "output_dir": str(output_dir),
+    }