Phase 1: establish the baseline

.gitignore

@@ -0,0 +1,104 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+env/
+.env
+
+# IDE and Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+*.sublime-project
+*.sublime-workspace
+.project
+.pydevproject
+.settings/
+*.code-workspace
+
+# OS
+Thumbs.db
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Logs and temporary files
+app/logs/*.jsonl
+app/logs/*.log
+*.log
+*.pot
+
+# Runtime data
+.coverage
+.pytest_cache/
+htmlcov/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+*.ipynb
+
+# Unit test / coverage reports
+.tox/
+.hypothesis/
+.coverage
+.coverage.*
+.cache
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Model files and large data
+*.model
+*.bin
+*.pt
+*.pth
+*.ckpt
+
+# Temporary and backup files
+*.tmp
+*.bak
+*.swp
+*.swo
+*~
+.~*
+
+# Generated files
+normalized_games.json
+
+
+# other files to ignore
+Geo_Chase_Project_Specification.md
+ai_pipeline_source_of_truth.md

app/__init__.py

@@ -0,0 +1 @@
+"""AI Pipeline for location-based game generation and management."""

app/main.py

@@ -0,0 +1,14 @@
+import gradio as gr
+import spaces
+import torch
+
+zero = torch.Tensor([0]).cuda()
+print(zero.device) # <-- 'cpu' 🤔
+
+@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()

app/prompts/game_generation.txt

@@ -0,0 +1,33 @@
+You are an expert urban real-world game designer. Your task is to create an engaging, safe, and playable location-based game.
+
+## Context
+- City: {city}
+- Area: {area}
+- Game Type: {game_type}
+- Duration: {duration_minutes} minutes
+- Number of 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
+
+## 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
+
+## Output Schema
+{output_schema}
+
+Generate the game JSON:

app/prompts/game_repair.txt

@@ -0,0 +1,18 @@
+You are an expert editor specializing in game design quality assurance.
+
+## Task
+Fix the following failed validation checks in this game JSON. Make minimal changes—only fix the specific failures listed.
+
+## Failures
+{failures}
+
+## Original Game
+{game_json}
+
+## Requirements
+- Return ONLY valid JSON matching the schema
+- Keep all other fields unchanged
+- Ensure no new validation failures are introduced
+
+## Output
+Repaired game JSON:

app/prompts/story_recap.txt

@@ -0,0 +1,20 @@
+You are a talented narrative writer creating engaging recaps of location-based games.
+
+## Game Data
+{story_packet}
+
+## Instructions
+- Use ONLY facts from logs, tasks, journals, scores, and photos
+- Do NOT invent locations or quotes
+- Mention 2-4 concrete moments from player journals
+- Highlight the decisive turning point
+- Maintain a lively, memorable tone
+- Keep recaps between 150-250 words for short recap, 400-600 words for long summary
+
+## Output
+Generate:
+1. short_recap: Brief highlight for the result screen
+2. long_summary: Full episode recap
+3. poster_prompt: Visual prompt for image generation
+
+Return as JSON with these three keys.

app/schemas/event_schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Event Schema",
+  "type": "object",
+  "required": [
+    "event_id",
+    "timestamp",
+    "session_id",
+    "team_id",
+    "event_type",
+    "payload"
+  ],
+  "properties": {
+    "event_id": {
+      "type": "string",
+      "description": "Unique event identifier"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp"
+    },
+    "session_id": {
+      "type": "string",
+      "description": "Game session identifier"
+    },
+    "team_id": {
+      "type": "string",
+      "description": "Team identifier"
+    },
+    "event_type": {
+      "type": "string",
+      "enum": [
+        "task_revealed",
+        "task_completed",
+        "hint_used",
+        "task_skipped",
+        "photo_uploaded",
+        "journal_recorded",
+        "score_updated",
+        "game_finished"
+      ],
+      "description": "Type of gameplay event"
+    },
+    "payload": {
+      "type": "object",
+      "description": "Event-specific data"
+    }
+  }
+}

app/schemas/game_schema.json

@@ -0,0 +1,178 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Game Schema",
+  "type": "object",
+  "required": [
+    "game_id",
+    "title",
+    "theme",
+    "setup",
+    "rules",
+    "tasks",
+    "global_hints",
+    "score_rules",
+    "tie_breaker",
+    "safety",
+    "story_seed"
+  ],
+  "properties": {
+    "game_id": {
+      "type": "string",
+      "description": "Unique game identifier"
+    },
+    "title": {
+      "type": "string",
+      "description": "Game title"
+    },
+    "theme": {
+      "type": "string",
+      "description": "Game theme"
+    },
+    "setup": {
+      "type": "object",
+      "required": ["city", "area", "meeting_point", "duration_minutes", "num_players"],
+      "properties": {
+        "city": {
+          "type": "string"
+        },
+        "area": {
+          "type": "string"
+        },
+        "meeting_point": {
+          "type": "string"
+        },
+        "duration_minutes": {
+          "type": "integer"
+        },
+        "num_players": {
+          "type": "integer"
+        }
+      }
+    },
+    "rules": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Game rules"
+    },
+    "tasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "task_id",
+          "title",
+          "description",
+          "location_hint",
+          "points",
+          "time_limit_minutes",
+          "proof_type",
+          "hint",
+          "safety_note"
+        ],
+        "properties": {
+          "task_id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "location_hint": {
+            "type": "string"
+          },
+          "points": {
+            "type": "integer"
+          },
+          "time_limit_minutes": {
+            "oneOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "proof_type": {
+            "type": "string",
+            "enum": ["photo", "observation", "text"]
+          },
+          "hint": {
+            "type": "string"
+          },
+          "safety_note": {
+            "type": "string"
+          }
+        }
+      },
+      "description": "List of game tasks"
+    },
+    "global_hints": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "score_rules": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "tie_breaker": {
+      "type": "string"
+    },
+    "safety": {
+      "type": "object",
+      "required": [
+        "allowed_zone",
+        "forbidden_behaviors",
+        "adult_supervision",
+        "stop_conditions"
+      ],
+      "properties": {
+        "allowed_zone": {
+          "type": "string"
+        },
+        "forbidden_behaviors": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "adult_supervision": {
+          "type": "boolean"
+        },
+        "stop_conditions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "story_seed": {
+      "type": "object",
+      "required": ["tone", "motifs", "recap_style"],
+      "properties": {
+        "tone": {
+          "type": "string",
+          "enum": ["playful", "cinematic", "chaotic", "wholesome"]
+        },
+        "motifs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "recap_style": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

app/schemas/journal_schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Journal Entry Schema",
+  "type": "object",
+  "required": [
+    "journal_id",
+    "timestamp",
+    "session_id",
+    "team_id",
+    "transcript",
+    "mood",
+    "location_note"
+  ],
+  "properties": {
+    "journal_id": {
+      "type": "string",
+      "description": "Unique journal entry identifier"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp"
+    },
+    "session_id": {
+      "type": "string",
+      "description": "Game session identifier"
+    },
+    "team_id": {
+      "type": "string",
+      "description": "Team identifier"
+    },
+    "task_id": {
+      "type": "string",
+      "description": "Optional associated task"
+    },
+    "transcript": {
+      "type": "string",
+      "description": "Transcribed voice note"
+    },
+    "mood": {
+      "type": "string",
+      "enum": ["funny", "confused", "excited", "tense", "lucky", "chaotic"],
+      "description": "Emotional tone of the journal entry"
+    },
+    "location_note": {
+      "type": "string",
+      "description": "Where the entry was recorded"
+    },
+    "photo_refs": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "References to associated photos"
+    }
+  }
+}

app/schemas/story_packet_schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Story Packet Schema",
+  "type": "object",
+  "required": [
+    "game_info",
+    "winner",
+    "final_scores",
+    "task_outcomes",
+    "journal_moments",
+    "photo_captions",
+    "notable_events",
+    "story_style"
+  ],
+  "properties": {
+    "game_info": {
+      "type": "object",
+      "description": "Game metadata and setup"
+    },
+    "winner": {
+      "type": "string",
+      "description": "Winning team identifier"
+    },
+    "final_scores": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      },
+      "description": "Final team scores"
+    },
+    "task_outcomes": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      },
+      "description": "Outcomes of all tasks"
+    },
+    "journal_moments": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      },
+      "description": "Selected journal entries for story"
+    },
+    "photo_captions": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      },
+      "description": "Photos with captions"
+    },
+    "notable_events": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      },
+      "description": "Significant gameplay moments"
+    },
+    "story_style": {
+      "type": "string",
+      "enum": ["episode_recap"],
+      "description": "Style of story to generate"
+    }
+  }
+}

app/services/__init__.py

@@ -0,0 +1 @@
+"""AI services for the game pipeline."""

app/services/generator.py

@@ -0,0 +1,41 @@
+"""Game generation module using Nemotron or similar models."""
+
+from typing import Any
+
+
+def generate_game(config: dict, retrieved_examples: list[dict]) -> dict:
+    """Generate a game from user config and retrieved examples.
+    
+    Uses NVIDIA Nemotron Nano 4B as the primary generator.
+    
+    Args:
+        config: Game configuration (game_type, city, duration, etc.)
+        retrieved_examples: List of similar example games for grounding
+        
+    Returns:
+        Generated game JSON matching the game schema
+    """
+    # TODO: Implement with Nemotron or mock for testing
+    mock_game = {
+        "game_id": "mock-001",
+        "title": "Mock Game",
+        "theme": "test",
+        "setup": config,
+        "rules": [],
+        "tasks": [],
+        "global_hints": [],
+        "score_rules": [],
+        "tie_breaker": "",
+        "safety": {
+            "allowed_zone": "",
+            "forbidden_behaviors": [],
+            "adult_supervision": False,
+            "stop_conditions": []
+        },
+        "story_seed": {
+            "tone": "playful",
+            "motifs": [],
+            "recap_style": "episode_recap"
+        }
+    }
+    return mock_game

app/services/journal.py

@@ -0,0 +1,34 @@
+"""Voice journal capture and summarization module."""
+
+from typing import Any
+
+
+def transcribe_journal(audio_path: str) -> str:
+    """Transcribe voice journal audio to text.
+    
+    Args:
+        audio_path: Path to recorded audio file
+        
+    Returns:
+        Transcribed text
+    """
+    # TODO: Implement with speech-to-text service
+    return ""
+
+
+def summarize_journal(transcript: str, task_id: str | None = None) -> dict:
+    """Summarize journal entry using OpenBMB model.
+    
+    Args:
+        transcript: Journal transcript text
+        task_id: Optional associated task ID
+        
+    Returns:
+        Journal summary with tags and story value
+    """
+    # TODO: Implement with MiniCPM or similar model
+    return {
+        "moment_summary": "",
+        "tags": [],
+        "story_value": "low"
+    }

app/services/retrieval.py

@@ -0,0 +1,200 @@
+"""Retrieval grounding module for fetching similar game examples."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def load_games_dataset(path: str) -> list[dict]:
+    """Load the games dataset from JSON file.
+    
+    Args:
+        path: Path to games_dataset.json
+        
+    Returns:
+        List of game records
+    """
+    with open(path, 'r', encoding='utf-8') as f:
+        return json.load(f)
+
+
+def normalize_game_record(record: dict) -> dict:
+    """Normalize a raw game record into structured format.
+    
+    Extracts features from the nested dataset structure and creates
+    a flat normalized record suitable for retrieval and logging.
+    
+    Args:
+        record: Raw game record from dataset
+        
+    Returns:
+        Normalized game record with extracted features
+    """
+    # Extract input fields
+    input_data = record.get('input', {})
+    game_type = input_data.get('game_type', '')
+    location = input_data.get('location', {})
+    preferences = input_data.get('preferences', {})
+    
+    # Extract output fields
+    output_data = record.get('expected_output', {})
+    tasks = output_data.get('tasks', [])
+    rules = output_data.get('rules', [])
+    hints = output_data.get('hints', [])
+    safety_flags = output_data.get('safety_flags', {})
+    
+    # Extract metadata
+    metadata = record.get('metadata', {})
+    
+    # Build normalized record
+    normalized = {
+        'id': record.get('id'),
+        'game_type': game_type,
+        'city': location.get('city', ''),
+        'area': location.get('area', ''),
+        'location_type': location.get('location_type', ''),
+        'duration_minutes': preferences.get('duration_minutes'),
+        'num_players': preferences.get('num_players'),
+        'difficulty': preferences.get('difficulty', ''),
+        'age_group': preferences.get('age_group', ''),
+        'num_tasks': len(tasks),
+        'task_ids': [t.get('task_id') for t in tasks],
+        'num_rules': len(rules),
+        'num_hints': len(hints),
+        'is_safe': safety_flags.get('is_safe', True),
+        'safety_flags_list': safety_flags.get('flags', []),
+        'quality_score': metadata.get('quality_score'),
+        'source': metadata.get('source'),
+        'notes': metadata.get('notes', ''),
+        # Store full objects for reference
+        'rules': rules,
+        'tasks': tasks,
+        'hints': hints,
+    }
+    
+    return normalized
+
+
+def retrieve_examples(config: dict, dataset: list[dict], k: int = 5) -> list[dict]:
+    """Retrieve top k closest examples from dataset.
+    
+    Uses game type, duration, age group, difficulty, location type,
+    and area similarity for retrieval.
+    
+    Args:
+        config: Game configuration from user input
+        dataset: Loaded games dataset
+        k: Number of examples to retrieve
+        
+    Returns:
+        List of retrieved example games (compressed exemplar bundles)
+    """
+    if not dataset:
+        return []
+    
+    # Scoring function for retrieval
+    def compute_similarity_score(config: dict, record: dict) -> float:
+        """Compute similarity score between config and record."""
+        score = 0.0
+        
+        # Game type exact match (highest weight)
+        if config.get('game_type', '').lower() == record.get('game_type', '').lower():
+            score += 50
+        
+        # Age group match (high weight)
+        config_age = config.get('age_group', '').lower()
+        record_age = record.get('age_group', '').lower()
+        if config_age and record_age:
+            # Exact match
+            if config_age == record_age:
+                score += 25
+            # Mixed age groups can match with any specific age
+            elif 'mixed' in [config_age, record_age]:
+                score += 15
+        
+        # Difficulty match (medium weight)
+        if config.get('difficulty', '').lower() == record.get('difficulty', '').lower():
+            score += 20
+        
+        # Location type match (medium weight)
+        if config.get('location_type', '').lower() == record.get('location_type', '').lower():
+            score += 15
+        
+        # Duration proximity (lower weight, prefer closer durations)
+        config_duration = config.get('duration_minutes')
+        record_duration = record.get('duration_minutes')
+        if config_duration and record_duration:
+            duration_diff = abs(config_duration - record_duration)
+            # Prefer matches within 15 minutes
+            if duration_diff <= 15:
+                score += 10
+            elif duration_diff <= 30:
+                score += 5
+        
+        # Area name similarity (lightweight fuzzy matching)
+        config_area = config.get('area', '').lower()
+        record_area = record.get('area', '').lower()
+        if config_area and record_area:
+            # Exact area match
+            if config_area == record_area:
+                score += 10
+            # Partial area match (e.g., "Parc" matches park names)
+            elif any(word in record_area for word in config_area.split()):
+                score += 3
+        
+        # Quality bonus (prefer higher quality examples)
+        quality = record.get('quality_score', 0)
+        if quality:
+            score += quality * 0.5
+        
+        # Safety bonus (prefer safe games)
+        if record.get('is_safe', True):
+            score += 5
+        
+        return score
+    
+    # Score all records
+    scored_records = []
+    for record in dataset:
+        score = compute_similarity_score(config, record)
+        scored_records.append({
+            'record': record,
+            'score': score
+        })
+    
+    # Sort by score descending
+    scored_records.sort(key=lambda x: x['score'], reverse=True)
+    
+    # Extract top k and compress into exemplar bundles
+    top_k = scored_records[:k]
+    retrieved = []
+    
+    for item in top_k:
+        record = item['record']
+        # Create compressed exemplar bundle
+        exemplar = {
+            'id': record['id'],
+            'game_type': record['game_type'],
+            'area': record['area'],
+            'city': record['city'],
+            'difficulty': record['difficulty'],
+            'age_group': record['age_group'],
+            'duration_minutes': record['duration_minutes'],
+            'location_type': record['location_type'],
+            'rules_summary': record.get('rules', [])[:3],  # Top 3 rules
+            'task_patterns': [
+                {
+                    'task_id': t.get('task_id'),
+                    'proof_type': t.get('proof_type') if 'proof_type' in t else 'observation',
+                    'points': t.get('points'),
+                    'time_limit': t.get('time_limit_minutes')
+                }
+                for t in record.get('tasks', [])[:3]  # Top 3 tasks
+            ],
+            'safety_patterns': record.get('safety_flags_list', []),
+            'quality_score': record.get('quality_score'),
+            'retrieval_score': item['score'],
+        }
+        retrieved.append(exemplar)
+    
+    return retrieved

app/services/schema_validator.py

@@ -0,0 +1,174 @@
+"""Schema validation utilities for the game pipeline."""
+
+import json
+import jsonschema
+from pathlib import Path
+from typing import Any, Tuple
+
+
+def load_schema(schema_name: str = "game_schema.json") -> dict:
+    """Load a JSON schema from the schemas directory.
+    
+    Args:
+        schema_name: Name of the schema file (default: game_schema.json)
+        
+    Returns:
+        Loaded schema as dict
+    """
+    schema_path = Path("app/schemas") / schema_name
+    with open(schema_path, 'r', encoding='utf-8') as f:
+        return json.load(f)
+
+
+def validate_game_schema(game: dict) -> Tuple[bool, list[str]]:
+    """Validate a game JSON against the game schema.
+    
+    Args:
+        game: Game data to validate
+        
+    Returns:
+        Tuple of (is_valid, list of error messages)
+    """
+    schema = load_schema("game_schema.json")
+    errors = []
+    
+    try:
+        jsonschema.validate(instance=game, schema=schema)
+        return True, []
+    except jsonschema.ValidationError as e:
+        errors.append(f"Validation error: {e.message}")
+        errors.append(f"Path: {'.'.join(str(p) for p in e.absolute_path)}")
+        return False, errors
+    except jsonschema.SchemaError as e:
+        errors.append(f"Schema error: {e.message}")
+        return False, errors
+
+
+def validate_task_structure(task: dict) -> Tuple[bool, list[str]]:
+    """Validate a single task object.
+    
+    Args:
+        task: Task data to validate
+        
+    Returns:
+        Tuple of (is_valid, list of error messages)
+    """
+    required_fields = [
+        'task_id', 'title', 'description', 'location_hint',
+        'points', 'time_limit_minutes', 'proof_type', 'hint', 'safety_note'
+    ]
+    
+    errors = []
+    for field in required_fields:
+        if field not in task:
+            errors.append(f"Missing required field: {field}")
+    
+    # Validate proof_type enum
+    if 'proof_type' in task:
+        valid_types = ['photo', 'observation', 'text']
+        if task['proof_type'] not in valid_types:
+            errors.append(f"Invalid proof_type: {task['proof_type']}. Must be one of {valid_types}")
+    
+    # Validate points and time_limit are positive
+    if 'points' in task and task['points'] < 0:
+        errors.append(f"Task points must be non-negative, got {task['points']}")
+    
+    if 'time_limit_minutes' in task and task['time_limit_minutes'] is not None:
+        if task['time_limit_minutes'] < 0:
+            errors.append(f"Task time_limit_minutes must be non-negative, got {task['time_limit_minutes']}")
+    
+    return len(errors) == 0, errors
+
+
+def validate_safety_structure(safety: dict) -> Tuple[bool, list[str]]:
+    """Validate the safety object structure.
+    
+    Args:
+        safety: Safety data to validate
+        
+    Returns:
+        Tuple of (is_valid, list of error messages)
+    """
+    required_fields = ['allowed_zone', 'forbidden_behaviors', 'adult_supervision', 'stop_conditions']
+    errors = []
+    
+    for field in required_fields:
+        if field not in safety:
+            errors.append(f"Missing required safety field: {field}")
+    
+    # Validate field types
+    if 'forbidden_behaviors' in safety and not isinstance(safety['forbidden_behaviors'], list):
+        errors.append("forbidden_behaviors must be an array")
+    
+    if 'stop_conditions' in safety and not isinstance(safety['stop_conditions'], list):
+        errors.append("stop_conditions must be an array")
+    
+    if 'adult_supervision' in safety and not isinstance(safety['adult_supervision'], bool):
+        errors.append("adult_supervision must be a boolean")
+    
+    return len(errors) == 0, errors
+
+
+def create_minimal_game_template() -> dict:
+    """Create a minimal valid game template for testing.
+    
+    Returns:
+        Minimal valid game JSON matching the schema
+    """
+    return {
+        "game_id": "test-game-001",
+        "title": "Test Game",
+        "theme": "test",
+        "setup": {
+            "city": "Paris",
+            "area": "Test Area",
+            "meeting_point": "Central location",
+            "duration_minutes": 45,
+            "num_players": 4
+        },
+        "rules": [
+            "Rule 1",
+            "Rule 2"
+        ],
+        "tasks": [
+            {
+                "task_id": "t1",
+                "title": "Task 1",
+                "description": "Find something",
+                "location_hint": "Look near the entrance",
+                "points": 20,
+                "time_limit_minutes": 10,
+                "proof_type": "photo",
+                "hint": "It's visible from the street",
+                "safety_note": "Stay on public paths"
+            }
+        ],
+        "global_hints": [
+            "Explore systematically"
+        ],
+        "score_rules": [
+            "1 point per second under time limit",
+            "No penalty for hints"
+        ],
+        "tie_breaker": "Team with most tasks completed first",
+        "safety": {
+            "allowed_zone": "Public streets and parks in the designated area",
+            "forbidden_behaviors": [
+                "Entering private buildings",
+                "Crossing major roads unsafely"
+            ],
+            "adult_supervision": False,
+            "stop_conditions": [
+                "Player injury",
+                "Weather emergency"
+            ]
+        },
+        "story_seed": {
+            "tone": "playful",
+            "motifs": [
+                "discovery",
+                "teamwork"
+            ],
+            "recap_style": "episode_recap"
+        }
+    }

app/services/scoring.py

@@ -0,0 +1,21 @@
+"""Deterministic scoring module."""
+
+from typing import Any
+
+
+def compute_scores(events: list[dict], game: dict) -> dict:
+    """Compute final scores from gameplay events.
+    
+    Args:
+        events: List of gameplay events
+        game: The original game definition
+        
+    Returns:
+        Scoring output with team scores and winner
+    """
+    # TODO: Implement deterministic scoring
+    return {
+        "team_scores": [],
+        "winner": None,
+        "scoring_explanation": []
+    }

app/services/story.py

@@ -0,0 +1,22 @@
+"""Final story and recap generation module."""
+
+from typing import Any
+
+
+def generate_story(story_packet: dict) -> dict:
+    """Generate final recap story from game data and events.
+    
+    Uses OpenBMB MiniCPM5-1B or similar model.
+    
+    Args:
+        story_packet: Structured packet with game info, scores, journals, photos
+        
+    Returns:
+        Story output with short recap, long-form summary, and poster prompt
+    """
+    # TODO: Implement with OpenBMB model
+    return {
+        "short_recap": "",
+        "long_summary": "",
+        "poster_prompt": ""
+    }

app/services/tracing.py

@@ -0,0 +1,29 @@
+"""Logging and tracing module for pipeline transparency."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+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
+    """
+    # TODO: Implement JSONL logging
+    pass
+
+
+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
+    """
+    # TODO: Implement trace saving
+    pass

app/services/validator.py

@@ -0,0 +1,54 @@
+"""Game validation and repair module."""
+
+from typing import Any
+
+
+def validate_game(game: dict, config: dict) -> tuple[bool, list[str]]:
+    """Validate generated game against hard rules.
+    
+    Args:
+        game: Generated game JSON
+        config: Original game configuration
+        
+    Returns:
+        Tuple of (is_valid, list of failure messages)
+    """
+    failures = []
+    
+    # Hard validation rules
+    hard_checks = [
+        ("title", lambda g: g.get("title")),
+        ("theme", lambda g: g.get("theme")),
+        ("setup", lambda g: g.get("setup")),
+        ("rules", lambda g: isinstance(g.get("rules"), list) and len(g.get("rules", [])) > 0),
+        ("tasks", lambda g: isinstance(g.get("tasks"), list) and len(g.get("tasks", [])) > 0),
+        ("no_buildings", lambda g: not any("building" in str(t).lower() for t in g.get("tasks", []))),
+        ("no_private_areas", lambda g: not any("private" in str(t).lower() for t in g.get("tasks", []))),
+        ("global_hints", lambda g: isinstance(g.get("global_hints"), list)),
+        ("score_rules", lambda g: isinstance(g.get("score_rules"), list)),
+        ("safety", lambda g: g.get("safety")),
+    ]
+    
+    for check_name, check_fn in hard_checks:
+        try:
+            if not check_fn(game):
+                failures.append(f"Failed check: {check_name}")
+        except Exception as e:
+            failures.append(f"Error in {check_name}: {str(e)}")
+    
+    return len(failures) == 0, failures
+
+
+def repair_game(game: dict, failures: list[str], config: dict) -> dict:
+    """Repair a game that failed validation.
+    
+    Args:
+        game: Failed game JSON
+        failures: List of validation failures
+        config: Original game configuration
+        
+    Returns:
+        Repaired game JSON
+    """
+    # TODO: Implement repair logic with minimal modifications
+    return game

inspect_dataset.py

@@ -0,0 +1,123 @@
+"""
+Inspect and verify the games dataset loader and normalizer.
+
+Run this script to:
+1. Load the dataset
+2. Normalize records
+3. Print one normalized record per game type
+4. Verify schema consistency
+"""
+
+import json
+import sys
+from pathlib import Path
+from app.services.retrieval import load_games_dataset, normalize_game_record
+
+def main():
+    # Load dataset
+    dataset_path = Path("app/data/games_dataset.json")
+    print(f"Loading dataset from: {dataset_path}")
+    
+    try:
+        raw_records = load_games_dataset(str(dataset_path))
+    except FileNotFoundError:
+        print(f"ERROR: Dataset not found at {dataset_path}")
+        sys.exit(1)
+    
+    print(f"\n✓ Loaded {len(raw_records)} game records\n")
+    
+    # Normalize and group by game type
+    normalized_records = []
+    game_types_seen = set()
+    
+    for record in raw_records:
+        try:
+            normalized = normalize_game_record(record)
+            normalized_records.append(normalized)
+        except Exception as e:
+            print(f"ERROR normalizing record {record.get('id')}: {e}")
+            continue
+    
+    print(f"✓ Normalized {len(normalized_records)} records\n")
+    
+    # Print summary
+    print("=" * 80)
+    print("DATASET SUMMARY")
+    print("=" * 80)
+    
+    game_types = {}
+    difficulties = set()
+    age_groups = set()
+    locations = set()
+    
+    for norm in normalized_records:
+        gt = norm['game_type']
+        game_types[gt] = game_types.get(gt, 0) + 1
+        difficulties.add(norm['difficulty'])
+        age_groups.add(norm['age_group'])
+        locations.add((norm['city'], norm['area']))
+    
+    print(f"\nGame Types: {dict(game_types)}")
+    print(f"Difficulties: {sorted(difficulties)}")
+    print(f"Age Groups: {sorted(age_groups)}")
+    print(f"Unique Locations: {len(locations)}")
+    for city, area in sorted(locations):
+        print(f"  - {city}: {area}")
+    
+    # Print one example per game type
+    print("\n" + "=" * 80)
+    print("SAMPLE NORMALIZED RECORDS (one per game type)")
+    print("=" * 80)
+    
+    printed = set()
+    for norm in normalized_records:
+        gt = norm['game_type']
+        if gt not in printed:
+            print(f"\n--- {gt.upper()} (ID: {norm['id']}) ---")
+            print(f"City: {norm['city']}")
+            print(f"Area: {norm['area']}")
+            print(f"Duration: {norm['duration_minutes']} min | Players: {norm['num_players']}")
+            print(f"Difficulty: {norm['difficulty']} | Age Group: {norm['age_group']}")
+            print(f"Tasks: {norm['num_tasks']} | Rules: {norm['num_rules']} | Hints: {norm['num_hints']}")
+            print(f"Location Type: {norm['location_type']}")
+            print(f"Safety: {norm['is_safe']} | Quality Score: {norm['quality_score']}")
+            print(f"Notes: {norm['notes']}")
+            
+            # Print first task as example
+            if norm['tasks']:
+                task = norm['tasks'][0]
+                print(f"\nFirst Task Example:")
+                print(f"  Task ID: {task.get('task_id')}")
+                print(f"  Description: {task.get('description')[:80]}...")
+                print(f"  Points: {task.get('points')} | Time: {task.get('time_limit_minutes')} min")
+            
+            printed.add(gt)
+    
+    # Schema validation
+    print("\n" + "=" * 80)
+    print("SCHEMA VALIDATION")
+    print("=" * 80)
+    
+    required_fields = [
+        'id', 'game_type', 'city', 'area', 'location_type', 
+        'duration_minutes', 'num_players', 'difficulty', 'age_group',
+        'num_tasks', 'task_ids', 'num_rules', 'num_hints', 
+        'is_safe', 'quality_score'
+    ]
+    
+    all_valid = True
+    for norm in normalized_records:
+        for field in required_fields:
+            if field not in norm:
+                print(f"✗ Record {norm.get('id')} missing field: {field}")
+                all_valid = False
+    
+    if all_valid:
+        print("✓ All records have required fields")
+    
+    print("\n" + "=" * 80)
+    print("INSPECTION COMPLETE")
+    print("=" * 80)
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,2 @@
+gradio
+torch

test_retrieval.py

@@ -0,0 +1,135 @@
+"""
+Test and demonstrate the retrieval system.
+
+Run this script to:
+1. Load and normalize the dataset
+2. Test retrieval with various config examples
+3. Display retrieved results with similarity scores
+"""
+
+import json
+from app.services.retrieval import load_games_dataset, normalize_game_record, retrieve_examples
+
+def main():
+    # Load and normalize dataset
+    print("Loading and normalizing dataset...")
+    raw_records = load_games_dataset("app/data/games_dataset.json")
+    normalized_records = [normalize_game_record(r) for r in raw_records]
+    print(f"✓ Loaded {len(normalized_records)} normalized records\n")
+    
+    # Test cases: different user configurations
+    test_configs = [
+        {
+            "name": "Scavenger Hunt - Adults - Medium",
+            "config": {
+                "game_type": "scavenger_hunt",
+                "city": "Paris",
+                "area": "free text",
+                "location_type": "mixed",
+                "duration_minutes": 60,
+                "num_players": 4,
+                "difficulty": "medium",
+                "age_group": "adults",
+                "energy_level": "medium",
+                "photo_enabled": True
+            }
+        },
+        {
+            "name": "Hide and Seek - Kids - Easy",
+            "config": {
+                "game_type": "hide_and_seek",
+                "city": "Paris",
+                "area": "park area",
+                "location_type": "park",
+                "duration_minutes": 45,
+                "num_players": 5,
+                "difficulty": "easy",
+                "age_group": "kids",
+                "energy_level": "high",
+                "photo_enabled": False
+            }
+        },
+        {
+            "name": "Tag - Teens - Hard",
+            "config": {
+                "game_type": "tag",
+                "city": "Paris",
+                "area": "outdoor spaces",
+                "location_type": "mixed",
+                "duration_minutes": 30,
+                "num_players": 8,
+                "difficulty": "hard",
+                "age_group": "teens",
+                "energy_level": "high",
+                "photo_enabled": False
+            }
+        },
+        {
+            "name": "Mixed Age - 90 minutes - Medium",
+            "config": {
+                "game_type": "scavenger_hunt",
+                "city": "Paris",
+                "area": "outdoor",
+                "location_type": "mixed",
+                "duration_minutes": 90,
+                "num_players": 6,
+                "difficulty": "medium",
+                "age_group": "mixed",
+                "energy_level": "medium",
+                "photo_enabled": True
+            }
+        }
+    ]
+    
+    # Run retrieval tests
+    for test in test_configs:
+        print("=" * 80)
+        print(f"TEST: {test['name']}")
+        print("=" * 80)
+        config = test['config']
+        print(f"Query Config:")
+        print(f"  Game Type: {config['game_type']}")
+        print(f"  Duration: {config['duration_minutes']} min | Players: {config['num_players']}")
+        print(f"  Difficulty: {config['difficulty']} | Age Group: {config['age_group']}")
+        print(f"  Location Type: {config['location_type']}")
+        
+        # Retrieve top 5 examples
+        retrieved = retrieve_examples(config, normalized_records, k=5)
+        
+        print(f"\nTop 5 Retrieved Examples:")
+        print("-" * 80)
+        
+        for i, example in enumerate(retrieved, 1):
+            print(f"\n{i}. {example['id']} (Score: {example['retrieval_score']:.1f})")
+            print(f"   Game Type: {example['game_type']}")
+            print(f"   Area: {example['area']}")
+            print(f"   Duration: {example['duration_minutes']} min | Difficulty: {example['difficulty']}")
+            print(f"   Age Group: {example['age_group']} | Quality: {example['quality_score']}/5")
+            print(f"   Rules: {len(example['rules_summary'])} examples")
+            if example['rules_summary']:
+                print(f"     • {example['rules_summary'][0][:70]}...")
+            print(f"   Tasks: {len(example['task_patterns'])} patterns")
+            for task in example['task_patterns'][:2]:
+                print(f"     • {task['task_id']}: {task['points']} pts ({task['proof_type']})")
+            if example['safety_patterns']:
+                print(f"   Safety Flags: {example['safety_patterns']}")
+        
+        print("\n")
+    
+    # Demonstrate retrieval output format
+    print("=" * 80)
+    print("EXEMPLAR BUNDLE OUTPUT FORMAT")
+    print("=" * 80)
+    
+    sample_config = test_configs[0]["config"]
+    sample_retrieved = retrieve_examples(sample_config, normalized_records, k=2)
+    
+    print("\nJSON Output (first 2 results):")
+    print(json.dumps(sample_retrieved, indent=2))
+    
+    print("\n" + "=" * 80)
+    print("RETRIEVAL TESTS COMPLETE")
+    print("=" * 80)
+
+if __name__ == "__main__":
+    main()

test_schema.py

@@ -0,0 +1,265 @@
+"""
+Test the game JSON schema and validation utilities.
+
+Run this script to:
+1. Test the schema against example games from the dataset
+2. Validate schema structure
+3. Test minimal game templates
+4. Display validation results
+"""
+
+import json
+from app.services.retrieval import load_games_dataset, normalize_game_record
+from app.services.schema_validator import (
+    load_schema,
+    validate_game_schema,
+    validate_task_structure,
+    validate_safety_structure,
+    create_minimal_game_template
+)
+
+
+def test_schema_structure():
+    """Test that the schema itself is valid."""
+    print("=" * 80)
+    print("SCHEMA STRUCTURE TEST")
+    print("=" * 80)
+    
+    try:
+        schema = load_schema("game_schema.json")
+        print("✓ Game schema loaded successfully")
+        print(f"  Title: {schema.get('title')}")
+        print(f"  Type: {schema.get('type')}")
+        print(f"  Required fields: {', '.join(schema.get('required', []))}")
+        return True
+    except Exception as e:
+        print(f"✗ Failed to load schema: {e}")
+        return False
+
+
+def test_minimal_template():
+    """Test validation of a minimal game template."""
+    print("\n" + "=" * 80)
+    print("MINIMAL GAME TEMPLATE TEST")
+    print("=" * 80)
+    
+    template = create_minimal_game_template()
+    is_valid, errors = validate_game_schema(template)
+    
+    if is_valid:
+        print("✓ Minimal template is valid against schema")
+        print(f"  Game ID: {template['game_id']}")
+        print(f"  Title: {template['title']}")
+        print(f"  Tasks: {len(template['tasks'])}")
+        print(f"  Rules: {len(template['rules'])}")
+        return True
+    else:
+        print(f"✗ Minimal template validation failed:")
+        for error in errors:
+            print(f"  - {error}")
+        return False
+
+
+def test_dataset_games():
+    """Test validation of example games from the dataset."""
+    print("\n" + "=" * 80)
+    print("DATASET GAMES VALIDATION TEST")
+    print("=" * 80)
+    
+    # Load dataset
+    raw_records = load_games_dataset("app/data/games_dataset.json")
+    
+    # Convert raw records to game schema format for testing
+    tested_count = 0
+    valid_count = 0
+    invalid_games = []
+    
+    for raw in raw_records[:3]:  # Test first 3 as sample
+        try:
+            # Extract expected output as game structure
+            output = raw.get('expected_output', {})
+            input_data = raw.get('input', {})
+            
+            # Build game in schema format
+            # Transform tasks to include required title field
+            tasks_transformed = []
+            for task in output.get('tasks', []):
+                task_copy = task.copy()
+                # Add title if missing
+                if 'title' not in task_copy:
+                    task_copy['title'] = task_copy.get('description', 'Task')[:50]
+                # Ensure all required fields exist
+                task_copy.setdefault('proof_type', 'observation')
+                task_copy.setdefault('hint', 'See location hint above')
+                task_copy.setdefault('safety_note', 'Follow general safety rules')
+                tasks_transformed.append(task_copy)
+            
+            game = {
+                "game_id": raw.get('id'),
+                "title": f"Game {raw.get('id')}",
+                "theme": "discovery",
+                "setup": {
+                    "city": input_data.get('location', {}).get('city', 'Paris'),
+                    "area": input_data.get('location', {}).get('area', ''),
+                    "meeting_point": "Central meeting point",
+                    "duration_minutes": input_data.get('preferences', {}).get('duration_minutes', 45),
+                    "num_players": input_data.get('preferences', {}).get('num_players', 4)
+                },
+                "rules": output.get('rules', []),
+                "tasks": tasks_transformed,
+                "global_hints": output.get('hints', [[]])[0] if output.get('hints') else [],
+                "score_rules": ["Standard scoring"],
+                "tie_breaker": "Most tasks completed",
+                "safety": {
+                    "allowed_zone": "Public area",
+                    "forbidden_behaviors": [],
+                    "adult_supervision": input_data.get('preferences', {}).get('age_group') == 'kids',
+                    "stop_conditions": ["Emergency", "Weather"]
+                },
+                "story_seed": {
+                    "tone": "playful",
+                    "motifs": [],
+                    "recap_style": "episode_recap"
+                }
+            }
+            
+            tested_count += 1
+            is_valid, errors = validate_game_schema(game)
+            
+            if is_valid:
+                valid_count += 1
+                print(f"✓ {game['game_id']}: Valid")
+            else:
+                invalid_games.append({
+                    'id': game['game_id'],
+                    'errors': errors
+                })
+                print(f"✗ {game['game_id']}: Invalid")
+                for error in errors[:2]:  # Show first 2 errors
+                    print(f"    {error}")
+        
+        except Exception as e:
+            tested_count += 1
+            print(f"✗ {raw.get('id')}: Exception - {str(e)[:60]}")
+    
+    print(f"\nResults: {valid_count}/{tested_count} games valid")
+    
+    if invalid_games:
+        print("\nInvalid games details:")
+        for game_info in invalid_games:
+            print(f"  {game_info['id']}: {game_info['errors']}")
+    
+    return valid_count == tested_count
+
+
+def test_task_validation():
+    """Test task-level validation."""
+    print("\n" + "=" * 80)
+    print("TASK VALIDATION TEST")
+    print("=" * 80)
+    
+    test_cases = [
+        {
+            "name": "Valid task",
+            "task": {
+                "task_id": "t1",
+                "title": "Find landmark",
+                "description": "Locate and photograph the fountain",
+                "location_hint": "Look in the central square",
+                "points": 25,
+                "time_limit_minutes": 15,
+                "proof_type": "photo",
+                "hint": "It's in the middle",
+                "safety_note": "Stay on paths"
+            },
+            "expect_valid": True
+        },
+        {
+            "name": "Invalid proof_type",
+            "task": {
+                "task_id": "t2",
+                "title": "Task",
+                "description": "Do something",
+                "location_hint": "Somewhere",
+                "points": 10,
+                "time_limit_minutes": 5,
+                "proof_type": "video",  # Invalid
+                "hint": "Hint",
+                "safety_note": "Safe"
+            },
+            "expect_valid": False
+        },
+        {
+            "name": "Missing safety_note",
+            "task": {
+                "task_id": "t3",
+                "title": "Task",
+                "description": "Do something",
+                "location_hint": "Somewhere",
+                "points": 10,
+                "time_limit_minutes": 5,
+                "proof_type": "observation",
+                "hint": "Hint"
+                # Missing safety_note
+            },
+            "expect_valid": False
+        }
+    ]
+    
+    for test in test_cases:
+        is_valid, errors = validate_task_structure(test['task'])
+        status = "✓" if is_valid == test['expect_valid'] else "✗"
+        print(f"{status} {test['name']}: {is_valid}")
+        if errors:
+            for error in errors[:1]:
+                print(f"    {error}")
+
+
+def test_safety_validation():
+    """Test safety object validation."""
+    print("\n" + "=" * 80)
+    print("SAFETY VALIDATION TEST")
+    print("=" * 80)
+    
+    valid_safety = {
+        "allowed_zone": "Public park and streets",
+        "forbidden_behaviors": [
+            "Entering buildings",
+            "Crossing roads unsafely"
+        ],
+        "adult_supervision": True,
+        "stop_conditions": [
+            "Injury",
+            "Emergency"
+        ]
+    }
+    
+    is_valid, errors = validate_safety_structure(valid_safety)
+    print(f"{'✓' if is_valid else '✗'} Valid safety object: {is_valid}")
+    if errors:
+        for error in errors:
+            print(f"    {error}")
+
+
+def main():
+    print("\nGAME SCHEMA AND VALIDATION TESTS\n")
+    
+    # Run all tests
+    schema_ok = test_schema_structure()
+    template_ok = test_minimal_template()
+    dataset_ok = test_dataset_games()
+    test_task_validation()
+    test_safety_validation()
+    
+    # Summary
+    print("\n" + "=" * 80)
+    print("TEST SUMMARY")
+    print("=" * 80)
+    print(f"Schema structure: {'✓ PASS' if schema_ok else '✗ FAIL'}")
+    print(f"Minimal template: {'✓ PASS' if template_ok else '✗ FAIL'}")
+    print(f"Dataset games: {'✓ PASS' if dataset_ok else '✗ FAIL'}")
+    print("\nSchema validation is ready for use in game generation and validation.")
+
+
+if __name__ == "__main__":
+    main()