Upload README.md with huggingface_hub

README.md

@@ -26,230 +26,84 @@ models:
 datasets: []
 ---
 
-<!--
-  AI Comic Studio — Build Small Hackathon 2026
-  Thousand Token Wood track · Best Use of Modal · Off Brand badge
--->
+# AI Comic Studio
 
-<div align="center">
+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**.
 
-# 🎬 AI Comic Studio
+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.
 
-### *Type an idea. Get a full comic book — written and illustrated live.*
-
-**A two-model AI pipeline that generates a complete 25-page, 50-panel comic book in about a minute — Gemma 4 writes the story, FLUX.2 paints every panel, and you watch it happen in real time.**
-
-</div>
-
----
-
-## The Idea
-
-Most AI image generators spit out one panel. AI Comic Studio generates an entire comic book — story bible, fixed cast with consistent character designs, 25 pages of narrative arc, and 50 illustrated panels — from a single sentence. The whole thing runs live on screen with a ticking stopwatch so you can see exactly how fast two small models can work together.
-
----
-
-## What It Does
-
-1. **You type a story idea** — "A lighthouse keeper guards a secret" or "Space-pirate noodle shop"
-2. **Gemma 4 26B-A4B** (the writer) does three things in sequence:
-   - **Safety gate** — refuses only genuinely harmful requests; fictional adventure, action, mystery, horror are all allowed
-   - **Story bible** — title, logline, a fixed cast with detailed visual descriptions (reused in every panel for consistency), art style, palette, and a 25-page synopsis
-   - **Panel script** — 5 batches of 5 pages each, each batch fed a recap of the story so far for continuity
-3. **FLUX.2 Klein 9B** (the artist) renders every panel — character appearance text from the bible is injected into every prompt to keep Elias and his lantern looking the same from panel 1 to panel 50
-4. **The Gradio reader** shows the finished comic — two image+caption panels per page, with ← → navigation
-
----
-
-## The Two-Model Pipeline
+## Pipeline
 
 ```
-"Type an idea"
-      │
-      ▼
-Gemma 4 26B-A4B (Writer)          FLUX.2 Klein 9B (Artist)
-  ├─ Safety gate                      ├─ Character injection
-  ├─ Story bible (title, cast,        ├─ Deterministic seeds
-  │   art style, 25-page synopsis)    ├─ 832×576 landscape panels
-  └─ 50 panels in 5 batches          └─ Batched GPU renders
-      │                                      │
-      ▼                                      ▼
-         25-page comic book reader
-         (Gradio · live timer · page nav)
+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)
 ```
 
-Both models run on **Modal** (H100 GPUs, scale-to-zero with `min_containers=1` for live demos). The Gradio frontend runs on Hugging Face Spaces (CPU).
+Gemma handles all text. FLUX handles all images. Both models stay under 32B params.
 
----
-
-## Model Details
+## How It Works
 
-| Model | Role | Parameters | Runtime |
-|-------|------|-----------|---------|
-| `google/gemma-4-26B-A4B-it` | Writer (text only) | 26B total (4B active MoE) | vLLM on Modal H100 |
-| `black-forest-labs/FLUX.2-klein-9B` | Artist (images only) | 9B | Diffusers on Modal H100 |
+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
 
-Both models are under the 32B parameter cap. Gemma handles ALL text; FLUX handles ALL images. Neither model does the other's job.
+## 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 |
 
-## Character Consistency
+## Modal
 
-The hard part of a 50-panel comic is keeping characters looking the same. AI Comic Studio solves this with **verbatim appearance injection**: each character gets a detailed visual description in the story bible (species/build, age, hair, face, signature clothing, colors, props — ~30 words), and that exact text is injected into every FLUX prompt where the character appears. Combined with deterministic seeds per panel, this keeps the art consistent across the full comic.
+Both backends run on Modal with `min_containers=1` — no cold boot during demos. Scale-to-zero when idle.
 
----
+```bash
+modal app stop comic-gemma && modal app stop comic-flux  # cost guard
+```
 
 ## Custom UI
 
-This is not a stock Gradio app. Every element is hand-crafted:
-
-- **Comic book landing page** — halftone dot background, Anton typography, hard ink shadows, paper texture
-- **Live ticking stopwatch** — `gr.Timer` at 100ms intervals, red while generating, green when done
-- **Panel-by-panel streaming** — each finished panel appears as a live thumbnail during generation
-- **Full comic reader** — two image+caption panels per page, page navigation, title card with logline
-- **Comic sticker buttons** — example chips and nav buttons with 3D press effects
-
-No `gr.Chatbot`, no `gr.Markdown` in the main flow — everything is `gr.HTML` with handwritten CSS.
-
----
-
-## Modal — Where the GPUs Live
-
-Modal powers both model backends:
-
-| Component | Modal Config | Purpose |
-|-----------|-------------|---------|
-| `comic-gemma` | vLLM, H100, `min_containers=1` | Gemma 4 writer endpoint |
-| `comic-flux` | Diffusers, H100, `min_containers=1` | FLUX.2 Klein renderer |
-
-**Why Modal:**
-- Scale-to-zero when not in use (no idle GPU costs)
-- `min_containers=1` keeps one container hot for live demos (no cold boot mid-recording)
-- H100 GPUs for fast inference (~1-2s per panel when warm)
-- `scaledown_window=5min` survives between generation steps
+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.
 
