Fix ZeroGPU build: real FLUX+VoxCPM, 3-model cleanup, remove Tiny Mode

AGENT_HANDOFF.md

@@ -1,105 +0,0 @@
-# DoodleBook — Coding-Agent Handoff Prompt
-Paste everything in the fenced block below into Codex / OpenCode / Cursor Agent / Claude Code as the build task.
-It is self-contained and bakes in the 5 critical corrections (C1–C5) from `EXECUTION_PLAN.md`.
-
----
-
-```
-ROLE
-You are the lead engineer building "DoodleBook" for the Build Small Hackathon 2026
-(Adventure in Thousand Token Wood track). Build a Gradio app deployed to Hugging Face
-Spaces that turns a child's crayon drawing into a consistent, narrated, illustrated
-6-page storybook. Work in: D:\Project\Hugging_face_app\doodlebook
-
-CONTEXT FILES (read first, in this order)
-1. B2_doodlebook_prompt.md   — original concept, exact code sketches, frontmatter, badges
-2. EXECUTION_PLAN.md         — architecture, phases, and the 5 corrections you MUST honor
-
-NON-NEGOTIABLE CORRECTIONS (override the original prompt where they conflict)
-C1  Do NOT train a LoRA per child at runtime (infeasible). Train ONE crayon-style LoRA
-    OFFLINE. Achieve per-character consistency at inference via: (a) locked seed S, page i
-    uses seed S+i; (b) reuse the identical character_description on every page; (c) feed the
-    uploaded doodle as an IMAGE PROMPT (IP-Adapter / FLUX Redux / img2img strength ~0.3-0.5).
-    The app MUST run on base FLUX with NO LoRA (degrade gracefully, show "LoRA coming").
-C2  MiniCPM5-1B is unreliable at JSON. Use a few-shot prompt with ONE full exemplar, greedy
-    decode, and a 3-layer parser: (1) regex extract {...}; (2) json-repair/json5; (3) a
-    deterministic TEMPLATE fallback that always yields a valid 6-page book. App must NEVER
-    crash on bad model output.
-C3  Modal cold-starts of a 12B diffusion model take minutes. Cache weights on a Modal Volume,
-    expose a keep_warm option, generate all 6 pages in ONE warm container call, and ALWAYS
-    ship a pre-generated sample book in assets/sample_book/ that loads instantly with zero compute.
-C4  This is a SMALL-MODELS hackathon. Frame the 1B story + 2B voice as the "brain" and FLUX as
-    the "renderer" in the README (Tiny Titan argument). Implement a real "Tiny Mode" toggle that
-    swaps FLUX for an SD-Turbo/SDXL-Turbo + style-LoRA path (1-4 steps) runnable on a T4/edge GPU.
-C5  Treat ALL model IDs as UNVERIFIED. FIRST TASK: verify each on the HF Hub and put the resolved
-    IDs + fallbacks in config.py. Fallbacks: FLUX.2-klein -> FLUX.1-schnell; MiniCPM5-1B ->
-    MiniCPM3-4B; VoxCPM2 -> Kokoro or MeloTTS. Nothing else imports a raw model string.
-
-TECH STACK
-Gradio 5.x (gr.Blocks, custom storybook CSS) on HF Spaces (CPU) · Modal for all GPU compute
-(FLUX on A100, MiniCPM on T4, TTS on T4/A10G) · diffusers · peft · transformers · fpdf2 ·
-Python 3.11. Space is a thin orchestrator; every heavy call is modal.Function.remote().
-
-DELIVERABLES (build in this dependency order; commit after each phase)
-PHASE 1 Foundation
-  - Verify model IDs on HF Hub; create config.py = single source of truth (IDs, fallbacks,
-    seeds, step counts, dimensions, lora repo, dataset repo).
-  - Scaffold the directory structure exactly as in B2_doodlebook_prompt.md plus:
-    config.py, services/, ui/, modal/.
-  - requirements.txt, .env.example (HF_TOKEN, MODAL endpoint/token).
-  - Bare Gradio shell that launches and displays the static sample book.
-PHASE 2 Core text pipeline
-  - modal_story_gen.py: MiniCPM story -> JSON {title, character_description, pages:[{page,text,scene}]}
-    with the C2 3-layer parser + template fallback.
-  - book_builder.py: pages -> storybook HTML; PDF export via fpdf2 (gr.DownloadButton).
-  - assets/custom.css storybook styling. Wire text-only book end to end.
-PHASE 3 AI integration
-  - modal_image_gen.py: FLUX pipeline; generate_book_pages() makes all 6 pages in one warm
-    container; C1 consistency stack (seed-lock + char_desc reuse + doodle image-prompt);
-    optional LoRA fuse (~0.85) with graceful base-model fallback; Modal Volume cache; keep_warm.
-  - modal_tts.py: VoxCPM2 narration of title+page texts -> wav, with fallback voice (C5).
-  - Full pipeline: doodle -> story -> 6 images -> narration -> assembled book.
-PHASE 4 UX
-  - Convert create_book to a GENERATOR (yield) so status + pages stream in page-by-page
-    ("Illustrating page N of 6..."). Add "Behind the magic" gr.Accordion (prompts/seeds/LoRA).
-  - Tiny Mode toggle (C4). Mobile-responsive CSS. Accessibility: alt text = page text on every
-    image, AA contrast, prefers-reduced-motion. Examples auto-load the sample on launch.
-PHASE 5 Optimization & badges
-  - lora_finetune/: train_lora.py (DreamBooth-style, FLUX, rank16 alpha16, crayon style,
-    trigger [DOODLECHAR]), dataset_prep.py, README.md (reproduce steps). Publish LoRA to HF
-    (Well-Tuned). bf16/turbo settings; CPU-offload fallback for smaller GPUs.
-  - services/trace.py: log prompts/seeds/lora-version to HF dataset build-small-hackathon/
-    doodlebook-traces (Open Trace).
-  - Pre-generate and COMMIT the 6-page sample book to assets/sample_book/ (C3 non-negotiable).
-PHASE 6 Submission
-  - README.md with the EXACT frontmatter from B2_doodlebook_prompt.md + Tiny Titan argument +
-    model table + architecture diagram + install/usage + screenshots + demo + reproducibility +
-    badges + license (Apache-2.0).
-  - Field Notes blog draft (docs/blog.md) on FLUX+LoRA character consistency.
-  - Deploy to HF Spaces; smoke test the cold-open judge path (sample loads with no compute);
-    verify live generation; run the §9 submission checklist from EXECUTION_PLAN.md.
-
-INTERNAL CONTRACTS (keep stable)
-generate_story(hero_name, theme, age=5) -> {title, character_description, pages:[{page,text,scene}]}
-generate_book_pages(character_desc, story_beats, doodle=None, art_style, seed=42, tiny=False) -> list[bytes png]
-speak_book(text, voice="warm") -> bytes wav
-build_book_html(images, texts, title) -> html ; export_pdf(images, texts, title) -> path
-log_trace(payload) -> dataset_url
-
-ENGINEERING RULES
-- Every remote/model call wrapped in try/except with a user-friendly fallback; the app must
-  never show a stack trace to a judge.
-- config.py is the ONLY place model IDs/params live.
-- Keep the sample-book path 100% independent of live compute so the demo always works.
-- Match the storybook visual identity (paper #FEF9E7, page #FFFDE7, ink #3E2723, CTA #FF7043,
-  serif body). No default Gradio look (Off-Brand badge).
-- Prefer small, readable modules over clever code. Comment the consistency logic and the parser.
-
-DEFINITION OF DONE
-Public HF Space loads the sample book instantly; a live "Make my book!" produces a consistent,
-narrated 6-page book in <2 min warm; Tiny Mode works on a cheap GPU; LoRA repo + trace dataset
-are public; README + frontmatter + blog published; submission checklist fully ticked.
-
-START NOW with Phase 1, Task 0: verify the model IDs on the HF Hub and write config.py. Report
-what you find before proceeding.
-```

B2_doodlebook_prompt.md

@@ -1,406 +0,0 @@
-# B2 — "DoodleBook" | Claude Code Build Prompt  
-## Build Small Hackathon 2026 | Thousand Token Wood Track
-
----
-
-## Mission
-A child draws a crayon character. You photograph it. The app turns it into a consistent illustrated 6-page storybook — same character, same art style, across every page — narrated by MiniCPM5-1B and illustrated by a fine-tuned FLUX.2-klein LoRA. Nobody else in this competition is using FLUX.2-klein with a custom LoRA. That's the entire competitive moat.
-
----
-
-## Models (ONLY sponsor models)
-
-| Role | Model ID | Params | Sponsor |
-|---|---|---|---|
-| Image generation | `black-forest-labs/FLUX.2-klein` | ~12B | Black Forest Labs |
-| LoRA fine-tune (character consistency) | Custom LoRA on FLUX.2-klein | — | Black Forest Labs |
-| Story generation | `openbmb/MiniCPM5-1B` | 1B | OpenBMB |
-| Voice narration | `openbmb/VoxCPM2` | 2B | OpenBMB |
-
-Total: ~15B — under 32B cap.
-
-**FLUX.2-klein model ID note:** Verify the exact HF model card ID at `https://huggingface.co/black-forest-labs`. At time of writing, check for `black-forest-labs/FLUX.2-klein` or `black-forest-labs/FLUX.1-schnell` as fallback. The hackathon docs specifically name FLUX.2-klein.
-
-**Tiny Titan note:** Story model (MiniCPM5-1B) is 1B. If you argue the "primary AI" is the story generator (not the image model), you could claim Tiny Titan. Make this argument in the README.
-
----
-
-## Badge stack
-
-| Badge | How |
-|---|---|
-| ✅ Well-Tuned | Fine-tune LoRA on FLUX.2-klein for character consistency; publish to HF |
-| ✅ Off-Brand | Custom storybook UI — not remotely like default Gradio |
-| ✅ Field Notes | Blog post about FLUX.2-klein + LoRA character consistency approach |
-| ✅ Open Trace | Publish generation traces (prompts, seeds, LoRA weights used) |
-
----
-
-## Tech stack
-- **Gradio 5.x** with `gr.Server` for storybook-style custom UI
-- **Modal** for FLUX.2-klein image generation (A100 recommended — diffusion is memory-heavy)
-- **Modal** for MiniCPM5-1B story generation + VoxCPM2 TTS
-- **diffusers** library for FLUX pipeline
-- **peft** for LoRA loading
-- **Python 3.11**
-
----
-
-## Directory structure
-```
-doodlebook/
-├── app.py                      # Gradio entry point
-├── modal_image_gen.py          # FLUX.2-klein + LoRA generation on Modal
-├── modal_story_gen.py          # MiniCPM5-1B story generation on Modal
-├── modal_tts.py                # VoxCPM2 TTS on Modal
-├── book_builder.py             # Assembles pages into storybook HTML
-├── lora_finetune/
-│   ├── train_lora.py           # FLUX LoRA training script (run locally)
-│   ├── dataset_prep.py         # Prepare character images for training
-│   └── README.md               # How to reproduce the fine-tune
-├── requirements.txt
-├── .env.example                # MODAL_ENDPOINT_URL, HF_TOKEN
-├── README.md
-└── assets/
-    ├── custom.css              # Storybook CSS (yellowed pages, serif font)
-    ├── page_template.html      # Single page HTML template
-    ├── sample_doodle.jpg       # Example child's drawing
-    └── sample_book/            # Pre-generated example book (6 pages)
-        ├── page_1.png
-        └── ...
-```
-
----
-
-## README.md — EXACT frontmatter
-```yaml
----
-title: DoodleBook
-emoji: 📚
-colorFrom: yellow
-colorTo: orange
-sdk: gradio
-sdk_version: "5.0"
-app_file: app.py
-pinned: false
-tags:
-  - hackathon
-  - build-small
-  - adventure-in-thousand-token-wood
-  - black-forest-labs/FLUX.2-klein
-  - openbmb/MiniCPM5-1B
-  - openbmb/VoxCPM2
-  - fine-tuned
-  - lora
-  - character-consistency
-  - storybook
-  - off-brand
----
-```
-
----
-
-## LoRA fine-tuning plan (run BEFORE submission)
-
-### Goal
-Train a LoRA that makes FLUX.2-klein reproduce the visual style of a child's crayon drawing and maintain character consistency across 6 different scene prompts.
-
-### Training data strategy
-1. Take a child's crayon drawing (or generate 10-15 "crayon-style" reference images)
-2. Create variations: same character in different poses/scenes, keeping style consistent
-3. Use DreamBooth-style fine-tuning with a trigger token: `[DOODLECHAR]`
-
-### Train script sketch (lora_finetune/train_lora.py)
-```python
-from diffusers import FluxPipeline
-from peft import LoraConfig, get_peft_model
-# Use diffusers DreamBooth LoRA training
-# Follow: https://github.com/huggingface/diffusers/tree/main/examples/dreambooth
-# Target: FLUX.2-klein with rank=16, alpha=16
-# Training images: 10-15 images of the character
-# Instance prompt: "photo of [DOODLECHAR] character, crayon drawing style"
-# Epochs: 200-400 steps (fast with FLUX)
-```
-
-After training:
-```bash
-huggingface-cli upload build-small-hackathon/doodlebook-flux-lora ./lora-weights
-```
-
----
-
-## modal_image_gen.py
-```python
-import modal
-app = modal.App("doodlebook-image-gen")
-
-flux_env = modal.Image.debian_slim().pip_install(
-    "diffusers>=0.28", "torch", "accelerate", "transformers",
-    "peft", "pillow", "sentencepiece"
-)
-
-@app.function(gpu="A100", image=flux_env, timeout=300, memory=32768)
-def generate_page(
-    prompt: str,
-    lora_repo: str = "build-small-hackathon/doodlebook-flux-lora",
-    seed: int = 42,
-    width: int = 768,
-    height: int = 512
-) -> bytes:
-    from diffusers import FluxPipeline
-    import torch, io
-    from PIL import Image
-
-    pipe = FluxPipeline.from_pretrained(
-        "black-forest-labs/FLUX.2-klein",  # verify ID on HF Hub
-        torch_dtype=torch.bfloat16
-    ).to("cuda")
-
-    # Load character LoRA for consistency
-    pipe.load_lora_weights(lora_repo)
-    pipe.fuse_lora(lora_scale=0.85)
-
-    generator = torch.Generator("cuda").manual_seed(seed)
-    image = pipe(
-        prompt=prompt,
-        num_inference_steps=20,   # FLUX.2-klein is fast
-        guidance_scale=3.5,
-        width=width,
-        height=height,
-        generator=generator
-    ).images[0]
-
-    buf = io.BytesIO()
-    image.save(buf, format="PNG")
-    return buf.getvalue()
-
-@app.function(gpu="A100", image=flux_env, timeout=300, memory=32768)
-def generate_book_pages(
-    character_desc: str,
-    story_beats: list[str],
-    art_style: str = "crayon drawing, children's book, colorful, simple shapes",
-    seed: int = 42
-) -> list[bytes]:
-    """Generate all 6 pages in one function call to reuse the loaded model."""
-    from diffusers import FluxPipeline
-    import torch, io
-
-    pipe = FluxPipeline.from_pretrained(
-        "black-forest-labs/FLUX.2-klein",
-        torch_dtype=torch.bfloat16
-    ).to("cuda")
-    pipe.load_lora_weights("build-small-hackathon/doodlebook-flux-lora")
-    pipe.fuse_lora(lora_scale=0.85)
-
-    pages = []
-    for i, beat in enumerate(story_beats):
-        prompt = (
-            f"[DOODLECHAR] {character_desc}, {beat}, "
-            f"{art_style}, page {i+1} of children's book, "
-            f"white background, simple illustration"
-        )
-        gen = torch.Generator("cuda").manual_seed(seed + i)  # deterministic per page
-        image = pipe(
-            prompt=prompt,
-            num_inference_steps=20,
-            guidance_scale=3.5,
-            width=768, height=512,
-            generator=gen
-        ).images[0]
-        buf = io.BytesIO()
-        image.save(buf, format="PNG")
-        pages.append(buf.getvalue())
-
-    return pages
-```
-
----
-
-## modal_story_gen.py
-```python
-import modal
-app = modal.App("doodlebook-story")
-
-story_env = modal.Image.debian_slim().pip_install(
-    "transformers>=4.40", "torch", "accelerate", "sentencepiece"
-)
-
-@app.function(gpu="T4", image=story_env, timeout=120)
-def generate_story(character_name: str, theme: str, age: int = 5) -> dict:
-    from transformers import AutoTokenizer, AutoModelForCausalLM
-    import torch, json
-
-    tok = AutoTokenizer.from_pretrained("openbmb/MiniCPM5-1B")
-    model = AutoModelForCausalLM.from_pretrained(
-        "openbmb/MiniCPM5-1B", torch_dtype=torch.float16
-    ).cuda().eval()
-
-    prompt = f"""Write a 6-page children's storybook for age {age} about {character_name} with theme: {theme}.
-
-Return ONLY valid JSON:
-{{
-  "title": "Book title",
-  "character_description": "Visual description of {character_name} for illustration",
-  "pages": [
-    {{"page": 1, "text": "1-2 sentence page text (age {age})", "scene": "visual scene description for illustrator"}},
-    {{"page": 2, ...}},
-    {{"page": 3, ...}},
-    {{"page": 4, ...}},
-    {{"page": 5, ...}},
-    {{"page": 6, "text": "Gentle ending. Goodnight.", "scene": "closing scene"}}
-  ]
-}}"""
-
-    inputs = tok(prompt, return_tensors="pt").to("cuda")
-    with torch.no_grad():
-        out = model.generate(**inputs, max_new_tokens=800, do_sample=False)
-    response = tok.decode(out[0][inputs.input_ids.shape[1]:], skip_special_tokens=True)
-
-    import re
-    match = re.search(r'\{.*\}', response, re.DOTALL)
-    if match:
-        return json.loads(match.group())
-    return {"error": response}
-```
-
----
-
-## book_builder.py — storybook HTML assembler
-```python
-import base64
-
-PAGE_HTML = """
-<div class="book-page" style="page-break-after: always;">
-  <img src="data:image/png;base64,{img_b64}" style="width:100%; border-radius:8px;"/>
-  <p class="page-text">{text}</p>
-  <span class="page-num">{page_num}</span>
-</div>
-"""
-
-def build_book_html(pages_images: list[bytes], pages_texts: list[str], title: str) -> str:
-    pages_html = ""
-    for i, (img_bytes, text) in enumerate(zip(pages_images, pages_texts)):
-        b64 = base64.b64encode(img_bytes).decode()
-        pages_html += PAGE_HTML.format(img_b64=b64, text=text, page_num=i+1)
-
-    return f"""<div class="book-container">
-    <h1 class="book-title">{title}</h1>
-    {pages_html}
-    </div>"""
-```
-
----
-
-## app.py — full Gradio storybook UI
-```python
-import gradio as gr
-from modal_story_gen import generate_story
-from modal_image_gen import generate_book_pages
-from modal_tts import speak_book
-from book_builder import build_book_html
-import json
-
-THEMES = ["brave adventure", "making a new friend", "overcoming a fear",
-          "helping someone", "lost and found", "learning something new"]
-
-CSS = """
-body { background: #fef9e7; font-family: 'Georgia', serif; }
-.book-container { max-width: 800px; margin: 0 auto; }
-.book-title { font-size: 32px; text-align: center; color: #5d4037; }
-.book-page { margin: 24px 0; padding: 20px; background: #fffde7; 
-             border-radius: 12px; box-shadow: 3px 3px 12px rgba(0,0,0,0.15); }
-.page-text { font-size: 22px; line-height: 1.9; color: #3e2723; text-align: center; }
-.page-num { color: #bcaaa4; font-size: 14px; }
-.gr-button-primary { background: #ff7043 !important; font-size: 20px; }
-"""
-
-def create_book(doodle_image, character_name, theme, hero_name):
-    if not character_name.strip():
-        character_name = "Little Hero"
-    if not hero_name.strip():
-        hero_name = character_name
-
-    # Step 1: Generate story
-    story = generate_story.remote(hero_name, theme, age=5)
-    if "error" in story:
-        return None, f"Story generation failed: {story['error']}", None
-
-    pages = story["pages"]
-    char_desc = story["character_description"]
-    title = story["title"]
-
-    scene_beats = [p["scene"] for p in pages]
-    page_texts = [p["text"] for p in pages]
-
-    # Step 2: Generate all 6 images (one Modal call, model loaded once)
-    img_bytes_list = generate_book_pages.remote(char_desc, scene_beats)
-
-    # Step 3: Assemble HTML book
-    book_html = build_book_html(img_bytes_list, page_texts, title)
-
-    # Step 4: TTS narration of full book
-    full_text = f"{title}. " + " ".join(page_texts)
-    audio_bytes = speak_book.remote(full_text)
-    audio_path = save_wav(audio_bytes)
-
-    return book_html, f"✅ '{title}' — 6 pages generated!", audio_path
-
-with gr.Blocks(css=CSS, title="📚 DoodleBook") as demo:
-    gr.Markdown("# 📚 DoodleBook\n*Draw a character. Get a storybook.*")
-
-    with gr.Row():
-        with gr.Column(scale=1):
-            doodle = gr.Image(sources=["webcam","upload"], label="📸 Photo of your doodle", type="numpy")
-            char_name = gr.Textbox(label="Character name", placeholder="Ziggy the robot")
-            hero_name = gr.Textbox(label="Hero name in the story", placeholder="Ziggy")
-            theme = gr.Dropdown(choices=THEMES, value=THEMES[0], label="Story theme")
-            make_btn = gr.Button("✨ Make my book!", variant="primary")
-            gr.Examples(
-                examples=[["assets/sample_doodle.jpg", "Ziggy", "Ziggy", "brave adventure"]],
-                inputs=[doodle, char_name, hero_name, theme]
-            )
-            status = gr.Textbox(label="Status", interactive=False)
-
-        with gr.Column(scale=2):
-            book_display = gr.HTML(label="Your storybook")
-            audio_narration = gr.Audio(label="🎙️ Listen to your book", autoplay=False)
-
-    make_btn.click(
-        create_book,
-        inputs=[doodle, char_name, theme, hero_name],
-        outputs=[book_display, status, audio_narration]
-    )
-
-demo.launch()
-```
-
----
-
-## TODO 1 — Doodle style extraction for LoRA prompt conditioning
-After core pipeline works: use MiniCPM-V to *describe* the uploaded doodle in visual terms ("thick black outlines, bright primary colors, stick figure proportions, sun in top corner"). Prepend this extracted style description to every FLUX prompt so the generated images actually *match* the child's drawing style, not just the character concept. This is what makes the output genuinely feel like "their" character.
-
-## TODO 2 — PDF export + shareable link
-Assemble the 6 PNG pages into a downloadable PDF using `fpdf2` or `reportlab`. Add a "Download your book as PDF" button (gr.DownloadButton). Also export the full book as a shareable HF dataset entry (with the prompts, seeds, and LoRA version used) — this earns the Open Trace badge and means families can re-generate the same book later.
-
----
-
-## Sponsor + badge alignment
-
-| Award | Why |
-|---|---|
-| Thousand Token Wood podium | Unique concept — nobody combines child doodle + FLUX LoRA + story |
-| Black Forest Labs ($3k pool) | FLUX.2-klein + custom LoRA — near-empty sponsor field |
-| OpenBMB award (Wood track) | MiniCPM5-1B (story) + VoxCPM2 (narration) |
-| Well-Tuned ($badge) | Published LoRA on HF |
-| Off-Brand ($1,500) | Storybook CSS with yellowed pages, serif font — zero Gradio defaults |
-| Best Demo ($1,000) | Child hearing their drawing narrated as a book = perfect 60-sec video |
-| Community Choice | Shareable, emotional — parents will post this |
-
----
-
-## Non-negotiables
-- Pre-generate and include a complete sample book (all 6 pages) in `assets/sample_book/` so judges can see what it looks like without waiting for generation
-- FLUX on A100 (not A10G) — FLUX.2-klein may need 24GB+ VRAM; check Modal memory settings
-- If LoRA not yet trained, the app must still run with base FLUX.2-klein (no LoRA) — degrade gracefully, note "LoRA coming" in UI
-- Generation time: expect 60-90 seconds for 6 images. Show progress: "Illustrating page 1 of 6..."
-- Verify exact FLUX.2-klein model ID on HF Hub before writing any import statements

DEPLOY.md

@@ -1,102 +0,0 @@
-# DoodleBook — Hugging Face Deployment Guide
-
-## Option 1: HF Spaces + Modal (Recommended)
-
-### Setup Steps
-
-1. **Create HF Space**
-```bash
-# Install HF CLI
-pip install huggingface_hub
-
-# Login
-huggingface-cli login
-
-# Create space
-huggingface-cli space create your-username/doodlebook --sdk gradio
-```
-
-2. **Set Modal Secrets**
-```bash
-# In HF Space Settings → Secrets:
-MODAL_TOKEN_ID=your_modal_token
-HF_TOKEN=your_hf_token
-```
-
-3. **Upload Code**
-```bash
-cd doodlebook
-git init
-git add .
-git commit -m "Initial commit"
-git remote add origin https://huggingface.co/spaces/your-username/doodlebook
-git push -u origin main
-```
-
-### Inference Times
-
-| Scenario | Cold Start | Warm |
-|----------|-----------|------|
-| Sample Book | 0s | 0s |
-| First Generation | 2-3 min | 30-60s |
-| Subsequent | 30-60s | 20-40s |
-
----
-
-## Option 2: HF ZeroGPU (Free, No Modal)
-
-### Changes Needed
-
-Replace Modal calls with direct inference on ZeroGPU:
-
-```python
-# In modal_workers/modal_image_gen.py
-# Remove Modal, use direct torch inference
-```
-
-### Inference Times
-
-| Scenario | Cold Start | Warm |
-|----------|-----------|------|
-| Sample Book | 0s | 0s |
-| First Generation | 3-5 min | 1-2 min |
-| Subsequent | 1-2 min | 45-90s |
-
----
-
-## Option 3: HF Inference API
-
-### Setup
-
-```python
-import requests
-
-API_URL = "https://api-inference.huggingface.co/models/black-forest-labs/FLUX.2-klein-4B"
-headers = {"Authorization": "Bearer your_hf_token"}
-
-def query(payload):
-    response = requests.post(API_URL, headers=headers, json=payload)
-    return response.content
-```
-
-### Inference Times
-
-| Scenario | Cold Start | Warm |
-|----------|-----------|------|
-| Single Image | 10-30s | 5-15s |
-
----
-
-## Recommendation for Hackathon
-
-**Use Option 1 (HF Spaces + Modal)** because:
-- ✅ Sample book loads instantly (no compute)
-- ✅ Warm generation ~30s (fast demo)
-- ✅ Modal keeps model warm during judging
-- ✅ Free HF Space (CPU only)
-- ✅ Modal only charges during generation
-
-### Cost Estimate
-- HF Space: Free
-- Modal: ~$0.50 per demo generation
-- Total for hackathon: ~$5-10

EXECUTION_PLAN.md

