Deploy provenance-first OpenComic-Continue research UI

README.md

@@ -12,6 +12,13 @@ license: apache-2.0
 
 # OpenComic-Continue
 
-Public research interface for the copyright-aware OpenComic-Continue pipeline. The Space calls an authenticated Modal API; credentials are configured only as Space secrets.
+Public research interface for the copyright-aware OpenComic-Continue pipeline. It analyzes several
+context pages, exposes an editable multi-page prose brief, locks a separate page/panel storyboard,
+and only then renders sequential identity-preserving edits. A bounded whole-frame checkpoint must
+pass literal cast/prop/anatomy review; otherwise the rest of the sequence switches to a conservative
+source-layer renderer. The Space calls an authenticated Modal API; credentials are configured only
+as managed Space secrets.
 
-Only upload content you own or are permitted to transform. Placeholder panels are explicitly labelled when the image GPU renderer is unavailable.
+Only upload content you own or are permitted to transform. Image output fails closed when the GPU
+renderer or strict anatomy/identity/prop verifier is unavailable; planning placeholders are never
+presented as generated art. Modal services are intentionally scale-to-zero and may cold-start.

app.py

@@ -10,9 +10,18 @@ from pathlib import Path
 
 import gradio as gr
 import httpx
-import spaces
 from PIL import Image
 
+try:
+    import spaces
+except ImportError:  # Local CPU development; Hugging Face provides this module in the Space.
+    class _LocalSpaces:
+        @staticmethod
+        def GPU(*_args, **_kwargs):
+            return lambda function: function
+
+    spaces = _LocalSpaces()
+
 API_URL = os.getenv("MODAL_API_URL", "http://127.0.0.1:8000").rstrip("/")
 API_TOKEN = os.getenv("OPENCOMIC_API_TOKEN", "")
 
@@ -40,12 +49,15 @@ def _upload_payload(files: list[str] | None) -> tuple[bytes, str, str]:
     return stream.getvalue(), "uploaded-pages.cbz", "application/vnd.comicbook+zip"
 
 
-def analyze(files: list[str] | None, reading_direction: str):
+def analyze(files: list[str] | None, reading_direction: str, continuity_notes: str):
     payload, name, mime = _upload_payload(files)
     with httpx.Client(timeout=900) as client:
         response = client.post(
             f"{API_URL}/analyze-comic",
-            params={"reading_direction": reading_direction},
+            params={
+                "reading_direction": reading_direction,
+                "continuity_notes": continuity_notes,
+            },
             headers=_headers(),
             files={"file": (name, payload, mime)},
         )
@@ -58,8 +70,11 @@ def analyze(files: list[str] | None, reading_direction: str):
     )
     session = {
         "memory": result["memory"],
+        "context_images": result.get("context_images", []),
         "reference_images": result.get("reference_images", []),
         "semantic_analysis": result.get("semantic_analysis", {}),
+        "layout_analysis": result.get("layout_analysis", {}),
+        "reading_direction": reading_direction,
     }
     return session, result["memory"], summary
 
@@ -69,8 +84,8 @@ def _data_url_to_image(value: str) -> Image.Image:
     return Image.open(io.BytesIO(payload)).convert("RGB")
 
 