-**Cost guard:** `modal app stop comic-gemma && modal app stop comic-flux` when done.
-
----
-
-## Running Locally
+## Run Locally
 
 ```bash
-git clone https://huggingface.co/spaces/ASTRALK/comic-book-generator
-cd comic-book-generator
 pip install -r requirements.txt
-
-# Mock mode (no GPU, offline, full UI):
-COMIC_BACKEND=mock python app.py
-
-# Live mode (requires Modal deployment):
-COMIC_BACKEND=modal python app.py
+COMIC_BACKEND=mock python app.py     # offline, no GPU
+COMIC_BACKEND=modal python app.py    # live (requires Modal deploy)
 ```
 
-### Deploying the Modal backends
+## Badges
 
-```bash
-pip install modal
-
-# Cache Gemma weights (one-time, ~52GB):
-PYTHONIOENCODING=utf-8 modal run serve/serve_gemma.py::download
-
-# Deploy both backends:
-PYTHONIOENCODING=utf-8 modal deploy serve/serve_gemma.py
-PYTHONIOENCODING=utf-8 modal deploy serve/serve_flux.py
-
-# Set environment:
-export COMIC_BACKEND=modal
-export COMIC_GEMMA_URL=https://<your-workspace>--comic-gemma-serve.modal.run/v1
-export COMIC_GEMMA_MODEL=gemma-comic
-```
-
----
-
-## Architecture
-
-```
-HF Space (CPU, Gradio)
-    │
-    │  OpenAI client → /v1/chat/completions
-    ▼
-Modal: comic-gemma (H100)
-    │  vLLM · Gemma 4 26B-A4B · text only
-    ▼
-Panel scripts (scene + caption)
-    │
-    │  modal.Cls → render_batch()
-    ▼
-Modal: comic-flux (H100)
-    │  Diffusers · FLUX.2 Klein 9B · images only
-    ▼
-50 JPEG panels → Gradio comic reader
-```
-
----
-
-## Tech Stack
-
-| Layer | Technology |
-|-------|-----------|
-| Writer model | Google Gemma 4 26B-A4B (MoE, 4B active) |
-| Artist model | Black Forest Labs FLUX.2 Klein 9B |
-| Writer runtime | vLLM on Modal (H100) |
-| Artist runtime | Diffusers on Modal (H100) |
-| Frontend | Gradio 6 — fully custom HTML/CSS/JS |
-| Character consistency | Verbatim appearance injection + deterministic seeds |
-| JSON parsing | Robust extractor (strips thinking, fences, prose) |
-
----
-
-## Badges Claimed
-
-| Badge | Why |
-|-------|-----|
-| 🎨 **Off Brand** | Fully custom UI — no default Gradio chrome in the main interface. Halftone dots, paper texture, Anton typography, comic sticker buttons, 3D press effects. |
-| 🤖 **Best Agent** | Multi-step pipeline: safety gate → story bible → 5-batch panel scripting → 50 image renders, all with continuity tracking and character consistency. |
-| 🎬 **Best Demo** | Live timer, panel-by-panel streaming, full comic reader with page nav. *(Demo video coming soon)* |
-| ⚡ **Modal** | Both model backends run on Modal — vLLM for Gemma, Diffusers for FLUX, scale-to-zero with min_containers=1 for live demos. |
-| 📡 **Sharing is Caring** | Agent trace published alongside the Space. *(Trace coming soon)* |
-| 📓 **Field Notes** | Blog post about building a 50-panel comic pipeline with two small models. *(Write-up coming soon)* |
-
----
+| 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
 
-> 📹 *Demo video coming soon*
-
-The demo will show:
-1. Typing a story idea
-2. Gemma writing the story bible live
-3. FLUX rendering panels one by one
-4. The live stopwatch ticking
-5. The finished 25-page comic with page navigation
-
----
+> 📹 *[Video link coming soon]*
 
 ## Social Post
 
-> 🐦 *Social post link coming soon*
-
----
-
-## Run Time
-
-A warm generation (both GPUs pre-warmed) takes approximately **60-90 seconds** for the full 25-page, 50-panel comic. Cold start adds ~1-3 minutes for container spin-up.
+> 🐦 *[Post link coming soon]*
 
 ---
 
-## License
-
-Apache 2.0
-
----
-
-<div align="center">
-
-**AI Comic Studio · Build Small Hackathon 2026 · Thousand Token Wood**
-
-*Gemma 4 26B · FLUX.2 Klein 9B · Modal · Gradio · 25 Pages · 50 Panels*
-
-</div>
+**Build Small Hackathon 2026 · Thousand Token Wood · Modal**