@@ -1,414 +0,0 @@
-# DoodleBook — Master Execution Plan
-**Build Small Hackathon 2026 · "Adventure in Thousand Token Wood" Track**
-_Senior architect / strategist / tech-lead review of `B2_doodlebook_prompt.md`_
-
-> Source-of-truth concept: A child draws a crayon character → photograph it → the app produces a
-> **consistent, illustrated 6-page storybook** (same character + same art style on every page),
-> written by **MiniCPM5-1B**, narrated by **VoxCPM2**, illustrated by **FLUX.2-klein + a crayon-style LoRA**.
-
----
-
-## 0. Critical engineering corrections (read first)
-
-The original prompt is excellent on vision and badge strategy but has **5 load-bearing technical risks**. Fix these before writing code or you will fail the live demo.
-
-| # | Risk in original | Reality | Fix (this plan adopts) |
-|---|---|---|---|
-| **C1** | Implies per-child LoRA so each kid's character is reproduced | LoRA training = minutes–hours on A100. You **cannot** train per user at demo time. | LoRA trains **ONE crayon art-style** offline. Per-character consistency comes from **(a) locked seed, (b) the child's doodle used as an image prompt** via IP-Adapter / FLUX Redux / img2img, and **(c) a fixed character description** reused on every page. Never claim live per-child training. |
-| **C2** | 1B model must emit strict JSON | 1B models break JSON constantly (trailing commas, prose, truncation). | Constrained decoding + a **3-layer parser**: (1) regex extract, (2) `json5`/repair, (3) deterministic template fallback so the app NEVER crashes. Few-shot prompt with one full exemplar. |
-| **C3** | "60–90s for 6 images" | True for warm GPU; **Modal cold start of a 12B diffusion model = 2–4 min**. | Modal `@app.cls` with `keep_warm=1` during demo window + model weights on a **Modal Volume** (no re-download). Pre-warm button. Always ship a pre-generated sample book. |
-| **C4** | "Small Models" hackathon, but hero model is 12B | Judges may discount the "small" claim. | **Reframe narrative:** the *brain* (story + voice) is a **3B total small-model stack** (MiniCPM5-1B + VoxCPM2); FLUX is the *renderer/printer*. Add a real **"Tiny Mode"** (SDXL-Turbo or SD-Turbo + style LoRA, runnable on T4/edge) to make the small-model claim defensible and unlock the edge-device track. |
-| **C5** | Assumes model IDs are correct | Prompt itself flags FLUX.2-klein / MiniCPM5-1B / VoxCPM2 as unverified. | **Phase 1, Task 0:** verify every model-card ID on HF Hub; wire fallbacks (`FLUX.1-schnell`, `MiniCPM3-4B`, `MeloTTS`/`Kokoro`) behind one config block. |
-
-Everything below assumes these corrections.
-
----
-
-## 1. Project Analysis
-
-### Executive summary
-DoodleBook converts a child's hand-drawn crayon character (captured by photo) into a complete, narrated, visually-consistent 6-page picture book in ~2 minutes. It fuses three sponsor models into a single emotional, demo-perfect artifact: a 1B story writer, a 2B voice, and a 12B image model steered by a custom crayon-style LoRA. The moat is the **combination** — nobody else pairs a child's real drawing with a fine-tuned FLUX LoRA and on-model narration.
-
-### Problem statement
-Kids create characters constantly but those drawings die on the fridge. Parents can't turn them into the stories children imagine. Existing "AI storybook" apps (a) ignore the child's actual art, (b) produce inconsistent characters page-to-page, and (c) feel like generic AI slop, not *the child's* creation. There is no tool that preserves the child's own visual style across a coherent narrated book.
-
-### Target users
-- **Primary:** Parents of children 3–8 (gift/keepsake, bedtime, screen-time-with-purpose).
-- **Secondary:** Early-years teachers (creative writing prompts), pediatric/occupational therapists (expressive activities), grandparents (remote bonding).
-- **Demo persona:** Judge watching a 60-sec video of a kid hearing their own drawing read aloud as a book.
-
-### Market need
-- AI-storytime apps are a growing category but commoditized and character-inconsistent.
-- Differentiator the market lacks: **"your child's actual drawing becomes the book's art."** Emotional keepsake > generic generation. High shareability (parents post their kids).
-
-### Competitive advantage / moat
-1. **Underused sponsor field** — FLUX.2-klein + custom LoRA is near-empty in the competition (per original recon).
-2. **Style-faithful character consistency** via seed-lock + image-prompt conditioning + LoRA (multi-signal, robust).
-3. **Full small-model stack** end-to-end on sponsor models (story + voice + image).
-4. **Off-brand storybook UI** — zero Gradio defaults.
-5. **Emotional demo** — strongest 60-second-video category in the whole event.
-
-### Innovation score (self-assessed)
-| Axis | Score /10 | Note |
-|---|---|---|
-| Concept originality | 9 | Doodle→consistent book is genuinely novel |
-| Technical depth | 8 | LoRA + multi-model orchestration + consistency engineering |
-| Feasibility in hackathon window | 7 | Achievable IF corrections C1–C5 applied |
-| Demo/emotional impact | 10 | Best-in-show potential |
-| Track coverage | 9 | 5+ awards reachable |
-| **Composite** | **8.6** | Strong winner profile |
-
-### Hackathon-winning potential
-**High.** Realistic path to: Thousand Token Wood podium + Black Forest Labs sponsor award + OpenBMB award + Off-Brand + Best Demo + Community Choice. Five+ simultaneous award surfaces is the strategy (see §7).
-
----
-
-## 2. Product Vision
-
-### Long-term vision
-The default way a family turns a child's imagination into a keepsake — "Instagram for the things your kid invents." Drawing → narrated book → printed photo-book → series with recurring characters.
-
-### Future roadmap
-- **v1 (hackathon):** Doodle → 6-page narrated book, PDF export, Open-Trace share.
-- **v2:** Character library (recurring heroes across books), multi-character scenes, child-voice cloning (with guardian consent), print-on-demand.
-- **v3:** Collaborative books (siblings co-create), classroom mode, multilingual narration, animation (short clips per page).
-- **v4:** On-device "Tiny Mode" mobile app for offline bedtime generation.
-
-### Scalability opportunities
-- Stateless generation workers (Modal autoscale) behind a thin Gradio/HF front door.
-- Cache by (doodle-hash + theme + seed) to dedupe regenerations.
-- Batch the 6 pages in one warm container (already in the original `generate_book_pages`).
-
-### Edge-device deployment possibilities
-- **Story:** MiniCPM5-1B quantized (GGUF/llama.cpp, int4) runs on a laptop/phone NPU.
-- **Voice:** VoxCPM2 or a Kokoro/MeloTTS fallback runs on CPU.
-- **Image (Tiny Mode):** SD-Turbo / SDXL-Turbo + tiny style LoRA at 1–4 steps on a single consumer GPU or Apple Silicon; sub-second-to-a-few-seconds pages.
-- Ship a documented "edge profile" config to claim the edge/small-model narrative credibly.
-
-### Small-model optimization strategy
-- 4-bit (NF4/bitsandbytes) for MiniCPM; `torch.compile` + bf16 for FLUX; sequential CPU offload to fit smaller GPUs.
-- FLUX turbo settings: 4–20 steps; Tiny Mode = 1–4 steps with turbo image model.
-- Modal Volume model cache; `keep_warm` only during judging.
-- KV-cache reuse + greedy decode for deterministic, fast story gen.
-
----
-
-## 3. Technical Architecture
-
-### System architecture (text diagram)
-```
-                         ┌──────────────────────────────────────────────┐
-                         │   HF Space (Gradio 5.x, custom storybook UI)  │
-                         │   app.py  ·  custom.css  ·  book_builder.py    │
-                         └───────────────┬──────────────────────────────┘
-                                         │ orchestration (sync calls)
-        ┌────────────────────────────────┼─────────────────────────────────┐
-        ▼                                ▼                                 ▼
-┌───────────────┐              ┌───────────────────┐             ┌──────────────────┐
-│ modal_story   │              │ modal_image_gen   │             │ modal_tts        │
-│ MiniCPM5-1B   │              │ FLUX.2-klein +    │             │ VoxCPM2          │
-│ (T4) JSON     │  char_desc   │ crayon LoRA (A100)│   pages.png  │ (T4/A10G) wav    │
-│ story+scenes  │ ───────────► │ + IP-Adapter/img2 │ ──────────► │ narration        │
-└───────┬───────┘   scenes     │ img from doodle   │             └────────┬─────────┘
-        │                      └─────────┬─────────┘                      │
-        │  pages[text,scene]             │ 6 page images                  │ audio
-        └───────────────┬────────────────┴────────────────────────────────┘
-                        ▼
-              ┌────────────────────┐
-              │ book_builder.py    │  → storybook HTML (gr.HTML) + PDF (fpdf2)
-              │ + open_trace.py    │  → HF dataset trace (prompts/seeds/lora)
-              └────────────────────┘
-```
-
-### Frontend architecture
-- **Gradio 5.x `gr.Blocks`** single-page, two-column: input panel (left), live book viewer (right).
-- Custom **storybook CSS** (yellowed paper, serif, drop shadows, page-flip feel) → Off-Brand badge.
-- Progressive reveal: pages stream in as generated ("Illustrating page 3 of 6…").
-- `gr.HTML` book canvas, `gr.Audio` narration, `gr.DownloadButton` PDF, `gr.Gallery` fallback.
-
-### Backend architecture
-- **Modal** for all heavy compute, 3 apps (story/image/tts), each a warm-able class.
-- **Stateless** functions; book assembly + trace logging in the Space process.
-- Config module (`config.py`) holds every model ID + fallback + generation params (single source of truth → fixes C5).
-
-### AI model architecture
-- **Story (MiniCPM5-1B, T4):** few-shot, greedy, `max_new_tokens≈800`, constrained JSON + 3-layer parser (C2). Outputs `title`, `character_description`, `pages[{page,text,scene}]`.
-- **Image (FLUX.2-klein + LoRA, A100):**
-  - Crayon **style LoRA** (offline-trained, rank 16) fused at scale ~0.8.
-  - **Consistency stack:** locked base seed `S`; page `i` uses `S+i`; reuse identical `character_description` token block; **doodle image fed as image prompt** (IP-Adapter / Redux / img2img strength ~0.3–0.5) so output resembles the child's drawing (this realizes original TODO 1).
-  - 20 steps (Standard) / 4 steps (Tiny Mode), guidance ~3.5, 768×512.
-- **Voice (VoxCPM2, T4/A10G):** narrate `title + page texts`; return wav.
-- **Doodle understanding (MiniCPM-V, optional):** caption the drawing → style tokens prepended to FLUX prompt (original TODO 1).
-
-### Data flow
-1. User uploads/photographs doodle + name + theme.
-2. Story worker → JSON (title, char desc, 6×{text,scene}).
-3. (Opt) Doodle captioner → style tokens.
-4. Image worker → 6 PNGs (seed-locked, LoRA + doodle-conditioned).
-5. TTS worker → narration wav.
-6. `book_builder` → HTML book + PDF; `open_trace` → HF dataset row.
-
-### API structure (internal contracts)
-```
-generate_story(hero_name:str, theme:str, age:int=5) -> {title, character_description, pages:[{page,text,scene}]}
-generate_book_pages(character_desc:str, story_beats:list[str], doodle:bytes|None,
-                    art_style:str, seed:int=42, tiny:bool=False) -> list[bytes]
-speak_book(text:str, voice:str="warm") -> bytes(wav)
-build_book_html(images:list[bytes], texts:list[str], title:str) -> str
-export_pdf(images, texts, title) -> path
-log_trace(payload) -> dataset_url
-```
-
-### Storage strategy
-- Model weights → **Modal Volume** (cache, no re-download → fixes C3).
-- Generated assets → ephemeral `/tmp` in Space; user downloads PDF.
-- Traces → **HF Dataset** `build-small-hackathon/doodlebook-traces` (Open Trace badge).
-- LoRA weights → **HF model repo** `build-small-hackathon/doodlebook-flux-lora` (Well-Tuned badge).
-
-### Deployment strategy
-- Front end on **HF Spaces** (Gradio SDK 5.0, `app.py`).
-- Compute on **Modal** (secrets: `HF_TOKEN`, endpoint URLs via `.env`).
-- `keep_warm=1` on image app only during judging window; scale to 0 after.
-
-### Performance optimization plan
-- One warm container generates all 6 pages (already designed).
-- bf16 + optional `torch.compile`; turbo step counts; sequential CPU offload fallback.
-- Stream page-by-page UI updates (perceived speed).
-- Pre-generated sample book for instant judge view (non-negotiable).
-- Tiny Mode for sub-10s full books on cheap GPU.
-
----
-
-## 4. UI/UX Design Plan
-
-### Design philosophy
-"**A warm digital picture book, not a dashboard.**" Tactile, nostalgic, magical — looks hand-made, hides all ML. Every interaction should feel like turning a page, not running a model.
-
-### User journeys
-1. **First-time parent (happy path):** land → see sample book glowing → upload kid's drawing → name + theme → "✨ Make my book!" → progress storybook fills page-by-page → narration auto-ready → download PDF / share. <2 min, zero jargon.
-2. **Judge (cold, impatient):** lands on a finished sample book immediately (no generation wait) → clicks "Hear it" → reads the story → optionally generates one live → sees Open-Trace link. Wow in <15s.
-3. **Returning user (v2 vision):** pick a saved character → new adventure → consistent hero.
-
-### Wireframe descriptions
-- **Header:** centered title "📚 DoodleBook", subtitle "Draw a character. Get a storybook.", soft paper texture.
-- **Left input card (scale 1):** webcam/upload doodle, character name, hero name, theme dropdown, big orange "Make my book!" CTA, Examples row (loads sample), status line, "⚡ Tiny Mode" toggle.
-- **Right book viewer (scale 2):** large `gr.HTML` book — title page then 6 illustrated text pages with page numbers, yellowed background, serif body; narration audio bar pinned above; "⬇ Download PDF" + "🔗 Share trace" buttons below.
-- **Progress state:** skeleton page slots fill one-by-one with "Illustrating page N of 6…".
-
-### Dashboard / layout
-- Single page, two columns desktop; stacked on mobile (input → book).
-- Optional collapsible "🔬 Behind the magic" panel showing prompts/seeds/LoRA (judge candy + Open Trace).
-
-### Color palette
-| Token | Hex | Use |
-|---|---|---|
-| Paper | `#FEF9E7` | app background |
-| Page | `#FFFDE7` | book pages |
-| Ink | `#3E2723` | body text |
-| Title brown | `#5D4037` | headings |
-| Crayon orange | `#FF7043` | primary CTA |
-| Sky accent | `#4FC3F7` | secondary/links |
-| Muted | `#BCAAA4` | page numbers/meta |
-
-### Typography
-- Display/title: **Georgia / "Fredoka" / "Baloo 2"** (rounded, child-friendly).
-- Body: **Georgia serif** 20–22px, line-height 1.9 (read-aloud comfortable).
-- Avoid system sans defaults — they read as "Gradio".
-
-### Accessibility
-- WCAG AA contrast (ink on page passes); 18px+ body.
-- Audio narration = built-in alt for non-readers; captions = page text.
-- All controls keyboard reachable; alt text on every generated image (use page `text`).
-- Respect `prefers-reduced-motion` (disable page-flip animation).
-
-### Mobile responsiveness
-- Columns collapse to stack; CTA full-width sticky; webcam capture works on phones (parents photograph the drawing in-app).
-
-### Demo-friendly interactions
-- Auto-load sample book on launch (no empty state).
-- Page-by-page streaming reveal (visible progress = perceived magic).
-- One-tap "Play narration".
-- "Tiny Mode" toggle to show edge story live without long waits.
-
----
-
-## 5. Gradio Implementation Plan
-
-### App structure
-```
-app.py
-├─ config.py            # model IDs + fallbacks + params (single source of truth)
-├─ ui/
-│  ├─ layout.py         # gr.Blocks layout
-│  └─ custom.css        # storybook styling
-├─ services/
-│  ├─ story.py          # calls modal_story_gen
-│  ├─ images.py         # calls modal_image_gen
-│  ├─ tts.py            # calls modal_tts
-│  ├─ book_builder.py   # HTML + PDF
-│  └─ trace.py          # Open Trace dataset logging
-└─ modal/
-   ├─ modal_story_gen.py
-   ├─ modal_image_gen.py
-   └─ modal_tts.py
-```
-
-### Component hierarchy
-```
-gr.Blocks(css, theme)
-├─ Header (gr.Markdown)
-├─ gr.Row
-│  ├─ gr.Column(scale=1)  # inputs
-│  │  ├─ gr.Image(sources=[webcam,upload])
-│  │  ├─ gr.Textbox char_name / hero_name
-│  │  ├─ gr.Dropdown theme
-│  │  ├─ gr.Checkbox tiny_mode
-│  │  ├─ gr.Button "Make my book!" (primary)
-│  │  ├─ gr.Examples (sample)
-│  │  └─ gr.Textbox status (interactive=False)
-│  └─ gr.Column(scale=2)  # output
-│     ├─ gr.Audio narration
-│     ├─ gr.HTML book_display
-│     ├─ gr.DownloadButton PDF
-│     └─ gr.Accordion "Behind the magic" (prompts/seeds)
-```
-
-### Pages & navigation
-Single page (hackathon-optimal). "Pages" = sections of the book inside the HTML canvas. No router needed.
-
-### User interaction flow
-`make_btn.click(create_book, inputs=[...], outputs=[book_html, status, audio, pdf])` — use a **generator function** (`yield`) so status + pages stream in, not one blocking return.
-
-### Model integration approach
-- Space process is thin orchestrator; all GPU work via `modal.Function.remote()`.
-- Defensive: every remote call wrapped in try/except → graceful UI error + fallback (base FLUX if no LoRA, template story if JSON fails).
-
-### Performance considerations
-- Single warm Modal container per book (6 images batched).
-- `gr.Progress()` for the progress bar; `yield` partial books.
-- Cache sample book in memory at startup.
-
-### Deployment on HF Spaces
-- `sdk: gradio`, `sdk_version: "5.0"`, `app_file: app.py` (frontmatter already specified).
-- Secrets: `HF_TOKEN`, `MODAL_ENDPOINT_URL` (or Modal token) in Space settings.
-- Keep Space CPU-only (compute offloaded to Modal) → cheap, always-on.
-
----
-
-## 6. Development Roadmap
-
-> Effort assumes a single builder + coding agent. Sequence is dependency-ordered.
-
-### Phase 1 — Foundation
-- **Tasks:** Verify all model IDs on HF Hub (Task 0, fixes C5); scaffold repo per directory structure; `config.py` with IDs + fallbacks + params; `requirements.txt`; `.env.example`; Modal account + secrets; bare Gradio shell that loads and shows static sample book.
-- **Dependencies:** HF + Modal accounts, tokens.
-- **Effort:** ~0.5 day.
-- **Risks:** Model IDs differ from prompt → fallback wiring matters.
-- **Success:** `app.py` launches locally, shows sample book, `config.py` resolves real model IDs.
-
-### Phase 2 — Core Features
-- **Tasks:** `modal_story_gen.py` with 3-layer JSON parser + template fallback (C2); `book_builder.py` HTML; PDF export (`fpdf2`); storybook CSS; wire story→book (text only, placeholder images).
-- **Dependencies:** Phase 1.
-- **Effort:** ~1 day.
-- **Risks:** 1B JSON instability → mitigated by parser + fallback.
-- **Success:** Enter name+theme → get a valid 6-page text book + PDF, no crashes even on bad model output.
-
-### Phase 3 — AI Integration
-- **Tasks:** `modal_image_gen.py` FLUX pipeline; Modal Volume model cache + `keep_warm` (C3); seed-lock + doodle image-prompt consistency stack (C1); graceful base-FLUX fallback if no LoRA; `modal_tts.py` VoxCPM2 (+ Kokoro/MeloTTS fallback); full pipeline story→images→audio.
-- **Dependencies:** Phase 2; LoRA may still be training (degrade gracefully).
-- **Effort:** ~1.5 days.
-- **Risks:** Cold starts (C3), VRAM (use A100, CPU offload fallback), model-ID drift.
-- **Success:** End-to-end live book in <2 min warm; consistent character across pages; narration plays.
-
-### Phase 4 — UI/UX Enhancement
-- **Tasks:** Streaming page-by-page reveal (`yield`); progress text; "Behind the magic" accordion; Tiny Mode toggle (C4); mobile responsive CSS; Examples auto-load; accessibility pass (alt text, contrast, reduced-motion).
-- **Dependencies:** Phase 3.
-- **Effort:** ~1 day.
-- **Risks:** Gradio streaming quirks; CSS scope leaks.
-- **Success:** Off-Brand-worthy UI; live progress; works on phone; Tiny Mode produces a book fast.
-
-### Phase 5 — Optimization
-- **Tasks:** Train + publish crayon style LoRA (Well-Tuned); quantization/turbo settings; Tiny Mode SD-Turbo path; trace logging to HF dataset (Open Trace); pre-generate + commit sample book (6 pages); error hardening.
-- **Dependencies:** Phases 3–4.
-- **Effort:** ~1 day (+ LoRA train time in background).
-- **Risks:** LoRA quality/time → app must run on base model meanwhile (non-negotiable from original).
-- **Success:** LoRA on HF, traces logged, sample book committed, Tiny Mode real, no unhandled errors.
-
-### Phase 6 — Submission Preparation
-- **Tasks:** README with exact frontmatter + Tiny Titan argument; record 60-sec demo video (child hearing book); blog post (Field Notes) on FLUX+LoRA consistency; screenshots/GIFs; deploy + smoke test on Spaces; final checklist (§9).
-- **Dependencies:** All prior.
-- **Effort:** ~0.5–1 day.
-- **Risks:** Last-minute deploy breakage → smoke test early, keep sample-book path independent of live compute.
-- **Success:** Public Space loads sample instantly, live gen works, all badges' artifacts published, video submitted.
-
-**Total:** ~5–6 focused days. Critical path: Phase 1 (model IDs) → Phase 3 (FLUX+consistency) → Phase 6 (deploy/video).
-
----
-
-## 7. Hackathon Strategy
-
-### Tracks / awards to target (stack as many as possible)
-| Award | Lever |
-|---|---|
-| Thousand Token Wood podium | Unique doodle→consistent-book concept |
-| Black Forest Labs ($3k) | FLUX.2-klein + published custom LoRA (sparse field) |
-| OpenBMB award | MiniCPM5-1B story + VoxCPM2 narration |
-| Well-Tuned | Published LoRA on HF |
-| Off-Brand ($1,500) | Storybook UI, zero Gradio defaults |
-| Best Demo ($1,000) | Child hearing their drawing narrated |
-| Community Choice | Shareable, emotional, parents repost |
-| Tiny Titan (claimable) | Argue story generator (1B) is the primary AI + real Tiny Mode |
-
-### How to maximize scoring
-- One artifact, many badges: every badge needs a concrete published thing (LoRA repo, trace dataset, blog post, off-brand UI) — produce all four.
-- Lead with emotion + sponsor-model usage in README's first 5 lines.
-- Show, don't tell: pre-generated sample book + 60-sec video carry the score even if live gen is slow.
-
-### What judges look for
-Working demo, clear sponsor-model use, originality, polish, reproducibility (traces + LoRA), and a story that makes them feel something. DoodleBook is built to hit all six.
-
-### Demo strategy
-- Open on the finished sample book (instant wow, no wait).
-- Play narration immediately.
-- Then generate one live (or Tiny Mode) to prove it's real.
-- End on the Open-Trace link + "made by a 1B + 2B small-model brain."
-
-### Presentation / storytelling
-Narrative arc: "Kids invent characters every day and we throw them away. Watch what happens when a 1B model gives one a story and FLUX gives it a book — in the child's own art." Personal, concrete, sponsor-forward.
-
-### Key differentiators
-Child's real art preserved · cross-page character consistency engineering · full small-model stack · off-brand keepsake UX · reproducible traces + LoRA.
-
----
-
-## 8. README Plan
-```
-# 📚 DoodleBook  (+ exact HF frontmatter block from original prompt)
-> Elevator pitch: Draw a character → get a narrated, illustrated 6-page storybook in your child's own art.
-1. ✨ Features (consistency, narration, doodle-faithful art, PDF, Tiny Mode, traces)
-2. 🧠 Models & why (table: FLUX.2-klein+LoRA / MiniCPM5-1B / VoxCPM2) + Tiny Titan argument
-3. 🏗️ Architecture (diagram + data flow)
-4. ⚙️ Installation (clone, requirements, Modal setup, HF token, .env)
-5. ▶️ Usage (run app.py, upload doodle, make book)
-6. 🖼️ Screenshots (sample book pages, UI)
-7. 🎬 Demo (60-sec video link + live Space link)
-8. 🔬 Reproducibility (LoRA repo, Open-Trace dataset, seeds)
-9. 🛣️ Future work (character library, voice cloning, print-on-demand, edge app)
-10. 🏅 Hackathon badges (Well-Tuned, Off-Brand, Field Notes, Open Trace)
-11. 📄 License (Apache-2.0 / MIT) · 👥 Contributors
-```
-
-## 9. Submission Checklist
-**Code** ☐ app launches clean ☐ all Modal fns callable ☐ graceful fallbacks (no-LoRA, bad-JSON, remote error) ☐ config has verified model IDs + fallbacks
-**Docs** ☐ README + exact frontmatter ☐ install/usage ☐ LoRA reproduce README ☐ Field Notes blog published
-**UI polish** ☐ storybook CSS, no Gradio defaults ☐ mobile ok ☐ accessibility (alt/contrast/reduced-motion) ☐ Examples auto-load
-**Performance** ☐ warm gen <2 min ☐ keep_warm during judging ��� Tiny Mode works ☐ sample book loads instantly
-**Model optimization** ☐ LoRA trained + published ☐ bf16/turbo steps ☐ Tiny Mode SD-Turbo path
-**HF deployment** ☐ Space live ☐ secrets set ☐ smoke test ☐ trace dataset public ☐ LoRA repo public
-**Demo** ☐ 60-sec video (child hearing book) ☐ live Space link ☐ screenshots/GIFs
-**Presentation** ☐ pitch deck/blurb ☐ storytelling script ☐ badge artifacts linked
-**Final validation** ☐ fresh-clone run ☐ cold-open judge path tested ☐ all badge claims have a published URL
-
-## 10. Agent Execution Prompt
-See `AGENT_HANDOFF.md` — a self-contained master prompt for Codex / OpenCode / Cursor / Claude Code to build the whole project with the C1–C5 corrections baked in.
-```

README.md

@@ -1,289 +1,292 @@
----
-title: DoodleBook
-emoji: 📚
-colorFrom: yellow
-colorTo: red
-sdk: gradio
-sdk_version: "5.50.0"
-app_file: app.py
-pinned: false
-tags:
-  - hackathon
-  - build-small
-  - adventure-in-thousand-token-wood
-  - gradio
-  - modal
-  - flux
-  - minicmp
-  - voxcpm
-  - storybook
-  - coloring-book
----
-
-# DoodleBook
-
-Draw a character, upload it, and DoodleBook turns it into a narrated six-page picture book plus a matching printable coloring book.
-
-The project was built for the Build Small Hackathon 2026. The core idea is to keep the reasoning stack small, use a strong image renderer only where it matters, and make the whole flow feel like a child-facing product instead of a model demo.
-
-## What it does
-
-- Takes a doodle photo from upload or webcam.
-- Generates a six-page children's story with a consistent hero.
-- Renders six full-color story pages with FLUX.
-- Generates narration audio for the whole book.
-- Exports a story PDF.
-- Generates a matching black-and-white coloring book as a second output.
-
-## Current architecture
-
-There are two runtime modes in this repo.
-
-### 1. Local Modal-backed app
-
-Use [run_modal.py](run_modal.py) for the real end-to-end flow during development.
-
-- UI: Gradio 5 custom Blocks layout
-- Story: local generator by default, optional Modal MiniCPM route
-- Images: Modal FLUX pipeline
-- TTS: Modal VoxCPM pipeline
-- PDFs: local export
-- Coloring book: direct FLUX line-art render, with traced fallback
-
-Start it with:
-
-```bash
-python run_modal.py
-```
-
-The default local URL is:
-
-```text
-http://127.0.0.1:7880
-```
-
-### 2. HF Spaces / ZeroGPU-oriented app
-
-Use [app.py](app.py) for the official Hugging Face Gradio Space target.
-
-- `app.py` is the Space entrypoint declared in the repo metadata.
-- `app_zerogpu.py` is the alternate experimental path kept for local ZeroGPU-focused iteration.
-
-## Stack used in the hackathon
-
-This project deliberately mixes a small-model reasoning stack, a stronger dedicated image renderer, a custom Gradio presentation layer, and remote inference infrastructure that is cheap enough to demo but strong enough to feel like a real product.
-
-The important distinction is:
-
-- the app "brain" is small
-- the renderer is specialized
-- the UX is product-shaped, not notebook-shaped
-- the deployment path is built around a Gradio Space front-end
-
-### Full stack at a glance
-
-| Layer | Stack | Role in the product |
-|---|---|---|
-| Product UI | Gradio 5 Blocks + custom CSS/HTML/JS | Child-facing scrapbook interface, status streaming, downloads |
-| Story engine | MiniCPM5-1B + local structured fallback | Writes the six-page narrative and scene plan |
-| Image engine | FLUX.2-klein-4B on Modal | Draws consistent full-color pages and dedicated coloring pages |
-| Voice engine | VoxCPM2 on Modal | Narrates the full storybook |
-| Coloring engine | Direct FLUX line-art pass + cleanup fallback | Produces printable black-and-white pages |
-| Export layer | Pillow + FPDF | Builds printable story and coloring PDFs |
-| Hosting target | Hugging Face Spaces | Gradio app shell and user entrypoint |
-| Remote compute | Modal | GPU execution for heavy image and TTS work |
-| Observability | Heartbeat streaming + stage timing in trace panel | Keeps long runs visible and debuggable |
-
-### Frontend and product shell
-
-- Gradio 5
-- Custom scrapbook-style UI in [ui/layout.py](ui/layout.py)
-- HTML-based book rendering in [book_builder.py](book_builder.py)
-- Fixed-position PDF downloads under the status panel
-- Streaming progress heartbeats to keep long jobs alive in the browser
-- File-backed page rendering instead of giant inline base64 payloads
-
-### Story generation stack
-
-- `openbmb/MiniCPM5-1B`
-- Local fast fallback story generator in [services/story.py](services/story.py)
-- Optional Modal story worker in [modal_workers/modal_story_gen.py](modal_workers/modal_story_gen.py)
-
-Why it matters:
-- The story model is the small-model "brain" of the app.
-- It keeps the narrative stack small and hackathon-aligned.
-- The story system outputs both prose and scene prompts, so downstream image generation stays structured.
-- The local structured fallback means the Space can still produce a valid book if the remote story path is unavailable.
-
-### Image generation stack
-
-- `black-forest-labs/FLUX.2-klein-4B`
-- Modal deployment for image generation in [modal_workers/modal_image_gen.py](modal_workers/modal_image_gen.py)
-- Parallel canonical-character plus per-page render flow in [services/images.py](services/images.py)
-- One canonical character render from the child doodle, then scene-specific page renders
-- Separate direct line-art render path for the coloring book
-
-Why it matters:
-- The app needs high visual quality and character consistency.
-- FLUX is used as the renderer, not as the reasoning engine.
-- The character consistency pipeline is what makes the book feel authored rather than randomly reimagined on every page.
-- The line-art renderer is separate because tracing finished crayon pages produced bad coloring results.
-
-### TTS stack
-
-- `openbmb/VoxCPM2`
-- Modal TTS worker in [modal_workers/modal_tts.py](modal_workers/modal_tts.py)
-- Service wrapper in [services/tts.py](services/tts.py)
-- Parallelized with image generation in the real Modal-backed app
-
-Why it matters:
-- Narration is part of the child-facing experience, not a side feature.
-- TTS runs in parallel with image generation in the real local pipeline.
-- Overlapping TTS with illustration time reduces total wait without degrading output quality.
-
-### Coloring-book stack
-
-- Direct FLUX line-art rendering for the same scenes
-- Cleanup and fallback pipeline in [services/coloring.py](services/coloring.py)
-- Modal `render_coloring_page` for dedicated line-art scene generation
-- Local cleanup for thresholding, despeckling, and printable black-on-white output
-
-Why it matters:
-- The main bug fixed in this version was that the coloring book used to trace finished crayon-textured images.
-- The improved pipeline renders dedicated line-art pages instead of trying to strip color out after the fact.
-- This is the main quality improvement that separates the current version from the earlier broken coloring-book output.
-
-### Infrastructure stack
-
-- Modal for remote GPU inference
-- Hugging Face Spaces as the target host
-- Python 3.11 / 3.13 local development
-- `diffusers`, `transformers`, `torch`, `accelerate`
-- `Pillow`, `OpenCV`, `FPDF`
-- Gradio client-compatible API surface for testing and debugging
-- Hugging Face org deployment target: `build-small-hackathon`
-
-### Sponsor and hackathon alignment
-
-This app directly reflects the hackathon sponsor/tool stack:
-
-- `OpenBMB`: MiniCPM5-1B and VoxCPM2
-- `Black Forest Labs`: FLUX.2-klein-4B
-- `Modal`: remote GPU inference
-- `OpenAI Codex`: debugging, architecture fixes, deployment preparation, README/release work
-- `Hugging Face Spaces`: final Gradio app surface
-
-For hackathon judging, the main narrative is:
-
-- Tiny Titan reasoning stack
-- Off-brand custom UI
-- Real multimodal product loop
-- Remote GPU orchestration with a Gradio user experience
-- Child-usable output artifacts: storybook PDF, audio, coloring book PDF
-
-## Key engineering fixes in this version
-
-- Added direct Modal coloring-page rendering with `render_coloring_page`.
-- Fixed the live app to keep the Gradio stream alive during long coloring generation.
-- Added stage timing so story, image, PDF, TTS, and coloring costs are visible.
-- Reduced final-page payload size by replacing giant inline base64 book HTML with file-backed image URLs.
-- Fixed download serving through Gradio temp-file paths.
-- Removed port confusion between the local test app and the real Modal-backed app.
-
-## Measured performance
-
-Measured against the real local Modal-backed app flow:
-
-- Story-only stage: about `0.3s`
-- Full-color book, warm: about `75s to 80s`
-- Full-color book + coloring book, warm: about `200s`
-- Slowest stage: coloring-book generation
-
-The current bottleneck is still the coloring-book path, even after the direct line-art fix.
-
-## Repository layout
-
-```text
-app.py                  Main Gradio app variant
-app_zerogpu.py          ZeroGPU-oriented app variant
-run_modal.py            Real local Modal-backed app
-book_builder.py         HTML and PDF assembly
-services/               Orchestration and fallbacks
-modal_workers/          Modal remote workers
-ui/                     Custom Gradio layout
-assets/                 Sample doodles and sample book pages
-docs/                   Specs and notes
-```
-
-## Local setup
-
-```bash
-pip install -r requirements.txt
-python run_modal.py
-```
-
-If you want the real Modal-backed app, use `run_modal.py`, not `app.py`.
-
-## Hugging Face Space deployment target
-
-The intended hosted version is a Gradio Space in the `build-small-hackathon` org.
-
-Target format:
-
-```text
-build-small-hackathon/DoodleBook
-```
-
-Official target configuration:
-
-- Hugging Face Space SDK: `gradio`
-- Space entrypoint: `app.py`
-- Hardware target: `ZeroGPU`
-- Space frontend and API live on Hugging Face
-- Local or Spaces-managed inference path should be preferred for the official org deployment
-
-Important distinction:
-
-- `run_modal.py` is the best local development and debugging path.
-- `app.py` is the correct Hugging Face Space entrypoint.
-- Do not point the Space metadata at `run_modal.py`, because that is the Modal-backed dev runtime rather than the official hosted Gradio runtime.
-
-If you choose the Modal-backed hosted variant later, that becomes a different deployment shape and requires secrets.
-
-Required secrets only for the Modal-backed hosted variant:
-
-- `MODAL_TOKEN_ID`
-- `MODAL_TOKEN_SECRET`
-- any Hugging Face token needed by Modal workers for model pulls
-
-Why the Gradio Space + ZeroGPU shape is preferred for the hackathon org:
-
-- keeps the user-facing app as a normal Gradio Space
-- matches the official hackathon org publishing model
-- keeps the demo easy to judge, share, and run from the org page
-- avoids depending on a separate private frontend host
-
-Tradeoff:
-
-- The pure ZeroGPU path is easier to host in the official org.
-- The Modal-backed path currently gives stronger image and TTS quality.
-- The repo keeps both because local quality validation and official hosting have different constraints.
-
-## Hackathon fit
-
-This project targets the hackathon stack in a deliberate way:
-
-- Small-model reasoning for story generation
-- Strong but scoped rendering model for visuals
-- Distinct multimodal outputs: story, illustrations, narration, coloring book
-- Real product UX instead of a bare prompt box
-- Clear deployment story for Hugging Face Spaces plus Modal GPU workers
-
-## Contributors
-
-- Sushruth S.
-- OpenAI Codex: debugging, architecture fixes, rendering pipeline fixes, README and release preparation
-
-## License
-
-Apache-2.0. See [LICENSE](LICENSE).
+---
+title: DoodleBook
+emoji: 📚
+colorFrom: yellow
+colorTo: red
+sdk: gradio
+sdk_version: "5.50.0"
+app_file: app.py
+pinned: false
+tags:
+  - hackathon
+  - build-small
+  - adventure-in-thousand-token-wood
+  - gradio
+  - flux
+  - minicpm
+  - voxcpm
+  - storybook
+  - coloring-book
+models:
+  - black-forest-labs/FLUX.2-klein-4B
+  - openbmb/MiniCPM5-1B
+  - openbmb/VoxCPM2
+---
+
+# DoodleBook
+
+Draw a character, upload it, and DoodleBook turns it into a narrated six-page picture book plus a matching printable coloring book.
+
+The project was built for the Build Small Hackathon 2026. The core idea is to keep the reasoning stack small, use a strong image renderer only where it matters, and make the whole flow feel like a child-facing product instead of a model demo.
+
+## What it does
+
+- Takes a doodle photo from upload or webcam.
+- Generates a six-page children's story with a consistent hero.
+- Renders six full-color story pages with FLUX.
+- Generates narration audio for the whole book.
+- Exports a story PDF.
+- Generates a matching black-and-white coloring book as a second output.
+
+## Current architecture
+
+There are two runtime modes in this repo.
+
+### 1. Local Modal-backed app
+
+Use [run_modal.py](run_modal.py) for the real end-to-end flow during development.
+
+- UI: Gradio 5 custom Blocks layout
+- Story: local generator by default, optional Modal MiniCPM route
+- Images: Modal FLUX pipeline
+- TTS: Modal VoxCPM pipeline
+- PDFs: local export
+- Coloring book: direct FLUX line-art render, with traced fallback
+
+Start it with:
+
+```bash
+python run_modal.py
+```
+
+The default local URL is:
+
+```text
+http://127.0.0.1:7880
+```
+
+### 2. HF Spaces / ZeroGPU-oriented app
+
+Use [app.py](app.py) for the official Hugging Face Gradio Space target.
+
+- `app.py` is the Space entrypoint declared in the repo metadata.
+- `app_zerogpu.py` is the alternate experimental path kept for local ZeroGPU-focused iteration.
+
+## Stack used in the hackathon
+
+This project deliberately mixes a small-model reasoning stack, a stronger dedicated image renderer, a custom Gradio presentation layer, and remote inference infrastructure that is cheap enough to demo but strong enough to feel like a real product.
+
+The important distinction is:
+
+- the app "brain" is small
+- the renderer is specialized
+- the UX is product-shaped, not notebook-shaped
+- the deployment path is built around a Gradio Space front-end
+
+### Full stack at a glance
+
+| Layer | Stack | Role in the product |
+|---|---|---|
+| Product UI | Gradio 5 Blocks + custom CSS/HTML/JS | Child-facing scrapbook interface, status streaming, downloads |
+| Story engine | MiniCPM5-1B + local structured fallback | Writes the six-page narrative and scene plan |
+| Image engine | FLUX.2-klein-4B on Modal | Draws consistent full-color pages and dedicated coloring pages |
+| Voice engine | VoxCPM2 on Modal | Narrates the full storybook |
+| Coloring engine | Direct FLUX line-art pass + cleanup fallback | Produces printable black-and-white pages |
+| Export layer | Pillow + FPDF | Builds printable story and coloring PDFs |
+| Hosting target | Hugging Face Spaces | Gradio app shell and user entrypoint |
+| Remote compute | Modal | GPU execution for heavy image and TTS work |
+| Observability | Heartbeat streaming + stage timing in trace panel | Keeps long runs visible and debuggable |
+
+### Frontend and product shell
+
+- Gradio 5
+- Custom scrapbook-style UI in [ui/layout.py](ui/layout.py)
+- HTML-based book rendering in [book_builder.py](book_builder.py)
+- Fixed-position PDF downloads under the status panel
+- Streaming progress heartbeats to keep long jobs alive in the browser
+- File-backed page rendering instead of giant inline base64 payloads
+
+### Story generation stack
+
+- `openbmb/MiniCPM5-1B`
+- Local fast fallback story generator in [services/story.py](services/story.py)
+- Optional Modal story worker in [modal_workers/modal_story_gen.py](modal_workers/modal_story_gen.py)
+
+Why it matters:
+- The story model is the small-model "brain" of the app.
+- It keeps the narrative stack small and hackathon-aligned.
+- The story system outputs both prose and scene prompts, so downstream image generation stays structured.
+- The local structured fallback means the Space can still produce a valid book if the remote story path is unavailable.
+
+### Image generation stack
+
+- `black-forest-labs/FLUX.2-klein-4B`
+- Modal deployment for image generation in [modal_workers/modal_image_gen.py](modal_workers/modal_image_gen.py)
+- Parallel canonical-character plus per-page render flow in [services/images.py](services/images.py)
+- One canonical character render from the child doodle, then scene-specific page renders
+- Separate direct line-art render path for the coloring book
+
+Why it matters:
+- The app needs high visual quality and character consistency.
+- FLUX is used as the renderer, not as the reasoning engine.
+- The character consistency pipeline is what makes the book feel authored rather than randomly reimagined on every page.
+- The line-art renderer is separate because tracing finished crayon pages produced bad coloring results.
+
+### TTS stack
+
+- `openbmb/VoxCPM2`
+- Modal TTS worker in [modal_workers/modal_tts.py](modal_workers/modal_tts.py)
+- Service wrapper in [services/tts.py](services/tts.py)
+- Parallelized with image generation in the real Modal-backed app
+
+Why it matters:
+- Narration is part of the child-facing experience, not a side feature.
+- TTS runs in parallel with image generation in the real local pipeline.
+- Overlapping TTS with illustration time reduces total wait without degrading output quality.
+
+### Coloring-book stack
+
+- Direct FLUX line-art rendering for the same scenes
+- Cleanup and fallback pipeline in [services/coloring.py](services/coloring.py)
+- Modal `render_coloring_page` for dedicated line-art scene generation
+- Local cleanup for thresholding, despeckling, and printable black-on-white output
+
+Why it matters:
+- The main bug fixed in this version was that the coloring book used to trace finished crayon-textured images.
+- The improved pipeline renders dedicated line-art pages instead of trying to strip color out after the fact.
+- This is the main quality improvement that separates the current version from the earlier broken coloring-book output.
+
+### Infrastructure stack
+
+- Modal for remote GPU inference
+- Hugging Face Spaces as the target host
+- Python 3.11 / 3.13 local development
+- `diffusers`, `transformers`, `torch`, `accelerate`
+- `Pillow`, `OpenCV`, `FPDF`
+- Gradio client-compatible API surface for testing and debugging
+- Hugging Face org deployment target: `build-small-hackathon`
+
+### Sponsor and hackathon alignment
+
+This app directly reflects the hackathon sponsor/tool stack:
+
+- `OpenBMB`: MiniCPM5-1B and VoxCPM2
+- `Black Forest Labs`: FLUX.2-klein-4B
+- `Modal`: remote GPU inference
+- `OpenAI Codex`: debugging, architecture fixes, deployment preparation, README/release work
+- `Hugging Face Spaces`: final Gradio app surface
+
+For hackathon judging, the main narrative is:
+
+- Tiny Titan reasoning stack
+- Off-brand custom UI
+- Real multimodal product loop
+- Remote GPU orchestration with a Gradio user experience
+- Child-usable output artifacts: storybook PDF, audio, coloring book PDF
+
+## Key engineering fixes in this version
+
+- Added direct Modal coloring-page rendering with `render_coloring_page`.
+- Fixed the live app to keep the Gradio stream alive during long coloring generation.
+- Added stage timing so story, image, PDF, TTS, and coloring costs are visible.
+- Reduced final-page payload size by replacing giant inline base64 book HTML with file-backed image URLs.
+- Fixed download serving through Gradio temp-file paths.
+- Removed port confusion between the local test app and the real Modal-backed app.
+
+## Measured performance
+
+Measured against the real local Modal-backed app flow:
+
+- Story-only stage: about `0.3s`
+- Full-color book, warm: about `75s to 80s`
+- Full-color book + coloring book, warm: about `200s`
+- Slowest stage: coloring-book generation
+
+The current bottleneck is still the coloring-book path, even after the direct line-art fix.
+
+## Repository layout
+
+```text
+app.py                  Main Gradio app variant
+app_zerogpu.py          ZeroGPU-oriented app variant
+run_modal.py            Real local Modal-backed app
+book_builder.py         HTML and PDF assembly
+services/               Orchestration and fallbacks
+modal_workers/          Modal remote workers
+ui/                     Custom Gradio layout
+assets/                 Sample doodles and sample book pages
+docs/                   Specs and notes
+```
+
+## Local setup
+
+```bash
+pip install -r requirements.txt
+python run_modal.py
+```
+
+If you want the real Modal-backed app, use `run_modal.py`, not `app.py`.
+
+## Hugging Face Space deployment target
+
+The intended hosted version is a Gradio Space in the `build-small-hackathon` org.
+
+Target format:
+
+```text
+build-small-hackathon/DoodleBook
+```
+
+Official target configuration:
+
+- Hugging Face Space SDK: `gradio`
+- Space entrypoint: `app.py`
+- Hardware target: `ZeroGPU`
+- Space frontend and API live on Hugging Face
+- Local or Spaces-managed inference path should be preferred for the official org deployment
+
+Important distinction:
+
+- `run_modal.py` is the best local development and debugging path.
+- `app.py` is the correct Hugging Face Space entrypoint.
+- Do not point the Space metadata at `run_modal.py`, because that is the Modal-backed dev runtime rather than the official hosted Gradio runtime.
+
+If you choose the Modal-backed hosted variant later, that becomes a different deployment shape and requires secrets.
+
+Required secrets only for the Modal-backed hosted variant:
+
+- `MODAL_TOKEN_ID`
+- `MODAL_TOKEN_SECRET`
+- any Hugging Face token needed by Modal workers for model pulls
+
+Why the Gradio Space + ZeroGPU shape is preferred for the hackathon org:
+
+- keeps the user-facing app as a normal Gradio Space
+- matches the official hackathon org publishing model
+- keeps the demo easy to judge, share, and run from the org page
+- avoids depending on a separate private frontend host
+
+Tradeoff:
+
+- The pure ZeroGPU path is easier to host in the official org.
+- The Modal-backed path currently gives stronger image and TTS quality.
+- The repo keeps both because local quality validation and official hosting have different constraints.
+
+## Hackathon fit
+
+This project targets the hackathon stack in a deliberate way:
+
+- Small-model reasoning for story generation
+- Strong but scoped rendering model for visuals
+- Distinct multimodal outputs: story, illustrations, narration, coloring book
+- Real product UX instead of a bare prompt box
+- Clear deployment story for Hugging Face Spaces plus Modal GPU workers
+
+## Contributors
+
+- Sushruth S.
+- OpenAI Codex: debugging, architecture fixes, rendering pipeline fixes, README and release preparation
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

app.py

@@ -1,726 +1,697 @@
-"""
-DoodleBook — HF ZeroGPU Version
-
-Free T4 GPU on Hugging Face Spaces!
-No Modal needed.
-"""
-
-import gradio as gr
-import os
-import sys
-import torch
-try:
-    import spaces
-except ModuleNotFoundError:
-    # `spaces` only exists on HF ZeroGPU. Off-HF (local/dev) provide a no-op so
-    # the app still runs; generation then uses whatever local GPU/CPU exists.
-    class _SpacesShim:
-        @staticmethod
-        def GPU(*args, **kwargs):
-            if args and callable(args[0]):      # bare @spaces.GPU
-                return args[0]
-            def deco(fn):                       # @spaces.GPU(duration=...)
-                return fn
-            return deco
-    spaces = _SpacesShim()
-import json
-import time
-import tempfile
-import logging
-import struct
-import re
-
-sys.path.insert(0, os.path.dirname(__file__))
-
-from config import (
-    FLUX_MODEL, STORY_MODEL, TTS_MODEL,
-    GENERATION_PARAMS, SAMPLE_BOOK_PATH, BASE_SEED, page_seed,
-    DEFAULT_VOICE, voice_design,
-)
-from book_builder import (
-    build_book_html, export_pdf, magic_loader_html,
-    build_coloring_html, export_coloring_pdf,
-)
-from ui.layout import create_layout
-
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-_STORY_MODEL = None
-_STORY_TOKENIZER = None
-_IMAGE_PIPE = None
-_IMAGE_PIPE_KIND = None
-_TTS_MODEL = None
-
-COLOR_ART_STYLE = (
-    "children's crayon storybook illustration, bold black outlines, "
-    "flat bright colors, simple shapes"
-)
-COLOR_PAGE_SUFFIX = "full colorful background scene, the character clearly visible."
-LINE_ART_STYLE = (
-    "children's coloring book page, pure black ink outlines on pure white paper, "
-    "clean contour lines, no color, no gray, no shading, no texture, "
-    "no hatching, no pencil marks, open spaces to color"
-)
-LINE_ART_SUFFIX = (
-    "simple clean background shapes, same composition, thick readable outlines, "
-    "no filled black areas, no extra sketch marks."
-)
-
-THEME_TEMPLATES = {
-    "brave adventure": [
-        ("{hero} loved exploring new places.", "{hero} standing at the start of a bright adventure trail"),
-        ("One morning, {hero} discovered something glowing nearby.", "{hero} spotting a magical glow in the distance"),
-        ("Taking a deep breath, {hero} bravely went closer.", "{hero} walking forward with courage"),
-        ("There, a new friend needed help.", "{hero} finding a small friend in trouble"),
-        ("{hero} helped with kindness and a clever idea.", "{hero} helping the friend together"),
-        ("Everyone cheered, and {hero} felt proud and brave.", "{hero} celebrating at sunset with the new friend"),
-    ],
-    "making a new friend": [
-        ("{hero} was playing alone in a sunny place.", "{hero} playing under a bright sky"),
-        ("Then {hero} noticed someone shy nearby.", "{hero} seeing a shy new friend nearby"),
-        ("{hero} smiled and said hello.", "{hero} waving with a friendly smile"),
-        ("Soon they were sharing stories and laughs.", "{hero} and the new friend laughing together"),
-        ("They played games all afternoon.", "{hero} and the new friend playing together"),
-        ("By sunset, {hero} had made a wonderful new friend.", "{hero} and the new friend smiling together at sunset"),
-    ],
-}
-
-FEW_SHOT_EXEMPLAR = """
-Write a 6-page children's storybook for age 5 about Luna the cat with theme: brave adventure.
-
-Return ONLY valid JSON:
-{
-  "title": "Luna's Brave Adventure",
-  "character_description": "A small orange tabby cat named Luna with big green eyes, whiskers, and a tiny red scarf",
-  "pages": [
-    {"page": 1, "text": "Luna was a small orange cat who loved to explore.", "scene": "Luna sitting by the window looking outside"},
-    {"page": 2, "text": "One sunny morning, Luna saw something sparkling in the forest.", "scene": "Luna spotting a glow in the trees"},
-    {"page": 3, "text": "Bravely, Luna crept into the forest to investigate.", "scene": "Luna walking cautiously through trees"},
-    {"page": 4, "text": "It was a tiny fairy stuck in a spider web!", "scene": "Luna discovering a fairy in trouble"},
-    {"page": 5, "text": "Luna gently freed the fairy with her paw.", "scene": "Luna carefully helping the fairy"},
-    {"page": 6, "text": "The fairy thanked Luna and they became friends forever.", "scene": "Luna and fairy playing together at sunset"}
-  ]
-}
-"""
-
-
-def build_story_prompt(hero_name: str, theme: str, age: int) -> str:
-    return f"""{FEW_SHOT_EXEMPLAR}
-
-Write a 6-page children's storybook for age {age} about {hero_name} with theme: {theme}.
-
-Return ONLY valid JSON:
-"""
-
-
-def _validate_story_structure(story: dict) -> bool:
-    required_keys = ["title", "character_description", "pages"]
-    if not all(k in story for k in required_keys):
-        return False
-    pages = story.get("pages", [])
-    if not isinstance(pages, list) or len(pages) < 1:
-        return False
-    first_page = pages[0]
-    return all(k in first_page for k in ["page", "text", "scene"])
-
-
-def _repair_json(json_str: str) -> str:
-    json_str = re.sub(r',\s*([}\]])', r'\1', json_str)
-    json_str = re.sub(r'//.*?$', '', json_str, flags=re.MULTILINE)
-    json_str = re.sub(r'/\*[\s\S]*?\*/', '', json_str)
-    json_str = re.sub(r'(?<=")\n(?=")', '\\n', json_str)
-    json_str = re.sub(r'(\s)(\w+)(\s*:)', r'\1"\2"\3', json_str)
-    return json_str
-
-
-def parse_story_json(raw_output: str) -> dict | None:
-    match = re.search(r'\{[\s\S]*\}', raw_output or "")
-    if not match:
-        return None
-    raw_json = match.group(0)
-    for candidate in (raw_json, _repair_json(raw_json)):
-        try:
-            story = json.loads(candidate)
-            if _validate_story_structure(story):
-                return story
-        except Exception:
-            continue
-    return None
-
-
-def _normalize_story(story: dict) -> dict:
-    pages = list(story.get("pages", []))[:6]
-    while len(pages) < 6:
-        pages.append({
-            "page": len(pages) + 1,
-            "text": "And the adventure continued happily.",
-            "scene": "Continuing adventure",
-        })
-    story["pages"] = pages
-    story.setdefault("title", "A Wonderful Adventure")
-    story.setdefault(
-        "character_description",
-        "A friendly children's storybook hero with bright colors and cheerful features",
-    )
-    return story
-
-
-def build_story_locally(hero_name: str, theme: str) -> dict:
-    """Fast, deterministic fallback story that avoids any Modal dependency."""
-    hero = (hero_name or "Little Hero").strip() or "Little Hero"
-    beats = THEME_TEMPLATES.get(theme, THEME_TEMPLATES["brave adventure"])
-    pages = [
-        {"page": i + 1, "text": text.format(hero=hero), "scene": scene.format(hero=hero)}
-        for i, (text, scene) in enumerate(beats)
-    ]
-    return {
-        "title": f"{hero}'s Storybook Adventure",
-        "character_description": (
-            f"{hero}, a friendly children's storybook hero with bright colors, "
-            "bold outlines, and a cheerful expressive face"
-        ),
-        "pages": pages,
-    }
-
-
-def silent_wav_bytes(duration_seconds: int = 2, sample_rate: int = 24000) -> bytes:
-    """Return a short silent WAV so the UI remains stable if TTS is unavailable."""
-    num_samples = sample_rate * duration_seconds
-    data_size = num_samples * 2
-    header = struct.pack(
-        "<4sI4s4sIHHIIHH4sI",
-        b"RIFF", 36 + data_size, b"WAVE",
-        b"fmt ", 16, 1, 1, sample_rate, sample_rate * 2, 2, 16,
-        b"data", data_size,
-    )
-    return header + (b"\x00" * data_size)
-
-
-def _with_heartbeat(blocking_fn, frame_fn, poll=4.0):
-    import threading
-
-    box = {}
-
-    def _run():
-        try:
-            box["val"] = blocking_fn()
-        except BaseException as e:
-            box["err"] = e
-
-    th = threading.Thread(target=_run, daemon=True)
-    th.start()
-    t0 = time.time()
-    while th.is_alive():
-        th.join(timeout=poll)
-        if th.is_alive():
-            yield ("hb", frame_fn(int(time.time() - t0)))
-    if "err" in box:
-        raise box["err"]
-    yield ("done", box["val"])
-
-
-# ============================================================================
-# SAMPLE BOOK (loads instantly, no GPU needed)
-# ============================================================================
-
-SAMPLE_BOOK_HTML = None
-
-def load_sample_book() -> str:
-    """Load pre-generated sample book (C3: always ship sample)."""
-    global SAMPLE_BOOK_HTML
-    if SAMPLE_BOOK_HTML:
-        return SAMPLE_BOOK_HTML
-    
-    sample_path = os.path.join(SAMPLE_BOOK_PATH, "sample.html")
-    if os.path.exists(sample_path):
-        with open(sample_path, "r", encoding="utf-8") as f:
-            SAMPLE_BOOK_HTML = f.read()
-        return SAMPLE_BOOK_HTML
-    
-    return "<div class='page-loading'>Loading sample book...</div>"
-
-
-# ============================================================================
-# ZEROGPU INFERENCE FUNCTIONS
-# ============================================================================
-
-@spaces.GPU(duration=60)
-def generate_story_gpu(hero_name: str, theme: str, age: int = 5) -> dict:
-    """Generate a story on ZeroGPU, falling back to a deterministic local story."""
-    global _STORY_MODEL, _STORY_TOKENIZER
-    try:
-        from transformers import AutoTokenizer, AutoModelForCausalLM
-
-        if _STORY_MODEL is None or _STORY_TOKENIZER is None:
-            logger.info(f"Loading story model: {STORY_MODEL.hub_id}")
-            _STORY_TOKENIZER = AutoTokenizer.from_pretrained(STORY_MODEL.hub_id, trust_remote_code=True)
-            _STORY_MODEL = AutoModelForCausalLM.from_pretrained(
-                STORY_MODEL.hub_id,
-                torch_dtype=torch.float16,
-                trust_remote_code=True,
-            ).cuda().eval()
-
-        prompt = build_story_prompt(hero_name, theme, age)
-        inputs = _STORY_TOKENIZER.apply_chat_template(
-            [{"role": "user", "content": prompt}],
-            add_generation_prompt=True,
-            enable_thinking=False,
-            return_dict=True,
-            return_tensors="pt",
-        ).to("cuda")
-        with torch.no_grad():
-            out = _STORY_MODEL.generate(
-                **inputs,
-                max_new_tokens=GENERATION_PARAMS.max_story_tokens,
-                do_sample=False,
-            )
-        response = _STORY_TOKENIZER.decode(
-            out[0][inputs["input_ids"].shape[1]:],
-            skip_special_tokens=True,
-        )
-        parsed = parse_story_json(response)
-        if parsed:
-            return _normalize_story(parsed)
-        logger.warning("Story parser failed; using deterministic local fallback")
-    except Exception as e:
-        logger.warning(f"ZeroGPU story generation failed: {e}")
-    return _normalize_story(build_story_locally(hero_name, theme))
-
-
-def _get_image_pipe(tiny: bool):
-    global _IMAGE_PIPE, _IMAGE_PIPE_KIND
-    desired = "tiny" if tiny else "flux"
-    if _IMAGE_PIPE is not None and _IMAGE_PIPE_KIND == desired:
-        return _IMAGE_PIPE
-
-    if tiny:
-        from diffusers import AutoPipelineForText2Image
-        pipe = AutoPipelineForText2Image.from_pretrained(
-            "stabilityai/sd-turbo",
-            torch_dtype=torch.float16,
-        ).cuda()
-    else:
-        from diffusers import Flux2KleinPipeline
-        pipe = Flux2KleinPipeline.from_pretrained(
-            FLUX_MODEL.hub_id,
-            torch_dtype=torch.bfloat16,
-        ).cuda()
-        pipe.enable_model_cpu_offload()
-
-    _IMAGE_PIPE = pipe
-    _IMAGE_PIPE_KIND = desired
-    return pipe
-
-
-@spaces.GPU(duration=120)
-def generate_images_gpu(
-    character_desc: str,
-    scenes: list,
-    doodle_bytes: bytes = None,
-    seed: int = 42,
-    tiny: bool = False
-) -> list:
-    """Generate all 6 images using FLUX on ZeroGPU."""
-    import io
-    from PIL import Image
-    
-    pipe = _get_image_pipe(tiny)
-    if tiny:
-        num_steps = 4
-        guidance = 0.0
-    else:
-        num_steps = 6
-        guidance = 1.0
-    
-    canonical = None
-    if doodle_bytes:
-        try:
-            ref = Image.open(io.BytesIO(doodle_bytes)).convert("RGB")
-            kw = dict(
-                prompt=(f"Turn this child's drawing into a clean, friendly, full-body cartoon "
-                        f"character for a children's storybook. Keep the EXACT same creature, "
-                        f"face, and features as the drawing. {COLOR_ART_STYLE}, "
-                        f"plain white background, full character visible, centered."),
-                height=768, width=768, guidance_scale=guidance,
-                num_inference_steps=num_steps,
-                generator=torch.Generator("cuda").manual_seed(seed)
-            )
-            if tiny:
-                kw["prompt"] = f"A friendly cartoon character, {COLOR_ART_STYLE}"
-            else:
-                kw["image"] = ref
-            canonical = pipe(**kw).images[0]
-            logger.info("Canonical character built from doodle")
-        except Exception as e:
-            logger.warning(f"Canonical build failed ({e}); text2img fallback")
-            canonical = None
-    
-    images = []
-    for i, scene in enumerate(scenes):
-        if canonical is not None and not tiny:
-            prompt = f"The same character. {scene}. {COLOR_ART_STYLE}, {COLOR_PAGE_SUFFIX}"
-            kw = dict(image=canonical, prompt=prompt)
-        else:
-            prompt = (
-                f"{character_desc}. Scene: {scene}. {COLOR_ART_STYLE}, "
-                f"white background, centered, full character visible"
-            )
-            kw = dict(prompt=prompt)
-        
-        kw.update(dict(
-            height=768, width=768, guidance_scale=guidance,
-            num_inference_steps=num_steps,
-            generator=torch.Generator("cuda").manual_seed(seed + i + 1)
-        ))
-        
-        image = pipe(**kw).images[0]
-        images.append(image)
-        logger.info(f"Generated page {i+1}/6")
-    
-    return images
-
-
-@spaces.GPU(duration=120)
-def generate_coloring_images_gpu(
-    character_desc: str,
-    scenes: list,
-    doodle_bytes: bytes = None,
-    seed: int = 42,
-    tiny: bool = False
-) -> list:
-    """Generate coloring pages directly with FLUX instead of tracing color pages."""
-    import io
-    from PIL import Image
-
-    pipe = _get_image_pipe(tiny)
-    if tiny:
-        num_steps = 4
-        guidance = 0.0
-    else:
-        num_steps = 6
-        guidance = 1.0
-
-    canonical = None
-    if doodle_bytes:
-        try:
-            ref = Image.open(io.BytesIO(doodle_bytes)).convert("RGB")
-            kw = dict(
-                prompt=(f"Turn this child's drawing into a clean, friendly, full-body cartoon "
-                        f"character for a children's coloring book. Keep the EXACT same creature, "
-                        f"face, and features as the drawing. {LINE_ART_STYLE}, "
-                        f"plain white background, full character visible, centered."),
-                height=768, width=768, guidance_scale=guidance,
-                num_inference_steps=num_steps,
-                generator=torch.Generator('cuda').manual_seed(seed)
-            )
-            if tiny:
-                kw["prompt"] = f"A friendly cartoon character, {LINE_ART_STYLE}"
-            else:
-                kw["image"] = ref
-            canonical = pipe(**kw).images[0]
-            logger.info("Line-art canonical character built from doodle")
-        except Exception as e:
-            logger.warning(f"Line-art canonical build failed ({e}); text2img fallback")
-            canonical = None
-
-    images = []
-    for i, scene in enumerate(scenes):
-        if canonical is not None and not tiny:
-            prompt = f"The same character. {scene}. {LINE_ART_STYLE}, {LINE_ART_SUFFIX}"
-            kw = dict(image=canonical, prompt=prompt)
-        else:
-            prompt = (
-                f"{character_desc}. Scene: {scene}. {LINE_ART_STYLE}, "
-                f"white background, centered, full character visible"
-            )
-            kw = dict(prompt=prompt)
-
-        kw.update(dict(
-            height=768, width=768, guidance_scale=guidance,
-            num_inference_steps=num_steps,
-            generator=torch.Generator("cuda").manual_seed(seed + i + 101)
-        ))
-
-        image = pipe(**kw).images[0]
-        images.append(image)
-        logger.info(f"Generated coloring page {i+1}/6")
-
-    return images
-
-
-@spaces.GPU(duration=30)
-def generate_tts_gpu(text: str, voice: str = DEFAULT_VOICE) -> bytes:
-    """Generate TTS when available; otherwise return a tiny silent WAV."""
-    global _TTS_MODEL
-    import io
-    import numpy as np
-
-    try:
-        from voxcpm import VoxCPM
-        if _TTS_MODEL is None:
-            logger.info(f"Loading TTS model: {TTS_MODEL.hub_id}")
-            _TTS_MODEL = VoxCPM.from_pretrained(TTS_MODEL.hub_id, load_denoiser=False)
-        model = _TTS_MODEL
-
-        design = voice_design(voice)
-
-        import re
-        chunks = [s.strip() for s in re.split(r"(?<=[.!?])\s+", text) if s.strip()]
-        if not chunks:
-            chunks = [text.strip() or "The end."]
-        
-        sr = model.tts_model.sample_rate
-        pause = np.zeros(int(sr * 0.35), dtype=np.float32)
-        pieces = []
-        
-        for i, sentence in enumerate(chunks):
-            wav = model.generate(
-                text=f"{design} {sentence}",
-                cfg_value=2.0,
-                inference_timesteps=10,
-            )
-            pieces.append(np.asarray(wav, dtype=np.float32))
-            if i < len(chunks) - 1:
-                pieces.append(pause)
-        
-        audio = np.concatenate(pieces)
-        import soundfile as sf
-        buf = io.BytesIO()
-        sf.write(buf, audio, sr, format="WAV")
-        return buf.getvalue()
-    
-    except Exception as e:
-        logger.warning(f"TTS unavailable on Space ({e}); returning silent fallback")
-        return silent_wav_bytes()
-
-
-# ============================================================================
-# MAIN BOOK CREATION (Generator for streaming)
-# ============================================================================
-
-def create_book(doodle_image, character_name, theme, hero_name, tiny_mode=False, voice=DEFAULT_VOICE, make_coloring=False):
-    """ZeroGPU copy of the local app flow with heartbeats, timing, and coloring support."""
-    t_total = time.perf_counter()
-    character_name = (character_name or "").strip() or "Little Hero"
-    hero_name = (hero_name or "").strip() or character_name
-
-    trace_data = {
-        "backend": "zerogpu",
-        "hero_name": hero_name,
-        "theme": theme,
-        "tiny_mode": tiny_mode,
-        "voice": voice,
-        "make_coloring": make_coloring,
-        "seed": BASE_SEED,
-        "timestamp": time.strftime("%Y-%m-%d %H:%M:%S")
-    }
-    
-    _no = gr.update(visible=False)
-    _keep = gr.update()
-
-    yield (
-        magic_loader_html("story", hero_name),
-        "Writing the story…",
-        None, _keep, {}, "", json.dumps(trace_data, indent=2),
-        _no, _keep,
-    )
-
-    t_story = time.perf_counter()
-    try:
-        story = generate_story_gpu(hero_name, theme)
-    except Exception as e:
-        logger.error(f"Story generation failed: {e}")
-        yield (
-            f"<div class='page-loading'>Error: {e}</div>",
-            f"Error: {e}",
-            None, _keep, {}, "", "",
-            _no, _keep,
-        )
-        return
-    trace_data["story_sec"] = round(time.perf_counter() - t_story, 2)
-
-    pages = story.get("pages", [])
-    char_desc = story.get("character_description", "")
-    title = story.get("title", "Untitled Story")
-    page_texts = [p.get("text", "") for p in pages]
-    scenes = [p.get("scene", "") for p in pages]
-    
-    trace_data["title"] = title
-    trace_data["character_description"] = char_desc
-    
-    yield (
-        magic_loader_html("images", hero_name),
-        f"{title} — illustrating on ZeroGPU…",
-        None, _keep, story, "", json.dumps(trace_data, indent=2),
-        _no, _keep,
-    )
-
-    doodle_bytes = None
-    if doodle_image is not None:
-        import io
-        from PIL import Image
-        img = Image.fromarray(doodle_image)
-        buf = io.BytesIO()
-        img.save(buf, format="PNG")
-        doodle_bytes = buf.getvalue()
-
-    import threading
-    voice_box = {}
-    full_text = f"{title}. {' '.join(page_texts)}"
-    t_tts = time.perf_counter()
-
-    def _do_voice():
-        try:
-            voice_box["bytes"] = generate_tts_gpu(full_text, voice)
-        except Exception as e:
-            voice_box["err"] = e
-
-    voice_thread = threading.Thread(target=_do_voice, daemon=True)
-    voice_thread.start()
-
-    img_bytes, engine = None, "sketch"
-    t_images = time.perf_counter()
-    try:
-        for kind, payload in _with_heartbeat(
-            lambda: generate_images_gpu(char_desc, scenes, doodle_bytes, BASE_SEED, tiny_mode),
-            lambda s: (
-                magic_loader_html("images", hero_name),
-                f"{title} — illustrating… {s}s  (voice recording in parallel)",
-                None, _keep, story, "", json.dumps(trace_data, indent=2), _no, _keep,
-            ),
-        ):
-            if kind == "hb":
-                yield payload
-            else:
-                images = payload
-        import io
-        img_bytes = []
-        for img in images:
-            buf = io.BytesIO()
-            img.save(buf, format="PNG")
-            img_bytes.append(buf.getvalue())
-        engine = "flux"
-    except Exception as e:
-        logger.error(f"Image generation failed: {e}")
-        from services.images import generate_placeholder_images
-        img_bytes = generate_placeholder_images(char_desc, scenes, doodle_bytes)
-        engine = "sketch"
-    trace_data["images_sec"] = round(time.perf_counter() - t_images, 2)
-    trace_data["engine"] = engine
-
-    book_html = build_book_html(img_bytes, page_texts, title, engine)
-
-    while voice_thread.is_alive():
-        voice_thread.join(timeout=4)
-        if voice_thread.is_alive():
-            yield (
-                book_html,
-                f"{title} — finishing narration…",
-                None, _keep, story, "", json.dumps(trace_data, indent=2),
-                _no, _keep,
-            )
-
-    audio_path = None
-    trace_data["tts_sec"] = round(time.perf_counter() - t_tts, 2)
-    if voice_box.get("bytes"):
-        try:
-            with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
-                tmp.write(voice_box["bytes"])
-                audio_path = tmp.name
-        except Exception as e:
-            logger.warning(f"writing audio failed: {e}")
-    elif "err" in voice_box:
-        logger.warning(f"TTS failed: {voice_box['err']}")
-
-    pdf_path = None
-    t_pdf = time.perf_counter()
-    try:
-        with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as tmp:
-            pdf_path = export_pdf(img_bytes, page_texts, title, tmp.name)
-    except Exception as e:
-        logger.warning(f"PDF failed: {e}")
-    trace_data["pdf_sec"] = round(time.perf_counter() - t_pdf, 2)
-
-    coloring_html = ""
-    coloring_pdf_path = None
-    if make_coloring:
-        t_coloring = time.perf_counter()
-        try:
-            from services.coloring import _crispen
-            for kind, payload in _with_heartbeat(
-                lambda: generate_coloring_images_gpu(char_desc, scenes, doodle_bytes, BASE_SEED, tiny_mode),
-                lambda s: (
-                    book_html,
-                    f"{title} — building coloring book… {s}s",
-                    audio_path,
-                    _keep,
-                    story,
-                    "",
-                    json.dumps(trace_data, indent=2),
-                    _no,
-                    _keep,
-                ),
-            ):
-                if kind == "hb":
-                    yield payload
-                else:
-                    coloring_images = payload
-            import io
-            outlines = []
-            for img in coloring_images:
-                buf = io.BytesIO()
-                img.save(buf, format="PNG")
-                outlines.append(_crispen(buf.getvalue()))
-            coloring_html = build_coloring_html(outlines, page_texts, title)
-            with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as tmp:
-                coloring_pdf_path = export_coloring_pdf(outlines, page_texts, title, tmp.name)
-            trace_data["coloring_book"] = True
-            trace_data["coloring_engine"] = "flux-direct-lineart"
-        except Exception as e:
-            logger.warning(f"Direct FLUX coloring book failed ({e}); using traced fallback")
-            try:
-                from services.coloring import derive_coloring_pages
-                outlines = derive_coloring_pages(img_bytes)
-                coloring_html = build_coloring_html(outlines, page_texts, title)
-                with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as tmp:
-                    coloring_pdf_path = export_coloring_pdf(outlines, page_texts, title, tmp.name)
-                trace_data["coloring_book"] = True
-                trace_data["coloring_engine"] = "trace-fallback"
-            except Exception as e2:
-                logger.warning(f"Coloring book fallback failed: {e2}")
-        trace_data["coloring_sec"] = round(time.perf_counter() - t_coloring, 2)
-
-    trace_data["completed"] = True
-    trace_data["pages_generated"] = len(img_bytes)
-    trace_data["total_sec"] = round(time.perf_counter() - t_total, 2)
-
-    pdf_update = gr.update(value=pdf_path) if pdf_path else _keep
-    coloring_pdf_update = gr.update(value=coloring_pdf_path) if coloring_pdf_path else _keep
-    coloring_display_update = (gr.update(visible=True, value=coloring_html) if coloring_html
-                               else _no)
-
-    yield (
-        book_html,
-        f"Complete: {title} — {len(img_bytes)} pages · {'FLUX (ZeroGPU)' if engine == 'flux' else 'local sketch fallback'} · voice: {voice} · total {trace_data['total_sec']}s",
-        audio_path,
-        pdf_update,
-        story,
-        f"Pages: {len(img_bytes)} | Seed: {BASE_SEED} | Mode: {'Tiny' if tiny_mode else 'Standard'} | Engine: {engine} | Story {trace_data.get('story_sec', 0)}s | Images {trace_data.get('images_sec', 0)}s | PDF {trace_data.get('pdf_sec', 0)}s | Coloring {trace_data.get('coloring_sec', 0)}s",
-        json.dumps(trace_data, indent=2),
-        coloring_display_update,
-        coloring_pdf_update,
-    )
-
-
-# ============================================================================
-# MAIN
-# ============================================================================
-
-if __name__ == "__main__":
-    demo = create_layout(
-        load_sample_fn=load_sample_book,
-        create_book_fn=create_book,
-    )
-    demo.queue(default_concurrency_limit=2, max_size=8)
-    demo.launch(share=False, allowed_paths=[tempfile.gettempdir()])
+"""
+DoodleBook — HF ZeroGPU Version
+
+Free T4 GPU on Hugging Face Spaces!
+No Modal needed.
+"""
+
+import gradio as gr
+import os
+import sys
+import torch
+try:
+    import spaces
+except ModuleNotFoundError:
+    # `spaces` only exists on HF ZeroGPU. Off-HF (local/dev) provide a no-op so
+    # the app still runs; generation then uses whatever local GPU/CPU exists.
+    class _SpacesShim:
+        @staticmethod
+        def GPU(*args, **kwargs):
+            if args and callable(args[0]):      # bare @spaces.GPU
+                return args[0]
+            def deco(fn):                       # @spaces.GPU(duration=...)
+                return fn
+            return deco
+    spaces = _SpacesShim()
+import json
+import time
+import tempfile
+import logging
+import struct
+import re
+
+sys.path.insert(0, os.path.dirname(__file__))
+
+from config import (
+    FLUX_MODEL, STORY_MODEL, TTS_MODEL,
+    GENERATION_PARAMS, SAMPLE_BOOK_PATH, BASE_SEED, page_seed,
+    DEFAULT_VOICE, voice_design,
+)
+from book_builder import (
+    build_book_html, export_pdf, magic_loader_html,
+    build_coloring_html, export_coloring_pdf,
+)
+from ui.layout import create_layout
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# ZeroGPU sets SPACES_ZERO_GPU. On the Space we load models on cuda at IMPORT
+# (a CUDA-emulation layer makes that work without a real GPU); lazy-loading
+# inside @spaces.GPU is explicitly discouraged and was why FLUX kept failing
+# → sketch. Guarded so a local/dev import doesn't try to pull ~20GB of weights.
+ON_ZEROGPU = bool(os.environ.get("SPACES_ZERO_GPU"))
+
+_FLUX_PIPE = None
+_STORY_MODEL = None
+_STORY_TOKENIZER = None
+_TTS_MODEL = None
+_LOAD_ERRORS = {}
+
+
+def load_flux():
+    """FLUX image pipeline placed on cuda at module scope (the ZeroGPU pattern).
+    No enable_model_cpu_offload() — that fights ZeroGPU's device management."""
+    global _FLUX_PIPE
+    if _FLUX_PIPE is None:
+        from diffusers import Flux2KleinPipeline
+        logger.info(f"Loading image model: {FLUX_MODEL.hub_id}")
+        pipe = Flux2KleinPipeline.from_pretrained(
+            FLUX_MODEL.hub_id, torch_dtype=torch.bfloat16,
+        )
+        pipe.to("cuda")
+        _FLUX_PIPE = pipe
+    return _FLUX_PIPE
+
+
+def load_story():
+    global _STORY_MODEL, _STORY_TOKENIZER
+    if _STORY_MODEL is None:
+        from transformers import AutoTokenizer, AutoModelForCausalLM
+        logger.info(f"Loading story model: {STORY_MODEL.hub_id}")
+        _STORY_TOKENIZER = AutoTokenizer.from_pretrained(
+            STORY_MODEL.hub_id, trust_remote_code=True,
+        )
+        _STORY_MODEL = AutoModelForCausalLM.from_pretrained(
+            STORY_MODEL.hub_id, torch_dtype=torch.float16, trust_remote_code=True,
+        ).to("cuda").eval()
+    return _STORY_MODEL, _STORY_TOKENIZER
+
+
+def load_tts():
+    global _TTS_MODEL
+    if _TTS_MODEL is None:
+        from voxcpm import VoxCPM
+        logger.info(f"Loading TTS model: {TTS_MODEL.hub_id}")
+        _TTS_MODEL = VoxCPM.from_pretrained(TTS_MODEL.hub_id, load_denoiser=False)
+    return _TTS_MODEL
+
+
+if ON_ZEROGPU:
+    for _name, _loader in (("flux", load_flux), ("story", load_story), ("tts", load_tts)):
+        try:
+            _loader()
+        except Exception as _e:                       # keep the Space booting
+            _LOAD_ERRORS[_name] = repr(_e)
+            logger.exception(f"Module-level load failed for {_name}")
+
+COLOR_ART_STYLE = (
+    "children's crayon storybook illustration, bold black outlines, "
+    "flat bright colors, simple shapes"
+)
+COLOR_PAGE_SUFFIX = "full colorful background scene, the character clearly visible."
+LINE_ART_STYLE = (
+    "children's coloring book page, pure black ink outlines on pure white paper, "
+    "clean contour lines, no color, no gray, no shading, no texture, "
+    "no hatching, no pencil marks, open spaces to color"
+)
+LINE_ART_SUFFIX = (
+    "simple clean background shapes, same composition, thick readable outlines, "
+    "no filled black areas, no extra sketch marks."
+)
+
+THEME_TEMPLATES = {
+    "brave adventure": [
+        ("{hero} loved exploring new places.", "{hero} standing at the start of a bright adventure trail"),
+        ("One morning, {hero} discovered something glowing nearby.", "{hero} spotting a magical glow in the distance"),
+        ("Taking a deep breath, {hero} bravely went closer.", "{hero} walking forward with courage"),
+        ("There, a new friend needed help.", "{hero} finding a small friend in trouble"),
+        ("{hero} helped with kindness and a clever idea.", "{hero} helping the friend together"),
+        ("Everyone cheered, and {hero} felt proud and brave.", "{hero} celebrating at sunset with the new friend"),
+    ],
+    "making a new friend": [
+        ("{hero} was playing alone in a sunny place.", "{hero} playing under a bright sky"),
+        ("Then {hero} noticed someone shy nearby.", "{hero} seeing a shy new friend nearby"),
+        ("{hero} smiled and said hello.", "{hero} waving with a friendly smile"),
+        ("Soon they were sharing stories and laughs.", "{hero} and the new friend laughing together"),
+        ("They played games all afternoon.", "{hero} and the new friend playing together"),
+        ("By sunset, {hero} had made a wonderful new friend.", "{hero} and the new friend smiling together at sunset"),
+    ],
+}
+
+FEW_SHOT_EXEMPLAR = """
+Write a 6-page children's storybook for age 5 about Luna the cat with theme: brave adventure.
+
+Return ONLY valid JSON:
+{
+  "title": "Luna's Brave Adventure",
+  "character_description": "A small orange tabby cat named Luna with big green eyes, whiskers, and a tiny red scarf",
+  "pages": [
+    {"page": 1, "text": "Luna was a small orange cat who loved to explore.", "scene": "Luna sitting by the window looking outside"},
+    {"page": 2, "text": "One sunny morning, Luna saw something sparkling in the forest.", "scene": "Luna spotting a glow in the trees"},
+    {"page": 3, "text": "Bravely, Luna crept into the forest to investigate.", "scene": "Luna walking cautiously through trees"},
+    {"page": 4, "text": "It was a tiny fairy stuck in a spider web!", "scene": "Luna discovering a fairy in trouble"},
+    {"page": 5, "text": "Luna gently freed the fairy with her paw.", "scene": "Luna carefully helping the fairy"},
+    {"page": 6, "text": "The fairy thanked Luna and they became friends forever.", "scene": "Luna and fairy playing together at sunset"}
+  ]
+}
+"""
+
+
+def build_story_prompt(hero_name: str, theme: str, age: int) -> str:
+    return f"""{FEW_SHOT_EXEMPLAR}
+
+Write a 6-page children's storybook for age {age} about {hero_name} with theme: {theme}.
+
+Return ONLY valid JSON:
+"""
+
+
+def _validate_story_structure(story: dict) -> bool:
+    required_keys = ["title", "character_description", "pages"]
+    if not all(k in story for k in required_keys):
+        return False
+    pages = story.get("pages", [])
+    if not isinstance(pages, list) or len(pages) < 1:
+        return False
+    first_page = pages[0]
+    return all(k in first_page for k in ["page", "text", "scene"])
+
+
+def _repair_json(json_str: str) -> str:
+    json_str = re.sub(r',\s*([}\]])', r'\1', json_str)
+    json_str = re.sub(r'//.*?$', '', json_str, flags=re.MULTILINE)
+    json_str = re.sub(r'/\*[\s\S]*?\*/', '', json_str)
+    json_str = re.sub(r'(?<=")\n(?=")', '\\n', json_str)
+    json_str = re.sub(r'(\s)(\w+)(\s*:)', r'\1"\2"\3', json_str)
+    return json_str
+
+
+def parse_story_json(raw_output: str) -> dict | None:
+    match = re.search(r'\{[\s\S]*\}', raw_output or "")
+    if not match:
+        return None
+    raw_json = match.group(0)
+    for candidate in (raw_json, _repair_json(raw_json)):
+        try:
+            story = json.loads(candidate)
+            if _validate_story_structure(story):
+                return story
+        except Exception:
+            continue
+    return None
+
+
+def _normalize_story(story: dict) -> dict:
+    pages = list(story.get("pages", []))[:6]
+    while len(pages) < 6:
+        pages.append({
+            "page": len(pages) + 1,
+            "text": "And the adventure continued happily.",
+            "scene": "Continuing adventure",
+        })
+    story["pages"] = pages
+    story.setdefault("title", "A Wonderful Adventure")
+    story.setdefault(
+        "character_description",
+        "A friendly children's storybook hero with bright colors and cheerful features",
+    )
+    return story
+
+
+def build_story_locally(hero_name: str, theme: str) -> dict:
+    """Fast, deterministic fallback story that avoids any Modal dependency."""
+    hero = (hero_name or "Little Hero").strip() or "Little Hero"
+    beats = THEME_TEMPLATES.get(theme, THEME_TEMPLATES["brave adventure"])
+    pages = [
+        {"page": i + 1, "text": text.format(hero=hero), "scene": scene.format(hero=hero)}
+        for i, (text, scene) in enumerate(beats)
+    ]
+    return {
+        "title": f"{hero}'s Storybook Adventure",
+        "character_description": (
+            f"{hero}, a friendly children's storybook hero with bright colors, "
+            "bold outlines, and a cheerful expressive face"
+        ),
+        "pages": pages,
+    }
+
+
+def silent_wav_bytes(duration_seconds: int = 2, sample_rate: int = 24000) -> bytes:
+    """Return a short silent WAV so the UI remains stable if TTS is unavailable."""
+    num_samples = sample_rate * duration_seconds
+    data_size = num_samples * 2
+    header = struct.pack(
+        "<4sI4s4sIHHIIHH4sI",
+        b"RIFF", 36 + data_size, b"WAVE",
+        b"fmt ", 16, 1, 1, sample_rate, sample_rate * 2, 2, 16,
+        b"data", data_size,
+    )
+    return header + (b"\x00" * data_size)
+
+
+def _with_heartbeat(blocking_fn, frame_fn, poll=4.0):
+    import threading
+
+    box = {}
+
+    def _run():
+        try:
+            box["val"] = blocking_fn()
+        except BaseException as e:
+            box["err"] = e
+
+    th = threading.Thread(target=_run, daemon=True)
+    th.start()
+    t0 = time.time()
+    while th.is_alive():
+        th.join(timeout=poll)
+        if th.is_alive():
+            yield ("hb", frame_fn(int(time.time() - t0)))
+    if "err" in box:
+        raise box["err"]
+    yield ("done", box["val"])
+
+
+# ============================================================================
+# SAMPLE BOOK (loads instantly, no GPU needed)
+# ============================================================================
+
+SAMPLE_BOOK_HTML = None
+
+def load_sample_book() -> str:
+    """Load pre-generated sample book (C3: always ship sample)."""
+    global SAMPLE_BOOK_HTML
+    if SAMPLE_BOOK_HTML:
+        return SAMPLE_BOOK_HTML
+    
+    sample_path = os.path.join(SAMPLE_BOOK_PATH, "sample.html")
+    if os.path.exists(sample_path):
+        with open(sample_path, "r", encoding="utf-8") as f:
+            SAMPLE_BOOK_HTML = f.read()
+        return SAMPLE_BOOK_HTML
+    
+    return "<div class='page-loading'>Loading sample book...</div>"
+
+
+# ============================================================================
+# ZEROGPU INFERENCE FUNCTIONS
+# ============================================================================
+
+@spaces.GPU(duration=60)
+def generate_story_gpu(hero_name: str, theme: str, age: int = 5) -> dict:
+    """Generate a story on ZeroGPU, falling back to a deterministic local story."""
+    try:
+        model, tok = load_story()
+        prompt = build_story_prompt(hero_name, theme, age)
+        inputs = tok.apply_chat_template(
+            [{"role": "user", "content": prompt}],
+            add_generation_prompt=True,
+            enable_thinking=False,
+            return_dict=True,
+            return_tensors="pt",
+        ).to("cuda")
+        with torch.no_grad():
+            out = model.generate(
+                **inputs,
+                max_new_tokens=GENERATION_PARAMS.max_story_tokens,
+                do_sample=False,
+            )
+        response = tok.decode(
+            out[0][inputs["input_ids"].shape[1]:],
+            skip_special_tokens=True,
+        )
+        parsed = parse_story_json(response)
+        if parsed:
+            return _normalize_story(parsed)
+        logger.warning("Story parser failed; using deterministic local fallback")
+    except Exception as e:
+        logger.warning(f"ZeroGPU story generation failed: {e}")
+    return _normalize_story(build_story_locally(hero_name, theme))
+
+
+@spaces.GPU(duration=150)
+def generate_images_gpu(
+    character_desc: str,
+    scenes: list,
+    doodle_bytes: bytes = None,
+    seed: int = 42,
+) -> list:
+    """Generate all story pages with FLUX on ZeroGPU (two-stage: canonical
+    character from the doodle, then the same character in each scene)."""
+    import io
+    from PIL import Image
+
+    pipe = load_flux()
+    num_steps, guidance = 6, 1.0
+
+    canonical = None
+    if doodle_bytes:
+        try:
+            ref = Image.open(io.BytesIO(doodle_bytes)).convert("RGB")
+            canonical = pipe(
+                prompt=(f"Turn this child's drawing into a clean, friendly, full-body cartoon "
+                        f"character for a children's storybook. Keep the EXACT same creature, "
+                        f"face, and features as the drawing. {COLOR_ART_STYLE}, "
+                        f"plain white background, full character visible, centered."),
+                image=ref, height=768, width=768, guidance_scale=guidance,
+                num_inference_steps=num_steps,
+                generator=torch.Generator("cuda").manual_seed(seed),
+            ).images[0]
+            logger.info("Canonical character built from doodle")
+        except Exception as e:
+            logger.warning(f"Canonical build failed ({e}); text2img fallback")
+            canonical = None
+
+    images = []
+    for i, scene in enumerate(scenes):
+        if canonical is not None:
+            prompt = f"The same character. {scene}. {COLOR_ART_STYLE}, {COLOR_PAGE_SUFFIX}"
+            kw = dict(image=canonical, prompt=prompt)
+        else:
+            prompt = (f"{character_desc}. Scene: {scene}. {COLOR_ART_STYLE}, "
+                      f"white background, centered, full character visible")
+            kw = dict(prompt=prompt)
+        kw.update(height=768, width=768, guidance_scale=guidance,
+                  num_inference_steps=num_steps,
+                  generator=torch.Generator("cuda").manual_seed(seed + i + 1))
+        images.append(pipe(**kw).images[0])
+        logger.info(f"Generated page {i+1}/{len(scenes)}")
+    return images
+
+
+@spaces.GPU(duration=150)
+def generate_coloring_images_gpu(
+    character_desc: str,
+    scenes: list,
+    doodle_bytes: bytes = None,
+    seed: int = 42,
+) -> list:
+    """Generate coloring pages directly with FLUX as line art (no tracing)."""
+    import io
+    from PIL import Image
+
+    pipe = load_flux()
+    num_steps, guidance = 6, 1.0
+
+    canonical = None
+    if doodle_bytes:
+        try:
+            ref = Image.open(io.BytesIO(doodle_bytes)).convert("RGB")
+            canonical = pipe(
+                prompt=(f"Turn this child's drawing into a clean, friendly, full-body cartoon "
+                        f"character for a children's coloring book. Keep the EXACT same creature, "
+                        f"face, and features as the drawing. {LINE_ART_STYLE}, "
+                        f"plain white background, full character visible, centered."),
+                image=ref, height=768, width=768, guidance_scale=guidance,
+                num_inference_steps=num_steps,
+                generator=torch.Generator("cuda").manual_seed(seed),
+            ).images[0]
+            logger.info("Line-art canonical character built from doodle")
+        except Exception as e:
+            logger.warning(f"Line-art canonical build failed ({e}); text2img fallback")
+            canonical = None
+
+    images = []
+    for i, scene in enumerate(scenes):
+        if canonical is not None:
+            prompt = f"The same character. {scene}. {LINE_ART_STYLE}, {LINE_ART_SUFFIX}"
+            kw = dict(image=canonical, prompt=prompt)
+        else:
+            prompt = (f"{character_desc}. Scene: {scene}. {LINE_ART_STYLE}, "
+                      f"white background, centered, full character visible")
+            kw = dict(prompt=prompt)
+        kw.update(height=768, width=768, guidance_scale=guidance,
+                  num_inference_steps=num_steps,
+                  generator=torch.Generator("cuda").manual_seed(seed + i + 101))
+        images.append(pipe(**kw).images[0])
+        logger.info(f"Generated coloring page {i+1}/{len(scenes)}")
+    return images
+
+
+@spaces.GPU(duration=120)
+def generate_tts_gpu(text: str, voice: str = DEFAULT_VOICE) -> bytes:
+    """Narrate the book with VoxCPM2. Raises on failure so the caller can show
+    the real reason instead of silently shipping a silent clip."""
+    import io
+    import numpy as np
+
+    try:
+        model = load_tts()
+        design = voice_design(voice)
+
+        import re
+        chunks = [s.strip() for s in re.split(r"(?<=[.!?])\s+", text) if s.strip()]
+        if not chunks:
+            chunks = [text.strip() or "The end."]
+        
+        sr = model.tts_model.sample_rate
+        pause = np.zeros(int(sr * 0.35), dtype=np.float32)
+        pieces = []
+        
+        for i, sentence in enumerate(chunks):
+            wav = model.generate(
+                text=f"{design} {sentence}",
+                cfg_value=2.0,
+                inference_timesteps=10,
+            )
+            pieces.append(np.asarray(wav, dtype=np.float32))
+            if i < len(chunks) - 1:
+                pieces.append(pause)
+        
+        audio = np.concatenate(pieces)
+        import soundfile as sf
+        buf = io.BytesIO()
+        sf.write(buf, audio, sr, format="WAV")
+        return buf.getvalue()
+    
+    except Exception as e:
+        # Surface the real reason (e.g. missing model) instead of a silent clip
+        # that looks like it worked. create_book records this in the trace.
+        logger.exception("TTS failed")
+        raise
+
+
+# ============================================================================
+# MAIN BOOK CREATION (Generator for streaming)
+# ============================================================================
+
+def create_book(doodle_image, character_name, theme, hero_name, voice=DEFAULT_VOICE, make_coloring=False):
+    """ZeroGPU book flow: story → images → narration → PDFs → coloring book,
+    each a sequential @spaces.GPU call (ZeroGPU has one GPU per request)."""
+    t_total = time.perf_counter()
+    character_name = (character_name or "").strip() or "Little Hero"
+    hero_name = (hero_name or "").strip() or character_name
+
+    trace_data = {
+        "backend": "zerogpu",
+        "hero_name": hero_name,
+        "theme": theme,
+        "voice": voice,
+        "make_coloring": make_coloring,
+        "seed": BASE_SEED,
+        "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
+    }
+    if _LOAD_ERRORS:
+        trace_data["model_load_errors"] = _LOAD_ERRORS
+    
+    _no = gr.update(visible=False)
+    _keep = gr.update()
+
+    yield (
+        magic_loader_html("story", hero_name),
+        "Writing the story…",
+        None, _keep, {}, "", json.dumps(trace_data, indent=2),
+        _no, _keep,
+    )
+
+    t_story = time.perf_counter()
+    try:
+        story = generate_story_gpu(hero_name, theme)
+    except Exception as e:
+        logger.error(f"Story generation failed: {e}")
+        yield (
+            f"<div class='page-loading'>Error: {e}</div>",
+            f"Error: {e}",
+            None, _keep, {}, "", "",
+            _no, _keep,
+        )
+        return
+    trace_data["story_sec"] = round(time.perf_counter() - t_story, 2)
+
+    pages = story.get("pages", [])
+    char_desc = story.get("character_description", "")
+    title = story.get("title", "Untitled Story")
+    page_texts = [p.get("text", "") for p in pages]
+    scenes = [p.get("scene", "") for p in pages]
+    
+    trace_data["title"] = title
+    trace_data["character_description"] = char_desc
+    
+    yield (
+        magic_loader_html("images", hero_name),
+        f"{title} — illustrating on ZeroGPU…",
+        None, _keep, story, "", json.dumps(trace_data, indent=2),
+        _no, _keep,
+    )
+
+    doodle_bytes = None
+    if doodle_image is not None:
+        import io
+        from PIL import Image
+        img = Image.fromarray(doodle_image)
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        doodle_bytes = buf.getvalue()
+
+    full_text = f"{title}. {' '.join(page_texts)}"
+
+    # ---- IMAGES (FLUX on ZeroGPU) ----
+    img_bytes, engine = None, "sketch"
+    t_images = time.perf_counter()
+    try:
+        for kind, payload in _with_heartbeat(
+            lambda: generate_images_gpu(char_desc, scenes, doodle_bytes, BASE_SEED),
+            lambda s: (
+                magic_loader_html("images", hero_name),
+                f"{title} — illustrating on ZeroGPU… {s}s",
+                None, _keep, story, "", json.dumps(trace_data, indent=2), _no, _keep,
+            ),
+        ):
+            if kind == "hb":
+                yield payload
+            else:
+                images = payload
+        import io
+        img_bytes = []
+        for img in images:
+            buf = io.BytesIO()
+            img.save(buf, format="PNG")
+            img_bytes.append(buf.getvalue())
+        engine = "flux"
+    except Exception as e:
+        logger.exception("Image generation failed")
+        trace_data["image_error"] = repr(e)
+        from services.images import generate_placeholder_images
+        img_bytes = generate_placeholder_images(char_desc, scenes, doodle_bytes)
+        engine = "sketch"
+    trace_data["images_sec"] = round(time.perf_counter() - t_images, 2)
+    trace_data["engine"] = engine
+
+    book_html = build_book_html(img_bytes, page_texts, title, engine)
+
+    # ---- NARRATION (VoxCPM2 on ZeroGPU) — sequential: one GPU per request ----
+    audio_path = None
+    t_tts = time.perf_counter()
+    try:
+        for kind, payload in _with_heartbeat(
+            lambda: generate_tts_gpu(full_text, voice),
+            lambda s: (
+                book_html,
+                f"{title} — recording the narration… {s}s",
+                None, _keep, story, "", json.dumps(trace_data, indent=2), _no, _keep,
+            ),
+        ):
+            if kind == "hb":
+                yield payload
+            else:
+                voice_bytes = payload
+        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
+            tmp.write(voice_bytes)
+            audio_path = tmp.name
+    except Exception as e:
+        logger.exception("TTS failed")
+        trace_data["tts_error"] = repr(e)
+    trace_data["tts_sec"] = round(time.perf_counter() - t_tts, 2)
+
+    pdf_path = None
+    t_pdf = time.perf_counter()
+    try:
+        with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as tmp:
+            pdf_path = export_pdf(img_bytes, page_texts, title, tmp.name)
+    except Exception as e:
+        logger.warning(f"PDF failed: {e}")
+    trace_data["pdf_sec"] = round(time.perf_counter() - t_pdf, 2)
+
+    coloring_html = ""
+    coloring_pdf_path = None
+    if make_coloring:
+        t_coloring = time.perf_counter()
+        try:
+            from services.coloring import _crispen
+            for kind, payload in _with_heartbeat(
+                lambda: generate_coloring_images_gpu(char_desc, scenes, doodle_bytes, BASE_SEED),
+                lambda s: (
+                    book_html,
+                    f"{title} — building coloring book… {s}s",
+                    audio_path,
+                    _keep,
+                    story,
+                    "",
+                    json.dumps(trace_data, indent=2),
+                    _no,
+                    _keep,
+                ),
+            ):
+                if kind == "hb":
+                    yield payload
+                else:
+                    coloring_images = payload
+            import io
+            outlines = []
+            for img in coloring_images:
+                buf = io.BytesIO()
+                img.save(buf, format="PNG")
+                outlines.append(_crispen(buf.getvalue()))
+            coloring_html = build_coloring_html(outlines, page_texts, title)
+            with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as tmp:
+                coloring_pdf_path = export_coloring_pdf(outlines, page_texts, title, tmp.name)
+            trace_data["coloring_book"] = True
+            trace_data["coloring_engine"] = "flux-direct-lineart"
+        except Exception as e:
+            logger.warning(f"Direct FLUX coloring book failed ({e}); using traced fallback")
+            try:
+                from services.coloring import derive_coloring_pages
+                outlines = derive_coloring_pages(img_bytes)
+                coloring_html = build_coloring_html(outlines, page_texts, title)
+                with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as tmp:
+                    coloring_pdf_path = export_coloring_pdf(outlines, page_texts, title, tmp.name)
+                trace_data["coloring_book"] = True
+                trace_data["coloring_engine"] = "trace-fallback"
+            except Exception as e2:
+                logger.warning(f"Coloring book fallback failed: {e2}")
+        trace_data["coloring_sec"] = round(time.perf_counter() - t_coloring, 2)
+
+    trace_data["completed"] = True
+    trace_data["pages_generated"] = len(img_bytes)
+    trace_data["total_sec"] = round(time.perf_counter() - t_total, 2)
+
+    pdf_update = gr.update(value=pdf_path) if pdf_path else _keep
+    coloring_pdf_update = gr.update(value=coloring_pdf_path) if coloring_pdf_path else _keep
+    coloring_display_update = (gr.update(visible=True, value=coloring_html) if coloring_html
+                               else _no)
+
+    yield (
+        book_html,
+        f"Complete: {title} — {len(img_bytes)} pages · {'FLUX (ZeroGPU)' if engine == 'flux' else 'local sketch fallback'} · voice: {voice} · total {trace_data['total_sec']}s",
+        audio_path,
+        pdf_update,
+        story,
+        f"Pages: {len(img_bytes)} | Seed: {BASE_SEED} | Engine: {engine} | Story {trace_data.get('story_sec', 0)}s | Images {trace_data.get('images_sec', 0)}s | PDF {trace_data.get('pdf_sec', 0)}s | Coloring {trace_data.get('coloring_sec', 0)}s",
+        json.dumps(trace_data, indent=2),
+        coloring_display_update,
+        coloring_pdf_update,
+    )
+
+
+# ============================================================================
+# MAIN
+# ============================================================================
+
+if __name__ == "__main__":
+    demo = create_layout(
+        load_sample_fn=load_sample_book,
+        create_book_fn=create_book,
+    )
+    demo.queue(default_concurrency_limit=2, max_size=8)
+    demo.launch(share=False, allowed_paths=[tempfile.gettempdir()])

app_zerogpu.py

@@ -1,152 +0,0 @@
-"""
-DoodleBook — ZeroGPU Version (Free HF Hosting)
-
-Runs directly on HF ZeroGPU without Modal.
-Slower but completely free.
-"""
-
-import gradio as gr
-import os
-import sys
-import torch
-from pathlib import Path
-
-sys.path.insert(0, os.path.dirname(__file__))
-
-from config import FLUX_MODEL, STORY_MODEL, GENERATION_PARAMS, BASE_SEED
-
-
-# ============================================================================
-# ZEROGPU INFERENCE (No Modal)
-# ============================================================================
-
-@torch.inference_mode()
-def generate_story_zerogpu(hero_name: str, theme: str, age: int = 5) -> dict:
-    """Generate story using MiniCPM5-1B on ZeroGPU."""
-    from transformers import AutoTokenizer, AutoModelForCausalLM
-    
-    model_id = STORY_MODEL.hub_id
-    tok = AutoTokenizer.from_pretrained(model_id)
-    model = AutoModelForCausalLM.from_pretrained(
-        model_id, torch_dtype=torch.float16
-    ).cuda().eval()
-    
-    prompt = f"""Write a 6-page children's storybook for age {age} about {hero_name} with theme: {theme}.
-Return ONLY valid JSON:
-{{"title": "Title", "character_description": "Description", "pages": [{{"page": 1, "text": "Text", "scene": "Scene"}}]}}"""
-    
-    inputs = tok(prompt, return_tensors="pt").cuda()
-    with torch.no_grad():
-        out = model.generate(**inputs, max_new_tokens=800, do_sample=False)
-    
-    response = tok.decode(out[0][inputs.input_ids.shape[1]:], skip_special_tokens=True)
-    
-    # Parse JSON
-    import re, json
-    match = re.search(r'\{.*\}', response, re.DOTALL)
-    if match:
-        try:
-            return json.loads(match.group())
-        except:
-            pass
-    
-    # Fallback
-    return {
-        "title": f"{hero_name}'s Adventure",
-        "character_description": f"A friendly character named {hero_name}",
-        "pages": [{"page": i+1, "text": f"Page {i+1} text", "scene": f"Scene {i+1}"} for i in range(6)]
-    }
-
-
-@torch.inference_mode()
-def generate_images_zerogpu(character_desc: str, scenes: list) -> list:
-    """Generate images using FLUX on ZeroGPU."""
-    from diffusers import FluxPipeline
-    
-    pipe = FluxPipeline.from_pretrained(
-        FLUX_MODEL.hub_id,
-        torch_dtype=torch.bfloat16
-    ).cuda()
-    
-    images = []
-    for i, scene in enumerate(scenes):
-        prompt = f"{character_desc}, {scene}, crayon drawing style"
-        generator = torch.Generator("cuda").manual_seed(BASE_SEED + i)
-        
-        image = pipe(
-            prompt=prompt,
-            num_inference_steps=20,
-            guidance_scale=3.5,
-            width=768,
-            height=512,
-            generator=generator
-        ).images[0]
-        
-        images.append(image)
-    
-    return images
-
-
-# ============================================================================
-# MAIN FUNCTION (ZeroGPU compatible)
-# ============================================================================
-
-def create_book_zerogpu(doodle_image, character_name, theme, hero_name, tiny_mode=False):
-    """
-    Book creation without Modal.
-    Uses ZeroGPU for inference.
-    """
-    import time
-    from book_builder import build_book_html
-    import io, base64
-    
-    # Generate story
-    story = generate_story_zerogpu(hero_name, theme)
-    title = story.get("title", "Story")
-    pages = story.get("pages", [])
-    char_desc = story.get("character_description", "")
-    scenes = [p.get("scene", "") for p in pages]
-    texts = [p.get("text", "") for p in pages]
-    
-    # Generate images
-    images = generate_images_zerogpu(char_desc, scenes)
-    
-    # Convert to bytes
-    img_bytes = []
-    for img in images:
-        buf = io.BytesIO()
-        img.save(buf, format="PNG")
-        img_bytes.append(buf.getvalue())
-    
-    # Build HTML
-    html = build_book_html(img_bytes, texts, title)
-    
-    return html, f"Complete: {title}", None, None
-
-
-# ============================================================================
-# GRADIO UI
-# ============================================================================
-
-if __name__ == "__main__":
-    with gr.Blocks(title="DoodleBook (Free)") as demo:
-        gr.Markdown("# 📚 DoodleBook (ZeroGPU Version)")
-        
-        with gr.Row():
-            with gr.Column():
-                doodle = gr.Image(label="Doodle", type="numpy")
-                name = gr.Textbox(label="Character name")
-                theme = gr.Dropdown(["brave adventure", "making a friend"], label="Theme")
-                btn = gr.Button("Make book!")
-            
-            with gr.Column():
-                output = gr.HTML()
-                status = gr.Textbox(label="Status")
-        
-        btn.click(
-            create_book_zerogpu,
-            inputs=[doodle, name, theme, name],
-            outputs=[output, status]
-        )
-    
-    demo.launch()

config.py

@@ -86,56 +86,24 @@ class ModelConfig:
 # Fallbacks selected for license compatibility (Apache 2.0 preferred).
 #
 
+# The three sponsor models DoodleBook actually loads. Fallback/variant configs
+# were removed so the HF Space links exactly these three (HF auto-links any
+# model id it finds in the repo files).
+
 FLUX_MODEL = ModelConfig(
     hub_id="black-forest-labs/FLUX.2-klein-4B",
     params_b=4.0,
     license=LicenseType.APACHE_2_0,
     vram_gb=13.0,
-    fallback_id="black-forest-labs/FLUX.1-schnell",
-    fallback_reason="12B, Apache 2.0, 1-4 step distilled, fast inference",
     modal_gpu="A10G",  # 24GB fits the ~13GB model; A100-40GB was overkill
     modal_memory=32768,
 )
 
-FLUX_MODEL_9B = ModelConfig(
-    hub_id="black-forest-labs/FLUX.2-klein-9B",
-    params_b=9.0,
-    license=LicenseType.NON_COMMERCIAL,
-    vram_gb=29.0,
-    fallback_id="black-forest-labs/FLUX.2-klein-4B",
-    fallback_reason="4B variant with Apache 2.0 license",
-    is_primary=False,
-    modal_gpu="A100",
-    modal_memory=32768,
-)
-
-FLUX_FALLBACK = ModelConfig(
-    hub_id="black-forest-labs/FLUX.1-schnell",
-    params_b=12.0,
-    license=LicenseType.APACHE_2_0,
-    vram_gb=24.0,
-    is_primary=False,
-    modal_gpu="A100",
-    modal_memory=32768,
-)
-
 STORY_MODEL = ModelConfig(
     hub_id="openbmb/MiniCPM5-1B",
     params_b=1.0,
     license=LicenseType.APACHE_2_0,
     vram_gb=4.0,
-    fallback_id="openbmb/MiniCPM3-4B",
-    fallback_reason="4B, stronger capability but larger footprint",
-    modal_gpu="T4",
-    modal_memory=8192,
-)
-
-STORY_FALLBACK = ModelConfig(
-    hub_id="openbmb/MiniCPM3-4B",
-    params_b=4.0,
-    license=LicenseType.APACHE_2_0,
-    vram_gb=8.0,
-    is_primary=False,
     modal_gpu="T4",
     modal_memory=8192,
 )
@@ -145,43 +113,6 @@ TTS_MODEL = ModelConfig(
     params_b=2.0,
     license=LicenseType.APACHE_2_0,
     vram_gb=8.0,
-    fallback_id="hexgrad/Kokoro-82M",
-    fallback_reason="82M params, ultra-lightweight, Apache 2.0",
-    modal_gpu="T4",
-    modal_memory=8192,
-)
-
-TTS_FALLBACK_KOKORO = ModelConfig(
-    hub_id="hexgrad/Kokoro-82M",
-    params_b=0.082,
-    license=LicenseType.APACHE_2_0,
-    vram_gb=1.0,
-    is_primary=False,
-    modal_gpu="T4",
-    modal_memory=4096,
-)
-
-TTS_FALLBACK_MELO = ModelConfig(
-    hub_id="myshell-ai/MeloTTS-English-v3",
-    params_b=0.0,  # Unknown exact size
-    license=LicenseType.MIT,
-    vram_gb=1.0,
-    is_primary=False,
-    modal_gpu="CPU",
-    modal_memory=2048,
-)
-
-# ============================================================================
-# TINY MODE MODELS (C4: Edge/Tiny Model Support)
-# ============================================================================
-
-TINY_IMAGE_MODEL = ModelConfig(
-    hub_id="stabilityai/sd-turbo",
-    params_b=0.67,
-    license=LicenseType.APACHE_2_0,
-    vram_gb=4.0,
-    fallback_id="stabilityai/sdxl-turbo",
-    fallback_reason="SDXL-Turbo, higher quality but more VRAM",
     modal_gpu="T4",
     modal_memory=8192,
 )
@@ -443,17 +374,8 @@ def get_model_with_fallback(
     Returns:
         ModelConfig (primary or fallback)
     """
-    if use_fallback and model.fallback_id:
-        logger.info(f"Using fallback: {model.fallback_id} (reason: {model.fallback_reason})")
-        # Return the appropriate fallback config
-        fallback_map = {
-            "black-forest-labs/FLUX.1-schnell": FLUX_FALLBACK,
-            "openbmb/MiniCPM3-4B": STORY_FALLBACK,
-            "hexgrad/Kokoro-82M": TTS_FALLBACK_KOKORO,
-            "myshell-ai/MeloTTS-English-v3": TTS_FALLBACK_MELO,
-        }
-        return fallback_map.get(model.fallback_id, model)
-    
+    # Fallback model configs were removed (the Space links only the 3 primaries);
+    # there is no alternate config to swap in, so always return the primary.
     return model
 
 

docs/blog.md

@@ -1,121 +0,0 @@
-# Field Notes: FLUX + LoRA Character Consistency
-
-*How we achieved cross-page character consistency in DoodleBook using FLUX.2-klein, seed-locking, and a crayon-style LoRA.*
-
----
-
-## The Challenge
-
-The core problem in AI-generated storybooks is **character consistency**. If you generate 6 pages of a story independently, each page produces a different character — different colors, different proportions, different style. The magic is lost.
-
-We needed: **the same character, in the same art style, across all 6 pages.**
-
----
-
-## Our Approach: The Consistency Stack
-
-We didn't rely on a single technique. Instead, we layered three complementary approaches:
-
-### 1. Seed Locking
-
-```python
-BASE_SEED = 42
-def page_seed(page_num):
-    return BASE_SEED + page_num  # Page 0: 42, Page 1: 43, ...
-```
-
-Each page uses a deterministic seed derived from a locked base. This ensures:
-- Reproducible generation (same inputs = same outputs)
-- Slight variation between pages (different seeds)
-- Consistent "feel" across the book
-
-### 2. Character Description Reuse
-
-Every page uses the **exact same** `character_description` string:
-
-```python
-prompt = f"""
-{character_description},  # IDENTICAL on every page
-{scene_description},      # UNIQUE per page
-{art_style}, page {i+1} of children's book
-"""
-```
-
-The character description acts as an anchor, keeping the model's interpretation consistent.
-
-### 3. LoRA Fine-Tuning (The Secret Sauce)
-
-We trained a **crayon-style LoRA** on FLUX.2-klein:
-
-- **Trigger token:** `[DOODLECHAR]`
-- **Training data:** 10-15 crayon-style character images
-- **Rank:** 16 (balances quality vs. file size)
-- **Steps:** 300
-
-The LoRA teaches FLUX to generate images in a specific art style. Combined with the character description, this creates a consistent visual identity.
-
----
-
-## The Results
-
-### Before LoRA (Base FLUX)
-- Pages look like generic AI art
-- Character changes dramatically between pages
-- No consistent style
-
-### After LoRA + Consistency Stack
-- Same character across all 6 pages
-- Consistent crayon art style
-- Recognizable as "the same book"
-
----
-
-## Key Learnings
-
-1. **Seed alone isn't enough.** Different prompts with the same seed produce different characters. You need description consistency too.
-
-2. **LoRA provides style, not identity.** The LoRA teaches the art style (crayon, watercolor, etc.), but the character identity comes from the prompt.
-
-3. **Image conditioning helps.** When available, feeding the child's actual doodle as an image prompt (via img2img) dramatically improves style matching.
-
-4. **Quality vs. speed tradeoff.** FLUX.2-klein-4B (4B params) runs faster than 9B with minimal quality loss for storybook art.
-
----
-
-## Technical Details
-
-### Model Stack
-- **Image:** FLUX.2-klein-4B + crayon-style LoRA
-- **Story:** MiniCPM5-1B (1B)
-- **TTS:** VoxCPM2 (2B)
-
-### Training Config
-```yaml
-rank: 16
-alpha: 16
-learning_rate: 1e-4
-steps: 300
-resolution: 512
-batch_size: 1
-```
-
-### Inference Config
-```yaml
-guidance_scale: 3.5
-num_inference_steps: 20  # Standard mode
-                       4  # Tiny Mode (SD-Turbo)
-width: 768
-height: 512
-```
-
----
-
-## Conclusion
-
-Character consistency in AI storybooks requires a multi-layered approach: seed locking for reproducibility, prompt engineering for identity, and LoRA fine-tuning for style. No single technique solves the problem alone, but together they create a reliable system.
-
-The result? A child's crayon drawing becomes a consistent, narrated, illustrated storybook — their character, their style, brought to life by AI.
-
----
-
-*Built for Build Small Hackathon 2026 · Thousand Token Wood Track*

docs/superpowers/specs/2026-06-14-coloring-book-loader-pdf-cover-design.md

@@ -1,174 +0,0 @@
-# DoodleBook — Coloring Book, Magic Loader & Styled PDF Covers
-
-**Date:** 2026-06-14
-**Status:** Approved design (pending spec review)
-
-Three user-requested features for the DoodleBook app (`run_modal.py` Modal build,
-mirrored in `app.py` HF build):
-
-1. **Magic Loader** — an engaging, on-brand wait screen while generation runs.
-2. **Coloring Book** — the SAME FLUX images with the colors removed (outlines
-   only) so kids can color the exact same pictures. No second/different image is
-   ever generated. Opt-in via a checkbox chosen before generating.
-3. **Styled PDF covers** — the PDF front page should match the on-screen scrapbook
-   cover (cream paper, crayon title with shadow, green "illustrated by" badge),
-   for both the storybook and the coloring-book PDFs.
-
----
-
-## Feature 1 — Magic Loader
-
-### Goal
-Generation takes a few minutes (FLUX is the slow stage). Replace the single plain
-status line with a crayon-styled animated panel that tells the user what's
-happening and showcases the small-model stack (good for judges too).
-
-### Approach
-Pure-CSS rotating messages (no JS, no per-page streaming — reliable inside Gradio
-`gr.HTML`). A stack of message `<div>`s fade in/out in sequence via staggered CSS
-`animation-delay` on an opacity keyframe.
-
-- Helper `magic_loader_html(stage: str, hero_name: str) -> str` in `book_builder.py`.
-- Rotating messages (image stage — the long one):
-  - `✏️ MiniCPM is dreaming up {hero}'s story…`
-  - `🎨 FLUX is painting your 6 pages…`
-  - `🔊 VoxCPM is recording the narration…`
-  - `💡 Did you know? Your whole storybook runs on tiny models!`
-- `create_book` yields the loader HTML into `book_display` during the story and
-  image stages (it already streams stage-by-stage).
-
-### CSS
-New `.magic-loader` / `.ml-msg` rules in the `ui/layout.py` CSS string. Each
-`.ml-msg` is absolutely stacked; `animation: ml-cycle Ns infinite` with
-`animation-delay: i*step`. Respects existing `prefers-reduced-motion` block
-(messages still legible, just no fade).
-
----
-
-## Feature 2 — Coloring Book (checkbox-triggered)
-
-### Goal
-When the user opts in, produce printable black-and-white outline pages **of the
-exact same FLUX images** (same scenes, same character) for kids to color. The
-coloring page is the color page with its colors removed — never a newly generated
-or different image.
-
-### Trigger
-New checkbox in the input card: `🖍️ Also make a coloring book` (`make_coloring`),
-chosen before pressing "Make my book!". Outline pages are produced automatically
-with the book when checked.
-
-### Generation (same image, colors removed — instant, free)
-Process the already-generated color images locally with OpenCV to strip the fills
-and keep the outlines. No extra Modal call, ~seconds, and the result is the SAME
-picture as line art. There is no FLUX re-generation and no "HD" alternative — that
-guarantees the coloring page always matches the color page exactly.
-
-### New module: `services/coloring.py`
-- `to_line_art(png_bytes: bytes) -> bytes`
-  - OpenCV: grayscale → light blur → `adaptiveThreshold(GAUSSIAN_C, THRESH_BINARY,
-    blockSize≈11, C≈2)` to get black lines on white; remove tiny speck components
-    (reuse the cleanup approach from `services/images.py:_doodle_to_cartoon`).
-  - Returns a PNG (white background, black outlines).
-  - On any failure: fall back to grayscale Otsu threshold; never raises.
-- `derive_coloring_pages(color_imgs: list[bytes]) -> list[bytes]`.
-
-### `book_builder.py` additions
-- `build_coloring_html(outline_imgs, page_texts, title) -> str` — same scrapbook
-  layout as `build_book_html` but with a coloring-book cover badge and outline
-  images (text kept small/light beneath each page).
-- `export_coloring_pdf(outline_imgs, page_texts, title, path) -> str` — styled
-  cover (Feature 3) + outline pages, print-friendly.
-
-### UI (`ui/layout.py`)
-- Input card: `make_coloring = gr.Checkbox(...)` (styled like `tiny_mode`).
-- Output card (below the storybook + downloads):
-  - `coloring_display = gr.HTML(visible=False)`
-  - `coloring_pdf_download = gr.DownloadButton("Download Coloring Book (PDF)", visible=False)`
-
-### Data flow
-```
-create_book(doodle, char_name, theme, hero, tiny, voice, make_coloring):
-  yield magic_loader(story)         -> book_display
-  story = services.story.generate_story(...)
-  yield magic_loader(images)
-  color_imgs, engine = services.images.generate_book_pages(...)
-  book_html = build_book_html(color_imgs, ...)
-  if make_coloring:
-      outlines = services.coloring.derive_coloring_pages(color_imgs)  # SAME imgs, colors removed
-      coloring_html = build_coloring_html(outlines, ...)
-      coloring_pdf = export_coloring_pdf(outlines, ...)
-  audio = services.tts.speak_book(...)
-  pdf = export_pdf(color_imgs, ...)
-  yield final: book_html, status, audio, pdf(visible), story_json, image_info,
-               trace, coloring_html(visible if make_coloring),
-               coloring_pdf(visible if make_coloring)
-```
-No `gr.State` and no regenerate handler are needed — the coloring pages are derived
-directly from `color_imgs`, so they always match the color book.
-
----
-
-## Feature 3 — Styled PDF cover
-
-### Goal
-Replace the plain Helvetica text title page in `export_pdf` with a cover that
-matches the on-screen scrapbook cover.
-
-### Approach
-Render the cover as a full-page **PIL image** and place it as PDF page 1 (PIL is
-already a dependency; works on HF with no browser).
-
-- `book_builder.render_cover_image(title, badge_text, kind="story") -> bytes`
-  - Canvas ~1240×1754 (A4 @150dpi). Cream fill (`#fff8e6`) + subtle speckle.
-  - Kicker `a DoodleBook story` — Caveat, berry (`#d6517a`), centered upper third.
-  - Title — Gaegu Bold, large, centered, wrapped to ≤2 lines, layered shadow:
-    offset draw in crayon-sun (`#f4c64a`) then ink (`#2e2a26`) on top.
-  - Badge — rounded rect, crayon-leaf (`#74b85a`), white Gaegu text `badge_text`.
-  - `badge_text`: story = `illustrated by FLUX.2-klein`; coloring =
-    `a coloring book to color in`.
-  - Fonts from `assets/fonts/Gaegu-Bold.ttf` + `Caveat.ttf` via
-    `ImageFont.truetype`; fall back to `ImageFont.load_default()` if missing.
-- `export_pdf` and `export_coloring_pdf` use `render_cover_image(...)` for page 1.
-
-### Fonts to bundle (OFL, free to redistribute)
-- `assets/fonts/Gaegu-Bold.ttf`
-- `assets/fonts/Caveat.ttf` (Regular or SemiBold)
-
----
-
-## Error handling (never crash a generation)
-- `to_line_art`: OpenCV failure → Otsu threshold fallback → original image.
-- `render_cover_image`: missing font → default font; PIL failure → old text cover.
-- `create_book` body wrapped so exceptions yield an error state, not a throw.
-
-## Testing
-- Unit:
-  - `to_line_art` → output PNG is mostly white with a meaningful fraction of dark
-    pixels (line art), valid dimensions.
-  - `render_cover_image` → returns a valid PNG of expected size; runs with fonts
-    present and with fonts removed (fallback path).
-  - `export_coloring_pdf` / `export_pdf` → produce a non-empty PDF whose page 1 is
-    the cover image.
-- Manual (run_modal.py): checkbox ON → loader animates → coloring section +
-  "Download Coloring Book (PDF)" appear; the outline pages are visibly the SAME
-  scenes as the color book; both PDFs open with the styled cover.
-
-## Files
-- **New:** `services/coloring.py`; `assets/fonts/Gaegu-Bold.ttf`,
-  `assets/fonts/Caveat.ttf`; this spec.
-- **Changed:** `ui/layout.py` (loader CSS, checkbox, coloring outputs, wiring);
-  `run_modal.py` (`create_book`) is the primary target; `app.py` mirrors the same
-  three features (loader, coloring from its own color images, styled cover) for HF
-  parity; `book_builder.py` (`render_cover_image`, `build_coloring_html`,
-  `export_coloring_pdf`, `magic_loader_html`, `export_pdf` cover).
-  No Modal worker changes are needed.
-
-## Out of scope (YAGNI)
-- Regenerating a separate line-art via FLUX. The user wants the EXACT same image,
-  just without color — so the coloring page is always derived from the color image,
-  never re-generated. (No "HD lines" button, no second FLUX run.)
-- Per-page progress bar (needs Modal streaming; loader covers the need).
-- Saving/downloading the narration audio (separate future ask).
-- Animated illustrated pipeline loader (chose the lighter CSS version).
-</content>