-def generate(
-    session: dict | None,
+def _continuation_request(
+    session: dict,
     pages: int,
     creativity: float,
     dialogue_density: float,
@@ -78,47 +93,70 @@ def generate(
     character_fidelity: float,
     reading_direction: str,
     research_mode: bool,
-):
-    if not session:
-        raise gr.Error("Analyze a comic before requesting a continuation.")
-    memory = session.get("memory", session)
-    reference_images = session.get("reference_images", [])
-    request = {
-        "memory": memory,
-        "reference_images": reference_images,
+) -> dict:
+    resolved_direction = (
+        session.get("reading_direction", "ltr")
+        if reading_direction == "auto"
+        else reading_direction
+    )
+    return {
+        "memory": session.get("memory", session),
+        "context_images": session.get("context_images", []),
+        "reference_images": session.get("reference_images", []),
         "settings": {
             "pages": int(pages),
             "creativity": creativity,
             "dialogue_density": dialogue_density,
             "style_fidelity": style_fidelity,
             "character_fidelity": character_fidelity,
-            "reading_direction": reading_direction,
+            "reading_direction": resolved_direction,
             "research_mode": research_mode,
             "seed": 20260823,
         },
     }
-    with httpx.Client(timeout=900) as client:
+
+
+def generate(
+    session: dict | None,
+    pages: int,
+    creativity: float,
+    dialogue_density: float,
+    style_fidelity: float,
+    character_fidelity: float,
+    reading_direction: str,
+    research_mode: bool,
+):
+    if not session:
+        raise gr.Error("Analyze a comic before requesting a continuation.")
+    request = _continuation_request(
+        session,
+        pages,
+        creativity,
+        dialogue_density,
+        style_fidelity,
+        character_fidelity,
+        reading_direction,
+        research_mode,
+    )
+    reference_images = request["reference_images"]
+    context_images = request["context_images"]
+    with httpx.Client(timeout=3600) as client:
         planned_response = client.post(
             f"{API_URL}/plan-continuation", headers=_headers(), json=request
         )
         if planned_response.is_error:
             raise gr.Error(
-                f"Planning failed ({planned_response.status_code}): "
-                f"{planned_response.text[:500]}"
+                f"Planning failed ({planned_response.status_code}): {planned_response.text[:500]}"
             )
         planned = planned_response.json()
         render_request = {
             **request,
-            "script": planned["script"],
+            "scripts": planned["scripts"],
             "planner_metadata": planned.get("planner", {}),
         }
-        response = client.post(
-            f"{API_URL}/render-script", headers=_headers(), json=render_request
-        )
+        response = client.post(f"{API_URL}/render-script", headers=_headers(), json=render_request)
         if response.is_error:
-            raise gr.Error(
-                f"Rendering failed ({response.status_code}): {response.text[:500]}"
-            )
+            raise gr.Error(f"Rendering failed ({response.status_code}): {response.text[:500]}")
         result = response.json()
     images = [_data_url_to_image(item) for item in result.get("page_data_urls", [])]
     research = {
@@ -132,8 +170,10 @@ def generate(
     }
     updated_session = {
         "memory": result.get("memory"),
+        "context_images": context_images,
         "reference_images": result.get("next_reference_images", reference_images),
         "semantic_analysis": session.get("semantic_analysis", {}),
+        "layout_analysis": session.get("layout_analysis", {}),
     }
     return (
         images,
@@ -144,6 +184,102 @@ def generate(
     )
 
 
+def draft_story_stage(
+    session: dict | None,
+    pages: int,
+    creativity: float,
+    dialogue_density: float,
+    style_fidelity: float,
+    character_fidelity: float,
+    reading_direction: str,
+    research_mode: bool,
+):
+    if not session:
+        raise gr.Error("Analyze a comic before drafting its continuation.")
+    request = _continuation_request(
+        session,
+        pages,
+        creativity,
+        dialogue_density,
+        style_fidelity,
+        character_fidelity,
+        reading_direction,
+        research_mode,
+    )
+    with httpx.Client(timeout=1800) as client:
+        response = client.post(f"{API_URL}/draft-story", headers=_headers(), json=request)
+    if response.is_error:
+        raise gr.Error(f"Story drafting failed ({response.status_code}): {response.text[:500]}")
+    drafted = response.json()
+    state = {"request": request, "story": drafted, "scripts": None}
+    return (
+        state,
+        json.dumps(drafted["story_brief"], indent=2, ensure_ascii=False),
+        "Story drafted and editorially validated. Edit it if needed, then lock it into a storyboard.",
+        {"story_stage": drafted},
+    )
+
+
+def storyboard_stage(planning_state: dict | None, approved_story: dict | str | None):
+    if not planning_state or not approved_story:
+        raise gr.Error("Draft and approve a story before storyboarding.")
+    if isinstance(approved_story, str):
+        try:
+            approved_story = json.loads(approved_story)
+        except json.JSONDecodeError as exc:
+            raise gr.Error(f"The edited story is not valid JSON: {exc}") from exc
+    request = {**planning_state["request"], "locked_story_brief": approved_story}
+    with httpx.Client(timeout=1800) as client:
+        response = client.post(
+            f"{API_URL}/storyboard-continuation", headers=_headers(), json=request
+        )
+    if response.is_error:
+        raise gr.Error(f"Storyboarding failed ({response.status_code}): {response.text[:500]}")
+    planned = response.json()
+    state = {**planning_state, "request": request, "storyboard": planned, "scripts": planned["scripts"]}
+    return (
+        state,
+        planned.get("planner", {}).get("causal_plan", {}),
+        planned["scripts"],
+        "Storyboard locked. Review the page and panel beats, then start visual rendering.",
+        {"story_stage": planning_state.get("story", {}), "storyboard_stage": planned},
+    )
+
+
+def render_locked_stage(session: dict | None, planning_state: dict | None):
+    if not session or not planning_state or not planning_state.get("scripts"):
+        raise gr.Error("Lock a storyboard before rendering.")
+    request = planning_state["request"]
+    render_request = {
+        **request,
+        "scripts": planning_state["scripts"],
+        "planner_metadata": planning_state.get("storyboard", {}).get("planner", {}),
+    }
+    with httpx.Client(timeout=3600) as client:
+        response = client.post(f"{API_URL}/render-script", headers=_headers(), json=render_request)
+    if response.is_error:
+        raise gr.Error(f"Rendering failed ({response.status_code}): {response.text[:500]}")
+    result = response.json()
+    images = [_data_url_to_image(item) for item in result.get("page_data_urls", [])]
+    research = {
+        "story_stage": planning_state.get("story", {}),
+        "storyboard_stage": planning_state.get("storyboard", {}),
+        "renderer": result.get("renderer", {}),
+        "job_id": result.get("job_id"),
+    }
+    updated_session = {
+        "memory": result.get("memory"),
+        "context_images": request.get("context_images", []),
+        "reference_images": result.get(
+            "next_reference_images", request.get("reference_images", [])
+        ),
+        "semantic_analysis": session.get("semantic_analysis", {}),
+        "layout_analysis": session.get("layout_analysis", {}),
+        "reading_direction": request["settings"]["reading_direction"],
+    }
+    return images, result.get("scripts", []), updated_session, result.get("memory"), research
+
+
 def record_preference(choice: str, notes: str) -> str:
     if not choice:
         return "Choose a preference before submitting."
@@ -157,11 +293,14 @@ def record_preference(choice: str, notes: str) -> str:
 with gr.Blocks(title="OpenComic-Continue") as demo:
     gr.Markdown(
         "# OpenComic-Continue\n"
-        "A story-first research prototype: understand the comic, lock a brief continuation "
-        "story, storyboard four causal boxes, then render each box from the previous image. "
+        "A multi-page story-first research prototype: understand several context pages, lock a "
+        "complete continuation arc, storyboard each page into natural four- or five-panel pacing, "
+        "then render every box from the previous "
+        "image plus immutable cast/prop references. "
         "Only upload material you own or have permission to transform."
     )
     memory_state = gr.State()
+    planning_state = gr.State()
     with gr.Tab("Analyze"):
         uploads = gr.File(
             label="Comic pages, PDF, CBZ, or ZIP",
@@ -169,20 +308,24 @@ with gr.Blocks(title="OpenComic-Continue") as demo:
             type="filepath",
         )
         direction = gr.Radio(["ltr", "rtl"], value="ltr", label="Reading direction")
+        continuity_notes = gr.Textbox(
+            label="Optional continuity corrections",
+            placeholder="Example: four physical cats; the round bottle is pink, not red",
+            lines=2,
+            max_lines=4,
+        )
         analyze_button = gr.Button("Analyze comic", variant="primary")
         analysis_summary = gr.Markdown()
         memory_json = gr.JSON(label="StoryMemory")
         analyze_button.click(
             analyze,
-            [uploads, direction],
+            [uploads, direction, continuity_notes],
             [memory_state, memory_json, analysis_summary],
             api_name="analyze_quality",
         )
     with gr.Tab("Continue"):
         with gr.Row():
-            page_count = gr.Slider(
-                1, 1, value=1, step=1, label="Quality pages per run", interactive=False
-            )
+            page_count = gr.Slider(2, 4, value=2, step=1, label="Continuation pages")
             creativity = gr.Slider(0, 1, value=0.5, label="Creativity")
             dialogue = gr.Slider(
                 0,
@@ -197,16 +340,51 @@ with gr.Blocks(title="OpenComic-Continue") as demo:
                 ["auto", "ltr", "rtl"], value="auto", label="Reading direction"
             )
         research_mode = gr.Checkbox(label="Research mode (show routing and model metadata)")
-        generate_button = gr.Button("Generate continuation", variant="primary")
         gr.Markdown(
-            "Generation runs in two bounded backend stages: a locked story + storyboard, then "
-            "sequential panel rendering with per-panel visual checks."
+            "1. Draft the causal prose story. 2. Edit/approve it and lock a storyboard. "
+            "3. Render the locked panels sequentially with strict anatomy, cast, and prop checks."
         )
+        with gr.Row():
+            draft_button = gr.Button("1 · Draft story", variant="primary")
+            storyboard_button = gr.Button("2 · Lock storyboard")
+            render_button = gr.Button("3 · Render panels")
+        stage_status = gr.Markdown()
+        story_brief = gr.Code(label="Editable story brief", language="json", lines=24)
+        storyboard_json = gr.JSON(label="Locked page/panel storyboard")
         gallery = gr.Gallery(label="Continuation pages", columns=2, object_fit="contain")
         scripts = gr.JSON(label="Structured scripts")
         updated_memory = gr.JSON(label="Updated StoryMemory")
         research_json = gr.JSON(label="Research metadata")
-        generate_button.click(
+        draft_button.click(
+            draft_story_stage,
+            [
+                memory_state,
+                page_count,
+                creativity,
+                dialogue,
+                style,
+                character,
+                generation_direction,
+                research_mode,
+            ],
+            [planning_state, story_brief, stage_status, research_json],
+            api_name="draft_story_quality",
+        )
+        storyboard_button.click(
+            storyboard_stage,
+            [planning_state, story_brief],
+            [planning_state, storyboard_json, scripts, stage_status, research_json],
+            api_name="storyboard_quality",
+        )
+        render_button.click(
+            render_locked_stage,
+            [memory_state, planning_state],
+            [gallery, scripts, memory_state, updated_memory, research_json],
+            api_name="render_quality",
+        )
+        # Keep the original combined API contract for scripted research clients.
+        legacy_generate_button = gr.Button("Legacy combined generation", visible=False)
+        legacy_generate_button.click(
             generate,
             [
                 memory_state,