Llamacpp addition and Hugging Face Spaces Zero GPU integration

NEMOTRON_GGUF_SETUP.md

@@ -108,20 +108,79 @@ CMAKE_ARGS="-DLLAMA_CUDA=on -DLLAMA_CUDA_DATALAYOUT=row -DCUDAToolkit_INCLUDE_DI
 ### Issue: Out of memory
 **Solution:** Reduce context window or use CPU-offloading in llama.cpp settings.
 
-## Integration with Hugging Face Spaces
+## Performance expectations
+
+| Setup | First Run | Subsequent Runs | Speed |
+|-------|-----------|-----------------|-------|
+| CPU (no optimization) | 5-10 min | 2-5 min per game | Slow |
+| CPU (quantized) | 5-10 min | 30-60s per game | Moderate |
+| GPU (CUDA/Metal) | 5-10 min | 5-15s per game | Fast |
+| HF Zero GPU (auto) | 5-10 min | 5-15s per game | Fast |
+
+## Integration with Hugging Face Spaces (Zero GPU)
+
+The app is fully configured for **Hugging Face Spaces** with **Zero GPU** support.
+
+### What is Zero GPU?
+
+Hugging Face Spaces **Zero GPU** (paid tier) provides on-demand GPU allocation:
+- GPU is allocated only when a `@spaces.GPU`-decorated function runs
+- GPU is **released** after the function completes (saves cost)
+- Without the decorator, code runs on CPU
+
+### How it works in this app
+
+1. `app/main.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`
+
+### Requirements
 
-For deployment in Hugging Face Spaces:
+Add to `requirements.txt`:
+```
+llama-cpp-python
+spaces
+```
+
+> **Note:** The `spaces` package is only available on the Hugging Face Spaces runtime. Local imports use `try/except ImportError` to handle this gracefully.
+
+### File structure for HF Spaces
+
+```
+app/
+  main.py           ← HF Spaces entry point (launches Gradio)
+  services/
+    generator.py    ← Auto-detects GPU via torch.cuda
+    ...
+requirements.txt
+```
+
+On Hugging Face Spaces, the app runs `app/main.py` automatically.
+
+### GPU auto-detection logic
+
+In `app/services/generator.py`:
+
+```python
+def _get_n_gpu_layers() -> int:
+    try:
+        import torch
+        if torch.cuda.is_available():
+            return -1  # All layers on GPU
+    except ImportError:
+        pass
+    return 0  # CPU only
+```
 
-1. **Requirements file includes:**
-   ```
-   llama-cpp-python
-   ```
+This works because `@spaces.GPU` makes `torch.cuda.is_available()` return `True` inside the decorated function.
 
-2. **Spaces environment** — HF Spaces has limited GPU memory
-   - Consider n_gpu_layers parameter in `generator.py`
-   - CPU fallback is always available
+### Deployment steps
 
-3. **Caching strategy** — Model is cached after first download
+1. Push the repo to Hugging Face Spaces
+2. Set **Space SDK** to **Gradio**
+3. Set **Space hardware** to **Zero GPU** (paid) for GPU acceleration, or leave as CPU (free)
+4. The app auto-detects and uses GPU/CPU accordingly
 
 ## Hackathon Integration
 

app/main.py