docs/superpowers/specs/2026-06-14-flux-lineart-coloring-design.md

@@ -1,93 +0,0 @@
-# FLUX-generated line art for coloring pages
-
-**Date:** 2026-06-14
-**Status:** Approved, pending implementation
-
-## Problem
-
-Coloring pages are derived from the finished full-color crayon page by
-`services/coloring.py:to_line_art()` (OpenCV: bilateral filter → k-means
-quantize → region-boundary trace). On textured/busy backgrounds (sand, hills,
-crayon-shaded sky) the crayon strokes fragment into hundreds of stray edges, so
-the coloring page is speckled and uncolorable (see the "rolling sand dunes" and
-"deep breath" pages). The source was never line art, so tracing it cleanly is
-fundamentally hard.
-
-The full-COLOR storybook pages look good and are NOT changing.
-
-## Approach (Option B — keep color pipeline, let FLUX draw the outline)
-
-Stop guessing outlines from pixels. Hand the finished color page back to FLUX
-and have it **redraw the scene as clean line art** via img2img. FLUX understands
-the scene semantically (character + clouds + hills) so it draws shape boundaries
-instead of tracing crayon texture.
-
-### Pipeline
-
-```
-canonical char ─┐
-                ├─► render_page (color, A10G) ──► STORYBOOK page (unchanged)
-story beat   ───┘            │
-                             └─► render_lineart (FLUX img2img, A10G)
-                                          │
-                                          └─► threshold B/W + despeckle ──► COLORING page
-```
-
-### Components
-
-1. **`modal_workers/modal_image_gen.py` — new `render_lineart(color_png) -> bytes`**
-   - A10G FLUX function (uses shared `GPU_FN` decorator → A10G, 300s timeout,
-     120s scaledown).
-   - img2img with the **color page as the image reference** (so the coloring
-     page matches the story picture exactly: same pose, same composition).
-   - Prompt: *"black and white coloring book line drawing, clean bold black
-     outlines on a pure white background, no shading, no color, no crayon
-     texture, simple shapes a child can color in."*
-   - Denoising `strength` tuned high enough to redraw as line art but low enough
-     to keep composition. **Exact param verified against the live
-     Flux2KleinPipeline and tuned on a real render before sign-off.**
-
-2. **`services/coloring.py` — cleanup + orchestration**
-   - Keep a small local `_crispen(png)`: threshold the FLUX output to pure
-     black-on-white + despeckle (FLUX may leave faint gray; coloring pages must
-     be crisp). Fast, no GPU.
-   - `derive_coloring_pages(color_imgs)`: fan the pages out via
-     `modal.Function.from_name("doodlebook-image-gen", "render_lineart").starmap`
-     (concurrent, like `render_page`), then `_crispen` each.
-   - **Fallback:** if the Modal call fails, fall back to the existing OpenCV
-     `to_line_art` (renamed `_to_line_art_opencv`) — so it degrades gracefully,
-     never worse than today.
-
-### Decisions (confirmed)
-
-- **Trace source:** the finished color page (matches the story picture).
-- **When it runs:** only when "Also make a coloring book" is checked — no extra
-  cost/time otherwise. `run_modal.py:182` already gates `derive_coloring_pages`
-  behind `make_coloring`, so no caller change needed.
-
-### Cost / latency
-
-+1 A10G render per page (~6 extra renders/book), opt-in. Cheap on A10G.
-
-## Ships with the GPU/deadlock fix
-
-Already edited (pending `modal deploy`): image-gen GPU A100→A10G,
-`scaledown_window` 1200→120s, per-call `timeout` 24h→300s. The deploy that ships
-line art also activates these. See the separate deadlock diagnosis (9 idle A100
-containers pinning the 10-GPU account quota → queued calls never timed out →
-app spun forever).
-
-## Testing
-
-1. Verify Flux2KleinPipeline img2img accepts a `strength`/denoising param;
-   confirm the exact name.
-2. Render ONE real book locally with coloring enabled; save the color page and
-   the line-art coloring page side by side.
-3. Confirm: clean colorable regions on the previously-bad busy pages (sand
-   dunes, hills), character preserved, pure black-on-white, no speckle.
-4. Tune `strength` if texture survives (raise) or composition drifts (lower).
-
-## Out of scope
-
-- Changing the color storybook render (looks good).
-- Programmatic flat-fill colorizing (not needed; color pipeline stays).

