Upload README.md with huggingface_hub

README.md

@@ -28,82 +28,115 @@ datasets: []
 
 # AI Comic Studio
 
-A two-model pipeline that generates a complete **25-page, 50-panel comic book** from a single sentence — written by **Gemma 4**, illustrated by **FLUX.2**, served live on **Modal**.
+You type one sentence. You get a 25-page, 50-panel comic book. Title, cast, story arc, consistent character art across every panel. Generated live in under 90 seconds.
 
-Type an idea → Gemma writes the story, casts characters with fixed visual descriptions → FLUX renders every panel with consistent art → a Gradio reader presents the finished comic with page navigation.
+AI Comic Studio chains two small models through a five-stage pipeline. Gemma 4 26B writes the entire comic (safety gate, story bible, 50 panel scripts). FLUX.2 Klein 9B draws every panel. A Gradio reader presents the result with page navigation. No human intervention between idea and finished book.
+
+## Demo
+
+[Watch the full demo on YouTube](https://youtu.be/ma_SNY1qats)
+
+## Social Post
+
+[View on X](https://x.com/Asura1612913/status/2066635430314095013)
+
+## How It Works
+
+**Stage 1: Safety Gate**
+Gemma reviews the idea. Fictional adventure, action, mystery, horror, romance all pass. Only genuinely harmful requests get refused.
+
+**Stage 2: Story Bible**
+Gemma produces: title, logline, a fixed cast of 1-4 characters (each with a 30-word visual description reused verbatim in every image prompt), global art style, color palette, and a 25-page synopsis with full narrative arc.
+
+**Stage 3: Panel Script**
+Gemma writes 50 panels across 5 batches of 5 pages. Each batch receives a recap of all prior panels for story continuity.
+
+**Stage 4: Image Render**
+FLUX.2 renders every panel at 832x576. Character appearance text from the bible is injected into each prompt. Deterministic seeds per panel keep the art consistent from page 1 to page 25.
+
+**Stage 5: Reader**
+The Gradio UI streams panels live as they render, then presents the finished comic: two image+caption panels per page, left/right navigation, and a frozen generation timer.
 
 ## Pipeline
 
 ```
-Story idea
-    │
-    ▼
-Gemma 4 26B-A4B          FLUX.2 Klein 9B
-  Safety gate               Character injection
-  Story bible               Deterministic seeds
-  50 panels (5 batches)     Batched GPU renders
-    │                            │
-    ▼                            ▼
-      25-page comic reader
-      (live timer · page nav)
+"Idea"
+  │
+  ├─ Gemma 4 26B-A4B (Writer)
+  │   ├─ Safety gate
+  │   ├─ Story bible (title, cast, style, 25-page synopsis)
+  │   └─ 50 panels in 5 batches (continuity recap per batch)
+  │
+  ├─ FLUX.2 Klein 9B (Artist)
+  │   ├─ Character injection per prompt
+  │   ├─ Deterministic seeds
+  │   └─ Batched renders (4 panels per GPU pass)
+  │
+  └─ Gradio Reader
+      ├─ Live panel streaming
+      ├─ Page navigation
+      └─ Generation timer
 ```
 
-Gemma handles all text. FLUX handles all images. Both models stay under 32B params.
-
-## How It Works
+## Performance
 
-1. **Safety gate** — Gemma approves or refuses the idea
-2. **Story bible** — title, logline, fixed cast with verbatim visual descriptions, art style, palette, 25-page synopsis
-3. **Panel script** — 5 batches of 5 pages, each fed a recap for continuity
-4. **Image render** — FLUX draws each panel using character descriptions injected into every prompt for consistency
-5. **Reader** — two panels per page, ← → navigation, live generation timer
+| Metric | Value |
+|--------|-------|
+| Warm generation (both GPUs hot) | ~60-90s |
+| Cold start (first call) | +1-3 min |
+| Panels per batch | 4 |
+| Total panels | 50 |
+| Total pages | 25 |
+| Image resolution | 832x576 |
+| FLUX inference steps | 4 |
 
 ## Models
 
-| Model | Role | Params | Runtime |
-|-------|------|--------|---------|
-| `google/gemma-4-26B-A4B-it` | Writer | 26B (4B active MoE) | vLLM on Modal H100 |
-| `black-forest-labs/FLUX.2-klein-9B` | Artist | 9B | Diffusers on Modal H100 |
+| Model | Parameters | Role | Runtime |
+|-------|-----------|------|---------|
+| `google/gemma-4-26B-A4B-it` | 26B (4B active MoE) | All text: safety, bible, panels | vLLM, Modal H100 |
+| `black-forest-labs/FLUX.2-klein-9B` | 9B | All images: panel renders | Diffusers, Modal H100 |
 
-## Modal
+Both models stay under the 32B cap. Gemma never draws. FLUX never writes.
 
-Both backends run on Modal with `min_containers=1` — no cold boot during demos. Scale-to-zero when idle.
+## Character Consistency
 
-```bash
-modal app stop comic-gemma && modal app stop comic-flux  # cost guard
-```
+The core problem in multi-panel comics: FLUX renders each panel independently. AI Comic Studio solves this with verbatim appearance injection. Every character gets a detailed visual description in the story bible (species, build, age, hair, face, clothing, colors, props). That exact text is injected into every FLUX prompt where the character appears. Combined with deterministic seeds, this keeps characters recognizable across 50 panels.
 
 ## Custom UI
 
-No stock Gradio components in the main flow. Everything is `gr.HTML` with handwritten CSS — halftone dot background, Anton typography, comic sticker buttons, live ticking stopwatch, panel-by-panel streaming.
+No stock Gradio components in the main flow. Everything is `gr.HTML` with handwritten CSS: halftone dot background, Anton typography, comic sticker buttons with 3D press effects, live ticking stopwatch at 100ms intervals, panel-by-panel streaming during generation.
 
 ## Run Locally
 
 ```bash
 pip install -r requirements.txt
-COMIC_BACKEND=mock python app.py     # offline, no GPU
-COMIC_BACKEND=modal python app.py    # live (requires Modal deploy)
+COMIC_BACKEND=mock python app.py     # offline, full UI, no GPU
+COMIC_BACKEND=modal python app.py    # live models on Modal
 ```
 
-## Badges
-
-| Badge | Claim |
-|-------|-------|
-| 🎨 Off Brand | Custom UI — no default Gradio chrome |
-| 🤖 Best Agent | Multi-step pipeline with continuity tracking |
-| 🎬 Best Demo | Live timer + panel streaming + comic reader |
-| ⚡ Modal | vLLM + Diffusers on Modal H100s |
-| 📡 Sharing is Caring | Agent trace published |
-| 📓 Field Notes | Build write-up |
-
-## Demo Video
+## Qualification
 
-> 📹 [Watch the demo](https://youtu.be/ma_SNY1qats)
+| Criteria | Status |
+|----------|--------|
+| Under 32B params | 26B + 9B, both under cap |
+| Gradio Space | Deployed on HF Spaces |
+| Demo video | [YouTube](https://youtu.be/ma_SNY1qats) |
+| Social post | [X/Twitter](https://x.com/Asura1612913/status/2066635430314095013) |
+| README tagged | Done |
+| Modal used | vLLM + Diffusers on Modal H100s |
 
-## Social Post
+## Badges
 
-> 🐦 *[Post link coming soon]*
+| Badge | Qualifies |
+|-------|-----------|
+| Off Brand | Yes. Custom UI, no default Gradio chrome. |
+| Best Agent | Yes. 5-stage pipeline with continuity tracking across 50 panels. |
+| Best Demo | Yes. Live timer, panel streaming, full comic reader. |
+| Modal | Yes. Both backends on Modal H100s with scale-to-zero. |
+| Sharing is Caring | Yes. [Social post](https://x.com/Asura1612913/status/2066635430314095013) published. |
+| Field Notes | Pending. Build write-up to be published. |
 
 ---
 
-**Build Small Hackathon 2026 · Thousand Token Wood · Modal**
+**Build Small Hackathon 2026 · Thousand Token Wood**