add recap and poster genration with minicpm and bfl

NEMOTRON_GGUF_SETUP.md

@@ -130,7 +130,7 @@ Hugging Face Spaces **Zero GPU** (paid tier) provides on-demand GPU allocation:
 
 ### How it works in this app
 
-1. `app/main.py` imports `spaces` gracefully (no error if missing)
+1. `app.py` imports `spaces` gracefully (no error if missing)
 2. The `_generate_with_gpu()` function is wrapped with `@spaces.GPU` only at runtime on HF Spaces
 3. Inside that function, `torch.cuda.is_available()` returns `True`, so `generator.py` auto-detects GPU via `_get_n_gpu_layers()` and sets `n_gpu_layers=-1`
 4. On CPU (local dev or free Spaces tier), it falls back to `n_gpu_layers=0`
@@ -156,7 +156,7 @@ app/
 requirements.txt
 ```
 
-On Hugging Face Spaces, the app runs `app/main.py` automatically.
+On Hugging Face Spaces, the app runs `app.py` automatically.
 
 ### GPU auto-detection logic
 

app.py

@@ -1,5 +1,9 @@
-import gradio as gr
+import os
 import uuid
+import json
+from pathlib import Path
+
+import gradio as gr
 
 try:
     import spaces  # only available on Hugging Face Spaces runtime
@@ -23,17 +27,18 @@ from app.services.journal import (
 )
 from app.services.scoring import compute_scores
 from app.services.story import build_story_packet, generate_story
+from app.services.image_gen import generate_poster_sync
 
 
 # ── Load dataset once on startup ──────────────────────────────────────────────
-DATASET_PATH = "app/data/games_dataset.json"
+DATASET_PATH = Path(__file__).resolve().parent / "app/data/games_dataset.json"
 DATA_RECORDS = []
 try:
-    raw = load_games_dataset(DATASET_PATH)
+    raw = load_games_dataset(str(DATASET_PATH))
     DATA_RECORDS = [normalize_game_record(r) for r in raw]
-    print(f"✓ Loaded {len(DATA_RECORDS)} game records for retrieval")
+    print(f"[OK] Loaded {len(DATA_RECORDS)} game records for retrieval")
 except FileNotFoundError:
-    print(f"⚠ Dataset not found at {DATASET_PATH}, retrieval will be empty")
+    print(f"[!] Dataset not found at {DATASET_PATH}, retrieval will be empty")
 
 
 # ── In-memory session store (resets on restart — fine for hackathon) ───────
@@ -167,7 +172,7 @@ def run_pipeline(
 
     # 8 ── Build summary text
     summary = build_summary(final_game, state, session_id)
-    return summary, final_game, session_id
+    return summary, session_id
 
 
 # ── Phase 3: Gameplay helpers ─────────────────────────────────────────────────
@@ -217,7 +222,7 @@ def record_journal(
 ):
     """Record a text journal entry, summarize it, and return the result."""
     if session_id not in SESSION_STORE:
-        return "⚠ Unknown session", ""
+        return "[!] Unknown session"
 
     # Build full journal entry
     entry = create_journal_entry(
@@ -255,7 +260,7 @@ def record_journal(
         f"- Tags: {', '.join(summary['tags'])}\n"
         f"- Summary: {summary['moment_summary']}"
     )
-    return display, entry["journal_id"]
+    return display
 
 
 def upload_photo(
@@ -267,7 +272,7 @@ def upload_photo(
 ):
     """Log a photo upload event and return a confirmation."""
     if session_id not in SESSION_STORE:
-        return "⚠ Unknown session", []
+        return "[!] Unknown session"
 
     photo_name = ""
     if photo_file is not None:
@@ -318,7 +323,7 @@ def upload_photo(
 def end_game(session_id: str, team_id: str = "team-a"):
     """End the game, compute scores, and return a scoreboard."""
     if session_id not in SESSION_STORE:
-        return "⚠ Unknown session"
+        return "[!] Unknown session"
 
     session = SESSION_STORE[session_id]
     game = session["game"]
@@ -332,9 +337,9 @@ def end_game(session_id: str, team_id: str = "team-a"):
     scores = compute_scores(events, game)
     session["scores"] = scores
 
-    lines = ["# 🏆 Final Scoreboard\n"]
+    lines = ["# Final Scoreboard\n"]
     for ts in scores.get("team_scores", []):
-        marker = " 🏆" if ts["team_id"] == scores.get("winner") else ""
+        marker = " [WINNER]" if ts["team_id"] == scores.get("winner") else ""
         lines.append(f"### Team: {ts['team_id']}{marker}")
         lines.append(f"- **Total points:** {ts['points']}")
         lines.append(f"- Tasks completed: {ts['completed_tasks']}/{ts['total_tasks']}")
@@ -344,19 +349,19 @@ def end_game(session_id: str, team_id: str = "team-a"):
         lines.append("")
         lines.append("**Breakdown:**")
         for b in ts.get("scoring_breakdown", []):
-            lines.append(f"  • {b}")
+            lines.append(f"  * {b}")
         lines.append("")
 
     if scores.get("winner"):
-        lines.append(f"**Winner: {scores['winner']}** 🎉")
+        lines.append(f"**Winner: {scores['winner']}**")
 
-    return "\n".join(lines), scores
+    return "\n".join(lines)
 
 
 def generate_recap(session_id: str):
     """Generate the final story recap from all collected session data."""
     if session_id not in SESSION_STORE:
-        return "⚠ Unknown session"
+        return "[!] Unknown session", {}
 
     session = SESSION_STORE[session_id]
     game = session["game"]
@@ -377,6 +382,10 @@ def generate_recap(session_id: str):
     # Generate story
     result = generate_story(packet, session_id=session_id)
 
+    # Try to generate a poster image via BFL FLUX
+    poster_url, poster_status = generate_poster_sync(session_id, result["poster_prompt"])
+    session["poster_url"] = poster_url
+
     # Format for display
     lines = [
         "# 📖 Episode Recap\n",
@@ -386,10 +395,13 @@ def generate_recap(session_id: str):
         result["long_summary"],
         "",
         "---\n",
-        "### 🎨 Poster Prompt\n",
-        f"```{result['poster_prompt']}```",
     ]
 
+    if poster_url:
+        lines.append(f"### 🖼️ Poster\n\n![Recap Poster]({poster_url})\n")
+    else:
+        lines.append(f"### 🎨 Poster Prompt\n```{result['poster_prompt']}```\n\n_{poster_status}_\n")
+
     return "\n".join(lines), result
 
 
@@ -535,7 +547,6 @@ with gr.Blocks(title="CityQuest-AI – Game Generator") as demo:
                 output_md = gr.Markdown(
                     value="Click **Generate Game** to create a new game!"
                 )
-                output_json = gr.JSON(label="Raw game JSON", visible=False)
                 session_id_box = gr.Textbox(
                     label="Session ID (copy to Play tab)", interactive=False, visible=True
                 )
@@ -616,7 +627,7 @@ with gr.Blocks(title="CityQuest-AI – Game Generator") as demo:
             game_type, city, area, location_type,
             duration_minutes, num_players, difficulty, age_group, energy_level,
         ],
-        outputs=[output_md, output_json, session_id_box],
+        outputs=[output_md, session_id_box],
     )
 
     # Play tab — task actions

app/main.py

@@ -1,577 +0,0 @@
-"""Hugging Face Spaces entry point with Zero GPU support.
-
-On HF Spaces, @spaces.GPU auto-allocates a GPU when the function runs
-and frees it after — saving costs on zero-GPU (paid) tier.
-"""
-
-import os
-import uuid
-import json
-from pathlib import Path
-
-import gradio as gr
-
-try:
-    import spaces  # only available on Hugging Face Spaces runtime
-except ImportError:
-    spaces = None
-
-from app.services.retrieval import load_games_dataset, normalize_game_record, retrieve_examples
-from app.services.generator import generate_game, generate_game_with_model, build_generation_prompt, NEMOTRON_MODEL_ID, NEMOTRON_GGUF_FILE
-from app.services.validator import validate_game, repair_game
-from app.services.schema_validator import create_minimal_game_template
-from app.services.tracing import log_event, log_generation_trace, load_events
-from app.services.journal import (
-    create_journal_entry, save_journal_entry, summarize_journal,
-    load_journal_entries, detect_mood, assess_story_value,
-)
-from app.services.scoring import compute_scores
-from app.services.story import build_story_packet, generate_story
-
-
-# ── Load dataset once on startup ──────────────────────────────────────────────
-DATASET_PATH = Path(__file__).resolve().parent.parent / "app/data/games_dataset.json"
-DATA_RECORDS = []
-try:
-    raw = load_games_dataset(str(DATASET_PATH))
-    DATA_RECORDS = [normalize_game_record(r) for r in raw]
-    print(f"✓ Loaded {len(DATA_RECORDS)} game records for retrieval")
-except FileNotFoundError:
-    print(f"⚠ Dataset not found at {DATASET_PATH}, retrieval will be empty")
-
-# ── In-memory session store ───────────────────────────────────────────────────
-SESSION_STORE: dict[str, dict] = {}
-
-
-# ── Zero GPU wrappers ─────────────────────────────────────────────────────────
-
-def _generate_with_gpu(config: dict, retrieved: list[dict]) -> dict:
-    """Call the model for generation — wrapped in @spaces.GPU on HF Spaces.
-    
-    The 2.84 GB GGUF model is lazily downloaded on first call (inside the GPU
-    context) via ``hf_hub_download``.  ``Llama(model_path=...)`` initialisation
-    happens here where CUDA is available via @spaces.GPU.
-    
-    Inside @spaces.GPU, torch.cuda.is_available() returns True,
-    so generator.py auto-detects GPU via _get_n_gpu_layers().
-    """
-    prompt = build_generation_prompt(config, retrieved)
-    json_str = generate_game_with_model(
-        prompt,
-        model_name="nemotron",
-    )
-    if json_str:
-        try:
-            game = json.loads(json_str)
-            if all(field in game for field in ["game_id", "title", "setup", "tasks", "safety"]):
-                return game
-        except json.JSONDecodeError:
-            pass
-    # Fallback — returns mock without using GPU
-    return None
-
-
-# Apply @spaces.GPU only if the decorator exists (HF Spaces runtime)
-# duration=300 allows up to 5 minutes for first-run 2.84 GB model download + init
-if spaces is not None:
-    _generate_with_gpu = spaces.GPU(duration=300)(_generate_with_gpu)
-
-
-def run_pipeline(
-    game_type: str,
-    city: str,
-    area: str,
-    location_type: str,
-    duration_minutes: int,
-    num_players: int,
-    difficulty: str,
-    age_group: str,
-    energy_level: str,
-):
-    """Run the full AI generation pipeline end-to-end."""
-    session_id = str(uuid.uuid4())
-
-    config = {
-        "game_type": game_type,
-        "city": city or "Paris",
-        "area": area or "Downtown",
-        "location_type": location_type,
-        "duration_minutes": int(duration_minutes),
-        "num_players": int(num_players),
-        "difficulty": difficulty,
-        "age_group": age_group,
-        "energy_level": energy_level,
-        "photo_enabled": True,
-    }
-
-    state = {}
-
-    # 1 ── Retrieval
-    state["num_retrieved"] = 0
-    if DATA_RECORDS:
-        retrieved = retrieve_examples(config, DATA_RECORDS, k=3)
-        state["num_retrieved"] = len(retrieved)
-        state["retrieved_ids"] = [r["id"] for r in retrieved]
-    else:
-        retrieved = []
-
-    # 2 ── Generation (with Zero GPU if available)
-    game = _generate_with_gpu(config, retrieved)
-    if game is None:
-        from app.services.generator import generate_game_mock
-        game = generate_game_mock(config, retrieved)
-        print("Using mock generation (model unavailable or failed)")
-
-    state["game_id"] = game["game_id"]
-    state["game_title"] = game["title"]
-
-    # 3 ── Validation
-    is_valid, failures = validate_game(game, config)
-    state["validation_passed"] = is_valid
-    state["validation_failures"] = failures
-
-    # 4 ── Repair (if needed)
-    repaired = None
-    if not is_valid:
-        repaired = repair_game(game, failures, config)
-        state["repair_applied"] = True
-        is_valid2, failures2 = validate_game(repaired, config)
-        state["repair_valid"] = is_valid2
-        state["remaining_failures"] = failures2
-    else:
-        state["repair_applied"] = False
-
-    final_game = repaired if repaired is not None else game
-
-    # 5 ── Log generation trace
-    log_generation_trace(
-        session_id=session_id,
-        config=config,
-        retrieved_examples=retrieved,
-        game=final_game,
-        validation_passed=is_valid or (repaired is not None and state.get("repair_valid", False)),
-        validation_failures=failures,
-        repaired_game=repaired,
-    )
-
-    # 6 ── Reveal all tasks as events
-    for task in final_game.get("tasks", []):
-        log_event(session_id, "task_revealed", {
-            "task_id": task["task_id"],
-            "title": task["title"],
-            "points": task["points"],
-        })
-
-    # 7 ── Store session
-    SESSION_STORE[session_id] = {
-        "config": config,
-        "game": final_game,
-        "events": [],
-        "journals": [],
-    }
-
-    # 8 ── Build summary text
-    summary = build_summary(final_game, state, session_id)
-    return summary, final_game, session_id
-
-
-# ── Phase 3: Gameplay helpers ─────────────────────────────────────────────────
-
-def complete_task(session_id: str, task_id: str, team_id: str = "team-a"):
-    if session_id not in SESSION_STORE:
-        return "⚠ Unknown session"
-    ev = log_event(session_id, "task_completed", {
-        "task_id": task_id,
-        "summary": f"Team {team_id} completed {task_id}",
-    }, team_id=team_id)
-    SESSION_STORE[session_id]["events"].append(ev)
-    return f"✅ Task {task_id} completed!"
-
-
-def skip_task(session_id: str, task_id: str, team_id: str = "team-a"):
-    if session_id not in SESSION_STORE:
-        return "⚠ Unknown session"
-    ev = log_event(session_id, "task_skipped", {
-        "task_id": task_id,
-        "summary": f"Team {team_id} skipped {task_id}",
-    }, team_id=team_id)
-    SESSION_STORE[session_id]["events"].append(ev)
-    return f"⏭️ Task {task_id} skipped."
-
-
-def use_hint(session_id: str, task_id: str, team_id: str = "team-a"):
-    if session_id not in SESSION_STORE:
-        return "⚠ Unknown session"
-    ev = log_event(session_id, "hint_used", {
-        "task_id": task_id,
-        "summary": f"Team {team_id} used a hint for {task_id}",
-    }, team_id=team_id)
-    SESSION_STORE[session_id]["events"].append(ev)
-    return f"💡 Hint used for {task_id} (−5 pts)"
-
-
-def record_journal(
-    session_id: str,
-    transcript: str,
-    task_id: str = "",
-    location_note: str = "",
-    team_id: str = "team-a",
-):
-    if session_id not in SESSION_STORE:
-        return "⚠ Unknown session", ""
-
-    entry = create_journal_entry(
-        transcript=transcript,
-        session_id=session_id,
-        team_id=team_id,
-        task_id=task_id or None,
-        location_note=location_note,
-    )
-
-    summary = summarize_journal(transcript, task_id=task_id or None, location_note=location_note)
-    entry["moment_summary"] = summary["moment_summary"]
-    entry["tags"] = summary["tags"]
-    entry["story_value"] = summary["story_value"]
-
-    save_journal_entry(entry)
-
-    ev = log_event(session_id, "journal_recorded", {
-        "journal_id": entry["journal_id"],
-        "mood": entry["mood"],
-        "story_value": summary["story_value"],
-        "summary": summary["moment_summary"],
-    }, team_id=team_id)
-    SESSION_STORE[session_id]["events"].append(ev)
-    SESSION_STORE[session_id]["journals"].append(entry)
-
-    display = (
-        f"🎙️ **Journal recorded!**\n"
-        f"- Mood: *{entry['mood']}*\n"
-        f"- Story value: **{summary['story_value']}**\n"
-        f"- Tags: {', '.join(summary['tags'])}\n"
-        f"- Summary: {summary['moment_summary']}"
-    )
-    return display, entry["journal_id"]
-
-
-def upload_photo(
-    session_id: str,
-    photo_file,
-    caption: str = "",
-    task_id: str = "",
-    team_id: str = "team-a",
-):
-    if session_id not in SESSION_STORE:
-        return "⚠ Unknown session", []
-
-    photo_name = ""
-    if photo_file is not None:
-        if isinstance(photo_file, str):
-            photo_name = photo_file.split("/")[-1].split("\\")[-1]
-        else:
-            photo_name = getattr(photo_file, "name", "photo")
-
-    photo_id = f"photo-{uuid.uuid4().hex[:8]}"
-
-    payload = {
-        "photo_id": photo_id,
-        "photo_name": photo_name,
-        "caption": caption,
-        "summary": f"Team {team_id} uploaded photo for {task_id or 'general'}",
-    }
-    if task_id:
-        payload["task_id"] = task_id
-
-    ev = log_event(session_id, "photo_uploaded", payload, team_id=team_id)
-    SESSION_STORE[session_id]["events"].append(ev)
-
-    if "photos" not in SESSION_STORE[session_id]:
-        SESSION_STORE[session_id]["photos"] = []
-    SESSION_STORE[session_id]["photos"].append({
-        "photo_id": photo_id,
-        "photo_name": photo_name,
-        "caption": caption,
-        "task_id": task_id,
-    })
-
-    photos = SESSION_STORE[session_id]["photos"]
-    gallery_lines = [f"📸 **{p['photo_id']}** — {p['caption'] or '(no caption)'} [{p['task_id'] or 'general'}]" for p in photos]
-
-    display = (
-        f"📸 **Photo uploaded!**\n"
-        f"- ID: `{photo_id}`\n"
-        f"- Caption: {caption or '(none)'}\n"
-        f"- Related task: {task_id or 'general'}\n\n"
-        f"**All photos ({len(photos)}):**\n" + "\n".join(gallery_lines)
-    )
-    return display
-
-
-def end_game(session_id: str, team_id: str = "team-a"):
-    if session_id not in SESSION_STORE:
-        return "⚠ Unknown session"
-
-    session = SESSION_STORE[session_id]
-    game = session["game"]
-    events = load_events(session_id=session_id)
-
-    ev = log_event(session_id, "game_finished", {
-        "summary": f"Game finished — session {session_id}",
-    }, team_id=team_id)
-    events.append(ev)
-
-    scores = compute_scores(events, game)
-    session["scores"] = scores
-
-    lines = ["# 🏆 Final Scoreboard\n"]
-    for ts in scores.get("team_scores", []):
-        marker = " 🏆" if ts["team_id"] == scores.get("winner") else ""
-        lines.append(f"### Team: {ts['team_id']}{marker}")
-        lines.append(f"- **Total points:** {ts['points']}")
-        lines.append(f"- Tasks completed: {ts['completed_tasks']}/{ts['total_tasks']}")
-        lines.append(f"- Hints used: {ts['hints_used']}")
-        if ts.get("bonuses"):
-            lines.append(f"- Bonuses: {', '.join(ts['bonuses'])}")
-        lines.append("")
-        lines.append("**Breakdown:**")
-        for b in ts.get("scoring_breakdown", []):
-            lines.append(f"  • {b}")
-        lines.append("")
-
-    if scores.get("winner"):
-        lines.append(f"**Winner: {scores['winner']}** 🎉")
-
-    return "\n".join(lines), scores
-
-
-def generate_recap(session_id: str):
-    if session_id not in SESSION_STORE:
-        return "⚠ Unknown session"
-
-    session = SESSION_STORE[session_id]
-    game = session["game"]
-    events = load_events(session_id=session_id)
-    journals = load_journal_entries(session_id=session_id)
-    scores = session.get("scores", compute_scores(events, game))
-    photos = session.get("photos", [])
-
-    packet = build_story_packet(
-        game=game,
-        events=events,
-        scores=scores,
-        journal_entries=journals,
-        photo_captions=photos,
-    )
-
-    result = generate_story(packet, session_id=session_id)
-
-    lines = [
-        "# 📖 Episode Recap\n",
-        result["short_recap"],
-        "",
-        "---\n",
-        result["long_summary"],
-        "",
-        "---\n",
-        "### 🎨 Poster Prompt\n",
-        f"```{result['poster_prompt']}```",
-    ]
-
-    return "\n".join(lines), result
-
-
-# ── Build summary text ────────────────────────────────────────────────────────
-def build_summary(game: dict, state: dict, session_id: str = "") -> str:
-    lines = []
-    lines.append(f"# 🎮 {game.get('title', 'Untitled')}")
-    lines.append("")
-    if session_id:
-        lines.append(f"> Session `{session_id[:12]}…` — paste this in the **Play** tab to log progress.")
-        lines.append("")
-    lines.append("## 📋 Setup")
-    setup = game.get("setup", {})
-    lines.append(f"- **Location:** {setup.get('city', '?')} — {setup.get('area', '?')}")
-    lines.append(f"- **Meeting point:** {setup.get('meeting_point', '?')}")
-    lines.append(f"- **Duration:** {setup.get('duration_minutes', '?')} min")
-    lines.append(f"- **Players:** {setup.get('num_players', '?')}")
-    lines.append("")
-
-    lines.append("## 📜 Rules")
-    for i, rule in enumerate(game.get("rules", []), 1):
-        lines.append(f"  {i}. {rule}")
-    lines.append("")
-
-    lines.append("## 🎯 Tasks")
-    for t in game.get("tasks", []):
-        time_str = f"{t.get('time_limit_minutes', '∞')} min" if t.get("time_limit_minutes") else "No time limit"
-        lines.append(f"  **{t.get('task_id', '?')}:** {t.get('title', '?')}")
-        lines.append(f"  - *{t.get('description', '')[:80]}*")
-        lines.append(f"  - 🏆 {t.get('points', 0)} pts | ⏱ {time_str} | 📸 {t.get('proof_type', '?')}")
-        lines.append(f"  - 💡 {t.get('hint', '')[:70]}")
-        lines.append(f"  - 🛡 {t.get('safety_note', '')[:70]}")
-        lines.append("")
-
-    lines.append("## 💡 Global Hints")
-    for h in game.get("global_hints", []):
-        lines.append(f"  • {h}")
-    lines.append("")
-
-    lines.append("## 🔒 Safety")
-    safety = game.get("safety", {})
-    lines.append(f"- **Zone:** {safety.get('allowed_zone', '?')}")
-    lines.append(f"- **Supervision required:** {'Yes' if safety.get('adult_supervision') else 'No'}")
-    lines.append(f"- **Forbidden:** {', '.join(safety.get('forbidden_behaviors', []))}")
-    lines.append("")
-
-    lines.append("## 📊 Scoring")
-    for s in game.get("score_rules", []):
-        lines.append(f"  • {s}")
-    lines.append(f"- **Tie-breaker:** {game.get('tie_breaker', '?')}")
-    lines.append("")
-
-    lines.append("## 📖 Story Seed")
-    seed = game.get("story_seed", {})
-    lines.append(f"- **Tone:** {seed.get('tone', '?')}")
-    lines.append(f"- **Motifs:** {', '.join(seed.get('motifs', []))}")
-    lines.append(f"- **Recap style:** {seed.get('recap_style', '?')}")
-    lines.append("")
-
-    lines.append("---")
-    lines.append("### 🔍 Pipeline trace")
-    lines.append(f"- Retrieval: {state.get('num_retrieved', 0)} examples found")
-    if state.get("retrieved_ids"):
-        lines.append(f"- Retrieved IDs: {', '.join(state['retrieved_ids'])}")
-    lines.append(f"- Game ID: {state.get('game_id', '?')}")
-    if state.get("validation_passed"):
-        lines.append(f"- ✅ Validation passed")
-    else:
-        lines.append(f"- ❌ Validation failed ({len(state.get('validation_failures', []))} issues)")
-        if state.get("repair_applied"):
-            lines.append(f"- 🔧 Repair applied → {'✅ Passed' if state.get('repair_valid') else '❌ Still has issues'}")
-        for f in state.get("validation_failures", [])[:5]:
-            lines.append(f"  - {f}")
-        leftover = state.get("remaining_failures", [])
-        if leftover:
-            for f in leftover[:5]:
-                lines.append(f"  - ⚠ {f}")
-
-    return "\n".join(lines)
-
-
-# ── Gradio UI ─────────────────────────────────────────────────────────────────
-with gr.Blocks(title="CityQuest-AI – Game Generator") as demo:
-    gr.Markdown(
-        """
-        # 🌍 CityQuest-AI — AI Game Generator
-        Configure your game, play it, record journals, and get a story recap.
-        """
-    )
-
-    # ── Tab 1: Generate ────────────────────────────────────────────────────
-    with gr.Tab("🎮 Generate"):
-        with gr.Row():
-            with gr.Column(scale=1):
-                gr.Markdown("### Game Configuration")
-
-                game_type = gr.Dropdown(
-                    label="Game Type",
-                    choices=["scavenger_hunt", "hide_and_seek", "tag"],
-                    value="scavenger_hunt",
-                )
-                city = gr.Textbox(label="City", value="Paris", info="Default: Paris")
-                area = gr.Textbox(label="Area", value="Le Marais", info="Neighbourhood or district")
-                location_type = gr.Radio(
-                    label="Location Type",
-                    choices=["park", "street", "landmark", "mixed"],
-                    value="mixed",
-                )
-                duration_minutes = gr.Slider(label="Duration (minutes)", minimum=15, maximum=120, value=60, step=5)
-                num_players = gr.Slider(label="Number of Players", minimum=2, maximum=10, value=4, step=1)
-                difficulty = gr.Dropdown(label="Difficulty", choices=["easy", "medium", "hard"], value="medium")
-                age_group = gr.Dropdown(label="Age Group", choices=["kids", "teens", "adults", "mixed"], value="adults")
-                energy_level = gr.Radio(label="Energy Level", choices=["low", "medium", "high"], value="medium")
-                generate_btn = gr.Button("🚀 Generate Game", variant="primary", size="lg")
-
-            with gr.Column(scale=2):
-                gr.Markdown("### 📄 Generated Game")
-                output_md = gr.Markdown(value="Click **Generate Game** to create a new game!")
-                output_json = gr.JSON(label="Raw game JSON", visible=False)
-                session_id_box = gr.Textbox(label="Session ID (copy to Play tab)", interactive=False, visible=True)
-
-    # ── Tab 2: Play ────────────────────────────────────────────────────────
-    with gr.Tab("🎯 Play"):
-        gr.Markdown("### Simulate gameplay")
-        with gr.Row():
-            play_session_id = gr.Textbox(label="Session ID", placeholder="Paste session ID here…")
-            play_team_id = gr.Textbox(label="Team ID", value="team-a")
-
-        with gr.Row():
-            with gr.Column():
-                gr.Markdown("#### Task Actions")
-                play_task_id = gr.Textbox(label="Task ID (e.g. t1, t2)", placeholder="t1")
-                with gr.Row():
-                    complete_btn = gr.Button("✅ Complete Task", variant="primary")
-                    skip_btn = gr.Button("⏭️ Skip Task")
-                    hint_btn = gr.Button("💡 Use Hint")
-                task_feedback = gr.Markdown(value="")
-
-            with gr.Column():
-                gr.Markdown("#### 🎙️ Voice Journal")
-                journal_transcript = gr.Textbox(label="Journal entry", lines=4, placeholder="We just found the mural near the canal — it was incredible!")
-                journal_task_id = gr.Textbox(label="Related Task ID (optional)", placeholder="t1")
-                journal_location = gr.Textbox(label="Location note", placeholder="Near the canal on Rue de Rivoli")
-                journal_btn = gr.Button("🎙️ Record Journal", variant="secondary")
-                journal_output = gr.Markdown(value="")
-
-        with gr.Row():
-            with gr.Column():
-                gr.Markdown("#### 📸 Photo Upload")
-                photo_file = gr.Image(label="Upload a photo", type="filepath", height=200)
-                photo_caption = gr.Textbox(label="Caption", placeholder="The mural we just discovered!")
-                photo_task_id = gr.Textbox(label="Related Task ID (optional)", placeholder="t1")
-                photo_btn = gr.Button("📸 Upload Photo", variant="secondary")
-                photo_output = gr.Markdown(value="")
-
-        with gr.Row():
-            end_btn = gr.Button("🏁 End Game & Score", variant="primary", size="lg")
-            scoreboard_md = gr.Markdown(value="")
-
-    # ── Tab 3: Recap ───────────────────────────────────────────────────────
-    with gr.Tab("📖 Recap"):
-        gr.Markdown("### Generate a story recap")
-        recap_session_id = gr.Textbox(label="Session ID", placeholder="Paste session ID here…")
-        recap_btn = gr.Button("📖 Generate Recap", variant="primary", size="lg")
-        recap_md = gr.Markdown(value="")
-        recap_json = gr.JSON(label="Recap data", visible=False)
-
-    # ── Wire events ────────────────────────────────────────────────────────
-    generate_btn.click(
-        fn=run_pipeline,
-        inputs=[game_type, city, area, location_type, duration_minutes, num_players, difficulty, age_group, energy_level],
-        outputs=[output_md, output_json, session_id_box],
-    )
-
-    complete_btn.click(fn=complete_task, inputs=[play_session_id, play_task_id, play_team_id], outputs=task_feedback)
-    skip_btn.click(fn=skip_task, inputs=[play_session_id, play_task_id, play_team_id], outputs=task_feedback)
-    hint_btn.click(fn=use_hint, inputs=[play_session_id, play_task_id, play_team_id], outputs=task_feedback)
-
-    journal_btn.click(
-        fn=record_journal,
-        inputs=[play_session_id, journal_transcript, journal_task_id, journal_location, play_team_id],
-        outputs=[journal_output, gr.Textbox(visible=False)],
-    )
-
-    photo_btn.click(
-        fn=upload_photo,
-        inputs=[play_session_id, photo_file, photo_caption, photo_task_id, play_team_id],
-        outputs=photo_output,
-    )
-
-    end_btn.click(fn=end_game, inputs=[play_session_id, play_team_id], outputs=[scoreboard_md, gr.JSON(visible=False)])
-
-    recap_btn.click(fn=generate_recap, inputs=[recap_session_id], outputs=[recap_md, recap_json])
-
-
-# ── Launch ────────────────────────────────────────────────────────────────────
-if __name__ == "__main__":
-    demo.launch()

app/services/image_gen.py

@@ -0,0 +1,107 @@
+"""Black Forest Labs FLUX poster generation module.
+
+Generates a recap poster image from a text prompt using the BFL API.
+When the API key is not set or the call fails, gracefully returns None
+so the pipeline always produces a visible result.
+
+Sponsor alignment: Black Forest Labs FLUX produces a visible demo artifact
+(the recap poster) rather than being hidden in backend code.
+"""
+
+import os
+from typing import Optional
+
+
+# ── Configuration ───────────────────────────────────────────────────────────
+BFL_API_KEY_ENV = "BFL_API_KEY"
+
+
+def generate_poster(
+    poster_prompt: str,
+    api_key: Optional[str] = None,
+) -> Optional[str]:
+    """Generate a poster image using Black Forest Labs FLUX API.
+
+    Args:
+        poster_prompt: Text prompt describing the desired image.
+        api_key: BFL API key. Falls back to ``BFL_API_KEY`` env var.
+
+    Returns:
+        URL string of the generated image, or ``None`` on failure.
+    """
+    key = api_key or os.environ.get(BFL_API_KEY_ENV)
+    if not key:
+        print(
+            "[image_gen] BFL_API_KEY not set — "
+            "set the environment variable to enable poster generation"
+        )
+        return None
+
+    try:
+        import bfl
+
+        client = bfl.Bfl(api_key=key)
+
+        # FLUX.1 Pro / FLUX.1.1 Pro — use the latest available
+        result = client.generate_image(
+            prompt=poster_prompt,
+            width=1024,
+            height=768,
+            steps=25,
+            guidance=3.5,
+        )
+
+        # The result object typically has a ``url`` or ``image_url`` attribute
+        image_url = getattr(result, "url", None) or getattr(result, "image_url", None)
+        if image_url:
+            print(f"[image_gen] Poster generated -> {image_url[:80]}...")
+            return image_url
+
+        print(f"[image_gen] BFL response had no URL: {result}")
+        return None
+
+    except ImportError:
+        print(
+            "[image_gen] 'bfl' Python package not installed. "
+            "Install with: pip install bfl"
+        )
+        return None
+    except Exception as e:
+        print(f"[image_gen] BFL API call failed: {type(e).__name__}: {e}")
+        return None
+
+
+def generate_poster_sync(
+    session_id: str,
+    poster_prompt: str,
+) -> tuple[Optional[str], str]:
+    """Generate a poster and return (image_url, status_message).
+
+    This is a convenience wrapper for use in the pipeline entry point.
+    The status message explains why no image was generated if the call
+    fails, so the UI can display a helpful fallback.
+
+    Args:
+        session_id: Session identifier (for logging).
+        poster_prompt: Text prompt for the image.
+
+    Returns:
+        Tuple of (image_url_or_None, status_message).
+    """
+    image_url = generate_poster(poster_prompt)
+
+    if image_url:
+        return image_url, f"\ud83d\uddbc\ufe0f **Poster generated!** [View image]({image_url})"
+
+    key = os.environ.get(BFL_API_KEY_ENV)
+    if not key:
+        return None, (
+            "\u26a0\ufe0f Poster generation unavailable — "
+            "set `BFL_API_KEY` environment variable to enable "
+            "Black Forest Labs FLUX poster generation."
+        )
+
+    return None, (
+        "\u26a0\ufe0f Poster generation failed — "
+        "check the BFL API key and try again."
+    )

app/services/minicpm.py

@@ -0,0 +1,208 @@
+"""OpenBMB MiniCPM5-1B recap generation via llama.cpp.
+
+Lazy-downloads the GGUF model on first call (same pattern as generator.py)
+and provides a ``generate_recap()`` function that takes a story packet and
+returns a recap dict with ``short_recap``, ``long_summary``, ``poster_prompt``.
+
+Sponsor alignment: OpenBMB MiniCPM5-1B gets the *first attempt* at recap
+before falling through to Nemotron → template.
+"""
+
+import json
+import os
+from typing import Optional
+
+
+# ── Model configuration ─────────────────────────────────────────────────────
+MINICPM_MODEL_ID = "openbmb/MiniCPM5-1B-GGUF"
+MINICPM_GGUF_FILE = "MiniCPM5-1B-Q4_K_M.gguf"  # 688 MB, good quality/size
+
+
+# ── Lazy model path resolution ──────────────────────────────────────────────
+_model_path: Optional[str] = None
+_model_download_attempted = False
+_model_cache: dict[str, object] = {}
+
+
+def _resolve_model_path() -> Optional[str]:
+    """Download the MiniCPM GGUF model to local cache and return its path.
+
+    Skips download if ``CITYQUEST_SKIP_MODEL`` environment variable is set
+    (used by fast-test mode).
+
+    Uses ``hf_hub_download`` which caches to ``~/.cache/huggingface/hub/``
+    so subsequent calls are instant (no re-download).
+
+    Returns:
+        Absolute path to the GGUF file, or ``None`` on failure or skip.
+    """
+    global _model_path, _model_download_attempted
+    if _model_download_attempted:
+        return _model_path
+    _model_download_attempted = True
+
+    if os.environ.get("CITYQUEST_SKIP_MODEL"):
+        print("[minicpm] CITYQUEST_SKIP_MODEL set — skipping model download")
+        return None
+
+    try:
+        os.environ.setdefault("HF_HUB_ENABLE_HF_TRANSFER", "1")
+
+        from huggingface_hub import hf_hub_download
+
+        print(f"[minicpm] Downloading {MINICPM_MODEL_ID}/{MINICPM_GGUF_FILE} ...")
+        _model_path = hf_hub_download(
+            repo_id=MINICPM_MODEL_ID,
+            filename=MINICPM_GGUF_FILE,
+        )
+        print(f"[minicpm] Downloaded -> {_model_path}")
+    except Exception as e:
+        print(f"[minicpm] Download failed: {type(e).__name__}: {e}")
+    return _model_path
+
+
+def _get_n_gpu_layers() -> int:
+    """Auto-detect GPU availability for llama.cpp inference.
+
+    Returns:
+        -1 if CUDA/GPU available (all layers on GPU), 0 for CPU-only.
+    """
+    try:
+        import torch
+        if torch.cuda.is_available():
+            return -1
+    except ImportError:
+        pass
+    return 0
+
+
+# ── Core inference ──────────────────────────────────────────────────────────
+
+def generate_summary(
+    prompt: str,
+    temperature: float = 0.7,
+    max_tokens: int = 1024,
+) -> Optional[str]:
+    """Run MiniCPM5-1B inference via llama.cpp and return the generated text.
+
+    Args:
+        prompt: The full prompt string to send to the model.
+        temperature: Sampling temperature (default 0.7).
+        max_tokens: Maximum tokens to generate (default 1024).
+
+    Returns:
+        Generated text string, or ``None`` if the model is unavailable.
+    """
+    try:
+        from llama_cpp import Llama
+
+        cache_key = f"minicpm_llama"
+        if cache_key in _model_cache:
+            llm = _model_cache[cache_key]
+        else:
+            model_path = _resolve_model_path()
+            if not model_path:
+                print("[minicpm] No model path available")
+                return None
+
+            n_gpu_layers = _get_n_gpu_layers()
+            gpu_info = "GPU" if n_gpu_layers < 0 else "CPU"
+            print(f"[minicpm] Initialising llama.cpp from: {model_path} ({gpu_info})")
+            llm = Llama(
+                model_path=model_path,
+                verbose=False,
+                n_gpu_layers=n_gpu_layers,
+                n_ctx=4096,
+            )
+            _model_cache[cache_key] = llm
+
+        # MiniCPM5 uses standard Llama chat template
+        messages = [
+            {"role": "system", "content": "You are a talented narrative writer. Return ONLY valid JSON. No other text."},
+            {"role": "user", "content": prompt},
+        ]
+
+        result = llm.create_chat_completion(
+            messages=messages,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            top_p=0.95,
+            stop=["```"],
+        )
+
+        text = result["choices"][0]["message"]["content"]
+        return text.strip()
+
+    except ImportError:
+        print("[minicpm] llama-cpp-python not available")
+        return None
+    except Exception as e:
+        print(f"[minicpm] Inference failed: {type(e).__name__}: {e}")
+        return None
+
+
+def _extract_json(text: str) -> Optional[dict]:
+    """Extract a JSON object from generated text by tracking brace depth."""
+    start = text.find("{")
+    if start == -1:
+        return None
+
+    depth = 0
+    for i in range(start, len(text)):
+        if text[i] == "{":
+            depth += 1
+        elif text[i] == "}":
+            depth -= 1
+            if depth == 0:
+                try:
+                    return json.loads(text[start : i + 1])
+                except json.JSONDecodeError:
+                    return None
+    return None
+
+
+# ── Recap generation ────────────────────────────────────────────────────────
+
+def generate_recap(story_packet: dict) -> Optional[dict]:
+    """Generate a recap using MiniCPM5-1B.
+
+    Builds a prompt from the story packet and attempts to produce a recap
+    dict with ``short_recap``, ``long_summary``, ``poster_prompt``.
+
+    Args:
+        story_packet: Structured packet from ``story.build_story_packet()``.
+
+    Returns:
+        Recap dict with three keys, or ``None`` if generation fails.
+    """
+    packet_str = json.dumps(story_packet, indent=2, default=str)[:3000]
+
+    prompt = (
+        "You are a talented narrative writer creating engaging recaps "
+        "of location-based games.\n\n"
+        f"## Game Data\n{packet_str}\n\n"
+        "## Instructions\n"
+        "- Use ONLY facts from logs, tasks, journals, scores, and photos\n"
+        "- Do NOT invent locations or quotes\n"
+        "- Mention 2-4 concrete moments from player journals\n"
+        "- Highlight the decisive turning point\n"
+        "- Maintain a lively, memorable tone\n"
+        "- Keep recaps between 150-250 words for short recap, "
+        "400-600 words for long summary\n\n"
+        "## Output\n"
+        "Generate:\n"
+        "1. short_recap: Brief highlight for the result screen\n"
+        "2. long_summary: Full episode recap\n"
+        "3. poster_prompt: Visual prompt for image generation\n\n"
+        "Return as JSON with these three keys."
+    )
+
+    text = generate_summary(prompt, temperature=0.8, max_tokens=2048)
+    if not text:
+        return None
+
+    result = _extract_json(text)
+    if result and all(k in result for k in ("short_recap", "long_summary", "poster_prompt")):
+        return result
+
+    return None