lora_finetune/dataset_prep.py

@@ -1,39 +0,0 @@
-"""
-Dataset preparation for LoRA training.
-
-Prepares character images for DreamBooth-style fine-tuning.
-"""
-
-import os
-from PIL import Image
-
-
-def prepare_training_data(
-    input_dir: str,
-    output_dir: str = "./training_data",
-    target_size: int = 512,
-    num_augmentations: int = 5
-):
-    """
-    Prepare training images for LoRA fine-tuning.
-    
-    Steps:
-    1. Load original doodle images
-    2. Resize to target size
-    3. Create variations (flip, rotate, color shift)
-    4. Save with consistent naming
-    
-    Args:
-        input_dir: Directory with original doodle images
-        output_dir: Output directory for prepared data
-        target_size: Target image size (512x512 for FLUX)
-        num_augmentations: Number of augmented versions per image
-    """
-    os.makedirs(output_dir, exist_ok=True)
-    
-    # Phase 5: Full implementation with augmentations
-    raise NotImplementedError("Phase 5: Dataset preparation")
-
-
-if __name__ == "__main__":
-    print("Run this script to prepare training data for LoRA.")

lora_finetune/train_lora.py

@@ -1,287 +0,0 @@
-"""
-FLUX LoRA Training Script — Phase 5
-
-Trains a crayon-style LoRA for character consistency on FLUX.2-klein.
-Uses DreamBooth-style fine-tuning with trigger token [DOODLECHAR].
-
-Usage:
-    python train_lora.py --images_dir ./training_images --output_dir ./lora-weights
-
-Requirements:
-    - diffusers>=0.28
-    - peft
-    - torch
-    - accelerate
-"""
-
-import argparse
-import os
-import json
-import logging
-from pathlib import Path
-
-logger = logging.getLogger(__name__)
-
-
-# ============================================================================
-# TRAINING CONFIGURATION
-# ============================================================================
-
-LORA_CONFIG = {
-    "rank": 16,
-    "alpha": 16,
-    "target_modules": [
-        "to_q", "to_k", "to_v", "to_out.0",
-        "add_q_proj", "add_k_proj", "add_v_proj", "to_add_out"
-    ],
-    "instance_prompt": "photo of [DOODLECHAR] character, crayon drawing style",
-    "class_prompt": "photo of a character",
-    "pretrained_model": "black-forest-labs/FLUX.2-klein-4B",
-    "resolution": 512,
-    "train_batch_size": 1,
-    "gradient_accumulation_steps": 4,
-    "learning_rate": 1e-4,
-    "max_train_steps": 300,
-    "checkpointing_steps": 50,
-    "seed": 42,
-}
-
-
-def train_lora(
-    training_images: list[str],
-    output_dir: str = "./lora-weights",
-    num_steps: int = 300,
-    learning_rate: float = 1e-4,
-    rank: int = 16,
-    alpha: int = 16,
-):
-    """
-    Train LoRA on FLUX.2-klein for crayon-style character consistency.
-    
-    Uses DreamBooth-style fine-tuning:
-    - Trigger token: [DOODLECHAR]
-    - Target: Cross-attention layers in UNet
-    - Loss: Cross-entropy with instance prompt
-    
-    Args:
-        training_images: Paths to training images (10-15 images recommended)
-        output_dir: Where to save LoRA weights
-        num_steps: Training steps (200-400 recommended)
-        learning_rate: Learning rate (1e-4 default)
-        rank: LoRA rank (16 recommended)
-        alpha: LoRA alpha (16 recommended, equals rank for scaling=1.0)
-        
-    Returns:
-        Path to saved LoRA weights
-    """
-    import torch
-    from diffusers import FluxPipeline
-    from peft import LoraConfig, get_peft_model
-    from torch.utils.data import Dataset, DataLoader
-    from PIL import Image
-    import torchvision.transforms as transforms
-    
-    # Create output directory
-    os.makedirs(output_dir, exist_ok=True)
-    
-    logger.info(f"Training LoRA with {len(training_images)} images")
-    logger.info(f"Config: rank={rank}, alpha={alpha}, steps={num_steps}, lr={learning_rate}")
-    
-    # Load FLUX pipeline
-    logger.info("Loading FLUX.2-klein pipeline...")
-    pipe = FluxPipeline.from_pretrained(
-        LORA_CONFIG["pretrained_model"],
-        torch_dtype=torch.bfloat16
-    )
-    
-    # Configure LoRA
-    lora_config = LoraConfig(
-        r=rank,
-        lora_alpha=alpha,
-        target_modules=LORA_CONFIG["target_modules"],
-        lora_dropout=0.0,
-        bias="none",
-    )
-    
-    # Apply LoRA to UNet
-    logger.info("Applying LoRA to UNet...")
-    pipe.unet = get_peft_model(pipe.unet, lora_config)
-    pipe.unet.print_trainable_parameters()
-    
-    # Create dataset
-    class CrayonDataset(Dataset):
-        def __init__(self, image_paths, transform=None):
-            self.image_paths = image_paths
-            self.transform = transform or transforms.Compose([
-                transforms.Resize((512, 512)),
-                transforms.ToTensor(),
-                transforms.Normalize([0.5], [0.5])
-            ])
-        
-        def __len__(self):
-            return len(self.image_paths)
-        
-        def __getitem__(self, idx):
-            img = Image.open(self.image_paths[idx]).convert("RGB")
-            return self.transform(img)
-    
-    dataset = CrayonDataset(training_images)
-    dataloader = DataLoader(dataset, batch_size=1, shuffle=True)
-    
-    # Training loop
-    logger.info("Starting training...")
-    pipe.unet.train()
-    
-    optimizer = torch.optim.AdamW(pipe.unet.parameters(), lr=learning_rate)
-    
-    for step in range(num_steps):
-        for batch in dataloader:
-            # Forward pass with noise
-            noise = torch.randn_like(batch)
-            timesteps = torch.randint(0, 1000, (batch.shape[0],), device=batch.device)
-            
-            # Simple training step (simplified for demonstration)
-            optimizer.zero_grad()
-            loss = torch.tensor(0.0, requires_grad=True)  # Placeholder
-            loss.backward()
-            optimizer.step()
-        
-        if (step + 1) % LORA_CONFIG["checkpointing_steps"] == 0:
-            logger.info(f"Step {step + 1}/{num_steps}")
-    
-    # Save LoRA weights
-    logger.info("Saving LoRA weights...")
-    pipe.unet.save_pretrained(output_dir)
-    
-    # Save training config
-    config_path = os.path.join(output_dir, "training_config.json")
-    with open(config_path, "w") as f:
-        json.dump({
-            **LORA_CONFIG,
-            "rank": rank,
-            "alpha": alpha,
-            "num_steps": num_steps,
-            "learning_rate": learning_rate,
-            "training_images": len(training_images),
-        }, f, indent=2)
-    
-    logger.info(f"LoRA saved to: {output_dir}")
-    return output_dir
-
-
-def publish_to_hf(
-    local_path: str, 
-    repo_id: str = "build-small-hackathon/doodlebook-flux-lora"
-):
-    """Upload trained LoRA to HuggingFace Hub (Well-Tuned badge)."""
-    from huggingface_hub import HfApi
-    
-    api = HfApi()
-    
-    # Create repo if it doesn't exist
-    api.create_repo(repo_id, repo_type="model", exist_ok=True)
-    
-    # Upload files
-    api.upload_folder(
-        folder_path=local_path,
-        repo_id=repo_id,
-        repo_type="model",
-        commit_message="Upload crayon-style LoRA for DoodleBook"
-    )
-    
-    logger.info(f"Published LoRA to: https://huggingface.co/{repo_id}")
-    return f"https://huggingface.co/{repo_id}"
-
-
-def prepare_training_data(
-    input_dir: str,
-    output_dir: str = "./training_data",
-    target_size: int = 512,
-):
-    """
-    Prepare training images for LoRA fine-tuning.
-    
-    Steps:
-    1. Load original doodle images
-    2. Resize to target size
-    3. Create augmentations (flip, rotate)
-    4. Save with consistent naming
-    """
-    from PIL import Image, ImageEnhance
-    import random
-    
-    os.makedirs(output_dir, exist_ok=True)
-    
-    image_extensions = {'.jpg', '.jpeg', '.png', '.webp'}
-    image_files = [
-        f for f in Path(input_dir).iterdir()
-        if f.suffix.lower() in image_extensions
-    ]
-    
-    logger.info(f"Found {len(image_files)} images in {input_dir}")
-    
-    output_idx = 0
-    
-    for img_path in image_files:
-        img = Image.open(img_path).convert("RGB")
-        img = img.resize((target_size, target_size), Image.LANCZOS)
-        
-        # Save original
-        img.save(os.path.join(output_dir, f"image_{output_idx:04d}.png"))
-        output_idx += 1
-        
-        # Create augmented versions
-        # Horizontal flip
-        flipped = img.transpose(Image.FLIP_LEFT_RIGHT)
-        flipped.save(os.path.join(output_dir, f"image_{output_idx:04d}.png"))
-        output_idx += 1
-        
-        # Slight rotation
-        rotated = img.rotate(random.uniform(-10, 10), fillcolor=(255, 255, 255))
-        rotated.save(os.path.join(output_dir, f"image_{output_idx:04d}.png"))
-        output_idx += 1
-        
-        # Color variation
-        enhancer = ImageEnhance.Color(img)
-        varied = enhancer.enhance(random.uniform(0.8, 1.2))
-        varied.save(os.path.join(output_dir, f"image_{output_idx:04d}.png"))
-        output_idx += 1
-    
-    logger.info(f"Prepared {output_idx} training images in {output_dir}")
-    return output_idx
-
-
-if __name__ == "__main__":
-    parser = argparse.ArgumentParser(description="Train crayon-style LoRA for DoodleBook")
-    parser.add_argument("--images_dir", required=True, help="Directory with training images")
-    parser.add_argument("--output_dir", default="./lora-weights", help="Output directory")
-    parser.add_argument("--num_steps", type=int, default=300, help="Training steps")
-    parser.add_argument("--learning_rate", type=float, default=1e-4, help="Learning rate")
-    parser.add_argument("--rank", type=int, default=16, help="LoRA rank")
-    parser.add_argument("--publish", action="store_true", help="Publish to HF Hub")
-    
-    args = parser.parse_args()
-    
-    logging.basicConfig(level=logging.INFO)
-    
-    # Prepare training data
-    training_dir = "./training_data"
-    prepare_training_data(args.images_dir, training_dir)
-    
-    # Get training images
-    training_images = list(Path(training_dir).glob("*.png"))
-    
-    # Train LoRA
-    output_dir = train_lora(
-        [str(p) for p in training_images],
-        args.output_dir,
-        args.num_steps,
-        args.learning_rate,
-        args.rank
-    )
-    
-    # Publish if requested
-    if args.publish:
-        publish_to_hf(output_dir)
-    
-    print("Training complete!")

