Upload README.md with huggingface_hub

README.md

@@ -1,14 +1,255 @@
 ---
-title: Comicx
-emoji: 📈
-colorFrom: blue
-colorTo: red
+title: AI Comic Studio
+emoji: 🎬
+colorFrom: red
+colorTo: yellow
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.12'
+sdk_version: "6.18.0"
 app_file: app.py
-pinned: false
-license: mit
+pinned: true
+license: apache-2.0
+short_description: Full comic book generated live — Gemma writes, FLUX draws.
+tags:
+- thousand-token-wood
+- off-brand
+- best-agent
+- best-demo
+- modal
+- track:thousand-token-wood
+- sponsor:modal
+- achievement:offbrand
+- achievement:sharing
+- achievement:fieldnotes
+models:
+- google/gemma-4-26B-A4B-it
+- black-forest-labs/FLUX.2-klein-9B
+datasets: []
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<!--
+  AI Comic Studio — Build Small Hackathon 2026
+  Thousand Token Wood track · Best Use of Modal · Off Brand badge
+-->
+
+<div align="center">
+
+# 🎬 AI Comic Studio
+
+### *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
+
+```
+"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)
+```
+
+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).
+
+---
+
+## Model Details
+
+| 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 |
+
+Both models are under the 32B parameter cap. Gemma handles ALL text; FLUX handles ALL images. Neither model does the other's job.
+
+---
+
+## Character Consistency
+
+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.
+
+---
+
+## 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
+
+**Cost guard:** `modal app stop comic-gemma && modal app stop comic-flux` when done.
+
+---
+
+## Running 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
+```
+
+### Deploying the Modal backends
+
+```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)* |
+
+---
+
+## 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
+
+---
+
+## 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.
+
+---
+
+## 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>