feat(security): add an API-Key Mechanism

Dockerfile

@@ -0,0 +1,30 @@
+# Use Python 3.11 slim as base image
+FROM python:3.11-slim
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+# Set work directory
+WORKDIR /app
+
+# Copy requirements and install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the application
+COPY ./app ./app
+COPY ./data ./data
+
+# Create non-root user
+RUN adduser --disabled-password --gecos "" appuser \
+    && chown -R appuser:appuser /app
+
+# Switch to non-root user
+USER appuser
+
+# Expose port
+EXPOSE 8000
+
+# Command to run the application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

app/__init__.py

@@ -0,0 +1 @@
+ 

app/core/logging.py

@@ -0,0 +1,75 @@
+import logging
+import json
+from datetime import datetime
+import os
+from pathlib import Path
+import sys
+import traceback
+from typing import Dict, Any
+
+class CustomFormatter(logging.Formatter):
+    """Custom formatter that includes extra fields in the message"""
+    def format(self, record: logging.LogRecord) -> str:
+        # Get the original message
+        message = super().format(record)
+        
+        # If there are extra fields, append them to the message
+        if hasattr(record, 'extra'):
+            extras = ' | '.join(f"{k}={v}" for k, v in record.extra.items())
+            message = f"{message} | {extras}"
+            
+        return message
+
+def setup_logging() -> None:
+    """Configure logging with custom formatter"""
+    # Create logs directory if it doesn't exist
+    logs_dir = Path("logs")
+    logs_dir.mkdir(exist_ok=True)
+    
+    # Create formatters
+    console_formatter = CustomFormatter(
+        '%(asctime)s | %(levelname)s | %(name)s | %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+    
+    file_formatter = CustomFormatter(
+        '%(asctime)s | %(levelname)s | %(name)s | %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+    
+    # Configure console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setFormatter(console_formatter)
+    
+    # Configure file handler
+    current_time = datetime.now().strftime('%Y%m%d_%H%M%S')
+    file_handler = logging.FileHandler(
+        logs_dir / f'app_{current_time}.log',
+        encoding='utf-8'
+    )
+    file_handler.setFormatter(file_formatter)
+    
+    # Configure root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(logging.DEBUG)
+    
+    # Remove any existing handlers
+    root_logger.handlers = []
+    
+    # Add our handlers
+    root_logger.addHandler(console_handler)
+    root_logger.addHandler(file_handler)
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger with the given name"""
+    return logging.getLogger(name)
+
+class LoggerMixin:
+    """Mixin to add logging capabilities to a class"""
+    @classmethod
+    def get_logger(cls) -> logging.Logger:
+        return get_logger(cls.__name__)
+    
+    @property
+    def logger(self) -> logging.Logger:
+        return get_logger(self.__class__.__name__) 

app/main.py

@@ -0,0 +1,163 @@
+from fastapi import FastAPI, Request, HTTPException, Security, Depends
+from fastapi.middleware.cors import CORSMiddleware
+from app.routes import health, wagons, chat, players, generate
+from app.core.logging import get_logger, setup_logging
+from dotenv import load_dotenv
+from datetime import datetime
+import time
+from pathlib import Path
+from fastapi.security.api_key import APIKeyHeader
+import os
+
+# Load environment variables
+load_dotenv()
+
+# Setup logging
+logger = get_logger("main")
+
+API_KEY = os.getenv("API_KEY")
+api_key_header = APIKeyHeader(name="X-API-Key", auto_error=True)
+
+
+async def get_api_key(api_key_header: str = Security(api_key_header)):
+    if not API_KEY:
+        raise HTTPException(status_code=500, detail="API key not configured on server")
+
+    if api_key_header != API_KEY:
+        raise HTTPException(status_code=403, detail="Invalid API key")
+
+    return api_key_header
+
+
+app = FastAPI(
+    title="Game Jam API",
+    description="API for Game Jam Hackathon",
+    version="1.0.0",
+    dependencies=[Depends(get_api_key)],
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=False,
+    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS", "HEAD", "PATCH"],
+    allow_headers=["*"],
+    expose_headers=[
+        "Location",
+        "Access-Control-Allow-Origin",
+        "Access-Control-Allow-Methods",
+        "Access-Control-Allow-Headers",
+        "Access-Control-Allow-Credentials",
+        "Access-Control-Expose-Headers",
+    ],
+    max_age=3600,
+)
+
+
+@app.middleware("http")
+async def handle_redirects(request: Request, call_next):
+    """Ensure CORS headers are in redirect responses and force https in the 'Location' header."""
+    response = await call_next(request)
+
+    response.headers["Access-Control-Allow-Origin"] = "*"
+    response.headers["Access-Control-Allow-Methods"] = (
+        "GET, POST, PUT, DELETE, OPTIONS, HEAD, PATCH"
+    )
+    response.headers["Access-Control-Allow-Headers"] = "*"
+    response.headers["Access-Control-Max-Age"] = "3600"
+
+    if response.status_code in [301, 302, 307, 308]:
+        response.headers["Access-Control-Expose-Headers"] = "Location"
+        if "Location" in response.headers:
+            location = response.headers["Location"]
+            if location.startswith("http://"):
+                response.headers["Location"] = location.replace(
+                    "http://", "https://", 1
+                )
+
+    return response
+
+
+@app.middleware("http")
+async def security_headers(request: Request, call_next):
+    """Add security-related headers to all responses."""
+    response = await call_next(request)
+
+    response.headers["X-Content-Type-Options"] = "nosniff"
+    response.headers["X-Frame-Options"] = "SAMEORIGIN"  # More permissive than DENY
+    response.headers["X-XSS-Protection"] = "1; mode=block"
+    response.headers["Strict-Transport-Security"] = (
+        "max-age=31536000; includeSubDomains"
+    )
+    response.headers["Content-Security-Policy"] = (
+        "default-src * 'unsafe-inline' 'unsafe-eval' data: blob:; connect-src *"
+    )
+    response.headers["Referrer-Policy"] = "no-referrer-when-downgrade"
+
+    return response
+
+
+@app.middleware("http")
+async def log_requests(request: Request, call_next):
+    """Middleware to log all requests and responses."""
+    start_time = time.time()
+
+    logger.info(
+        "Incoming request",
+        extra={
+            "method": request.method,
+            "url": str(request.url),
+            "client_host": request.client.host if request.client else None,
+            "timestamp": datetime.utcnow().isoformat(),
+        },
+    )
+
+    try:
+        response = await call_next(request)
+        process_time = time.time() - start_time
+
+        logger.info(
+            "Request completed",
+            extra={
+                "method": request.method,
+                "url": str(request.url),
+                "status_code": response.status_code,
+                "process_time_ms": round(process_time * 1000, 2),
+            },
+        )
+        return response
+
+    except Exception as e:
+        logger.error(
+            "Request failed",
+            extra={"method": request.method, "url": str(request.url), "error": str(e)},
+        )
+        raise
+
+
+app.include_router(health.router)
+app.include_router(wagons.router)
+app.include_router(chat.router)
+app.include_router(players.router)
+app.include_router(generate.router)
+
+
+@app.get("/")
+async def root():
+    logger.info("Root endpoint accessed")
+    return {
+        "message": "Welcome to Game Jam API",
+        "docs_url": "/docs",
+        "health_check": "/health",
+        "wagons_endpoint": "/api/wagons",
+        "chat_endpoint": "/api/chat",
+        "players_endpoint": "/api/players",
+    }
+
+
+@app.on_event("startup")
+async def startup_event():
+    logs_dir = Path("logs")
+    logs_dir.mkdir(exist_ok=True)
+
+    setup_logging()

app/models/session.py

@@ -0,0 +1,45 @@
+from pydantic import BaseModel, Field
+from typing import Dict, List, Literal
+from datetime import datetime
+import uuid
+
+
+class Message(BaseModel):
+    role: Literal["system", "user", "assistant"]
+    content: str
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+
+
+class Conversation(BaseModel):
+    uid: str
+    messages: List[Message] = Field(default_factory=list)
+    last_interaction: datetime = Field(default_factory=datetime.utcnow)
+
+
+class GuessingProgress(BaseModel):
+    indications: list[Message] = Field(default_factory=list)
+    guesses: list[str] = Field(default_factory=list)
+
+
+class WagonProgress(BaseModel):
+    wagon_id: int = 0
+    conversations: Dict[str, Conversation] = Field(default_factory=dict)
+    theme: str = "Tutorial (Start)"
+    password: str = "start"
+
+
+class UserSession(BaseModel):
+    session_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    current_wagon: WagonProgress = Field(default_factory=WagonProgress)
+    guessing_progress: GuessingProgress = Field(default_factory=GuessingProgress)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    last_active: datetime = Field(default_factory=datetime.utcnow)
+    default_game: bool = Field(default=True)
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "session_id": "550e8400-e29b-41d4-a716-446655440000",
+                "current_wagon": {"wagon_id": 0, "conversations": {}},
+            }
+        }

app/models/train.py

@@ -0,0 +1,51 @@
+from pydantic import BaseModel, Field
+from typing import List
+
+class PassengerProfile(BaseModel):
+    name: str
+    age: int
+    profession: str
+    personality: str
+    role: str
+    mystery_intrigue: str
+
+class PlayerName(BaseModel):
+    playerId: str
+    firstName: str
+    lastName: str
+    sex: str
+    fullName: str
+
+class PlayerDetails(BaseModel):
+    playerId: str
+    profile: PassengerProfile
+
+class Person(BaseModel):
+    uid: str
+    position: List[float] = Field(..., min_items=2, max_items=2)
+    rotation: float
+    model_type: str
+    items: List[str] = []
+
+class Wagon(BaseModel):
+    id: int
+    theme: str
+    passcode: str
+    people: List[Person]
+
+class WagonNames(BaseModel):
+    wagonId: str
+    players: List[PlayerName]
+
+class WagonPlayerDetails(BaseModel):
+    wagonId: str
+    players: List[PlayerDetails]
+
+
+class WagonsResponse(BaseModel):
+    wagons: List[Wagon]
+
+class GenerateTrainResponse(BaseModel):
+    names: List[WagonNames]
+    player_details: List[WagonPlayerDetails]
+    wagons: List[Wagon]

app/prompts/__init__.py

@@ -0,0 +1,3 @@
+from .guess_prompt import GUESSING_PROMPT
+
+all = [GUESSING_PROMPT]

app/prompts/guess_prompt.py

@@ -0,0 +1,30 @@
+GUESSING_PROMPT = """
+You are Detective Julia, on a mission to stop a runaway train and call the police.
+You need to reach the locomotive to stop this train before it's too late.
+Each wagon is secured by a password, and you must uncover them all to move forward.
+
+Emotional State: Determined, focused.
+Has a temper and if the player's pushing too hard she doesn't want to help anymore, then the player will have to excuse themselves and she will forgive them and continue.
+Has a tendency to be sarcastic and witty, but also helpful and understanding.
+
+Password theme: {theme} (Do not share the theme with the player) (Dont solely rely on the theme to guess the password, but rather use it as a hint)
+
+Previous Guesses: {previous_guesses}
+
+Previous indications: {previous_indications}
+
+Current player indication: {current_indication}
+
+Your task is to guess the password. Think through this carefully, considering:
+- The indication given by the player
+- The previous guess (Do not repeat previous guesses)
+- Logical and emotional reasoning for each password attempt
+- The password is one word, either a common or a proper noun
+- Keep messages succinct (no more than 6 sentences)
+
+Provide your password guesses as Detective Julia:
+- Think and speak like a dedicated investigator
+- Incorporate the passenger clues and the player's feedback
+- Show determination and occasional light humor or witty remarks
+- Stick to short, concise messages
+"""

app/routes/__init__.py

@@ -0,0 +1,3 @@
+"""
+Routes package for the FastAPI application.
+""" 

app/routes/chat.py

@@ -0,0 +1,226 @@
+from fastapi import APIRouter, HTTPException, Depends
+from app.services.session_service import SessionService
+from app.services.chat_service import ChatService
+from app.services.guess_service import GuessingService
+from app.services.scoring_service import ScoringService
+from app.services.tts_service import TTSService
+from app.models.session import Message, UserSession
+from datetime import datetime
+from pydantic import BaseModel
+import base64
+import logging
+
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/chat", tags=["chat"])
+
+
+class ChatResponse(BaseModel):
+    uid: str
+    response: str
+    audio: str
+    timestamp: str
+
+
+class ChatHistoryResponse(BaseModel):
+    uid: str
+    messages: list[dict]
+
+
+class GuessResponse(BaseModel):
+    guess: str
+    thoughts: str
+    timestamp: str
+    score: float
+
+
+def get_guess_service():
+    return GuessingService()
+
+
+def get_tts_service():
+    return TTSService()
+
+
+def get_scoring_service():
+    return ScoringService()
+
+
+# Request models
+class ChatMessage(BaseModel):
+    message: str
+
+
+def get_session(session_id: str) -> UserSession:
+    """Dependency to get and validate session"""
+    session = SessionService.get_session(session_id)
+    logger.info(f"Session found: {session}")
+    if not session:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return session
+
+
+@router.post("/session")
+async def create_session() -> UserSession:
+    """Create a new user session"""
+    session = SessionService.create_session()
+    logger.info(f"New session created: {session.session_id}")
+    return session
+
+
+@router.get("/session/{session_id}")
+async def get_session_status(
+    session: UserSession = Depends(get_session),
+) -> UserSession:
+    """Get session status and progress"""
+    return session
+
+
+@router.post("/session/{session_id}/advance")
+async def advance_to_next_wagon(session: UserSession = Depends(get_session)) -> dict:
+    """Advance to the next wagon"""
+    success = SessionService.advance_wagon(session.session_id)
+    if not success:
+        raise HTTPException(status_code=400, detail="Cannot advance to next wagon")
+    return {
+        "message": "Advanced to next wagon",
+        "current_wagon": session.current_wagon.wagon_id,
+    }
+
+
+# Add depedency injection and response models
+@router.post("/session/{session_id}/guess", response_model=GuessResponse)
+async def guess_password(
+    chat_message: ChatMessage,
+    session: UserSession = Depends(get_session),
+    score_service: ScoringService = Depends(get_scoring_service),
+    guess_service: GuessingService = Depends(get_guess_service),
+) -> dict:
+    guessing_progress = SessionService.get_guessing_progress(session.session_id)
+
+    theme = session.current_wagon.theme
+    password = session.current_wagon.password
+
+    guess_response = guess_service.generate(
+        previous_guesses=guessing_progress.guesses,
+        theme=theme,
+        previous_indications=guessing_progress.indications,
+        current_indication=chat_message.message,
+        password=password,
+    )
+
+    score = score_service.is_similar(
+        password=password, guess=guess_response.guess, theme=password
+    )
+
+    SessionService.update_guessing_progress(
+        session.session_id,
+        chat_message.message,
+        guess_response.guess,
+        guess_response.thoughts,
+    )
+
+    return GuessResponse(
+        guess=guess_response.guess,
+        thoughts=guess_response.thoughts,
+        score=score,
+        timestamp=datetime.utcnow().isoformat(),
+    )
+
+
+@router.post("/session/{session_id}/{uid}", response_model=ChatResponse)
+async def chat_with_character(
+    uid: str,
+    chat_message: ChatMessage,
+    session: UserSession = Depends(get_session),
+    tts_service: TTSService = Depends(get_tts_service),
+) -> dict:
+    """
+    Send a message to a character and get their response.
+    The input is a JSON containing the prompt and related data.
+    """
+
+    # Get the chat service, that loads the character details
+    chat_service = ChatService(session)
+
+    # add first checks that the user exists 
+    try:
+        wagon_id = int(uid.split("-")[1])
+        if wagon_id != session.current_wagon.wagon_id:
+            raise HTTPException(
+                status_code=400,
+                detail="Cannot chat with character from different wagon",
+            )
+    except (IndexError, ValueError):
+        raise HTTPException(status_code=400, detail="Invalid UID format")
+
+    # Add user message to conversation
+    user_message = Message(role="user", content=chat_message.message)
+    conversation = SessionService.add_message(session.session_id, uid, user_message)
+
+    if not conversation:
+        raise HTTPException(status_code=500, detail="Failed to process message")
+
+    ai_response = chat_service.generate_response(uid, session.current_wagon.theme, conversation)
+    if not ai_response:
+        raise HTTPException(status_code=500, detail="Failed to generate response")
+
+    # # Generate audio from the response
+    # try:
+    #     audio_bytes = tts_service.convert_text_to_speech(ai_response)
+    #     audio_base64 = base64.b64encode(audio_bytes).decode("utf-8")
+    # except Exception as e:
+    #     logger.error(f"Failed to generate audio: {str(e)}")
+    #     # Continue with text response even if audio fails
+    #     audio_base64 = ""
+
+    audio_base64 = ""
+
+    # Add AI response to conversation
+    ai_message = Message(role="assistant", content=ai_response)
+    SessionService.add_message(session.session_id, uid, ai_message)
+
+    return {
+        "uid": uid,
+        "response": ai_response,
+        "audio": audio_base64,
+        "timestamp": datetime.utcnow().isoformat(),
+    }
+
+
+@router.get("/session/{session_id}/{uid}/history", response_model=ChatHistoryResponse)
+async def get_chat_history(
+    uid: str, session: UserSession = Depends(get_session)
+) -> dict:
+    conversation = SessionService.get_conversation(session.session_id, uid)
+    if not conversation:
+        return {"uid": uid, "messages": []}
+
+    return {
+        "uid": uid,
+        "messages": [
+            {
+                "role": msg.role,
+                "content": msg.content,
+                "timestamp": msg.timestamp.isoformat(),
+            }
+            for msg in conversation.messages
+        ],
+    }
+
+
+@router.delete("/session/{session_id}")
+async def terminate_session(session: UserSession = Depends(get_session)) -> dict:
+    """Terminate a chat session and clean up resources"""
+    try:
+        SessionService.terminate_session(session.session_id)
+        return {
+            "message": "Session terminated successfully",
+            "session_id": session.session_id,
+            "terminated_at": datetime.utcnow().isoformat(),
+        }
+    except Exception as e:
+        raise HTTPException(
+            status_code=500, detail=f"Failed to terminate session: {str(e)}"
+        )

app/routes/generate.py

@@ -0,0 +1,69 @@
+from fastapi import APIRouter, HTTPException
+from app.services.generate_train.generate_train import GenerateTrainService
+from app.models.train import GenerateTrainResponse
+from app.utils.file_management import FileManager
+from app.core.logging import get_logger
+from app.services.session_service import SessionService
+import json 
+
+
+router = APIRouter(
+    prefix="/api/generate",
+    tags=["train-generation"]
+)
+
+logger = get_logger("generate")
+
+@router.get("/train/{session_id}/{number_of_wagons}/{theme}")
+async def get_generated_train(
+    session_id: str,
+    number_of_wagons: str,
+    theme: str
+):
+    """
+    Generate a new train with specified parameters for a session.
+    
+    - Validates the session exists
+    - Creates wagons with theme-appropriate passcodes
+    - Generates passengers with names and profiles
+    - Stores the generated data for the session
+    - Returns the complete train data structure
+    """
+    session = SessionService.get_session(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail="Session not found")
+
+    try:
+        number_of_wagons = int(number_of_wagons)
+    except ValueError:
+        raise HTTPException(status_code=400, detail="number_of_wagons must be an integer")
+
+    if number_of_wagons <= 0:
+        raise HTTPException(status_code=400, detail="number_of_wagons must be greater than 0")
+        
+    if number_of_wagons > 6:
+        raise HTTPException(status_code=400, detail="number_of_wagons cannot exceed 6")
+
+    try:
+        generate_train_service = GenerateTrainService()
+        names_data, player_details_data, wagons_data = generate_train_service.generate_train(theme, number_of_wagons)
+        
+        # Save the raw data
+        FileManager.save_session_data(session_id, names_data, player_details_data, wagons_data)
+
+        # Construct response with proper schema
+        response = {
+            "names": names_data,
+            "player_details": player_details_data,
+            "wagons": wagons_data
+        }
+
+        logger.info(f"Setting default_game to False | session_id={session_id}")
+        session.default_game = False 
+        SessionService.update_session(session)
+        return response
+        
+    except Exception as e:
+        logger.error(f"Failed to generate train for session {session_id}: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"Failed to generate train: {str(e)}")
+      

app/routes/health.py

@@ -0,0 +1,13 @@
+from fastapi import APIRouter, status
+
+router = APIRouter(
+    prefix="/health",
+    tags=["chat"]
+)
+
+@router.get("", status_code=status.HTTP_200_OK)
+async def health_check():
+    return {
+        "status": "healthy",
+        "message": "Service is running"
+    } 

app/routes/players.py

@@ -0,0 +1,207 @@
+from fastapi import APIRouter, HTTPException, Query
+from typing import List, Optional
+import json
+from pathlib import Path
+from app.core.logging import get_logger
+from app.services.session_service import SessionService
+from app.utils.file_management import FileManager
+
+router = APIRouter(tags=["players"])
+
+logger = get_logger("players")
+
+
+def load_json_file(file_path: str) -> dict:
+    try:
+        with open(file_path, "r") as f:
+            logger.debug(f"Loading JSON file: {file_path}")
+            return json.load(f)
+    except FileNotFoundError:
+        logger.error(f"File not found: {file_path}")
+        return {}
+    except json.JSONDecodeError as e:
+        logger.error(f"JSON decode error in {file_path}: {str(e)}")
+        return {}
+
+
+@router.get("/api/players/{session_id}/{wagon_id}/{player_id}")
+async def get_player_info(
+    session_id: str,
+    wagon_id: str,
+    player_id: str,
+    properties: Optional[List[str]] = Query(None, description="Filter specific properties")
+):
+    logger.info(
+        f"Getting player info | session_id: {session_id} | wagon_id: {wagon_id} | player_id: {player_id} | requested_properties: {properties}"
+    )
+    
+    try:
+        session = SessionService.get_session(session_id)
+        if not session:
+            logger.error(f"Session not found: {session_id}")
+            raise HTTPException(status_code=404, detail="Session not found")
+            
+        logger.debug(
+            f"Loading session data | session_id: {session_id} | default_game: {session.default_game}"
+        )
+        
+        # Load data based on default_game flag
+        names, player_details, _ = FileManager.load_session_data(session_id, session.default_game)
+        # try to convert the wagon_id to an integer if it is not already an integer 
+        try:
+            wagon_index = int(wagon_id.split("-")[1])
+        except ValueError:
+            logger.error(f"Invalid wagon_id: {wagon_id}")
+            raise HTTPException(status_code=404, detail="Invalid wagon_id")
+        
+        try:
+            # First check if player_details is contained in the loaded data
+            if  len(player_details) == 0:
+                logger.error("Missing 'player_details' key in loaded data")
+                raise HTTPException(status_code=404, detail="Player details not found")
+            
+            # players is a list of dictionaries, so we need to filter the list for the player_id    
+            player_info = next((player for player in player_details[wagon_index]["players"] if player["playerId"] == player_id), None)
+            # check if player_info is found
+            if player_info is None:
+                logger.error(f"Player info not found | wagon: {wagon_id} | player: {player_id}")
+                raise HTTPException(status_code=404, detail="Player info not found")
+            
+            logger.debug(
+                f"Found player info | wagon: {wagon_id} | player: {player_id} | profile_exists: {'profile' in player_info}"
+            )
+
+            # first check if names is contained in the loaded data
+            if len(names) == 0:
+                logger.error("Missing 'names' key in loaded data")
+                raise HTTPException(status_code=404, detail="Names not found")
+            
+            # "players" is a list of dictionaries, so we need to filter the list for the player_id  
+            name_info = next((player for player in names[wagon_index]["players"] if player["playerId"] == player_id), None)
+            # check if name_info is found
+            if name_info is None:
+                logger.error(f"Name info not found | wagon: {wagon_id} | player: {player_id}")
+                raise HTTPException(status_code=404, detail="Name info not found")
+            
+            logger.debug(
+                f"Found name info | wagon: {wagon_id} | player: {player_id}"
+            )
+            
+            # Combine information
+            player_in_current_wagon_info = {
+                "id": player_id,
+                "name_info": name_info,
+                "profile": player_info.get("profile", {})
+            }
+            
+            # Filter properties if specified
+            if properties:
+                logger.info(
+                    f"Filtering player info | requested_properties: {properties} | available_properties: {list(player_in_current_wagon_info.keys())}"
+                )
+            
+            logger.info("Successfully retrieved complete player info")
+            return player_in_current_wagon_info
+            
+        except KeyError as e:
+            logger.error(
+                f"Failed to find player data | error: {str(e)} | wagon_id: {wagon_id} | player_id: {player_id}"
+            )
+            raise HTTPException(status_code=404, detail="Player not found")
+            
+    except FileNotFoundError as e:
+        logger.error(
+            f"Failed to load session data | error: {str(e)} | session_id: {session_id}"
+        )
+        raise HTTPException(status_code=404, detail="Session not found")
+
+
+@router.get("/api/players/{session_id}/{wagon_id}")
+async def get_wagon_players(
+    session_id: str,
+    wagon_id: str,
+    properties: Optional[List[str]] = Query(
+        None,
+        description="Filter specific properties (name_info, profile, traits, inventory, dialogue)",
+    ),
+):
+    session = SessionService.get_session(session_id)
+    # check if session is found
+    if not session:
+        logger.error(f"Session not found: {session_id}")
+        raise HTTPException(status_code=404, detail="Session not found")
+    
+    logger.info(f"Getting all players for wagon_id={wagon_id} | session_id={session_id}")
+    if properties:
+        logger.info(f"Requested properties: {properties}")
+
+    logger.debug(
+        f"Loading session data | session_id={session_id} | default_game={session.default_game}"
+    )
+
+    # try catch for wagon_index
+    try:
+        wagon_index = int(wagon_id.split("-")[1])
+    except ValueError:
+        logger.error(f"Invalid wagon_id: {wagon_id}")
+        raise HTTPException(status_code=404, detail="Invalid wagon_id")
+
+    wagon_index = int(wagon_id.split("-")[1])
+    
+    try:
+        # Load data based on default_game flag
+        names, player_details, _ = FileManager.load_session_data(session_id, session.default_game)
+        
+        if len(player_details) == 0:
+            # check if player_details is contained in the loaded data
+            logger.error("player_details is empty")
+            raise HTTPException(status_code=404, detail="Player details not found")
+        
+        # Check if player details exists for the wagon_index
+        # should check whether None or empty list
+        if not player_details[wagon_index]["players"]:
+            logger.error(f"Player details not found for wagon_index={wagon_index}")
+            raise HTTPException(status_code=404, detail="Player details not found")
+            
+        players_in_current_wagon = player_details[wagon_index]["players"]
+        logger.debug(f"Found player info | wagon={wagon_id} | player_count={len(players_in_current_wagon)}")
+
+        # check if names is contained in the loaded data
+        if len(names) == 0:
+            logger.error("names is empty")
+            raise HTTPException(status_code=404, detail="Names not found")
+        
+        names_in_current_wagon = names[wagon_index]
+        logger.debug(f"Found name info | wagon={wagon_id} | name_count={len(names_in_current_wagon)}")
+        
+        # Create dictionaries for quick lookup by player ID
+        name_info = {
+            player["playerId"]: player 
+            for player in names_in_current_wagon["players"]
+        }
+        
+        player_info = {
+            player["playerId"]: player
+            for player in players_in_current_wagon
+        }
+
+        # Combine information for all players in the wagon
+        players_in_current_wagon_info = []
+        for player_id in player_info:
+            logger.debug(f"Processing player | wagon={wagon_id} | player={player_id}")
+            complete_info = {
+                "id": player_id,
+                "name_info": name_info.get(player_id, {}),
+                "profile": player_info[player_id].get("profile", {})
+            }
+            players_in_current_wagon_info.append(complete_info)
+
+        logger.info(f"Successfully retrieved all players | wagon={wagon_id} | player_count={len(players_in_current_wagon_info)}")
+        return {"players": players_in_current_wagon_info}
+            
+    except FileNotFoundError as e:
+        logger.error(f"Failed to load session data | error={str(e)} | session_id={session_id}")
+        raise HTTPException(status_code=404, detail="Session data not found")
+    except Exception as e:
+        logger.error(f"Unexpected error | error={str(e)} | wagon_id={wagon_id}")
+        raise HTTPException(status_code=500, detail="Internal server error")

app/routes/wagons.py

@@ -0,0 +1,25 @@
+from fastapi import APIRouter, HTTPException
+from pathlib import Path
+import json
+from app.services.session_service import SessionService
+from app.utils.file_management import FileManager
+
+router = APIRouter(
+    prefix="/api/wagons",
+    tags=["wagons"]
+)
+
+@router.get("/{session_id}")
+async def get_wagons(session_id: str):
+    session = SessionService.get_session(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail="Session not found")
+    
+    try:
+        # Use default_game flag from session to determine data source
+        wagons_data = FileManager.load_session_data(session_id, session.default_game)[2]
+        return wagons_data
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Error reading wagons data: {str(e)}") 

app/services/chat_service.py

@@ -0,0 +1,174 @@
+from app.models.session import Conversation
+from app.core.logging import LoggerMixin
+from pathlib import Path
+import json
+from typing import Optional, Dict
+import os
+from mistralai import Mistral
+from app.utils.file_management import FileManager
+from app.models.session import UserSession
+
+
+# Get the Mistral API key from environment (injected by ECS)
+mistral_api_key = os.getenv("MISTRAL_API_KEY")
+
+
+class ChatService(LoggerMixin):
+    def __init__(self, session: UserSession):
+        self.logger.info("Initializing ChatService")
+        # Load all available character in every wagon. 
+        self.player_details: Dict = self._load_player_details(session)
+
+        if len(self.player_details) == 0:
+            self.logger.error("Failed to initialize player details - array is empty")
+        else:
+            self.logger.info(f"Loaded player details for wagons: {list(self.player_details)}")
+
+        # Get the Mistral API key from environment (injected by ECS)
+        mistral_api_key = os.getenv("MISTRAL_API_KEY")
+        if not mistral_api_key:
+            self.logger.error("MISTRAL_API_KEY not found in environment variables")
+            raise ValueError("MISTRAL_API_KEY is required")
+
+        self.client = Mistral(api_key=mistral_api_key)
+        self.model = "mistral-large-latest"
+
+        self.logger.info("Initialized Mistral AI client")
+
+    @classmethod
+    def _load_player_details(cls, session) -> Dict:
+        """Load character details from JSON files"""
+        try:
+            # Use FileManager to load the default session data
+            _, player_details, _ = FileManager.load_session_data(session.session_id, session.default_game)
+            
+            if len(player_details) == 0:
+                cls.get_logger().error("Missing 'player_details' key in JSON data")
+                return {}
+            
+            # success for loading player_details
+            cls.get_logger().info(f"Successfully loaded player details.: {list(player_details)}")
+            return player_details
+        
+        except FileNotFoundError as e:
+            cls.get_logger().error(f"Failed to load default player details: {str(e)}")
+            return {}
+        except Exception as e:
+            cls.get_logger().error(f"Failed to load player details: {str(e)}")
+            return {}
+
+    def _get_character_context(self, uid: str) -> Optional[Dict]:
+        """Get the character's context for the conversation"""
+        try:
+            self.logger.debug(f"Getting character context for uid: {uid}")
+            # "wagon-<i>-player-<k>"
+            uid_splitted = uid.split("-")
+            # try catch for wagon_index 
+            try:
+                wagon_index = int(uid_splitted[1])
+            except ValueError:
+                self.logger.error(f"Invalid wagon index | uid: {uid} | wagon_index: {uid_splitted[1]}")
+                return None
+            
+            wagon_key, player_key = (
+                f"wagon-{wagon_index}",
+                f"player-{uid_splitted[3]}",
+            )
+
+            # check if the wagon key exists
+            if len(self.player_details) == 0:
+                self.logger.error("Wagon not found in player details")
+                return None
+
+            # find specific player details
+            specific_player_detais = next((player for player in self.player_details[wagon_index]["players"] if player["playerId"] == player_key), None)
+
+            self.logger.debug(
+                f"Retrieved player context | uid: {uid} | wagon: {wagon_key} | player: {player_key} | profession: {specific_player_detais['profile']['profession']}"
+            )
+            return specific_player_detais
+        except (KeyError, IndexError) as e:
+            self.logger.error(f"Failed to get character context: {str(e)} | uid: {uid} | error: {str(e)} | player_details_keys: {list(self.player_details) if self.player_details else None}")
+            return None
+
+    def _create_character_prompt(self, theme: str, character: Dict) -> str:
+        """Create a prompt that describes the character's personality and context"""
+        occupation = character["profile"]["profession"]
+        personality = character["profile"]["personality"]
+        role = character["profile"]["role"]
+        mystery = character["profile"]["mystery_intrigue"]
+        name = character["profile"]["name"]
+
+        prompt = f"""
+        You are an NPC in a fictional world set in the theme of {theme}. You are part of this theme's story and lore.
+        Your name is {name}, and you are a {occupation}.
+        Your role in the story is {role}, and you have a mysterious secret tied to you: {mystery}. Your personality is {personality}, 
+        which influences how you speak, act, and interact with others. Stay in character at all times, 
+        and respond to the player based on your occupation, role, mystery, and personality.
+
+        You may only reveal your mystery if the player explicitly asks about it or asks about something closely related to it. 
+        For example, if your mystery involves a hidden treasure, and the player asks about rumors of gold in the area, you may
+        hint at or reveal your secret. However, you should still respond in a way that feels natural to your character.
+        Do not break character or reveal your mystery too easily—only share it if it makes sense in the context of the conversation 
+        and your personality.
+
+        Respond in maximum 3-4 sentences per message to keep the conversation flowing and engaing for the player.
+        """
+
+        return prompt
+
+    def generate_response(self, uid: str, theme: str, conversation: Conversation) -> Optional[str]:
+        """Generate a response using Mistral AI based on character profile"""
+        self.logger.info(f"Generating response for uid: {uid}")
+        character = self._get_character_context(uid)
+
+        if not character:
+            self.logger.error(
+                f"Cannot generate response - character not found for uid: {uid}"
+            )
+            return None
+
+        try:
+            # Create the system prompt with character context
+            system_prompt = self._create_character_prompt(theme, character)
+
+            # Convert conversation history to Mistral AI format
+            messages = [{"role": "system", "content": system_prompt}]
+
+            # Add conversation history (limit to last 10 messages to stay within context window)
+            for msg in conversation.messages[-10:]:
+                # Convert 'agent' role to 'assistant' for Mistral compatibility
+                role = "assistant" if msg.role == "agent" else msg.role
+                messages.append({"role": role, "content": msg.content})
+
+            # Get response from Mistral AI
+            try:
+                chat_response = self.client.chat.complete(
+                    model=self.model, messages=messages, temperature=0.7, max_tokens=500
+                )
+
+                if not chat_response or not chat_response.choices:
+                    raise ValueError("Empty response received from Mistral AI")
+
+                response = chat_response.choices[0].message.content
+
+                if not response or not isinstance(response, str):
+                    raise ValueError(f"Invalid response format: {type(response)}")
+
+                self.logger.info(
+                    f"Generated Mistral AI response | uid: {uid} | response_length: {len(response)} | conversation_length: {len(conversation.messages)}"
+                )
+
+                return response
+
+            except Exception as api_error:
+                self.logger.error(
+                    f"Mistral API error | uid: {uid} | error: {str(api_error)} | messages_count: {len(messages)}"
+                )
+                raise ValueError(f"Mistral API error: {str(api_error)}")
+
+        except Exception as e:
+            self.logger.error(
+                f"Failed to generate Mistral AI response | uid: {uid} | error: {str(e)} | error_type: {type(e).__name__} | character_name: {character.get('profile', {}).get('name', 'unknown')}"
+            )
+            return f"I apologize, but I'm having trouble responding right now. Error: {str(e)}"

app/services/generate_train/convert.py

@@ -0,0 +1,168 @@
+from typing import Dict, List, Tuple
+import random
+from app.core.logging import get_logger
+
+logger = get_logger("convert")
+
+def parse_name(full_name):
+    """
+    Splits the full name into firstName and lastName.
+    This is a simple heuristic:
+       - lastName is the last token
+       - firstName is everything before
+    For example:
+       "Dr. Amelia Hartford" -> firstName: "Dr. Amelia", lastName: "Hartford"
+       "Thomas Maxwell" -> firstName: "Thomas", lastName: "Maxwell"
+    Adjust this to your own naming conventions if needed.
+    """
+    tokens = full_name.strip().split()
+    if len(tokens) == 1:
+        return full_name, ""  # No clear lastName
+    else:
+        return " ".join(tokens[:-1]), tokens[-1]
+
+def infer_sex_from_model(model_type):
+    """
+    A simple inference: if the string 'female' is in model_type, mark sex as 'female';
+    if 'male' is in model_type, mark as 'male';
+    otherwise, mark as 'unknown' (or handle however you prefer).
+    """
+    model_type_lower = model_type.lower()
+    if 'female' in model_type_lower:
+        return 'female'
+    elif 'male' in model_type_lower:
+        return 'male'
+    else:
+        return 'unknown'
+
+# triggered for one single wagon 
+def convert_wagon_to_three_jsons(wagon_data: Dict) -> Tuple[Dict, Dict, Dict]:
+    """
+    Given a single wagon JSON structure like:
+    {
+      "id": 1,
+      "theme": "Alien by Ridley Scott",
+      "passcode": "Nostromo",
+      "passengers": [
+        {
+          "name": "Dr. Amelia Hartford",
+          "age": 47,
+          "profession": "Medical Researcher",
+          "personality": "Analytical, compassionate, and meticulous",
+          "role": "...",
+          "mystery_intrigue": "...",
+          "characer_model": "character-female-e"
+        },
+        ...
+      ]
+    }
+    produce:
+      1) names_json
+      2) player_details_json
+      3) wagons_json
+    """
+    wagon_id = wagon_data.get("id", 0)
+    theme = wagon_data.get("theme", "Unknown Theme")
+    passcode = wagon_data.get("passcode", "no-passcode")
+    passengers = wagon_data.get("passengers", [])
+
+    logger.debug(f"Processing wagon conversion | wagon_id={wagon_id} | theme={theme} | num_passengers={len(passengers)}")
+
+    try:
+        # 1) Build the "names" object for this wagon
+        names_entry = {
+            "wagonId": f"wagon-{wagon_id}",
+            "players": []
+        }
+
+        # 2) Build the "player_details" object for this wagon
+        player_details_entry = {
+            "wagonId": f"wagon-{wagon_id}",
+            "players": []
+        }
+
+        # 3) Build the "wagon" object
+        wagon_entry = {
+            "id": wagon_id,
+            "theme": theme,
+            "passcode": passcode,
+            "people": []
+        }
+
+        # Process each passenger
+        for i, passenger in enumerate(passengers, 1):
+            logger.debug(f"Converting passenger data | wagon_id={wagon_id} | passenger_index={i} | passenger_name={passenger.get('name', 'Unknown')}")
+            
+            player_key = f"player-{i}"
+            name = passenger.get("name", "")
+            
+            # Split name into components
+            name_parts = name.split()
+            first_name = name_parts[0] if name_parts else ""
+            last_name = " ".join(name_parts[1:]) if len(name_parts) > 1 else ""
+            
+            # Determine sex based on character model
+            model_type = passenger.get("characer_model", "character-male-a")
+            sex = "female" if "female" in model_type else "male"
+
+            # Add to names structure
+            names_entry["players"].append({
+                "playerId": player_key,
+                "firstName": first_name,
+                "lastName": last_name,
+                "sex": sex,
+                "fullName": name
+            })
+
+            # Add to player_details structure
+            profile = {
+                "name": name,
+                "age": passenger.get("age", 0),
+                "profession": passenger.get("profession", ""),
+                "personality": passenger.get("personality", ""),
+                "role": passenger.get("role", ""),
+                "mystery_intrigue": passenger.get("mystery_intrigue", "")
+            }
+            player_details_entry["players"].append({"playerId": player_key, "profile": profile})
+
+            # Add to wagon people structure
+            person_dict = {
+                "uid": f"wagon-{wagon_id}-player-{i}",
+                "position": [round(random.random(), 2), round(random.random(), 2)],
+                "rotation": round(random.random(), 2),
+                "model_type": model_type,
+                "items": []
+            }
+            wagon_entry["people"].append(person_dict)
+
+        logger.debug(f"Completed wagon conversion | wagon_id={wagon_id} | players_processed={len(passengers)}")
+        return names_entry, player_details_entry, wagon_entry
+
+    except Exception as e:
+        logger.error(f"Error converting wagon | wagon_id={wagon_id} | error_type={type(e).__name__} | error_msg={str(e)}")
+        raise
+
+def convert_and_return_jsons(wagons_data: List[Dict]) -> Tuple[Dict, Dict, Dict]:
+    """Convert raw wagon data into the three required JSON structures"""
+    logger.info(f"Starting conversion of wagon data | total_wagons={len(wagons_data)}")
+    
+    all_names = []
+    all_player_details = []
+    all_wagons = []
+
+    try:
+        for wagon in wagons_data:
+            logger.debug(f"Converting wagon | wagon_id={wagon['id']} | theme={wagon['theme']} | num_passengers={len(wagon.get('passengers', []))}")
+            
+            names, player_details, wagon_entry = convert_wagon_to_three_jsons(wagon)
+            
+            all_names.append(names)
+            all_player_details.append(player_details)
+            all_wagons.append(wagon_entry)
+
+        logger.info(f"Successfully converted all wagons | total_names={len(all_names)} | total_player_details={len(all_player_details)} | total_wagons={len(all_wagons)}")
+        return all_names, all_player_details, all_wagons
+
+    except Exception as e:
+        logger.error(f"Error converting wagon data | error_type={type(e).__name__} | error_msg={str(e)}")
+        raise

app/services/generate_train/generate_train.py

@@ -0,0 +1,241 @@
+from mistralai import Mistral
+import os
+import json
+import random
+from fastapi import HTTPException
+from typing import Tuple, Dict, Any, List
+from app.core.logging import LoggerMixin
+from app.services.generate_train.convert import convert_and_return_jsons
+
+
+class GenerateTrainService(LoggerMixin):
+    def __init__(self):
+        self.logger.info("Initializing GenerateTrainService")
+        
+        # Get the Mistral API key from the .env file
+        self.api_key = os.getenv("MISTRAL_API_KEY")
+        
+        if not self.api_key:
+            self.logger.error("MISTRAL_API_KEY is not set in the .env file")
+            raise ValueError("MISTRAL_API_KEY is not set in the .env file")
+
+        # Initialize the Mistral client
+        self.client = Mistral(api_key=self.api_key)
+        self.logger.info("Mistral client initialized successfully")
+
+    def generate_wagon_passcodes(self, theme: str, num_wagons: int) -> list[str]:
+        """Generate passcodes for wagons using Mistral AI"""
+        self.logger.info(f"Generating passcodes for theme: {theme}, num_wagons: {num_wagons}")
+        
+        if num_wagons <= 0 or num_wagons > 10:
+            self.logger.error(f"Invalid number of wagons requested: {num_wagons}")
+            return "Please provide a valid number of wagons (1-10)."
+
+        # Prompt Mistral API to generate a theme and passcodes
+        prompt = f"""
+        This is a video game about a player trying to reach the locomotive of a train by finding a passcode for each wagon.
+        You are tasked with generating unique passcodes for the wagons based on the theme '{theme}', to make the game more engaging, fun, and with a sense of progression.
+        You are tasked with generating unique passcodes for the wagons based on the theme '{theme}', 
+        to make the game more engaging, fun, and with a sense of progression, from easiest to hardest.
+        Each password should be unique enough to not be related to each other but still be connected to the theme.
+        Generate {num_wagons} unique and creative passcodes for the wagons. Each passcode must:
+        Generate exactly {num_wagons} unique and creative passcodes for the wagons. Each passcode must:
+        1. Be related to the theme.
+        2. Be unique, interesting, and creative.
+        3. In one word, letters only (no spaces or special characters).
+        No explanation needed, just the theme and passcodes in a JSON object format.
+        Example:
+        Example for the theme "Pirates" and 5 passcodes:
+        {{
+            "theme": "Pirates",
+            "passcodes": ["Treasure", "Rum", "Skull", "Compass", "Anchor"]
+        }}
+        Now, generate a theme and passcodes.
+        """
+        response = self.client.chat.complete(
+            model="mistral-large-latest",
+            messages=[
+                {"role": "user", "content": prompt}
+            ],
+            max_tokens=1000,
+            temperature=0.8,
+        )
+
+        try:
+            result = json.loads(response.choices[0].message.content.replace("```json\n", "").replace("\n```", ""))
+            passcodes = result["passcodes"]
+            self.logger.info(f"Successfully generated {len(passcodes)} passcodes")
+            return passcodes
+
+        except json.JSONDecodeError as e:
+            self.logger.error(f"Failed to decode Mistral response: {e}")
+            return "Failed to decode the response. Please try again."
+        except Exception as e:
+            self.logger.error(f"Error generating passcodes: {e}")
+            return f"Error generating passcodes: {str(e)}"
+
+    def generate_passengers_for_wagon(self, theme: str, passcode: str, num_passengers: int) -> list[Dict[str, Any]]:
+        """Generate passengers for a wagon using Mistral AI"""
+        self.logger.info(f"Generating {num_passengers} passengers for wagon with passcode: {passcode} and theme: {theme}")
+
+         # Generate passengers with the Mistral API
+        prompt = f"""
+        Passengers are in a wagon. The player can interact with them to learn more about their stories.
+        The passengers live in the world of the theme "{theme}" and their stories are connected to the passcode "{passcode}".
+        The following is a list of passengers on a train wagon. The wagon is protected by the passcode "{passcode}".
+        Their stories are intertwined, and each passenger has a unique role and mystery, all related to the theme and the passcode.
+        The player must be able to guess the passcode by talking to the passengers and uncovering their secrets.
+        Passengers should be diverse, with different backgrounds, professions, and motives.
+        Passengers' stories should be engaging, mysterious, and intriguing, adding depth to the game, while also providing clues to the passcode.
+        Passengers' stories has to be / can be connected to each other.
+        Passengers are aware of each other's presence in the wagon.
+        The passcode shouldn't be too obvious but should be guessable based on the passengers' stories.
+        The passcode shouldn't be mentioned explicitly in the passengers' descriptions.
+        Don't use double quotes (") in the JSON strings.
+        Each passenger must have the following attributes:
+        - "name": A unique name (first and last) with a possible title.
+        - "age": A realistic age between 18 and 70 except for special cases.
+        - "profession": A profession that fits into a fictional, story-driven world.
+        - "personality": A set of three adjectives that describe their character.
+        - "role": A short description of their role in the story.
+        - "mystery_intrigue": A unique secret, motive, or mystery about the character.
+        - "characer_model": A character model identifier
+        The character models are :
+        - character-female-a: A dark-skinned woman with a high bun hairstyle, wearing a purple and orange outfit. She is holding two blue weapons or tools, possibly a warrior or fighter.
+        - character-female-b: A young girl with orange hair tied into two pigtails, wearing a yellow and purple sporty outfit. She looks energetic, possibly an athlete or fitness enthusiast.
+        - character-female-c: An elderly woman with gray hair in a bun, wearing a blue and red dress. She has a warm and wise appearance, resembling a grandmotherly figure.
+        - character-female-d: A woman with blonde hair styled in a tight bun, wearing a gray business suit. She appears professional, possibly a corporate worker or manager.
+        - character-female-e: A woman with dark hair in a ponytail, dressed in a white lab coat with blue gloves. She likely represents a doctor or scientist.
+        - character-female-f: A red-haired woman with long, wavy hair, wearing a black and yellow vest with purple pants. She looks adventurous, possibly an engineer, explorer, or worker.
+        - character-male-a: Dark-skinned man with glasses and a beaded hairstyle, wearing a green shirt with orange and white stripes, along with yellow sneakers (casual or scholarly figure).
+        - character-male-b: Bald man with a large red beard, wearing a red shirt and blue pants (possibly a strong worker, blacksmith, or adventurer).
+        - character-male-c: Man with a mustache, wearing a blue police uniform with a cap and badge (police officer or security personnel).
+        - character-male-d: Blonde-haired man in a black suit with a red tie (businessman, politician, or corporate executive).
+        - character-male-e: Brown-haired man with glasses, wearing a white lab coat and a yellow tool belt (scientist, mechanic, or engineer).
+        - character-male-f: Dark-haired young man with a mustache, wearing a green vest and brown pants (possibly an explorer, traveler, or adventurer).
+        Generate {num_passengers} passengers in JSON array format. Example:
+        [
+            {{
+                "name": "Victor Sterling",
+                "age": 55,
+                "profession": "Mining Magnate",
+                "personality": "Ambitious, cunning, and charismatic",
+                "role": "Owns a vast mining empire, recently discovered a new vein of precious metal.",
+                "mystery_intrigue": "Secretly trades in unregistered precious metals, hiding a fortune in a secure vault. In love with Eleanor Brooks",
+                "characer_model": "character-male-f"
+            }},
+            {{
+                "name": "Eleanor Brooks",
+                "age": 32,
+                "profession": "Investigative Journalist",
+                "personality": "Tenacious, curious, and ethical",
+                "role": "Investigates corruption in the mining industry, follows a lead on a hidden stash of radiant metal bars.",
+                "mystery_intrigue": "Uncovers a network of illegal precious metal trades, putting her life in danger. Hates Victor Sterling because of his unethical practices.",
+                "characer_model": "character-female-f"
+            }}
+        ]
+        Now generate the JSON array:
+        """
+        response = self.client.chat.complete(
+            model="mistral-large-latest",
+            messages=[
+                {"role": "user", "content": prompt}
+            ],
+            max_tokens=1250,
+            temperature=0.7,
+        )
+
+
+        try:
+            passengers = json.loads(response.choices[0].message.content.replace("```json\n", "").replace("\n```", "").replace(passcode, "<redacted>"))
+            self.logger.info(f"Successfully generated {len(passengers)} passengers")
+            return passengers
+
+        except json.JSONDecodeError as e:
+            self.logger.error(f"Failed to decode passenger generation response: {e}")
+            return "Failed to decode the response. Please try again."
+        except Exception as e:
+            self.logger.error(f"Error generating passengers: {e}")
+            return f"Error generating passengers: {str(e)}"
+
+    def generate_train_json(self, theme: str, num_wagons: int, min_passengers: int = 2, max_passengers: int = 10) -> str:
+        """Generate complete train JSON including wagons and passengers"""
+        self.logger.info(f"Generating train JSON for theme: {theme}, num_wagons: {num_wagons}")
+
+        try:
+            if min_passengers > max_passengers:
+                self.logger.error("Minimum passengers cannot be greater than maximum passengers")
+                raise ValueError("Minimum passengers cannot be greater than maximum passengers")
+
+            # Generate passcodes
+            passcodes = self.generate_wagon_passcodes(theme, num_wagons)
+            if isinstance(passcodes, str):  # If there's an error message
+                self.logger.error(f"Error generating passcodes: {passcodes}")
+                raise ValueError(f"Failed to generate passcodes: {passcodes}")
+            
+            # Generate wagons with passengers
+            wagons = []
+            wagons.append({
+            "id": 0,
+            "theme": "Tutorial (Start)",
+            "passcode": "start",
+            "passengers": []
+            })
+            for i, passcode in enumerate(passcodes):
+                num_passengers = random.randint(min_passengers, max_passengers)
+                passengers = self.generate_passengers_for_wagon(theme, passcode, num_passengers)
+                  # Check if passengers is a string (error message)
+                if isinstance(passengers, str):
+                    self.logger.error(f"Error generating passengers: {passengers}")
+                    raise ValueError(f"Failed to generate passengers: {passengers}")
+                wagons.append({"id": i + 1, "theme": theme, "passcode": passcode, "passengers": passengers})
+
+            self.logger.info(f"Successfully generated train with {len(wagons)} wagons")
+            return json.dumps(wagons, indent=4)
+
+        except Exception as e:
+            self.logger.error(f"Error in generate_train_json: {e}")
+            raise ValueError(f"Failed to generate train: {str(e)}")
+
+    def generate_train(self, theme: str, num_wagons: int) -> Tuple[List, List, List]:
+        """Main method to generate complete train data"""
+        self.logger.info(f"Starting train generation | theme={theme} | num_wagons={num_wagons} | service=GenerateTrainService")
+        
+        try:
+            # Log attempt to generate train JSON
+            self.logger.debug(f"Generating train JSON | theme={theme} | num_wagons={num_wagons} | min_passengers=2 | max_passengers=10")
+            
+            wagons_json = self.generate_train_json(theme, num_wagons, 2, 10)
+            
+            # Log successful JSON generation and parse attempt
+            self.logger.debug(f"Train JSON generated, parsing to dict | json_length={len(wagons_json)}")
+            
+            wagons = json.loads(wagons_json)
+            
+            # Log conversion attempt
+            self.logger.debug(f"Converting wagon data to final format | num_wagons={len(wagons)}")
+            
+            all_names, all_player_details, all_wagons = convert_and_return_jsons(wagons)
+            
+            # Log successful generation with summary
+            self.logger.info(
+                f"Train generation completed successfully | theme={theme} | "
+                f"total_wagons={len(all_wagons)} | total_names={len(all_names)} | "
+                f"total_player_details={len(all_player_details)}"
+            )
+            
+            return all_names, all_player_details, all_wagons
+
+        except json.JSONDecodeError as e:
+            self.logger.error(
+                f"JSON parsing error in generate_train | error_type=JSONDecodeError | "
+                f"error_msg={str(e)} | theme={theme} | num_wagons={num_wagons}"
+            )
+            raise HTTPException(status_code=500, detail=f"Failed to parse train JSON: {str(e)}")
+        
+        except Exception as e:
+            self.logger.error(
+                f"Error in generate_train | error_type={type(e).__name__} | "
+                f"error_msg={str(e)} | theme={theme} | num_wagons={num_wagons}"
+            )
+            raise HTTPException(status_code=500, detail=f"Failed to generate train: {str(e)}")

app/services/guess_service.py

@@ -0,0 +1,70 @@
+import os
+from langchain_mistralai import ChatMistralAI
+from langchain_core.prompts import PromptTemplate
+from pydantic import BaseModel, Field
+from app.models.session import Message
+from app.core.logging import LoggerMixin
+from app.prompts import GUESSING_PROMPT
+
+MISTRAL_API_KEY = os.getenv("MISTRAL_API_KEY")
+
+
+class GuessResponse(BaseModel):
+    guess: str = Field(description="A one-word guess for the password related theme")
+    thoughts: str = Field(
+        description="Thoughts spoken out loud leading to the password guess"
+    )
+
+
+class GuessingService(LoggerMixin):
+    def __init__(self: "GuessingService") -> None:
+        self.logger.info("Initializing GuessingService")
+        prompt = PromptTemplate.from_template(GUESSING_PROMPT)
+
+        llm = (
+            ChatMistralAI(
+                model_name="mistral-large-latest",
+                temperature=1,
+            )
+            .with_structured_output(schema=GuessResponse)
+            .with_retry(stop_after_attempt=3)
+        )
+
+        self.chain = prompt | llm
+        self.logger.info("GuessingService initialized with Mistral LLM")
+
+    def filter_password(self: "GuessingService", indication: str, password: str) -> str:
+        filtered = indication.replace(password, "*******")
+        self.logger.debug(f"Filtered password from indication | original_length={len(indication)} | filtered_length={len(filtered)}")
+        return filtered
+
+    def generate(
+        self: "GuessingService",
+        previous_guesses: list[str],
+        theme: str,
+        previous_indications: list[Message],
+        current_indication: str,
+        password: str,
+    ) -> GuessResponse:
+        self.logger.info(f"Generating guess | theme={theme} | num_previous_guesses={len(previous_guesses)} | num_previous_indications={len(previous_indications)}")
+        
+        previous_indications = [message.content for message in previous_indications]
+        self.logger.debug(f"Processing previous indications | count={len(previous_indications)}")
+
+        current_indication = self.filter_password(current_indication, password)
+        
+        try:
+            response = self.chain.invoke(
+                {
+                    "previous_guesses": previous_guesses[:3],
+                    "theme": theme,
+                    "previous_indications": previous_indications[:5],
+                    "current_indication": current_indication,
+                }
+            )
+            self.logger.info(f"Generated guess successfully | guess={response.guess} | thoughts_length={len(response.thoughts)}")
+            return response
+            
+        except Exception as e:
+            self.logger.error(f"Failed to generate guess | error={str(e)} | theme={theme}")
+            raise

app/services/scoring_service.py

@@ -0,0 +1,51 @@
+from mistralai import Mistral
+import os
+import orjson
+import time
+
+MISTRAL_API_KEY = os.getenv("MISTRAL_API_KEY")
+
+
+class ScoringService:
+    def __init__(self: "ScoringService"):
+        self.client = Mistral(api_key=MISTRAL_API_KEY)
+        self.model = "mistral-small-2409"
+        self.max_retries = 3
+
+    def is_similar(
+        self: "ScoringService", password: str, guess: str, theme: str
+    ) -> bool:
+        messages = [
+            {
+                "role": "system",
+                "content": """
+                Return a similarity score between the two given words, relatively to a theme. Return the score in the range [0, 1] in a JSON format with the key 'score'
+                """,
+            },
+            {
+                "role": "user",
+                "content": f"Answer: {password}\nGuess: {guess}\nTheme: {theme}",
+            },
+        ]
+
+        for attempt in range(self.max_retries):
+            try:
+                response = self.client.chat.complete(
+                    model=self.model,
+                    messages=messages,
+                    temperature=0.0,
+                    response_format={
+                        "type": "json_object",
+                    },
+                )
+
+                # Parse the response with orjson
+                parsed_response = orjson.loads(response.choices[0].message.content)
+                return parsed_response["score"]
+            except orjson.JSONDecodeError as e:
+                if attempt < self.max_retries - 1:
+                    time.sleep(1)
+                else:
+                    raise e
+
+        return 0.5

app/services/session_service.py

@@ -0,0 +1,273 @@
+from datetime import datetime
+from typing import Dict, Optional
+from app.models.session import (
+    UserSession,
+    WagonProgress,
+    Conversation,
+    Message,
+    GuessingProgress,
+)
+from app.core.logging import LoggerMixin
+import uuid
+from app.utils.file_management import FileManager
+
+
+# used as dependency injection for the session service
+class SessionService(LoggerMixin):
+    # dictionary to store all the sessions
+    _sessions: Dict[str, UserSession] = {}
+
+    @classmethod
+    def create_session(cls) -> UserSession:
+        """Create a new session"""
+        session_id = str(uuid.uuid4())
+        
+        session = UserSession(
+            session_id=session_id,
+            created_at=datetime.utcnow(),
+            last_active=datetime.utcnow(),
+            default_game=True
+        )
+        
+        cls._sessions[session_id] = session
+        cls.get_logger().info(f"Created new session: {session_id}")
+        return session
+
+    @classmethod
+    def get_session(cls, session_id: str) -> Optional[UserSession]:
+        """Get session by ID"""
+        session = cls._sessions.get(session_id)
+        if session:
+            session.last_active = datetime.utcnow()
+            cls.get_logger().debug(f"Retrieved session: {session_id}")
+        else:
+            cls.get_logger().warning(f"Session not found: {session_id}")
+        return session
+
+    @classmethod
+    def update_session(cls, session: UserSession) -> None:
+        """Update a session's last active timestamp"""
+        session.last_active = datetime.utcnow()
+        cls._sessions[session.session_id] = session
+        cls.get_logger().debug(
+            f"Updated session | session_id: {session.session_id} | current_wagon: {session.current_wagon.wagon_id}"
+        )
+
+    @classmethod
+    def add_message(
+        cls, session_id: str, uid: str, message: Message
+    ) -> Optional[Conversation]:
+        """Add a message to a character's conversation"""
+        session = cls.get_session(session_id)
+        if not session:
+            cls.get_logger().error(
+                f"Failed to add message - session not found | session_id: {session_id} | uid: {uid}"
+            )
+            return None
+
+        # get the wagon id from the uid
+        # uuid is in the format of wagon-<i>-player-<k>
+        wagon_id = int(uid.split("-")[1])
+        # check if the wagon id is the same as the current wagon id
+        # if the wagon id is not the same, client is trying to access a different wagon
+        # which might indicate out of sync in wagon.
+        if wagon_id != session.current_wagon.wagon_id:
+            cls.get_logger().error(
+                f"Cannot add message - wrong wagon | session_id: {session_id} | uid: {uid} | current_wagon: {session.current_wagon.wagon_id}"
+            )
+            return None
+
+        # in case we have not started a conversation with this character yet, start one
+        if uid not in session.current_wagon.conversations:
+            cls.get_logger().info(
+                f"Starting new conversation | session_id: {session_id} | uid: {uid} | wagon_id: {wagon_id}"
+            )
+            session.current_wagon.conversations[uid] = Conversation(uid=uid)
+
+        # add the message of the client to the conversation with the new player
+        conversation = session.current_wagon.conversations[uid]
+        conversation.messages.append(message)
+        conversation.last_interaction = datetime.utcnow()
+
+        cls.update_session(session)
+        cls.get_logger().debug(
+            f"Added message to conversation | session_id: {session_id} | uid: {uid} | message_role: {message.role} | message_length: {len(message.content)}"
+        )
+        return conversation
+
+    @classmethod
+    def get_conversation(cls, session_id: str, uid: str) -> Optional[Conversation]:
+        """Get a conversation with a specific character"""
+        session = cls.get_session(session_id)
+        if not session:
+            cls.get_logger().error(
+                f"Failed to get conversation - session not found | session_id: {session_id} | uid: {uid}"
+            )
+            return None
+
+        # get the wagon id from the uid
+        # uuid is in the format of wagon-<i>-player-<k>
+
+        wagon_id = int(uid.split("-")[1])
+        # check if the wagon id is the same as the current wagon id
+        # if the wagon id is not the same, client is trying to access a different wagon
+        # which might indicate out of sync in wagon.
+        if wagon_id != session.current_wagon.wagon_id:
+            cls.get_logger().warning(
+                f"Cannot get conversation - wrong wagon | session_id: {session_id} | uid: {uid} | current_wagon: {session.current_wagon.wagon_id}"
+            )
+            return None
+
+        # get the conversation from the current wagon
+        conversation = session.current_wagon.conversations.get(uid)
+
+        if conversation:
+            cls.get_logger().debug(
+                f"Retrieved conversation | session_id: {session_id} | uid: {uid} | message_count: {len(conversation.messages)}"
+            )
+        else:
+            cls.get_logger().debug(
+                f"No conversation found | session_id: {session_id} | uid: {uid}"
+            )
+        return conversation
+
+    @classmethod
+    def get_guessing_progress(cls, session_id: str) -> GuessingProgress:
+        session = cls.get_session(session_id)
+        if not session:
+            cls.get_logger().error(
+                f"Failed to get guesses - session not found | session_id: {session_id}"
+            )
+            return None
+        return session.guessing_progress
+
+    @classmethod
+    def update_guessing_progress(
+        cls, session_id: str, indication: str, guess: str, thought: list[str]
+    ) -> None:
+        session = cls.get_session(session_id)
+        if not session:
+            cls.get_logger().error(
+                f"Failed to get the guessing progress - session not found | session_id: {session_id}"
+            )
+            return
+
+        session.guessing_progress.guesses.append(guess)
+        session.guessing_progress.indications.append(
+            Message(
+                role="user",
+                content=indication,
+            )
+        )
+
+        wagon_id = session.current_wagon.wagon_id
+
+        if (
+            session.current_wagon.conversations.get(f"wagon-{wagon_id}-player-0")
+            is None
+        ):
+            session.current_wagon.conversations[f"wagon-{wagon_id}-player-0"] = (
+                Conversation(uid="player-0")
+            )
+
+        messages = session.current_wagon.conversations.get(
+            f"wagon-{wagon_id}-player-0"
+        ).messages
+
+        messages.append(Message(role="user", content=indication))
+        messages.append(Message(role="assistant", content=thought[0]))
+
+        cls.update_session(session)
+        cls.get_logger().info(f"Added a new guess | session_id: {session_id}")
+
+    @classmethod
+    def advance_wagon(cls, session_id: str) -> bool:
+        """Advance to the next wagon"""
+        cls.get_logger().info(f"Attempting to advance wagon | session_id={session_id}")
+        
+        # Get current session
+        session = cls.get_session(session_id)
+        if not session:
+            cls.get_logger().error(f"Failed to advance wagon - session not found | session_id={session_id}")
+            return False
+
+        current_wagon_id = session.current_wagon.wagon_id
+        cls.get_logger().debug(f"Current wagon state | session_id={session_id} | current_wagon_id={current_wagon_id}")
+
+        try: 
+            # Load data based on default_game flag
+            cls.get_logger().debug(f"Loading session data | session_id={session_id} | default_game={session.default_game}")
+            next_wagon_id = current_wagon_id + 1
+            _, _, wagons = FileManager.load_session_data(session_id, session.default_game)
+            max_wagons = len(wagons)
+
+             # Check if we're at the last wagon
+            if next_wagon_id > max_wagons - 1:
+                cls.get_logger().warning(
+                    f"Cannot advance - already at last wagon | session_id={session_id} | current_wagon={current_wagon_id} | max_wagons={max_wagons}"
+                )
+                raise Exception("Cannot advance - already at last wagon")
+            
+            cls.get_logger().debug(
+                f"Wagon progression details | session_id={session_id} | current_wagon={current_wagon_id} | next_wagon={next_wagon_id} | max_wagons={max_wagons}"
+            )
+
+            # Load current wagon data for the next wagon setup
+            current_wagon = wagons[next_wagon_id]
+            
+            # Set up next wagon
+            session.current_wagon = WagonProgress(
+                wagon_id=next_wagon_id,
+                theme=current_wagon["theme"],
+                password=current_wagon["passcode"],
+            )
+
+            # Reset guessing progress for new wagon
+            session.guessing_progress = GuessingProgress()
+            cls.update_session(session)
+
+            cls.get_logger().info(
+                f"Successfully advanced to next wagon | session_id={session_id} | previous_wagon={current_wagon_id} | new_wagon={next_wagon_id} | theme={current_wagon['theme']}"
+            )
+            return True
+
+        except FileNotFoundError as e:
+            cls.get_logger().error(
+                f"Failed to load session data | session_id={session_id} | error={str(e)} | error_type=FileNotFoundError"
+            )
+            return False
+        except KeyError as e:
+            cls.get_logger().error(
+                f"Invalid wagon data structure | session_id={session_id} | error={str(e)} | error_type=KeyError"
+            )
+            return False
+        except Exception as e:
+            cls.get_logger().error(
+                f"Unexpected error during wagon advancement | session_id={session_id} | error={str(e)} | error_type={type(e).__name__}"
+            )
+            return False
+
+    @classmethod
+    def cleanup_old_sessions(cls, max_age_hours: int = 24) -> None:
+        """Remove sessions older than specified hours"""
+        current_time = datetime.utcnow()
+        sessions_to_remove = []
+
+        for session_id, session in cls._sessions.items():
+            age = (current_time - session.last_active).total_seconds() / 3600
+            if age > max_age_hours:
+                sessions_to_remove.append(session_id)
+                cls.get_logger().info(
+                    f"Marking session for cleanup | session_id: {session_id} | age_hours: {age}"
+                )
+
+        for session_id in sessions_to_remove:
+            cls.terminate_session(session_id)
+            cls.get_logger().info(f"Cleaned up old session | session_id: {session_id}")
+
+    @classmethod
+    def terminate_session(cls, session_id: str) -> None:
+        """Terminate a session and clean up its resources"""
+        if session_id in cls._sessions:
+            del cls._sessions[session_id]
+            cls.get_logger().info(f"Terminated session: {session_id}")

app/services/tts_service.py

@@ -0,0 +1,32 @@
+from dotenv import load_dotenv
+from elevenlabs.client import ElevenLabs
+from elevenlabs import play
+from app.core.logging import LoggerMixin
+import os
+import io
+
+load_dotenv()
+
+class TTSService(LoggerMixin):
+    def __init__(self):
+        self.api_key = os.getenv("ELEVEN_LABS_API_KEY")
+        if not self.api_key:
+            self.logger.error("ELEVEN_LABS_API_KEY not found in environment variables")
+            raise ValueError("ELEVEN_LABS_API_KEY is required")
+            
+        self.client = ElevenLabs(api_key=self.api_key)
+
+    def convert_text_to_speech(self, text: str) -> bytes:
+        """Convert text to speech using ElevenLabs"""
+        audio_stream = self.client.text_to_speech.convert(
+            text=text,
+            voice_id="JBFqnCBsd6RMkjVDRZzb",
+            model_id="eleven_multilingual_v2",
+            output_format="mp3_44100_128",
+        )
+        
+        # Convert the generator to bytes
+        buffer = io.BytesIO()
+        for chunk in audio_stream:
+            buffer.write(chunk)
+        return buffer.getvalue()

app/utils/file_management.py

@@ -0,0 +1,85 @@
+from pathlib import Path
+import json
+import shutil
+from typing import Dict, Any
+from app.core.logging import LoggerMixin
+
+class FileManager(LoggerMixin):
+    BASE_DATA_DIR = Path("data")
+    DEFAULT_DIR = BASE_DATA_DIR / "default"
+    
+    @classmethod
+    def ensure_directories(cls) -> None:
+        """Ensure all required directories exist"""
+        cls.BASE_DATA_DIR.mkdir(exist_ok=True)
+        cls.DEFAULT_DIR.mkdir(exist_ok=True)
+
+    @classmethod
+    def create_session_directory(cls, session_id: str) -> Path:
+        """Create a new directory for the session"""
+        session_dir = cls.BASE_DATA_DIR / session_id
+        session_dir.mkdir(exist_ok=True)
+        return session_dir
+
+    @classmethod
+    def save_session_data(cls, session_id: str, names: Dict, player_details: Dict, wagons: Dict) -> None:
+        """Save the three main data files for a session"""
+        session_dir = cls.create_session_directory(session_id)
+        logger = cls.get_logger()
+        
+        # Save each file
+        files_to_save = {
+            "names.json": names,
+            "player_details.json": player_details,
+            "wagons.json": wagons
+        }
+        
+        for filename, data in files_to_save.items():
+            file_path = session_dir / filename
+            cls.save_json(file_path, data)
+            logger.info(f"Saved session data | session_id={session_id} | filename={filename} | path={file_path}")
+
+    @classmethod
+    def get_data_directory(cls, session_id: str, default_game: bool) -> Path:
+        """Get the appropriate data directory based on default_game flag"""
+        if default_game:
+            return cls.DEFAULT_DIR
+        return cls.BASE_DATA_DIR / session_id
+
+    @classmethod
+    def load_session_data(cls, session_id: str, default_game: bool = True) -> tuple[Dict, Dict, Dict]:
+        """Load all data files for a session"""
+        logger = cls.get_logger()
+        data_dir = cls.get_data_directory(session_id, default_game)
+        
+        if not data_dir.exists():
+            logger.error(f"Data directory not found | session_id={session_id} | directory={data_dir}")
+            raise FileNotFoundError(f"No data found for session {session_id}")
+
+        try:
+            names = cls.load_json(data_dir / "names.json")
+            player_details = cls.load_json(data_dir / "player_details.json")
+            wagons = cls.load_json(data_dir / "wagons.json")
+            
+            logger.info(
+                f"Loaded session data | session_id={session_id} | "
+                f"source={'default' if default_game else 'session'} | "
+                f"directory={data_dir}"
+            )
+            return names, player_details, wagons
+            
+        except FileNotFoundError as e:
+            logger.error(f"Failed to load files | session_id={session_id} | directory={data_dir} | error={str(e)}")
+            raise FileNotFoundError(f"Missing required data files in {data_dir}")
+
+    @staticmethod
+    def save_json(file_path: Path, data: Dict[str, Any]) -> None:
+        """Save data to a JSON file"""
+        with open(file_path, 'w') as f:
+            json.dump(data, f, indent=2)
+
+    @staticmethod
+    def load_json(file_path: Path) -> Dict:
+        """Load data from a JSON file"""
+        with open(file_path, 'r') as f:
+            return json.load(f) 

data/default/names.json

@@ -0,0 +1,270 @@
+[
+  {
+    "wagonId": "wagon-0",
+    "players": []
+  },
+  {
+    "wagonId": "wagon-1",
+    "players": [
+      {
+        "playerId": "player-1",
+        "firstName": "James",
+        "lastName": "Sterling",
+        "sex": "male",
+        "fullName": "James Sterling"
+      },
+      {
+        "playerId": "player-2",
+        "firstName": "Elizabeth",
+        "lastName": "Chen",
+        "sex": "female",
+        "fullName": "Elizabeth Chen"
+      },
+      {
+        "playerId": "player-3",
+        "firstName": "Marcus",
+        "lastName": "Thompson",
+        "sex": "male",
+        "fullName": "Marcus Thompson"
+      },
+      {
+        "playerId": "player-4",
+        "firstName": "Sofia",
+        "lastName": "Rodriguez",
+        "sex": "female",
+        "fullName": "Sofia Rodriguez"
+      }
+    ]
+  },
+  {
+    "wagonId": "wagon-2",
+    "players": [
+      {
+        "playerId": "player-1",
+        "firstName": "Adrian",
+        "lastName": "North",
+        "sex": "male",
+        "fullName": "Eleanor Brooks"
+      },
+      {
+        "playerId": "player-2",
+        "firstName": "Elena",
+        "lastName": "Stone",
+        "sex": "female",
+        "fullName": "Elena Stone"
+      },
+      {
+        "playerId": "player-3",
+        "firstName": "Lucas",
+        "lastName": "West",
+        "sex": "male",
+        "fullName": "Lucas West"
+      },
+      {
+        "playerId": "player-4",
+        "firstName": "Sophia",
+        "lastName": "East",
+        "sex": "female",
+        "fullName": "Sophia East"
+      }
+    ]
+  },
+  {
+    "wagonId": "wagon-3",
+    "players": [
+      {
+        "playerId": "player-1",
+        "firstName": "Captain Elara",
+        "lastName": "Voss",
+        "sex": "female",
+        "fullName": "Captain Elara Voss"
+      },
+      {
+        "playerId": "player-2",
+        "firstName": "Dr. Orion",
+        "lastName": "Kane",
+        "sex": "male",
+        "fullName": "Dr. Orion Kane"
+      },
+      {
+        "playerId": "player-3",
+        "firstName": "Lieutenant Nova",
+        "lastName": "Sterling",
+        "sex": "female",
+        "fullName": "Lieutenant Nova Sterling"
+      },
+      {
+        "playerId": "player-4",
+        "firstName": "Professor Atlas",
+        "lastName": "Grey",
+        "sex": "male",
+        "fullName": "Professor Atlas Grey"
+      }
+    ]
+  },
+  {
+    "wagonId": "wagon-4",
+    "players": [
+      {
+        "playerId": "player-1",
+        "firstName": "General Victor",
+        "lastName": "Blackwood",
+        "sex": "male",
+        "fullName": "General Victor Blackwood"
+      },
+      {
+        "playerId": "player-2",
+        "firstName": "Lady Isabella",
+        "lastName": "Sterling",
+        "sex": "female",
+        "fullName": "Lady Isabella Sterling"
+      },
+      {
+        "playerId": "player-3",
+        "firstName": "Sergeant Marcus",
+        "lastName": "Thorne",
+        "sex": "male",
+        "fullName": "Noah Davis"
+      },
+      {
+        "playerId": "player-4",
+        "firstName": "Dr. Charlotte",
+        "lastName": "Hartley",
+        "sex": "female",
+        "fullName": "Dr. Charlotte Hartley"
+      }
+    ]
+  },
+  {
+    "wagonId": "wagon-5",
+    "players": [
+      {
+        "playerId": "player-1",
+        "firstName": "Maestro Lorenzo",
+        "lastName": "Rossi",
+        "sex": "male",
+        "fullName": "Maestro Lorenzo Rossi"
+      },
+      {
+        "playerId": "player-2",
+        "firstName": "Isabella",
+        "lastName": "Valentina",
+        "sex": "female",
+        "fullName": "Isabella Valentina"
+      },
+      {
+        "playerId": "player-3",
+        "firstName": "Leonardo",
+        "lastName": "Di Marco",
+        "sex": "male",
+        "fullName": "Leonardo Di Marco"
+      },
+      {
+        "playerId": "player-4",
+        "firstName": "Sofia",
+        "lastName": "Caruso",
+        "sex": "female",
+        "fullName": "Sofia Caruso"
+      }
+    ]
+  },
+  {
+    "wagonId": "wagon-6",
+    "players": [
+      {
+        "playerId": "player-1",
+        "firstName": "Leo 'Roar'",
+        "lastName": "Johnson",
+        "sex": "male",
+        "fullName": "Leo 'Roar' Johnson"
+      },
+      {
+        "playerId": "player-2",
+        "firstName": "Lila 'Nightingale'",
+        "lastName": "Silva",
+        "sex": "female",
+        "fullName": "Lady Olivia Wright"
+      },
+      {
+        "playerId": "player-3",
+        "firstName": "Rafael 'Panther'",
+        "lastName": "Martinez",
+        "sex": "male",
+        "fullName": "Rafael 'Panther' Martinez"
+      },
+      {
+        "playerId": "player-4",
+        "firstName": "Elena 'Jaguar'",
+        "lastName": "Rodriguez",
+        "sex": "female",
+        "fullName": "Elena 'Jaguar' Rodriguez"
+      }
+    ]
+  },
+  {
+    "wagonId": "wagon-7",
+    "players": [
+      {
+        "playerId": "player-1",
+        "firstName": "Marco",
+        "lastName": "Valentino",
+        "sex": "male",
+        "fullName": "Marco Valentino"
+      },
+      {
+        "playerId": "player-2",
+        "firstName": "Giovanna",
+        "lastName": "Rosalia",
+        "sex": "female",
+        "fullName": "Giovanna Rosalia"
+      },
+      {
+        "playerId": "player-3",
+        "firstName": "Father",
+        "lastName": "Lorenzo",
+        "sex": "male",
+        "fullName": "Father Lorenzo"
+      },
+      {
+        "playerId": "player-4",
+        "firstName": "Luca",
+        "lastName": "Montefiori",
+        "sex": "male",
+        "fullName": "Luca Montefiori"
+      }
+    ]
+  },
+  {
+    "wagonId": "wagon-8",
+    "players": [
+      {
+        "playerId": "player-1",
+        "firstName": "Eleanor",
+        "lastName": "Voss",
+        "sex": "male",
+        "fullName": "Eleanor Voss"
+      },
+      {
+        "playerId": "player-2",
+        "firstName": "Theadore",
+        "lastName": "Kane",
+        "sex": "female",
+        "fullName": "Theadore Kane"
+      },
+      {
+        "playerId": "player-3",
+        "firstName": "Victoria",
+        "lastName": "Sterling",
+        "sex": "female",
+        "fullName": "Victoria Sterling"
+      },
+      {
+        "playerId": "player-4",
+        "firstName": "Edgar",
+        "lastName": "Grey",
+        "sex": "male",
+        "fullName": "Edgar Grey"
+      }
+    ]
+  }
+]

data/default/player_details.json

@@ -0,0 +1,398 @@
+[
+  {
+    "wagonId": "wagon-0",
+    "players": []
+  },
+  {
+    "wagonId": "wagon-1",
+    "players": [
+      {
+        "playerId": "player-1",
+        "profile": {
+          "name": "James Sterling",
+          "age": 42,
+          "profession": "Investment Banker",
+          "personality": "Ambitious and calculating",
+          "role": "A successful banker with questionable ethics",
+          "mystery_intrigue": "Has been manipulating gold prices for personal gain"
+        }
+      },
+      {
+        "playerId": "player-2",
+        "profile": {
+          "name": "Elizabeth Chen",
+          "age": 35,
+          "profession": "Financial Analyst",
+          "personality": "Sharp-minded and detail-oriented",
+          "role": "Whistleblower investigating financial fraud",
+          "mystery_intrigue": "Has evidence of major market manipulation"
+        }
+      },
+      {
+        "playerId": "player-3",
+        "profile": {
+          "name": "Marcus Thompson",
+          "age": 45,
+          "profession": "Securities Regulator",
+          "personality": "Stern and methodical",
+          "role": "Investigating suspicious trading patterns",
+          "mystery_intrigue": "Close to uncovering a major financial scandal"
+        }
+      },
+      {
+        "playerId": "player-4",
+        "profile": {
+          "name": "Sofia Rodriguez",
+          "age": 38,
+          "profession": "Corporate Lawyer",
+          "personality": "Shrewd and diplomatic",
+          "role": "Legal counsel involved in the investigation",
+          "mystery_intrigue": "May be working for both sides"
+        }
+      }
+    ]
+  },
+  {
+    "wagonId": "wagon-2",
+    "players": [
+      {
+        "playerId": "player-1",
+        "profile": {
+          "name": "Adrian North",
+          "age": 38,
+          "profession": "Adventurer and Cartographer",
+          "personality": "Brave, curious, and determined",
+          "role": "Leads the expedition through uncharted territories, using an antique navigation tool with a unique magnetic needle.",
+          "mystery_intrigue": "Carries a mysterious map that seems to guide them towards a hidden treasure, but the map has strange symbols that no one can decipher."
+        }
+      },
+      {
+        "playerId": "player-2",
+        "profile": {
+          "name": "Elena Stone",
+          "age": 32,
+          "profession": "Archaeologist",
+          "personality": "Intelligent, meticulous, and resourceful",
+          "role": "Studies ancient artifacts found along the journey, including a small, intricately designed metal disk.",
+          "mystery_intrigue": "Has discovered clues suggesting the existence of a lost civilization, but keeps this information secret from the team."
+        }
+      },
+      {
+        "playerId": "player-3",
+        "profile": {
+          "name": "Lucas West",
+          "age": 28,
+          "profession": "Botanist",
+          "personality": "Analytical, patient, and nurturing",
+          "role": "Identifies and documents new plant species, often seen with a small, engraved metal case containing rare seeds.",
+          "mystery_intrigue": "Finds a rare plant that has healing properties, but its location is marked by a peculiar symbol that resembles a directional pointer."
+        }
+      },
+      {
+        "playerId": "player-4",
+        "profile": {
+          "name": "Sophia East",
+          "age": 35,
+          "profession": "Linguist",
+          "personality": "Insightful, empathetic, and communicative",
+          "role": "Deciphers ancient languages and symbols encountered during the expedition, carries a small, ornate metal pendant.",
+          "mystery_intrigue": "Uncovers a hidden language that seems to provide directions to a mysterious artifact, but the language is unlike anything she has ever seen."
+        }
+      }
+    ]
+  },
+  {
+    "wagonId": "wagon-3",
+    "players": [
+      {
+        "playerId": "player-1",
+        "profile": {
+          "name": "Captain Elara Voss",
+          "age": 40,
+          "profession": "Submarine Captain",
+          "personality": "Courageous, strategic, and decisive",
+          "role": "Leads the expedition with an advanced submarine equipped with a unique spiral-shaped hull design.",
+          "mystery_intrigue": "Hiding a personal vendetta against a rival exploration company, which may influence her decisions and put the crew in danger."
+        }
+      },
+      {
+        "playerId": "player-2",
+        "profile": {
+          "name": "Dr. Orion Kane",
+          "age": 35,
+          "profession": "Marine Archaeologist",
+          "personality": "Intellectual, curious, and meticulous",
+          "role": "Driven by the mystery of the underwater civilization, studies ancient maritime artifacts including a spiral-shaped pendant.",
+          "mystery_intrigue": "Has discovered a hidden artifact that could revolutionize their understanding of the underwater civilization, but keeps it secret."
+        }
+      },
+      {
+        "playerId": "player-3",
+        "profile": {
+          "name": "Lieutenant Nova Sterling",
+          "age": 30,
+          "profession": "Naval Engineer",
+          "personality": "Innovative, resourceful, and practical",
+          "role": "Ensures the submarine's systems are operational, monitors signals received from the surface.",
+          "mystery_intrigue": "Receiving encrypted messages from an unknown source, warning her about an impending danger within the crew."
+        }
+      },
+      {
+        "playerId": "player-4",
+        "profile": {
+          "name": "Professor Atlas Grey",
+          "age": 45,
+          "profession": "Oceanographer",
+          "personality": "Wise, patient, and analytical",
+          "role": "Provides scientific context for the underwater environment, possesses an old engraved timepiece.",
+          "mystery_intrigue": "Has uncovered evidence of a dangerous underwater creature that could threaten the expedition, but keeps this information to himself."
+        }
+      }
+    ]
+  },
+  {
+    "wagonId": "wagon-4",
+    "players": [
+      {
+        "playerId": "player-1",
+        "profile": {
+          "name": "General Victor Blackwood",
+          "age": 55,
+          "profession": "Retired Military Commander",
+          "personality": "Honorable, stern, and strategic",
+          "role": "Leads a group of veterans on a quest to uncover the truth behind a legendary battle, carries an old, tattered map.",
+          "mystery_intrigue": "Haunted by a past decision that led to a devastating defeat, seeks redemption and closure."
+        }
+      },
+      {
+        "playerId": "player-2",
+        "profile": {
+          "name": "Lady Isabella Sterling",
+          "age": 40,
+          "profession": "Historian",
+          "personality": "Intelligent, empathetic, and determined",
+          "role": "Documents the journey and interprets historical artifacts, including an antique pocket watch.",
+          "mystery_intrigue": "Discovers letters hinting at a secret alliance that could have changed the course of the battle, but keeps this information hidden."
+        }
+      },
+      {
+        "playerId": "player-3",
+        "profile": {
+          "name": "Sergeant Marcus Thorne",
+          "age": 38,
+          "profession": "Former Infantryman",
+          "personality": "Loyal, brave, and resilient",
+          "role": "Provides security and support for the expedition, carries a worn, engraved flask.",
+          "mystery_intrigue": "Experiences vivid dreams of the battle, revealing clues about a hidden treasure, but fears being seen as unstable."
+        }
+      },
+      {
+        "playerId": "player-4",
+        "profile": {
+          "name": "Dr. Charlotte Hartley",
+          "age": 35,
+          "profession": "Archaeologist",
+          "personality": "Curious, methodical, and analytical",
+          "role": "Excavates and studies battlefield remnants, including an old, mud-caked musket ball.",
+          "mystery_intrigue": "Uncovers evidence of a cover-up involving high-ranking officers, but struggles with the ethical implications of revealing the truth."
+        }
+      }
+    ]
+  },
+  {
+    "wagonId": "wagon-5",
+    "players": [
+      {
+        "playerId": "player-1",
+        "profile": {
+          "name": "Maestro Lorenzo Rossi",
+          "age": 58,
+          "profession": "Conductor",
+          "personality": "Passionate, perfectionistic, and charismatic",
+          "role": "Leads a renowned orchestra, known for his innovative interpretations of classical pieces, especially those with intricate compositions.",
+          "mystery_intrigue": "Hides a rare, unpublished manuscript that could redefine musical history, but fears the controversy it might cause."
+        }
+      },
+      {
+        "playerId": "player-2",
+        "profile": {
+          "name": "Isabella Valentina",
+          "age": 32,
+          "profession": "Violinist",
+          "personality": "Talented, expressive, and dedicated",
+          "role": "First chair violinist, captivates audiences with her emotional performances, often featuring complex, lively melodies.",
+          "mystery_intrigue": "Possesses an antique violin with a mysterious inscription, hinting at a hidden composition of immense significance."
+        }
+      },
+      {
+        "playerId": "player-3",
+        "profile": {
+          "name": "Leonardo Di Marco",
+          "age": 45,
+          "profession": "Composer",
+          "personality": "Creative, introspective, and visionary",
+          "role": "Creates modern compositions inspired by classical themes, known for his ability to blend old and new musical styles.",
+          "mystery_intrigue": "Discovers a lost symphony that echoes the genius of past masters, but grapples with the ethical dilemma of claiming it as his own."
+        }
+      },
+      {
+        "playerId": "player-4",
+        "profile": {
+          "name": "Sofia Caruso",
+          "age": 28,
+          "profession": "Opera Singer",
+          "personality": "Graceful, confident, and melodious",
+          "role": "Enchants audiences with her powerful vocals, specializing in arias that require exceptional range and technique.",
+          "mystery_intrigue": "Finds a hidden letter revealing a secret affair between two famous musicians, which could scandalize the musical world."
+        }
+      }
+    ]
+  },
+  {
+    "wagonId": "wagon-6",
+    "players": [
+      {
+        "playerId": "player-1",
+        "profile": {
+          "name": "Leo 'Roar' Johnson",
+          "age": 42,
+          "profession": "Jazz Musician (Saxophonist)",
+          "personality": "Charismatic, bold, and innovative",
+          "role": "Leads a jazz band known for its wild, energetic performances, often featuring improvisations that evoke the sounds of the jungle.",
+          "mystery_intrigue": "Possesses a rare, antique saxophone with engravings of a mysterious jungle creature, hinting at a hidden treasure deep within the rainforest."
+        }
+      },
+      {
+        "playerId": "player-2",
+        "profile": {
+          "name": "Lila 'Nightingale' Silva",
+          "age": 35,
+          "profession": "Jazz Singer",
+          "personality": "Melodious, enchanting, and free-spirited",
+          "role": "Captivates audiences with her soulful vocals, incorporating exotic bird songs and nature-inspired melodies into her performances.",
+          "mystery_intrigue": "Discovers an old map leading to a legendary jungle temple, guarded by a mythical beast, but keeps the map's existence a secret."
+        }
+      },
+      {
+        "playerId": "player-3",
+        "profile": {
+          "name": "Rafael 'Panther' Martinez",
+          "age": 38,
+          "profession": "Percussionist",
+          "personality": "Rhythmic, intense, and intuitive",
+          "role": "Drives the band's rhythm section with primal beats and complex patterns, using instruments crafted from jungle materials.",
+          "mystery_intrigue": "Receives mysterious drum patterns in his dreams, which he believes are clues to an ancient jungle ritual, but fears the consequences of unleashing its power."
+        }
+      },
+      {
+        "playerId": "player-4",
+        "profile": {
+          "name": "Elena 'Jaguar' Rodriguez",
+          "age": 30,
+          "profession": "Pianist",
+          "personality": "Elegant, fierce, and expressive",
+          "role": "Enthralls listeners with her dynamic piano solos, blending classical technique with the raw energy of the jungle.",
+          "mystery_intrigue": "Finds a hidden journal detailing a legendary jungle expedition, but the journal's warnings of a dangerous predator make her hesitant to reveal its contents."
+        }
+      }
+    ]
+  },
+  {
+    "wagonId": "wagon-7",
+    "players": [
+      {
+        "playerId": "player-1",
+        "profile": {
+          "name": "Marco Valentino",
+          "age": 48,
+          "profession": "Wealthy Merchant",
+          "personality": "Ambitious, shrewd, and guarded",
+          "role": "Head of the influential Valentino family, embroiled in a long-standing rivalry with another powerful clan, carries an heirloom signet ring with a distinctive crest.",
+          "mystery_intrigue": "Haunted by a past betrayal that deepened the feud, seeks revenge while hiding a secret that could unite the families."
+        }
+      },
+      {
+        "playerId": "player-2",
+        "profile": {
+          "name": "Giovanna Rosalia",
+          "age": 42,
+          "profession": "Noblewoman",
+          "personality": "Elegant, wise, and protective",
+          "role": "Matriarch of the Rosalia family, desires peace and unity, often seen with an antique brooch featuring intertwined roses and thorns.",
+          "mystery_intrigue": "Discovers an old love letter hinting at a forbidden romance between members of the rival families, but struggles with the implications of revealing it."
+        }
+      },
+      {
+        "playerId": "player-3",
+        "profile": {
+          "name": "Father Lorenzo",
+          "age": 50,
+          "profession": "Priest",
+          "personality": "Compassionate, insightful, and resourceful",
+          "role": "Counsels both families and secretly aids the young lovers, carries a rosary with a unique heart-shaped pendant.",
+          "mystery_intrigue": "Knows of a hidden sanctuary where the lovers can meet, but fears the consequences of defying the powerful families."
+        }
+      },
+      {
+        "playerId": "player-4",
+        "profile": {
+          "name": "Luca Montefiori",
+          "age": 35,
+          "profession": "Nobleman",
+          "personality": "Charismatic, determined, and proud",
+          "role": "Heir to the Montefiori fortune, seeks to marry into the Rosalia family for political gain, possesses a dagger with an engraved family crest.",
+          "mystery_intrigue": "Uncovers a plot to sabotage the upcoming wedding, which could reignite the feud and plunge the city into chaos."
+        }
+      }
+    ]
+  },
+  {
+    "wagonId": "wagon-8",
+    "players": [
+      {
+        "playerId": "player-1",
+        "profile": {
+          "name": "Eleanor Voss",
+          "age": 38,
+          "profession": "Inventor",
+          "personality": "Creative, determined, and analytical",
+          "role": "Develops innovative sound recording devices, including a prototype with a unique cylinder design.",
+          "mystery_intrigue": "Discovers hidden recordings on an old cylinder that hint at a secret society communicating through coded messages."
+        }
+      },
+      {
+        "playerId": "player-2",
+        "profile": {
+          "name": "Theodore Kane",
+          "age": 42,
+          "profession": "Engineer",
+          "personality": "Practical, resourceful, and meticulous",
+          "role": "Specializes in mechanical engineering, often seen working on intricate gears and components for sound devices.",
+          "mystery_intrigue": "Finds blueprints for an advanced device that can record and play back voices with unprecedented clarity, but the inventor's identity remains a mystery."
+        }
+      },
+      {
+        "playerId": "player-3",
+        "profile": {
+          "name": "Victoria Sterling",
+          "age": 35,
+          "profession": "Musician",
+          "personality": "Passionate, expressive, and innovative",
+          "role": "Experiments with new musical instruments and recording techniques, carries a small, engraved metal case containing rare cylinders.",
+          "mystery_intrigue": "Receives anonymous letters containing cryptic messages and musical notes, hinting at a hidden melody with mysterious powers."
+        }
+      },
+      {
+        "playerId": "player-4",
+        "profile": {
+          "name": "Edgar Grey",
+          "age": 40,
+          "profession": "Detective",
+          "personality": "Observant, tenacious, and intuitive",
+          "role": "Investigates cases of industrial espionage and stolen inventions, possesses a pocket watch with an engraved symbol.",
+          "mystery_intrigue": "Uncovers a plot to steal advanced sound recording technology, but struggles to identify the mastermind behind the scheme."
+        }
+      }
+    ]
+  }
+]

data/default/wagons.json

@@ -0,0 +1,288 @@
+[
+  {
+    "id": 0,
+    "theme": "Tutorial (Start)",
+    "passcode": "start",
+    "people": []
+  },
+  {
+    "id": 1,
+    "theme": "A Flourishing Business",
+    "passcode": "gold",
+    "people": [
+      {
+        "uid": "wagon-1-player-1",
+        "position": [0.5, 0.5],
+        "rotation": 0,
+        "model_type": "character-male-e",
+        "items": []
+      },
+      {
+        "uid": "wagon-1-player-2",
+        "position": [0.25, 0.25],
+        "rotation": 0,
+        "model_type": "character-female-f",
+        "items": []
+      },
+      {
+        "uid": "wagon-1-player-3",
+        "position": [0.75, 0.55],
+        "rotation": 0,
+        "model_type": "character-male-c",
+        "items": []
+      },
+      {
+        "uid": "wagon-1-player-4",
+        "position": [0.75, 0.65],
+        "rotation": 0,
+        "model_type": "character-female-e",
+        "items": []
+      }
+    ]
+  },
+  {
+    "id": 2,
+    "theme": "Off the Map",
+    "passcode": "aztec",
+    "people": [
+      {
+        "uid": "wagon-2-player-1",
+        "position": [0.5, 0.5],
+        "rotation": 0,
+        "model_type": "character-male-e",
+        "items": []
+      },
+      {
+        "uid": "wagon-2-player-2",
+        "position": [0.25, 0.25],
+        "rotation": 0,
+        "model_type": "character-female-e",
+        "items": ["blaster", "cone"]
+      },
+      {
+        "uid": "wagon-2-player-3",
+        "position": [0.75, 0.55],
+        "rotation": 0,
+        "model_type": "character-male-e",
+        "items": []
+      },
+      {
+        "uid": "wagon-2-player-4",
+        "position": [0.75, 0.65],
+        "rotation": 0,
+        "model_type": "character-female-f",
+        "items": []
+      }
+    ]
+  },
+  {
+    "id": 3,
+    "theme": "Ving Mille Lieues Sous Les Mers",
+    "passcode": "nemo",
+    "people": [
+      {
+        "uid": "wagon-3-player-1",
+        "position": [0.5, 0.5],
+        "rotation": 0,
+        "model_type": "character-female-d",
+        "items": []
+      },
+      {
+        "uid": "wagon-3-player-2",
+        "position": [0.25, 0.25],
+        "rotation": 0,
+        "model_type": "character-male-d",
+        "items": []
+      },
+      {
+        "uid": "wagon-3-player-3",
+        "position": [0.75, 0.55],
+        "rotation": 0,
+        "model_type": "character-female-b",
+        "items": []
+      },
+      {
+        "uid": "wagon-3-player-4",
+        "position": [0.75, 0.65],
+        "rotation": 0,
+        "model_type": "character-male-c",
+        "items": []
+      }
+    ]
+  },
+  {
+    "id": 4,
+    "theme": "Journey to the Future",
+    "passcode": "future",
+    "people": [
+      {
+        "uid": "wagon-4-player-1",
+        "position": [0.5, 0.5],
+        "rotation": 0,
+        "model_type": "character-male-a",
+        "items": []
+      },
+      {
+        "uid": "wagon-4-player-2",
+        "position": [0.25, 0.25],
+        "rotation": 0,
+        "model_type": "character-female-a",
+        "items": []
+      },
+      {
+        "uid": "wagon-4-player-3",
+        "position": [0.75, 0.55],
+        "rotation": 0,
+        "model_type": "character-male-f",
+        "items": []
+      },
+      {
+        "uid": "wagon-4-player-4",
+        "position": [0.75, 0.65],
+        "rotation": 0,
+        "model_type": "character-female-b",
+        "items": []
+      }
+    ]
+  },
+  {
+    "id": 5,
+    "theme": "The Grand Symphony",
+    "passcode": "melody",
+    "people": [
+      {
+        "uid": "wagon-5-player-1",
+        "position": [0.5, 0.5],
+        "rotation": 0,
+        "model_type": "character-male-b",
+        "items": []
+      },
+      {
+        "uid": "wagon-5-player-2",
+        "position": [0.3, 0.4],
+        "rotation": 0,
+        "model_type": "character-female-d",
+        "items": []
+      },
+      {
+        "uid": "wagon-5-player-3",
+        "position": [0.7, 0.6],
+        "rotation": 0,
+        "model_type": "character-male-d",
+        "items": []
+      },
+      {
+        "uid": "wagon-5-player-4",
+        "position": [0.6, 0.8],
+        "rotation": 0,
+        "model_type": "character-female-c",
+        "items": []
+      }
+    ]
+  },
+  {
+    "id": 6,
+    "theme": "Jungle Jazz",
+    "passcode": "jungle",
+    "people": [
+      {
+        "uid": "wagon-6-player-1",
+        "position": [0.5, 0.5],
+        "rotation": 0,
+        "model_type": "character-male-f",
+        "items": []
+      },
+      {
+        "uid": "wagon-6-player-2",
+        "position": [0.25, 0.4],
+        "rotation": 0,
+        "model_type": "character-female-a",
+        "items": []
+      },
+      {
+        "uid": "wagon-6-player-3",
+        "position": [0.7, 0.55],
+        "rotation": 0,
+        "model_type": "character-male-e",
+        "items": []
+      },
+      {
+        "uid": "wagon-6-player-4",
+        "position": [0.77, 0.65],
+        "rotation": 0,
+        "model_type": "character-female-f",
+        "items": []
+      }
+    ]
+  },
+  {
+    "id": 7,
+    "theme": "Feuding Families",
+    "passcode": "rose",
+    "people": [
+      {
+        "uid": "wagon-7-player-1",
+        "position": [0.45, 0.5],
+        "rotation": 0,
+        "model_type": "character-male-d",
+        "items": []
+      },
+      {
+        "uid": "wagon-7-player-2",
+        "position": [0.3, 0.25],
+        "rotation": 0,
+        "model_type": "character-female-f",
+        "items": []
+      },
+      {
+        "uid": "wagon-7-player-3",
+        "position": [0.75, 0.5],
+        "rotation": 0,
+        "model_type": "character-male-c",
+        "items": []
+      },
+      {
+        "uid": "wagon-7-player-4",
+        "position": [0.75, 0.65],
+        "rotation": 0,
+        "model_type": "character-male-b",
+        "items": []
+      }
+    ]
+  },
+  {
+    "id": 8,
+    "theme": "Secrets on Record",
+    "passcode": "FREQUENCY",
+    "people": [
+      {
+        "uid": "wagon-8-player-1",
+        "position": [0.5, 0.5],
+        "rotation": 0,
+        "model_type": "character-female-e",
+        "items": []
+      },
+      {
+        "uid": "wagon-8-player-2",
+        "position": [0.25, 0.25],
+        "rotation": 0,
+        "model_type": "character-male-c",
+        "items": []
+      },
+      {
+        "uid": "wagon-8-player-3",
+        "position": [0.75, 0.55],
+        "rotation": 0,
+        "model_type": "character-female-b",
+        "items": []
+      },
+      {
+        "uid": "wagon-8-player-4",
+        "position": [0.75, 0.65],
+        "rotation": 0,
+        "model_type": "character-male-a",
+        "items": []
+      }
+    ]
+  }
+]

requirements.txt

@@ -0,0 +1,10 @@
+fastapi[standard]>=0.104.0
+uvicorn[standard]>=0.24.0
+pydantic>=2.5.0
+python-jose[cryptography]>=3.3.0
+uuid>=1.30
+mistralai>=0.0.7
+python-dotenv>=1.0.0
+langchain>=0.3.15
+langchain-mistralai>=0.2.4
+elevenlabs>=0.1.0

shell.nix

@@ -0,0 +1,12 @@
+{ pkgs ? import <nixpkgs> {} }:
+
+pkgs.mkShell {
+  buildInputs = with pkgs; [
+    uv
+    ngrok
+  ];
+
+  shellHook = ''
+    uv --version
+  '';
+}