@@ -1,14 +1,569 @@
+"""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
-import spaces
-import torch
 
-zero = torch.Tensor([0]).cuda()
-print(zero.device) # <-- 'cpu' 🤔
+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.
+    
+    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)
+if spaces is not None:
+    _generate_with_gpu = spaces.GPU(_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])
 
-@spaces.GPU
-def greet(n):
-    print(zero.device) # <-- 'cuda:0' 🤗
-    return f"Hello {zero + n} Tensor"
 
-demo = gr.Interface(fn=greet, inputs=gr.Number(), outputs=gr.Text())
-demo.launch()
+# ── Launch ────────────────────────────────────────────────────────────────────
+if __name__ == "__main__":
+    demo.launch()

app/prompts/game_generation.txt

@@ -1,33 +1,28 @@
-You are an expert urban real-world game designer. Your task is to create an engaging, safe, and playable location-based game.
+Generate a location-based game in strict JSON format.
 
 ## Context
 - City: {city}
 - Area: {area}
 - Game Type: {game_type}
 - Duration: {duration_minutes} minutes
-- Number of Players: {num_players}
+- Players: {num_players}
 - Difficulty: {difficulty}
 - Age Group: {age_group}
 
 ## Retrieved Examples
 {retrieved_examples}
 
-## Hard Safety Constraints
-1. NO entering buildings, shops, private courtyards, rooftops, or fenced areas
-2. NO proximity to river edges, canal edges, traffic, rail lines without explicit restrictions
-3. NO direct interaction with strangers or staff
-4. NO requiring purchases
-5. All locations must be public, accessible, and safe
-6. Include supervision requirements for mixed-age groups
+## Safety
+- NO entering buildings or private property
+- NO proximity to water, traffic, or rail lines
+- NO interacting with strangers
+- NO purchases required
+- All locations must be public and accessible
 
-## Output Requirements
-- Return ONLY valid JSON that matches the provided schema
-- Each task must have clear location hints, proof type, and safety notes
-- Include global hints to help teams navigate
-- Define clear win conditions
-- Avoid invented private or inaccessible locations
+## Required JSON Structure
+{output_schema}
+
+Return ONLY the JSON object. Start with {{ and end with }}. No other text.
 
 ## Output Schema
 {output_schema}
-
-Generate the game JSON:

app/services/generator.py

@@ -11,7 +11,27 @@ _model_cache = {}
 
 # Model configuration
 NEMOTRON_MODEL_ID = "nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF"
-NEMOTRON_GGUF_FILE = "model.gguf"  # The GGUF file name in the HF repo
+NEMOTRON_GGUF_FILE = "*Q4_K_M.gguf"  # The GGUF file name in the HF repo
+
+
+def _get_n_gpu_layers() -> int:
+    """Auto-detect GPU availability for llama.cpp.
+    
+    On Hugging Face Zero GPU, torch.cuda.is_available() returns True
+    inside @spaces.GPU decorated functions.
+    
+    Returns:
+        -1 if GPU available (all layers on GPU), 0 for CPU only
+    """
+    try:
+        import torch
+        if torch.cuda.is_available():
+            print(f"[GPU] CUDA detected ({torch.cuda.get_device_name(0)}) — GPU acceleration ON")
+            return -1
+    except ImportError:
+        pass
+    print("[CPU] No CUDA detected — using CPU only")
+    return 0
 
 
 def build_generation_prompt(config: dict, retrieved_examples: list[dict]) -> str:
@@ -96,34 +116,41 @@ def generate_game_with_model(prompt: str, model_name: str = "nemotron") -> Optio
             print(f"Initializing llama.cpp with: {model_id}/{NEMOTRON_GGUF_FILE}")
             
             # Initialize llama.cpp with the GGUF model
-            # The model will be downloaded from HuggingFace automatically via llama-cpp-python
+            # Auto-detect GPU — works with HF Zero GPU (@spaces.GPU)
             _model_cache[cache_key] = Llama.from_pretrained(
                 repo_id=model_id,
                 filename=NEMOTRON_GGUF_FILE,
                 verbose=False,
-                n_gpu_layers=-1,  # Use GPU if available
-                n_ctx=2048,  # Context window
+                n_gpu_layers=_get_n_gpu_layers(),  # Auto: -1 GPU, 0 CPU
+                n_ctx=8192,  # Larger context window (model supports 1M)
             )
         
         llm = _model_cache[cache_key]
         
-        # Build strict JSON prompt
-        system_prompt = "You are an expert game designer. Return ONLY valid JSON, no other text."
-        full_prompt = f"{system_prompt}\n\n{prompt}"
+        # Use create_chat_completion — this model uses a Nemotron chat template
+        messages = [
+            {"role": "system", "content": "You output only valid JSON. No other text."},
+            {"role": "user", "content": prompt},
+        ]
         
-        # Generate with llama.cpp
-        result = llm(
-            full_prompt,
-            max_tokens=2000,
-            temperature=0.7,
-            top_p=0.95,
-            stop=["```", "\n\n"]
+        result = llm.create_chat_completion(
+            messages=messages,
+            max_tokens=8192,
+            temperature=0.3,  # Low temperature for structured output
+            top_p=0.9,
+            stop=["```"],
         )
         
-        generated_text = result['choices'][0]['text']
+        generated_text = result["choices"][0]["message"]["content"]
+        # Strip leading/trailing whitespace
+        generated_text = generated_text.strip()
+        print(f"[nemotron] Generated {len(generated_text)} chars")
         
         # Extract JSON from generated text
         json_str = extract_json(generated_text)
+        if not json_str:
+            print(f"[nemotron] JSON extraction failed on output (len={len(generated_text)})")
+            print(f"[nemotron] Preview: {generated_text[:300]}...")
         return json_str
         
     except ImportError:
@@ -137,18 +164,20 @@ def generate_game_with_model(prompt: str, model_name: str = "nemotron") -> Optio
 def extract_json(text: str) -> Optional[str]:
     """Extract JSON object from generated text.
     
+    Handles various prefixes (e.g. double braces {{ from prompt echoing).
+    
     Args:
         text: Generated text that may contain JSON
         
     Returns:
         JSON string or None if not found
     """
-    # Find JSON block
+    # Find JSON block - look for the first {
     start_idx = text.find('{')
     if start_idx == -1:
         return None
     
-    # Find matching closing brace
+    # Find matching closing brace using depth counting
     depth = 0
     for i in range(start_idx, len(text)):
         if text[i] == '{':
@@ -156,8 +185,14 @@ def extract_json(text: str) -> Optional[str]:
         elif text[i] == '}':
             depth -= 1
             if depth == 0:
-                return text[start_idx:i+1]
+                raw = text[start_idx:i+1]
+                # Normalize double braces from prompt echoing ({{ -> {)
+                # Only fix the outermost brace pair if needed
+                if raw.startswith('{{') and raw.endswith('}}'):
+                    raw = raw[1:-1]
+                return raw
     
+    # Truncated JSON — return what we have
     return None
 
 

requirements.txt

@@ -2,3 +2,4 @@ gradio
 torch
 llama-cpp-python
 jsonschema
+spaces