milimo-storyboard-analyst

name	milimo-storyboard-analyst
description	Expertise in the Milimo Video Storyboard pipeline, from script parsing (Regex vs AI via Gemma) to generating concept art thumbnails and handling the Smart Element Matching engine. Use this when debugging storyboard extraction, prompt generation for chained video chunks, or modifying the scene/shot hierarchy logic.

Milimo Storyboard Analyst Skill

As the Milimo Storyboard Analyst, your domain is transforming plain text screenplays into generation-ready, strictly formatted data structures (Scene and Shot records), and enriching those structures with intelligent context.

1. Script Parsing Pipelines

The frontend StoryboardView.tsx accepts raw script text. The backend processes it through two main parsing methodologies:

A. The Regex Parser (services/script_parser.py)

• Fast, deterministic. Good for perfectly formatted standard screenplays.
• Uses regex to detect INT./EXT. (Scenes), ALL CAPS (Character Names), and action blocks.
• Failures: Will miss non-standard formatting, prose descriptions, or poorly formatted text.

B. The AI Parser (services/ai_storyboard.py)

• Dispatched via POST /storyboard/ai-parse when the brain icon is clicked.
• Routes through the LTX-2 Text Encoder's chat completion interface (_enhance()), defaulting to Gemma 3.
• Instructs the AI (via AI_STORYBOARD_SYSTEM_PROMPT) to act as a storyboard artist and build a cinematic [ { "scene_heading": "...", "shots": [ ... ] } ] JSON array.
• Evaluates implicit action descriptions to generate varied, appropriate cinematic shot_types (close_up, wide, tracking, etc.).
• Fallback: If Gemma unavailable, automatically routes back to Regex parser.

2. Smart Element Matching (services/element_matcher.py)

After a script is parsed but before it is committed to the database, the backend attempts to auto-link the newly discovered shots to existing Project Elements (characters, locations, items).

• No LLM required: Evaluates 8 discrete signals deterministically.
• Calculates a composite confidence score:
  • Exact character match: 1.0
  • Trigger word in action: 0.95
  • Name in action: 0.85, etc.
• Matches with score >= 0.35 are linked into the shot.matched_elements JSON field.
• Why it matters: StoryboardManager uses this data to inject visual conditioning (IP-Adapter reference images) into the generation pipeline for that shot.

3. Thumbnail Generation & The Job Queue

• UI triggers thumbnail generation: POST /projects/{id}/storyboard/thumbnails.
• Generates 512x320 concept art using Flux 2 (generate_image_task).
• Creates a backend Job marked with is_thumbnail=True.
• The BackgroundTasks worker fulfills the generation, saves to Shot.thumbnail_url, and fires an SSE "complete" event containing shot_id instead of lastJobId.
• CRITICAL: The frontend ServerSlice deliberately ignores thumbnailUrl updates if they do not match shot.lastJobId unless is_thumbnail: true is set, ensuring video generation jobs and thumbnail generation jobs do not conflict in the UI state.

4. Continuity (The Pipeline Handoff)

• To ensure flow across scenes, when StoryboardManager.prepare_shot_generation() is called on shot N, it attempts to pull the last frame of shot N-1.
• Uses asyncio.create_subprocess_exec ffmpeg extraction (-sseof -0.1) to grab the frame without blocking the FastAPI event loop.
• Modifies the generation request to include this extracted image as conditioning_image at frame_0.