modal_workers/modal_image_gen.py

@@ -1,332 +0,0 @@
-"""
-Modal image generation — FLUX.2-klein-4B (verified API) on A100.
-
-Verified against the live model card (June 2026):
-  from diffusers import Flux2KleinPipeline
-  pipe(prompt=..., guidance_scale=1.0, num_inference_steps=4)   # fast distilled
-
-Character consistency (C1): identical character_description on every page +
-locked seed S, page i uses S+i. The character_description is produced upstream
-by the vision worker (reads the child's doodle) so the hero matches their drawing.
-"""
-
-import os
-import io
-import logging
-
-import modal
-
-logger = logging.getLogger(__name__)
-
-app = modal.App("doodlebook-image-gen")
-
-CACHE = "/cache"
-vol = modal.Volume.from_name("doodlebook-hf-cache", create_if_missing=True)
-HF_SECRET = modal.Secret.from_name("huggingface")
-
-flux_image = (
-    modal.Image.debian_slim(python_version="3.11")
-    .pip_install(
-        "torch", "diffusers", "transformers", "accelerate",
-        "sentencepiece", "pillow", "huggingface_hub",
-    )
-    .env({"HF_HOME": CACHE})
-)
-
-MIN_CONTAINERS = int(os.environ.get("DOODLEBOOK_KEEP_WARM", "0"))
-# FLUX.2-klein-4B is ~13GB in bf16 (see config.FLUX_MODEL.vram_gb) — fits an
-# A10G (24GB) with room to spare, ~4-5x cheaper than A100-40GB and far more
-# available, so books stop exhausting the scarce A100 pool.
-GPU = "A10G"
-# A real per-call timeout: if a render can't get a GPU slot (account GPU quota
-# exhausted) it FAILS instead of queuing for 24h, so services/images.py falls
-# back to the local sketch instead of the app spinning forever.
-RENDER_TIMEOUT = 300  # 5 min — generous for a cold start + 6-step render
-# Short scaledown so idle containers release their GPU quota quickly instead of
-# pinning it for 20 min and blocking the next book (this was the deadlock).
-SCALEDOWN = 120
-FLUX_ID = "black-forest-labs/FLUX.2-klein-4B"
-DEFAULT_ART_STYLE = (
-    "children's crayon storybook illustration, bold black outlines, "
-    "flat bright colors, simple shapes"
-)
-DEFAULT_COLORING_STYLE = (
-    "children's coloring book page, pure black ink outlines on pure white paper, "
-    "clean contour lines, no color, no gray, no shading, no texture, "
-    "no hatching, no pencil marks, open spaces to color"
-)
-GPU_FN = dict(  # shared decorator kwargs for the FLUX functions
-    gpu=GPU, image=flux_image, volumes={CACHE: vol}, secrets=[HF_SECRET],
-    timeout=RENDER_TIMEOUT, min_containers=MIN_CONTAINERS, scaledown_window=SCALEDOWN,
-)
-
-# loaded once per warm container, reused across calls
-_PIPE = None
-
-
-def _get_pipe():
-    global _PIPE
-    if _PIPE is None:
-        import torch
-        from diffusers import Flux2KleinPipeline
-        logger.info("Loading FLUX.2-klein-4B…")
-        _PIPE = Flux2KleinPipeline.from_pretrained(
-            FLUX_ID, torch_dtype=torch.bfloat16, cache_dir=CACHE,
-        )
-        _PIPE.enable_model_cpu_offload()
-        logger.info("FLUX ready.")
-    return _PIPE
-
-
-@app.function(**GPU_FN)
-def generate_book_pages(
-    character_desc: str,
-    story_beats: list[str],
-    doodle: bytes = None,
-    art_style: str = "children's crayon storybook illustration, bold black outlines, flat bright colors, simple shapes",
-    seed: int = 42,
-    lora_repo: str = None,
-    tiny: bool = False,
-) -> list[bytes]:
-    """
-    Render all 6 pages so the hero MATCHES THE CHILD'S DRAWING.
-
-    Two-stage when a doodle is provided (FLUX.2-klein image reference):
-      Stage 1: doodle  -> canonical full-body character (same creature, colorized)
-      Stage 2: canonical -> the SAME character placed into each story scene
-    Falls back to text2img from `character_desc` only when no doodle is given.
-    """
-    import torch
-    from PIL import Image
-
-    pipe = _get_pipe()
-    if lora_repo:
-        try:
-            pipe.load_lora_weights(lora_repo)
-            logger.info(f"LoRA loaded: {lora_repo}")
-        except Exception as e:
-            logger.warning(f"LoRA load failed ({e}); base model")
-
-    steps = 4 if tiny else 6
-
-    def _gen(image, prompt, s):
-        kw = dict(prompt=prompt, height=768, width=768, guidance_scale=1.0,
-                  num_inference_steps=steps,
-                  generator=torch.Generator("cuda").manual_seed(s))
-        if image is not None:
-            kw["image"] = image
-        return pipe(**kw).images[0]
-
-    # --- Stage 1: canonical character from the actual drawing ---
-    canonical = None
-    if doodle:
-        try:
-            ref = Image.open(io.BytesIO(doodle)).convert("RGB")
-            canonical = _gen(
-                ref,
-                ("Turn this child's drawing into a clean, friendly, full-body cartoon "
-                 "character for a children's storybook. Keep the EXACT same creature, "
-                 "face, and features as the drawing. " + art_style +
-                 ", plain white background, full character visible, centered."),
-                seed,
-            )
-            logger.info("canonical character built from doodle")
-        except Exception as e:
-            logger.warning(f"canonical build failed ({e}); text2img fallback")
-            canonical = None
-
-    # --- Stage 2: place the SAME character into each scene ---
-    pages = []
-    for i, beat in enumerate(story_beats):
-        if canonical is not None:
-            prompt = (
-                f"The same character. {beat}. {art_style}, "
-                f"full colorful background scene, the character clearly visible."
-            )
-            img = _gen(canonical, prompt, seed + i + 1)
-        else:
-            prompt = (
-                f"{character_desc}. Scene: {beat}. {art_style}, white background, "
-                f"centered, full character visible, same character design throughout"
-            )
-            img = _gen(None, prompt, seed + i + 1)
-        buf = io.BytesIO(); img.save(buf, format="PNG")
-        pages.append(buf.getvalue())
-        logger.info(f"page {i+1}/{len(story_beats)} done")
-
-    if lora_repo:
-        try:
-            pipe.unload_lora_weights()
-        except Exception:
-            pass
-    vol.commit()
-    return pages
-
-
-# ============================================================================
-# PARALLEL PATH — split into canonical (1 call) + per-page (fan out via .starmap)
-# so the 6 scenes render concurrently across warm containers instead of one
-# container doing 7 inferences back-to-back. Orchestrated by services/images.py.
-# ============================================================================
-
-# canonical runs once per book, so keep at most ONE warm (don't double the bill)
-_CANON_FN = {**GPU_FN, "min_containers": min(1, MIN_CONTAINERS)}
-
-
-@app.function(**_CANON_FN)
-def build_canonical(
-    doodle: bytes,
-    art_style: str = DEFAULT_ART_STYLE,
-    seed: int = 42,
-    tiny: bool = False,
-) -> bytes:
-    """Stage 1: child's drawing -> canonical full-body character (PNG bytes).
-    Returns b"" when no doodle is given (caller then renders text2img per page)."""
-    if not doodle:
-        return b""
-    import io
-    import torch
-    from PIL import Image
-
-    pipe = _get_pipe()
-    ref = Image.open(io.BytesIO(doodle)).convert("RGB")
-    img = pipe(
-        prompt=("Turn this child's drawing into a clean, friendly, full-body cartoon "
-                "character for a children's storybook. Keep the EXACT same creature, "
-                "face, and features as the drawing. " + art_style +
-                ", plain white background, full character visible, centered."),
-        image=ref, height=768, width=768, guidance_scale=1.0,
-        num_inference_steps=4 if tiny else 6,
-        generator=torch.Generator("cuda").manual_seed(seed),
-    ).images[0]
-    buf = io.BytesIO(); img.save(buf, format="PNG")
-    return buf.getvalue()
-
-
-@app.function(**GPU_FN)
-def render_page(
-    canonical: bytes,
-    character_desc: str,
-    beat: str,
-    art_style: str = DEFAULT_ART_STYLE,
-    seed: int = 42,
-    tiny: bool = False,
-) -> bytes:
-    """Stage 2: render ONE scene. Uses the canonical character as an image
-    reference when provided (consistency), else text2img from character_desc."""
-    import io
-    import torch
-    from PIL import Image
-
-    pipe = _get_pipe()
-    if canonical:
-        ref = Image.open(io.BytesIO(canonical)).convert("RGB")
-        prompt = (f"The same character. {beat}. {art_style}, "
-                  f"full colorful background scene, the character clearly visible.")
-        kw = dict(prompt=prompt, image=ref)
-    else:
-        prompt = (f"{character_desc}. Scene: {beat}. {art_style}, white background, "
-                  f"centered, full character visible, same character design throughout")
-        kw = dict(prompt=prompt)
-    kw.update(height=768, width=768, guidance_scale=1.0,
-              num_inference_steps=4 if tiny else 6,
-              generator=torch.Generator("cuda").manual_seed(seed))
-    img = pipe(**kw).images[0]
-    buf = io.BytesIO(); img.save(buf, format="PNG")
-    return buf.getvalue()
-
-
-@app.function(**GPU_FN)
-def render_coloring_page(
-    canonical: bytes,
-    character_desc: str,
-    beat: str,
-    art_style: str = DEFAULT_COLORING_STYLE,
-    seed: int = 42,
-    tiny: bool = False,
-) -> bytes:
-    """Stage 2 alternate render: same scene, but directly as clean line art."""
-    import io
-    import torch
-    from PIL import Image
-
-    pipe = _get_pipe()
-    if canonical:
-        ref = Image.open(io.BytesIO(canonical)).convert("RGB")
-        prompt = (
-            f"The same character. {beat}. {art_style}, simple clean background shapes, "
-            f"same composition, thick readable outlines, no filled black areas, "
-            f"no extra sketch marks."
-        )
-        kw = dict(prompt=prompt, image=ref)
-    else:
-        prompt = (
-            f"{character_desc}. Scene: {beat}. {art_style}, white background, "
-            f"centered, full character visible, same character design throughout"
-        )
-        kw = dict(prompt=prompt)
-    kw.update(
-        height=768,
-        width=768,
-        guidance_scale=1.0,
-        num_inference_steps=4 if tiny else 6,
-        generator=torch.Generator("cuda").manual_seed(seed),
-    )
-    img = pipe(**kw).images[0]
-    buf = io.BytesIO()
-    img.save(buf, format="PNG")
-    return buf.getvalue()
-
-
-LINEART_PROMPT = (
-    "black and white coloring book line art, clean bold contour lines only on a "
-    "pure white background, no shading, no gray, no color, no fill, no crayon "
-    "texture, no crosshatching, no tiny details, simple shapes a child can color"
-)
-
-LINEART_NEGATIVE_PROMPT = (
-    "color, grayscale, shadows, shading, gradients, texture, speckles, noise, "
-    "blur, sketch shading, hatch marks, crosshatching, filled shapes, busy background"
-)
-
-
-@app.function(**GPU_FN)
-def render_lineart(color_png: bytes, seed: int = 42) -> bytes:
-    """Turn a finished COLOR page into clean coloring-book line art.
-
-    img2img from the color page so the coloring page matches the story picture
-    (same pose/composition), but FLUX REDRAWS it as outlines — it understands the
-    scene semantically (kid + clouds + hills) and traces shape boundaries instead
-    of the crayon texture that wrecked the old OpenCV edge-trace.
-
-    `strength` controls how far it departs from the source: high enough to redraw
-    as flat line art, low enough to keep the composition. Flux2KleinPipeline may
-    not expose `strength` (it's a unified edit/reference pipeline), so we pass it
-    when accepted and silently retry without it.
-    """
-    import io
-    import torch
-    from PIL import Image
-
-    pipe = _get_pipe()
-    ref = Image.open(io.BytesIO(color_png)).convert("RGB")
-    base = dict(
-        prompt=LINEART_PROMPT, image=ref, height=768, width=768,
-        guidance_scale=1.0, num_inference_steps=6,
-        generator=torch.Generator("cuda").manual_seed(seed),
-    )
-    try:
-        img = pipe(**base, strength=0.68, negative_prompt=LINEART_NEGATIVE_PROMPT).images[0]
-    except TypeError:
-        logger.info("pipeline rejected `strength`; retrying without it")
-        try:
-            img = pipe(**base, negative_prompt=LINEART_NEGATIVE_PROMPT).images[0]
-        except TypeError:
-            img = pipe(**base).images[0]
-    buf = io.BytesIO(); img.save(buf, format="PNG")
-    return buf.getvalue()
-
-
-@app.function(image=flux_image, timeout=30)
-def health_check() -> str:
-    return "image_gen_healthy"

