Phase 3: add live session intelligence

.gitignore

@@ -48,6 +48,10 @@ env/
 Thumbs.db
 .DS_Store
 .AppleDouble
+
+# Runtime logs (generated per session — never commit)
+app/logs/*.jsonl
+app/logs/trace_*.json
 .LSOverride
 
 # Logs and temporary files

app.py

@@ -1,4 +1,5 @@
 import gradio as gr
+import uuid
 
 try:
     import spaces  # only available on Hugging Face Spaces
@@ -9,6 +10,13 @@ from app.services.retrieval import load_games_dataset, normalize_game_record, re
 from app.services.generator import generate_game
 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 ──────────────────────────────────────────────
@@ -22,6 +30,10 @@ except FileNotFoundError:
     print(f"⚠ Dataset not found at {DATASET_PATH}, retrieval will be empty")
 
 
+# ── In-memory session store (resets on restart — fine for hackathon) ───────
+SESSION_STORE: dict[str, dict] = {}  # session_id -> {config: {...}, game: {...}, events: [...], journals: [...]}
+
+
 # ── Pipeline entry point ──────────────────────────────────────────────────────
 def run_pipeline(
     game_type: str,
@@ -36,20 +48,22 @@ def run_pipeline(
 ):
     """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": duration_minutes,
-        "num_players": num_players,
+        "duration_minutes": int(duration_minutes),
+        "num_players": int(num_players),
         "difficulty": difficulty,
         "age_group": age_group,
         "energy_level": energy_level,
         "photo_enabled": True,
     }
 
-    state = {}  # collect logs for the UI trace
+    state = {}
 
     # 1 ── Retrieval
     state["num_retrieved"] = 0
@@ -75,7 +89,6 @@ def run_pipeline(
     if not is_valid:
         repaired = repair_game(game, failures, config)
         state["repair_applied"] = True
-        # re-validate repaired version
         is_valid2, failures2 = validate_game(repaired, config)
         state["repair_valid"] = is_valid2
         state["remaining_failures"] = failures2
@@ -84,16 +97,270 @@ def run_pipeline(
 
     final_game = repaired if repaired is not None else game
 
-    # 5 ── Build summary text
-    summary = build_summary(final_game, state)
-    return summary, final_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"):
+    """Log a task completion event and return updated scoreboard."""
+    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"):
+    """Log a task skip event."""
+    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"):
+    """Log a hint usage event."""
+    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",
+):
+    """Record a text journal entry, summarize it, and return the result."""
+    if session_id not in SESSION_STORE:
+        return "⚠ Unknown session", ""
+
+    # Build full journal entry
+    entry = create_journal_entry(
+        transcript=transcript,
+        session_id=session_id,
+        team_id=team_id,
+        task_id=task_id or None,
+        location_note=location_note,
+    )
+
+    # Summarize
+    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"]
+
+    # Persist
+    save_journal_entry(entry)
+
+    # Log event
+    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)
+
+    # Build display text
+    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",
+):
+    """Log a photo upload event and return a confirmation."""
+    if session_id not in SESSION_STORE:
+        return "⚠ Unknown session", []
+
+    photo_name = ""
+    if photo_file is not None:
+        # Gradio 4+ returns a filepath string or a PIL image
+        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)
+
+    # Track photo in session store for recap
+    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,
+    })
+
+    # Build gallery list
+    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"):
+    """End the game, compute scores, and return a scoreboard."""
+    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):
+    """Generate the final story recap from all collected session data."""
+    if session_id not in SESSION_STORE:
+        return "⚠ Unknown session"
 
-def build_summary(game: dict, state: dict) -> str:
+    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", [])
+
+    # Build story packet
+    packet = build_story_packet(
+        game=game,
+        events=events,
+        scores=scores,
+        journal_entries=journals,
+        photo_captions=photos,
+    )
+
+    # Generate story
+    result = generate_story(packet, session_id=session_id)
+
+    # Format for display
+    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:
     """Format a human-readable game summary for the UI."""
     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', '?')}")
@@ -170,83 +437,198 @@ with gr.Blocks(title="CityQuest-AI – Game Generator") as demo:
     gr.Markdown(
         """
         # 🌍 CityQuest-AI — AI Game Generator
-        Configure your location-based game below and let AI create it.
+        Configure your game, play it, record journals, and get a story recap.
         """
     )
 
-    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)
-
+    # ── 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
+            Paste your **Session ID** from the Generate tab, then log task
+            completions, hints, and journal entries as you play.
+            """
+        )
+        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 (what happened, how you feel)",
+                    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 (drag & drop or click)", 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
+            After ending the game, paste your **Session ID** to generate a
+            narrative recap from your real session data.
+            """
+        )
+        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 tab
     generate_btn.click(
         fn=run_pipeline,
         inputs=[
-            game_type,
-            city,
-            area,
-            location_type,
-            duration_minutes,
-            num_players,
-            difficulty,
-            age_group,
-            energy_level,
+            game_type, city, area, location_type,
+            duration_minutes, num_players, difficulty, age_group, energy_level,
         ],
-        outputs=[output_md, output_json],
+        outputs=[output_md, output_json, session_id_box],
+    )
+
+    # Play tab — task actions
+    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],
+    )
+
+    # Play tab — journal
+    journal_btn.click(
+        fn=record_journal,
+        inputs=[play_session_id, journal_transcript, journal_task_id, journal_location, play_team_id],
+        outputs=[journal_output],
+    )
+
+    # Play tab — photo upload
+    photo_btn.click(
+        fn=upload_photo,
+        inputs=[play_session_id, photo_file, photo_caption, photo_task_id, play_team_id],
+        outputs=[photo_output],
+    )
+
+    # Play tab — end game
+    end_btn.click(
+        fn=end_game,
+        inputs=[play_session_id, play_team_id],
+        outputs=[scoreboard_md],
+    )
+
+    # Recap tab
+    recap_btn.click(
+        fn=generate_recap,
+        inputs=[recap_session_id],
+        outputs=[recap_md, recap_json],
     )
 
     gr.Markdown(
         """
         ---
-        Built with ❤️ for the **NVIDIA / HF Hackathon** · CityQuest-AI · [Nemotron 3 Nano 4B](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF) · [llama.cpp](https://github.com/ggerganov/llama.cpp)
+        Built with ❤️ for the **NVIDIA / HF Hackathon** · CityQuest-AI ·
+        [Nemotron 3 Nano 4B](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF) ·
+        [llama.cpp](https://github.com/ggerganov/llama.cpp)
         """
     )
 

app/services/journal.py

@@ -1,34 +1,310 @@
-"""Voice journal capture and summarization module."""
+"""Voice journal capture and summarization module.
 
-from typing import Any
+Provides two paths for journal creation:
+  1. Voice path: record audio → transcribe → summarize (requires STT backend)
+  2. Text path: type a journal entry directly → summarize
 
+Summarization uses a heuristic + optional LLM approach so the pipeline
+works even when no LLM is available.
+"""
+
+import json
+import uuid
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+
+# ── Mood keywords for heuristic mood detection ──────────────────────────────
+MOOD_KEYWORDS: dict[str, list[str]] = {
+    "funny": [
+        "hilarious", "laughed", "laughing", "funny", "silly", "ridiculous",
+        "comedic", "joke", "cracked up", "wheezing", "snort",
+    ],
+    "confused": [
+        "confused", "lost", "don't understand", "no idea", "where is",
+        "which way", "puzzled", "baffled", "not sure", "wait what",
+    ],
+    "excited": [
+        "excited", "amazing", "awesome", "incredible", "wow", "yes!",
+        "let's go", "so cool", "unbelievable", "found it", "nailed it",
+    ],
+    "tense": [
+        "nervous", "worried", "oh no", "scary", "rushed", "panicked",
+        "close call", "barely made it", "running out of time", "hurry",
+    ],
+    "lucky": [
+        "lucky", "by chance", "just happened", "stumbled", "coincidence",
+        "right place", "phew", "got lucky", "luckily", "close one",
+    ],
+    "chaotic": [
+        "chaos", "everything at once", "all over the place", "wild",
+        "crazy", "mayhem", "pandemonium", "disaster", "total mess", "frantic",
+    ],
+}
+
+# Story-value indicators
+HIGH_VALUE_SIGNALS = [
+    "turning point", "decided to", "changed our mind", "found it",
+    "last second", "just in time", "unexpected", "surprise", "nobody expected",
+    "close call", "first time", "only team", "beat them", "won",
+    "everyone cheered", "high five", "best moment", "highlight",
+]
+
+LOCATION_KEYWORDS = [
+    "square", "street", "corner", "park", "garden", "bridge", "cafe",
+    "church", "museum", "statue", "fountain", "canal", "river", "market",
+    "tower", "palace", "mural", "gallery", "arch", "gate", "alley",
+    "plaza", "staircase", "passage", "courtyard",
+]
+
+
+# ── Transcription ───────────────────────────────────────────────────────────
 
 def transcribe_journal(audio_path: str) -> str:
     """Transcribe voice journal audio to text.
-    
+
+    Tries (in order):
+      1. ``whisper`` Python package (OpenAI Whisper, runs locally).
+      2. Returns an empty string with a warning so downstream code
+         still works and the user can fall back to typed input.
+
     Args:
-        audio_path: Path to recorded audio file
-        
+        audio_path: Path to a recorded audio file (wav/mp3/m4a/ogg/webm).
+
     Returns:
-        Transcribed text
+        Transcribed text, or ``""`` if transcription is unavailable.
     """
-    # TODO: Implement with speech-to-text service
+    path = Path(audio_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Audio file not found: {audio_path}")
+
+    # Try local Whisper
+    try:
+        import whisper  # type: ignore
+
+        model = whisper.load_model("base")
+        result = model.transcribe(str(path))
+        return result.get("text", "").strip()
+    except ImportError:
+        print(
+            "[journal] whisper not installed — install with: "
+            "pip install openai-whisper. Falling back to empty transcript."
+        )
+    except Exception as exc:
+        print(f"[journal] Whisper transcription failed: {exc}")
+
     return ""
 
 
-def summarize_journal(transcript: str, task_id: str | None = None) -> dict:
-    """Summarize journal entry using OpenBMB model.
-    
+# ── Mood detection ──────────────────────────────────────────────────────────
+
+def detect_mood(transcript: str) -> str:
+    """Detect the dominant mood from transcript text using keyword matching.
+
+    Returns one of: ``funny``, ``confused``, ``excited``, ``tense``,
+    ``lucky``, ``chaotic``.  Defaults to ``excited`` if no clear signal.
+    """
+    lower = transcript.lower()
+    scores: dict[str, int] = {}
+
+    for mood, keywords in MOOD_KEYWORDS.items():
+        count = sum(1 for kw in keywords if kw in lower)
+        if count > 0:
+            scores[mood] = count
+
+    if not scores:
+        return "excited"  # safe default
+
+    return max(scores, key=scores.get)
+
+
+# ── Tag extraction ──────────────────────────────────────────────────────────
+
+def extract_tags(transcript: str, task_id: Optional[str] = None) -> list[str]:
+    """Extract meaningful tags from the transcript.
+
+    Tags include:
+      - The associated ``task_id`` if provided.
+      - Detected mood.
+      - Any mentioned locations / landmarks.
+      - Any detected story-value signal words.
+    """
+    lower = transcript.lower()
+    tags: list[str] = []
+
+    if task_id:
+        tags.append(task_id)
+
+    tags.append(detect_mood(transcript))
+
+    for loc in LOCATION_KEYWORDS:
+        if loc in lower:
+            tags.append(loc)
+
+    return tags
+
+
+# ── Story-value scoring ─────────────────────────────────────────────────────
+
+def assess_story_value(transcript: str) -> str:
+    """Rate the story value of a journal entry as ``low``, ``medium``, or ``high``.
+
+    Heuristic: count the number of high-value signals present in the text.
+    """
+    lower = transcript.lower()
+    hits = sum(1 for sig in HIGH_VALUE_SIGNALS if sig in lower)
+
+    word_count = len(transcript.split())
+
+    # Very short entries are low value regardless
+    if word_count < 8:
+        return "low"
+    if hits >= 3:
+        return "high"
+    if hits >= 1 or word_count >= 30:
+        return "medium"
+    return "low"
+
+
+# ── Summarization ───────────────────────────────────────────────────────────
+
+def summarize_journal(
+    transcript: str,
+    task_id: Optional[str] = None,
+    location_note: str = "",
+) -> dict:
+    """Summarize a journal entry with tags and story value.
+
+    Uses a keyword-based heuristic that works offline.  When an LLM is
+    available it can optionally produce a richer summary.
+
     Args:
-        transcript: Journal transcript text
-        task_id: Optional associated task ID
-        
+        transcript: Journal transcript text (typed or transcribed).
+        task_id: Optional associated task ID.
+        location_note: Where the entry was recorded.
+
     Returns:
-        Journal summary with tags and story value
+        Dictionary with keys ``moment_summary``, ``tags``, ``story_value``.
     """
-    # TODO: Implement with MiniCPM or similar model
+    if not transcript or not transcript.strip():
+        return {
+            "moment_summary": "No content recorded.",
+            "tags": [],
+            "story_value": "low",
+        }
+
+    mood = detect_mood(transcript)
+    tags = extract_tags(transcript, task_id)
+    story_value = assess_story_value(transcript)
+
+    # Build a short summary (first sentence or first 40 words)
+    sentences = re.split(r'[.!?]+', transcript)
+    first_sentence = sentences[0].strip() if sentences else transcript[:200]
+
+    if len(first_sentence.split()) > 40:
+        first_sentence = " ".join(first_sentence.split()[:40]) + "…"
+
+    moment_summary = f"[{mood}] {first_sentence}"
+
     return {
-        "moment_summary": "",
-        "tags": [],
-        "story_value": "low"
+        "moment_summary": moment_summary,
+        "tags": tags,
+        "story_value": story_value,
     }
+
+
+# ── Full journal entry builder ──────────────────────────────────────────────
+
+def create_journal_entry(
+    transcript: str,
+    session_id: str,
+    team_id: str = "team-a",
+    task_id: Optional[str] = None,
+    location_note: str = "",
+    photo_refs: Optional[list[str]] = None,
+) -> dict:
+    """Build a complete journal entry dict matching the journal schema.
+
+    Args:
+        transcript: Journal transcript text.
+        session_id: Game session identifier.
+        team_id: Team identifier.
+        task_id: Optional associated task ID.
+        location_note: Where the entry was recorded.
+        photo_refs: List of photo identifiers to attach.
+
+    Returns:
+        Full journal entry dict.
+    """
+    mood = detect_mood(transcript)
+
+    entry = {
+        "journal_id": str(uuid.uuid4()),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "session_id": session_id,
+        "team_id": team_id,
+        "transcript": transcript,
+        "mood": mood,
+        "location_note": location_note or "Unknown location",
+        "photo_refs": photo_refs or [],
+    }
+
+    if task_id:
+        entry["task_id"] = task_id
+
+    return entry
+
+
+def save_journal_entry(entry: dict, log_dir: str = "app/logs") -> dict:
+    """Persist a journal entry to a JSONL file.
+
+    Args:
+        entry: Journal entry dict (as returned by ``create_journal_entry``).
+        log_dir: Directory to store logs.
+
+    Returns:
+        The same entry dict for chaining.
+    """
+    log_path = Path(log_dir)
+    log_path.mkdir(parents=True, exist_ok=True)
+    journal_file = log_path / "journals.jsonl"
+
+    with open(journal_file, "a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+    return entry
+
+
+def load_journal_entries(
+    session_id: Optional[str] = None, log_dir: str = "app/logs"
+) -> list[dict]:
+    """Load journal entries from the JSONL log, optionally by session.
+
+    Args:
+        session_id: If provided, only return entries for this session.
+        log_dir: Directory containing journal logs.
+
+    Returns:
+        List of journal entry dicts.
+    """
+    journal_file = Path(log_dir) / "journals.jsonl"
+    if not journal_file.exists():
+        return []
+
+    entries: list[dict] = []
+    with open(journal_file, "r", encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if session_id and entry.get("session_id") != session_id:
+                continue
+            entries.append(entry)
+
+    return entries

app/services/scoring.py

@@ -1,21 +1,217 @@
-"""Deterministic scoring module."""
+"""Deterministic scoring module.
 
-from typing import Any
+Computes team scores entirely in Python — never delegated to an LLM.
+Score breakdown is transparent and stored in ``scoring_explanation`` so
+it can be displayed in the UI and included in story packets.
+"""
 
+from datetime import datetime, timezone
+from typing import Optional
+
+
+# ── Constants ───────────────────────────────────────────────────────────────
+HINT_PENALTY = 5          # Points deducted per hint used
+FAST_FINISH_BONUS = 20    # Bonus for completing all tasks before time expires
+COMPLETION_RATIO_BONUS = 10  # Bonus for completing >75 % of tasks
+MAX_TIME_BONUS = 15       # Max bonus points for finishing early
+
+
+# ── Internal helpers ────────────────────────────────────────────────────────
+
+def _build_task_map(game: dict) -> dict[str, dict]:
+    """Index tasks by ``task_id`` for O(1) lookups."""
+    return {t["task_id"]: t for t in game.get("tasks", [])}
+
+
+def _parse_ts(ts_str: str) -> Optional[datetime]:
+    """Parse an ISO-8601 timestamp string, returning None on failure."""
+    try:
+        # Handle both Z suffix and +00:00
+        ts = ts_str.replace("Z", "+00:00")
+        return datetime.fromisoformat(ts)
+    except (ValueError, TypeError):
+        return None
+
+
+def _seconds_between(start: str, end: str) -> Optional[float]:
+    """Return seconds between two ISO-8601 timestamps, or None."""
+    dt_start = _parse_ts(start)
+    dt_end = _parse_ts(end)
+    if dt_start and dt_end:
+        return max(0, (dt_end - dt_start).total_seconds())
+    return None
+
+
+# ── Public API ──────────────────────────────────────────────────────────────
 
 def compute_scores(events: list[dict], game: dict) -> dict:
     """Compute final scores from gameplay events.
-    
+
+    Scoring logic:
+      • Each ``task_completed`` awards the task's base ``points``.
+      • Each ``hint_used`` deducts ``HINT_PENALTY`` points.
+      • ``task_skipped`` awards 0 points for that task.
+      • ``fast_finish`` bonus: +``FAST_FINISH_BONUS`` if all tasks are
+        completed before the game's duration elapses.
+      • ``completion_ratio`` bonus: +``COMPLETION_RATIO_BONUS`` if the
+        team completed more than 75 % of tasks.
+      • ``time_bonus``: up to ``MAX_TIME_TIME_BONUS`` points for finishing
+        early, scaled linearly by how much time remains.
+
     Args:
-        events: List of gameplay events
-        game: The original game definition
-        
+        events: List of gameplay event dicts.
+        game: The original game definition (with tasks, setup, etc.).
+
     Returns:
-        Scoring output with team scores and winner
+        Scoring output dict matching the ``event_schema`` score contract:
+        ``{"team_scores": [...], "winner": str, "scoring_explanation": [...]}``
     """
-    # TODO: Implement deterministic scoring
+    task_map = _build_task_map(game)
+    duration_seconds = game.get("setup", {}).get("duration_minutes", 45) * 60
+
+    # ── Collect per-team data ───────────────────────────────────────────
+    team_data: dict[str, dict] = {}
+
+    for ev in events:
+        team_id = ev.get("team_id", "team-a")
+        if team_id not in team_data:
+            team_data[team_id] = {
+                "completed_tasks": [],
+                "skipped_tasks": [],
+                "hints_used": 0,
+                "photos_uploaded": 0,
+                "journals": [],
+                "first_event_ts": ev.get("timestamp"),
+                "last_event_ts": ev.get("timestamp"),
+            }
+
+        td = team_data[team_id]
+        ev_type = ev.get("event_type")
+        payload = ev.get("payload", {})
+        ts = ev.get("timestamp", "")
+
+        # Track time window
+        if ts < td["first_event_ts"]:
+            td["first_event_ts"] = ts
+        if ts > td["last_event_ts"]:
+            td["last_event_ts"] = ts
+
+        if ev_type == "task_completed":
+            task_id = payload.get("task_id")
+            if task_id and task_id not in td["completed_tasks"]:
+                td["completed_tasks"].append(task_id)
+
+        elif ev_type == "task_skipped":
+            task_id = payload.get("task_id")
+            if task_id and task_id not in td["skipped_tasks"]:
+                td["skipped_tasks"].append(task_id)
+
+        elif ev_type == "hint_used":
+            td["hints_used"] += 1
+
+        elif ev_type == "photo_uploaded":
+            td["photos_uploaded"] += 1
+
+        elif ev_type == "journal_recorded":
+            td["journals"].append(payload)
+
+    # ── Score each team ─────────────────────────────────────────────────
+    all_tasks = game.get("tasks", [])
+    total_possible_tasks = len(all_tasks)
+    team_scores: list[dict] = []
+    explanations: list[str] = []
+
+    for team_id, td in team_data.items():
+        base_points = 0
+        for task_id in td["completed_tasks"]:
+            task = task_map.get(task_id, {})
+            pts = task.get("points", 0)
+            base_points += pts
+
+        # Hint penalty
+        hint_penalty = td["hints_used"] * HINT_PENALTY
+
+        # Completion ratio
+        completed_count = len(td["completed_tasks"])
+        completion_ratio = completed_count / total_possible_tasks if total_possible_tasks else 0
+
+        # Time bonus
+        elapsed = _seconds_between(td["first_event_ts"], td["last_event_ts"])
+        time_bonus = 0
+        if elapsed is not None and elapsed < duration_seconds:
+            remaining_ratio = 1 - (elapsed / duration_seconds)
+            time_bonus = min(MAX_TIME_BONUS, round(remaining_ratio * MAX_TIME_BONUS))
+
+        # Fast-finish bonus
+        fast_finish = FAST_FINISH_BONUS if completed_count >= total_possible_tasks and elapsed is not None and elapsed < duration_seconds else 0
+
+        # Completion-ratio bonus
+        completion_bonus = COMPLETION_RATIO_BONUS if completion_ratio > 0.75 else 0
+
+        total_points = max(0, base_points - hint_penalty + time_bonus + fast_finish + completion_bonus)
+
+        # Build per-team explanation
+        team_explanation = [
+            f"Base points from {completed_count} completed tasks: +{base_points}",
+            f"Hints used: {td['hints_used']} × {HINT_PENALTY} penalty = -{hint_penalty}",
+        ]
+        if time_bonus > 0:
+            team_explanation.append(f"Time bonus for finishing early: +{time_bonus}")
+        if fast_finish > 0:
+            team_explanation.append(f"Fast-finish bonus (all tasks): +{fast_finish}")
+        if completion_bonus > 0:
+            team_explanation.append(f"Completion ratio bonus (>75%): +{completion_bonus}")
+        team_explanation.append(f"Final total: {total_points}")
+
+        bonuses = []
+        if fast_finish > 0:
+            bonuses.append("fast_finish")
+        if completion_bonus > 0:
+            bonuses.append("completion_ratio")
+
+        team_scores.append({
+            "team_id": team_id,
+            "points": total_points,
+            "base_points": base_points,
+            "hint_penalty": hint_penalty,
+            "time_bonus": time_bonus,
+            "fast_finish_bonus": fast_finish,
+            "completion_bonus": completion_bonus,
+            "completed_tasks": completed_count,
+            "total_tasks": total_possible_tasks,
+            "hints_used": td["hints_used"],
+            "bonuses": bonuses,
+            "scoring_breakdown": team_explanation,
+        })
+
+        explanations.append(f"Team {team_id}: {total_points} pts ({completed_count}/{total_possible_tasks} tasks)")
+
+    # ── Determine winner ────────────────────────────────────────────────
+    winner: Optional[str] = None
+    if team_scores:
+        # Sort descending by points; tie-break by fewer hints
+        ranked = sorted(
+            team_scores,
+            key=lambda t: (t["points"], -t["hints_used"]),
+            reverse=True,
+        )
+        winner = ranked[0]["team_id"]
+
+        if len(ranked) > 1 and ranked[0]["points"] == ranked[1]["points"]:
+            explanations.append(
+                f"⚠ Tie between teams with {ranked[0]['points']} pts — "
+                "tie-breaker: fewer hints used wins."
+            )
+            # Re-rank with tie-breaker
+            ranked_tied = sorted(
+                ranked,
+                key=lambda t: t["hints_used"],
+            )
+            winner = ranked_tied[0]["team_id"]
+            explanations.append(f"Tie-break winner: {winner} (fewer hints)")
+
     return {
-        "team_scores": [],
-        "winner": None,
-        "scoring_explanation": []
+        "team_scores": team_scores,
+        "winner": winner,
+        "scoring_explanation": explanations,
     }

app/services/story.py

@@ -1,22 +1,350 @@
-"""Final story and recap generation module."""
+"""Final story and recap generation module.
 
-from typing import Any
+Builds a compact *story packet* from verified runtime data (game config,
+events, scores, journals) and produces three artefacts:
 
+  1. ``short_recap`` – a punchy paragraph for the result screen.
+  2. ``long_summary`` – a 400-600 word episode recap.
+  3. ``poster_prompt`` – a visual prompt for image generation.
 
-def generate_story(story_packet: dict) -> dict:
+When no LLM is available, a high-quality template-based recap is generated
+so the pipeline always returns a visible result.
+"""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from app.services.tracing import log_event
+
+
+# ── Story packet builder ───────────────────────────────────────────────────
+
+def build_story_packet(
+    game: dict,
+    events: list[dict],
+    scores: dict,
+    journal_entries: Optional[list[dict]] = None,
+    photo_captions: Optional[list[dict]] = None,
+) -> dict:
+    """Assemble a compact, verified story packet from runtime data.
+
+    The packet contains **only facts** — no fabricated locations or quotes.
+    This is the sole input to the recap generation step.
+
+    Args:
+        game: The generated game definition dict.
+        events: Full gameplay event stream.
+        scores: Output of ``scoring.compute_scores()``.
+        journal_entries: Optional list of journal dicts (from ``journal.py``).
+        photo_captions: Optional list of ``{"photo_id": ..., "caption": ...}``.
+
+    Returns:
+        Story packet dict matching ``story_packet_schema.json``.
+    """
+    # Task outcomes — one entry per task with completion status
+    task_map = {t["task_id"]: t for t in game.get("tasks", [])}
+    completed_ids: set[str] = set()
+    skipped_ids: set[str] = set()
+
+    for ev in events:
+        ev_type = ev.get("event_type")
+        payload = ev.get("payload", {})
+        tid = payload.get("task_id")
+        if ev_type == "task_completed" and tid:
+            completed_ids.add(tid)
+        elif ev_type == "task_skipped" and tid:
+            skipped_ids.add(tid)
+
+    task_outcomes = []
+    for tid, task in task_map.items():
+        if tid in completed_ids:
+            status = "completed"
+        elif tid in skipped_ids:
+            status = "skipped"
+        else:
+            status = "incomplete"
+        task_outcomes.append({
+            "task_id": tid,
+            "title": task.get("title", ""),
+            "completed": tid in completed_ids,
+            "skipped": tid in skipped_ids,
+            "points": task.get("points", 0),
+            "status": status,
+        })
+
+    # Notable events — high-signal moments
+    notable_events = []
+    for ev in events:
+        ev_type = ev.get("event_type")
+        payload = ev.get("payload", {})
+        if ev_type in ("task_completed", "game_finished"):
+            notable_events.append({
+                "event_type": ev_type,
+                "team_id": ev.get("team_id"),
+                "timestamp": ev.get("timestamp"),
+                "summary": payload.get("summary", f"{ev_type}"),
+            })
+
+    # Journal moments — select high-value ones
+    journal_moments = []
+    if journal_entries:
+        value_rank = {"high": 3, "medium": 2, "low": 1}
+        sorted_journals = sorted(
+            journal_entries,
+            key=lambda j: value_rank.get(j.get("story_value", "low"), 0),
+            reverse=True,
+        )
+        for j in sorted_journals[:4]:
+            journal_moments.append({
+                "journal_id": j.get("journal_id"),
+                "moment_summary": j.get("moment_summary", j.get("transcript", "")[:120]),
+                "mood": j.get("mood"),
+                "tags": j.get("tags", []),
+                "story_value": j.get("story_value", "low"),
+            })
+
+    winner = scores.get("winner")
+
+    packet = {
+        "game_info": {
+            "game_id": game.get("game_id"),
+            "title": game.get("title"),
+            "theme": game.get("theme"),
+            "city": game.get("setup", {}).get("city"),
+            "area": game.get("setup", {}).get("area"),
+            "duration_minutes": game.get("setup", {}).get("duration_minutes"),
+            "num_players": game.get("setup", {}).get("num_players"),
+        },
+        "winner": winner,
+        "final_scores": scores.get("team_scores", []),
+        "task_outcomes": task_outcomes,
+        "journal_moments": journal_moments,
+        "photo_captions": photo_captions or [],
+        "notable_events": notable_events,
+        "story_style": game.get("story_seed", {}).get("recap_style", "episode_recap"),
+    }
+
+    return packet
+
+
+# ── Template-based recap (works offline) ───────────────────────────────────
+
+def _template_short_recap(packet: dict) -> str:
+    """Generate a short recap from the story packet without an LLM."""
+    title = packet.get("game_info", {}).get("title", "The Game")
+    winner = packet.get("winner", "nobody")
+    total_tasks = len(packet.get("task_outcomes", []))
+    completed = sum(
+        1 for t in packet.get("task_outcomes", []) if t.get("completed")
+    )
+    score_entries = packet.get("final_scores", [])
+    top_score = score_entries[0]["points"] if score_entries else 0
+
+    decisive = None
+    for t in packet.get("task_outcomes", []):
+        if t.get("completed"):
+            decisive = t.get("title")
+
+    parts = [
+        f"🏆 **{title}** is in the books!",
+        f"Team **{winner}** took the crown with **{top_score}** points, "
+        f"completing {completed}/{total_tasks} tasks.",
+    ]
+
+    if decisive:
+        parts.append(f"The decisive moment came during *{decisive}*.")
+
+    moments = packet.get("journal_moments", [])
+    if moments:
+        m = moments[0]
+        mood = m.get("mood", "excited")
+        summary = m.get("moment_summary", "")[:100]
+        parts.append(f"A [{mood}] highlight: \"{summary}\"")
+
+    return "\n\n".join(parts)
+
+
+def _template_long_summary(packet: dict) -> str:
+    """Generate a full episode recap from the story packet without an LLM."""
+    info = packet.get("game_info", {})
+    title = info.get("title", "The Game")
+    city = info.get("city", "the city")
+    area = info.get("area", "the area")
+    duration = info.get("duration_minutes", 45)
+    num_players = info.get("num_players", 4)
+    winner = packet.get("winner", "nobody")
+
+    lines = [
+        f"# {title}",
+        "",
+        f"In the heart of **{city}**, specifically around **{area}**, "
+        f"{num_players} players gathered for a {duration}-minute showdown.",
+        "",
+        "## How it went down",
+        "",
+    ]
+
+    for t in packet.get("task_outcomes", []):
+        status = t.get("status", "incomplete")
+        icon = "✅" if status == "completed" else "⏭️" if status == "skipped" else "❌"
+        lines.append(f"- {icon} **{t.get('title', 'Unknown')}** — {t.get('points', 0)} pts [{status}]")
+
+    moments = packet.get("journal_moments", [])
+    if moments:
+        lines.extend(["", "## Memorable moments", ""])
+        for m in moments:
+            mood = m.get("mood", "")
+            lines.append(f"- 🎙️ *{mood}*: \"{m.get('moment_summary', '')}\"")
+
+    lines.extend(["", "## Final standings", ""])
+    for s in packet.get("final_scores", []):
+        marker = " 🏆" if s.get("team_id") == winner else ""
+        lines.append(
+            f"- **{s.get('team_id', 'team')}**: {s.get('points', 0)} pts "
+            f"({s.get('completed_tasks', 0)}/{s.get('total_tasks', 0)} tasks){marker}"
+        )
+
+    lines.extend(["", "### Scoring breakdown"])
+    for s in packet.get("final_scores", []):
+        for line in s.get("scoring_breakdown", []):
+            lines.append(f"  - {line}")
+
+    lines.extend([
+        "",
+        "---",
+        f"*Generated by GeoChase AI Pipeline — {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}*",
+    ])
+
+    return "\n".join(lines)
+
+
+def _template_poster_prompt(packet: dict) -> str:
+    """Generate an image-generation prompt for a recap poster."""
+    info = packet.get("game_info", {})
+    winner = packet.get("winner", "team-a")
+    title = info.get("title", "GeoChase Game")
+    city = info.get("city", "Paris")
+    area = info.get("area", "the city center")
+    mood = "wholesome"
+    moments = packet.get("journal_moments", [])
+    if moments:
+        mood = moments[0].get("mood", "wholesome")
+
+    return (
+        f"Cinematic recap poster for an urban real-world game called '{title}'. "
+        f"Scene: a group of {info.get('num_players', 4)} friends exploring "
+        f"{area} in {city}. Style: warm lighting, slightly nostalgic film grain, "
+        f"vibrant but not oversaturated. Mood: {mood}. "
+        f"Include subtle game UI overlays (score badge, timer). "
+        f"Team {winner} celebrating. No text in the image."
+    )
+
+
+# ── LLM-based recap ────────────────────────────────────────────────────────
+
+def _llm_recap(prompt_template: str, story_packet: dict) -> Optional[dict]:
+    """Attempt to generate a recap using the Nemotron LLM via llama-cpp-python.
+
+    Returns None if the model is unavailable so callers can fall back to
+    the template engine.
+    """
+    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",
+            verbose=False,
+            n_gpu_layers=-1,
+            n_ctx=2048,
+        )
+
+        packet_str = json.dumps(story_packet, indent=2, default=str)[:3000]
+        prompt = prompt_template.format(story_packet=packet_str)
+
+        result = llm(
+            f"You are a talented narrative writer. Return ONLY valid JSON.\n\n{prompt}",
+            max_tokens=2000,
+            temperature=0.8,
+            top_p=0.95,
+            stop=["```", "\n\n\n"],
+        )
+
+        text = result["choices"][0]["text"]
+        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:
+                    return json.loads(text[start : i + 1])
+
+        return None
+
+    except Exception as exc:
+        print(f"[story] LLM recap failed: {exc}")
+        return None
+
+
+# ── Main entry point ────────────────────────────────────────────────────────
+
+def generate_story(story_packet: dict, session_id: Optional[str] = None) -> dict:
     """Generate final recap story from game data and events.
-    
-    Uses OpenBMB MiniCPM5-1B or similar model.
-    
+
+    Attempts LLM-based generation first; falls back to high-quality
+    templates so the pipeline always returns a result.
+
     Args:
-        story_packet: Structured packet with game info, scores, journals, photos
-        
+        story_packet: Structured packet with game info, scores, journals, photos.
+        session_id: Optional session ID for logging the recap event.
+
     Returns:
-        Story output with short recap, long-form summary, and poster prompt
+        Story output dict with keys ``short_recap``, ``long_summary``,
+        ``poster_prompt``, ``story_packet``.
     """
-    # TODO: Implement with OpenBMB model
-    return {
-        "short_recap": "",
-        "long_summary": "",
-        "poster_prompt": ""
+    # 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")
+
+    llm_result = None
+    if prompt_template:
+        llm_result = _llm_recap(prompt_template, story_packet)
+
+    if llm_result and all(k in llm_result for k in ("short_recap", "long_summary", "poster_prompt")):
+        short_recap = llm_result["short_recap"]
+        long_summary = llm_result["long_summary"]
+        poster_prompt = llm_result["poster_prompt"]
+    else:
+        short_recap = _template_short_recap(story_packet)
+        long_summary = _template_long_summary(story_packet)
+        poster_prompt = _template_poster_prompt(story_packet)
+
+    result = {
+        "short_recap": short_recap,
+        "long_summary": long_summary,
+        "poster_prompt": poster_prompt,
+        "story_packet": story_packet,
     }
+
+    if session_id:
+        log_event(
+            session_id=session_id,
+            event_type="game_finished",
+            payload={
+                "short_recap": short_recap[:200],
+                "winner": story_packet.get("winner"),
+                "total_tasks": len(story_packet.get("task_outcomes", [])),
+            },
+        )
+
+    return result

app/services/tracing.py

@@ -1,29 +1,174 @@
-"""Logging and tracing module for pipeline transparency."""
+"""Logging and tracing module for pipeline transparency.
+
+Stores JSONL event logs and complete pipeline traces for debugging,
+demo narration, and possible trace publication.
+"""
 
 import json
+import uuid
+from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any
+from typing import Any, Optional
+
+
+# Valid event types matching the event schema
+VALID_EVENT_TYPES = [
+    "task_revealed",
+    "task_completed",
+    "hint_used",
+    "task_skipped",
+    "photo_uploaded",
+    "journal_recorded",
+    "score_updated",
+    "game_finished",
+]
+
+
+def _ensure_log_dir(log_dir: str) -> Path:
+    """Ensure the log directory exists and return its Path."""
+    path = Path(log_dir)
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _now_iso() -> str:
+    """Return current time as ISO-8601 string."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def log_event(
+    session_id: str,
+    event_type: str,
+    payload: dict,
+    team_id: str = "team-a",
+    log_dir: str = "app/logs",
+) -> dict:
+    """Log a gameplay event to a JSONL file.
+
+    Each event is appended as a single JSON line to ``events.jsonl`` inside
+    *log_dir*.  Returns the full event dict that was written so callers can
+    pass it onward (e.g. into the scoring pipeline).
+
+    Args:
+        session_id: Session identifier.
+        event_type: One of the ``VALID_EVENT_TYPES``.
+        payload: Event-specific data dictionary.
+        team_id: Team that generated the event (default ``"team-a"``).
+        log_dir: Directory to store logs.
+
+    Returns:
+        The complete event dict that was persisted.
+
+    Raises:
+        ValueError: If *event_type* is not in the allowed set.
+    """
+    if event_type not in VALID_EVENT_TYPES:
+        raise ValueError(
+            f"Invalid event_type '{event_type}'. "
+            f"Must be one of: {VALID_EVENT_TYPES}"
+        )
+
+    event = {
+        "event_id": str(uuid.uuid4()),
+        "timestamp": _now_iso(),
+        "session_id": session_id,
+        "team_id": team_id,
+        "event_type": event_type,
+        "payload": payload,
+    }
 
+    log_path = _ensure_log_dir(log_dir) / "events.jsonl"
+    with open(log_path, "a", encoding="utf-8") as fh:
+        fh.write(json.dumps(event, ensure_ascii=False) + "\n")
+
+    return event
+
+
+def load_events(session_id: Optional[str] = None, log_dir: str = "app/logs") -> list[dict]:
+    """Load events from the JSONL log file, optionally filtered by session.
+
+    Args:
+        session_id: If provided, only return events for this session.
+        log_dir: Directory containing event logs.
+
+    Returns:
+        List of event dicts.
+    """
+    log_path = Path(log_dir) / "events.jsonl"
+    if not log_path.exists():
+        return []
+
+    events: list[dict] = []
+    with open(log_path, "r", encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if session_id and event.get("session_id") != session_id:
+                continue
+            events.append(event)
+
+    return events
+
+
+def log_generation_trace(
+    session_id: str,
+    config: dict,
+    retrieved_examples: list[dict],
+    game: dict,
+    validation_passed: bool,
+    validation_failures: list[str],
+    repaired_game: Optional[dict] = None,
+    log_dir: str = "app/logs",
+) -> dict:
+    """Log the full generation pipeline trace for one session.
+
+    Captures config → retrieval → generation → validation → repair in a
+    single JSON file for debugging and publication.
 
-def log_event(session_id: str, event_type: str, payload: dict, log_dir: str = "app/logs") -> None:
-    """Log a gameplay event to JSONL file.
-    
     Args:
-        session_id: Session identifier
-        event_type: Type of event (task_revealed, completed, etc.)
-        payload: Event data
-        log_dir: Directory to store logs
+        session_id: Session identifier.
+        config: User-provided game configuration.
+        retrieved_examples: Examples retrieved by the grounding module.
+        game: Generated game JSON.
+        validation_passed: Whether the game passed validation.
+        validation_failures: Any validation failure messages.
+        repaired_game: Post-repair game dict, or None if no repair was needed.
+        log_dir: Directory to store logs.
+
+    Returns:
+        The complete trace dict.
     """
-    # TODO: Implement JSONL logging
-    pass
+    trace = {
+        "session_id": session_id,
+        "timestamp": _now_iso(),
+        "config": config,
+        "retrieved_examples": retrieved_examples,
+        "generated_game": game,
+        "validation_passed": validation_passed,
+        "validation_failures": validation_failures,
+        "repaired_game": repaired_game,
+    }
+
+    trace_path = _ensure_log_dir(log_dir) / f"trace_{session_id}.json"
+    with open(trace_path, "w", encoding="utf-8") as fh:
+        json.dump(trace, fh, indent=2, ensure_ascii=False)
+
+    return trace
 
 
 def save_trace(trace_data: dict, output_path: str) -> None:
     """Save a complete pipeline trace for debugging and publication.
-    
+
     Args:
-        trace_data: Dictionary containing all pipeline data
-        output_path: Where to save the trace file
+        trace_data: Dictionary containing all pipeline data.
+        output_path: Where to save the trace file.
     """
-    # TODO: Implement trace saving
-    pass
+    out = Path(output_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    with open(out, "w", encoding="utf-8") as fh:
+        json.dump(trace_data, fh, indent=2, ensure_ascii=False)

test_phase3.py

@@ -0,0 +1,83 @@
+"""End-to-end test for Phase 3: Session Intelligence."""
+
+import uuid
+from app.services.retrieval import load_games_dataset, normalize_game_record, retrieve_examples
+from app.services.generator import generate_game
+from app.services.validator import validate_game, repair_game
+from app.services.tracing import log_event, load_events
+from app.services.journal import create_journal_entry, save_journal_entry, summarize_journal, load_journal_entries
+from app.services.scoring import compute_scores
+from app.services.story import build_story_packet, generate_story
+
+# 1. Load dataset
+raw = load_games_dataset("app/data/games_dataset.json")
+records = [normalize_game_record(r) for r in raw]
+print(f"✓ Loaded {len(records)} records")
+
+# 2. Config
+config = {
+    "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",
+    "photo_enabled": True,
+}
+
+# 3. Retrieve + Generate
+retrieved = retrieve_examples(config, records, k=3)
+game = generate_game(config, retrieved)
+print(f"✓ Generated: {game['title']} with {len(game['tasks'])} tasks")
+
+# 4. Validate
+is_valid, failures = validate_game(game, config)
+status = "PASS" if is_valid else f"FAIL ({len(failures)} issues)"
+print(f"✓ Validation: {status}")
+
+# 5. Session
+session_id = f"test-{uuid.uuid4().hex[:8]}"
+
+# 6. Log events
+for t in game["tasks"]:
+    log_event(session_id, "task_revealed", {"task_id": t["task_id"], "title": t["title"]})
+log_event(session_id, "task_completed", {"task_id": "t1", "summary": "Completed first task"}, team_id="team-a")
+log_event(session_id, "task_completed", {"task_id": "t2", "summary": "Completed second task"}, 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")
+events = load_events(session_id)
+print(f"✓ Logged {len(events)} events")
+
+# 7. Journal
+entry = create_journal_entry(
+    transcript="We found the mural near the canal, it was incredible! The whole team cheered.",
+    session_id=session_id,
+    team_id="team-a",
+    task_id="t1",
+    location_note="Canal area",
+)
+summary = summarize_journal(entry["transcript"], task_id="t1")
+entry.update(summary)
+save_journal_entry(entry)
+journals = load_journal_entries(session_id)
+print(f"✓ Journal mood={entry['mood']}, story_value={entry['story_value']}")
+
+# 8. Score
+scores = compute_scores(events, game)
+print(f"✓ Winner: {scores['winner']}")
+for s in scores["team_scores"]:
+    print(f"  - {s['team_id']}: {s['points']} pts ({s['completed_tasks']}/{s['total_tasks']} tasks)")
+
+# 9. Story
+packet = build_story_packet(game, events, scores, journals)
+story = generate_story(packet, session_id=session_id)
+print(f"✓ Story recap: {len(story['short_recap'])} chars short, {len(story['long_summary'])} chars long")
+
+print()
+print("=== SHORT RECAP ===")
+print(story["short_recap"])
+print()
+print("=== PIPELINE COMPLETE ✓ ===")