app/services/story.py

@@ -17,6 +17,7 @@ from pathlib import Path
 from typing import Optional
 
 from app.services.tracing import log_event
+from app.services.generator import NEMOTRON_MODEL_ID, NEMOTRON_GGUF_FILE
 
 
 # ── Story packet builder ───────────────────────────────────────────────────
@@ -253,10 +254,9 @@ def _llm_recap(prompt_template: str, story_packet: dict) -> Optional[dict]:
     try:
         from llama_cpp import Llama
 
-        model_id = "nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF"
         llm = Llama.from_pretrained(
-            repo_id=model_id,
-            filename="model.gguf",
+            repo_id=NEMOTRON_MODEL_ID,
+            filename=NEMOTRON_GGUF_FILE,
             verbose=False,
             n_gpu_layers=-1,
             n_ctx=2048,
@@ -299,8 +299,8 @@ def _llm_recap(prompt_template: str, story_packet: dict) -> Optional[dict]:
 def generate_story(story_packet: dict, session_id: Optional[str] = None) -> dict:
     """Generate final recap story from game data and events.
 
-    Attempts LLM-based generation first; falls back to high-quality
-    templates so the pipeline always returns a result.
+    Attempts MiniCPM-based generation first, then Nemotron, then falls
+    back to high-quality templates so the pipeline always returns a result.
 
     Args:
         story_packet: Structured packet with game info, scores, journals, photos.
@@ -310,15 +310,27 @@ def generate_story(story_packet: dict, session_id: Optional[str] = None) -> dict
         Story output dict with keys ``short_recap``, ``long_summary``,
         ``poster_prompt``, ``story_packet``.
     """
-    # Try LLM path
-    template_path = Path("app/prompts/story_recap.txt")
-    prompt_template = ""
-    if template_path.exists():
-        prompt_template = template_path.read_text(encoding="utf-8")
-
+    # Try MiniCPM path first (OpenBMB sponsor model)
     llm_result = None
-    if prompt_template:
-        llm_result = _llm_recap(prompt_template, story_packet)
+    try:
+        from app.services.minicpm import generate_recap as minicpm_recap
+        llm_result = minicpm_recap(story_packet)
+        if llm_result:
+            print("[story] MiniCPM recap generated successfully")
+    except Exception as exc:
+        print(f"[story] MiniCPM recap unavailable: {exc}")
+
+    # Fall back to Nemotron LLM path
+    if not llm_result:
+        template_path = Path("app/prompts/story_recap.txt")
+        prompt_template = ""
+        if template_path.exists():
+            prompt_template = template_path.read_text(encoding="utf-8")
+
+        if prompt_template:
+            llm_result = _llm_recap(prompt_template, story_packet)
+            if llm_result:
+                print("[story] Nemotron recap generated successfully")
 
     if llm_result and all(k in llm_result for k in ("short_recap", "long_summary", "poster_prompt")):
         short_recap = llm_result["short_recap"]

requirements.txt

@@ -7,4 +7,5 @@ huggingface_hub
 --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124
 llama-cpp-python
 gradio>=6.16.0
-jsonschema
+jsonschema
+# modal            # uncomment to deploy to Modal cloud GPU

test_end_to_end.py

@@ -0,0 +1,420 @@
+"""End-to-end test for the full CityQuest AI pipeline.
+
+Run with ``CITYQUEST_FAST_TEST=1`` to skip GGUF model downloads
+and use mock generation for LLM-dependent steps.
+
+Usage:
+    python test_end_to_end.py
+    CITYQUEST_FAST_TEST=1 python test_end_to_end.py
+"""
+
+import os
+import sys
+import json
+import uuid
+from pathlib import Path
+
+# ── Fast-test guard ──────────────────────────────────────────────────────────
+if os.environ.get("CITYQUEST_FAST_TEST"):
+    print("[test] FAST TEST - skipping GGUF model download and LLM inference")
+    os.environ["CITYQUEST_SKIP_MODEL"] = "1"
+
+# ── Test tracking ────────────────────────────────────────────────────────────
+passed = 0
+failed = 0
+errors: list[str] = []
+
+
+def check(label: str, condition: bool, detail: str = ""):
+    global passed, failed
+    if condition:
+        passed += 1
+        print(f"  ✓ PASS: {label}")
+    else:
+        failed += 1
+        msg = f"✗ FAIL: {label} — {detail}" if detail else f"✗ FAIL: {label}"
+        errors.append(msg)
+        print(f"  {msg}")
+
+
+def main():
+    global passed, failed, errors
+    print("\n" + "=" * 80)
+    print("CITYQUEST AI — END-TO-END PIPELINE TEST")
+    print("=" * 80)
+
+    # ── Imports ──────────────────────────────────────────────────────────
+    print("\n" + "-" * 80)
+    print("MODULE IMPORTS")
+    print("-" * 80)
+
+    try:
+        from app.services.retrieval import load_games_dataset, normalize_game_record, retrieve_examples
+        from app.services.generator import generate_game, generate_game_mock, build_generation_prompt
+        from app.services.validator import validate_game, repair_game
+        from app.services.schema_validator import validate_game_schema, create_minimal_game_template
+        from app.services.tracing import log_event, load_events, log_generation_trace
+        from app.services.journal import create_journal_entry, save_journal_entry, summarize_journal, load_journal_entries, detect_mood, assess_story_value
+        from app.services.scoring import compute_scores
+        from app.services.story import build_story_packet, generate_story, _template_short_recap, _template_long_summary
+        from app.services.minicpm import generate_recap as minicpm_recap, generate_summary as minicpm_summary
+        from app.services.image_gen import generate_poster, generate_poster_sync
+        check("All service modules imported", True)
+    except Exception as e:
+        check("All service modules imported", False, str(e))
+        # Don't continue if core imports fail
+        _summary()
+        sys.exit(1)
+
+    # ── T1: Dataset loading ──────────────────────────────────────────────
+    print("\n" + "-" * 80)
+    print("T1: DATASET LOADING & NORMALIZATION")
+    print("-" * 80)
+
+    try:
+        raw = load_games_dataset("app/data/games_dataset.json")
+        check("Dataset loaded", len(raw) > 0, f"Got {len(raw)} records")
+        check("Dataset has 70 records", len(raw) == 70, f"Got {len(raw)}")
+
+        records = [normalize_game_record(r) for r in raw]
+        check("Records normalized", len(records) == len(raw))
+
+        # Verify structure of first record
+        r0 = records[0]
+        check("Normalized record has id", bool(r0.get("id")))
+        check("Normalized record has game_type", bool(r0.get("game_type")))
+        check("Normalized record has tasks list", isinstance(r0.get("tasks"), list))
+        check("Normalized record has rules list", isinstance(r0.get("rules"), list))
+
+        # Check game type distribution
+        game_types = set(r["game_type"] for r in records)
+        check("All game types present", game_types == {"scavenger_hunt", "hide_and_seek", "tag"},
+              f"Got {game_types}")
+    except Exception as e:
+        check("Dataset loading", False, str(e))
+
+    # ── T2: Retrieval ────────────────────────────────────────────────────
+    print("\n" + "-" * 80)
+    print("T2: RETRIEVAL GROUNDING")
+    print("-" * 80)
+
+    try:
+        config_adults = {
+            "game_type": "scavenger_hunt",
+            "city": "Paris", "area": "Le Marais",
+            "location_type": "mixed", "duration_minutes": 60,
+            "num_players": 4, "difficulty": "medium",
+            "age_group": "adults", "energy_level": "medium",
+        }
+
+        retrieved = retrieve_examples(config_adults, records, k=3)
+        check("Retrieval returns k=3 results", len(retrieved) == 3)
+
+        # Verify structure
+        check("Retrieved has id", all(r.get("id") for r in retrieved))
+        check("Retrieved has retrieval_score", all("retrieval_score" in r for r in retrieved))
+        check("Retrieved has rules_summary", all("rules_summary" in r for r in retrieved))
+        check("Retrieved has task_patterns", all("task_patterns" in r for r in retrieved))
+
+        # Test different config types
+        config_kids = {"game_type": "hide_and_seek", "city": "Paris", "area": "Park",
+                        "location_type": "park", "duration_minutes": 45, "num_players": 5,
+                        "difficulty": "easy", "age_group": "kids", "energy_level": "high"}
+        r_kids = retrieve_examples(config_kids, records, k=5)
+        check("Kids config returns k=5", len(r_kids) == 5)
+
+        config_teens = {"game_type": "tag", "city": "Paris", "area": "Square",
+                         "location_type": "mixed", "duration_minutes": 30, "num_players": 8,
+                         "difficulty": "hard", "age_group": "teens", "energy_level": "high"}
+        r_teens = retrieve_examples(config_teens, records, k=3)
+        check("Teens config returns k=3", len(r_teens) == 3)
+    except Exception as e:
+        check("Retrieval", False, str(e))
+
+    # ── T3: Game Generation (mock) ────────────────────────────────────────
+    print("\n" + "-" * 80)
+    print("T3: GAME GENERATION (MOCK PATH)")
+    print("-" * 80)
+
+    try:
+        game = generate_game_mock(config_adults, retrieved)
+        check("Game generated", game is not None)
+        check("Game has game_id", bool(game.get("game_id")))
+        check("Game has title", bool(game.get("title")))
+        check("Game has theme", bool(game.get("theme")))
+        check("Game has setup with city", game.get("setup", {}).get("city") == "Paris")
+        check("Game has tasks list", len(game.get("tasks", [])) > 0)
+        check("Game has rules list", len(game.get("rules", [])) > 0)
+        check("Game has safety section", bool(game.get("safety")))
+        check("Game has story_seed", bool(game.get("story_seed")))
+
+        # Schema validation
+        is_valid_schema, schema_errors = validate_game_schema(game)
+        check("Game passes JSON schema", is_valid_schema, f"Errors: {schema_errors[:3]}")
+
+        # Build generation prompt
+        prompt = build_generation_prompt(config_adults, retrieved)
+        check("Prompt built", len(prompt) > 100, f"Got {len(prompt)} chars")
+    except Exception as e:
+        check("Game generation", False, str(e))
+
+    # ── T4: Validation ───────────────────────────────────────────────────
+    print("\n" + "-" * 80)
+    print("T4: VALIDATION CHECKS")
+    print("-" * 80)
+
+    try:
+        is_valid, failures = validate_game(game, config_adults)
+        check("Generated game passes validation", is_valid, f"Failures: {failures[:3]}")
+
+        # Test that invalid games are caught
+        bad_game = {
+            "game_id": "", "title": "", "theme": "",
+            "setup": {}, "rules": [], "tasks": [],
+            "global_hints": [], "score_rules": [],
+            "tie_breaker": "", "safety": {}, "story_seed": {},
+        }
+        is_bad_valid, bad_failures = validate_game(bad_game, config_adults)
+        check("Empty game fails validation", not is_bad_valid, f"Got {len(bad_failures)} issues")
+        check("Empty game has issues", len(bad_failures) > 5)
+    except Exception as e:
+        check("Validation", False, str(e))
+
+    # ── T5: Repair ───────────────────────────────────────────────────────
+    print("\n" + "-" * 80)
+    print("T5: REPAIR PASS")
+    print("-" * 80)
+
+    try:
+        bad_game = {
+            "game_id": "", "title": "", "theme": "",
+            "setup": {}, "rules": [], "tasks": [],
+            "global_hints": [], "score_rules": [],
+            "tie_breaker": "", "safety": {}, "story_seed": {},
+        }
+        _, failures = validate_game(bad_game, config_adults)
+        repaired = repair_game(bad_game, failures, config_adults)
+
+        check("Repair returns dict", isinstance(repaired, dict))
+        check("Repaired has game_id", bool(repaired.get("game_id")), f"Got '{repaired.get('game_id')}'")
+        check("Repaired has title", bool(repaired.get("title")))
+        check("Repaired has tasks", len(repaired.get("tasks", [])) > 0)
+        check("Repaired has rules", len(repaired.get("rules", [])) > 0)
+        check("Repaired has safety zone", bool(repaired.get("safety", {}).get("allowed_zone")))
+
+        is_repaired_valid, repaired_failures = validate_game(repaired, config_adults)
+        check("Repaired game passes validation", is_repaired_valid, f"Remaining: {repaired_failures[:3]}")
+    except Exception as e:
+        check("Repair", False, str(e))
+
+    # ── T6: Event Logging ────────────────────────────────────────────────
+    print("\n" + "-" * 80)
+    print("T6: EVENT LOGGING")
+    print("-" * 80)
+
+    try:
+        session_id = f"test-{uuid.uuid4().hex[:8]}"
+
+        ev1 = log_event(session_id, "task_revealed", {"task_id": "t1", "title": "Find the mural"})
+        check("Event logged", ev1 is not None)
+        check("Event has event_id", bool(ev1.get("event_id")))
+        check("Event has timestamp", bool(ev1.get("timestamp")))
+        check("Event has payload", "task_id" in ev1.get("payload", {}))
+
+        log_event(session_id, "task_completed", {"task_id": "t1", "summary": "Done"}, team_id="team-a")
+        log_event(session_id, "task_completed", {"task_id": "t2", "summary": "Done"}, team_id="team-a")
+        log_event(session_id, "hint_used", {"task_id": "t2", "summary": "Used hint"}, team_id="team-a")
+        log_event(session_id, "task_skipped", {"task_id": "t3", "summary": "Skipped"}, team_id="team-a")
+        log_event(session_id, "photo_uploaded", {"photo_id": "p1", "summary": "Selfie"}, team_id="team-a")
+        log_event(session_id, "journal_recorded", {"journal_id": "j1", "mood": "excited"}, team_id="team-a")
+
+        events = load_events(session_id)
+        check("All events loaded", len(events) >= 6, f"Got {len(events)} events")
+
+        event_types = [e["event_type"] for e in events]
+        check("Has task_completed", "task_completed" in event_types)
+        check("Has hint_used", "hint_used" in event_types)
+        check("Has task_skipped", "task_skipped" in event_types)
+        check("Has photo_uploaded", "photo_uploaded" in event_types)
+    except Exception as e:
+        check("Event logging", False, str(e))
+
+    # ── T7: Journal ──────────────────────────────────────────────────────
+    print("\n" + "-" * 80)
+    print("T7: JOURNAL PIPELINE")
+    print("-" * 80)
+
+    try:
+        transcript = "We found the mural near the canal, it was incredible! The whole team cheered. This was definitely the highlight of our game - a close call that turned into our best moment."
+        entry = create_journal_entry(
+            transcript=transcript,
+            session_id=session_id,
+            team_id="team-a",
+            task_id="t1",
+            location_note="Canal area",
+        )
+        check("Journal entry created", entry is not None)
+        check("Journal has journal_id", bool(entry.get("journal_id")))
+        check("Journal has session_id", entry.get("session_id") == session_id)
+
+        # Mood detection
+        mood = detect_mood(transcript)
+        check("Mood detected", bool(mood), f"Got '{mood}'")
+        check("Mood is expected", mood in ("excited", "funny", "confused", "tense", "lucky", "chaotic"),
+              f"Got '{mood}'")
+
+        # Story value
+        story_value = assess_story_value(transcript)
+        check("Story value assessed", bool(story_value), f"Got '{story_value}'")
+
+        # Summarization
+        summary = summarize_journal(transcript, task_id="t1")
+        check("Summary has moment_summary", bool(summary.get("moment_summary")))
+        check("Summary has tags", len(summary.get("tags", [])) > 0)
+        check("Summary has story_value", bool(summary.get("story_value")))
+
+        entry.update(summary)
+        save_journal_entry(entry)
+
+        journals = load_journal_entries(session_id)
+        check("Journal persisted", len(journals) >= 1, f"Got {len(journals)} entries")
+    except Exception as e:
+        check("Journal pipeline", False, str(e))
+
+    # ── T8: Scoring ──────────────────────────────────────────────────────
+    print("\n" + "-" * 80)
+    print("T8: DETERMINISTIC SCORING")
+    print("-" * 80)
+
+    try:
+        events = load_events(session_id)
+        scores = compute_scores(events, game)
+
+        check("Scores returned", scores is not None)
+        check("Has team_scores", len(scores.get("team_scores", [])) > 0)
+        check("Has winner", bool(scores.get("winner")))
+        check("Has scoring_explanation", len(scores.get("scoring_explanation", [])) > 0)
+
+        ts = scores["team_scores"][0]
+        check("Team score has points", ts.get("points", 0) >= 0)
+        check("Team score has completed_tasks", ts.get("completed_tasks", 0) >= 0)
+        check("Team score has hints_used", ts.get("hints_used", 0) >= 0)
+        check("Team score has total_tasks", ts.get("total_tasks", 0) > 0)
+
+        # Verify hint penalty
+        check("Hint penalty applied", ts["hints_used"] > 0)
+
+        # Scoring breakdown is present
+        has_breakdown = any(s.get("scoring_breakdown") for s in scores["team_scores"])
+        check("Has scoring breakdown", has_breakdown)
+    except Exception as e:
+        check("Scoring", False, str(e))
+
+    # ── T9: Story Recap (template) ──────────────────────────────────────
+    print("\n" + "-" * 80)
+    print("T9: STORY RECAP (TEMPLATE FALLBACK)")
+    print("-" * 80)
+
+    try:
+        events = load_events(session_id)
+        packet = build_story_packet(
+            game=game,
+            events=events,
+            scores=scores,
+            journal_entries=load_journal_entries(session_id),
+        )
+        check("Story packet built", packet is not None)
+        check("Packet has game_info", bool(packet.get("game_info")))
+        check("Packet has winner", bool(packet.get("winner")))
+        check("Packet has final_scores", len(packet.get("final_scores", [])) > 0)
+        check("Packet has task_outcomes", len(packet.get("task_outcomes", [])) > 0)
+
+        # Template recap
+        short = _template_short_recap(packet)
+        check("Template short recap generated", len(short) > 50, f"Got {len(short)} chars")
+
+        long = _template_long_summary(packet)
+        check("Template long summary generated", len(long) > 100, f"Got {len(long)} chars")
+
+        # Full generate_story with fallback
+        story = generate_story(packet, session_id=session_id)
+        check("generate_story() returns dict", isinstance(story, dict))
+        check("Has short_recap", bool(story.get("short_recap")))
+        check("Has long_summary", bool(story.get("long_summary")))
+        check("Has poster_prompt", bool(story.get("poster_prompt")))
+        check("Has story_packet", bool(story.get("story_packet")))
+    except Exception as e:
+        check("Story recap", False, str(e))
+
+    # ── T10: MiniCPM module ─────────────────────────────────────────────
+    print("\n" + "-" * 80)
+    print("T10: MINICPM MODULE (lazy-load only — no download in fast test)")
+    print("-" * 80)
+
+    try:
+        from app.services.minicpm import MINICPM_MODEL_ID, MINICPM_GGUF_FILE, generate_recap, generate_summary
+
+        check("MiniCPM constants loaded", bool(MINICPM_MODEL_ID) and bool(MINICPM_GGUF_FILE))
+        check("MiniCPM model ID is correct", "MiniCPM" in MINICPM_MODEL_ID)
+        check("MiniCPM GGUF file ends with .gguf", MINICPM_GGUF_FILE.endswith(".gguf"))
+
+        # In fast test, skip actual model loading
+        if os.environ.get("CITYQUEST_FAST_TEST"):
+            check("MiniCPM module imports (fast test — model skipped)", True)
+        else:
+            # Try recapping — will likely fail without model, that's OK
+            packet = build_story_packet(
+                game=game, events=events, scores=scores,
+                journal_entries=load_journal_entries(session_id),
+            )
+            result = generate_recap(packet)
+            # May be None if no model, but must not raise
+            check("MiniCPM generate_recap() runs without exception", True)
+    except Exception as e:
+        check("MiniCPM module", False, str(e))
+
+    # ── T11: Image Gen module ───────────────────────────────────────────
+    print("\n" + "-" * 80)
+    print("T11: IMAGE GEN MODULE")
+    print("-" * 80)
+
+    try:
+        from app.services.image_gen import generate_poster, generate_poster_sync, BFL_API_KEY_ENV
+
+        check("Image gen constants loaded", bool(BFL_API_KEY_ENV))
+
+        # Test with no API key — must return None gracefully
+        result = generate_poster("A test poster prompt", api_key=None)
+        check("generate_poster() with no key returns None", result is None)
+
+        url, status = generate_poster_sync("test-session", "A test poster prompt")
+        check("generate_poster_sync() returns tuple", isinstance(url, type(None)) and isinstance(status, str))
+        check("Status message is informative", "BFL_API_KEY" in status or "Failed" in status or "unavailable" in status)
+    except Exception as e:
+        check("Image gen module", False, str(e))
+
+    # ── Summary ──────────────────────────────────────────────────────────
+    _summary()
+
+
+def _summary():
+    total = passed + failed
+    print(f"\nRESULTS: {passed}/{total} tests passed", end="")
+    if failed > 0:
+        print(f"{passed}/{total} tests passed - ALL CLEAR")
+    else:
+        print(" — ALL PASSED! 🎉")
+    print("=" * 80)
+
+    if errors:
+        print("\nFailed tests:")
+        for e in errors:
+            print(f"  {e}")
+
+    # Exit with error code if any test failed
+    if failed > 0:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()