modal_workers/modal_story_gen.py

@@ -1,397 +0,0 @@
-"""
-Modal story generation — MiniCPM5-1B on T4 GPU.
-
-C2 Compliance: 3-layer JSON parser + template fallback
-- Layer 1: Regex extraction of {...} block
-- Layer 2: json-repair / json5 parsing
-- Layer 3: Deterministic template fallback (NEVER crashes)
-
-Few-shot prompt with ONE full exemplar for reliable JSON output.
-Greedy decode (do_sample=False) for determinism.
-"""
-
-import modal
-import re
-import json
-import logging
-
-logger = logging.getLogger(__name__)
-
-app = modal.App("doodlebook-story")
-
-story_env = modal.Image.debian_slim().pip_install(
-    "transformers>=4.40", "torch", "accelerate", "sentencepiece"
-)
-
-
-# ============================================================================
-# FEW-SHOT EXEMPLAR
-# ============================================================================
-
-FEW_SHOT_EXEMPLAR = """
-Write a 6-page children's storybook for age 5 about Luna the cat with theme: brave adventure.
-
-Return ONLY valid JSON:
-{
-  "title": "Luna's Brave Adventure",
-  "character_description": "A small orange tabby cat named Luna with big green eyes, whiskers, and a tiny red scarf",
-  "pages": [
-    {"page": 1, "text": "Luna was a small orange cat who loved to explore.", "scene": "Luna sitting by the window looking outside"},
-    {"page": 2, "text": "One sunny morning, Luna saw something sparkling in the forest.", "scene": "Luna spotting a glow in the trees"},
-    {"page": 3, "text": "Bravely, Luna crept into the forest to investigate.", "scene": "Luna walking cautiously through trees"},
-    {"page": 4, "text": "It was a tiny fairy stuck in a spider web!", "scene": "Luna discovering a fairy in trouble"},
-    {"page": 5, "text": "Luna gently freed the fairy with her paw.", "scene": "Luna carefully helping the fairy"},
-    {"page": 6, "text": "The fairy thanked Luna and they became friends forever.", "scene": "Luna and fairy playing together at sunset"}
-  ]
-}
-"""
-
-
-# ============================================================================
-# STORY GENERATION PROMPT
-# ============================================================================
-
-def build_prompt(hero_name: str, theme: str, age: int) -> str:
-    """Build few-shot prompt for story generation."""
-    return f"""{FEW_SHOT_EXEMPLAR}
-
-Write a 6-page children's storybook for age {age} about {hero_name} with theme: {theme}.
-
-Return ONLY valid JSON:
-"""
-
-
-# ============================================================================
-# 3-LAYER JSON PARSER (C2)
-# ============================================================================
-
-def parse_story_json(raw_output: str) -> dict:
-    """
-    3-layer parser: regex → json5/repair → template fallback.
-    
-    Layer 1: Extract {...} block with regex
-    Layer 2: Parse with json.loads, repair common issues
-    Layer 3: Return deterministic template (NEVER crashes)
-    
-    Args:
-        raw_output: Raw model output string
-        
-    Returns:
-        Parsed story dict with keys: title, character_description, pages
-    """
-    # Layer 1: Regex extraction
-    story = _layer1_regex_extract(raw_output)
-    if story:
-        return story
-    
-    # Layer 2: JSON repair
-    story = _layer2_json_repair(raw_output)
-    if story:
-        return story
-    
-    # Layer 3: Template fallback (NEVER crashes)
-    logger.warning("All parsing failed, using template fallback")
-    return _layer3_template_fallback(raw_output)
-
-
-def _layer1_regex_extract(text: str) -> dict | None:
-    """Layer 1: Extract {...} block with regex."""
-    try:
-        # Find the outermost {...} block
-        match = re.search(r'\{[\s\S]*\}', text)
-        if not match:
-            return None
-        
-        json_str = match.group(0)
-        story = json.loads(json_str)
-        
-        # Validate structure
-        if _validate_story_structure(story):
-            return story
-        return None
-    except (json.JSONDecodeError, KeyError, TypeError):
-        return None
-
-
-def _layer2_json_repair(text: str) -> dict | None:
-    """Layer 2: Repair common JSON issues and parse."""
-    try:
-        # Find the {...} block
-        match = re.search(r'\{[\s\S]*\}', text)
-        if not match:
-            return None
-        
-        json_str = match.group(0)
-        
-        # Common repairs
-        json_str = _repair_json(json_str)
-        
-        story = json.loads(json_str)
-        
-        if _validate_story_structure(story):
-            return story
-        return None
-    except (json.JSONDecodeError, KeyError, TypeError):
-        return None
-
-
-def _repair_json(json_str: str) -> str:
-    """Repair common JSON issues from 1B model output."""
-    # Remove trailing commas before } or ] (with optional whitespace)
-    json_str = re.sub(r',\s*([}\]])', r'\1', json_str)
-    
-    # Remove single-line // comments
-    json_str = re.sub(r'//.*?$', '', json_str, flags=re.MULTILINE)
-    
-    # Remove multi-line comments /* ... */
-    json_str = re.sub(r'/\*[\s\S]*?\*/', '', json_str)
-    
-    # Fix unescaped newlines in strings
-    json_str = re.sub(r'(?<=")\n(?=")', '\\n', json_str)
-    
-    # Fix missing quotes around keys (word before colon)
-    json_str = re.sub(r'(\s)(\w+)(\s*:)', r'\1"\2"\3', json_str)
-    
-    return json_str
-
-
-def _validate_story_structure(story: dict) -> bool:
-    """Validate story has required structure."""
-    required_keys = ["title", "character_description", "pages"]
-    if not all(k in story for k in required_keys):
-        return False
-    
-    pages = story.get("pages", [])
-    if not isinstance(pages, list) or len(pages) < 1:
-        return False
-    
-    # Check first page has required fields
-    first_page = pages[0]
-    if not all(k in first_page for k in ["page", "text", "scene"]):
-        return False
-    
-    return True
-
-
-def _layer3_template_fallback(raw_output: str) -> dict:
-    """
-    Layer 3: Deterministic template fallback.
-    NEVER crashes - always returns valid 6-page book.
-    """
-    # Try to extract any useful text from raw output
-    extracted_text = raw_output[:200] if raw_output else "an adventure"
-    
-    return {
-        "title": "A Wonderful Adventure",
-        "character_description": f"A friendly character who went on {extracted_text}",
-        "pages": [
-            {"page": 1, "text": "Once upon a time, there was a character who loved adventures.", "scene": "Character introduction"},
-            {"page": 2, "text": "One day, something exciting happened.", "scene": "Inciting incident"},
-            {"page": 3, "text": "The character bravely faced the challenge.", "scene": "Rising action"},
-            {"page": 4, "text": "With courage and kindness, the character succeeded.", "scene": "Climax"},
-            {"page": 5, "text": "Friends gathered to celebrate the victory.", "scene": "Resolution"},
-            {"page": 6, "text": "And they all lived happily ever after. The end.", "scene": "Happy ending"}
-        ]
-    }
-
-
-# ============================================================================
-# TEMPLATE STORY (for testing without Modal)
-# ============================================================================
-
-# ---------------------------------------------------------------------------
-# Local story generator — theme-accurate, character-aware, and VARIED.
-# Each theme has its own 6-beat arc; slots ({place}, {friend}, {thing}, {feeling})
-# are filled from per-theme word banks chosen by a seed derived from hero+theme,
-# so different heroes/themes produce different books (no more identical text).
-# ---------------------------------------------------------------------------
-
-_PLACES = ["whispering forest", "sunny meadow", "sparkling river", "cloud-top hill",
-           "hidden garden", "snowy valley", "rolling sand dunes", "moonlit lake"]
-_FRIENDS = ["a shy little fox", "a lost baby bird", "a giggling firefly", "a sleepy turtle",
-            "a tiny dragon", "a kind old owl", "a bouncing bunny", "a glowing jellyfish"]
-_THINGS = ["a glowing key", "a singing flower", "a map of stars", "a tiny golden bell",
-           "a magic seed", "a shimmering shell", "a friendly lantern", "a curious door"]
-
-
-def _theme_arc(theme: str, hero: str, place: str, friend: str, thing: str) -> dict:
-    """Return {title, pages[6]} for the given theme, with slots filled in."""
-    T = {
-        "brave adventure": {
-            "title": f"{hero}'s Brave Adventure",
-            "pages": [
-                (f"{hero} woke up wanting to explore the world.", f"{hero} standing at the edge of a {place}"),
-                (f"At the {place}, {hero} found {thing} glowing softly.", f"{hero} discovering {thing}"),
-                (f"Taking a deep breath, {hero} bravely followed where it led.", f"{hero} walking bravely into the {place}"),
-                (f"There, {friend} was stuck and a little scared.", f"{friend} in trouble, {hero} nearby"),
-                (f"{hero} was brave and gently helped {friend} get free.", f"{hero} helping {friend}"),
-                (f"Side by side they went home, and {hero} felt brave and proud.", f"{hero} and {friend} heading home at sunset"),
-            ],
-        },
-        "making a new friend": {
-            "title": f"{hero} Makes a Friend",
-            "pages": [
-                (f"{hero} was playing alone in the {place}.", f"{hero} playing alone in a {place}"),
-                (f"Nearby, {friend} sat all by itself, looking lonely.", f"{friend} sitting alone"),
-                (f"{hero} walked over and said a cheerful hello.", f"{hero} greeting {friend} with a wave"),
-                (f"They shared {thing} and laughed together.", f"{hero} and {friend} sharing {thing}"),
-                (f"All afternoon they played their favorite games.", f"{hero} and {friend} playing games"),
-                (f"Now {hero} knew: a friend is just a hello away.", f"{hero} and {friend} smiling together"),
-            ],
-        },
-        "overcoming a fear": {
-            "title": f"{hero} and the Big Brave Day",
-            "pages": [
-                (f"{hero} felt scared of the dark {place}.", f"{hero} looking nervously at a dark {place}"),
-                (f"But {friend} needed {thing} from inside it.", f"{friend} asking {hero} for help"),
-                (f"{hero}'s tummy felt wobbly, but {hero} took one small step.", f"{hero} taking a brave first step into the {place}"),
-                (f"One step, then another — it wasn't so scary after all.", f"{hero} walking carefully, growing braver"),
-                (f"{hero} found {thing} and carried it back proudly.", f"{hero} holding {thing} triumphantly"),
-                (f"{hero} learned that being brave means trying, even when you're scared.", f"{hero} and {friend} celebrating"),
-            ],
-        },
-        "helping someone": {
-            "title": f"{hero} Lends a Hand",
-            "pages": [
-                (f"One morning {hero} skipped through the {place}.", f"{hero} walking happily through a {place}"),
-                (f"{hero} heard a tiny cry — it was {friend}!", f"{hero} noticing {friend} in need"),
-                (f"{friend} had dropped {thing} and couldn't reach it.", f"{friend} reaching for {thing}"),
-                (f"{hero} thought hard and came up with a clever plan.", f"{hero} thinking of a plan"),
-                (f"Together they got {thing} back, and {friend} cheered.", f"{hero} and {friend} succeeding together"),
-                (f"Helping others made {hero}'s heart feel warm and happy.", f"{hero} and {friend} hugging"),
-            ],
-        },
-        "lost and found": {
-            "title": f"{hero} and the Lost {thing.split()[-1].title()}",
-            "pages": [
-                (f"{hero} was playing when {thing} suddenly went missing.", f"{hero} searching for {thing}"),
-                (f"{hero} looked all around the {place}.", f"{hero} looking around a {place}"),
-                (f"Along the way, {hero} met {friend} who wanted to help.", f"{hero} meeting {friend}"),
-                (f"They followed tiny clues together, step by step.", f"{hero} and {friend} following a trail"),
-                (f"At last, {thing} was found tucked beneath a leaf!", f"{hero} finding {thing}"),
-                (f"{hero} hugged {friend} and thanked them for never giving up.", f"{hero} and {friend} happy together"),
-            ],
-        },
-        "learning something new": {
-            "title": f"{hero} Learns to Soar",
-            "pages": [
-                (f"{hero} really wanted to learn something new today.", f"{hero} curious in a {place}"),
-                (f"{friend} offered to teach {hero} a wonderful trick.", f"{friend} teaching {hero}"),
-                (f"The first try wobbled and didn't work at all.", f"{hero} trying and stumbling"),
-                (f"{hero} practiced again and again, never giving up.", f"{hero} practicing hard"),
-                (f"Suddenly it worked, with {thing} sparkling in the air!", f"{hero} succeeding with {thing}"),
-                (f"{hero} beamed — trying your best helps you grow.", f"{hero} and {friend} celebrating the win"),
-            ],
-        },
-    }
-    return T.get(theme, T["brave adventure"])
-
-
-def generate_story_local(hero_name: str, theme: str, age: int = 5) -> dict:
-    """
-    Theme-accurate, varied, character-aware story (no Modal/GPU required).
-    Deterministic per (hero, theme) but different across heroes/themes.
-    """
-    import random
-    hero = (hero_name or "Little Hero").strip()
-    hero = hero[:1].upper() + hero[1:] if hero else "Little Hero"
-    rng = random.Random(hash((hero.lower(), theme)) & 0xFFFFFFFF)
-    place = rng.choice(_PLACES)
-    friend = rng.choice(_FRIENDS)
-    thing = rng.choice(_THINGS)
-
-    arc = _theme_arc(theme, hero, place, friend, thing)
-    pages = [{"page": i + 1, "text": t, "scene": s} for i, (t, s) in enumerate(arc["pages"])]
-
-    return {
-        "title": arc["title"],
-        "character_description": (
-            f"{hero}, a friendly storybook character, bright crayon colors, "
-            f"bold outlines, simple children's-book style"
-        ),
-        "pages": pages,
-    }
-
-
-# ============================================================================
-# MODAL FUNCTION
-# ============================================================================
-
-@app.function(gpu="T4", image=story_env, timeout=120)
-def generate_story(character_name: str, theme: str, age: int = 5) -> dict:
-    """
-    Generate a 6-page children's story via MiniCPM5-1B.
-    
-    C2 Compliance:
-    - Few-shot prompt with ONE full exemplar
-    - Greedy decode (do_sample=False)
-    - 3-layer parser + template fallback
-    - NEVER crashes on bad model output
-    
-    Args:
-        character_name: Main character name
-        theme: Story theme
-        age: Target age
-        
-    Returns:
-        dict with keys: title, character_description, pages[{page, text, scene}]
-    """
-    from transformers import AutoTokenizer, AutoModelForCausalLM
-    import torch
-
-    # Load model (MiniCPM ships custom modeling code -> trust_remote_code required)
-    model_id = "openbmb/MiniCPM5-1B"
-    tok = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
-    model = AutoModelForCausalLM.from_pretrained(
-        model_id, torch_dtype=torch.float16, trust_remote_code=True
-    ).cuda().eval()
-
-    # Build prompt and wrap in the model's chat template (it's an instruct model;
-    # a raw prompt generates poorly). enable_thinking=False = no reasoning preamble.
-    prompt = build_prompt(character_name, theme, age)
-    inputs = tok.apply_chat_template(
-        [{"role": "user", "content": prompt}],
-        add_generation_prompt=True,
-        enable_thinking=False,
-        return_dict=True,
-        return_tensors="pt",
-    ).to("cuda")
-
-    # Generate with greedy decode for determinism
-    with torch.no_grad():
-        out = model.generate(
-            **inputs,
-            max_new_tokens=800,
-            do_sample=False,  # Greedy for determinism
-        )
-
-    response = tok.decode(out[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
-    
-    # Parse with 3-layer parser (NEVER crashes)
-    story = parse_story_json(response)
-    
-    # Ensure pages list has exactly 6 entries
-    while len(story.get("pages", [])) < 6:
-        story.setdefault("pages", []).append({
-            "page": len(story.get("pages", [])) + 1,
-            "text": "And the adventure continued happily.",
-            "scene": "Continuing adventure"
-        })
-    
-    return story
-
-
-@app.function(gpu="T4", image=story_env, timeout=30)
-def health_check() -> str:
-    """Quick health check for Modal function."""
-    return "story_gen_healthy"
-
-
-# ============================================================================
-# CLI TEST
-# ============================================================================
-
-if __name__ == "__main__":
-    # Test local generation
-    story = generate_story_local("Ziggy", "brave adventure", 5)
-    print(json.dumps(story, indent=2))

modal_workers/modal_tts.py

@@ -1,235 +0,0 @@
-"""
-Modal TTS — VoxCPM2 narration on T4 GPU.
-
-C5 Compliance: Fallback chain
-- Primary: VoxCPM2 (2B, Apache 2.0)
-- Fallback 1: Kokoro-82M (ultra-lightweight)
-- Fallback 2: MeloTTS (MIT license)
-
-Generates WAV audio for book narration.
-"""
-
-import modal
-import io
-import os
-import logging
-
-logger = logging.getLogger(__name__)
-
-app = modal.App("doodlebook-tts")
-
-# Keep N containers always warm so the app is "live" with no cold start.
-# 0 = scale to zero when idle (cheap); 1 = always-on GPU (costs money 24/7).
-# Set at deploy time: DOODLEBOOK_KEEP_WARM=1 modal deploy modal_workers/modal_tts.py
-KEEP_WARM = int(os.environ.get("DOODLEBOOK_KEEP_WARM", "0"))
-NO_TIMEOUT = 86400  # Modal's max (24h) — effectively no per-call timeout
-
-CACHE = "/cache"
-vol = modal.Volume.from_name("doodlebook-hf-cache", create_if_missing=True)
-HF_SECRET = modal.Secret.from_name("huggingface")
-
-tts_env = (
-    modal.Image.debian_slim(python_version="3.11")
-    .apt_install("ffmpeg")
-    .pip_install("voxcpm==2.0.3", "soundfile", "torch", "huggingface_hub")
-    .env({"HF_HOME": CACHE})
-)
-
-# Child-friendly voices (VoxCPM2 "voice design" prefixes). The (parenthetical) is
-# interpreted as a voice instruction, not spoken aloud.
-# MIRROR of config.VOICE_PRESETS — kept inline so the Modal deploy stays
-# import-free. Keep the two in sync if you edit them. Default leans young.
-DEFAULT_VOICE = "kid"
-VOICE_DESIGN = {
-    "kid": "(A sweet little girl around seven years old telling a story to her "
-           "friends, bright high-pitched cheerful child's voice, playful, giggly "
-           "and full of wonder)",
-    "big_kid": "(A lively young girl about eleven years old reading a fun story "
-               "aloud, bright youthful energetic voice, expressive and excited)",
-    "playful": "(A cheerful, friendly young woman telling a fun children's story, "
-               "bright, animated, smiling, expressive)",
-    "storyteller": "(A warm, gentle female storyteller reading a bedtime story to a "
-                   "young child, soft, soothing, slow and expressive, kind and cozy)",
-    "grandpa": "(A kind, gentle old grandfather telling a cozy bedtime story, warm, "
-               "slow, soothing)",
-}
-
-_TTS = None
-
-
-def _get_tts():
-    global _TTS
-    if _TTS is None:
-        from voxcpm import VoxCPM
-        logger.info("Loading VoxCPM2…")
-        _TTS = VoxCPM.from_pretrained("openbmb/VoxCPM2", load_denoiser=False)
-        logger.info("VoxCPM2 ready.")
-    return _TTS
-
-
-@app.function(
-    gpu="A10G", image=tts_env, volumes={CACHE: vol}, secrets=[HF_SECRET],
-    timeout=NO_TIMEOUT, scaledown_window=1200, min_containers=KEEP_WARM,
-)
-def speak_book(text: str, voice: str = DEFAULT_VOICE) -> bytes:
-    """
-    Narrate the book with VoxCPM2 using a child-friendly storyteller voice.
-
-    Generates sentence-by-sentence with the SAME voice-design prefix for a
-    consistent voice, then stitches with short pauses for natural pacing.
-    """
-    import re
-    import numpy as np
-    import soundfile as sf
-
-    model = _get_tts()
-    design = VOICE_DESIGN.get(voice, VOICE_DESIGN[DEFAULT_VOICE])
-    sr = model.tts_model.sample_rate
-
-    # split into sentences so long books stay stable; keep each chunk's voice fixed
-    chunks = [s.strip() for s in re.split(r"(?<=[.!?])\s+", text) if s.strip()]
-    if not chunks:
-        chunks = [text.strip() or "The end."]
-
-    pause = np.zeros(int(sr * 0.35), dtype=np.float32)   # gentle gap between sentences
-    pieces = []
-    for i, sentence in enumerate(chunks):
-        wav = model.generate(
-            text=f"{design} {sentence}",
-            cfg_value=2.0,
-            inference_timesteps=10,
-        )
-        pieces.append(np.asarray(wav, dtype=np.float32))
-        if i < len(chunks) - 1:
-            pieces.append(pause)
-        logger.info(f"narrated sentence {i+1}/{len(chunks)}")
-
-    audio = np.concatenate(pieces)
-    buf = io.BytesIO()
-    sf.write(buf, audio, sr, format="WAV")
-    vol.commit()
-    return buf.getvalue()
-
-
-# ============================================================================
-# LOCAL TTS (FOR TESTING WITHOUT MODAL)
-# ============================================================================
-
-def speak_book_local(text: str, voice: str = DEFAULT_VOICE) -> bytes:
-    """
-    Local TTS for testing (no Modal/GPU required).
-
-    Chain: Windows SAPI5 (offline, audible) -> pyttsx3 (if installed) ->
-    silent WAV (last resort). Real child-friendly voice = VoxCPM2 on Modal.
-    """
-    for fn in (_speak_sapi_windows, _speak_pyttsx3):
-        try:
-            audio = fn(text, voice)
-            if audio:
-                logger.info(f"Local TTS via {fn.__name__}")
-                return audio
-        except Exception as e:
-            logger.warning(f"{fn.__name__} unavailable: {e}")
-    logger.error("No working local TTS — returning silence")
-    return _generate_silent_wav(duration_seconds=5)
-
-
-def _speak_sapi_windows(text: str, voice: str = DEFAULT_VOICE) -> bytes:
-    """
-    Offline Windows TTS via SAPI5 (pywin32). Produces an audible WAV with no
-    GPU, no internet, and no extra install — pywin32 ships win32com.
-    """
-    import win32com.client
-    import pythoncom
-    import tempfile
-    import os
-
-    pythoncom.CoInitialize()  # Gradio runs handlers off-thread; COM needs init
-    path = None
-    try:
-        spvoice = win32com.client.Dispatch("SAPI.SpVoice")
-        stream = win32com.client.Dispatch("SAPI.SpFileStream")
-
-        # Prefer a female/child-friendly voice if the system has one
-        try:
-            for tok in spvoice.GetVoices():
-                desc = tok.GetDescription()
-                if any(n in desc for n in ("Zira", "Hazel", "Female")):
-                    spvoice.Voice = tok
-                    break
-        except Exception:
-            pass
-
-        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
-            path = tmp.name
-
-        stream.Open(path, 3)            # 3 = SSFMCreateForWrite
-        spvoice.AudioOutputStream = stream
-        spvoice.Rate = -1               # a touch slower, gentle for a bedtime story
-        spvoice.Speak(text)
-        stream.Close()
-
-        with open(path, "rb") as f:
-            data = f.read()
-        # release COM objects before uninit to avoid noisy IUnknown warnings
-        spvoice.AudioOutputStream = None
-        stream = None
-        spvoice = None
-        return data
-    finally:
-        if path and os.path.exists(path):
-            try:
-                os.unlink(path)
-            except OSError:
-                pass
-        pythoncom.CoUninitialize()
-
-
-def _speak_pyttsx3(text: str, voice: str = DEFAULT_VOICE) -> bytes:
-    """Cross-platform offline TTS via pyttsx3 (only if installed)."""
-    import pyttsx3
-    import tempfile
-    import os
-
-    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
-        path = tmp.name
-    engine = pyttsx3.init()
-    engine.setProperty("rate", 165)
-    engine.save_to_file(text, path)
-    engine.runAndWait()
-    with open(path, "rb") as f:
-        data = f.read()
-    if os.path.exists(path):
-        os.unlink(path)
-    return data
-
-
-def _generate_silent_wav(duration_seconds: int = 5, sample_rate: int = 48000) -> bytes:
-    """Generate silent WAV file as placeholder."""
-    import struct
-    
-    # WAV header
-    num_samples = sample_rate * duration_seconds
-    data_size = num_samples * 2  # 16-bit audio
-    
-    header = struct.pack(
-        '<4sI4s4sIHHIIHH4sI',
-        b'RIFF', 36 + data_size, b'WAVE',
-        b'fmt ', 16, 1, 1, sample_rate, sample_rate * 2, 2, 16,
-        b'data', data_size
-    )
-    
-    # Silent audio data
-    silent_data = b'\x00' * data_size
-    
-    return header + silent_data
-
-
-# ============================================================================
-# HEALTH CHECK
-# ============================================================================
-
-@app.function(gpu="T4", image=tts_env, timeout=30)
-def health_check() -> str:
-    """Quick health check for Modal function."""
-    return "tts_healthy"

requirements.txt

@@ -1,23 +1,26 @@
-# DoodleBook — Dependencies (ZeroGPU Version)
-# Core
-gradio>=5.0
-python-dotenv
-spaces
-
-# Image generation
-diffusers>=0.28
-transformers>=4.40
-accelerate
-peft
-torch
-pillow
-sentencepiece
-opencv-python-headless
-
-# Book building
-fpdf2
-
-# Utilities
-requests
-huggingface_hub
-soundfile
+# DoodleBook — Dependencies (ZeroGPU Version)
+# Core
+gradio>=5.0
+python-dotenv
+spaces
+
+# Image generation
+diffusers>=0.28
+transformers>=4.40
+accelerate
+torch
+pillow
+sentencepiece
+opencv-python-headless
+numpy
+
+# Voice narration (VoxCPM2) — was MISSING, so TTS always hit the silent fallback
+voxcpm
+
+# Book building
+fpdf2
+
+# Utilities
+requests
+huggingface_hub
+soundfile

run.py

@@ -1,34 +0,0 @@
-"""Launcher for DoodleBook — captures all output for debugging."""
-import sys
-import os
-import traceback
-
-sys.path.insert(0, os.path.dirname(__file__))
-
-# Redirect stderr to file
-log = open("_crash.log", "w", encoding="utf-8")
-sys.stderr = log
-sys.stdout = log
-
-try:
-    from app import create_layout, load_sample_book, create_book
-    print("Imports OK", flush=True)
-    
-    demo = create_layout(
-        load_sample_fn=load_sample_book,
-        create_book_fn=create_book,
-    )
-    print("Layout OK", flush=True)
-    
-    demo.launch(server_port=7870, prevent_thread_lock=True)
-    print("Launch OK — server running on port 7870", flush=True)
-    
-    import time
-    while True:
-        time.sleep(60)
-    
-except Exception as e:
-    print(f"ERROR: {e}", flush=True)
-    traceback.print_exc(file=log)
-finally:
-    log.flush()

run_modal.py

@@ -1,287 +0,0 @@
-"""
-DoodleBook — MODAL-ONLY runner.
-
-Serves the Gradio UI locally but runs ALL heavy generation on Modal's deployed
-functions (no local GPU inference):
-  - story      -> doodlebook-story / generate_story      (services.story)
-  - images     -> doodlebook-image-gen / generate_book_pages (services.images)
-  - voice      -> doodlebook-tts / speak_book            (services.tts)
-
-Use this (not app.py) when you want to check real Modal output on this machine.
-Run:  python run_modal.py
-"""
-
-import io
-import json
-import time
-import tempfile
-import logging
-
-import gradio as gr
-from PIL import Image
-
-from config import BASE_SEED, DEFAULT_VOICE
-from book_builder import (
-    build_book_html, export_pdf, magic_loader_html,
-    build_coloring_html, export_coloring_pdf,
-)
-from ui.layout import create_layout
-
-import services.story as story_svc
-import services.images as image_svc
-import services.tts as tts_svc
-
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger("doodlebook.modal")
-
-
-def _doodle_to_png_bytes(doodle_image):
-    """Gradio numpy image -> PNG bytes (or None)."""
-    if doodle_image is None:
-        return None
-    buf = io.BytesIO()
-    Image.fromarray(doodle_image).save(buf, format="PNG")
-    return buf.getvalue()
-
-
-def _with_heartbeat(blocking_fn, frame_fn, poll=4.0):
-    """
-    Run blocking_fn() in a thread while keeping the Gradio stream alive.
-
-    A multi-minute Modal call (FLUX ~2-3 min, VoxCPM ~30-60s) blocks the
-    generator with no yield, so the browser's SSE stream goes silent, the
-    connection drops, and the UI shows "Error". This pumps frame_fn(elapsed)
-    into the stream every `poll` seconds until the work finishes.
-
-    Yields ("hb", <frame tuple>) heartbeats, then a final ("done", <return>).
-    Re-raises whatever blocking_fn raised.
-    """
-    import threading
-    box = {}
-
-    def _run():
-        try:
-            box["val"] = blocking_fn()
-        except BaseException as e:  # surfaced to the caller below
-            box["err"] = e
-
-    th = threading.Thread(target=_run, daemon=True)
-    th.start()
-    t0 = time.time()
-    while th.is_alive():
-        th.join(timeout=poll)
-        if th.is_alive():
-            yield ("hb", frame_fn(int(time.time() - t0)))
-    if "err" in box:
-        raise box["err"]
-    yield ("done", box["val"])
-
-
-def create_book(doodle_image, character_name, theme, hero_name,
-                tiny_mode=False, voice=DEFAULT_VOICE, make_coloring=False):
-    """Streaming book creation — everything heavy runs on Modal."""
-    t_total = time.perf_counter()
-    character_name = (character_name or "").strip() or "Little Hero"
-    hero_name = (hero_name or "").strip() or character_name
-
-    trace = {
-        "backend": "modal",
-        "hero_name": hero_name,
-        "theme": theme,
-        "voice": voice,
-        "tiny_mode": tiny_mode,
-        "make_coloring": make_coloring,
-        "seed": BASE_SEED,
-        "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
-    }
-
-    _no = gr.update(visible=False)
-    _keep = gr.update()  # no-op: leave the (fixed, always-visible) download buttons as-is
-
-    # ---- 1) STORY (Modal MiniCPM, else fast text template) ----
-    yield (magic_loader_html("story", hero_name),
-           "Writing the story…", None, _keep, {}, "",
-           json.dumps(trace, indent=2), _no, _keep)
-
-    t_story = time.perf_counter()
-    story = story_svc.generate_story(hero_name, theme)
-    trace["story_sec"] = round(time.perf_counter() - t_story, 2)
-    title = story.get("title", "Untitled Story")
-    char_desc = story.get("character_description", "")
-    pages = story.get("pages", [])
-    page_texts = [p.get("text", "") for p in pages]
-    scenes = [p.get("scene", "") for p in pages]
-    trace.update(title=title, character_description=char_desc)
-
-    # ---- 2) VOICE starts NOW, concurrently with images (it only needs the text,
-    #         which is ready) so its ~30-60s overlaps the image render for free ----
-    import threading
-    voice_box = {}
-    full_text = f"{title}. {' '.join(page_texts)}"
-    t_voice = time.perf_counter()
-
-    def _do_voice():
-        try:
-            voice_box["bytes"] = tts_svc.speak_book(full_text, voice)
-        except Exception as e:
-            voice_box["err"] = e
-
-    voice_thread = threading.Thread(target=_do_voice, daemon=True)
-    voice_thread.start()
-
-    # ---- 3) IMAGES (Modal FLUX.2-klein — 6 pages rendered in PARALLEL) ----
-    yield (magic_loader_html("images", hero_name),
-           f"{title} — illustrating on Modal (FLUX)…",
-           None, _keep, story, "", json.dumps(trace, indent=2), _no, _keep)
-
-    doodle_bytes = _doodle_to_png_bytes(doodle_image)
-    img_bytes, engine = None, "sketch"
-    t_images = time.perf_counter()
-    for kind, payload in _with_heartbeat(
-        lambda: image_svc.generate_book_pages(
-            char_desc, scenes, doodle=doodle_bytes, seed=BASE_SEED, tiny=tiny_mode
-        ),
-        lambda s: (magic_loader_html("images", hero_name),
-                   f"{title} — illustrating… {s}s  (voice recording in parallel)",
-                   None, _keep, story, "", json.dumps(trace, indent=2), _no, _keep),
-    ):
-        if kind == "hb":
-            yield payload
-        else:
-            img_bytes, engine = payload
-    trace["images_sec"] = round(time.perf_counter() - t_images, 2)
-    trace["engine"] = engine
-    if engine != "flux":
-        logger.warning("Image gen fell back to local sketch — Modal FLUX did not run.")
-
-    book_html = build_book_html(img_bytes, page_texts, title, engine)
-
-    # ---- 4) Collect the parallel VOICE result (usually already finished) ----
-    while voice_thread.is_alive():  # only loops if voice somehow outran images
-        voice_thread.join(timeout=4)
-        if voice_thread.is_alive():
-            yield (book_html, f"{title} — finishing narration…",
-                   None, _keep, story, "", json.dumps(trace, indent=2), _no, _keep)
-
-    audio_path = None
-    trace["tts_sec"] = round(time.perf_counter() - t_voice, 2)
-    if voice_box.get("bytes"):
-        try:
-            with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
-                tmp.write(voice_box["bytes"])
-                audio_path = tmp.name
-        except Exception as e:
-            logger.warning(f"writing audio failed: {e}")
-    elif "err" in voice_box:
-        logger.warning(f"TTS failed: {voice_box['err']}")
-
-    # ---- 4) PDFs ----
-    pdf_path = None
-    t_pdf = time.perf_counter()
-    try:
-        with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as tmp:
-            pdf_path = export_pdf(img_bytes, page_texts, title, tmp.name)
-    except Exception as e:
-        logger.warning(f"PDF failed: {e}")
-    trace["pdf_sec"] = round(time.perf_counter() - t_pdf, 2)
-
-    # ---- 5) COLORING BOOK ----
-    coloring_html = ""
-    coloring_pdf_path = None
-    if make_coloring:
-        t_coloring = time.perf_counter()
-        outlines, coloring_engine = None, "failed"
-        for kind, payload in _with_heartbeat(
-            lambda: image_svc.generate_coloring_pages(
-                char_desc,
-                scenes,
-                doodle=doodle_bytes,
-                source_color_imgs=img_bytes,
-                seed=BASE_SEED,
-                tiny=tiny_mode,
-            ),
-            lambda s: (
-                book_html,
-                f"{title} — building coloring book… {s}s",
-                audio_path,
-                _keep,
-                story,
-                "",
-                json.dumps(trace, indent=2),
-                _no,
-                _keep,
-            ),
-        ):
-            if kind == "hb":
-                yield payload
-            else:
-                outlines, coloring_engine = payload
-        try:
-            coloring_html = build_coloring_html(outlines, page_texts, title)
-            with tempfile.NamedTemporaryFile(suffix=".pdf", delete=False) as tmp:
-                coloring_pdf_path = export_coloring_pdf(outlines, page_texts, title, tmp.name)
-            trace["coloring_book"] = True
-            trace["coloring_engine"] = coloring_engine
-        except Exception as e:
-            logger.warning(f"Coloring book failed: {e}")
-        trace["coloring_sec"] = round(time.perf_counter() - t_coloring, 2)
-
-    trace["completed"] = True
-    trace["total_sec"] = round(time.perf_counter() - t_total, 2)
-    engine_label = "FLUX (Modal)" if engine == "flux" else "local sketch fallback"
-    # download buttons stay visible (fixed under the status); just attach the files
-    pdf_update = gr.update(value=pdf_path) if pdf_path else _keep
-    coloring_pdf_update = gr.update(value=coloring_pdf_path) if coloring_pdf_path else _keep
-    coloring_display_update = (gr.update(visible=True, value=coloring_html) if coloring_html
-                               else gr.update(visible=False))
-
-    yield (
-        book_html,
-        f"Complete: {title} — {len(img_bytes)} pages · {engine_label} · voice: {voice} · total {trace['total_sec']}s",
-        audio_path,
-        pdf_update,
-        story,
-        f"Pages: {len(img_bytes)} | Seed: {BASE_SEED} | "
-        f"Mode: {'Tiny' if tiny_mode else 'Standard'} | Engine: {engine} | "
-        f"Story {trace.get('story_sec', 0)}s | Images {trace.get('images_sec', 0)}s | "
-        f"PDF {trace.get('pdf_sec', 0)}s | Coloring {trace.get('coloring_sec', 0)}s",
-        json.dumps(trace, indent=2),
-        coloring_display_update,
-        coloring_pdf_update,
-    )
-
-
-if __name__ == "__main__":
-    import os
-
-    demo = create_layout(create_book_fn=create_book)
-    # Queue so a long (multi-minute) Modal generation doesn't make the whole app
-    # unresponsive: allow several concurrent sessions and never time a job out.
-    demo.queue(default_concurrency_limit=8, max_size=64)
-    # NOTE: when server_port is set, Gradio does NOT auto-pick a free port — it
-    # raises OSError and exits if the port is busy. start_app.bat frees the port
-    # before launching; if you run this directly, make sure 7880 is free first.
-    port = int(os.environ.get("DOODLEBOOK_PORT", "7880"))
-    # Bind all interfaces so both 127.0.0.1 and localhost (and LAN/phone) reach it.
-    try:
-        demo.launch(
-            server_name="0.0.0.0",
-            server_port=port,
-            inbrowser=False,
-            show_error=True,
-            max_threads=40,
-            # PDFs are written to the system temp dir; Gradio won't serve files
-            # outside its allowed paths, so the DownloadButton links 404'd and the
-            # button looked broken. Allow the temp dir so downloads actually work.
-            allowed_paths=[tempfile.gettempdir()],
-        )
-    except OSError as e:
-        logger.error(
-            f"Could not bind port {port}: {e}\n"
-            f"  Something is already using it — likely a leftover DoodleBook "
-            f"instance (app.py on 7870, an old run_modal.py, or test_final.py).\n"
-            f"  Fix: close the other window, or run:  "
-            f"netstat -ano | findstr :{port}   then  taskkill /f /pid <PID>\n"
-            f"  Then relaunch with start_app.bat (it frees the port automatically)."
-        )
-        raise SystemExit(1)

services/story.py

@@ -1,71 +0,0 @@
-"""
-Story generation service — calls modal_story_gen for MiniCPM5-1B inference.
-
-C2 Compliance: 3-layer JSON parser + template fallback.
-"""
-
-from config import STORY_MODEL, GENERATION_PARAMS
-import os
-import logging
-
-logger = logging.getLogger(__name__)
-
-
-def generate_story(hero_name: str, theme: str, age: int = None) -> dict:
-    """
-    Generate a 6-page children's story.
-
-    Story runs LOCALLY by default: the local generator is instant and
-    theme-accurate, whereas the deployed MiniCPM5-1B was slower (T4 cold start)
-    and lower quality (the 1B model parroted the few-shot example). Set
-    DOODLEBOOK_STORY_MODAL=1 to route the story to the Modal MiniCPM model.
-
-    Args:
-        hero_name: Main character name
-        theme: Story theme (e.g., "brave adventure")
-        age: Target age (default from config)
-
-    Returns:
-        dict with keys: title, character_description, pages[{page, text, scene}]
-    """
-    if age is None:
-        age = GENERATION_PARAMS.target_age
-
-    # 1) Real model on Modal (MiniCPM) — opt-in only
-    if os.environ.get("DOODLEBOOK_STORY_MODAL", "0") == "1":
-        try:
-            import modal
-            fn = modal.Function.from_name("doodlebook-story", "generate_story")
-            story = fn.remote(hero_name, theme, age)
-            if story and story.get("pages"):
-                logger.info("Story generated via Modal MiniCPM")
-                return story
-        except Exception as e:
-            logger.info(f"Modal story unavailable ({e}); using local generator")
-
-    # 2) Rich local generator (theme-accurate, varied) — DEFAULT
-    try:
-        from modal_workers.modal_story_gen import generate_story_local
-        return generate_story_local(hero_name, theme, age)
-    except Exception as e:
-        logger.error(f"Local story generation failed: {e}")
-        return _fallback_story(hero_name, theme, age)
-
-
-def _fallback_story(hero_name: str, theme: str, age: int) -> dict:
-    """
-    Deterministic template fallback (C2 Layer 3).
-    NEVER crashes - always returns valid 6-page book.
-    """
-    return {
-        "title": f"{hero_name}'s {theme.title()}",
-        "character_description": f"A friendly character named {hero_name}, drawn in crayon style with bright colors, suitable for age {age}",
-        "pages": [
-            {"page": 1, "text": f"Once upon a time, there was a character named {hero_name}.", "scene": "Character introduction"},
-            {"page": 2, "text": f"{hero_name} loved going on adventures.", "scene": "Adventure begins"},
-            {"page": 3, "text": f"One day, {hero_name} discovered something magical.", "scene": "Discovery moment"},
-            {"page": 4, "text": f"With courage, {hero_name} faced the challenge.", "scene": "Challenge scene"},
-            {"page": 5, "text": f"Friends helped {hero_name} succeed.", "scene": "Teamwork scene"},
-            {"page": 6, "text": f"And they all lived happily ever after. The end.", "scene": "Happy ending"}
-        ]
-    }

services/trace.py

@@ -1,113 +0,0 @@
-"""
-Trace logging service — publishes generation metadata to HF Dataset (Open Trace badge).
-
-Logs prompts, seeds, and LoRA version for reproducibility.
-"""
-
-from typing import Optional
-import json
-import logging
-import os
-from datetime import datetime
-
-logger = logging.getLogger(__name__)
-
-TRACE_DATASET = "build-small-hackathon/doodlebook-traces"
-
-
-def log_trace(
-    hero_name: str,
-    theme: str,
-    story: dict,
-    seed: int,
-    lora_version: Optional[str] = None,
-    tiny_mode: bool = False,
-    character_description: str = "",
-    art_style: str = "crayon drawing, children's book"
-) -> str:
-    """
-    Log generation trace to HuggingFace Dataset.
-    
-    Creates a row in the trace dataset with all generation parameters
-    for reproducibility (Open Trace badge).
-    
-    Args:
-        hero_name: Character name used
-        theme: Story theme
-        story: Generated story dict
-        seed: Seed used for generation
-        lora_version: LoRA model version (if used)
-        tiny_mode: Whether Tiny Mode was used
-        character_description: Character description used
-        art_style: Art style used
-        
-    Returns:
-        Dataset URL
-    """
-    trace = {
-        "timestamp": datetime.now().isoformat(),
-        "hero_name": hero_name,
-        "theme": theme,
-        "title": story.get("title", ""),
-        "character_description": character_description or story.get("character_description", ""),
-        "art_style": art_style,
-        "seed": seed,
-        "lora_version": lora_version or "none",
-        "tiny_mode": tiny_mode,
-        "num_pages": len(story.get("pages", [])),
-        "pages": story.get("pages", []),
-        "models": {
-            "image": "black-forest-labs/FLUX.2-klein-4B",
-            "story": "openbmb/MiniCPM5-1B",
-            "tts": "openbmb/VoxCPM2"
-        }
-    }
-    
-    # Save trace locally
-    trace_dir = "traces"
-    os.makedirs(trace_dir, exist_ok=True)
-    trace_file = os.path.join(trace_dir, f"trace_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json")
-    
-    with open(trace_file, "w", encoding="utf-8") as f:
-        json.dump(trace, f, indent=2, ensure_ascii=False)
-    
-    logger.info(f"Trace saved: {trace_file}")
-    
-    # Try to upload to HF Dataset
-    try:
-        return _upload_to_hf_dataset(trace)
-    except Exception as e:
-        logger.warning(f"HF Dataset upload failed: {e}. Trace saved locally.")
-        return f"Local: {trace_file}"
-
-
-def _upload_to_hf_dataset(trace: dict) -> str:
-    """Upload trace to HuggingFace Dataset."""
-    try:
-        from huggingface_hub import HfApi
-        
-        api = HfApi()
-        
-        # Check if dataset exists, create if not
-        try:
-            api.dataset_info(TRACE_DATASET)
-        except Exception:
-            api.create_repo(TRACE_DATASET, repo_type="dataset", exist_ok=True)
-        
-        # Upload trace as JSON
-        trace_json = json.dumps(trace, indent=2, ensure_ascii=False)
-        filename = f"trace_{trace['timestamp'].replace(':', '-').replace('.', '-')}.json"
-        
-        api.upload_file(
-            path_or_fileobj=trace_json.encode(),
-            path_in_repo=filename,
-            repo_id=TRACE_DATASET,
-            repo_type="dataset",
-            commit_message=f"Log trace for {trace['hero_name']}"
-        )
-        
-        return f"https://huggingface.co/datasets/{TRACE_DATASET}/blob/main/{filename}"
-        
-    except ImportError:
-        logger.warning("huggingface_hub not installed")
-        return "Trace saved locally (no HF upload)"

services/tts.py

@@ -1,50 +0,0 @@
-"""
-TTS service — calls modal_tts for VoxCPM2 narration.
-
-C5 Compliance: Fallback chain
-- Primary: VoxCPM2 (2B, Apache 2.0)
-- Fallback 1: Kokoro-82M (ultra-lightweight)
-- Fallback 2: MeloTTS (MIT license)
-"""
-
-from config import TTS_MODEL, GENERATION_PARAMS
-import logging
-
-logger = logging.getLogger(__name__)
-
-
-def speak_book(text: str, voice: str = "kid") -> bytes:
-    """
-    Generate narration audio via VoxCPM2 on Modal.
-    
-    C5 Compliance: Falls back to local TTS if Modal fails.
-    
-    Args:
-        text: Full text to narrate (title + all pages)
-        voice: Voice style (warm, friendly, etc.)
-        
-    Returns:
-        WAV audio bytes
-    """
-    try:
-        # Try Modal (real VoxCPM2) — looks up the DEPLOYED function on Modal cloud
-        import modal
-        fn = modal.Function.from_name("doodlebook-tts", "speak_book")
-        return fn.remote(text, voice)
-    except Exception as e:
-        logger.warning(f"Modal TTS unavailable: {e}, using local fallback")
-        return speak_book_local(text, voice)
-
-
-def speak_book_local(text: str, voice: str = "warm") -> bytes:
-    """
-    Local TTS for testing (no Modal required).
-    Uses MeloTTS or returns silent WAV placeholder.
-    """
-    try:
-        from modal_workers.modal_tts import speak_book_local as local_tts
-        return local_tts(text, voice)
-    except Exception as e:
-        logger.warning(f"Local TTS failed: {e}, returning placeholder")
-        from modal_workers.modal_tts import _generate_silent_wav
-        return _generate_silent_wav(duration_seconds=5)

start_app.bat

@@ -1,33 +0,0 @@
-@echo off
-REM ============================================================
-REM  DoodleBook launcher — SINGLE instance, FIXED port.
-REM  Double-click this file to start.  Close this window to quit.
-REM
-REM  Why this matters: Gradio is given an explicit port. If that
-REM  port is still held (a killed instance's socket in TIME_WAIT,
-REM  an orphaned python, or app.py/test_final.py running too),
-REM  Gradio CRASHES on startup instead of picking another port.
-REM  The old loop then relaunched into the same crash forever and
-REM  the browser showed "Connection lost. Attempting reconnection".
-REM  So: free the port FIRST, then launch.
-REM ============================================================
-cd /d "%~dp0"
-set PYTHONUTF8=1
-set PYTHONIOENCODING=utf-8
-set DOODLEBOOK_PORT=7880
-
-:loop
-echo.
-echo === Freeing port %DOODLEBOOK_PORT% (killing any old/stray instance) ===
-for /f "tokens=5" %%a in ('netstat -ano ^| findstr ":%DOODLEBOOK_PORT% " ^| findstr LISTENING') do (
-    echo   killing PID %%a holding port %DOODLEBOOK_PORT%
-    taskkill /f /pid %%a >nul 2>&1
-)
-
-echo === Starting DoodleBook on http://127.0.0.1:%DOODLEBOOK_PORT%/ ===
-echo === Open EXACTLY that URL in your browser (not 7860/7870) ===
-python run_modal.py
-echo.
-echo === Server stopped (exit code %errorlevel%). Restarting in 3 seconds... (close this window to quit) ===
-timeout /t 3 /nobreak >nul
-goto loop

ui/layout.py

@@ -618,11 +618,6 @@ def create_layout(load_sample_fn=None, create_book_fn=None):
                     value=False,
                     elem_classes=["tiny-toggle"],
                 )
-                tiny_mode = gr.Checkbox(
-                    label="Tiny Mode — faster, runs on small GPUs",
-                    value=False,
-                    elem_classes=["tiny-toggle"],
-                )
                 make_btn = gr.Button(
                     "Make my book!",
                     variant="primary",
@@ -714,7 +709,7 @@ FLUX is the printer. **Tiny Titan.**
         if create_book_fn:
             make_btn.click(
                 fn=create_book_fn,
-                inputs=[doodle, char_name, theme, hero_name, tiny_mode, voice, make_coloring],
+                inputs=[doodle, char_name, theme, hero_name, voice, make_coloring],
                 outputs=[book_display, status, audio_narration, pdf_download,
                          story_info, image_info, trace_info,
                          coloring_display, coloring_pdf_download],