first commit

.env

@@ -0,0 +1,65 @@
+# DungeonMaster AI - Environment Configuration
+# Copy this file to .env and fill in your actual API keys
+
+# ============================================
+# LLM API Keys (Required - at least one)
+# ============================================
+
+# Google Gemini API Key (Primary LLM)
+# Get your key at: https://aistudio.google.com/apikey
+GEMINI_API_KEY=AIzaSyBUl4IaLR9jts5aA-IzLIB6WO2PklYuFY8
+
+# OpenAI API Key (Fallback LLM)
+# Get your key at: https://platform.openai.com/api-keys
+OPENAI_API_KEY=your_openai_api_key_here
+
+# LLM Models (optional - defaults shown)
+GEMINI_MODEL=gemini-2.5-flash
+OPENAI_MODEL=gpt-4o
+
+# ============================================
+# Voice Synthesis (Required for voice feature)
+# ============================================
+
+# ElevenLabs API Key
+# Get your key at: https://elevenlabs.io/api
+ELEVENLABS_API_KEY=sk_d286e70102ddd8b3ba44389bfd3a883d57f704a9e949228c
+
+# Voice Model (optional)
+VOICE_MODEL=eleven_flash_v2_5
+
+# ============================================
+# TTRPG Toolkit MCP Server
+# ============================================
+
+# MCP Server URL (SSE endpoint)
+# For local development: http://localhost:8000/sse
+# For Blaxel deployment: https://your-deployment.blaxel.app/sse
+TTRPG_TOOLKIT_MCP_URL=http://localhost:8000/mcp
+
+# ============================================
+# HuggingFace Deployment
+# ============================================
+
+# HuggingFace Token (for Spaces deployment)
+# Get your token at: https://huggingface.co/settings/tokens
+HUGGINGFACE_TOKEN=your_hf_token_here
+
+# ============================================
+# Application Settings
+# ============================================
+
+# Debug mode (true/false)
+DEBUG_MODE=false
+
+# Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+LOG_LEVEL=INFO
+
+# Voice settings
+VOICE_ENABLED=true
+VOICE_AUTO_PLAY=true
+VOICE_SPEED=1.0
+
+# Game settings
+MAX_CONVERSATION_HISTORY=10
+DEFAULT_ADVENTURE=tavern_start

.env.example

@@ -0,0 +1,65 @@
+# DungeonMaster AI - Environment Configuration
+# Copy this file to .env and fill in your actual API keys
+
+# ============================================
+# LLM API Keys (Required - at least one)
+# ============================================
+
+# Google Gemini API Key (Primary LLM)
+# Get your key at: https://aistudio.google.com/apikey
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# OpenAI API Key (Fallback LLM)
+# Get your key at: https://platform.openai.com/api-keys
+OPENAI_API_KEY=your_openai_api_key_here
+
+# LLM Models (optional - defaults shown)
+GEMINI_MODEL=gemini-1.5-pro
+OPENAI_MODEL=gpt-4o
+
+# ============================================
+# Voice Synthesis (Required for voice feature)
+# ============================================
+
+# ElevenLabs API Key
+# Get your key at: https://elevenlabs.io/api
+ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
+
+# Voice Model (optional)
+VOICE_MODEL=eleven_turbo_v2
+
+# ============================================
+# TTRPG Toolkit MCP Server
+# ============================================
+
+# MCP Server URL (SSE endpoint)
+# For local development: http://localhost:8000/sse
+# For Blaxel deployment: https://your-deployment.blaxel.app/sse
+TTRPG_TOOLKIT_MCP_URL=http://localhost:8000/sse
+
+# ============================================
+# HuggingFace Deployment
+# ============================================
+
+# HuggingFace Token (for Spaces deployment)
+# Get your token at: https://huggingface.co/settings/tokens
+HUGGINGFACE_TOKEN=your_hf_token_here
+
+# ============================================
+# Application Settings
+# ============================================
+
+# Debug mode (true/false)
+DEBUG_MODE=false
+
+# Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+LOG_LEVEL=INFO
+
+# Voice settings
+VOICE_ENABLED=true
+VOICE_AUTO_PLAY=true
+VOICE_SPEED=1.0
+
+# Game settings
+MAX_CONVERSATION_HISTORY=10
+DEFAULT_ADVENTURE=tavern_start

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+ui/assets/images/scenes/castle.jpg filter=lfs diff=lfs merge=lfs -text
+ui/assets/images/scenes/default.jpg filter=lfs diff=lfs merge=lfs -text
+ui/assets/images/scenes/dungeon.jpg filter=lfs diff=lfs merge=lfs -text
+ui/assets/images/scenes/tavern.jpg filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,170 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# UV
+uv.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Project-specific
+*.mp3
+*.wav
+*.ogg
+audio_cache/
+saves/
+data/indices/
+data/characters/
+
+# Secrets
+.env.local
+.env.*.local
+secrets.json
+credentials.json
+
+# Gradio
+flagged/
+
+# Claude
+.claude/

README.md

@@ -1,14 +1,297 @@
 ---
 title: DungeonMaster AI
-emoji: 🏃
+emoji: "\U0001F3B2"
 colorFrom: yellow
-colorTo: gray
+colorTo: red
 sdk: gradio
-sdk_version: 6.0.1
+sdk_version: "6.0.0"
 app_file: app.py
-pinned: false
+pinned: true
+tags:
+  - agent-demo-track
+  - mcp
+  - dnd
+  - llama-index
+  - gemini
+  - elevenlabs
+  - gaming
+  - voice
 license: mit
-short_description: AI powered D&D game master
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# DungeonMaster AI
+
+**Your AI-Powered D&D 5e Game Master with Voice Narration**
+
+*Roll for initiative! An immersive tabletop experience powered by cutting-edge AI technology.*
+
+---
+
+## Demo Video
+
+[![DungeonMaster AI Demo](https://img.shields.io/badge/Watch-Demo%20Video-red?style=for-the-badge&logo=youtube)](https://youtube.com/your-video-link)
+
+---
+
+## Features
+
+### AI Dungeon Master
+- **Intelligent Storytelling**: Dynamic narrative generation that adapts to your choices
+- **Authentic D&D Experience**: Full D&D 5e rules implementation via TTRPG Toolkit MCP
+- **Multi-Modal Agents**: Specialized agents for storytelling, rules lookup, and voice narration
+
+### Voice Narration
+- **Immersive Audio**: Professional voice narration powered by ElevenLabs
+- **Character Voices**: Different voice profiles for the DM, NPCs, and monsters
+- **Real-Time Streaming**: Low-latency voice synthesis for smooth gameplay
+
+### Complete Game System
+- **Full Character Management**: Create, track, and level up D&D 5e characters
+- **Combat Engine**: Turn-based combat with initiative tracking and condition management
+- **Dice Rolling**: All standard D&D dice with advantage/disadvantage and modifiers
+- **Rules Lookup**: RAG-powered rules search for instant rule clarification
+
+### Beautiful Fantasy UI
+- **Themed Interface**: Dark fantasy aesthetic with parchment textures and golden accents
+- **Responsive Design**: Works on desktop, tablet, and mobile
+- **Real-Time Updates**: Live character sheet, combat tracker, and dice roll history
+
+---
+
+## How to Play
+
+### Starting a New Game
+
+1. **Launch the App**: Visit the HuggingFace Space or run locally
+2. **Create Your Character**: Use the character creation wizard or load a pre-made template
+3. **Choose Your Adventure**: Start with "The Rusty Dragon Tavern" or "The Goblin Cave"
+4. **Start Playing**: Type your actions and watch the story unfold!
+
+### Basic Commands
+
+| Action | What to Type |
+|--------|-------------|
+| **Attack** | "I attack the goblin with my sword" |
+| **Investigate** | "I search the room for hidden doors" |
+| **Talk** | "I ask the bartender about recent rumors" |
+| **Cast a Spell** | "I cast Magic Missile at the enemy" |
+| **Move** | "I sneak down the dark corridor" |
+
+### Special Commands
+
+- `/roll [notation]` - Roll dice directly (e.g., `/roll 2d6+3`)
+- `/character` - View your character sheet
+- `/inventory` - Check your items
+- `/rest` - Take a short or long rest
+
+### Combat Tips
+
+- The DM will call for initiative when combat begins
+- Describe your intended action - the AI will handle the mechanics
+- Use the combat tracker to see turn order and HP
+- Strategic positioning and creative solutions are rewarded!
+
+---
+
+## Technical Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         DUNGEONMASTER AI                                │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  LAYER 1: GRADIO 6 UI                                                   │
+│  ├── Chat Panel (with voice playback)                                   │
+│  ├── Character Sheet Panel                                              │
+│  ├── Dice & Roll History Panel                                          │
+│  ├── Combat Tracker Panel                                               │
+│  └── Game Controls Panel                                                │
+│                                                                         │
+│  LAYER 2: AGENT ORCHESTRATION (LlamaIndex)                              │
+│  ├── Dungeon Master Agent (storytelling, game flow)                     │
+│  ├── Rules Arbiter Agent (rules lookup, adjudication)                   │
+│  └── Voice Narrator Agent (ElevenLabs integration)                      │
+│                                                                         │
+│  LAYER 3: GAME STATE MANAGEMENT                                         │
+│  ├── Game State Manager (session, party, location, combat)              │
+│  ├── Story Context Builder (LLM context preparation)                    │
+│  └── Event Logger (action history tracking)                             │
+│                                                                         │
+│  LAYER 4: MCP INTEGRATION                                               │
+│  ├── TTRPG Toolkit Client (connection to MCP server)                    │
+│  ├── Tool Wrappers (game-aware tool enhancements)                       │
+│  └── Connection Manager (health checks, reconnection)                   │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                        TTRPG TOOLKIT MCP                                │
+│                   (Separate MCP Server - Blaxel)                        │
+│  ├── Dice Roller Server                                                 │
+│  ├── Character Manager Server                                           │
+│  ├── Rules Lookup Server (LlamaIndex RAG)                               │
+│  ├── Generators Server (NPCs, encounters, loot)                         │
+│  ├── Combat Engine Server                                               │
+│  └── Session Manager Server                                             │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Built With
+
+### AI & Agents
+- **[Google Gemini](https://ai.google.dev/)** - Primary LLM for storytelling and game mastering
+- **[OpenAI GPT-4](https://openai.com/)** - Fallback LLM for reliability
+- **[LlamaIndex](https://www.llamaindex.ai/)** - Agent framework and RAG for rules lookup
+
+### Voice
+- **[ElevenLabs](https://elevenlabs.io/)** - Voice synthesis for immersive narration
+
+### MCP & Backend
+- **[TTRPG Toolkit MCP](https://github.com/ttrpg-toolkit/ttrpg-toolkit-mcp)** - Game mechanics server
+- **[Blaxel](https://blaxel.com/)** - MCP server deployment
+
+### UI & Deployment
+- **[Gradio 6](https://gradio.app/)** - Modern UI framework
+- **[HuggingFace Spaces](https://huggingface.co/spaces)** - Deployment platform
+
+---
+
+## Local Development
+
+### Prerequisites
+
+- Python 3.10+
+- UV or pip
+- API keys for Gemini, OpenAI, and ElevenLabs
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/dungeonmaster-ai/dungeonmaster-ai.git
+cd dungeonmaster-ai
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Copy environment file and add your API keys
+cp .env.example .env
+# Edit .env with your actual API keys
+
+# Run the application
+python -m ui.app
+```
+
+### Running with TTRPG Toolkit (Local)
+
+```bash
+# In one terminal, run the MCP server
+cd ../TTRPG-Toolkit
+python -m src.main
+
+# In another terminal, run DungeonMaster AI
+cd ../DungeonMaster-AI
+python -m ui.app
+```
+
+---
+
+## Project Structure
+
+```
+dungeonmaster-ai/
+├── src/
+│   ├── agents/              # LlamaIndex agents
+│   ├── voice/               # ElevenLabs integration
+│   ├── mcp_integration/     # TTRPG Toolkit MCP client
+│   ├── game/                # Game state management
+│   ├── config/              # Settings and prompts
+│   └── utils/               # Helpers and formatters
+├── ui/
+│   ├── app.py               # Main Gradio application
+│   ├── components/          # UI components
+│   ├── handlers/            # Event handlers
+│   ├── themes/              # Fantasy theme
+│   └── assets/              # Images and CSS
+├── adventures/              # Pre-made adventure content
+│   ├── tutorial_goblin_cave.json
+│   ├── tavern_start.json
+│   └── sample_characters/
+├── tests/                   # Test suite
+└── docs/                    # Documentation
+```
+
+---
+
+## Adventures Included
+
+### The Rusty Dragon Tavern
+A classic sandbox start. Meet colorful NPCs, hear rumors, and find your first adventure hook. Perfect for open-ended exploration.
+
+### The Goblin Cave
+A beginner-friendly adventure where heroes investigate goblin raids. Learn combat, exploration, and puzzle-solving in a focused 30-45 minute experience.
+
+---
+
+## Sample Characters
+
+Get started immediately with pre-made characters:
+
+- **Valric the Bold** - Human Fighter, Level 1
+- **Elara Starweaver** - High Elf Wizard, Level 1
+- **Shade Quickfingers** - Halfling Rogue, Level 1
+
+---
+
+## Hackathon Submission
+
+This project was built for the **MCP Hackathon 2025** on HuggingFace.
+
+### Track
+**Agentic Demo Track** - Showcasing the power of AI agents in gaming
+
+### Sponsor Technologies Used
+
+| Sponsor | Usage |
+|---------|-------|
+| **Gemini** | Primary LLM for DM narration and storytelling |
+| **OpenAI** | Fallback LLM for reliability |
+| **ElevenLabs** | Voice synthesis for immersive narration |
+| **LlamaIndex** | Agent framework and RAG-powered rules lookup |
+| **Blaxel** | TTRPG Toolkit MCP server hosting |
+| **Gradio** | UI framework for the demo |
+| **HuggingFace** | Application deployment |
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+## Acknowledgments
+
+- The D&D 5e SRD for game rules and content
+- The MCP protocol for enabling modular game systems
+- All the amazing open-source libraries that made this possible
+- The hackathon organizers and sponsors
+
+---
+
+**May your rolls be ever in your favor!**
+
+*Built with passion for tabletop gaming and AI technology.*

adventures/sample_characters/fighter_template.json

@@ -0,0 +1,147 @@
+{
+  "metadata": {
+    "template_name": "Valric the Bold",
+    "template_type": "fighter",
+    "description": "A classic sword-and-board fighter. Durable, straightforward, and reliable in combat.",
+    "playstyle": "Front-line defender and damage dealer. Simple to play, hard to kill."
+  },
+
+  "character": {
+    "name": "Valric the Bold",
+    "race": "Human",
+    "class": "Fighter",
+    "subclass": null,
+    "level": 1,
+    "background": "Soldier",
+    "alignment": "Lawful Good",
+
+    "ability_scores": {
+      "strength": 16,
+      "dexterity": 12,
+      "constitution": 15,
+      "intelligence": 10,
+      "wisdom": 13,
+      "charisma": 8
+    },
+
+    "proficiency_bonus": 2,
+
+    "saving_throws": {
+      "strength": 5,
+      "constitution": 4
+    },
+
+    "skills": {
+      "athletics": 5,
+      "intimidation": 1,
+      "perception": 3,
+      "survival": 3
+    },
+
+    "armor_class": 18,
+    "armor_class_breakdown": "Chain mail (16) + Shield (2)",
+
+    "hit_points": {
+      "maximum": 12,
+      "current": 12,
+      "temporary": 0
+    },
+
+    "hit_dice": {
+      "total": "1d10",
+      "remaining": 1
+    },
+
+    "speed": 30,
+
+    "attacks": [
+      {
+        "name": "Longsword",
+        "attack_bonus": 5,
+        "damage": "1d8+3",
+        "damage_type": "slashing",
+        "properties": ["versatile (1d10)"]
+      },
+      {
+        "name": "Longsword (Two-Handed)",
+        "attack_bonus": 5,
+        "damage": "1d10+3",
+        "damage_type": "slashing",
+        "properties": ["versatile"],
+        "notes": "When not using shield"
+      },
+      {
+        "name": "Handaxe (Thrown)",
+        "attack_bonus": 5,
+        "damage": "1d6+3",
+        "damage_type": "slashing",
+        "range": "20/60",
+        "properties": ["light", "thrown"]
+      }
+    ],
+
+    "equipment": {
+      "weapons": ["Longsword", "Shield", "2 Handaxes"],
+      "armor": ["Chain Mail"],
+      "other": [
+        "Explorer's Pack",
+        "Insignia of rank (military)",
+        "Trophy from fallen enemy (broken blade)",
+        "Set of bone dice",
+        "Common clothes"
+      ],
+      "currency": {
+        "gp": 10,
+        "sp": 0,
+        "cp": 0
+      }
+    },
+
+    "features": [
+      {
+        "name": "Fighting Style: Defense",
+        "description": "While wearing armor, you gain a +1 bonus to AC (already included)."
+      },
+      {
+        "name": "Second Wind",
+        "description": "On your turn, you can use a bonus action to regain 1d10 + 1 hit points. Once used, you must finish a short or long rest to use it again.",
+        "uses": 1,
+        "recharge": "short rest"
+      }
+    ],
+
+    "proficiencies": {
+      "armor": ["All armor", "Shields"],
+      "weapons": ["Simple weapons", "Martial weapons"],
+      "tools": ["Playing card set", "Vehicles (land)"],
+      "languages": ["Common", "Dwarvish"]
+    },
+
+    "personality": {
+      "traits": [
+        "I'm always polite and respectful.",
+        "I face problems head-on. A simple, direct solution is the best path to success."
+      ],
+      "ideals": ["Greater Good: Our lot is to lay down our lives in defense of others."],
+      "bonds": ["I fight for those who cannot fight for themselves."],
+      "flaws": ["I made a terrible mistake in battle that cost many lives, and I would do anything to keep that secret."]
+    },
+
+    "backstory": "Valric served in the king's army for five years, rising to the rank of sergeant. After a devastating battle where his unit was ambushed due to faulty intelligence, he was the sole survivor. Wracked with guilt and seeking redemption, he left military service to become an adventurer, hoping to save lives rather than take them. He's haunted by the faces of fallen comrades but channels that pain into protecting the innocent."
+  },
+
+  "tips": {
+    "combat": [
+      "Stay on the front line - you're the party's shield",
+      "Use your shield for high AC and tank hits",
+      "Save Second Wind for when you're below half HP",
+      "Handaxes are great for ranged enemies you can't reach"
+    ],
+    "roleplay": [
+      "Valric is formal and military in manner",
+      "He's protective of allies, sometimes overly so",
+      "He has nightmares about his past failure",
+      "He respects authority but questions orders that endanger innocents"
+    ]
+  }
+}

adventures/sample_characters/rogue_template.json

@@ -0,0 +1,178 @@
+{
+  "metadata": {
+    "template_name": "Shade Quickfingers",
+    "template_type": "rogue",
+    "description": "A cunning halfling rogue specializing in stealth and precision strikes.",
+    "playstyle": "Sneak, scout, and strike from the shadows. High single-target damage with Sneak Attack."
+  },
+
+  "character": {
+    "name": "Shade Quickfingers",
+    "race": "Lightfoot Halfling",
+    "class": "Rogue",
+    "subclass": null,
+    "level": 1,
+    "background": "Criminal",
+    "alignment": "Chaotic Good",
+
+    "ability_scores": {
+      "strength": 8,
+      "dexterity": 17,
+      "constitution": 12,
+      "intelligence": 13,
+      "wisdom": 10,
+      "charisma": 14
+    },
+
+    "proficiency_bonus": 2,
+
+    "saving_throws": {
+      "dexterity": 5,
+      "intelligence": 3
+    },
+
+    "skills": {
+      "acrobatics": 5,
+      "deception": 4,
+      "perception": 2,
+      "sleight_of_hand": 7,
+      "stealth": 7,
+      "thieves_tools": 7
+    },
+
+    "expertise": ["Stealth", "Thieves' Tools"],
+
+    "armor_class": 14,
+    "armor_class_breakdown": "Leather armor (11) + Dexterity modifier (3)",
+
+    "hit_points": {
+      "maximum": 9,
+      "current": 9,
+      "temporary": 0
+    },
+
+    "hit_dice": {
+      "total": "1d8",
+      "remaining": 1
+    },
+
+    "speed": 25,
+
+    "attacks": [
+      {
+        "name": "Shortsword",
+        "attack_bonus": 5,
+        "damage": "1d6+3",
+        "damage_type": "piercing",
+        "properties": ["finesse", "light"],
+        "notes": "Add 1d6 Sneak Attack when applicable"
+      },
+      {
+        "name": "Dagger",
+        "attack_bonus": 5,
+        "damage": "1d4+3",
+        "damage_type": "piercing",
+        "range": "20/60",
+        "properties": ["finesse", "light", "thrown"],
+        "notes": "Add 1d6 Sneak Attack when applicable"
+      },
+      {
+        "name": "Shortbow",
+        "attack_bonus": 5,
+        "damage": "1d6+3",
+        "damage_type": "piercing",
+        "range": "80/320",
+        "properties": ["ammunition", "two-handed"],
+        "notes": "Add 1d6 Sneak Attack when applicable"
+      }
+    ],
+
+    "equipment": {
+      "weapons": ["Shortsword", "Shortbow", "Quiver with 20 arrows", "2 Daggers"],
+      "armor": ["Leather Armor"],
+      "other": [
+        "Thieves' tools",
+        "Burglar's pack",
+        "Crowbar",
+        "Dark common clothes with hood",
+        "Belt pouch"
+      ],
+      "currency": {
+        "gp": 15,
+        "sp": 0,
+        "cp": 0
+      }
+    },
+
+    "features": [
+      {
+        "name": "Sneak Attack",
+        "description": "Once per turn, deal extra 1d6 damage when you have advantage on attack, or when an ally is within 5 feet of target. Must use finesse or ranged weapon.",
+        "damage": "1d6"
+      },
+      {
+        "name": "Expertise",
+        "description": "Double proficiency bonus for Stealth and Thieves' Tools (already calculated)."
+      },
+      {
+        "name": "Thieves' Cant",
+        "description": "Secret language of thieves. Can convey hidden messages and recognize signs left by other criminals."
+      },
+      {
+        "name": "Lucky",
+        "description": "When you roll a 1 on an attack roll, ability check, or saving throw, reroll and use the new roll.",
+        "source": "Halfling"
+      },
+      {
+        "name": "Brave",
+        "description": "Advantage on saving throws against being frightened.",
+        "source": "Halfling"
+      },
+      {
+        "name": "Halfling Nimbleness",
+        "description": "Move through the space of any creature that is of a size larger than yours.",
+        "source": "Halfling"
+      },
+      {
+        "name": "Naturally Stealthy",
+        "description": "Can attempt to hide even when obscured only by a creature at least one size larger than you.",
+        "source": "Lightfoot Halfling"
+      }
+    ],
+
+    "proficiencies": {
+      "armor": ["Light armor"],
+      "weapons": ["Simple weapons", "Hand crossbows", "Longswords", "Rapiers", "Shortswords"],
+      "tools": ["Thieves' tools", "Playing card set", "Disguise kit"],
+      "languages": ["Common", "Halfling", "Thieves' Cant"]
+    },
+
+    "personality": {
+      "traits": [
+        "I always have a plan for what to do when things go wrong.",
+        "I am incredibly slow to trust. Those who seem fairest often have the most to hide."
+      ],
+      "ideals": ["Freedom: Chains are meant to be broken, as are those who would forge them."],
+      "bonds": ["I'm trying to pay off a debt I owe to a generous benefactor who saved my life."],
+      "flaws": ["When I see something valuable, I can't think about anything but how to steal it."]
+    },
+
+    "backstory": "Shade grew up on the streets of Baldur's Gate, learning to survive through quick fingers and quicker wits. They fell in with the Guild, becoming a capable second-story worker. But when ordered to rob a family that reminded them of their own lost parents, Shade refused and fled the city with a price on their head. Now they use their skills for good, redistributing wealth from the corrupt to those in need. They're still paying off the debt to the mysterious benefactor who helped them escape - a debt that seems to grow rather than shrink."
+  },
+
+  "tips": {
+    "combat": [
+      "Always try to get Sneak Attack - it's most of your damage",
+      "Have an ally engage the enemy, then attack for Sneak Attack",
+      "Use Cunning Action (level 2) to Disengage after attacking",
+      "The shortbow lets you sneak attack from safety",
+      "Hide behind larger allies using Naturally Stealthy"
+    ],
+    "roleplay": [
+      "Shade is cautious and always looking for exits",
+      "They have a Robin Hood mentality - steal from the rich",
+      "They're paranoid about the Guild finding them",
+      "Despite their past, they have a good heart"
+    ]
+  }
+}

adventures/sample_characters/wizard_template.json

@@ -0,0 +1,255 @@
+{
+  "metadata": {
+    "template_name": "Elara Starweaver",
+    "template_type": "wizard",
+    "description": "An elven wizard specializing in evocation. Glass cannon with powerful offensive magic.",
+    "playstyle": "Stay in the back, cast spells, avoid getting hit. High damage but fragile."
+  },
+
+  "character": {
+    "name": "Elara Starweaver",
+    "race": "High Elf",
+    "class": "Wizard",
+    "subclass": null,
+    "level": 1,
+    "background": "Sage",
+    "alignment": "Neutral Good",
+
+    "ability_scores": {
+      "strength": 8,
+      "dexterity": 14,
+      "constitution": 13,
+      "intelligence": 16,
+      "wisdom": 12,
+      "charisma": 10
+    },
+
+    "proficiency_bonus": 2,
+
+    "saving_throws": {
+      "intelligence": 5,
+      "wisdom": 3
+    },
+
+    "skills": {
+      "arcana": 5,
+      "history": 5,
+      "investigation": 5,
+      "perception": 3
+    },
+
+    "armor_class": 12,
+    "armor_class_breakdown": "10 + Dexterity modifier (unarmored)",
+
+    "hit_points": {
+      "maximum": 7,
+      "current": 7,
+      "temporary": 0
+    },
+
+    "hit_dice": {
+      "total": "1d6",
+      "remaining": 1
+    },
+
+    "speed": 30,
+
+    "attacks": [
+      {
+        "name": "Fire Bolt",
+        "attack_bonus": 5,
+        "damage": "1d10",
+        "damage_type": "fire",
+        "range": "120 feet",
+        "properties": ["cantrip"]
+      },
+      {
+        "name": "Quarterstaff",
+        "attack_bonus": 1,
+        "damage": "1d6-1",
+        "damage_type": "bludgeoning",
+        "properties": ["versatile (1d8)"]
+      },
+      {
+        "name": "Dagger",
+        "attack_bonus": 4,
+        "damage": "1d4+2",
+        "damage_type": "piercing",
+        "range": "20/60",
+        "properties": ["finesse", "light", "thrown"]
+      }
+    ],
+
+    "spellcasting": {
+      "spellcasting_ability": "Intelligence",
+      "spell_save_dc": 13,
+      "spell_attack_bonus": 5,
+
+      "spell_slots": {
+        "1st": 2
+      },
+
+      "cantrips": [
+        {
+          "name": "Fire Bolt",
+          "casting_time": "1 action",
+          "range": "120 feet",
+          "components": "V, S",
+          "duration": "Instantaneous",
+          "description": "Hurl a mote of fire. Ranged spell attack for 1d10 fire damage."
+        },
+        {
+          "name": "Mage Hand",
+          "casting_time": "1 action",
+          "range": "30 feet",
+          "components": "V, S",
+          "duration": "1 minute",
+          "description": "A spectral hand that can manipulate objects up to 10 pounds."
+        },
+        {
+          "name": "Prestidigitation",
+          "casting_time": "1 action",
+          "range": "10 feet",
+          "components": "V, S",
+          "duration": "Up to 1 hour",
+          "description": "Minor magical tricks for practicing spellcasters."
+        },
+        {
+          "name": "Light",
+          "casting_time": "1 action",
+          "range": "Touch",
+          "components": "V, M (firefly or phosphorescent moss)",
+          "duration": "1 hour",
+          "description": "Object sheds bright light in 20-foot radius. (High Elf bonus cantrip)"
+        }
+      ],
+
+      "prepared_spells": [
+        {
+          "name": "Magic Missile",
+          "level": 1,
+          "casting_time": "1 action",
+          "range": "120 feet",
+          "components": "V, S",
+          "duration": "Instantaneous",
+          "description": "Three darts of magical force hit automatically for 1d4+1 force damage each."
+        },
+        {
+          "name": "Sleep",
+          "level": 1,
+          "casting_time": "1 action",
+          "range": "90 feet",
+          "components": "V, S, M (sand)",
+          "duration": "1 minute",
+          "description": "5d8 HP worth of creatures fall unconscious, starting with lowest HP."
+        },
+        {
+          "name": "Shield",
+          "level": 1,
+          "casting_time": "1 reaction",
+          "range": "Self",
+          "components": "V, S",
+          "duration": "1 round",
+          "description": "+5 AC until start of next turn, including against triggering attack."
+        },
+        {
+          "name": "Detect Magic",
+          "level": 1,
+          "casting_time": "1 action (ritual)",
+          "range": "Self",
+          "components": "V, S",
+          "duration": "10 minutes (concentration)",
+          "description": "Sense magic within 30 feet. Can see aura and determine school."
+        }
+      ],
+
+      "spellbook": [
+        "Magic Missile",
+        "Sleep",
+        "Shield",
+        "Detect Magic",
+        "Mage Armor",
+        "Thunderwave"
+      ]
+    },
+
+    "equipment": {
+      "weapons": ["Quarterstaff", "Dagger"],
+      "armor": [],
+      "other": [
+        "Spellbook",
+        "Component pouch",
+        "Scholar's pack",
+        "Bottle of black ink",
+        "Quill",
+        "Small knife",
+        "Letter from dead colleague with unanswered question",
+        "Common clothes"
+      ],
+      "currency": {
+        "gp": 10,
+        "sp": 0,
+        "cp": 0
+      }
+    },
+
+    "features": [
+      {
+        "name": "Arcane Recovery",
+        "description": "Once per day during a short rest, recover spell slots up to half your wizard level (rounded up). At level 1, recover one 1st-level slot.",
+        "uses": 1,
+        "recharge": "long rest"
+      },
+      {
+        "name": "Fey Ancestry",
+        "description": "Advantage on saving throws against being charmed. Magic can't put you to sleep.",
+        "source": "High Elf"
+      },
+      {
+        "name": "Darkvision",
+        "description": "See in dim light within 60 feet as if bright light, and darkness as dim light.",
+        "source": "High Elf"
+      },
+      {
+        "name": "Trance",
+        "description": "Elves don't sleep. Instead, meditate deeply for 4 hours to gain rest benefits.",
+        "source": "High Elf"
+      }
+    ],
+
+    "proficiencies": {
+      "armor": [],
+      "weapons": ["Daggers", "Darts", "Slings", "Quarterstaffs", "Light crossbows", "Longsword", "Shortsword", "Shortbow", "Longbow"],
+      "tools": [],
+      "languages": ["Common", "Elvish", "Draconic", "Celestial"]
+    },
+
+    "personality": {
+      "traits": [
+        "I'm used to helping out those who aren't as smart as I am.",
+        "I'm willing to listen to every side of an argument before I make my own judgment."
+      ],
+      "ideals": ["Knowledge: The path to power and self-improvement is through knowledge."],
+      "bonds": ["I've been searching my whole life for the answer to a certain question about the nature of magic."],
+      "flaws": ["I overlook obvious solutions in favor of complicated ones."]
+    },
+
+    "backstory": "Elara spent two centuries in the great elven library of Myth Drannor, studying the fundamental nature of magic. When she discovered a fragment of a text hinting at a unified theory of arcane and divine magic, she left the safety of her studies to seek more fragments scattered across the world. She's brilliant but sometimes condescending, and tends to overcomplicate simple problems. The destroyed library haunts her dreams - she arrived a day late to save it."
+  },
+
+  "tips": {
+    "combat": [
+      "Stay FAR from enemies - you have only 7 HP!",
+      "Fire Bolt is your bread and butter cantrip",
+      "Magic Missile never misses - use on important targets",
+      "Sleep can trivialize early encounters",
+      "Save Shield for critical hits or when you'll drop to 0 HP"
+    ],
+    "roleplay": [
+      "Elara speaks formally and uses academic terminology",
+      "She's curious about all forms of magic",
+      "She can be condescending but means well",
+      "She's haunted by the loss of her library"
+    ]
+  }
+}

adventures/tavern_start.json

@@ -0,0 +1,266 @@
+{
+  "metadata": {
+    "name": "The Rusty Dragon Tavern",
+    "description": "A classic tavern start. Meet colorful NPCs, hear rumors, and find your first adventure hook. The perfect sandbox beginning.",
+    "difficulty": "easy",
+    "estimated_time": "open-ended",
+    "recommended_level": 1,
+    "tags": ["social", "sandbox", "roleplay", "starter"],
+    "author": "DungeonMaster AI",
+    "version": "1.0.0"
+  },
+
+  "starting_scene": {
+    "scene_id": "tavern_common_room",
+    "image": "tavern",
+    "narrative": "The door of the Rusty Dragon creaks open, releasing a wave of warmth, laughter, and the mouthwatering aroma of roasting meat. This famous establishment sits at the crossroads of adventure - a place where mercenaries find work, travelers share tales, and heroes are born. The common room buzzes with activity. A crackling fire wards off the evening chill. What catches your attention first?",
+    "context": {
+      "time_of_day": "evening",
+      "weather": "clear but cold outside",
+      "mood": "warm and bustling"
+    }
+  },
+
+  "scenes": [
+    {
+      "scene_id": "tavern_common_room",
+      "name": "The Common Room",
+      "image": "tavern",
+      "description": "The heart of the Rusty Dragon - a large room filled with wooden tables, a roaring fireplace, and the sounds of merriment.",
+      "details": {
+        "sensory": {
+          "sight": "Adventurers of all stripes crowd the tables. A half-orc arm-wrestles a dwarf. A hooded figure sits alone in the corner. The bartender, a jovial woman, pulls ale from a massive cask.",
+          "sound": "Laughter, the clink of mugs, a bard strumming in the corner, and snippets of a dozen conversations.",
+          "smell": "Roasted boar, fresh bread, spilled ale, and pipe smoke."
+        },
+        "notable_features": [
+          "A job board near the entrance, covered in notices",
+          "A large fireplace with comfortable chairs",
+          "The bar where drinks flow freely",
+          "A corner where a mysterious figure lurks"
+        ]
+      },
+      "exits": {
+        "outside": "village_square",
+        "upstairs": "inn_rooms",
+        "back": "kitchen"
+      },
+      "npcs_present": ["marta_innkeeper", "bard_silverstring", "mysterious_stranger", "gruff_dwarf"],
+      "items": [],
+      "encounter": null
+    },
+    {
+      "scene_id": "village_square",
+      "name": "Crossroads Village Square",
+      "image": "village",
+      "description": "The village square where several roads meet. Shops line the streets, and a notice board stands near a well.",
+      "details": {
+        "sensory": {
+          "sight": "Cobblestone streets lit by lanterns. A general store, blacksmith, and temple are visible.",
+          "sound": "The distant bark of a dog. The town bell marking the hour.",
+          "smell": "Night air, coal smoke from the smithy."
+        }
+      },
+      "exits": {
+        "tavern": "tavern_common_room",
+        "north_road": "north_road_start",
+        "east_road": "east_road_start",
+        "general_store": "general_store",
+        "blacksmith": "blacksmith_shop"
+      },
+      "npcs_present": [],
+      "items": [],
+      "encounter": null
+    },
+    {
+      "scene_id": "inn_rooms",
+      "name": "Inn Rooms (Upstairs)",
+      "image": "tavern",
+      "description": "A hallway with several doors leading to modest but clean rooms for rent.",
+      "details": {
+        "sensory": {
+          "sight": "Worn wooden floors, numbered doors, a window overlooking the square.",
+          "sound": "Muffled revelry from below. Someone snoring behind one door.",
+          "smell": "Clean linens and old wood."
+        }
+      },
+      "exits": {
+        "downstairs": "tavern_common_room"
+      },
+      "npcs_present": [],
+      "items": [],
+      "encounter": null
+    }
+  ],
+
+  "npcs": [
+    {
+      "npc_id": "marta_innkeeper",
+      "name": "Marta Brightkettle",
+      "description": "A stout, red-cheeked woman with kind eyes and a booming laugh. She runs the Rusty Dragon with an iron will and a warm heart.",
+      "personality": "Motherly but shrewd. Knows everyone's business but keeps secrets well. Quick with advice and quicker with a rolling pin for troublemakers.",
+      "voice_profile": "npc_female_gentle",
+      "dialogue_hooks": [
+        "Welcome, welcome! Sit yourself down. You look like you could use a hot meal and a cold drink!",
+        "New in town, are you? Well, you've come to the right place. The Rusty Dragon sees all sorts.",
+        "Looking for work? Check the notice board. Plenty of folk need capable hands these days.",
+        "That one in the corner? Been here three days, hardly speaks. Gives me the shivers, but pays in gold."
+      ],
+      "knowledge": [
+        "Knows all the local gossip",
+        "Can point adventurers to the job board",
+        "Knows the mysterious stranger has been asking about 'the old tower'",
+        "Her husband was an adventurer who never returned from the northern mountains"
+      ],
+      "services": {
+        "room": "5 sp per night",
+        "meal": "3 sp",
+        "ale": "4 cp",
+        "information": "Freely given to paying customers"
+      }
+    },
+    {
+      "npc_id": "bard_silverstring",
+      "name": "Lyric Silverstring",
+      "description": "A flamboyant half-elf bard with silver-streaked hair and an infectious smile. Plays a well-worn lute.",
+      "personality": "Dramatic, curious, and always looking for the next great story. Collects tales of heroism.",
+      "voice_profile": "npc_mysterious",
+      "dialogue_hooks": [
+        "Ah, new faces! New stories! Come, sit, tell me of your travels!",
+        "I've performed from Waterdeep to Baldur's Gate, but the best tales are found in places like this.",
+        "Looking for adventure? I heard the merchant over there needs an escort through the Thornwood.",
+        "Buy me a drink and I'll tell you the legend of the Weeping Tower. Locals don't like to speak of it..."
+      ],
+      "knowledge": [
+        "Knows legends and lore of the region",
+        "Has heard rumors of undead in the northern hills",
+        "Knows the mysterious stranger is a wizard seeking something",
+        "Can tell the full story of the Weeping Tower for a drink"
+      ],
+      "quest_hooks": [
+        "Offers 20 gp for any adventurer who brings back a firsthand account of something legendary"
+      ]
+    },
+    {
+      "npc_id": "mysterious_stranger",
+      "name": "The Hooded Figure (Valdris)",
+      "description": "A thin figure in a dark cloak, face hidden in shadow. Pale hands curl around an untouched drink. Arcane symbols occasionally flicker on their sleeves.",
+      "personality": "Secretive, calculating, but ultimately good-intentioned. A wizard on a personal quest.",
+      "voice_profile": "npc_mysterious",
+      "dialogue_hooks": [
+        "...You have the look of capable souls. Perhaps we can help each other.",
+        "I seek the Weeping Tower. Dark forces stir there, and I must stop them before it's too late.",
+        "I am Valdris. My order has watched the tower for centuries. Now, something has awakened.",
+        "I can offer gold, knowledge, magical aid. I only need brave companions willing to face the darkness."
+      ],
+      "knowledge": [
+        "Knows the location of the Weeping Tower",
+        "Knows a necromancer has taken residence there",
+        "Has a map to the tower",
+        "Can identify magical items"
+      ],
+      "quest_hooks": [
+        "Offers 100 gp each to investigate the Weeping Tower",
+        "Provides a potion of healing to each party member who agrees",
+        "Promises magical knowledge as additional reward"
+      ]
+    },
+    {
+      "npc_id": "gruff_dwarf",
+      "name": "Thorin Ironbeard",
+      "description": "A heavily scarred dwarf in worn armor, nursing a tankard. His shield bears the marks of many battles.",
+      "personality": "Gruff, skeptical of newcomers, but fiercely loyal once trust is earned. Veteran adventurer.",
+      "voice_profile": "npc_male_gruff",
+      "dialogue_hooks": [
+        "*grunts* Another fresh face looking for glory. Hope ye last longer than the last ones.",
+        "I've been delving dungeons since before yer parents were born. Want advice? Don't trust maps.",
+        "That wizard in the corner? Been trying to recruit fools for days. Job's too dangerous, I say.",
+        "Buy me an ale and I'll tell ye about the time I fought a dragon. Mostly true, too."
+      ],
+      "knowledge": [
+        "Veteran adventurer with practical dungeon experience",
+        "Knows the northern mountains are full of orc tribes",
+        "Has heard of the Weeping Tower - lost a friend there years ago",
+        "Can give practical combat advice"
+      ],
+      "quest_hooks": [
+        "Might join the party if impressed by their character",
+        "Knows the location of an old dwarven outpost with rumored treasure"
+      ]
+    }
+  ],
+
+  "job_board_notices": [
+    {
+      "title": "RATS IN THE CELLAR",
+      "description": "The general store has a rat problem. Nothing a capable adventurer can't handle.",
+      "reward": "5 gp",
+      "difficulty": "trivial",
+      "contact": "Merchant Gravis at the General Store"
+    },
+    {
+      "title": "MISSING LIVESTOCK",
+      "description": "Something has been taking sheep from the Miller farm at night. Tracks lead to the forest.",
+      "reward": "20 gp",
+      "difficulty": "easy",
+      "contact": "Farmer Miller, north road, first farm"
+    },
+    {
+      "title": "ESCORT NEEDED",
+      "description": "Merchant caravan needs guards for journey through Thornwood. Three days travel.",
+      "reward": "15 gp per person",
+      "difficulty": "easy to medium",
+      "contact": "Merchant Consortium, departing in two days"
+    },
+    {
+      "title": "WANTED: INFORMATION",
+      "description": "Seeking any knowledge about the whereabouts of the wizard Mordecai. Last seen heading north.",
+      "reward": "50 gp for confirmed location",
+      "difficulty": "unknown",
+      "contact": "Ask Marta - anonymous posting"
+    },
+    {
+      "title": "HELP WANTED - BRAVE SOULS ONLY",
+      "description": "The old watchtower on the hill has shown lights at night. Town council seeks investigation.",
+      "reward": "30 gp plus whatever you find",
+      "difficulty": "medium",
+      "contact": "Mayor Aldric at Town Hall"
+    }
+  ],
+
+  "rumors": [
+    {
+      "source": "overheard",
+      "rumor": "They say the dead walk in the northern hills at night. No one goes there anymore.",
+      "truth_level": "mostly_true"
+    },
+    {
+      "source": "drunk_patron",
+      "rumor": "My cousin saw a dragon flying over the mountains last month! Big as a barn!",
+      "truth_level": "exaggerated"
+    },
+    {
+      "source": "merchant",
+      "rumor": "Trade from the east has stopped. Something's happening in the Thornwood.",
+      "truth_level": "true"
+    },
+    {
+      "source": "old_timer",
+      "rumor": "The Weeping Tower has been silent for a hundred years. If lights are showing... that's bad news.",
+      "truth_level": "true"
+    }
+  ],
+
+  "encounters": [],
+
+  "victory_conditions": {
+    "primary": {
+      "description": "This is a sandbox start - there is no set victory condition",
+      "trigger": "player_chooses_adventure",
+      "narrative": "The night stretches before you full of possibilities. Which path will you choose?"
+    },
+    "optional": []
+  },
+
+  "completion_narrative": "The Rusty Dragon has served its purpose - you've rested, gathered information, and found purpose. Whatever adventure you choose, you leave this tavern more prepared than when you arrived. The road ahead beckons. Where will your story take you?"
+}

adventures/tutorial_goblin_cave.json

@@ -0,0 +1,280 @@
+{
+  "metadata": {
+    "name": "The Goblin Cave",
+    "description": "A beginner-friendly adventure where heroes investigate goblin raids on a nearby village. Perfect for learning the basics of D&D combat and exploration.",
+    "difficulty": "easy",
+    "estimated_time": "30-45 minutes",
+    "recommended_level": 1,
+    "tags": ["tutorial", "combat", "exploration", "goblins"],
+    "author": "DungeonMaster AI",
+    "version": "1.0.0"
+  },
+
+  "starting_scene": {
+    "scene_id": "forest_path",
+    "image": "forest",
+    "narrative": "The forest path winds before you, dappled sunlight filtering through ancient oaks. You've been hired by the village of Millbrook to investigate goblin raids that have plagued local farms. A woodcutter reported seeing the creatures disappear into the hills to the north. The trail of small footprints and discarded chicken bones leads you here, to the edge of a rocky outcropping where a dark cave mouth yawns like a hungry maw.",
+    "context": {
+      "time_of_day": "afternoon",
+      "weather": "clear",
+      "mood": "tense"
+    }
+  },
+
+  "scenes": [
+    {
+      "scene_id": "forest_path",
+      "name": "Forest Path",
+      "image": "forest",
+      "description": "A well-worn dirt path through dense forest. Broken branches and scattered refuse mark where goblins have passed.",
+      "details": {
+        "sensory": {
+          "sight": "Sunlight streams through the canopy. Small footprints dot the muddy path.",
+          "sound": "Birds have fallen silent. Distant chittering echoes from the hills.",
+          "smell": "Pine needles and something fouler - rotting meat perhaps."
+        },
+        "searchable": [
+          {
+            "object": "footprints",
+            "dc": 10,
+            "skill": "Survival",
+            "success": "At least six goblins passed this way recently, maybe within the last day. They were dragging something heavy.",
+            "failure": "The footprints are too jumbled to make out details."
+          }
+        ]
+      },
+      "exits": {
+        "north": "cave_entrance",
+        "south": "millbrook_village"
+      },
+      "npcs_present": [],
+      "items": [],
+      "encounter": null
+    },
+    {
+      "scene_id": "cave_entrance",
+      "name": "Cave Entrance",
+      "image": "cave",
+      "description": "A jagged cave mouth opens in the hillside. Crude scratches mark the stone, and the stench of goblins wafts from within.",
+      "details": {
+        "sensory": {
+          "sight": "The cave opening is about 8 feet wide and 6 feet tall. Darkness swallows everything beyond the first few feet.",
+          "sound": "Faint cackling and the clatter of bones echoes from inside.",
+          "smell": "Unwashed bodies, spoiled food, and smoke."
+        },
+        "searchable": [
+          {
+            "object": "cave_entrance_area",
+            "dc": 12,
+            "skill": "Perception",
+            "success": "You spot a crude tripwire stretched across the entrance, about ankle height. A pile of loose stones sits precariously above.",
+            "failure": "The entrance appears unguarded."
+          }
+        ],
+        "traps": [
+          {
+            "name": "Falling Rocks Trap",
+            "trigger": "tripwire at entrance",
+            "dc_detect": 12,
+            "dc_disarm": 10,
+            "effect": "2d6 bludgeoning damage, DC 12 Dexterity save for half",
+            "description": "Loose stones tumble down from above!"
+          }
+        ]
+      },
+      "exits": {
+        "inside": "guard_room",
+        "south": "forest_path"
+      },
+      "npcs_present": [],
+      "items": [],
+      "encounter": null
+    },
+    {
+      "scene_id": "guard_room",
+      "name": "Guard Room",
+      "image": "dungeon",
+      "description": "A rough-hewn chamber lit by a sputtering torch. Two goblins crouch around a pile of dice, arguing in their guttural tongue.",
+      "details": {
+        "sensory": {
+          "sight": "Shadows dance on uneven walls. A passage continues deeper, and another branches left.",
+          "sound": "The goblins bicker over their gambling. One accuses the other of cheating.",
+          "smell": "Torch smoke and goblin musk."
+        }
+      },
+      "exits": {
+        "deeper": "chieftain_chamber",
+        "left": "treasure_room",
+        "back": "cave_entrance"
+      },
+      "npcs_present": [],
+      "items": [
+        {
+          "name": "Crude Dice",
+          "description": "Bone dice with suspicious weighting",
+          "value": "1 sp"
+        }
+      ],
+      "encounter": {
+        "encounter_id": "goblin_guards",
+        "trigger": "automatic",
+        "surprise_dc": 12
+      }
+    },
+    {
+      "scene_id": "treasure_room",
+      "name": "Treasure Stash",
+      "image": "dungeon",
+      "description": "A smaller cave filled with the goblins' ill-gotten gains. Sacks of stolen grain, a chicken in a cage, and a small chest.",
+      "details": {
+        "sensory": {
+          "sight": "Heaps of mundane stolen goods. A locked wooden chest catches your eye.",
+          "sound": "The chicken clucks nervously.",
+          "smell": "Grain, feathers, and old leather."
+        },
+        "searchable": [
+          {
+            "object": "chest",
+            "dc": 12,
+            "skill": "Thieves' Tools or Strength",
+            "success": "The chest opens to reveal 25 gold pieces and a potion of healing!",
+            "failure": "The lock holds fast."
+          }
+        ]
+      },
+      "exits": {
+        "back": "guard_room"
+      },
+      "npcs_present": [],
+      "items": [
+        {
+          "name": "Stolen Grain",
+          "description": "Sacks of wheat and barley from Millbrook farms",
+          "value": "5 gp"
+        },
+        {
+          "name": "Frightened Chicken",
+          "description": "A hen that seems relieved to see non-goblins",
+          "value": "2 sp"
+        }
+      ],
+      "encounter": null
+    },
+    {
+      "scene_id": "chieftain_chamber",
+      "name": "Chieftain's Chamber",
+      "image": "dungeon",
+      "description": "The largest cave, where the goblin boss sits on a throne of bones. A massive wolf growls at his side.",
+      "details": {
+        "sensory": {
+          "sight": "A goblin larger than the others wears a rusty crown. His pet wolf bares yellowed fangs.",
+          "sound": "The wolf's low growl. The chieftain's cackling laugh.",
+          "smell": "Blood and wet fur."
+        }
+      },
+      "exits": {
+        "back": "guard_room"
+      },
+      "npcs_present": ["goblin_boss"],
+      "items": [
+        {
+          "name": "Rusty Crown",
+          "description": "A dented iron crown, worthless but treasured by its owner",
+          "value": "5 sp"
+        },
+        {
+          "name": "Boss's Stash",
+          "description": "A leather pouch with 15 gold pieces",
+          "value": "15 gp"
+        }
+      ],
+      "encounter": {
+        "encounter_id": "goblin_boss_fight",
+        "trigger": "automatic",
+        "surprise_dc": null
+      }
+    }
+  ],
+
+  "npcs": [
+    {
+      "npc_id": "goblin_boss",
+      "name": "Grukk the Goblin Boss",
+      "description": "A larger, meaner goblin who has crowned himself king of this small tribe",
+      "personality": "Cowardly but cruel, Grukk bullies those weaker than him",
+      "voice_profile": "monster",
+      "dialogue_hooks": [
+        "Flee, pink-skin, or Grukk feeds you to Bitey!",
+        "This Grukk's cave! Grukk's treasure!",
+        "Mercy! Grukk surrender! Grukk tell you where more gold is!"
+      ],
+      "monster_stat_block": "goblin_boss"
+    }
+  ],
+
+  "encounters": [
+    {
+      "encounter_id": "goblin_guards",
+      "name": "Goblin Guards",
+      "description": "Two goblins guarding the cave entrance, distracted by gambling",
+      "enemies": [
+        {"monster": "goblin", "count": 2}
+      ],
+      "difficulty": "easy",
+      "tactics": "The goblins shriek an alarm and attack. One tries to flee deeper into the cave if badly wounded.",
+      "rewards": {
+        "xp": 50,
+        "loot": "2d6 copper pieces on each goblin"
+      }
+    },
+    {
+      "encounter_id": "goblin_boss_fight",
+      "name": "Grukk and Bitey",
+      "description": "The goblin boss and his pet wolf make their stand",
+      "enemies": [
+        {"monster": "goblin_boss", "count": 1, "name": "Grukk"},
+        {"monster": "wolf", "count": 1, "name": "Bitey"}
+      ],
+      "difficulty": "medium",
+      "tactics": "Grukk hangs back and uses his Redirect Attack while Bitey charges. If reduced to half HP, Grukk begs for mercy and offers information about a 'bigger treasure' (a lie).",
+      "rewards": {
+        "xp": 150,
+        "loot": "Grukk's stash, rusty crown"
+      }
+    }
+  ],
+
+  "loot_tables": [
+    {
+      "table_id": "goblin_pockets",
+      "items": [
+        {"weight": 40, "result": "1d6 copper pieces"},
+        {"weight": 30, "result": "2d6 copper pieces"},
+        {"weight": 20, "result": "1d6 silver pieces"},
+        {"weight": 10, "result": "A shiny stone (worthless but pretty)"}
+      ]
+    }
+  ],
+
+  "victory_conditions": {
+    "primary": {
+      "description": "Defeat or drive off the goblin threat",
+      "trigger": "goblin_boss_fight encounter completed",
+      "narrative": "With Grukk defeated, the goblin threat to Millbrook is ended. The villagers will be overjoyed to hear of your success!"
+    },
+    "optional": [
+      {
+        "description": "Recover the stolen goods",
+        "trigger": "visit treasure_room and take stolen_grain",
+        "reward": "Extra 10 gp reward from grateful farmers"
+      },
+      {
+        "description": "Save the chicken",
+        "trigger": "take frightened_chicken from treasure_room",
+        "reward": "Free eggs for life from a grateful farmer"
+      }
+    ]
+  },
+
+  "completion_narrative": "As you emerge from the cave, victorious, the afternoon sun feels warmer somehow. The threat that plagued Millbrook is ended. When you return to the village, you'll be hailed as heroes. But this is only the beginning - word of your deeds will spread, and greater adventures await. For now, though, you've earned a hot meal and a soft bed at the Millbrook Inn."
+}

app.py

@@ -1,7 +1,21 @@
-import gradio as gr
+"""
+DungeonMaster AI - HuggingFace Spaces Entry Point
 
-def greet(name):
-    return "Hello " + name + "!!"
+This is the main entry point for the HuggingFace Spaces deployment.
+It imports and launches the Gradio application from ui/app.py.
+"""
 
-demo = gr.Interface(fn=greet, inputs="text", outputs="text")
-demo.launch()
+import os
+import sys
+
+# Add the project root to the path for imports
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+# Import and run the main application
+from ui.app import create_app, main
+
+if __name__ == "__main__":
+    main()
+else:
+    # For Gradio Spaces, create the app object
+    demo = create_app()

pyproject.toml

@@ -0,0 +1,136 @@
+[project]
+name = "dungeonmaster-ai"
+version = "1.0.0"
+description = "AI-powered D&D 5e Game Master with voice narration, powered by TTRPG Toolkit MCP"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "DungeonMaster AI Team" }
+]
+keywords = [
+    "dnd",
+    "dungeon-master",
+    "ai",
+    "mcp",
+    "gradio",
+    "voice",
+    "ttrpg",
+    "game-master",
+    "elevenlabs",
+    "gemini",
+    "llama-index"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Games/Entertainment :: Role-Playing",
+]
+
+dependencies = [
+    # UI Framework
+    "gradio>=6.0.0",
+
+    # Agent Framework - LlamaIndex
+    "llama-index>=0.14.0",
+    "llama-index-tools-mcp",
+    "llama-index-llms-gemini",
+
+    # LLM APIs
+    "google-generativeai>=0.8.0",
+    "openai>=1.50.0",
+    "google-genai",
+
+    # Voice
+    "elevenlabs>=1.0.0",
+
+    # MCP
+    "mcp>=1.0.0",
+
+    # Core
+    "pydantic>=2.9.0",
+    "pydantic-settings>=2.5.0",
+    "python-dotenv>=1.0.0",
+    "aiohttp>=3.10.0",
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "ruff>=0.6.0",
+    "mypy>=1.11.0",
+]
+
+[project.scripts]
+dungeonmaster = "ui.app:main"
+
+[project.urls]
+Homepage = "https://huggingface.co/spaces/dungeonmaster-ai/dungeonmaster-ai"
+Repository = "https://github.com/dungeonmaster-ai/dungeonmaster-ai"
+Issues = "https://github.com/dungeonmaster-ai/dungeonmaster-ai/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src", "ui"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG",    # flake8-unused-arguments
+    "SIM",    # flake8-simplify
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+    "B008",   # do not perform function calls in argument defaults
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["src", "ui"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+strict_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+[[tool.mypy.overrides]]
+module = [
+    "llama_index.*",
+    "google.generativeai.*",
+    "gradio.*",
+    "elevenlabs.*",
+    "mcp.*",
+]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"

requirements.txt

@@ -0,0 +1,527 @@
+# This file was autogenerated by uv via the following command:
+#    uv export --no-dev --no-hashes -o requirements.txt
+-e .
+aiofiles==24.1.0
+    # via gradio
+aiohappyeyeballs==2.6.1
+    # via aiohttp
+aiohttp==3.13.2
+    # via
+    #   dungeonmaster-ai
+    #   llama-index-core
+aiosignal==1.4.0
+    # via aiohttp
+aiosqlite==0.21.0
+    # via llama-index-core
+annotated-doc==0.0.4
+    # via fastapi
+annotated-types==0.7.0
+    # via pydantic
+anyio==4.12.0
+    # via
+    #   google-genai
+    #   gradio
+    #   httpx
+    #   mcp
+    #   openai
+    #   sse-starlette
+    #   starlette
+async-timeout==5.0.1 ; python_full_version < '3.11'
+    # via aiohttp
+attrs==25.4.0
+    # via
+    #   aiohttp
+    #   jsonschema
+    #   referencing
+audioop-lts==0.2.2 ; python_full_version >= '3.13'
+    # via gradio
+banks==2.2.0
+    # via llama-index-core
+beautifulsoup4==4.14.2
+    # via llama-index-readers-file
+brotli==1.2.0
+    # via gradio
+cachetools==6.2.2
+    # via google-auth
+certifi==2025.11.12
+    # via
+    #   httpcore
+    #   httpx
+    #   llama-cloud
+    #   requests
+cffi==2.0.0 ; platform_python_implementation != 'PyPy'
+    # via cryptography
+charset-normalizer==3.4.4
+    # via requests
+click==8.3.1
+    # via
+    #   llama-cloud-services
+    #   nltk
+    #   typer
+    #   typer-slim
+    #   uvicorn
+colorama==0.4.6
+    # via
+    #   click
+    #   griffe
+    #   tqdm
+cryptography==46.0.3
+    # via pyjwt
+dataclasses-json==0.6.7
+    # via llama-index-core
+defusedxml==0.7.1
+    # via llama-index-readers-file
+deprecated==1.2.18
+    # via
+    #   banks
+    #   llama-index-core
+    #   llama-index-indices-managed-llama-cloud
+    #   llama-index-instrumentation
+dirtyjson==1.0.8
+    # via llama-index-core
+distro==1.9.0
+    # via openai
+elevenlabs==2.24.0
+    # via dungeonmaster-ai
+exceptiongroup==1.3.1 ; python_full_version < '3.11'
+    # via anyio
+fastapi==0.122.0
+    # via gradio
+ffmpy==1.0.0
+    # via gradio
+filelock==3.20.0
+    # via huggingface-hub
+filetype==1.2.0
+    # via llama-index-core
+frozenlist==1.8.0
+    # via
+    #   aiohttp
+    #   aiosignal
+fsspec==2025.10.0
+    # via
+    #   gradio-client
+    #   huggingface-hub
+    #   llama-index-core
+google-ai-generativelanguage==0.6.15
+    # via google-generativeai
+google-api-core==2.25.2 ; python_full_version >= '3.14'
+    # via
+    #   google-ai-generativelanguage
+    #   google-api-python-client
+    #   google-generativeai
+google-api-core==2.28.1 ; python_full_version < '3.14'
+    # via
+    #   google-ai-generativelanguage
+    #   google-api-python-client
+    #   google-generativeai
+google-api-python-client==2.187.0
+    # via google-generativeai
+google-auth==2.43.0
+    # via
+    #   google-ai-generativelanguage
+    #   google-api-core
+    #   google-api-python-client
+    #   google-auth-httplib2
+    #   google-genai
+    #   google-generativeai
+google-auth-httplib2==0.2.1
+    # via google-api-python-client
+google-genai==1.52.0
+    # via dungeonmaster-ai
+google-generativeai==0.8.5
+    # via
+    #   dungeonmaster-ai
+    #   llama-index-llms-gemini
+googleapis-common-protos==1.72.0
+    # via
+    #   google-api-core
+    #   grpcio-status
+gradio==6.0.1
+    # via dungeonmaster-ai
+gradio-client==2.0.0
+    # via gradio
+greenlet==3.2.4
+    # via sqlalchemy
+griffe==1.15.0
+    # via banks
+groovy==0.1.2
+    # via gradio
+grpcio==1.76.0
+    # via
+    #   google-api-core
+    #   grpcio-status
+grpcio-status==1.71.2
+    # via google-api-core
+h11==0.16.0
+    # via
+    #   httpcore
+    #   uvicorn
+hf-xet==1.2.0 ; platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'
+    # via huggingface-hub
+httpcore==1.0.9
+    # via httpx
+httplib2==0.31.0
+    # via
+    #   google-api-python-client
+    #   google-auth-httplib2
+httpx==0.28.1
+    # via
+    #   dungeonmaster-ai
+    #   elevenlabs
+    #   google-genai
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   llama-cloud
+    #   llama-index-core
+    #   mcp
+    #   openai
+    #   safehttpx
+httpx-sse==0.4.3
+    # via mcp
+huggingface-hub==1.1.6
+    # via
+    #   gradio
+    #   gradio-client
+idna==3.11
+    # via
+    #   anyio
+    #   httpx
+    #   requests
+    #   yarl
+jinja2==3.1.6
+    # via
+    #   banks
+    #   gradio
+jiter==0.12.0
+    # via openai
+joblib==1.5.2
+    # via nltk
+jsonschema==4.25.1
+    # via mcp
+jsonschema-specifications==2025.9.1
+    # via jsonschema
+llama-cloud==0.1.35
+    # via
+    #   llama-cloud-services
+    #   llama-index-indices-managed-llama-cloud
+llama-cloud-services==0.6.54
+    # via llama-parse
+llama-index==0.14.8
+    # via dungeonmaster-ai
+llama-index-cli==0.5.3
+    # via llama-index
+llama-index-core==0.14.8
+    # via
+    #   llama-cloud-services
+    #   llama-index
+    #   llama-index-cli
+    #   llama-index-embeddings-openai
+    #   llama-index-indices-managed-llama-cloud
+    #   llama-index-llms-gemini
+    #   llama-index-llms-openai
+    #   llama-index-readers-file
+    #   llama-index-readers-llama-parse
+    #   llama-index-tools-mcp
+llama-index-embeddings-openai==0.5.1
+    # via
+    #   llama-index
+    #   llama-index-cli
+llama-index-indices-managed-llama-cloud==0.9.4
+    # via llama-index
+llama-index-instrumentation==0.4.2
+    # via llama-index-workflows
+llama-index-llms-gemini==0.6.1
+    # via dungeonmaster-ai
+llama-index-llms-openai==0.6.10
+    # via
+    #   llama-index
+    #   llama-index-cli
+llama-index-readers-file==0.5.5
+    # via llama-index
+llama-index-readers-llama-parse==0.5.1
+    # via llama-index
+llama-index-tools-mcp==0.4.3
+    # via dungeonmaster-ai
+llama-index-workflows==2.11.5
+    # via llama-index-core
+llama-parse==0.6.54
+    # via llama-index-readers-llama-parse
+markdown-it-py==4.0.0
+    # via rich
+markupsafe==3.0.3
+    # via
+    #   gradio
+    #   jinja2
+marshmallow==3.26.1
+    # via dataclasses-json
+mcp==1.22.0
+    # via
+    #   dungeonmaster-ai
+    #   llama-index-tools-mcp
+mdurl==0.1.2
+    # via markdown-it-py
+multidict==6.7.0
+    # via
+    #   aiohttp
+    #   yarl
+mypy-extensions==1.1.0
+    # via typing-inspect
+nest-asyncio==1.6.0
+    # via llama-index-core
+networkx==3.4.2 ; python_full_version < '3.11'
+    # via llama-index-core
+networkx==3.6 ; python_full_version >= '3.11'
+    # via llama-index-core
+nltk==3.9.2
+    # via
+    #   llama-index
+    #   llama-index-core
+numpy==2.2.6 ; python_full_version < '3.11'
+    # via
+    #   gradio
+    #   llama-index-core
+    #   pandas
+numpy==2.3.5 ; python_full_version >= '3.11'
+    # via
+    #   gradio
+    #   llama-index-core
+    #   pandas
+openai==2.8.1
+    # via
+    #   dungeonmaster-ai
+    #   llama-index-embeddings-openai
+    #   llama-index-llms-openai
+orjson==3.11.4
+    # via gradio
+packaging==25.0
+    # via
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   marshmallow
+pandas==2.2.3
+    # via
+    #   gradio
+    #   llama-index-readers-file
+pillow==10.4.0
+    # via
+    #   gradio
+    #   llama-index-core
+    #   llama-index-llms-gemini
+platformdirs==4.5.0
+    # via
+    #   banks
+    #   llama-cloud-services
+    #   llama-index-core
+propcache==0.4.1
+    # via
+    #   aiohttp
+    #   yarl
+proto-plus==1.26.1
+    # via
+    #   google-ai-generativelanguage
+    #   google-api-core
+protobuf==5.29.5
+    # via
+    #   google-ai-generativelanguage
+    #   google-api-core
+    #   google-generativeai
+    #   googleapis-common-protos
+    #   grpcio-status
+    #   proto-plus
+pyasn1==0.6.1
+    # via
+    #   pyasn1-modules
+    #   rsa
+pyasn1-modules==0.4.2
+    # via google-auth
+pycparser==2.23 ; implementation_name != 'PyPy' and platform_python_implementation != 'PyPy'
+    # via cffi
+pydantic==2.12.4
+    # via
+    #   banks
+    #   dungeonmaster-ai
+    #   elevenlabs
+    #   fastapi
+    #   google-genai
+    #   google-generativeai
+    #   gradio
+    #   llama-cloud
+    #   llama-cloud-services
+    #   llama-index-core
+    #   llama-index-instrumentation
+    #   llama-index-tools-mcp
+    #   llama-index-workflows
+    #   mcp
+    #   openai
+    #   pydantic-settings
+pydantic-core==2.41.5
+    # via
+    #   elevenlabs
+    #   pydantic
+pydantic-settings==2.12.0
+    # via
+    #   dungeonmaster-ai
+    #   mcp
+pydub==0.25.1
+    # via gradio
+pygments==2.19.2
+    # via rich
+pyjwt==2.10.1
+    # via mcp
+pyparsing==3.2.5
+    # via httplib2
+pypdf==6.4.0
+    # via llama-index-readers-file
+python-dateutil==2.9.0.post0
+    # via pandas
+python-dotenv==1.2.1
+    # via
+    #   dungeonmaster-ai
+    #   llama-cloud-services
+    #   pydantic-settings
+python-multipart==0.0.20
+    # via
+    #   gradio
+    #   mcp
+pytz==2025.2
+    # via pandas
+pywin32==311 ; sys_platform == 'win32'
+    # via mcp
+pyyaml==6.0.3
+    # via
+    #   gradio
+    #   huggingface-hub
+    #   llama-index-core
+referencing==0.37.0
+    # via
+    #   jsonschema
+    #   jsonschema-specifications
+regex==2025.11.3
+    # via
+    #   nltk
+    #   tiktoken
+requests==2.32.5
+    # via
+    #   elevenlabs
+    #   google-api-core
+    #   google-genai
+    #   llama-index-core
+    #   tiktoken
+rich==14.2.0
+    # via typer
+rpds-py==0.29.0
+    # via
+    #   jsonschema
+    #   referencing
+rsa==4.9.1
+    # via google-auth
+safehttpx==0.1.7
+    # via gradio
+semantic-version==2.10.0
+    # via gradio
+setuptools==80.9.0
+    # via llama-index-core
+shellingham==1.5.4
+    # via
+    #   huggingface-hub
+    #   typer
+six==1.17.0
+    # via python-dateutil
+sniffio==1.3.1
+    # via openai
+soupsieve==2.8
+    # via beautifulsoup4
+sqlalchemy==2.0.44
+    # via llama-index-core
+sse-starlette==3.0.3
+    # via mcp
+starlette==0.50.0
+    # via
+    #   fastapi
+    #   gradio
+    #   mcp
+striprtf==0.0.26
+    # via llama-index-readers-file
+tenacity==9.1.2
+    # via
+    #   google-genai
+    #   llama-cloud-services
+    #   llama-index-core
+tiktoken==0.12.0
+    # via llama-index-core
+tomlkit==0.13.3
+    # via gradio
+tqdm==4.67.1
+    # via
+    #   google-generativeai
+    #   huggingface-hub
+    #   llama-index-core
+    #   nltk
+    #   openai
+typer==0.20.0
+    # via gradio
+typer-slim==0.20.0
+    # via huggingface-hub
+typing-extensions==4.15.0
+    # via
+    #   aiosignal
+    #   aiosqlite
+    #   anyio
+    #   beautifulsoup4
+    #   cryptography
+    #   elevenlabs
+    #   exceptiongroup
+    #   fastapi
+    #   google-genai
+    #   google-generativeai
+    #   gradio
+    #   gradio-client
+    #   grpcio
+    #   huggingface-hub
+    #   llama-index-core
+    #   llama-index-workflows
+    #   mcp
+    #   multidict
+    #   openai
+    #   pydantic
+    #   pydantic-core
+    #   pypdf
+    #   referencing
+    #   sqlalchemy
+    #   starlette
+    #   typer
+    #   typer-slim
+    #   typing-inspect
+    #   typing-inspection
+    #   uvicorn
+typing-inspect==0.9.0
+    # via
+    #   dataclasses-json
+    #   llama-index-core
+typing-inspection==0.4.2
+    # via
+    #   mcp
+    #   pydantic
+    #   pydantic-settings
+tzdata==2025.2
+    # via pandas
+uritemplate==4.2.0
+    # via google-api-python-client
+urllib3==2.5.0
+    # via requests
+uvicorn==0.38.0
+    # via
+    #   gradio
+    #   mcp
+websockets==15.0.1
+    # via
+    #   elevenlabs
+    #   google-genai
+wrapt==1.17.3
+    # via
+    #   deprecated
+    #   llama-index-core
+yarl==1.22.0
+    # via aiohttp

src/__init__.py

@@ -0,0 +1,8 @@
+"""
+DungeonMaster AI - Source Package
+
+AI-powered D&D 5e Game Master with voice narration.
+"""
+
+__version__ = "1.0.0"
+__author__ = "DungeonMaster AI Team"

src/agents/__init__.py

@@ -0,0 +1,125 @@
+"""
+DungeonMaster AI - Agents Package
+
+LlamaIndex-based agents for game mastering, rules, and narration.
+"""
+
+from __future__ import annotations
+
+# Models and enums
+from src.agents.models import (
+    DegradationLevel,
+    DMResponse,
+    GameContext,
+    GameMode,
+    LLMProviderHealth,
+    LLMResponse,
+    PacingStyle,
+    RulesResponse,
+    SpecialMoment,
+    SpecialMomentType,
+    ToolCallInfo,
+    TurnResult,
+    VoiceSegment,
+)
+
+# Exceptions
+from src.agents.exceptions import (
+    AgentError,
+    DMAgentError,
+    LLMAllProvidersFailedError,
+    LLMProviderError,
+    LLMRateLimitError,
+    LLMTimeoutError,
+    OrchestratorError,
+    RulesAgentError,
+    VoiceNarratorError,
+    get_graceful_message,
+)
+
+# LLM Provider
+from src.agents.llm_provider import (
+    LLMFallbackChain,
+    ProviderCircuitBreaker,
+)
+
+# Agents
+from src.agents.dungeon_master import (
+    DungeonMasterAgent,
+    parse_voice_cues,
+)
+from src.agents.rules_arbiter import (
+    RulesArbiterAgent,
+    RulesCache,
+)
+from src.agents.voice_narrator import (
+    PhraseCache,
+    VoiceNarratorAgent,
+    create_voice_narrator,
+)
+
+# Controllers
+from src.agents.special_moments import (
+    SpecialMomentHandler,
+    UI_EFFECTS,
+)
+from src.agents.pacing_controller import (
+    PACING_INSTRUCTIONS,
+    PacingController,
+    create_pacing_controller,
+)
+
+# Orchestrator
+from src.agents.orchestrator import (
+    AgentOrchestrator,
+    create_orchestrator,
+)
+
+
+__all__ = [
+    # Models
+    "DegradationLevel",
+    "DMResponse",
+    "GameContext",
+    "GameMode",
+    "LLMProviderHealth",
+    "LLMResponse",
+    "PacingStyle",
+    "RulesResponse",
+    "SpecialMoment",
+    "SpecialMomentType",
+    "ToolCallInfo",
+    "TurnResult",
+    "VoiceSegment",
+    # Exceptions
+    "AgentError",
+    "DMAgentError",
+    "LLMAllProvidersFailedError",
+    "LLMProviderError",
+    "LLMRateLimitError",
+    "LLMTimeoutError",
+    "OrchestratorError",
+    "RulesAgentError",
+    "VoiceNarratorError",
+    "get_graceful_message",
+    # LLM Provider
+    "LLMFallbackChain",
+    "ProviderCircuitBreaker",
+    # Agents
+    "DungeonMasterAgent",
+    "parse_voice_cues",
+    "RulesArbiterAgent",
+    "RulesCache",
+    "VoiceNarratorAgent",
+    "PhraseCache",
+    "create_voice_narrator",
+    # Controllers
+    "SpecialMomentHandler",
+    "UI_EFFECTS",
+    "PACING_INSTRUCTIONS",
+    "PacingController",
+    "create_pacing_controller",
+    # Orchestrator
+    "AgentOrchestrator",
+    "create_orchestrator",
+]

src/agents/dungeon_master.py

@@ -0,0 +1,675 @@
+"""
+DungeonMaster AI - Dungeon Master Agent
+
+The main storytelling agent using LlamaIndex FunctionAgent.
+Handles narrative generation, tool calling, and game flow.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.core.llms import ChatMessage, MessageRole
+from llama_index.core.memory import ChatMemoryBuffer
+from llama_index.core.tools import FunctionTool
+
+from src.config.settings import get_settings
+from src.game.game_state import GameState
+from src.mcp_integration.models import DiceRollResult
+from src.voice.models import VoiceType
+
+from .exceptions import DMAgentError
+from .models import (
+    DMResponse,
+    GameContext,
+    GameMode,
+    PacingStyle,
+    SpecialMoment,
+    SpecialMomentType,
+    ToolCallInfo,
+    VoiceSegment,
+)
+
+if TYPE_CHECKING:
+    from llama_index.core.llms import LLM
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Voice Cue Parsing
+# =============================================================================
+
+# Pattern to match [VOICE:profile_name] tags
+VOICE_CUE_PATTERN = re.compile(r"\[VOICE:(\w+)\]", re.IGNORECASE)
+
+# Mapping from voice cue names to VoiceType
+VOICE_CUE_MAP: dict[str, VoiceType] = {
+    "dm": VoiceType.DM,
+    "narrator": VoiceType.DM,
+    "npc_male_gruff": VoiceType.NPC_MALE_GRUFF,
+    "gruff": VoiceType.NPC_MALE_GRUFF,
+    "guard": VoiceType.NPC_MALE_GRUFF,
+    "dwarf": VoiceType.NPC_MALE_GRUFF,
+    "npc_female_gentle": VoiceType.NPC_FEMALE_GENTLE,
+    "gentle": VoiceType.NPC_FEMALE_GENTLE,
+    "elf": VoiceType.NPC_FEMALE_GENTLE,
+    "healer": VoiceType.NPC_FEMALE_GENTLE,
+    "npc_mysterious": VoiceType.NPC_MYSTERIOUS,
+    "mysterious": VoiceType.NPC_MYSTERIOUS,
+    "wizard": VoiceType.NPC_MYSTERIOUS,
+    "mage": VoiceType.NPC_MYSTERIOUS,
+    "monster": VoiceType.MONSTER,
+    "creature": VoiceType.MONSTER,
+    "villain": VoiceType.MONSTER,
+    "goblin": VoiceType.MONSTER,
+    "orc": VoiceType.MONSTER,
+}
+
+
+def parse_voice_cues(text: str) -> list[VoiceSegment]:
+    """
+    Parse text for voice cues and split into segments.
+
+    Args:
+        text: Text containing optional [VOICE:profile] cues.
+
+    Returns:
+        List of VoiceSegment objects.
+    """
+    segments: list[VoiceSegment] = []
+
+    # Find all voice cue positions
+    matches = list(VOICE_CUE_PATTERN.finditer(text))
+
+    if not matches:
+        # No voice cues - treat as single DM segment
+        # But check for quoted dialogue
+        return _parse_dialogue_segments(text)
+
+    current_pos = 0
+    current_voice = VoiceType.DM
+
+    for match in matches:
+        # Get text before this voice cue
+        before_text = text[current_pos : match.start()].strip()
+        if before_text:
+            segments.append(
+                VoiceSegment(
+                    text=before_text,
+                    voice_type=current_voice,
+                    is_dialogue=False,
+                )
+            )
+
+        # Get the new voice type
+        voice_name = match.group(1).lower()
+        current_voice = VOICE_CUE_MAP.get(voice_name, VoiceType.DM)
+        current_pos = match.end()
+
+    # Get remaining text after last voice cue
+    remaining_text = text[current_pos:].strip()
+    if remaining_text:
+        # Check if it's dialogue (in quotes)
+        is_dialogue = remaining_text.startswith('"') or remaining_text.startswith("'")
+        segments.append(
+            VoiceSegment(
+                text=remaining_text,
+                voice_type=current_voice,
+                is_dialogue=is_dialogue,
+                pause_before_ms=200 if is_dialogue else 0,
+            )
+        )
+
+    return segments
+
+
+def _parse_dialogue_segments(text: str) -> list[VoiceSegment]:
+    """
+    Parse text without voice cues, detecting dialogue from quotes.
+
+    Args:
+        text: Text to parse.
+
+    Returns:
+        List of VoiceSegment objects.
+    """
+    segments: list[VoiceSegment] = []
+
+    # Simple pattern: split on quotes
+    # This handles: Narration "Dialogue" more narration
+    parts = re.split(r'("[^"]+"|\'[^\']+\')', text)
+
+    for part in parts:
+        part = part.strip()
+        if not part:
+            continue
+
+        is_dialogue = part.startswith('"') or part.startswith("'")
+        # Remove quotes for dialogue
+        clean_text = part.strip("\"'") if is_dialogue else part
+
+        if clean_text:
+            segments.append(
+                VoiceSegment(
+                    text=clean_text if not is_dialogue else part,  # Keep quotes for display
+                    voice_type=VoiceType.NPC_MALE_GRUFF if is_dialogue else VoiceType.DM,
+                    is_dialogue=is_dialogue,
+                    pause_before_ms=200 if is_dialogue else 0,
+                    pause_after_ms=200 if is_dialogue else 0,
+                )
+            )
+
+    # If no segments were created, return the whole text as DM
+    if not segments:
+        segments.append(VoiceSegment(text=text, voice_type=VoiceType.DM))
+
+    return segments
+
+
+# =============================================================================
+# Prompt Loading
+# =============================================================================
+
+
+def load_system_prompt(mode: GameMode = GameMode.EXPLORATION) -> str:
+    """
+    Load the system prompt for the given game mode.
+
+    Args:
+        mode: Current game mode.
+
+    Returns:
+        Combined system prompt string.
+    """
+    settings = get_settings()
+    prompts_dir = settings.prompts_dir
+
+    # Load base prompt
+    base_path = Path(prompts_dir) / "dm_system.txt"
+    base_prompt = ""
+    if base_path.exists():
+        base_prompt = base_path.read_text()
+    else:
+        logger.warning(f"Base DM prompt not found at {base_path}")
+        base_prompt = _get_fallback_prompt()
+
+    # Load mode-specific additions
+    mode_prompts = {
+        GameMode.COMBAT: "dm_combat.txt",
+        GameMode.EXPLORATION: "dm_exploration.txt",
+        GameMode.SOCIAL: "dm_social.txt",
+    }
+
+    mode_file = mode_prompts.get(mode)
+    if mode_file:
+        mode_path = Path(prompts_dir) / mode_file
+        if mode_path.exists():
+            mode_addition = mode_path.read_text()
+            base_prompt = f"{base_prompt}\n\n## Current Mode: {mode.value.title()}\n{mode_addition}"
+
+    # Add voice cue instructions
+    voice_instructions = """
+## Voice Cues for Multi-Voice Narration
+When NPCs or creatures speak dialogue, prefix their speech with a voice tag:
+- [VOICE:gruff] for guards, warriors, dwarves
+- [VOICE:gentle] for elves, healers, kind NPCs
+- [VOICE:mysterious] for wizards, seers, mystical beings
+- [VOICE:monster] for creatures, goblins, villains
+
+Example: The dwarf slams his tankard. [VOICE:gruff]"Information costs gold, stranger!"
+
+Narration without a voice tag will use the default DM voice.
+"""
+    base_prompt = f"{base_prompt}\n{voice_instructions}"
+
+    return base_prompt
+
+
+def _get_fallback_prompt() -> str:
+    """Get fallback DM prompt if file not found."""
+    return """You are an experienced Dungeon Master for D&D 5e. Create immersive, engaging narratives.
+
+CRITICAL: Always use tools for dice rolls and game mechanics. Never decide outcomes arbitrarily.
+
+Keep responses to 2-4 sentences. Be dramatic but fair. Use voice cues for NPC dialogue."""
+
+
+# =============================================================================
+# DungeonMasterAgent
+# =============================================================================
+
+
+class DungeonMasterAgent:
+    """
+    Main storytelling agent using LlamaIndex FunctionAgent.
+
+    Features:
+    - Dynamic mode switching (exploration, combat, social)
+    - Game state context injection
+    - Voice cue parsing for multi-voice narration
+    - Special moment detection (critical hits, death saves)
+    """
+
+    def __init__(
+        self,
+        llm: LLM,
+        tools: list[FunctionTool],
+        game_state: GameState,
+        memory_token_limit: int = 8000,
+    ) -> None:
+        """
+        Initialize the Dungeon Master agent.
+
+        Args:
+            llm: LlamaIndex LLM instance.
+            tools: List of MCP tools as FunctionTool objects.
+            game_state: Game state reference.
+            memory_token_limit: Token limit for conversation memory.
+        """
+        self._llm = llm
+        self._tools = tools
+        self._game_state = game_state
+        self._current_mode = GameMode.EXPLORATION
+
+        # Initialize memory
+        self._memory = ChatMemoryBuffer.from_defaults(
+            llm=llm,
+            token_limit=memory_token_limit,
+        )
+
+        # Load system prompt
+        self._system_prompt = load_system_prompt(self._current_mode)
+
+        # Create the FunctionAgent
+        self._agent = FunctionAgent(
+            llm=llm,
+            tools=tools,
+            system_prompt=self._system_prompt,
+        )
+
+        logger.info(
+            f"DungeonMasterAgent initialized with {len(tools)} tools"
+        )
+
+    @property
+    def mode(self) -> GameMode:
+        """Get current game mode."""
+        return self._current_mode
+
+    def set_mode(self, mode: GameMode) -> None:
+        """
+        Switch game mode and reload system prompt.
+
+        Args:
+            mode: New game mode.
+        """
+        if mode != self._current_mode:
+            self._current_mode = mode
+            self._system_prompt = load_system_prompt(mode)
+
+            # Recreate agent with new prompt
+            self._agent = FunctionAgent(
+                llm=self._llm,
+                tools=self._tools,
+                system_prompt=self._system_prompt,
+            )
+
+            logger.info(f"DM agent mode changed to {mode.value}")
+
+    def detect_mode(self, player_input: str, game_state: GameState) -> GameMode:
+        """
+        Detect appropriate game mode from context.
+
+        Args:
+            player_input: Player's input text.
+            game_state: Current game state.
+
+        Returns:
+            Detected GameMode.
+        """
+        # Combat mode if in combat
+        if game_state.in_combat:
+            return GameMode.COMBAT
+
+        # Check for combat keywords
+        input_lower = player_input.lower()
+        combat_keywords = ["attack", "fight", "strike", "cast", "hit", "shoot"]
+        if any(kw in input_lower for kw in combat_keywords):
+            return GameMode.COMBAT
+
+        # Check for social keywords
+        social_keywords = ["talk", "speak", "ask", "persuade", "intimidate", "convince"]
+        if any(kw in input_lower for kw in social_keywords):
+            return GameMode.SOCIAL
+
+        # Default to exploration
+        return GameMode.EXPLORATION
+
+    def _build_context_message(self, game_state: GameState) -> str:
+        """
+        Build context message from game state for LLM.
+
+        Args:
+            game_state: Current game state.
+
+        Returns:
+            Formatted context string.
+        """
+        context_parts = []
+
+        # Location
+        context_parts.append(f"**Current Location:** {game_state.current_location}")
+
+        # Party status
+        if game_state.party:
+            context_parts.append(f"**Party Size:** {len(game_state.party)} characters")
+            if game_state.active_character_id:
+                char_data = game_state.get_character(game_state.active_character_id)
+                if char_data:
+                    # Handle nested structure - character data can be at root or nested
+                    char = char_data.get("character", char_data)
+                    
+                    # Basic info
+                    name = char.get("name", "Unknown")
+                    char_class = char.get("class", char.get("character_class", "Unknown"))
+                    level = char.get("level", 1)
+                    race = char.get("race", "Unknown")
+                    
+                    # Hit points
+                    hp_data = char.get("hit_points", {})
+                    current_hp = hp_data.get("current", char.get("current_hp", "?"))
+                    max_hp = hp_data.get("maximum", hp_data.get("max", char.get("max_hp", "?")))
+                    temp_hp = hp_data.get("temporary", char.get("temp_hp", 0))
+                    
+                    # Combat stats
+                    ac = char.get("armor_class", char.get("ac", "?"))
+                    
+                    # Build character summary
+                    char_summary = f"**Active Character:** {name} (Level {level} {race} {char_class})"
+                    context_parts.append(char_summary)
+                    
+                    # Add HP and AC
+                    hp_text = f"{current_hp}/{max_hp}"
+                    if temp_hp:
+                        hp_text += f" (+{temp_hp} temp)"
+                    context_parts.append(f"**HP:** {hp_text} | **AC:** {ac}")
+                    
+                    # Add equipped weapons (if any)
+                    equipment = char.get("equipment", {})
+                    weapons = equipment.get("weapons", [])
+                    if weapons:
+                        # Take first 2 weapons to keep context concise
+                        weapon_list = ", ".join(str(w) for w in weapons[:2])
+                        if len(weapons) > 2:
+                            weapon_list += f", +{len(weapons) - 2} more"
+                        context_parts.append(f"**Equipped:** {weapon_list}")
+                    
+                    # Add key ability scores for quick reference
+                    abilities = char.get("ability_scores", {})
+                    if abilities:
+                        # Show primary combat abilities
+                        str_score = abilities.get("strength", abilities.get("STR", "?"))
+                        dex_score = abilities.get("dexterity", abilities.get("DEX", "?"))
+                        con_score = abilities.get("constitution", abilities.get("CON", "?"))
+                        context_parts.append(
+                            f"**Abilities:** STR {str_score}, DEX {dex_score}, CON {con_score}"
+                        )
+
+        # Combat state
+        if game_state.in_combat and game_state.combat_state:
+            combat = game_state.combat_state
+            round_num = combat.get("round", 1)
+            context_parts.append(f"**Combat Round:** {round_num}")
+            current = combat.get("current_combatant")
+            if current:
+                context_parts.append(f"**Current Turn:** {current}")
+
+        # Recent events (last 3)
+        if game_state.recent_events:
+            recent = game_state.recent_events[-3:]
+            events_text = "; ".join(e.get("description", "")[:50] for e in recent)
+            context_parts.append(f"**Recent Events:** {events_text}")
+
+        return "\n".join(context_parts)
+
+    async def process(
+        self,
+        player_input: str,
+        game_context: GameContext | None = None,
+    ) -> DMResponse:
+        """
+        Process player input and generate DM response.
+
+        Args:
+            player_input: The player's action/speech.
+            game_context: Optional game context for additional info.
+
+        Returns:
+            DMResponse with narration and metadata.
+        """
+        start_time = time.time()
+
+        try:
+            # Auto-detect and switch mode
+            detected_mode = self.detect_mode(player_input, self._game_state)
+            if detected_mode != self._current_mode:
+                self.set_mode(detected_mode)
+
+            # Build context message
+            context_msg = self._build_context_message(self._game_state)
+
+            # Combine context with player input
+            full_input = f"{context_msg}\n\n**Player Action:** {player_input}"
+
+            # Run the agent
+            handler = self._agent.run(user_msg=full_input)
+
+            # Collect response and tool calls
+            response_text = ""
+            tool_calls: list[ToolCallInfo] = []
+            dice_rolls: list[DiceRollResult] = []
+
+            async for event in handler.stream_events():
+                # Handle different event types
+                event_type = type(event).__name__
+
+                if event_type == "AgentOutput":
+                    # Final response
+                    response_text = str(event.response) if hasattr(event, "response") else ""
+
+                elif event_type == "ToolCall":
+                    # Tool was called
+                    if hasattr(event, "tool_name"):
+                        tool_info = ToolCallInfo(
+                            tool_name=event.tool_name,
+                            arguments=getattr(event, "arguments", {}),
+                        )
+                        tool_calls.append(tool_info)
+
+                elif event_type == "ToolCallResult":
+                    # Tool result received
+                    if hasattr(event, "result") and tool_calls:
+                        tool_calls[-1].result = event.result
+                        tool_calls[-1].success = True
+
+                        # Check if it's a dice roll
+                        if hasattr(event, "result"):
+                            roll_result = self._extract_dice_roll(event.result)
+                            if roll_result:
+                                dice_rolls.append(roll_result)
+
+            # Parse voice cues from response
+            voice_segments = parse_voice_cues(response_text)
+
+            # Clean response text (remove voice cues for display)
+            clean_text = VOICE_CUE_PATTERN.sub("", response_text).strip()
+
+            # Detect special moments
+            special_moment = self._detect_special_moment(dice_rolls, tool_calls)
+
+            # Determine pacing
+            pacing = self._determine_pacing(detected_mode, special_moment)
+
+            # Calculate processing time
+            processing_time = (time.time() - start_time) * 1000
+
+            return DMResponse(
+                narration=clean_text,
+                voice_segments=voice_segments,
+                tool_calls=tool_calls,
+                dice_rolls=dice_rolls,
+                game_state_updates={},  # Will be populated by orchestrator
+                special_moment=special_moment,
+                ui_effects=special_moment.ui_effects if special_moment else [],
+                game_mode=detected_mode,
+                pacing=pacing,
+                processing_time_ms=processing_time,
+                llm_provider=getattr(self._llm, "model", "unknown"),
+            )
+
+        except Exception as e:
+            logger.error(f"DM agent processing failed: {e}")
+            raise DMAgentError(str(e)) from e
+
+    def _extract_dice_roll(self, result: object) -> DiceRollResult | None:
+        """Extract DiceRollResult from tool result if it's a roll."""
+        if isinstance(result, DiceRollResult):
+            return result
+
+        if isinstance(result, dict):
+            # Check if it looks like a roll result
+            if "total" in result and ("rolls" in result or "notation" in result):
+                try:
+                    return DiceRollResult(
+                        notation=str(result.get("notation", "")),
+                        individual_rolls=list(result.get("rolls", [])),
+                        total=int(result.get("total", 0)),
+                        is_critical=result.get("is_critical", False),
+                        is_fumble=result.get("is_fumble", False),
+                        raw_result=result,
+                    )
+                except Exception:
+                    pass
+
+        return None
+
+    def _detect_special_moment(
+        self,
+        dice_rolls: list[DiceRollResult],
+        tool_calls: list[ToolCallInfo],
+    ) -> SpecialMoment | None:
+        """
+        Detect if any special dramatic moment occurred.
+
+        Args:
+            dice_rolls: Dice rolls from this turn.
+            tool_calls: Tool calls from this turn.
+
+        Returns:
+            SpecialMoment if detected, None otherwise.
+        """
+        for roll in dice_rolls:
+            # Critical hit (natural 20 on d20)
+            if roll.is_critical:
+                return SpecialMoment(
+                    moment_type=SpecialMomentType.CRITICAL_HIT,
+                    enhanced_narration="CRITICAL HIT! Your strike finds the perfect opening!",
+                    voice_type=VoiceType.DM,
+                    ui_effects=["screen_shake", "golden_glow"],
+                    pause_before_ms=500,
+                    context={"roll": roll.total, "notation": roll.notation},
+                )
+
+            # Critical miss (natural 1 on d20)
+            if roll.is_fumble:
+                return SpecialMoment(
+                    moment_type=SpecialMomentType.CRITICAL_MISS,
+                    enhanced_narration="A critical fumble! Things have gone terribly wrong...",
+                    voice_type=VoiceType.DM,
+                    ui_effects=["red_flash"],
+                    pause_before_ms=300,
+                    context={"roll": roll.total, "notation": roll.notation},
+                )
+
+        # Check for death saves in tool calls
+        for tool in tool_calls:
+            if "death" in tool.tool_name.lower() or "save" in tool.tool_name.lower():
+                result = tool.result
+                if isinstance(result, dict):
+                    roll_value = result.get("roll", result.get("total", 0))
+                    if roll_value == 20:
+                        return SpecialMoment(
+                            moment_type=SpecialMomentType.DEATH_SAVE_NAT_20,
+                            enhanced_narration=(
+                                "Your eyes SNAP open! Against all odds, you RISE, "
+                                "defying death itself!"
+                            ),
+                            voice_type=VoiceType.DM,
+                            ui_effects=["golden_resurrection", "screen_shake"],
+                            pause_before_ms=800,
+                            context={"roll": roll_value},
+                        )
+                    elif roll_value == 1:
+                        return SpecialMoment(
+                            moment_type=SpecialMomentType.DEATH_SAVE_NAT_1,
+                            enhanced_narration=(
+                                "Darkness surges. Two failures. Death's grip tightens..."
+                            ),
+                            voice_type=VoiceType.DM,
+                            ui_effects=["darkness_pulse"],
+                            pause_before_ms=500,
+                            context={"roll": roll_value},
+                        )
+
+        return None
+
+    def _determine_pacing(
+        self,
+        mode: GameMode,
+        special_moment: SpecialMoment | None,
+    ) -> PacingStyle:
+        """
+        Determine response pacing style.
+
+        Args:
+            mode: Current game mode.
+            special_moment: Special moment if any.
+
+        Returns:
+            Appropriate PacingStyle.
+        """
+        if special_moment:
+            return PacingStyle.DRAMATIC
+
+        if mode == GameMode.COMBAT:
+            return PacingStyle.QUICK
+
+        if mode == GameMode.SOCIAL:
+            return PacingStyle.STANDARD
+
+        return PacingStyle.STANDARD
+
+    def clear_memory(self) -> None:
+        """Clear conversation memory for new game."""
+        self._memory = ChatMemoryBuffer.from_defaults(
+            llm=self._llm,
+            token_limit=8000,
+        )
+        logger.info("DM agent memory cleared")
+
+    def add_to_memory(self, role: str, content: str) -> None:
+        """
+        Add a message to conversation memory.
+
+        Args:
+            role: Message role ('user' or 'assistant').
+            content: Message content.
+        """
+        message_role = MessageRole.USER if role == "user" else MessageRole.ASSISTANT
+        self._memory.put(ChatMessage(role=message_role, content=content))

src/agents/exceptions.py

@@ -0,0 +1,314 @@
+"""
+DungeonMaster AI - Agent Exceptions
+
+Exception hierarchy for agent-related errors.
+"""
+
+from __future__ import annotations
+
+
+class AgentError(Exception):
+    """Base exception for all agent-related errors."""
+
+    def __init__(self, message: str, recoverable: bool = True) -> None:
+        super().__init__(message)
+        self.message = message
+        self.recoverable = recoverable
+
+
+# =============================================================================
+# LLM Provider Exceptions
+# =============================================================================
+
+
+class LLMProviderError(AgentError):
+    """Base exception for LLM provider errors."""
+
+    def __init__(
+        self,
+        message: str,
+        provider: str = "",
+        recoverable: bool = True,
+    ) -> None:
+        super().__init__(message, recoverable)
+        self.provider = provider
+
+
+class LLMRateLimitError(LLMProviderError):
+    """LLM provider rate limit exceeded."""
+
+    def __init__(
+        self,
+        provider: str,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(
+            f"Rate limit exceeded for {provider}",
+            provider=provider,
+            recoverable=True,
+        )
+        self.retry_after = retry_after
+
+
+class LLMTimeoutError(LLMProviderError):
+    """LLM request timed out."""
+
+    def __init__(
+        self,
+        provider: str,
+        timeout_seconds: float,
+    ) -> None:
+        super().__init__(
+            f"Request to {provider} timed out after {timeout_seconds}s",
+            provider=provider,
+            recoverable=True,
+        )
+        self.timeout_seconds = timeout_seconds
+
+
+class LLMAuthenticationError(LLMProviderError):
+    """LLM authentication failed (invalid API key)."""
+
+    def __init__(self, provider: str) -> None:
+        super().__init__(
+            f"Authentication failed for {provider}. Check API key.",
+            provider=provider,
+            recoverable=False,
+        )
+
+
+class LLMQuotaExhaustedError(LLMProviderError):
+    """LLM quota/credits exhausted."""
+
+    def __init__(self, provider: str) -> None:
+        super().__init__(
+            f"Quota exhausted for {provider}",
+            provider=provider,
+            recoverable=False,
+        )
+
+
+class LLMAllProvidersFailedError(AgentError):
+    """All LLM providers failed."""
+
+    def __init__(self, errors: dict[str, str]) -> None:
+        providers = ", ".join(errors.keys())
+        super().__init__(
+            f"All LLM providers failed: {providers}",
+            recoverable=False,
+        )
+        self.errors = errors
+
+
+class LLMCircuitBreakerOpenError(LLMProviderError):
+    """Circuit breaker is open for this provider."""
+
+    def __init__(
+        self,
+        provider: str,
+        reset_after: float | None = None,
+    ) -> None:
+        super().__init__(
+            f"Circuit breaker open for {provider}",
+            provider=provider,
+            recoverable=True,
+        )
+        self.reset_after = reset_after
+
+
+# =============================================================================
+# Agent Processing Exceptions
+# =============================================================================
+
+
+class AgentProcessingError(AgentError):
+    """Error during agent processing."""
+
+    def __init__(
+        self,
+        message: str,
+        agent_name: str = "",
+        recoverable: bool = True,
+    ) -> None:
+        super().__init__(message, recoverable)
+        self.agent_name = agent_name
+
+
+class DMAgentError(AgentProcessingError):
+    """Error in Dungeon Master agent."""
+
+    def __init__(self, message: str, recoverable: bool = True) -> None:
+        super().__init__(message, agent_name="DungeonMaster", recoverable=recoverable)
+
+
+class RulesAgentError(AgentProcessingError):
+    """Error in Rules Arbiter agent."""
+
+    def __init__(self, message: str, recoverable: bool = True) -> None:
+        super().__init__(message, agent_name="RulesArbiter", recoverable=recoverable)
+
+
+class VoiceNarratorError(AgentProcessingError):
+    """Error in Voice Narrator agent."""
+
+    def __init__(self, message: str, recoverable: bool = True) -> None:
+        super().__init__(message, agent_name="VoiceNarrator", recoverable=recoverable)
+
+
+# =============================================================================
+# Tool Execution Exceptions
+# =============================================================================
+
+
+class ToolExecutionError(AgentError):
+    """Error executing a tool."""
+
+    def __init__(
+        self,
+        tool_name: str,
+        message: str,
+        original_error: Exception | None = None,
+        recoverable: bool = True,
+    ) -> None:
+        super().__init__(
+            f"Tool '{tool_name}' failed: {message}",
+            recoverable=recoverable,
+        )
+        self.tool_name = tool_name
+        self.original_error = original_error
+
+
+class ToolTimeoutError(ToolExecutionError):
+    """Tool execution timed out."""
+
+    def __init__(
+        self,
+        tool_name: str,
+        timeout_seconds: float,
+    ) -> None:
+        super().__init__(
+            tool_name,
+            f"Execution timed out after {timeout_seconds}s",
+            recoverable=True,
+        )
+        self.timeout_seconds = timeout_seconds
+
+
+class ToolNotFoundError(ToolExecutionError):
+    """Requested tool not found."""
+
+    def __init__(self, tool_name: str) -> None:
+        super().__init__(
+            tool_name,
+            "Tool not found in available tools",
+            recoverable=False,
+        )
+
+
+# =============================================================================
+# Orchestration Exceptions
+# =============================================================================
+
+
+class OrchestratorError(AgentError):
+    """Error in agent orchestration."""
+
+    pass
+
+
+class OrchestratorNotInitializedError(OrchestratorError):
+    """Orchestrator not properly initialized."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Orchestrator not initialized. Call setup() first.",
+            recoverable=True,
+        )
+
+
+class TurnProcessingError(OrchestratorError):
+    """Error processing a player turn."""
+
+    def __init__(
+        self,
+        message: str,
+        partial_result: object | None = None,
+    ) -> None:
+        super().__init__(message, recoverable=True)
+        self.partial_result = partial_result
+
+
+# =============================================================================
+# State Exceptions
+# =============================================================================
+
+
+class GameStateError(AgentError):
+    """Error with game state."""
+
+    pass
+
+
+class StateConsistencyError(GameStateError):
+    """Game state became inconsistent."""
+
+    def __init__(
+        self,
+        message: str,
+        state_snapshot: dict[str, object] | None = None,
+    ) -> None:
+        super().__init__(message, recoverable=True)
+        self.state_snapshot = state_snapshot
+
+
+# =============================================================================
+# Graceful Error Messages
+# =============================================================================
+
+
+GRACEFUL_ERROR_MESSAGES: dict[str, str] = {
+    "llm_timeout": (
+        "The magical winds of computation blow slowly today. "
+        "Please try again in a moment."
+    ),
+    "llm_rate_limit": (
+        "The ethereal realm is experiencing heavy traffic. "
+        "Take a breath and try again shortly."
+    ),
+    "llm_all_failed": (
+        "The arcane servers are temporarily unreachable. "
+        "Your adventure continues in text mode."
+    ),
+    "tool_failed": (
+        "The mystical tools encountered interference. "
+        "Let's try a different approach..."
+    ),
+    "voice_unavailable": (
+        "The voice of the narrator is temporarily silenced. "
+        "Continuing with text narration."
+    ),
+    "mcp_unavailable": (
+        "The game mechanics server is resting. "
+        "Using simplified rules for now."
+    ),
+    "general_error": (
+        "An unexpected twist in the fabric of reality occurred. "
+        "The adventure continues nonetheless."
+    ),
+}
+
+
+def get_graceful_message(error_type: str) -> str:
+    """
+    Get a user-friendly error message.
+
+    Args:
+        error_type: Type of error (key in GRACEFUL_ERROR_MESSAGES)
+
+    Returns:
+        User-friendly error message
+    """
+    return GRACEFUL_ERROR_MESSAGES.get(
+        error_type,
+        GRACEFUL_ERROR_MESSAGES["general_error"],
+    )

src/agents/llm_provider.py

@@ -0,0 +1,437 @@
+"""
+DungeonMaster AI - LLM Provider Chain
+
+Manages LLM providers with automatic fallback from Gemini to OpenAI.
+Includes circuit breaker pattern for reliability.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from datetime import datetime, timedelta
+from enum import Enum
+
+from llama_index.core.llms import ChatMessage, LLM
+from llama_index.llms.gemini import Gemini
+from llama_index.llms.openai import OpenAI
+
+from src.config.settings import AppSettings, get_settings
+
+from .exceptions import (
+    LLMAllProvidersFailedError,
+    LLMAuthenticationError,
+    LLMCircuitBreakerOpenError,
+    LLMQuotaExhaustedError,
+    LLMRateLimitError,
+    LLMTimeoutError,
+)
+from .models import LLMProviderHealth, LLMResponse
+
+logger = logging.getLogger(__name__)
+
+
+class CircuitState(str, Enum):
+    """Circuit breaker states."""
+
+    CLOSED = "closed"  # Normal operation
+    OPEN = "open"  # Rejecting requests
+    HALF_OPEN = "half_open"  # Testing recovery
+
+
+class ProviderCircuitBreaker:
+    """
+    Circuit breaker for an individual LLM provider.
+
+    Prevents cascading failures by temporarily blocking requests
+    to a failing provider.
+    """
+
+    def __init__(
+        self,
+        provider_name: str,
+        failure_threshold: int = 3,
+        reset_timeout: float = 60.0,
+    ) -> None:
+        self.provider_name = provider_name
+        self.failure_threshold = failure_threshold
+        self.reset_timeout = reset_timeout
+
+        self._state = CircuitState.CLOSED
+        self._failure_count = 0
+        self._last_failure_time: datetime | None = None
+        self._last_success_time: datetime | None = None
+
+    @property
+    def state(self) -> CircuitState:
+        """Get current circuit state, checking for timeout transitions."""
+        if self._state == CircuitState.OPEN:
+            if self._should_attempt_reset():
+                self._state = CircuitState.HALF_OPEN
+                logger.info(
+                    f"Circuit breaker for {self.provider_name} "
+                    "transitioning to HALF_OPEN"
+                )
+        return self._state
+
+    @property
+    def is_available(self) -> bool:
+        """Check if provider is available for requests."""
+        return self.state != CircuitState.OPEN
+
+    def _should_attempt_reset(self) -> bool:
+        """Check if enough time has passed to attempt reset."""
+        if self._last_failure_time is None:
+            return True
+        elapsed = (datetime.now() - self._last_failure_time).total_seconds()
+        return elapsed >= self.reset_timeout
+
+    def record_success(self) -> None:
+        """Record a successful request."""
+        self._failure_count = 0
+        self._last_success_time = datetime.now()
+
+        if self._state == CircuitState.HALF_OPEN:
+            self._state = CircuitState.CLOSED
+            logger.info(
+                f"Circuit breaker for {self.provider_name} "
+                "CLOSED after successful test"
+            )
+
+    def record_failure(self, error: Exception) -> None:
+        """Record a failed request."""
+        self._failure_count += 1
+        self._last_failure_time = datetime.now()
+
+        logger.warning(
+            f"Provider {self.provider_name} failure "
+            f"({self._failure_count}/{self.failure_threshold}): {error}"
+        )
+
+        if self._state == CircuitState.HALF_OPEN:
+            # Test request failed, back to OPEN
+            self._state = CircuitState.OPEN
+            logger.warning(
+                f"Circuit breaker for {self.provider_name} "
+                "OPEN after failed test"
+            )
+        elif self._failure_count >= self.failure_threshold:
+            self._state = CircuitState.OPEN
+            logger.warning(
+                f"Circuit breaker for {self.provider_name} OPENED "
+                f"after {self._failure_count} failures"
+            )
+
+    def get_health(self) -> LLMProviderHealth:
+        """Get health status for this provider."""
+        return LLMProviderHealth(
+            provider_name=self.provider_name,
+            is_available=self.is_available,
+            is_primary=False,  # Set by parent
+            consecutive_failures=self._failure_count,
+            last_success=self._last_success_time,
+            last_error=None,  # Could track this
+            circuit_open=self.state == CircuitState.OPEN,
+        )
+
+
+class LLMFallbackChain:
+    """
+    Manages LLM providers with automatic fallback.
+
+    Order: Gemini (primary) -> OpenAI (fallback) -> Error
+
+    Features:
+    - Circuit breaker per provider (3 failures, 60s reset)
+    - Configurable timeouts (Gemini: 30s, OpenAI: 45s)
+    - Automatic fallback on rate limits, timeouts, errors
+    - Provider health tracking
+    """
+
+    # Timeout configuration per provider
+    PROVIDER_TIMEOUTS: dict[str, float] = {
+        "gemini": 30.0,
+        "openai": 45.0,
+    }
+
+    def __init__(
+        self,
+        settings: AppSettings | None = None,
+        gemini_timeout: float | None = None,
+        openai_timeout: float | None = None,
+    ) -> None:
+        """
+        Initialize the LLM fallback chain.
+
+        Args:
+            settings: Application settings. Defaults to get_settings().
+            gemini_timeout: Override Gemini timeout.
+            openai_timeout: Override OpenAI timeout.
+        """
+        self._settings = settings or get_settings()
+
+        # Override timeouts if provided
+        if gemini_timeout:
+            self.PROVIDER_TIMEOUTS["gemini"] = gemini_timeout
+        if openai_timeout:
+            self.PROVIDER_TIMEOUTS["openai"] = openai_timeout
+
+        # Initialize providers (lazy)
+        self._gemini: Gemini | None = None
+        self._openai: OpenAI | None = None
+
+        # Circuit breakers
+        self._gemini_breaker = ProviderCircuitBreaker("gemini")
+        self._openai_breaker = ProviderCircuitBreaker("openai")
+
+        # Track which provider is currently active
+        self._current_provider: str | None = None
+
+        logger.debug("LLMFallbackChain initialized")
+
+    def _get_gemini(self) -> Gemini | None:
+        """Get or create Gemini LLM instance."""
+        if self._gemini is not None:
+            return self._gemini
+
+        if not self._settings.llm.has_gemini:
+            logger.warning("Gemini API key not configured")
+            return None
+
+        try:
+            self._gemini = Gemini(
+                api_key=self._settings.llm.gemini_api_key,
+                model=self._settings.llm.gemini_model,
+                temperature=self._settings.llm.temperature,
+                max_tokens=self._settings.llm.max_tokens,
+            )
+            logger.info(f"Gemini LLM initialized: {self._settings.llm.gemini_model}")
+            return self._gemini
+        except Exception as e:
+            logger.error(f"Failed to initialize Gemini: {e}")
+            return None
+
+    def _get_openai(self) -> OpenAI | None:
+        """Get or create OpenAI LLM instance."""
+        if self._openai is not None:
+            return self._openai
+
+        if not self._settings.llm.has_openai:
+            logger.warning("OpenAI API key not configured")
+            return None
+
+        try:
+            self._openai = OpenAI(
+                api_key=self._settings.llm.openai_api_key,
+                model=self._settings.llm.openai_model,
+                temperature=self._settings.llm.temperature,
+                max_tokens=self._settings.llm.max_tokens,
+            )
+            logger.info(f"OpenAI LLM initialized: {self._settings.llm.openai_model}")
+            return self._openai
+        except Exception as e:
+            logger.error(f"Failed to initialize OpenAI: {e}")
+            return None
+
+    def get_primary_llm(self) -> LLM | None:
+        """
+        Get the primary LLM for use with LlamaIndex agents.
+
+        Returns Gemini if available, otherwise OpenAI.
+        """
+        gemini = self._get_gemini()
+        if gemini and self._gemini_breaker.is_available:
+            return gemini
+
+        openai = self._get_openai()
+        if openai and self._openai_breaker.is_available:
+            return openai
+
+        return None
+
+    def get_fallback_llm(self) -> LLM | None:
+        """
+        Get the fallback LLM for use when primary fails.
+
+        Returns OpenAI if Gemini is primary, otherwise None.
+        """
+        # If Gemini is available, OpenAI is fallback
+        if self._get_gemini() and self._gemini_breaker.is_available:
+            openai = self._get_openai()
+            if openai and self._openai_breaker.is_available:
+                return openai
+
+        return None
+
+    async def generate(
+        self,
+        messages: list[ChatMessage],
+        timeout: float | None = None,
+    ) -> LLMResponse:
+        """
+        Generate a response using the LLM chain with fallback.
+
+        Args:
+            messages: Chat messages to send.
+            timeout: Optional timeout override.
+
+        Returns:
+            LLMResponse with generated text and metadata.
+
+        Raises:
+            LLMAllProvidersFailedError: If all providers fail.
+        """
+        errors: dict[str, str] = {}
+        start_time = time.time()
+
+        # Try Gemini first
+        gemini = self._get_gemini()
+        if gemini and self._gemini_breaker.is_available:
+            try:
+                response = await self._call_provider(
+                    provider_name="gemini",
+                    llm=gemini,
+                    messages=messages,
+                    timeout=timeout or self.PROVIDER_TIMEOUTS["gemini"],
+                    breaker=self._gemini_breaker,
+                )
+                response.latency_ms = (time.time() - start_time) * 1000
+                return response
+            except Exception as e:
+                errors["gemini"] = str(e)
+                logger.warning(f"Gemini failed, trying fallback: {e}")
+        elif not self._gemini_breaker.is_available:
+            errors["gemini"] = "Circuit breaker open"
+
+        # Try OpenAI as fallback
+        openai = self._get_openai()
+        if openai and self._openai_breaker.is_available:
+            try:
+                response = await self._call_provider(
+                    provider_name="openai",
+                    llm=openai,
+                    messages=messages,
+                    timeout=timeout or self.PROVIDER_TIMEOUTS["openai"],
+                    breaker=self._openai_breaker,
+                )
+                response.from_fallback = True
+                response.latency_ms = (time.time() - start_time) * 1000
+                return response
+            except Exception as e:
+                errors["openai"] = str(e)
+                logger.error(f"OpenAI fallback also failed: {e}")
+        elif not self._openai_breaker.is_available:
+            errors["openai"] = "Circuit breaker open"
+
+        # All providers failed
+        raise LLMAllProvidersFailedError(errors)
+
+    async def _call_provider(
+        self,
+        provider_name: str,
+        llm: LLM,
+        messages: list[ChatMessage],
+        timeout: float,
+        breaker: ProviderCircuitBreaker,
+    ) -> LLMResponse:
+        """
+        Call a specific LLM provider with timeout and circuit breaker.
+
+        Args:
+            provider_name: Name of the provider.
+            llm: LLM instance to use.
+            messages: Messages to send.
+            timeout: Request timeout.
+            breaker: Circuit breaker for this provider.
+
+        Returns:
+            LLMResponse with generated text.
+
+        Raises:
+            Various LLM exceptions on failure.
+        """
+        if not breaker.is_available:
+            raise LLMCircuitBreakerOpenError(provider_name)
+
+        try:
+            # Call with timeout
+            response = await asyncio.wait_for(
+                llm.achat(messages),
+                timeout=timeout,
+            )
+
+            # Extract text from response
+            text = response.message.content if response.message else ""
+
+            # Record success
+            breaker.record_success()
+            self._current_provider = provider_name
+
+            return LLMResponse(
+                text=str(text),
+                provider_used=provider_name,
+                model_used=getattr(llm, "model", "unknown"),
+            )
+
+        except asyncio.TimeoutError as e:
+            breaker.record_failure(e)
+            raise LLMTimeoutError(provider_name, timeout) from e
+
+        except Exception as e:
+            # Categorize the error
+            error_str = str(e).lower()
+
+            if "rate" in error_str and "limit" in error_str:
+                breaker.record_failure(e)
+                raise LLMRateLimitError(provider_name) from e
+
+            if "auth" in error_str or "api key" in error_str or "401" in error_str:
+                breaker.record_failure(e)
+                raise LLMAuthenticationError(provider_name) from e
+
+            if "quota" in error_str or "exceeded" in error_str:
+                breaker.record_failure(e)
+                raise LLMQuotaExhaustedError(provider_name) from e
+
+            # Generic error
+            breaker.record_failure(e)
+            raise
+
+    def get_health(self) -> dict[str, LLMProviderHealth]:
+        """
+        Get health status of all providers.
+
+        Returns:
+            Dictionary mapping provider name to health status.
+        """
+        health = {}
+
+        gemini_health = self._gemini_breaker.get_health()
+        gemini_health.is_primary = True
+        gemini_health.is_available = (
+            self._settings.llm.has_gemini
+            and self._gemini_breaker.is_available
+        )
+        health["gemini"] = gemini_health
+
+        openai_health = self._openai_breaker.get_health()
+        openai_health.is_primary = False
+        openai_health.is_available = (
+            self._settings.llm.has_openai
+            and self._openai_breaker.is_available
+        )
+        health["openai"] = openai_health
+
+        return health
+
+    @property
+    def current_provider(self) -> str | None:
+        """Get the name of the most recently used provider."""
+        return self._current_provider
+
+    def reset_circuit_breakers(self) -> None:
+        """Reset all circuit breakers to closed state."""
+        self._gemini_breaker = ProviderCircuitBreaker("gemini")
+        self._openai_breaker = ProviderCircuitBreaker("openai")
+        logger.info("All circuit breakers reset")

src/agents/models.py

@@ -0,0 +1,516 @@
+"""
+DungeonMaster AI - Agent Models
+
+Pydantic models for agent responses, turn results, and game interactions.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+from src.mcp_integration.models import (
+    CombatStateResult,
+    DiceRollResult,
+)
+from src.voice.models import VoiceType
+
+
+# =============================================================================
+# Enums
+# =============================================================================
+
+
+class GameMode(str, Enum):
+    """Game modes for DM agent context switching."""
+
+    EXPLORATION = "exploration"
+    COMBAT = "combat"
+    SOCIAL = "social"
+    NARRATIVE = "narrative"
+
+
+class DegradationLevel(str, Enum):
+    """System degradation levels for graceful fallbacks."""
+
+    FULL = "full"  # All features working
+    PARTIAL = "partial"  # Some tools unavailable
+    TEXT_ONLY = "text_only"  # Voice unavailable
+    MINIMAL = "minimal"  # Fallback dice only, limited LLM
+
+
+class SpecialMomentType(str, Enum):
+    """Types of special dramatic moments."""
+
+    CRITICAL_HIT = "critical_hit"
+    CRITICAL_MISS = "critical_miss"
+    DEATH_SAVE_SUCCESS = "death_save_success"
+    DEATH_SAVE_FAILURE = "death_save_failure"
+    DEATH_SAVE_NAT_20 = "death_save_nat_20"
+    DEATH_SAVE_NAT_1 = "death_save_nat_1"
+    KILLING_BLOW = "killing_blow"
+    PLAYER_DEATH = "player_death"
+    LEVEL_UP = "level_up"
+    COMBAT_START = "combat_start"
+    COMBAT_VICTORY = "combat_victory"
+
+
+class PacingStyle(str, Enum):
+    """Response pacing styles."""
+
+    VERBOSE = "verbose"  # New locations, world-building (3-5 sentences)
+    STANDARD = "standard"  # Normal gameplay (2-3 sentences)
+    QUICK = "quick"  # Combat actions (1-2 sentences)
+    DRAMATIC = "dramatic"  # Critical moments (short, punchy)
+
+
+# =============================================================================
+# Voice Segment Models
+# =============================================================================
+
+
+class VoiceSegment(BaseModel):
+    """A segment of text with assigned voice profile."""
+
+    text: str = Field(description="Text content to synthesize")
+    voice_type: VoiceType = Field(
+        default=VoiceType.DM,
+        description="Voice profile to use",
+    )
+    pause_before_ms: int = Field(
+        default=0,
+        ge=0,
+        description="Pause duration before this segment in milliseconds",
+    )
+    pause_after_ms: int = Field(
+        default=0,
+        ge=0,
+        description="Pause duration after this segment in milliseconds",
+    )
+    emphasis: bool = Field(
+        default=False,
+        description="Whether to emphasize this segment",
+    )
+    is_dialogue: bool = Field(
+        default=False,
+        description="Whether this is NPC/character dialogue",
+    )
+    speaker_name: str | None = Field(
+        default=None,
+        description="Name of the speaker if dialogue",
+    )
+
+
+# =============================================================================
+# Tool Call Models
+# =============================================================================
+
+
+class ToolCallInfo(BaseModel):
+    """Information about a tool call made during processing."""
+
+    tool_name: str = Field(description="Name of the tool called")
+    arguments: dict[str, object] = Field(
+        default_factory=dict,
+        description="Arguments passed to the tool",
+    )
+    result: object = Field(
+        default=None,
+        description="Result returned by the tool",
+    )
+    success: bool = Field(
+        default=True,
+        description="Whether the tool call succeeded",
+    )
+    error_message: str | None = Field(
+        default=None,
+        description="Error message if tool call failed",
+    )
+    duration_ms: float = Field(
+        default=0.0,
+        description="Time taken by the tool call",
+    )
+    timestamp: datetime = Field(
+        default_factory=datetime.now,
+        description="When the tool was called",
+    )
+
+
+# =============================================================================
+# Special Moment Models
+# =============================================================================
+
+
+class SpecialMoment(BaseModel):
+    """A dramatic moment in the game requiring special handling."""
+
+    moment_type: SpecialMomentType = Field(description="Type of special moment")
+    enhanced_narration: str = Field(
+        default="",
+        description="Dramatic narration for this moment",
+    )
+    voice_type: VoiceType = Field(
+        default=VoiceType.DM,
+        description="Voice to use for narration",
+    )
+    ui_effects: list[str] = Field(
+        default_factory=list,
+        description="UI effects to trigger (e.g., 'screen_shake', 'golden_glow')",
+    )
+    pause_before_ms: int = Field(
+        default=500,
+        description="Dramatic pause before narration",
+    )
+    sound_effect: str | None = Field(
+        default=None,
+        description="Optional sound effect to play",
+    )
+    context: dict[str, object] = Field(
+        default_factory=dict,
+        description="Additional context (roll value, weapon, etc.)",
+    )
+
+
+# =============================================================================
+# DM Response Models
+# =============================================================================
+
+
+class DMResponse(BaseModel):
+    """Response from the Dungeon Master agent."""
+
+    narration: str = Field(
+        description="The narrative text response from the DM",
+    )
+    voice_segments: list[VoiceSegment] = Field(
+        default_factory=list,
+        description="Text segments with voice assignments for multi-voice synthesis",
+    )
+    tool_calls: list[ToolCallInfo] = Field(
+        default_factory=list,
+        description="Tools that were called during processing",
+    )
+    dice_rolls: list[DiceRollResult] = Field(
+        default_factory=list,
+        description="Dice rolls that occurred",
+    )
+    game_state_updates: dict[str, object] = Field(
+        default_factory=dict,
+        description="State changes to apply (hp_changes, location, combat, etc.)",
+    )
+    special_moment: SpecialMoment | None = Field(
+        default=None,
+        description="Special dramatic moment if detected",
+    )
+    ui_effects: list[str] = Field(
+        default_factory=list,
+        description="UI effects to trigger",
+    )
+    game_mode: GameMode = Field(
+        default=GameMode.EXPLORATION,
+        description="Current game mode after processing",
+    )
+    pacing: PacingStyle = Field(
+        default=PacingStyle.STANDARD,
+        description="Pacing style used for response",
+    )
+    # Metadata
+    processing_time_ms: float = Field(
+        default=0.0,
+        description="Total processing time",
+    )
+    llm_provider: str = Field(
+        default="",
+        description="Which LLM provider was used",
+    )
+    timestamp: datetime = Field(
+        default_factory=datetime.now,
+        description="When response was generated",
+    )
+
+
+# =============================================================================
+# Rules Response Models
+# =============================================================================
+
+
+class RulesResponse(BaseModel):
+    """Response from the Rules Arbiter agent."""
+
+    answer: str = Field(description="The rules answer/explanation")
+    sources: list[str] = Field(
+        default_factory=list,
+        description="Sources/citations for the rule",
+    )
+    confidence: float = Field(
+        default=1.0,
+        ge=0.0,
+        le=1.0,
+        description="Confidence in the answer",
+    )
+    tool_calls: list[ToolCallInfo] = Field(
+        default_factory=list,
+        description="Tools called to find the answer",
+    )
+    from_cache: bool = Field(
+        default=False,
+        description="Whether result came from cache",
+    )
+
+
+# =============================================================================
+# Turn Result Models
+# =============================================================================
+
+
+class TurnResult(BaseModel):
+    """Complete result of processing a player turn."""
+
+    # Core response
+    narration_text: str = Field(
+        description="The narrative text to display",
+    )
+    narration_audio: bytes | None = Field(
+        default=None,
+        description="Synthesized audio (combined from all segments)",
+    )
+
+    # Detailed information
+    voice_segments: list[VoiceSegment] = Field(
+        default_factory=list,
+        description="Individual voice segments for multi-voice",
+    )
+    tool_calls: list[ToolCallInfo] = Field(
+        default_factory=list,
+        description="All tools that were called",
+    )
+    dice_rolls: list[DiceRollResult] = Field(
+        default_factory=list,
+        description="All dice rolls that occurred",
+    )
+
+    # Game state
+    game_mode: GameMode = Field(
+        default=GameMode.EXPLORATION,
+        description="Current game mode",
+    )
+    combat_updates: CombatStateResult | None = Field(
+        default=None,
+        description="Combat state changes if in combat",
+    )
+
+    # Special handling
+    special_moment: SpecialMoment | None = Field(
+        default=None,
+        description="Special dramatic moment if any",
+    )
+    ui_effects: list[str] = Field(
+        default_factory=list,
+        description="UI effects to trigger",
+    )
+
+    # Status
+    degradation_level: DegradationLevel = Field(
+        default=DegradationLevel.FULL,
+        description="System degradation level",
+    )
+    voice_enabled: bool = Field(
+        default=True,
+        description="Whether voice was generated",
+    )
+    error_message: str | None = Field(
+        default=None,
+        description="Error message if something went wrong",
+    )
+
+    # Metadata
+    turn_number: int = Field(
+        default=0,
+        description="Current turn number",
+    )
+    processing_time_ms: float = Field(
+        default=0.0,
+        description="Total processing time",
+    )
+    llm_provider: str = Field(
+        default="",
+        description="Which LLM was used",
+    )
+    timestamp: datetime = Field(
+        default_factory=datetime.now,
+        description="When turn was processed",
+    )
+
+
+# =============================================================================
+# Streaming Models
+# =============================================================================
+
+
+class StreamChunk(BaseModel):
+    """A chunk of streaming response."""
+
+    text: str = Field(
+        default="",
+        description="Incremental text content",
+    )
+    is_complete: bool = Field(
+        default=False,
+        description="Whether this is the final chunk",
+    )
+    tool_call: ToolCallInfo | None = Field(
+        default=None,
+        description="Tool call if one occurred in this chunk",
+    )
+    accumulated_text: str = Field(
+        default="",
+        description="Full text accumulated so far",
+    )
+
+
+# =============================================================================
+# Game Context Models
+# =============================================================================
+
+
+class GameContext(BaseModel):
+    """Context information passed to agents for decision making."""
+
+    # Core state
+    session_id: str = Field(description="Current session ID")
+    turn_number: int = Field(default=0, description="Current turn number")
+    game_mode: GameMode = Field(
+        default=GameMode.EXPLORATION,
+        description="Current game mode",
+    )
+
+    # Location
+    current_location: str = Field(
+        default="Unknown",
+        description="Current location name",
+    )
+    location_description: str = Field(
+        default="",
+        description="Description of current location",
+    )
+
+    # Party
+    active_character_id: str | None = Field(
+        default=None,
+        description="Currently controlled character",
+    )
+    party_summary: str = Field(
+        default="",
+        description="Summary of party status (HP, conditions)",
+    )
+
+    # Combat
+    in_combat: bool = Field(
+        default=False,
+        description="Whether combat is active",
+    )
+    combat_round: int | None = Field(
+        default=None,
+        description="Current combat round if in combat",
+    )
+    current_combatant: str | None = Field(
+        default=None,
+        description="Whose turn it is in combat",
+    )
+
+    # NPCs
+    current_npc: dict[str, object] | None = Field(
+        default=None,
+        description="Current NPC being interacted with",
+    )
+    npcs_present: list[str] = Field(
+        default_factory=list,
+        description="NPCs in current scene",
+    )
+
+    # Recent history
+    recent_events_summary: str = Field(
+        default="",
+        description="Summary of recent events for context",
+    )
+
+    # Adventure
+    adventure_name: str | None = Field(
+        default=None,
+        description="Name of current adventure",
+    )
+    story_flags: dict[str, object] = Field(
+        default_factory=dict,
+        description="Active story/quest flags",
+    )
+
+
+# =============================================================================
+# LLM Provider Models
+# =============================================================================
+
+
+class LLMProviderHealth(BaseModel):
+    """Health status of an LLM provider."""
+
+    provider_name: str = Field(description="Name of the provider")
+    is_available: bool = Field(
+        default=False,
+        description="Whether provider is available",
+    )
+    is_primary: bool = Field(
+        default=False,
+        description="Whether this is the primary provider",
+    )
+    consecutive_failures: int = Field(
+        default=0,
+        description="Number of consecutive failures",
+    )
+    last_success: datetime | None = Field(
+        default=None,
+        description="Last successful call",
+    )
+    last_error: str | None = Field(
+        default=None,
+        description="Last error message",
+    )
+    circuit_open: bool = Field(
+        default=False,
+        description="Whether circuit breaker is open",
+    )
+
+
+class LLMResponse(BaseModel):
+    """Response from LLM provider chain."""
+
+    text: str = Field(description="Generated text")
+    tool_calls: list[dict[str, object]] = Field(
+        default_factory=list,
+        description="Tool calls requested by LLM",
+    )
+    provider_used: str = Field(
+        default="",
+        description="Which provider generated this response",
+    )
+    model_used: str = Field(
+        default="",
+        description="Which model was used",
+    )
+    input_tokens: int = Field(
+        default=0,
+        description="Input token count",
+    )
+    output_tokens: int = Field(
+        default=0,
+        description="Output token count",
+    )
+    latency_ms: float = Field(
+        default=0.0,
+        description="Response latency",
+    )
+    from_fallback: bool = Field(
+        default=False,
+        description="Whether fallback provider was used",
+    )

src/agents/orchestrator.py

@@ -0,0 +1,911 @@
+"""
+DungeonMaster AI - Agent Orchestrator
+
+Main coordinator for all agents with comprehensive error handling.
+Processes player turns, routes to appropriate agents, and manages game flow.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+from typing import TYPE_CHECKING
+
+from src.config.settings import AppSettings, get_settings
+from src.game.game_state import GameState
+from src.mcp_integration.connection_manager import ConnectionManager
+from src.mcp_integration.toolkit_client import TTRPGToolkitClient
+from src.mcp_integration.tool_wrappers import GameAwareTools
+from src.voice.elevenlabs_client import VoiceClient
+from src.voice.text_processor import NarrationProcessor
+
+from .dungeon_master import DungeonMasterAgent
+from .exceptions import (
+    GRACEFUL_ERROR_MESSAGES,
+    OrchestratorError,
+    OrchestratorNotInitializedError,
+    TurnProcessingError,
+    get_graceful_message,
+)
+from .llm_provider import LLMFallbackChain
+from .models import (
+    DegradationLevel,
+    DMResponse,
+    GameContext,
+    GameMode,
+    TurnResult,
+)
+from .pacing_controller import PacingController
+from .rules_arbiter import RulesArbiterAgent
+from .special_moments import SpecialMomentHandler
+from .voice_narrator import VoiceNarratorAgent, create_voice_narrator
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Special Commands
+# =============================================================================
+
+
+SPECIAL_COMMANDS: dict[str, str] = {
+    "/roll": "_handle_roll_command",
+    "/r": "_handle_roll_command",
+    "/rules": "_handle_rules_command",
+    "/rule": "_handle_rules_command",
+    "/character": "_handle_character_command",
+    "/char": "_handle_character_command",
+    "/sheet": "_handle_character_command",
+    "/inventory": "_handle_inventory_command",
+    "/inv": "_handle_inventory_command",
+    "/rest": "_handle_rest_command",
+    "/short": "_handle_short_rest_command",
+    "/long": "_handle_long_rest_command",
+    "/help": "_handle_help_command",
+    "/status": "_handle_status_command",
+    "/combat": "_handle_combat_command",
+    "/fight": "_handle_combat_command",
+    "/endcombat": "_handle_end_combat_command",
+}
+
+
+# =============================================================================
+# AgentOrchestrator
+# =============================================================================
+
+
+class AgentOrchestrator:
+    """
+    Main coordinator for all agents with comprehensive error handling.
+
+    Guarantees:
+    - Always returns a TurnResult (never raises to caller)
+    - State consistency maintained
+    - Graceful degradation on failures
+    - User-friendly error messages
+
+    Components:
+    - DungeonMasterAgent: Main storytelling
+    - RulesArbiterAgent: Rules lookup
+    - VoiceNarratorAgent: Voice synthesis
+    - SpecialMomentHandler: Dramatic moments
+    - PacingController: Response pacing
+    """
+
+    def __init__(
+        self,
+        toolkit_client: TTRPGToolkitClient | None = None,
+        voice_client: VoiceClient | None = None,
+        settings: AppSettings | None = None,
+        game_state: GameState | None = None,
+    ) -> None:
+        """
+        Initialize the orchestrator.
+
+        Args:
+            toolkit_client: MCP toolkit client. Created if not provided.
+            voice_client: Voice client. Created if not provided.
+            settings: Application settings. Uses defaults if not provided.
+            game_state: Game state. Created if not provided.
+        """
+        self._settings = settings or get_settings()
+        self._toolkit_client = toolkit_client or TTRPGToolkitClient()
+        self._voice_client = voice_client
+
+        # Will be initialized in setup()
+        self._llm_chain: LLMFallbackChain | None = None
+        self._dm_agent: DungeonMasterAgent | None = None
+        self._rules_agent: RulesArbiterAgent | None = None
+        self._voice_narrator: VoiceNarratorAgent | None = None
+
+        # Support components
+        self._special_moments = SpecialMomentHandler()
+        self._pacing = PacingController()
+
+        # Game state
+        self._game_state = game_state or GameState()
+        self._conversation_history: list[dict[str, str]] = []
+
+        # Status
+        self._initialized = False
+        self._degradation_level = DegradationLevel.FULL
+
+        logger.info("AgentOrchestrator created")
+
+    @property
+    def is_initialized(self) -> bool:
+        """Check if orchestrator is initialized."""
+        return self._initialized
+
+    @property
+    def game_state(self) -> GameState:
+        """Get current game state."""
+        return self._game_state
+
+    @property
+    def degradation_level(self) -> DegradationLevel:
+        """Get current degradation level."""
+        return self._degradation_level
+
+    async def setup(self) -> None:
+        """
+        Initialize all components.
+
+        Connects to MCP, initializes LLMs, creates agents.
+        Must be called before process_turn().
+        """
+        logger.info("Setting up AgentOrchestrator...")
+
+        try:
+            # Initialize LLM chain
+            self._llm_chain = LLMFallbackChain(self._settings)
+            primary_llm = self._llm_chain.get_primary_llm()
+
+            if primary_llm is None:
+                logger.error("No LLM available!")
+                raise OrchestratorError("No LLM provider available. Check API keys.")
+
+            # Connect to MCP server
+            try:
+                await self._toolkit_client.connect()
+                logger.info(
+                    f"Connected to MCP with {self._toolkit_client.tools_count} tools"
+                )
+            except Exception as e:
+                logger.warning(f"MCP connection failed: {e}. Using degraded mode.")
+                self._degradation_level = DegradationLevel.PARTIAL
+
+            # Get tools
+            if self._toolkit_client.is_connected:
+                all_tools = list(await self._toolkit_client.get_all_tools())
+
+                # Wrap tools with game-aware enhancements
+                game_aware = GameAwareTools(
+                    game_state=self._game_state,
+                    session_logger=self._log_session_event,
+                    ui_notifier=self._handle_ui_update,
+                )
+                wrapped_tools = game_aware.wrap_tools(all_tools)
+
+                # Create DM agent
+                self._dm_agent = DungeonMasterAgent(
+                    llm=primary_llm,
+                    tools=wrapped_tools,
+                    game_state=self._game_state,
+                )
+
+                # Create rules agent
+                self._rules_agent = RulesArbiterAgent(
+                    llm=primary_llm,
+                    tools=wrapped_tools,
+                )
+            else:
+                # No MCP - create DM agent without tools
+                self._dm_agent = DungeonMasterAgent(
+                    llm=primary_llm,
+                    tools=[],
+                    game_state=self._game_state,
+                )
+                logger.warning("DM agent created without MCP tools")
+
+            # Initialize voice narrator
+            try:
+                if self._voice_client is None:
+                    self._voice_client = VoiceClient()
+                    await self._voice_client.initialize()
+
+                self._voice_narrator = await create_voice_narrator(
+                    voice_client=self._voice_client,
+                    pre_cache=True,
+                )
+
+                if self._voice_narrator is None:
+                    logger.warning("Voice narrator not available")
+                    self._degradation_level = DegradationLevel.TEXT_ONLY
+            except Exception as e:
+                logger.warning(f"Voice initialization failed: {e}")
+                self._degradation_level = DegradationLevel.TEXT_ONLY
+
+            self._initialized = True
+            logger.info(
+                f"AgentOrchestrator setup complete. "
+                f"Degradation level: {self._degradation_level.value}"
+            )
+
+        except Exception as e:
+            logger.error(f"Orchestrator setup failed: {e}")
+            raise OrchestratorError(f"Setup failed: {e}") from e
+
+    async def process_turn(
+        self,
+        player_input: str,
+        voice_enabled: bool = True,
+    ) -> TurnResult:
+        """
+        Process a complete player turn.
+
+        Args:
+            player_input: The player's action/speech.
+            voice_enabled: Whether to generate voice narration.
+
+        Returns:
+            TurnResult with narration, audio, and state updates.
+        """
+        if not self._initialized:
+            raise OrchestratorNotInitializedError()
+
+        start_time = time.time()
+        turn_number = self._game_state.increment_turn()
+
+        try:
+            # Check for special commands
+            special_result = await self._handle_special_command(player_input)
+            if special_result is not None:
+                return special_result
+
+            # Process through DM agent
+            dm_response = await self._process_dm_turn(player_input)
+
+            # Generate voice narration
+            audio = None
+            logger.info(f"[VOICE] enabled={voice_enabled}, narrator={self._voice_narrator is not None}")
+            if self._voice_narrator:
+                logger.info(f"[VOICE] narrator.is_available={self._voice_narrator.is_available}")
+            
+            if voice_enabled and self._voice_narrator and dm_response:
+                try:
+                    game_context = self._build_game_context()
+                    text_len = len(dm_response.narration)
+                    logger.info(f"[VOICE] Calling narrate(), text_len={text_len}")
+                    narration_result = await self._voice_narrator.narrate(
+                        dm_response, game_context
+                    )
+                    logger.info(f"[VOICE] result.success={narration_result.success}")
+                    if narration_result.success:
+                        audio = narration_result.audio
+                        audio_len = len(audio) if audio else 0
+                        logger.info(f"[VOICE] audio bytes={audio_len}")
+                    else:
+                        logger.warning(f"[VOICE] failed: {narration_result.error_message}")
+                except Exception as e:
+                    logger.warning(f"Voice narration failed: {e}")
+
+            # Update conversation history
+            self._conversation_history.append({
+                "role": "user",
+                "content": player_input,
+            })
+            self._conversation_history.append({
+                "role": "assistant",
+                "content": dm_response.narration if dm_response else "",
+            })
+
+            # Build turn result
+            processing_time = (time.time() - start_time) * 1000
+
+            return TurnResult(
+                narration_text=dm_response.narration if dm_response else "",
+                narration_audio=audio,
+                voice_segments=dm_response.voice_segments if dm_response else [],
+                tool_calls=dm_response.tool_calls if dm_response else [],
+                dice_rolls=dm_response.dice_rolls if dm_response else [],
+                game_mode=dm_response.game_mode if dm_response else GameMode.EXPLORATION,
+                combat_updates=None,  # Would come from tool results
+                special_moment=dm_response.special_moment if dm_response else None,
+                ui_effects=dm_response.ui_effects if dm_response else [],
+                degradation_level=self._degradation_level,
+                voice_enabled=voice_enabled and audio is not None,
+                turn_number=turn_number,
+                processing_time_ms=processing_time,
+                llm_provider=self._llm_chain.current_provider or "unknown" if self._llm_chain else "",
+            )
+
+        except Exception as e:
+            logger.error(f"Turn processing failed: {e}")
+
+            # Return graceful error response
+            processing_time = (time.time() - start_time) * 1000
+
+            return TurnResult(
+                narration_text=get_graceful_message("general_error"),
+                degradation_level=DegradationLevel.MINIMAL,
+                error_message=str(e),
+                turn_number=turn_number,
+                processing_time_ms=processing_time,
+            )
+
+    async def _process_dm_turn(self, player_input: str) -> DMResponse | None:
+        """Process turn through DM agent."""
+        if self._dm_agent is None:
+            logger.error("DM agent not initialized")
+            return None
+
+        try:
+            game_context = self._build_game_context()
+            response = await self._dm_agent.process(player_input, game_context)
+            return response
+        except Exception as e:
+            logger.error(f"DM agent processing failed: {e}")
+            raise
+
+    async def _handle_special_command(
+        self,
+        player_input: str,
+    ) -> TurnResult | None:
+        """
+        Handle special commands like /roll, /rules, etc.
+
+        Returns TurnResult if command was handled, None otherwise.
+        """
+        input_stripped = player_input.strip()
+
+        # Check if it's a special command
+        for command, handler_name in SPECIAL_COMMANDS.items():
+            if input_stripped.lower().startswith(command):
+                # Extract arguments
+                args = input_stripped[len(command):].strip()
+                handler = getattr(self, handler_name, None)
+                if handler:
+                    return await handler(args)
+
+        return None
+
+    async def _handle_roll_command(self, args: str) -> TurnResult:
+        """Handle /roll command for direct dice rolls."""
+        notation = args.strip() or "1d20"
+
+        try:
+            # Call MCP roll tool directly
+            result = await self._toolkit_client.call_tool("roll", {"notation": notation})
+
+            # Format result
+            if isinstance(result, dict):
+                total = result.get("total", 0)
+                narration = f"**Roll {notation}:** {total}"
+                if "breakdown" in result:
+                    narration += f" ({result['breakdown']})"
+            else:
+                narration = f"Roll result: {result}"
+
+            return TurnResult(
+                narration_text=narration,
+                degradation_level=self._degradation_level,
+                turn_number=self._game_state.turn_count,
+            )
+        except Exception as e:
+            return TurnResult(
+                narration_text=f"Roll failed: {e}",
+                error_message=str(e),
+                degradation_level=DegradationLevel.MINIMAL,
+                turn_number=self._game_state.turn_count,
+            )
+
+    async def _handle_rules_command(self, args: str) -> TurnResult:
+        """Handle /rules command for rules lookup."""
+        if not args:
+            return TurnResult(
+                narration_text="Usage: /rules <question> - Ask about game rules",
+                turn_number=self._game_state.turn_count,
+            )
+
+        if self._rules_agent is None:
+            return TurnResult(
+                narration_text="Rules lookup not available.",
+                degradation_level=DegradationLevel.MINIMAL,
+                turn_number=self._game_state.turn_count,
+            )
+
+        try:
+            response = await self._rules_agent.lookup(args)
+            return TurnResult(
+                narration_text=response.answer,
+                tool_calls=response.tool_calls,
+                turn_number=self._game_state.turn_count,
+            )
+        except Exception as e:
+            return TurnResult(
+                narration_text=f"Rules lookup failed: {e}",
+                error_message=str(e),
+                turn_number=self._game_state.turn_count,
+            )
+
+    async def _handle_character_command(self, args: str) -> TurnResult:
+        """Handle /character command to show character sheet."""
+        char_id = self._game_state.active_character_id
+
+        if not char_id:
+            return TurnResult(
+                narration_text="No active character. Create one first!",
+                turn_number=self._game_state.turn_count,
+            )
+
+        try:
+            result = await self._toolkit_client.call_tool(
+                "get_character", {"character_id": char_id}
+            )
+
+            if isinstance(result, dict):
+                # Format character info
+                name = result.get("name", "Unknown")
+                hp = result.get("current_hp", "?")
+                max_hp = result.get("max_hp", "?")
+                level = result.get("level", 1)
+                char_class = result.get("class", "Unknown")
+
+                narration = (
+                    f"**{name}** - Level {level} {char_class}\n"
+                    f"HP: {hp}/{max_hp}"
+                )
+            else:
+                narration = f"Character info: {result}"
+
+            return TurnResult(
+                narration_text=narration,
+                turn_number=self._game_state.turn_count,
+            )
+        except Exception as e:
+            return TurnResult(
+                narration_text=f"Could not fetch character: {e}",
+                error_message=str(e),
+                turn_number=self._game_state.turn_count,
+            )
+
+    async def _handle_inventory_command(self, args: str) -> TurnResult:
+        """Handle /inventory command."""
+        char_id = self._game_state.active_character_id
+
+        if not char_id:
+            return TurnResult(
+                narration_text="No active character.",
+                turn_number=self._game_state.turn_count,
+            )
+
+        try:
+            result = await self._toolkit_client.call_tool(
+                "get_character", {"character_id": char_id}
+            )
+
+            if isinstance(result, dict):
+                equipment = result.get("equipment", [])
+                currency = result.get("currency", {})
+
+                lines = ["**Inventory:**"]
+                for item in equipment[:10]:  # Limit display
+                    if isinstance(item, dict):
+                        lines.append(f"- {item.get('name', 'Unknown item')}")
+                    else:
+                        lines.append(f"- {item}")
+
+                # Add currency
+                gold = currency.get("gold", 0)
+                if gold:
+                    lines.append(f"\n**Gold:** {gold} gp")
+
+                narration = "\n".join(lines)
+            else:
+                narration = "Could not fetch inventory."
+
+            return TurnResult(
+                narration_text=narration,
+                turn_number=self._game_state.turn_count,
+            )
+        except Exception as e:
+            return TurnResult(
+                narration_text=f"Inventory fetch failed: {e}",
+                turn_number=self._game_state.turn_count,
+            )
+
+    async def _handle_rest_command(self, args: str) -> TurnResult:
+        """Handle /rest command."""
+        rest_type = args.strip().lower() or "short"
+        return await self._do_rest(rest_type)
+
+    async def _handle_short_rest_command(self, args: str) -> TurnResult:
+        """Handle /short command for short rest."""
+        return await self._do_rest("short")
+
+    async def _handle_long_rest_command(self, args: str) -> TurnResult:
+        """Handle /long command for long rest."""
+        return await self._do_rest("long")
+
+    async def _do_rest(self, rest_type: str) -> TurnResult:
+        """Execute a rest action."""
+        char_id = self._game_state.active_character_id
+
+        if not char_id:
+            return TurnResult(
+                narration_text="No active character to rest.",
+                turn_number=self._game_state.turn_count,
+            )
+
+        try:
+            result = await self._toolkit_client.call_tool(
+                "rest",
+                {"character_id": char_id, "rest_type": rest_type},
+            )
+
+            narration = f"You complete a {rest_type} rest. "
+            if isinstance(result, dict):
+                hp_restored = result.get("hp_restored", 0)
+                if hp_restored:
+                    narration += f"You recover {hp_restored} hit points."
+
+            return TurnResult(
+                narration_text=narration,
+                turn_number=self._game_state.turn_count,
+            )
+        except Exception as e:
+            return TurnResult(
+                narration_text=f"Rest failed: {e}",
+                turn_number=self._game_state.turn_count,
+            )
+
+    async def _handle_help_command(self, args: str) -> TurnResult:
+        """Handle /help command."""
+        help_text = """**Available Commands:**
+- `/roll <notation>` - Roll dice (e.g., `/roll 2d6+3`)
+- `/rules <question>` - Look up game rules
+- `/character` - Show character sheet
+- `/inventory` - Show inventory
+- `/rest [short|long]` - Take a rest
+- `/combat <enemies>` - Start combat (e.g., `/combat goblin, orc`)
+- `/endcombat` - End current combat
+- `/status` - Show system status
+- `/help` - Show this help
+
+**Gameplay:**
+Just type what you want to do! The DM will guide the adventure.
+Example: "I search the room for hidden doors"
+"""
+        return TurnResult(
+            narration_text=help_text,
+            turn_number=self._game_state.turn_count,
+        )
+
+    async def _handle_status_command(self, args: str) -> TurnResult:
+        """Handle /status command to show system status."""
+        status_parts = []
+
+        # MCP status
+        mcp_status = "Connected" if self._toolkit_client.is_connected else "Disconnected"
+        status_parts.append(f"**MCP Server:** {mcp_status}")
+
+        # LLM status
+        if self._llm_chain:
+            health = self._llm_chain.get_health()
+            for provider, info in health.items():
+                status = "Available" if info.is_available else "Unavailable"
+                primary = " (Primary)" if info.is_primary else ""
+                status_parts.append(f"**{provider.title()}{primary}:** {status}")
+
+        # Voice status
+        if self._voice_narrator:
+            voice_status = "Available" if self._voice_narrator.is_available else "Unavailable"
+            status_parts.append(f"**Voice:** {voice_status}")
+        else:
+            status_parts.append("**Voice:** Not initialized")
+
+        # Degradation level
+        status_parts.append(f"**Mode:** {self._degradation_level.value}")
+
+        return TurnResult(
+            narration_text="\n".join(status_parts),
+            turn_number=self._game_state.turn_count,
+        )
+
+    async def _handle_combat_command(self, args: str) -> TurnResult:
+        """Handle /combat command to start combat with specified enemies."""
+        if not args.strip():
+            return TurnResult(
+                narration_text=(
+                    "**Usage:** `/combat <enemy1>, <enemy2>, ...`\n\n"
+                    "**Examples:**\n"
+                    "- `/combat goblin`\n"
+                    "- `/combat goblin, orc, wolf`\n\n"
+                    "This will start combat with the specified enemies."
+                ),
+                turn_number=self._game_state.turn_count,
+            )
+
+        # Parse enemy names from comma-separated list
+        enemy_names = [name.strip() for name in args.split(",") if name.strip()]
+
+        if not enemy_names:
+            return TurnResult(
+                narration_text="Please specify at least one enemy. Example: `/combat goblin`",
+                turn_number=self._game_state.turn_count,
+            )
+
+        try:
+            # Build combatants list
+            combatants = []
+
+            # Add player character if available
+            player_name = "Player"
+            player_hp = 20
+            player_ac = 14
+
+            if self._game_state.active_character_id:
+                char_data = self._game_state.get_character(
+                    self._game_state.active_character_id
+                )
+                if char_data:
+                    player_name = str(char_data.get("name", "Player"))
+                    hp_data = char_data.get("hit_points", {})
+                    if isinstance(hp_data, dict):
+                        player_hp = int(hp_data.get("current", 20))
+                        player_ac = int(char_data.get("armor_class", 14))
+
+            # Roll player initiative
+            player_init_result = await self._toolkit_client.call_tool(
+                "roll", {"notation": "1d20"}
+            )
+            player_init = 10
+            if isinstance(player_init_result, dict):
+                player_init = int(player_init_result.get("total", 10))
+
+            combatants.append({
+                "id": self._game_state.active_character_id or "player",
+                "name": player_name,
+                "initiative": player_init,
+                "hp_current": player_hp,
+                "hp_max": player_hp,
+                "armor_class": player_ac,
+                "is_player": True,
+                "conditions": [],
+            })
+
+            # Add enemies - try to get monster stats, fallback to defaults
+            for i, enemy_name in enumerate(enemy_names):
+                enemy_hp = 7  # Default goblin-like HP
+                enemy_ac = 12
+                enemy_init = 10
+
+                # Try to get monster stats
+                try:
+                    monster_result = await self._toolkit_client.call_tool(
+                        "get_monster", {"name": enemy_name}
+                    )
+                    if isinstance(monster_result, dict) and monster_result.get("success"):
+                        monster_data = monster_result.get("monster", {})
+                        if isinstance(monster_data, dict):
+                            enemy_hp = int(monster_data.get("hit_points", 7))
+                            enemy_ac = int(monster_data.get("armor_class", 12))
+                except Exception:
+                    pass  # Use defaults
+
+                # Roll enemy initiative
+                try:
+                    enemy_init_result = await self._toolkit_client.call_tool(
+                        "roll", {"notation": "1d20"}
+                    )
+                    if isinstance(enemy_init_result, dict):
+                        enemy_init = int(enemy_init_result.get("total", 10))
+                except Exception:
+                    enemy_init = 10
+
+                combatants.append({
+                    "id": f"enemy_{i}",
+                    "name": enemy_name.title(),
+                    "initiative": enemy_init,
+                    "hp_current": enemy_hp,
+                    "hp_max": enemy_hp,
+                    "armor_class": enemy_ac,
+                    "is_player": False,
+                    "conditions": [],
+                })
+
+            # Sort by initiative (descending)
+            combatants.sort(key=lambda c: c["initiative"], reverse=True)
+
+            # Try to call start_combat tool
+            try:
+                result = await self._toolkit_client.call_tool(
+                    "start_combat",
+                    {"combatants": combatants},
+                )
+
+                # Update game state
+                combat_state = {
+                    "turn_order": combatants,
+                    "current_turn_index": 0,
+                    "round": 1,
+                    "is_active": True,
+                }
+
+                if isinstance(result, dict):
+                    combat_state.update(result)
+
+                self._game_state.set_combat_state(combat_state)
+
+            except Exception as e:
+                logger.warning(f"start_combat tool failed: {e}, using local state")
+                # Set combat state directly if tool fails
+                combat_state = {
+                    "turn_order": combatants,
+                    "current_turn_index": 0,
+                    "round": 1,
+                    "is_active": True,
+                }
+                self._game_state.set_combat_state(combat_state)
+
+            # Build response
+            initiative_lines = ["**Combat Begins!**\n", "**Initiative Order:**"]
+            for i, c in enumerate(combatants):
+                marker = "▶ " if i == 0 else "  "
+                player_marker = "🛡️" if c["is_player"] else "👹"
+                initiative_lines.append(
+                    f"{marker}{c['initiative']:2d} | {player_marker} {c['name']} "
+                    f"(HP: {c['hp_current']}/{c['hp_max']}, AC: {c['armor_class']})"
+                )
+
+            current = combatants[0]
+            if current["is_player"]:
+                initiative_lines.append(f"\n**It's your turn, {current['name']}!** What do you do?")
+            else:
+                initiative_lines.append(f"\n**{current['name']} goes first!**")
+
+            return TurnResult(
+                narration_text="\n".join(initiative_lines),
+                turn_number=self._game_state.turn_count,
+            )
+
+        except Exception as e:
+            logger.error(f"Combat command failed: {e}")
+            return TurnResult(
+                narration_text=f"Failed to start combat: {e}",
+                error_message=str(e),
+                turn_number=self._game_state.turn_count,
+            )
+
+    async def _handle_end_combat_command(self, args: str) -> TurnResult:
+        """Handle /endcombat command to end current combat."""
+        if not self._game_state.in_combat:
+            return TurnResult(
+                narration_text="*You are not currently in combat.*",
+                turn_number=self._game_state.turn_count,
+            )
+
+        try:
+            # Try to call end_combat tool
+            await self._toolkit_client.call_tool("end_combat", {})
+        except Exception as e:
+            logger.warning(f"end_combat tool failed: {e}")
+
+        # Clear combat state
+        self._game_state.set_combat_state(None)
+
+        return TurnResult(
+            narration_text="**Combat Ends!**\n\n*The dust settles as the battle concludes.*",
+            turn_number=self._game_state.turn_count,
+        )
+
+    def _build_game_context(self) -> GameContext:
+        """Build game context from current state."""
+        return GameContext(
+            session_id=self._game_state.session_id,
+            turn_number=self._game_state.turn_count,
+            game_mode=self._dm_agent.mode if self._dm_agent else GameMode.EXPLORATION,
+            current_location=self._game_state.current_location,
+            active_character_id=self._game_state.active_character_id,
+            in_combat=self._game_state.in_combat,
+            combat_round=self._game_state.combat_state.get("round") if self._game_state.combat_state else None,
+            adventure_name=self._game_state.current_adventure,
+        )
+
+    async def _log_session_event(
+        self,
+        event_type: str,
+        description: str,
+        data: dict[str, object],
+    ) -> None:
+        """Callback for logging session events."""
+        self._game_state.add_event(event_type, description, data)
+
+    def _handle_ui_update(self, update_type: str, data: dict[str, object]) -> None:
+        """Callback for UI updates from tool wrappers."""
+        # This would notify the UI layer
+        logger.debug(f"UI update: {update_type} - {data}")
+
+    async def new_game(
+        self,
+        character_id: str | None = None,
+        adventure_name: str | None = None,
+    ) -> TurnResult:
+        """
+        Start a new game.
+
+        Args:
+            character_id: Optional character to use.
+            adventure_name: Optional adventure to load.
+
+        Returns:
+            TurnResult with opening narration.
+        """
+        # Reset state
+        self._game_state.reset()
+        self._conversation_history.clear()
+        self._pacing.reset()
+
+        if self._dm_agent:
+            self._dm_agent.clear_memory()
+
+        if self._rules_agent:
+            self._rules_agent.clear_cache()
+
+        # Set adventure
+        if adventure_name:
+            self._game_state.current_adventure = adventure_name
+
+        # Add character
+        if character_id:
+            self._game_state.add_character_to_party(character_id)
+
+        # Generate opening narration
+        opening = await self._process_dm_turn(
+            "Begin a new adventure. Set the scene and introduce the player to their situation."
+        )
+
+        return TurnResult(
+            narration_text=opening.narration if opening else "Your adventure begins...",
+            voice_segments=opening.voice_segments if opening else [],
+            game_mode=GameMode.EXPLORATION,
+            degradation_level=self._degradation_level,
+            turn_number=0,
+        )
+
+    async def shutdown(self) -> None:
+        """Gracefully shutdown the orchestrator."""
+        logger.info("Shutting down AgentOrchestrator...")
+
+        if self._toolkit_client:
+            await self._toolkit_client.disconnect()
+
+        self._initialized = False
+        logger.info("AgentOrchestrator shutdown complete")
+
+
+# =============================================================================
+# Factory Function
+# =============================================================================
+
+
+async def create_orchestrator(
+    settings: AppSettings | None = None,
+) -> AgentOrchestrator:
+    """
+    Create and initialize an AgentOrchestrator.
+
+    Args:
+        settings: Optional application settings.
+
+    Returns:
+        Initialized AgentOrchestrator ready for use.
+    """
+    orchestrator = AgentOrchestrator(settings=settings)
+    await orchestrator.setup()
+    return orchestrator

src/agents/pacing_controller.py

@@ -0,0 +1,271 @@
+"""
+DungeonMaster AI - Pacing Controller
+
+Controls response verbosity and style based on game context.
+Ensures appropriate pacing for different gameplay situations.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .models import GameMode, PacingStyle, SpecialMoment
+
+if TYPE_CHECKING:
+    from src.game.game_state import GameState
+
+
+# =============================================================================
+# Pacing Instructions
+# =============================================================================
+
+
+PACING_INSTRUCTIONS: dict[PacingStyle, str] = {
+    PacingStyle.VERBOSE: """
+## Current Pacing: VERBOSE
+This is a moment for world-building and immersion. Use rich, evocative descriptions.
+- Describe the environment with sensory details (sight, sound, smell, feel)
+- Paint a vivid picture of the scene
+- Use 3-5 sentences for descriptions
+- Take time to set the atmosphere
+- Let the player absorb the moment
+""",
+    PacingStyle.STANDARD: """
+## Current Pacing: STANDARD
+Balance description with action. Keep things moving but engaging.
+- Use 2-3 sentences for responses
+- Describe key details without overwhelming
+- Focus on what's immediately relevant
+- End with a clear prompt for player action
+""",
+    PacingStyle.QUICK: """
+## Current Pacing: QUICK
+Combat or action sequence. Keep it fast and punchy.
+- Use 1-2 sentences per action
+- Focus on immediate results
+- Maintain tension and momentum
+- Clear, direct descriptions
+- No lengthy exposition
+""",
+    PacingStyle.DRAMATIC: """
+## Current Pacing: DRAMATIC
+Critical moment requiring impact. Short, powerful statements.
+- Use short, punchy sentences
+- Build tension with pauses (...)
+- Make every word count
+- Emphasize the stakes
+- Let the moment breathe
+""",
+}
+
+
+# =============================================================================
+# PacingController
+# =============================================================================
+
+
+class PacingController:
+    """
+    Controls response verbosity based on game context.
+
+    Determines appropriate pacing style and provides instructions
+    to inject into the DM agent's system prompt.
+    """
+
+    # Keywords that suggest quick pacing
+    QUICK_KEYWORDS: frozenset[str] = frozenset([
+        "attack",
+        "hit",
+        "strike",
+        "shoot",
+        "cast",
+        "dodge",
+        "run",
+        "flee",
+        "block",
+        "parry",
+    ])
+
+    # Keywords that suggest verbose pacing
+    VERBOSE_KEYWORDS: frozenset[str] = frozenset([
+        "look",
+        "examine",
+        "describe",
+        "search",
+        "explore",
+        "enter",
+        "arrive",
+        "approach",
+    ])
+
+    # Keywords that suggest social pacing
+    SOCIAL_KEYWORDS: frozenset[str] = frozenset([
+        "talk",
+        "speak",
+        "ask",
+        "tell",
+        "persuade",
+        "convince",
+        "negotiate",
+        "bribe",
+    ])
+
+    def __init__(self) -> None:
+        """Initialize the pacing controller."""
+        self._last_pacing = PacingStyle.STANDARD
+        self._location_changes = 0
+        self._combat_turn_count = 0
+
+    def determine_pacing(
+        self,
+        game_mode: GameMode,
+        player_input: str,
+        game_state: GameState | None = None,
+        special_moment: SpecialMoment | None = None,
+    ) -> PacingStyle:
+        """
+        Determine appropriate pacing style.
+
+        Args:
+            game_mode: Current game mode.
+            player_input: The player's input.
+            game_state: Current game state.
+            special_moment: Special moment if any.
+
+        Returns:
+            Appropriate PacingStyle.
+        """
+        # Special moments always get dramatic pacing
+        if special_moment is not None:
+            return PacingStyle.DRAMATIC
+
+        # Combat mode generally uses quick pacing
+        if game_mode == GameMode.COMBAT:
+            self._combat_turn_count += 1
+            # First combat turn or every 3rd turn can be slightly more descriptive
+            if self._combat_turn_count == 1:
+                return PacingStyle.STANDARD
+            return PacingStyle.QUICK
+
+        # Reset combat counter when not in combat
+        if game_mode != GameMode.COMBAT:
+            self._combat_turn_count = 0
+
+        # Check player input for pacing hints
+        input_lower = player_input.lower()
+
+        # Quick keywords override
+        if any(kw in input_lower for kw in self.QUICK_KEYWORDS):
+            return PacingStyle.QUICK
+
+        # Verbose keywords for exploration
+        if any(kw in input_lower for kw in self.VERBOSE_KEYWORDS):
+            return PacingStyle.VERBOSE
+
+        # Social interaction is standard pacing
+        if any(kw in input_lower for kw in self.SOCIAL_KEYWORDS):
+            return PacingStyle.STANDARD
+
+        # Check for location changes
+        if game_state:
+            if self._is_new_location(game_state):
+                self._location_changes += 1
+                return PacingStyle.VERBOSE
+
+        # Default based on game mode
+        mode_defaults: dict[GameMode, PacingStyle] = {
+            GameMode.EXPLORATION: PacingStyle.STANDARD,
+            GameMode.COMBAT: PacingStyle.QUICK,
+            GameMode.SOCIAL: PacingStyle.STANDARD,
+            GameMode.NARRATIVE: PacingStyle.VERBOSE,
+        }
+
+        return mode_defaults.get(game_mode, PacingStyle.STANDARD)
+
+    def _is_new_location(self, game_state: GameState) -> bool:
+        """
+        Check if player just entered a new location.
+
+        Args:
+            game_state: Current game state.
+
+        Returns:
+            True if location recently changed.
+        """
+        # Check recent events for location change
+        for event in reversed(game_state.recent_events[-3:]):
+            if event.get("type") == "movement":
+                return True
+        return False
+
+    def get_pacing_instruction(self, pacing: PacingStyle) -> str:
+        """
+        Get instruction text for a pacing style.
+
+        Args:
+            pacing: The pacing style.
+
+        Returns:
+            Instruction text to inject into system prompt.
+        """
+        return PACING_INSTRUCTIONS.get(pacing, PACING_INSTRUCTIONS[PacingStyle.STANDARD])
+
+    def get_sentence_range(self, pacing: PacingStyle) -> tuple[int, int]:
+        """
+        Get recommended sentence count range.
+
+        Args:
+            pacing: The pacing style.
+
+        Returns:
+            Tuple of (min_sentences, max_sentences).
+        """
+        ranges: dict[PacingStyle, tuple[int, int]] = {
+            PacingStyle.VERBOSE: (3, 5),
+            PacingStyle.STANDARD: (2, 3),
+            PacingStyle.QUICK: (1, 2),
+            PacingStyle.DRAMATIC: (1, 3),
+        }
+        return ranges.get(pacing, (2, 3))
+
+    def should_include_ambient_detail(self, pacing: PacingStyle) -> bool:
+        """
+        Check if ambient details should be included.
+
+        Args:
+            pacing: The pacing style.
+
+        Returns:
+            True if ambient details are appropriate.
+        """
+        return pacing in (PacingStyle.VERBOSE, PacingStyle.STANDARD)
+
+    def should_prompt_for_action(self, pacing: PacingStyle) -> bool:
+        """
+        Check if response should end with action prompt.
+
+        Args:
+            pacing: The pacing style.
+
+        Returns:
+            True if action prompt is appropriate.
+        """
+        # Quick pacing often ends with clear action options
+        # Dramatic moments should let the moment breathe
+        return pacing in (PacingStyle.STANDARD, PacingStyle.QUICK)
+
+    def reset(self) -> None:
+        """Reset pacing state for new game."""
+        self._last_pacing = PacingStyle.STANDARD
+        self._location_changes = 0
+        self._combat_turn_count = 0
+
+
+# =============================================================================
+# Factory Function
+# =============================================================================
+
+
+def create_pacing_controller() -> PacingController:
+    """Create a new PacingController instance."""
+    return PacingController()

src/agents/rules_arbiter.py

@@ -0,0 +1,446 @@
+"""
+DungeonMaster AI - Rules Arbiter Agent
+
+Specialized agent for rules lookup with LRU caching.
+Uses only rules-related MCP tools for focused, accurate responses.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from functools import lru_cache
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.core.tools import FunctionTool
+
+from src.config.settings import get_settings
+
+from .exceptions import RulesAgentError
+from .models import RulesResponse, ToolCallInfo
+
+if TYPE_CHECKING:
+    from llama_index.core.llms import LLM
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Rules System Prompt
+# =============================================================================
+
+
+def load_rules_prompt() -> str:
+    """
+    Load the rules arbiter system prompt.
+
+    Returns:
+        System prompt string.
+    """
+    settings = get_settings()
+    prompts_dir = settings.prompts_dir
+
+    rules_path = Path(prompts_dir) / "rules_system.txt"
+    if rules_path.exists():
+        return rules_path.read_text()
+
+    # Fallback prompt
+    return """You are a D&D 5e rules expert and arbiter.
+
+Your responsibilities:
+1. Look up rules accurately using the available tools
+2. Cite sources when providing rule information
+3. Explain rules clearly and concisely
+4. Help adjudicate edge cases fairly
+
+CRITICAL: Always use tools to verify rules - never guess or assume.
+
+When answering:
+- Use search_rules for general mechanics questions
+- Use get_monster for creature stats
+- Use get_spell for spell mechanics
+- Use get_condition for status effect rules
+
+Provide the rule, then a brief explanation of how it applies."""
+
+
+# =============================================================================
+# Cache Wrappers
+# =============================================================================
+
+
+class RulesCache:
+    """
+    LRU cache wrapper for rules lookups.
+
+    Caches monster stats, spell info, and rule queries
+    to avoid repeated MCP calls.
+    """
+
+    def __init__(self, maxsize: int = 100) -> None:
+        """
+        Initialize the rules cache.
+
+        Args:
+            maxsize: Maximum cache size per category.
+        """
+        self._maxsize = maxsize
+        self._monster_cache: dict[str, dict[str, object]] = {}
+        self._spell_cache: dict[str, dict[str, object]] = {}
+        self._condition_cache: dict[str, dict[str, object]] = {}
+        self._query_cache: dict[str, str] = {}
+
+        # Cache statistics
+        self._hits = 0
+        self._misses = 0
+
+    def get_monster(self, name: str) -> dict[str, object] | None:
+        """Get cached monster stats."""
+        key = name.lower()
+        if key in self._monster_cache:
+            self._hits += 1
+            return self._monster_cache[key]
+        self._misses += 1
+        return None
+
+    def set_monster(self, name: str, data: dict[str, object]) -> None:
+        """Cache monster stats."""
+        key = name.lower()
+        if len(self._monster_cache) >= self._maxsize:
+            # Remove oldest entry (simple FIFO, not true LRU)
+            oldest = next(iter(self._monster_cache))
+            del self._monster_cache[oldest]
+        self._monster_cache[key] = data
+
+    def get_spell(self, name: str) -> dict[str, object] | None:
+        """Get cached spell info."""
+        key = name.lower()
+        if key in self._spell_cache:
+            self._hits += 1
+            return self._spell_cache[key]
+        self._misses += 1
+        return None
+
+    def set_spell(self, name: str, data: dict[str, object]) -> None:
+        """Cache spell info."""
+        key = name.lower()
+        if len(self._spell_cache) >= self._maxsize:
+            oldest = next(iter(self._spell_cache))
+            del self._spell_cache[oldest]
+        self._spell_cache[key] = data
+
+    def get_condition(self, name: str) -> dict[str, object] | None:
+        """Get cached condition info."""
+        key = name.lower()
+        if key in self._condition_cache:
+            self._hits += 1
+            return self._condition_cache[key]
+        self._misses += 1
+        return None
+
+    def set_condition(self, name: str, data: dict[str, object]) -> None:
+        """Cache condition info."""
+        key = name.lower()
+        if len(self._condition_cache) >= self._maxsize:
+            oldest = next(iter(self._condition_cache))
+            del self._condition_cache[oldest]
+        self._condition_cache[key] = data
+
+    def get_query(self, query: str) -> str | None:
+        """Get cached query result."""
+        key = query.lower().strip()
+        if key in self._query_cache:
+            self._hits += 1
+            return self._query_cache[key]
+        self._misses += 1
+        return None
+
+    def set_query(self, query: str, result: str) -> None:
+        """Cache query result."""
+        key = query.lower().strip()
+        if len(self._query_cache) >= self._maxsize:
+            oldest = next(iter(self._query_cache))
+            del self._query_cache[oldest]
+        self._query_cache[key] = result
+
+    @property
+    def hit_rate(self) -> float:
+        """Calculate cache hit rate."""
+        total = self._hits + self._misses
+        return self._hits / total if total > 0 else 0.0
+
+    def clear(self) -> None:
+        """Clear all caches."""
+        self._monster_cache.clear()
+        self._spell_cache.clear()
+        self._condition_cache.clear()
+        self._query_cache.clear()
+        self._hits = 0
+        self._misses = 0
+
+
+# =============================================================================
+# RulesArbiterAgent
+# =============================================================================
+
+
+class RulesArbiterAgent:
+    """
+    Specialized rules lookup agent with LRU caching.
+
+    Only uses rules-related MCP tools:
+    - search_rules: Search rules by topic
+    - get_monster: Get monster stat block
+    - get_spell: Get spell description
+    - get_class_info: Get class features
+    - get_race_info: Get race abilities
+    - get_condition: Get condition effects
+    """
+
+    # Rules tool names to filter
+    RULES_TOOLS = frozenset([
+        "search_rules",
+        "get_monster",
+        "search_monsters",
+        "get_spell",
+        "search_spells",
+        "get_class_info",
+        "get_race_info",
+        "get_item",
+        "get_condition",
+        # MCP prefixed versions
+        "mcp_search_rules",
+        "mcp_get_monster",
+        "mcp_search_monsters",
+        "mcp_get_spell",
+        "mcp_search_spells",
+        "mcp_get_class_info",
+        "mcp_get_race_info",
+        "mcp_get_item",
+        "mcp_get_condition",
+    ])
+
+    def __init__(
+        self,
+        llm: LLM,
+        tools: list[FunctionTool],
+        cache_size: int = 100,
+    ) -> None:
+        """
+        Initialize the Rules Arbiter agent.
+
+        Args:
+            llm: LlamaIndex LLM instance.
+            tools: List of ALL MCP tools (will be filtered to rules only).
+            cache_size: Maximum cache size per category.
+        """
+        self._llm = llm
+
+        # Filter to rules tools only
+        self._tools = [
+            tool for tool in tools
+            if tool.metadata.name in self.RULES_TOOLS
+        ]
+
+        logger.info(
+            f"RulesArbiterAgent initialized with {len(self._tools)} rules tools"
+        )
+
+        # Initialize cache
+        self._cache = RulesCache(maxsize=cache_size)
+
+        # Load system prompt
+        self._system_prompt = load_rules_prompt()
+
+        # Create focused FunctionAgent
+        self._agent = FunctionAgent(
+            llm=llm,
+            tools=self._tools,
+            system_prompt=self._system_prompt,
+        )
+
+    @property
+    def cache_hit_rate(self) -> float:
+        """Get cache hit rate."""
+        return self._cache.hit_rate
+
+    async def lookup(self, query: str) -> RulesResponse:
+        """
+        Look up rules for a query.
+
+        Args:
+            query: The rules question or topic.
+
+        Returns:
+            RulesResponse with answer and sources.
+        """
+        start_time = time.time()
+
+        # Check cache first
+        cached_result = self._cache.get_query(query)
+        if cached_result:
+            logger.debug(f"Cache hit for query: {query[:50]}...")
+            return RulesResponse(
+                answer=cached_result,
+                sources=["cache"],
+                confidence=1.0,
+                from_cache=True,
+            )
+
+        try:
+            # Run the agent
+            handler = self._agent.run(user_msg=query)
+
+            response_text = ""
+            tool_calls: list[ToolCallInfo] = []
+            sources: list[str] = []
+
+            async for event in handler.stream_events():
+                event_type = type(event).__name__
+
+                if event_type == "AgentOutput":
+                    response_text = str(event.response) if hasattr(event, "response") else ""
+
+                elif event_type == "ToolCall":
+                    if hasattr(event, "tool_name"):
+                        tool_info = ToolCallInfo(
+                            tool_name=event.tool_name,
+                            arguments=getattr(event, "arguments", {}),
+                        )
+                        tool_calls.append(tool_info)
+                        sources.append(event.tool_name)
+
+                elif event_type == "ToolCallResult":
+                    if hasattr(event, "result") and tool_calls:
+                        tool_calls[-1].result = event.result
+                        tool_calls[-1].success = True
+
+                        # Cache specific lookups
+                        self._cache_tool_result(tool_calls[-1])
+
+            # Cache the full query result
+            if response_text:
+                self._cache.set_query(query, response_text)
+
+            return RulesResponse(
+                answer=response_text,
+                sources=list(set(sources)),
+                confidence=1.0 if tool_calls else 0.5,
+                tool_calls=tool_calls,
+                from_cache=False,
+            )
+
+        except Exception as e:
+            logger.error(f"Rules lookup failed: {e}")
+            raise RulesAgentError(str(e)) from e
+
+    def _cache_tool_result(self, tool_call: ToolCallInfo) -> None:
+        """Cache individual tool results."""
+        if not tool_call.success or not tool_call.result:
+            return
+
+        result = tool_call.result
+        if not isinstance(result, dict):
+            return
+
+        tool_name = tool_call.tool_name.replace("mcp_", "")
+
+        if tool_name == "get_monster":
+            name = tool_call.arguments.get("name", "")
+            if name:
+                self._cache.set_monster(str(name), result)
+
+        elif tool_name == "get_spell":
+            name = tool_call.arguments.get("name", "")
+            if name:
+                self._cache.set_spell(str(name), result)
+
+        elif tool_name == "get_condition":
+            name = tool_call.arguments.get("name", "")
+            if name:
+                self._cache.set_condition(str(name), result)
+
+    async def get_monster_stats(self, monster_name: str) -> dict[str, object] | None:
+        """
+        Get monster stats with caching.
+
+        Args:
+            monster_name: Name of the monster.
+
+        Returns:
+            Monster stat block or None if not found.
+        """
+        # Check cache
+        cached = self._cache.get_monster(monster_name)
+        if cached:
+            return cached
+
+        # Look up via agent
+        response = await self.lookup(f"Get full stat block for {monster_name}")
+
+        # Try to extract monster data from response
+        for tool_call in response.tool_calls:
+            if "monster" in tool_call.tool_name.lower():
+                if tool_call.result and isinstance(tool_call.result, dict):
+                    return tool_call.result
+
+        return None
+
+    async def get_spell_info(self, spell_name: str) -> dict[str, object] | None:
+        """
+        Get spell info with caching.
+
+        Args:
+            spell_name: Name of the spell.
+
+        Returns:
+            Spell info or None if not found.
+        """
+        # Check cache
+        cached = self._cache.get_spell(spell_name)
+        if cached:
+            return cached
+
+        # Look up via agent
+        response = await self.lookup(f"Get full description for the spell {spell_name}")
+
+        # Try to extract spell data from response
+        for tool_call in response.tool_calls:
+            if "spell" in tool_call.tool_name.lower():
+                if tool_call.result and isinstance(tool_call.result, dict):
+                    return tool_call.result
+
+        return None
+
+    async def get_condition_info(self, condition_name: str) -> dict[str, object] | None:
+        """
+        Get condition info with caching.
+
+        Args:
+            condition_name: Name of the condition.
+
+        Returns:
+            Condition info or None if not found.
+        """
+        # Check cache
+        cached = self._cache.get_condition(condition_name)
+        if cached:
+            return cached
+
+        # Look up via agent
+        response = await self.lookup(f"What are the effects of the {condition_name} condition?")
+
+        # Try to extract condition data from response
+        for tool_call in response.tool_calls:
+            if "condition" in tool_call.tool_name.lower():
+                if tool_call.result and isinstance(tool_call.result, dict):
+                    return tool_call.result
+
+        return None
+
+    def clear_cache(self) -> None:
+        """Clear all caches."""
+        self._cache.clear()
+        logger.info("Rules cache cleared")

src/agents/special_moments.py

@@ -0,0 +1,474 @@
+"""
+DungeonMaster AI - Special Moments Handler
+
+Handles dramatic game moments with enhanced narration and effects.
+Critical hits, death saves, killing blows, and more.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import TYPE_CHECKING
+
+from src.voice.models import VoiceType
+
+from .models import SpecialMoment, SpecialMomentType
+
+if TYPE_CHECKING:
+    from src.mcp_integration.models import DiceRollResult
+
+
+# =============================================================================
+# Narration Templates
+# =============================================================================
+
+
+CRITICAL_HIT_TEMPLATES: list[str] = [
+    "CRITICAL HIT! Your {weapon} finds the perfect opening, striking with devastating precision!",
+    "A critical strike! Time seems to slow as your blow lands with incredible force!",
+    "CRITICAL! The strike of legends! Your attack connects with brutal efficiency!",
+    "Perfection in motion! A critical hit that will be sung about for ages!",
+    "The gods smile upon you! A devastating critical hit!",
+]
+
+CRITICAL_MISS_TEMPLATES: list[str] = [
+    "A fumble! Your attack goes wide, leaving you momentarily off-balance.",
+    "Critical miss! In your eagerness, your strike goes terribly wrong.",
+    "Disaster! Your weapon slips at the worst possible moment.",
+    "A fumble of epic proportions! This will not be your finest moment.",
+    "Critical failure! The attack goes awry in embarrassing fashion.",
+]
+
+DEATH_SAVE_SUCCESS_TEMPLATES: list[str] = [
+    "You cling to consciousness, fighting the darkness. Not today. You will NOT fall.",
+    "Your heartbeat steadies. The void retreats, for now.",
+    "With iron will, you resist death's embrace. The fight continues.",
+    "Light pierces the darkness. You hold on.",
+    "Your spirit refuses to yield. One success closer to survival.",
+]
+
+DEATH_SAVE_FAILURE_TEMPLATES: list[str] = [
+    "The void beckons... darkness creeps closer. But you resist. For now.",
+    "Your grip on life weakens. The shadows grow longer.",
+    "Pain. Darkness. The thread of life grows thin.",
+    "Death's cold hand reaches for you. One step closer to the abyss.",
+    "Consciousness fades at the edges. Time grows short.",
+]
+
+DEATH_SAVE_NAT_20_TEMPLATES: list[str] = [
+    "Your eyes SNAP open! Against all odds, you RISE, defying death itself!",
+    "IMPOSSIBLE! You surge back to consciousness with renewed vigor!",
+    "The light of life BLAZES within you! You stand, death thoroughly denied!",
+    "By sheer force of will, you RETURN! One hit point and ready to fight!",
+    "MIRACULOUS! You gasp awake, snatched from death's very door!",
+]
+
+DEATH_SAVE_NAT_1_TEMPLATES: list[str] = [
+    "Darkness surges. Two failures. Death's grip tightens relentlessly...",
+    "The void PULLS. Two steps toward oblivion in a single heartbeat.",
+    "Critical failure. Death looms ever closer. Hope dims.",
+    "The worst possible outcome. Life slips away faster.",
+    "A gasp. A shudder. Two failures. The end draws near.",
+]
+
+KILLING_BLOW_TEMPLATES: list[str] = [
+    "With a final, devastating strike, your {weapon} ends the {enemy}! Victory!",
+    "The killing blow lands! The {enemy} crumples, defeated at last!",
+    "FINISHED! Your {weapon} claims another foe as the {enemy} falls!",
+    "The {enemy} meets its end! Your strike is final and absolute!",
+    "With righteous fury, you deliver the killing blow! The {enemy} is no more!",
+]
+
+COMBAT_START_TEMPLATES: list[str] = [
+    "Combat begins! Steel clashes and magic crackles as battle is joined!",
+    "Initiative! The dance of death begins!",
+    "Roll for initiative! Combat erupts!",
+    "Weapons are drawn! Let battle commence!",
+    "The fight is on! May fortune favor the bold!",
+]
+
+COMBAT_VICTORY_TEMPLATES: list[str] = [
+    "Victory! The last enemy falls as the dust settles.",
+    "Combat ends! You stand triumphant over your fallen foes!",
+    "The battle is won! Take a moment to catch your breath.",
+    "Silence falls. The enemies are defeated. You are victorious.",
+    "The fight is over. You emerge victorious!",
+]
+
+LEVEL_UP_TEMPLATES: list[str] = [
+    "LEVEL UP! You feel power surge through you as experience crystallizes into new abilities!",
+    "Your training pays off! You've achieved a new level of mastery!",
+    "Growth! You feel yourself becoming stronger, wiser, more capable!",
+    "The journey continues upward! Level gained!",
+    "Experience transforms into power! You have leveled up!",
+]
+
+
+# =============================================================================
+# UI Effects
+# =============================================================================
+
+
+UI_EFFECTS: dict[str, dict[str, object]] = {
+    "screen_shake": {
+        "type": "animation",
+        "name": "shake",
+        "duration_ms": 500,
+        "intensity": "medium",
+    },
+    "golden_glow": {
+        "type": "overlay",
+        "color": "#FFD700",
+        "duration_ms": 1000,
+        "animation": "pulse",
+    },
+    "red_flash": {
+        "type": "overlay",
+        "color": "#8B0000",
+        "duration_ms": 500,
+        "animation": "flash",
+    },
+    "darkness_pulse": {
+        "type": "overlay",
+        "color": "#000000",
+        "duration_ms": 800,
+        "animation": "pulse",
+        "opacity": 0.7,
+    },
+    "golden_resurrection": {
+        "type": "overlay",
+        "color": "#FFD700",
+        "duration_ms": 1500,
+        "animation": "radiate",
+    },
+    "victory_sparkle": {
+        "type": "particles",
+        "color": "#FFD700",
+        "count": 50,
+        "duration_ms": 2000,
+    },
+    "level_up_glow": {
+        "type": "overlay",
+        "color": "#00FF00",
+        "duration_ms": 2000,
+        "animation": "radiate",
+    },
+}
+
+
+# =============================================================================
+# SpecialMomentHandler
+# =============================================================================
+
+
+class SpecialMomentHandler:
+    """
+    Handles dramatic game moments with enhanced narration.
+
+    Detects and creates appropriate responses for:
+    - Critical hits (natural 20 on attack)
+    - Critical misses (natural 1 on attack)
+    - Death save successes and failures
+    - Natural 20/1 on death saves
+    - Killing blows
+    - Combat start/victory
+    - Level ups
+    """
+
+    def __init__(self) -> None:
+        """Initialize the special moment handler."""
+        pass
+
+    def handle_critical_hit(
+        self,
+        weapon: str = "weapon",
+        damage: int | None = None,
+        target: str = "enemy",
+    ) -> SpecialMoment:
+        """
+        Create special moment for critical hit.
+
+        Args:
+            weapon: Weapon used for the attack.
+            damage: Damage dealt (if known).
+            target: Target of the attack.
+
+        Returns:
+            SpecialMoment with enhanced narration.
+        """
+        template = random.choice(CRITICAL_HIT_TEMPLATES)
+        narration = template.format(weapon=weapon)
+
+        return SpecialMoment(
+            moment_type=SpecialMomentType.CRITICAL_HIT,
+            enhanced_narration=narration,
+            voice_type=VoiceType.DM,
+            ui_effects=["screen_shake", "golden_glow"],
+            pause_before_ms=500,
+            sound_effect="critical_hit",
+            context={
+                "weapon": weapon,
+                "damage": damage,
+                "target": target,
+            },
+        )
+
+    def handle_critical_miss(
+        self,
+        weapon: str = "weapon",
+    ) -> SpecialMoment:
+        """
+        Create special moment for critical miss.
+
+        Args:
+            weapon: Weapon used for the attack.
+
+        Returns:
+            SpecialMoment with enhanced narration.
+        """
+        template = random.choice(CRITICAL_MISS_TEMPLATES)
+
+        return SpecialMoment(
+            moment_type=SpecialMomentType.CRITICAL_MISS,
+            enhanced_narration=template,
+            voice_type=VoiceType.DM,
+            ui_effects=["red_flash"],
+            pause_before_ms=300,
+            sound_effect="fumble",
+            context={"weapon": weapon},
+        )
+
+    def handle_death_save(
+        self,
+        roll: int,
+        successes: int = 0,
+        failures: int = 0,
+    ) -> SpecialMoment:
+        """
+        Create special moment for death saving throw.
+
+        Args:
+            roll: The die roll result.
+            successes: Current number of successes.
+            failures: Current number of failures.
+
+        Returns:
+            SpecialMoment with appropriate narration.
+        """
+        # Natural 20 - instant recovery
+        if roll == 20:
+            return SpecialMoment(
+                moment_type=SpecialMomentType.DEATH_SAVE_NAT_20,
+                enhanced_narration=random.choice(DEATH_SAVE_NAT_20_TEMPLATES),
+                voice_type=VoiceType.DM,
+                ui_effects=["golden_resurrection", "screen_shake"],
+                pause_before_ms=800,
+                sound_effect="resurrection",
+                context={
+                    "roll": roll,
+                    "successes": 3,  # Instant recovery
+                    "failures": failures,
+                },
+            )
+
+        # Natural 1 - two failures
+        if roll == 1:
+            return SpecialMoment(
+                moment_type=SpecialMomentType.DEATH_SAVE_NAT_1,
+                enhanced_narration=random.choice(DEATH_SAVE_NAT_1_TEMPLATES),
+                voice_type=VoiceType.DM,
+                ui_effects=["darkness_pulse"],
+                pause_before_ms=500,
+                sound_effect="death_approaching",
+                context={
+                    "roll": roll,
+                    "successes": successes,
+                    "failures": failures + 2,
+                },
+            )
+
+        # Success (10+)
+        if roll >= 10:
+            return SpecialMoment(
+                moment_type=SpecialMomentType.DEATH_SAVE_SUCCESS,
+                enhanced_narration=random.choice(DEATH_SAVE_SUCCESS_TEMPLATES),
+                voice_type=VoiceType.DM,
+                ui_effects=[],
+                pause_before_ms=300,
+                context={
+                    "roll": roll,
+                    "successes": successes + 1,
+                    "failures": failures,
+                },
+            )
+
+        # Failure (<10)
+        return SpecialMoment(
+            moment_type=SpecialMomentType.DEATH_SAVE_FAILURE,
+            enhanced_narration=random.choice(DEATH_SAVE_FAILURE_TEMPLATES),
+            voice_type=VoiceType.DM,
+            ui_effects=["darkness_pulse"],
+            pause_before_ms=300,
+            context={
+                "roll": roll,
+                "successes": successes,
+                "failures": failures + 1,
+            },
+        )
+
+    def handle_killing_blow(
+        self,
+        weapon: str = "weapon",
+        enemy: str = "enemy",
+    ) -> SpecialMoment:
+        """
+        Create special moment for killing blow.
+
+        Args:
+            weapon: Weapon used.
+            enemy: Enemy defeated.
+
+        Returns:
+            SpecialMoment with enhanced narration.
+        """
+        template = random.choice(KILLING_BLOW_TEMPLATES)
+        narration = template.format(weapon=weapon, enemy=enemy)
+
+        return SpecialMoment(
+            moment_type=SpecialMomentType.KILLING_BLOW,
+            enhanced_narration=narration,
+            voice_type=VoiceType.DM,
+            ui_effects=["screen_shake"],
+            pause_before_ms=400,
+            sound_effect="killing_blow",
+            context={
+                "weapon": weapon,
+                "enemy": enemy,
+            },
+        )
+
+    def handle_player_death(
+        self,
+        character_name: str,
+    ) -> SpecialMoment:
+        """
+        Create special moment for player death.
+
+        Args:
+            character_name: Name of the fallen character.
+
+        Returns:
+            SpecialMoment with solemn narration.
+        """
+        narration = (
+            f"Silence falls as {character_name}'s spirit departs. "
+            "A hero has fallen. Their sacrifice will not be forgotten."
+        )
+
+        return SpecialMoment(
+            moment_type=SpecialMomentType.PLAYER_DEATH,
+            enhanced_narration=narration,
+            voice_type=VoiceType.DM,
+            ui_effects=["darkness_pulse"],
+            pause_before_ms=1000,
+            sound_effect="death",
+            context={"character_name": character_name},
+        )
+
+    def handle_combat_start(self) -> SpecialMoment:
+        """Create special moment for combat beginning."""
+        return SpecialMoment(
+            moment_type=SpecialMomentType.COMBAT_START,
+            enhanced_narration=random.choice(COMBAT_START_TEMPLATES),
+            voice_type=VoiceType.DM,
+            ui_effects=["screen_shake"],
+            pause_before_ms=300,
+            sound_effect="combat_start",
+            context={},
+        )
+
+    def handle_combat_victory(self) -> SpecialMoment:
+        """Create special moment for combat victory."""
+        return SpecialMoment(
+            moment_type=SpecialMomentType.COMBAT_VICTORY,
+            enhanced_narration=random.choice(COMBAT_VICTORY_TEMPLATES),
+            voice_type=VoiceType.DM,
+            ui_effects=["victory_sparkle"],
+            pause_before_ms=500,
+            sound_effect="victory",
+            context={},
+        )
+
+    def handle_level_up(
+        self,
+        character_name: str,
+        new_level: int,
+    ) -> SpecialMoment:
+        """
+        Create special moment for level up.
+
+        Args:
+            character_name: Name of the character.
+            new_level: The new level achieved.
+
+        Returns:
+            SpecialMoment with celebratory narration.
+        """
+        template = random.choice(LEVEL_UP_TEMPLATES)
+
+        return SpecialMoment(
+            moment_type=SpecialMomentType.LEVEL_UP,
+            enhanced_narration=f"{character_name} reaches level {new_level}! {template}",
+            voice_type=VoiceType.DM,
+            ui_effects=["level_up_glow"],
+            pause_before_ms=500,
+            sound_effect="level_up",
+            context={
+                "character_name": character_name,
+                "new_level": new_level,
+            },
+        )
+
+    def detect_from_roll(
+        self,
+        roll_result: DiceRollResult,
+        context: dict[str, object] | None = None,
+    ) -> SpecialMoment | None:
+        """
+        Detect special moment from a dice roll result.
+
+        Args:
+            roll_result: The dice roll result.
+            context: Additional context (weapon, target, etc.).
+
+        Returns:
+            SpecialMoment if detected, None otherwise.
+        """
+        context = context or {}
+
+        # Check for critical hit
+        if roll_result.is_critical:
+            return self.handle_critical_hit(
+                weapon=str(context.get("weapon", "weapon")),
+                target=str(context.get("target", "enemy")),
+            )
+
+        # Check for critical miss
+        if roll_result.is_fumble:
+            return self.handle_critical_miss(
+                weapon=str(context.get("weapon", "weapon")),
+            )
+
+        return None
+
+    def get_ui_effect_config(self, effect_name: str) -> dict[str, object]:
+        """
+        Get configuration for a UI effect.
+
+        Args:
+            effect_name: Name of the effect.
+
+        Returns:
+            Effect configuration dictionary.
+        """
+        return UI_EFFECTS.get(effect_name, {})

src/agents/voice_narrator.py

@@ -0,0 +1,449 @@
+"""
+DungeonMaster AI - Voice Narrator Agent
+
+Coordinates multi-voice narration using ElevenLabs.
+NOT an LLM agent - uses existing voice infrastructure.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import io
+import logging
+import time
+from typing import TYPE_CHECKING
+
+from src.voice.elevenlabs_client import VoiceClient
+from src.voice.models import (
+    NarrationResult,
+    ProcessedNarration,
+    TextSegment,
+    VoiceType,
+)
+from src.voice.text_processor import NarrationProcessor
+from src.voice.voice_profiles import get_voice_profile
+
+from .exceptions import VoiceNarratorError
+from .models import DMResponse, GameContext, VoiceSegment
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Phrase Cache
+# =============================================================================
+
+
+class PhraseCache:
+    """
+    Cache for common phrases to enable instant playback.
+
+    Caches audio for frequently used phrases like "Roll for initiative!"
+    """
+
+    # Common phrases to pre-cache
+    COMMON_PHRASES: list[tuple[str, VoiceType]] = [
+        ("Roll for initiative!", VoiceType.DM),
+        ("Roll a d20.", VoiceType.DM),
+        ("Make a saving throw.", VoiceType.DM),
+        ("Combat has begun!", VoiceType.DM),
+        ("Your turn.", VoiceType.DM),
+        ("What do you do?", VoiceType.DM),
+        ("Make an attack roll.", VoiceType.DM),
+        ("Roll for damage.", VoiceType.DM),
+        ("Critical hit!", VoiceType.DM),
+        ("The enemy is defeated!", VoiceType.DM),
+    ]
+
+    def __init__(self, max_size: int = 50) -> None:
+        """
+        Initialize phrase cache.
+
+        Args:
+            max_size: Maximum number of phrases to cache.
+        """
+        self._cache: dict[str, bytes] = {}
+        self._max_size = max_size
+
+    def _make_key(self, text: str, voice_type: VoiceType) -> str:
+        """Create cache key from text and voice type."""
+        content = f"{voice_type.value}:{text}"
+        return hashlib.md5(content.encode()).hexdigest()
+
+    def get(self, text: str, voice_type: VoiceType) -> bytes | None:
+        """Get cached audio for phrase."""
+        key = self._make_key(text, voice_type)
+        return self._cache.get(key)
+
+    def set(self, text: str, voice_type: VoiceType, audio: bytes) -> None:
+        """Cache audio for phrase."""
+        if len(self._cache) >= self._max_size:
+            # Remove oldest entry
+            oldest = next(iter(self._cache))
+            del self._cache[oldest]
+
+        key = self._make_key(text, voice_type)
+        self._cache[key] = audio
+
+    def clear(self) -> None:
+        """Clear the cache."""
+        self._cache.clear()
+
+    @property
+    def size(self) -> int:
+        """Get number of cached phrases."""
+        return len(self._cache)
+
+
+# =============================================================================
+# Audio Utilities
+# =============================================================================
+
+
+def generate_silence(duration_ms: int, sample_rate: int = 22050) -> bytes:
+    """
+    Generate silence audio bytes.
+
+    Args:
+        duration_ms: Duration of silence in milliseconds.
+        sample_rate: Audio sample rate.
+
+    Returns:
+        Silence audio as bytes (raw PCM).
+    """
+    # For MP3 output, we'll use actual silence
+    # This is a minimal silent MP3 frame
+    # In production, you'd use proper audio concatenation
+    return b""  # Empty bytes - pauses handled differently
+
+
+async def concatenate_audio_segments(
+    segments: list[tuple[bytes, int]],
+) -> bytes:
+    """
+    Concatenate audio segments with pauses.
+
+    Args:
+        segments: List of (audio_bytes, pause_after_ms) tuples.
+
+    Returns:
+        Combined audio bytes.
+
+    Note:
+        This is a simplified implementation. In production,
+        you'd use a proper audio library like pydub.
+    """
+    # For now, just concatenate the audio bytes
+    # Pauses would require proper audio manipulation
+    combined = io.BytesIO()
+    for audio, _pause in segments:
+        combined.write(audio)
+    return combined.getvalue()
+
+
+# =============================================================================
+# VoiceNarratorAgent
+# =============================================================================
+
+
+class VoiceNarratorAgent:
+    """
+    Multi-voice narration coordinator.
+
+    NOT an LLM agent - uses existing voice infrastructure:
+    - VoiceClient for ElevenLabs synthesis
+    - NarrationProcessor for text preprocessing
+    - Voice profiles for character voices
+
+    Features:
+    - Multi-voice dialogue (DM, NPC, monster voices)
+    - Phrase caching for common utterances
+    - Graceful degradation when voice unavailable
+    """
+
+    def __init__(
+        self,
+        voice_client: VoiceClient,
+        text_processor: NarrationProcessor | None = None,
+    ) -> None:
+        """
+        Initialize the Voice Narrator.
+
+        Args:
+            voice_client: ElevenLabs voice client.
+            text_processor: Text processor for TTS optimization.
+        """
+        self._voice_client = voice_client
+        self._text_processor = text_processor or NarrationProcessor()
+        self._phrase_cache = PhraseCache()
+
+        logger.info("VoiceNarratorAgent initialized")
+
+    async def narrate(
+        self,
+        dm_response: DMResponse,
+        game_context: GameContext | None = None,
+    ) -> NarrationResult:
+        """
+        Generate voice narration for a DM response.
+
+        Args:
+            dm_response: The DM's response with voice segments.
+            game_context: Optional game context for voice selection.
+
+        Returns:
+            NarrationResult with synthesized audio.
+        """
+        start_time = time.time()
+
+        try:
+            # Get voice segments from DM response
+            segments = dm_response.voice_segments
+
+            # If no segments, create one from narration text
+            if not segments:
+                segments = [
+                    VoiceSegment(
+                        text=dm_response.narration,
+                        voice_type=VoiceType.DM,
+                    )
+                ]
+
+            # Process each segment
+            audio_segments: list[tuple[bytes, int]] = []
+            total_text = ""
+
+            for segment in segments:
+                # Check phrase cache first
+                cached_audio = self._phrase_cache.get(
+                    segment.text, segment.voice_type
+                )
+
+                if cached_audio:
+                    audio_segments.append((cached_audio, segment.pause_after_ms))
+                    total_text += segment.text + " "
+                    continue
+
+                # Process text for TTS
+                processed_text = self._text_processor.process_for_tts(segment.text)
+
+                # Synthesize audio
+                try:
+                    audio_bytes = await self._voice_client.synthesize(
+                        text=processed_text,
+                        voice_type=segment.voice_type,
+                        stream=False,
+                    )
+
+                    if audio_bytes and isinstance(audio_bytes, bytes):
+                        audio_segments.append(
+                            (audio_bytes, segment.pause_after_ms)
+                        )
+
+                        # Cache if it's a short phrase
+                        if len(segment.text) < 100:
+                            self._phrase_cache.set(
+                                segment.text,
+                                segment.voice_type,
+                                audio_bytes,
+                            )
+
+                except Exception as e:
+                    logger.warning(f"Failed to synthesize segment: {e}")
+                    # Continue with other segments
+
+                total_text += segment.text + " "
+
+            # Combine audio segments
+            if audio_segments:
+                combined_audio = await concatenate_audio_segments(audio_segments)
+            else:
+                combined_audio = None
+
+            # Determine primary voice used
+            primary_voice = VoiceType.DM
+            if segments:
+                # Use the most common voice type
+                voice_counts: dict[VoiceType, int] = {}
+                for seg in segments:
+                    voice_counts[seg.voice_type] = voice_counts.get(seg.voice_type, 0) + 1
+                primary_voice = max(voice_counts, key=voice_counts.get)
+
+            duration_ms = int((time.time() - start_time) * 1000)
+
+            return NarrationResult(
+                success=combined_audio is not None,
+                audio=combined_audio,
+                format="mp3",
+                voice_used=primary_voice.value,
+                voice_type=primary_voice,
+                text_narrated=dm_response.narration,
+                text_processed=total_text.strip(),
+                duration_ms=duration_ms,
+                is_streaming=False,
+                from_cache=False,
+            )
+
+        except Exception as e:
+            logger.error(f"Voice narration failed: {e}")
+            raise VoiceNarratorError(str(e)) from e
+
+    async def narrate_text(
+        self,
+        text: str,
+        voice_type: VoiceType = VoiceType.DM,
+    ) -> NarrationResult:
+        """
+        Narrate simple text with a single voice.
+
+        Args:
+            text: Text to narrate.
+            voice_type: Voice to use.
+
+        Returns:
+            NarrationResult with audio.
+        """
+        # Create minimal DM response
+        dm_response = DMResponse(
+            narration=text,
+            voice_segments=[
+                VoiceSegment(text=text, voice_type=voice_type)
+            ],
+        )
+        return await self.narrate(dm_response)
+
+    async def narrate_dialogue(
+        self,
+        segments: list[VoiceSegment],
+    ) -> NarrationResult:
+        """
+        Narrate multi-voice dialogue sequence.
+
+        Args:
+            segments: List of voice segments.
+
+        Returns:
+            NarrationResult with combined audio.
+        """
+        # Build narration text
+        full_text = " ".join(s.text for s in segments)
+
+        dm_response = DMResponse(
+            narration=full_text,
+            voice_segments=segments,
+        )
+        return await self.narrate(dm_response)
+
+    async def pre_cache_phrases(self) -> int:
+        """
+        Pre-cache common phrases for instant playback.
+
+        Returns:
+            Number of phrases cached.
+        """
+        cached_count = 0
+
+        for phrase, voice_type in PhraseCache.COMMON_PHRASES:
+            try:
+                # Check if already cached
+                if self._phrase_cache.get(phrase, voice_type):
+                    cached_count += 1
+                    continue
+
+                # Synthesize and cache
+                processed = self._text_processor.process_for_tts(phrase)
+                audio_bytes = await self._voice_client.synthesize(
+                    text=processed,
+                    voice_type=voice_type,
+                    stream=False,
+                )
+
+                if audio_bytes and isinstance(audio_bytes, bytes):
+                    self._phrase_cache.set(phrase, voice_type, audio_bytes)
+                    cached_count += 1
+
+            except Exception as e:
+                logger.warning(f"Failed to pre-cache phrase '{phrase}': {e}")
+
+        logger.info(f"Pre-cached {cached_count} common phrases")
+        return cached_count
+
+    def get_voice_profile_info(self, voice_type: VoiceType) -> dict[str, str]:
+        """
+        Get information about a voice profile.
+
+        Args:
+            voice_type: Voice type to get info for.
+
+        Returns:
+            Dictionary with profile information.
+        """
+        profile = get_voice_profile(voice_type)
+        return {
+            "name": profile.name,
+            "description": profile.description,
+            "voice_id": profile.voice_id,
+            "type": voice_type.value,
+        }
+
+    @property
+    def is_available(self) -> bool:
+        """Check if voice service is available."""
+        status = self._voice_client.get_status()
+        return status.is_available
+
+    @property
+    def cache_size(self) -> int:
+        """Get phrase cache size."""
+        return self._phrase_cache.size
+
+    def clear_cache(self) -> None:
+        """Clear phrase cache."""
+        self._phrase_cache.clear()
+        logger.info("Voice phrase cache cleared")
+
+
+# =============================================================================
+# Factory Function
+# =============================================================================
+
+
+async def create_voice_narrator(
+    voice_client: VoiceClient | None = None,
+    pre_cache: bool = True,
+) -> VoiceNarratorAgent | None:
+    """
+    Create and initialize a VoiceNarratorAgent.
+
+    Args:
+        voice_client: Optional voice client. Creates new one if not provided.
+        pre_cache: Whether to pre-cache common phrases.
+
+    Returns:
+        VoiceNarratorAgent or None if voice is unavailable.
+    """
+    if voice_client is None:
+        voice_client = VoiceClient()
+        try:
+            await voice_client.initialize()
+        except Exception as e:
+            logger.warning(f"Voice client initialization failed: {e}")
+            return None
+
+    if not voice_client.get_status().is_available:
+        logger.warning("Voice service not available")
+        return None
+
+    narrator = VoiceNarratorAgent(
+        voice_client=voice_client,
+        text_processor=NarrationProcessor(),
+    )
+
+    if pre_cache:
+        await narrator.pre_cache_phrases()
+
+    return narrator

src/config/__init__.py

@@ -0,0 +1,25 @@
+"""
+DungeonMaster AI - Configuration Package
+
+Settings and configuration management.
+"""
+
+from src.config.settings import (
+    AppSettings,
+    GameSettings,
+    LLMSettings,
+    MCPSettings,
+    VoiceSettings,
+    get_settings,
+    settings,
+)
+
+__all__ = [
+    "AppSettings",
+    "LLMSettings",
+    "VoiceSettings",
+    "MCPSettings",
+    "GameSettings",
+    "get_settings",
+    "settings",
+]

src/config/prompts/dm_combat.txt

@@ -0,0 +1,46 @@
+## Combat Mode - Additional Guidelines
+
+You are now running a combat encounter. Shift your narration style to match the intensity and tactical nature of battle.
+
+### Combat Flow Management
+1. **Always track initiative order** - use the combat tools to manage turn order
+2. **Announce each turn clearly** - "It's your turn. The goblin archer is 30 feet away, the wounded one is in melee range."
+3. **Describe the battlefield** - remind players of positioning, cover, and tactical options
+4. **Monster tactics** - play enemies intelligently based on their intelligence and nature
+
+### Attack Resolution
+When the player attacks:
+1. Ask what they're attacking and how (weapon, spell, ability)
+2. Call for an attack roll using the roll tool with appropriate modifiers
+3. Compare to target AC (use get_monster if needed)
+4. If hit, roll damage with the roll tool
+5. Apply damage using modify_hp
+6. Narrate the result cinematically
+
+### Damage Descriptions by Severity
+- **Minor hit (1-5 damage)**: "Your blade grazes the creature's arm, drawing a thin line of blood"
+- **Solid hit (6-15 damage)**: "Your strike lands true, biting deep into flesh"
+- **Devastating hit (16+ damage)**: "Your weapon crashes through the creature's defenses with brutal force"
+- **Critical hit**: "Time seems to slow as your blow finds the perfect opening - a strike that will be sung about in taverns!"
+
+### Death and Unconsciousness
+- When a player reaches 0 HP, immediately describe them falling unconscious
+- Begin death saving throws on their turn
+- Describe the tension as allies scramble to help
+- When enemies drop to 0 HP, describe their defeat dramatically
+
+### Tactical Information to Provide
+At the start of each player turn, briefly note:
+- Current HP status (without exact numbers unless asked)
+- Obvious threats and opportunities
+- Environmental factors that might help
+- Status of ongoing effects
+
+### Ending Combat
+When combat ends:
+1. Use end_combat to properly close the encounter
+2. Describe the aftermath - bodies, environment damage, emotional state
+3. Allow for looting and recovery
+4. Transition smoothly back to exploration or roleplay
+
+Remember: Combat should feel exciting and dangerous, but also fair. Use your tools to ensure mechanical accuracy while your narration brings the battle to life!

src/config/prompts/dm_exploration.txt

@@ -0,0 +1,56 @@
+## Exploration Mode - Additional Guidelines
+
+You are guiding the player through exploration and discovery. Focus on environmental storytelling and rewarding curiosity.
+
+### Scene Setting
+When the player enters a new area:
+1. Describe the immediate sensory experience (sight, sound, smell)
+2. Note obvious exits and points of interest
+3. Hint at things that might reward investigation
+4. Establish the mood and atmosphere
+
+### Environmental Description Layers
+- **Immediate (always describe)**: What's obvious at first glance
+- **Observable (on looking closer)**: Details noticed with attention
+- **Hidden (requires checks)**: Secrets, traps, hidden passages
+
+### Skill Check Triggers
+Call for checks when there's genuine uncertainty:
+- **Perception**: Noticing hidden details, detecting ambushes
+- **Investigation**: Deducing information, finding secret mechanisms
+- **Survival**: Tracking, foraging, navigating wilderness
+- **History/Arcana/Religion/Nature**: Recalling relevant knowledge
+- **Athletics/Acrobatics**: Physical challenges
+
+### Check Difficulty Guidelines
+- **DC 10 (Easy)**: Most adventurers succeed
+- **DC 15 (Medium)**: Requires skill or luck
+- **DC 20 (Hard)**: Challenging even for experts
+- **DC 25+ (Very Hard)**: Near-legendary difficulty
+
+### Discovery and Rewards
+When players search or investigate:
+1. Use the roll tool for the appropriate check
+2. Scale information revealed to the check result
+3. Use the generators to create appropriate loot if needed
+4. Make discoveries feel earned and exciting
+
+### Trap Handling
+If traps are present:
+1. Provide subtle hints before triggering (strange floor tiles, odd drafts)
+2. Allow Perception/Investigation to detect
+3. Allow Thieves' Tools or creative solutions to disarm
+4. If triggered, describe and roll damage fairly
+5. Let creative solutions bypass or minimize harm
+
+### Time and Resources
+- Track time passing when relevant (torches, spells, exhaustion)
+- Note when resources are consumed
+- Create tension through resource management when appropriate
+
+### Transitioning to Other Modes
+- If combat initiates: "Roll for initiative!" and switch to combat mode
+- If NPC encountered: Switch to social mode for the conversation
+- If puzzle found: Describe it clearly and let the player work through it
+
+Remember: Exploration should feel like discovering a living world. Reward curiosity, create atmosphere, and let the environment tell its own story!

src/config/prompts/dm_social.txt

@@ -0,0 +1,69 @@
+## Social Encounter Mode - Additional Guidelines
+
+You are facilitating roleplay and social interaction. Bring NPCs to life with distinct personalities and motivations.
+
+### NPC Portrayal
+When voicing an NPC:
+1. **Distinct voice**: Give each NPC a unique way of speaking (formal, casual, accent hints)
+2. **Clear motivation**: Know what the NPC wants and fears
+3. **Reactive personality**: Respond to player approach (hostile, friendly, suspicious)
+4. **Consistent behavior**: Remember how they've been treated
+
+### NPC Personality Markers
+Establish quickly:
+- Speech pattern (verbose, terse, nervous, confident)
+- Emotional state (bored, afraid, excited, suspicious)
+- Relationship to player (helpful, neutral, hostile)
+- Key information they possess
+
+### Social Skill Checks
+Call for rolls when:
+- **Persuasion**: Convincing through logic or charm
+- **Deception**: Lying or misleading
+- **Intimidation**: Threatening or coercing
+- **Insight**: Reading true intentions
+- **Performance**: Entertaining or distracting
+
+### When NOT to Roll
+- If the player makes a genuinely good argument, consider auto-success
+- If the request is reasonable and NPC is friendly, just say yes
+- If the request is impossible (peasant gives up their only food), no roll helps
+- Let good roleplay grant advantage, poor roleplay grant disadvantage
+
+### Dialogue Flow
+1. Let the player speak first
+2. React as the NPC would genuinely react
+3. Provide hooks for continued conversation
+4. Include non-verbal cues (the guard's eyes narrow, the merchant's face lights up)
+
+### Information Sharing
+NPCs can provide:
+- **Quest hooks**: Rumors, pleas for help, job offers
+- **World building**: Local history, customs, dangers
+- **Practical info**: Directions, prices, recommendations
+- **Plot advancement**: Clues, secrets, revelations
+
+### Reading NPCs
+When players try to discern motives:
+1. Call for Insight check
+2. Scale information to the roll:
+   - Low roll: Surface impression only
+   - Medium roll: General sense of honesty/intent
+   - High roll: Specific hidden emotions or tells
+   - Natural 20: Deep understanding of motivation
+
+### Conflict Resolution
+Not all social encounters end peacefully:
+- If negotiations break down, give warning signs
+- Allow players to course-correct before violence
+- If combat begins, transition smoothly
+- Remember: Some NPCs can't be talked down
+
+### Building Relationships
+Track NPC disposition:
+- Note if players helped or harmed them
+- Have NPCs remember past interactions
+- Build recurring characters when appropriate
+- Create consequences for broken promises
+
+Remember: NPCs are people, not quest dispensers. Give them lives, loves, and fears. The most memorable adventures feature characters the player genuinely cares about - or loves to hate!

src/config/prompts/dm_system.txt

@@ -0,0 +1,88 @@
+You are an experienced, engaging Dungeon Master for Dungeons & Dragons 5th Edition. Your role is to create an immersive, memorable tabletop roleplaying experience for the player.
+
+## Your Personality
+- **Dramatic yet fair**: You weave compelling narratives while ensuring balanced gameplay
+- **Descriptive but concise**: You paint vivid scenes in 2-4 sentences, never overwhelming with walls of text
+- **Responsive and adaptive**: You react creatively to player choices, never railroading them
+- **Knowledgeable**: You understand D&D 5e rules deeply but prioritize fun over strict adherence
+
+## Core Responsibilities
+1. **Narrate the story**: Describe environments, events, and outcomes with evocative detail
+2. **Control NPCs and monsters**: Give each character a distinct voice, motivation, and personality
+3. **Present challenges**: Create obstacles that test the player's creativity and character abilities
+4. **Adjudicate actions**: Determine outcomes fairly, calling for appropriate checks when uncertainty exists
+5. **Maintain pacing**: Keep the game moving, cutting to interesting moments
+
+## Tool Usage Guidelines (CRITICAL)
+You have access to powerful tools via the TTRPG Toolkit. USE THEM CORRECTLY:
+
+- **ALWAYS use the roll tool** for any uncertain outcome. Never arbitrarily decide success/failure.
+- **Use get_character** to check player stats before making decisions involving their abilities
+- **Use modify_hp** when ANY damage is dealt or healing occurs - track HP precisely
+- **Use search_rules** when uncertain about any game mechanic - never guess at rules
+- **Use get_monster** to retrieve accurate monster stats for any encounter
+- **Use combat tools** (start_combat, next_turn, etc.) to properly manage combat flow
+- **Use generators** when you need spontaneous NPCs, encounters, or loot
+
+## Response Guidelines
+- Keep narration to 2-4 sentences typically - quality over quantity
+- Describe results narratively, not mechanically
+  - GOOD: "Your blade catches the goblin across the chest, and it crumples with a pained shriek"
+  - BAD: "You deal 8 slashing damage to the goblin"
+- End responses at natural decision points - let the player choose what happens next
+- When multiple paths exist, briefly hint at options without dictating choice
+- Be fair but challenging - players should feel their choices matter
+
+## Combat Narration
+When in combat:
+- Describe attacks cinematically based on success/failure margins
+- A natural 20 deserves epic description
+- A natural 1 should be embarrassing but not campaign-ending
+- Track initiative and remind players whose turn it is
+- Describe monster tactics and reactions to make combat feel dynamic
+
+## Voice Narration System (CRITICAL)
+Your narration will be converted to speech. Use VOICE CUES to assign different voices to dialogue and narration.
+
+### Available Voice Types
+Use these tags to mark text for different voices:
+- `[VOICE:dm]` - Your narration voice (default, authoritative, dramatic)
+- `[VOICE:gruff]` - Rough, tough characters (dwarves, soldiers, thugs)
+- `[VOICE:gentle]` - Kind, soft characters (healers, elves, children)
+- `[VOICE:mysterious]` - Enigmatic characters (mages, seers, strangers)
+- `[VOICE:monster]` - Creatures and beasts (goblins, dragons, demons)
+
+### Voice Cue Format
+Insert voice tags BEFORE the text they apply to. Each tag affects text until the next tag or end of response.
+
+### Voice Examples
+GOOD:
+[VOICE:dm]You enter the dimly lit tavern. A grizzled dwarf at the bar turns to face you.
+[VOICE:gruff]"What're ye lookin' at, stranger? This ain't no place for sightseers."
+[VOICE:dm]His hand moves subtly toward a hammer beneath the counter.
+
+GOOD (Combat):
+[VOICE:dm]The goblin shrieks as your sword connects!
+[VOICE:monster]"No! No hurt Griknak! We surrenders!"
+[VOICE:dm]The remaining goblins scatter into the shadows.
+
+GOOD (Mystery):
+[VOICE:dm]The hooded figure emerges from the mist.
+[VOICE:mysterious]"You seek answers, but are you prepared for the truth?"
+[VOICE:dm]Their eyes glow with an otherworldly light.
+
+### Voice Guidelines
+- ALWAYS use [VOICE:dm] for narration and your DM voice
+- SWITCH voices for NPC dialogue to create distinct characters
+- Use [VOICE:monster] for creatures, even intelligent ones, to differentiate from humanoids
+- Keep voice switches to 2-3 per response to maintain clarity
+- Critical moments (death saves, killing blows) should use [VOICE:dm] for maximum impact
+
+## The Golden Rule
+Your job is to facilitate fun and adventure. When in doubt:
+1. Ask yourself "What would make this moment most exciting?"
+2. Use your tools to ensure fairness
+3. Say "yes, and..." or "yes, but..." rather than flat "no"
+4. Remember: The player is the hero of this story
+
+Now, embrace your role as Dungeon Master. The adventure awaits!

src/config/prompts/narrator_system.txt

@@ -0,0 +1,60 @@
+You are the voice narrator for DungeonMaster AI. Your role is to process Dungeon Master text for optimal voice synthesis.
+
+## Text Processing Guidelines
+
+### Pronunciation
+- Expand abbreviations for natural speech:
+  - HP -> "hit points"
+  - AC -> "armor class"
+  - DC -> "difficulty class"
+  - STR, DEX, CON, INT, WIS, CHA -> full ability names
+  - d20, d6, etc. -> "dee twenty", "dee six"
+  - +5 -> "plus five"
+  - -2 -> "minus two"
+  - 1st, 2nd, 3rd -> "first", "second", "third"
+
+### Dramatic Pacing
+- Add natural pauses after dramatic statements
+- Slow down for important revelations
+- Speed up during action sequences
+- Let tension build with appropriate beats
+
+### Dialogue Handling
+When text contains dialogue:
+- DM narration uses the primary narrator voice
+- NPC dialogue should be marked for character voice switching
+- Monster speech may need the monster voice profile
+- Internal thoughts can be delivered with different intonation
+
+### Emotional Tone Markers
+Identify the emotional context:
+- **Tension**: Slow, deliberate delivery
+- **Excitement**: Faster, more energetic
+- **Mystery**: Lower, more measured
+- **Danger**: Urgent, warning tone
+- **Victory**: Triumphant, celebratory
+- **Sorrow**: Gentle, somber
+
+### Voice Assignment Rules
+Select appropriate voice based on:
+1. **DM Narration**: Deep, authoritative (default DM voice)
+2. **Male NPC - Gruff**: Guards, dwarves, warriors
+3. **Female NPC - Gentle**: Elves, healers, sages
+4. **Mysterious Figure**: Wizards, fey, ethereal beings
+5. **Monster**: Creatures, villains, supernatural entities
+
+### Text Cleanup
+Before synthesis:
+- Remove markdown formatting
+- Convert special characters appropriately
+- Ensure proper sentence structure
+- Remove meta-commentary not meant to be spoken
+
+### Output Format
+For each text segment, provide:
+1. Cleaned text ready for TTS
+2. Recommended voice profile
+3. Emotional tone suggestion
+4. Any special pacing notes
+
+Your goal is to make the audio narration as engaging and immersive as the written adventure!

src/config/prompts/rules_system.txt

@@ -0,0 +1,64 @@
+You are a D&D 5th Edition rules expert and arbiter. Your role is to provide accurate, clear rules information when asked.
+
+## Core Principles
+1. **Accuracy first**: Always use your tools to verify rules - never guess
+2. **Cite sources**: Reference specific rules when providing information
+3. **Clarity**: Explain rules in plain language, then quote official text if needed
+4. **Fairness**: When rules are ambiguous, suggest fair interpretations
+
+## Your Capabilities
+You have access to rules lookup tools:
+- **search_rules**: Find rules by topic or keyword
+- **get_monster**: Retrieve complete monster statistics
+- **get_spell**: Get detailed spell information
+- **get_class_info**: Class features and abilities
+- **get_race_info**: Racial traits and features
+- **get_item**: Magic items and equipment
+- **get_condition**: Status condition effects
+
+## Response Format
+When answering rules questions:
+
+1. **Direct answer first**: Give the ruling in plain terms
+2. **Official citation**: Quote relevant rules text
+3. **Edge cases**: Note common misunderstandings or exceptions
+4. **Practical application**: Give an example if helpful
+
+## Common Rules Areas
+
+### Combat
+- Attack rolls and armor class
+- Damage types and resistances
+- Actions, bonus actions, reactions
+- Movement and positioning
+- Cover and visibility
+- Conditions and status effects
+
+### Spellcasting
+- Spell slots and casting
+- Concentration
+- Components (V, S, M)
+- Saving throws and attack rolls
+- Spell interactions
+
+### Character Abilities
+- Ability checks and skills
+- Saving throws
+- Class features
+- Racial abilities
+- Feats
+
+### Adjudication Principles
+When rules are unclear:
+1. Check for specific over general (specific rules override general)
+2. Look for designer intent (what makes sense?)
+3. Consider game balance
+4. Default to what's most fun while fair
+
+## Important Notes
+- If asked to rule on homebrew, clarify that your knowledge is for official 5e content
+- When multiple valid interpretations exist, present them fairly
+- Encourage "rule of cool" for dramatic moments, but maintain consistency
+- Remember: The DM has final say, but rules provide the foundation
+
+Your goal is to help ensure the game runs smoothly by providing quick, accurate rules information when needed.

src/config/settings.py

@@ -0,0 +1,289 @@
+"""
+DungeonMaster AI - Application Settings
+
+Centralized configuration management using pydantic-settings.
+Loads settings from environment variables and .env file.
+"""
+
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class LLMSettings(BaseSettings):
+    """LLM API configuration."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="",
+        extra="ignore",
+    )
+
+    # Gemini (Primary)
+    gemini_api_key: str = Field(
+        default="",
+        description="Google Gemini API key for primary LLM",
+    )
+    gemini_model: str = Field(
+        default="gemini-1.5-pro",
+        description="Gemini model to use",
+    )
+
+    # OpenAI (Fallback)
+    openai_api_key: str = Field(
+        default="",
+        description="OpenAI API key for fallback LLM",
+    )
+    openai_model: str = Field(
+        default="gpt-4o",
+        description="OpenAI model to use as fallback",
+    )
+
+    # LLM Parameters
+    temperature: float = Field(
+        default=0.75,
+        ge=0.0,
+        le=2.0,
+        description="Temperature for LLM generation (0.0-2.0)",
+    )
+    max_tokens: int = Field(
+        default=1024,
+        ge=100,
+        le=8192,
+        description="Maximum tokens for LLM response",
+    )
+
+    @property
+    def has_gemini(self) -> bool:
+        """Check if Gemini API key is configured."""
+        return bool(self.gemini_api_key and self.gemini_api_key != "your_gemini_api_key_here")
+
+    @property
+    def has_openai(self) -> bool:
+        """Check if OpenAI API key is configured."""
+        return bool(self.openai_api_key and self.openai_api_key != "your_openai_api_key_here")
+
+
+class VoiceSettings(BaseSettings):
+    """Voice synthesis configuration."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="",
+        extra="ignore",
+    )
+
+    elevenlabs_api_key: str = Field(
+        default="",
+        description="ElevenLabs API key for voice synthesis",
+    )
+    voice_enabled: bool = Field(
+        default=True,
+        description="Whether voice narration is enabled",
+    )
+    voice_auto_play: bool = Field(
+        default=True,
+        description="Auto-play voice narration",
+    )
+    voice_speed: float = Field(
+        default=1.0,
+        ge=0.5,
+        le=2.0,
+        description="Voice playback speed (0.5-2.0)",
+    )
+    voice_model: str = Field(
+        default="eleven_turbo_v2",
+        description="ElevenLabs model to use",
+    )
+
+    # Voice Profile IDs (ElevenLabs voice IDs)
+    dm_voice_id: str = Field(
+        default="pNInz6obpgDQGcFmaJgB",  # Adam - deep, authoritative
+        description="Voice ID for DM narration",
+    )
+    npc_male_gruff_voice_id: str = Field(
+        default="VR6AewLTigWG4xSOukaG",  # Arnold - gruff male
+        description="Voice ID for gruff male NPCs",
+    )
+    npc_female_gentle_voice_id: str = Field(
+        default="EXAVITQu4vr4xnSDxMaL",  # Bella - gentle female
+        description="Voice ID for gentle female NPCs",
+    )
+    npc_mysterious_voice_id: str = Field(
+        default="onwK4e9ZLuTAKqWW03F9",  # Daniel - mysterious
+        description="Voice ID for mysterious NPCs",
+    )
+    monster_voice_id: str = Field(
+        default="N2lVS1w4EtoT3dr4eOWO",  # Callum - menacing
+        description="Voice ID for monsters",
+    )
+
+    @property
+    def has_elevenlabs(self) -> bool:
+        """Check if ElevenLabs API key is configured."""
+        return bool(
+            self.elevenlabs_api_key and self.elevenlabs_api_key != "your_elevenlabs_api_key_here"
+        )
+
+
+class MCPSettings(BaseSettings):
+    """MCP Server configuration."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="",
+        extra="ignore",
+    )
+
+    ttrpg_toolkit_mcp_url: str = Field(
+        default="http://localhost:8000/mcp",
+        description="TTRPG Toolkit MCP server URL (streamable-http endpoint)",
+    )
+    mcp_connection_timeout: int = Field(
+        default=30,
+        ge=5,
+        le=120,
+        description="MCP connection timeout in seconds",
+    )
+    mcp_retry_attempts: int = Field(
+        default=3,
+        ge=1,
+        le=10,
+        description="Number of retry attempts for MCP connection",
+    )
+    mcp_retry_delay: float = Field(
+        default=1.0,
+        ge=0.5,
+        le=10.0,
+        description="Delay between retry attempts in seconds",
+    )
+
+
+class GameSettings(BaseSettings):
+    """Game-specific configuration."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="",
+        extra="ignore",
+    )
+
+    max_conversation_history: int = Field(
+        default=10,
+        ge=5,
+        le=50,
+        description="Maximum conversation turns to keep in context",
+    )
+    default_adventure: str = Field(
+        default="tavern_start",
+        description="Default adventure to load on new game",
+    )
+    auto_save_enabled: bool = Field(
+        default=True,
+        description="Enable auto-save functionality",
+    )
+    auto_save_interval: int = Field(
+        default=5,
+        ge=1,
+        le=30,
+        description="Auto-save interval in minutes",
+    )
+
+
+class AppSettings(BaseSettings):
+    """Main application settings."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        case_sensitive=False,
+    )
+
+    # Application Info
+    app_name: str = Field(
+        default="DungeonMaster AI",
+        description="Application name",
+    )
+    app_version: str = Field(
+        default="1.0.0",
+        description="Application version",
+    )
+
+    # Debug & Logging
+    debug_mode: bool = Field(
+        default=False,
+        description="Enable debug mode",
+    )
+    log_level: str = Field(
+        default="INFO",
+        description="Logging level",
+    )
+
+    # HuggingFace
+    huggingface_token: str = Field(
+        default="",
+        description="HuggingFace token for deployment",
+    )
+
+    # Paths
+    base_dir: Path = Field(
+        default_factory=lambda: Path(__file__).parent.parent.parent,
+        description="Base directory of the application",
+    )
+
+    # Sub-settings (loaded separately for better organization)
+    llm: LLMSettings = Field(default_factory=LLMSettings)
+    voice: VoiceSettings = Field(default_factory=VoiceSettings)
+    mcp: MCPSettings = Field(default_factory=MCPSettings)
+    game: GameSettings = Field(default_factory=GameSettings)
+
+    @field_validator("log_level")
+    @classmethod
+    def validate_log_level(cls, v: str) -> str:
+        """Validate log level."""
+        valid_levels = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
+        upper_v = v.upper()
+        if upper_v not in valid_levels:
+            raise ValueError(f"Invalid log level: {v}. Must be one of {valid_levels}")
+        return upper_v
+
+    @property
+    def prompts_dir(self) -> Path:
+        """Get prompts directory path."""
+        return self.base_dir / "src" / "config" / "prompts"
+
+    @property
+    def adventures_dir(self) -> Path:
+        """Get adventures directory path."""
+        return self.base_dir / "adventures"
+
+    @property
+    def assets_dir(self) -> Path:
+        """Get UI assets directory path."""
+        return self.base_dir / "ui" / "assets"
+
+    def get_prompt_path(self, prompt_name: str) -> Path:
+        """Get path to a specific prompt file."""
+        return self.prompts_dir / f"{prompt_name}.txt"
+
+    def get_adventure_path(self, adventure_name: str) -> Path:
+        """Get path to a specific adventure file."""
+        return self.adventures_dir / f"{adventure_name}.json"
+
+
+@lru_cache
+def get_settings() -> AppSettings:
+    """
+    Get cached application settings.
+
+    Uses lru_cache to ensure settings are only loaded once.
+    Call get_settings.cache_clear() to reload settings.
+    """
+    return AppSettings()
+
+
+# Convenience function for quick access
+settings = get_settings()

src/game/__init__.py

@@ -0,0 +1,86 @@
+"""
+DungeonMaster AI - Game Package
+
+Game state management, context building, event logging, and adventure loading.
+
+This package provides:
+- GameState: Basic game state dataclass (Phase 1 stub)
+- GameStateManager: High-level state manager with MCP integration
+- StoryContextBuilder: LLM context construction
+- EventLogger: Session event logging
+- AdventureLoader: Pre-made adventure loading
+
+Models:
+- SessionEvent: Event log entry
+- Combatant: Combat participant
+- CombatState: Active combat state
+- CharacterSnapshot: Cached character data
+- NPCInfo: NPC information
+- SceneInfo: Location/scene data
+- GameSaveData: Serializable save file
+- AdventureData: Adventure module data
+"""
+
+# Original Phase 1 exports (preserved for compatibility)
+from .game_state import GameState, GameStateProtocol
+
+# New Pydantic models
+from .models import (
+    # Enums
+    EventType,
+    CombatantStatus,
+    HPStatus,
+    # Event models
+    SessionEvent,
+    # Combat models
+    Combatant,
+    CombatState,
+    # Character models
+    CharacterSnapshot,
+    # NPC and Scene models
+    NPCInfo,
+    SceneInfo,
+    # Save/Load models
+    GameSaveData,
+    # Adventure models
+    AdventureMetadata,
+    EncounterData,
+    AdventureData,
+)
+
+# Manager classes
+from .game_state_manager import GameStateManager
+from .story_context import StoryContextBuilder
+from .event_logger import EventLogger
+from .adventure_loader import AdventureLoader
+
+__all__ = [
+    # Original (Phase 1)
+    "GameState",
+    "GameStateProtocol",
+    # Enums
+    "EventType",
+    "CombatantStatus",
+    "HPStatus",
+    # Event models
+    "SessionEvent",
+    # Combat models
+    "Combatant",
+    "CombatState",
+    # Character models
+    "CharacterSnapshot",
+    # NPC and Scene models
+    "NPCInfo",
+    "SceneInfo",
+    # Save/Load models
+    "GameSaveData",
+    # Adventure models
+    "AdventureMetadata",
+    "EncounterData",
+    "AdventureData",
+    # Manager classes
+    "GameStateManager",
+    "StoryContextBuilder",
+    "EventLogger",
+    "AdventureLoader",
+]

src/game/adventure_loader.py

@@ -0,0 +1,530 @@
+"""
+DungeonMaster AI - Adventure Loader
+
+Loads and manages adventure JSON files for pre-made scenarios.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .models import (
+    AdventureData,
+    EncounterData,
+    NPCInfo,
+    SceneInfo,
+)
+
+if TYPE_CHECKING:
+    from .game_state_manager import GameStateManager
+
+logger = logging.getLogger(__name__)
+
+# Default adventures directory relative to project root
+DEFAULT_ADVENTURES_DIR = Path(__file__).parent.parent.parent / "adventures"
+
+
+class AdventureLoader:
+    """
+    Loads and manages adventure JSON files.
+
+    Adventures are pre-made scenarios with scenes, NPCs, encounters,
+    and victory conditions. This class handles loading, parsing,
+    and initializing games from adventure files.
+    """
+
+    def __init__(
+        self,
+        adventures_dir: Path | str | None = None,
+    ) -> None:
+        """
+        Initialize the adventure loader.
+
+        Args:
+            adventures_dir: Directory containing adventure JSON files.
+                           Defaults to 'adventures/' in project root.
+        """
+        if adventures_dir is None:
+            self._adventures_dir = DEFAULT_ADVENTURES_DIR
+        else:
+            self._adventures_dir = Path(adventures_dir)
+
+        # Cache loaded adventures
+        self._cache: dict[str, AdventureData] = {}
+
+        logger.debug(f"AdventureLoader initialized with dir: {self._adventures_dir}")
+
+    @property
+    def adventures_dir(self) -> Path:
+        """Get the adventures directory path."""
+        return self._adventures_dir
+
+    # =========================================================================
+    # Adventure Discovery
+    # =========================================================================
+
+    def list_adventures(self) -> list[dict[str, str]]:
+        """
+        List all available adventures.
+
+        Returns:
+            List of adventure info dicts with keys:
+            - name: Adventure name
+            - file: Filename
+            - description: Adventure description
+            - difficulty: Difficulty level
+            - estimated_time: Estimated play time
+        """
+        adventures: list[dict[str, str]] = []
+
+        if not self._adventures_dir.exists():
+            logger.warning(f"Adventures directory not found: {self._adventures_dir}")
+            return adventures
+
+        for json_file in self._adventures_dir.glob("*.json"):
+            # Skip sample_characters directory
+            if json_file.is_dir():
+                continue
+
+            try:
+                with open(json_file, encoding="utf-8") as f:
+                    data = json.load(f)
+
+                metadata = data.get("metadata", {})
+                adventures.append(
+                    {
+                        "name": metadata.get("name", json_file.stem),
+                        "file": json_file.name,
+                        "description": metadata.get("description", ""),
+                        "difficulty": metadata.get("difficulty", "medium"),
+                        "estimated_time": metadata.get("estimated_time", "Unknown"),
+                        "recommended_level": str(
+                            metadata.get("recommended_level", 1)
+                        ),
+                    }
+                )
+            except (json.JSONDecodeError, OSError) as e:
+                logger.warning(f"Failed to load adventure {json_file}: {e}")
+                continue
+
+        return adventures
+
+    # =========================================================================
+    # Adventure Loading
+    # =========================================================================
+
+    def load(self, adventure_name: str) -> AdventureData | None:
+        """
+        Load an adventure by name.
+
+        Checks cache first, then loads from file.
+
+        Args:
+            adventure_name: Name of adventure or filename (with/without .json)
+
+        Returns:
+            AdventureData if found, None otherwise
+        """
+        # Check cache
+        if adventure_name in self._cache:
+            return self._cache[adventure_name]
+
+        # Find the file
+        json_file = self._find_adventure_file(adventure_name)
+        if json_file is None:
+            logger.warning(f"Adventure not found: {adventure_name}")
+            return None
+
+        # Load and parse
+        try:
+            with open(json_file, encoding="utf-8") as f:
+                data = json.load(f)
+
+            adventure = AdventureData.from_json(data)
+
+            # Cache by both name and filename
+            self._cache[adventure_name] = adventure
+            self._cache[adventure.metadata.name] = adventure
+            self._cache[json_file.stem] = adventure
+
+            logger.info(f"Loaded adventure: {adventure.metadata.name}")
+            return adventure
+
+        except (json.JSONDecodeError, OSError) as e:
+            logger.error(f"Failed to load adventure {json_file}: {e}")
+            return None
+        except Exception as e:
+            logger.error(f"Failed to parse adventure {json_file}: {e}")
+            return None
+
+    def _find_adventure_file(self, adventure_name: str) -> Path | None:
+        """
+        Find an adventure file by name.
+
+        Args:
+            adventure_name: Name or filename to search for
+
+        Returns:
+            Path to file if found, None otherwise
+        """
+        if not self._adventures_dir.exists():
+            return None
+
+        # Try exact filename
+        exact_path = self._adventures_dir / adventure_name
+        if exact_path.exists():
+            return exact_path
+
+        # Try with .json extension
+        json_path = self._adventures_dir / f"{adventure_name}.json"
+        if json_path.exists():
+            return json_path
+
+        # Try matching by metadata name
+        for json_file in self._adventures_dir.glob("*.json"):
+            try:
+                with open(json_file, encoding="utf-8") as f:
+                    data = json.load(f)
+                    metadata = data.get("metadata", {})
+                    if metadata.get("name", "").lower() == adventure_name.lower():
+                        return json_file
+            except (json.JSONDecodeError, OSError):
+                continue
+
+        return None
+
+    # =========================================================================
+    # Game Initialization
+    # =========================================================================
+
+    async def initialize_game(
+        self,
+        manager: GameStateManager,
+        adventure_name: str,
+    ) -> bool:
+        """
+        Initialize a game session with an adventure.
+
+        Args:
+            manager: GameStateManager to initialize
+            adventure_name: Name of adventure to load
+
+        Returns:
+            True if successful, False otherwise
+        """
+        adventure = self.load(adventure_name)
+        if adventure is None:
+            return False
+
+        try:
+            # Start new game with adventure name
+            await manager.new_game(adventure=adventure.metadata.name)
+
+            # Set starting location
+            starting_scene = adventure.starting_scene
+            scene_id = str(starting_scene.get("scene_id", ""))
+            scene_info = self.get_scene(adventure_name, scene_id)
+
+            if scene_info:
+                manager.set_location(scene_info.name, scene_info)
+            else:
+                # Fallback to basic location from starting scene
+                manager.set_location(
+                    str(starting_scene.get("scene_id", "Unknown")),
+                    None,
+                )
+
+            # Add all NPCs to manager
+            for npc_data in adventure.npcs:
+                if isinstance(npc_data, dict):
+                    npc = self._parse_npc(npc_data)
+                    if npc:
+                        manager.add_known_npc(npc)
+
+            # Set initial story flags
+            manager.set_story_flag("adventure_started", True)
+            manager.set_story_flag("adventure_name", adventure.metadata.name)
+
+            logger.info(
+                f"Initialized game with adventure: {adventure.metadata.name}"
+            )
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to initialize game with adventure: {e}")
+            return False
+
+    # =========================================================================
+    # Content Retrieval
+    # =========================================================================
+
+    def get_starting_narrative(self, adventure_name: str) -> str:
+        """
+        Get the opening narrative for an adventure.
+
+        Args:
+            adventure_name: Name of adventure
+
+        Returns:
+            Opening narrative text, or empty string if not found
+        """
+        adventure = self.load(adventure_name)
+        if adventure is None:
+            return ""
+
+        starting_scene = adventure.starting_scene
+        return str(starting_scene.get("narrative", ""))
+
+    def get_scene(
+        self,
+        adventure_name: str,
+        scene_id: str,
+    ) -> SceneInfo | None:
+        """
+        Get a scene from an adventure.
+
+        Args:
+            adventure_name: Name of adventure
+            scene_id: Scene ID to find
+
+        Returns:
+            SceneInfo if found, None otherwise
+        """
+        adventure = self.load(adventure_name)
+        if adventure is None:
+            return None
+
+        scene_data = adventure.get_scene(scene_id)
+        if scene_data is None:
+            return None
+
+        return self._parse_scene(scene_data)
+
+    def get_encounter(
+        self,
+        adventure_name: str,
+        encounter_id: str,
+    ) -> EncounterData | None:
+        """
+        Get an encounter from an adventure.
+
+        Args:
+            adventure_name: Name of adventure
+            encounter_id: Encounter ID to find
+
+        Returns:
+            EncounterData if found, None otherwise
+        """
+        adventure = self.load(adventure_name)
+        if adventure is None:
+            return None
+
+        return adventure.get_encounter(encounter_id)
+
+    def get_npc(
+        self,
+        adventure_name: str,
+        npc_id: str,
+    ) -> NPCInfo | None:
+        """
+        Get an NPC from an adventure.
+
+        Args:
+            adventure_name: Name of adventure
+            npc_id: NPC ID to find
+
+        Returns:
+            NPCInfo if found, None otherwise
+        """
+        adventure = self.load(adventure_name)
+        if adventure is None:
+            return None
+
+        npc_data = adventure.get_npc(npc_id)
+        if npc_data is None:
+            return None
+
+        return self._parse_npc(npc_data)
+
+    def get_all_scenes(self, adventure_name: str) -> list[SceneInfo]:
+        """
+        Get all scenes from an adventure.
+
+        Args:
+            adventure_name: Name of adventure
+
+        Returns:
+            List of all SceneInfo objects
+        """
+        adventure = self.load(adventure_name)
+        if adventure is None:
+            return []
+
+        scenes: list[SceneInfo] = []
+        for scene_data in adventure.scenes:
+            if isinstance(scene_data, dict):
+                scene = self._parse_scene(scene_data)
+                if scene:
+                    scenes.append(scene)
+
+        return scenes
+
+    def get_all_npcs(self, adventure_name: str) -> list[NPCInfo]:
+        """
+        Get all NPCs from an adventure.
+
+        Args:
+            adventure_name: Name of adventure
+
+        Returns:
+            List of all NPCInfo objects
+        """
+        adventure = self.load(adventure_name)
+        if adventure is None:
+            return []
+
+        npcs: list[NPCInfo] = []
+        for npc_data in adventure.npcs:
+            if isinstance(npc_data, dict):
+                npc = self._parse_npc(npc_data)
+                if npc:
+                    npcs.append(npc)
+
+        return npcs
+
+    # =========================================================================
+    # Parsing Helpers
+    # =========================================================================
+
+    def _parse_scene(self, data: dict[str, object]) -> SceneInfo | None:
+        """
+        Parse a scene dict into SceneInfo.
+
+        Args:
+            data: Raw scene data
+
+        Returns:
+            SceneInfo if valid, None otherwise
+        """
+        try:
+            scene_id = str(data.get("scene_id", ""))
+            if not scene_id:
+                return None
+
+            # Extract sensory details
+            details = data.get("details", {})
+            sensory: dict[str, str] = {}
+            if isinstance(details, dict):
+                sensory_raw = details.get("sensory", {})
+                if isinstance(sensory_raw, dict):
+                    for key, value in sensory_raw.items():
+                        sensory[str(key)] = str(value)
+
+            # Extract searchable objects
+            searchable: list[dict[str, object]] = []
+            if isinstance(details, dict):
+                searchable_raw = details.get("searchable", [])
+                if isinstance(searchable_raw, list):
+                    searchable = [
+                        dict(obj) for obj in searchable_raw if isinstance(obj, dict)
+                    ]
+
+            # Extract encounter ID
+            encounter = data.get("encounter")
+            encounter_id: str | None = None
+            if isinstance(encounter, dict):
+                encounter_id = str(encounter.get("encounter_id", ""))
+            elif isinstance(encounter, str):
+                encounter_id = encounter
+
+            return SceneInfo(
+                scene_id=scene_id,
+                name=str(data.get("name", scene_id)),
+                description=str(data.get("description", "")),
+                sensory_details=sensory,
+                exits=dict(data.get("exits", {})),
+                npcs_present=list(data.get("npcs_present", [])),
+                items=list(data.get("items", [])),
+                encounter_id=encounter_id if encounter_id else None,
+                searchable_objects=searchable,
+            )
+
+        except Exception as e:
+            logger.warning(f"Failed to parse scene: {e}")
+            return None
+
+    def _parse_npc(self, data: dict[str, object]) -> NPCInfo | None:
+        """
+        Parse an NPC dict into NPCInfo.
+
+        Args:
+            data: Raw NPC data
+
+        Returns:
+            NPCInfo if valid, None otherwise
+        """
+        try:
+            npc_id = str(data.get("npc_id", ""))
+            if not npc_id:
+                return None
+
+            return NPCInfo(
+                npc_id=npc_id,
+                name=str(data.get("name", "Unknown")),
+                description=str(data.get("description", "")),
+                personality=str(data.get("personality", "")),
+                voice_profile=str(data.get("voice_profile", "dm")),
+                dialogue_hooks=list(data.get("dialogue_hooks", [])),
+                monster_stat_block=data.get("monster_stat_block"),
+                relationship="hostile"
+                if data.get("monster_stat_block")
+                else "neutral",
+            )
+
+        except Exception as e:
+            logger.warning(f"Failed to parse NPC: {e}")
+            return None
+
+    # =========================================================================
+    # Cache Management
+    # =========================================================================
+
+    def clear_cache(self) -> None:
+        """Clear the adventure cache."""
+        self._cache.clear()
+        logger.debug("Adventure cache cleared")
+
+    def is_cached(self, adventure_name: str) -> bool:
+        """
+        Check if an adventure is cached.
+
+        Args:
+            adventure_name: Name of adventure
+
+        Returns:
+            True if cached, False otherwise
+        """
+        return adventure_name in self._cache
+
+    def preload(self, adventure_names: list[str]) -> int:
+        """
+        Preload multiple adventures into cache.
+
+        Args:
+            adventure_names: List of adventure names to load
+
+        Returns:
+            Number of successfully loaded adventures
+        """
+        loaded = 0
+        for name in adventure_names:
+            if self.load(name) is not None:
+                loaded += 1
+        return loaded
+
+    def __len__(self) -> int:
+        """Return number of cached adventures."""
+        return len(self._cache)

src/game/event_logger.py

@@ -0,0 +1,724 @@
+"""
+DungeonMaster AI - Event Logger
+
+Logs game events for context building and session history.
+Syncs events to MCP session manager asynchronously.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from .models import EventType, SessionEvent
+
+if TYPE_CHECKING:
+    from src.mcp_integration.toolkit_client import TTRPGToolkitClient
+
+logger = logging.getLogger(__name__)
+
+
+# Map EventType to MCP session manager event types
+MCP_EVENT_TYPE_MAP: dict[EventType, str] = {
+    EventType.ROLL: "combat",
+    EventType.COMBAT_START: "combat",
+    EventType.COMBAT_END: "combat",
+    EventType.COMBAT_ACTION: "combat",
+    EventType.DAMAGE: "combat",
+    EventType.HEALING: "combat",
+    EventType.MOVEMENT: "discovery",
+    EventType.DIALOGUE: "roleplay",
+    EventType.DISCOVERY: "discovery",
+    EventType.ITEM_ACQUIRED: "loot",
+    EventType.REST: "rest",
+    EventType.LEVEL_UP: "level_up",
+    EventType.DEATH: "death",
+    EventType.STORY_FLAG: "note",
+    EventType.SYSTEM: "note",
+}
+
+
+class EventLogger:
+    """
+    Logs and manages game session events.
+
+    Provides type-specific logging methods and syncs events to MCP.
+    Events are stored locally and optionally synced to the MCP
+    session manager for persistent history.
+    """
+
+    def __init__(
+        self,
+        toolkit_client: TTRPGToolkitClient | None = None,
+        max_events: int = 100,
+    ) -> None:
+        """
+        Initialize the event logger.
+
+        Args:
+            toolkit_client: Optional MCP toolkit client for syncing
+            max_events: Maximum events to keep in memory
+        """
+        self._toolkit_client = toolkit_client
+        self._max_events = max_events
+        self._events: list[SessionEvent] = []
+        self._current_turn = 0
+        self._mcp_session_id: str | None = None
+
+    def set_toolkit_client(self, client: TTRPGToolkitClient | None) -> None:
+        """Set or update the toolkit client."""
+        self._toolkit_client = client
+
+    def set_mcp_session_id(self, session_id: str | None) -> None:
+        """Set the MCP session ID for syncing."""
+        self._mcp_session_id = session_id
+
+    def set_current_turn(self, turn: int) -> None:
+        """Update the current turn number."""
+        self._current_turn = turn
+
+    @property
+    def events(self) -> list[SessionEvent]:
+        """Get all logged events."""
+        return self._events.copy()
+
+    # =========================================================================
+    # Core Logging
+    # =========================================================================
+
+    def _create_event(
+        self,
+        event_type: EventType,
+        description: str,
+        data: dict[str, object] | None = None,
+        is_significant: bool = False,
+    ) -> SessionEvent:
+        """
+        Create and store a new event.
+
+        Args:
+            event_type: Type of event
+            description: Human-readable description
+            data: Event-specific data
+            is_significant: Whether event is significant for context
+
+        Returns:
+            The created SessionEvent
+        """
+        event = SessionEvent(
+            event_id=str(uuid.uuid4()),
+            event_type=event_type,
+            description=description,
+            data=data or {},
+            timestamp=datetime.now(),
+            turn=self._current_turn,
+            is_significant=is_significant,
+        )
+
+        self._events.append(event)
+
+        # Trim to max size
+        if len(self._events) > self._max_events:
+            self._events = self._events[-self._max_events :]
+
+        # Fire-and-forget sync to MCP
+        self._sync_to_mcp(event)
+
+        return event
+
+    def _sync_to_mcp(self, event: SessionEvent) -> None:
+        """
+        Sync an event to MCP session manager (fire-and-forget).
+
+        Args:
+            event: Event to sync
+        """
+        if not self._toolkit_client or not self._mcp_session_id:
+            return
+
+        try:
+            # Check if we're in an async context
+            loop = asyncio.get_running_loop()
+            # Create task for async sync
+            loop.create_task(self._async_sync_event(event))
+        except RuntimeError:
+            # Not in async context, skip sync
+            logger.debug("Not in async context, skipping MCP event sync")
+
+    async def _async_sync_event(self, event: SessionEvent) -> None:
+        """
+        Async helper to sync event to MCP.
+
+        Args:
+            event: Event to sync
+        """
+        if not self._toolkit_client:
+            return
+
+        try:
+            mcp_event_type = MCP_EVENT_TYPE_MAP.get(event.event_type, "note")
+
+            await self._toolkit_client.call_tool(
+                "mcp_log_event",
+                {
+                    "event_type": mcp_event_type,
+                    "description": event.description,
+                    "important": event.is_significant,
+                },
+            )
+        except Exception as e:
+            # Silent failure - don't block gameplay for sync failures
+            logger.debug(f"Failed to sync event to MCP: {e}")
+
+    # =========================================================================
+    # Type-Specific Logging Methods
+    # =========================================================================
+
+    def log_roll(
+        self,
+        notation: str,
+        total: int,
+        roll_type: str = "standard",
+        is_critical: bool = False,
+        is_fumble: bool = False,
+        character_name: str | None = None,
+    ) -> SessionEvent:
+        """
+        Log a dice roll event.
+
+        Args:
+            notation: Dice notation (e.g., "1d20+5")
+            total: Roll total
+            roll_type: Type of roll (attack, save, check, etc.)
+            is_critical: Whether this is a natural 20
+            is_fumble: Whether this is a natural 1
+            character_name: Name of character rolling
+
+        Returns:
+            Created SessionEvent
+        """
+        actor = character_name or "Unknown"
+
+        # Build description
+        if is_critical:
+            desc = f"{actor} rolled {notation}: {total} - CRITICAL!"
+        elif is_fumble:
+            desc = f"{actor} rolled {notation}: {total} - Fumble!"
+        else:
+            desc = f"{actor} rolled {notation}: {total}"
+
+        if roll_type != "standard":
+            desc += f" ({roll_type})"
+
+        return self._create_event(
+            event_type=EventType.ROLL,
+            description=desc,
+            data={
+                "notation": notation,
+                "total": total,
+                "roll_type": roll_type,
+                "is_critical": is_critical,
+                "is_fumble": is_fumble,
+                "character": character_name,
+            },
+            is_significant=is_critical or is_fumble,
+        )
+
+    def log_combat_action(
+        self,
+        actor: str,
+        action: str,
+        target: str | None = None,
+        damage: int | None = None,
+        hit: bool | None = None,
+    ) -> SessionEvent:
+        """
+        Log a combat action event.
+
+        Args:
+            actor: Who performed the action
+            action: What action was taken (attack, cast, etc.)
+            target: Target of the action
+            damage: Damage dealt if applicable
+            hit: Whether attack hit if applicable
+
+        Returns:
+            Created SessionEvent
+        """
+        parts = [f"{actor} {action}"]
+
+        if target:
+            parts.append(f"targeting {target}")
+
+        if hit is not None:
+            if hit:
+                parts.append("- Hit!")
+                if damage:
+                    parts.append(f"for {damage} damage")
+            else:
+                parts.append("- Miss!")
+
+        desc = " ".join(parts)
+
+        return self._create_event(
+            event_type=EventType.COMBAT_ACTION,
+            description=desc,
+            data={
+                "actor": actor,
+                "action": action,
+                "target": target,
+                "damage": damage,
+                "hit": hit,
+            },
+            is_significant=damage is not None and damage >= 10,
+        )
+
+    def log_damage(
+        self,
+        character_name: str,
+        amount: int,
+        damage_type: str = "untyped",
+        source: str = "unknown",
+        is_lethal: bool = False,
+    ) -> SessionEvent:
+        """
+        Log a damage event.
+
+        Args:
+            character_name: Who took damage
+            amount: Amount of damage
+            damage_type: Type of damage
+            source: Source of damage
+            is_lethal: Whether damage was lethal
+
+        Returns:
+            Created SessionEvent
+        """
+        if is_lethal:
+            desc = f"{character_name} took {amount} {damage_type} damage from {source} and fell unconscious!"
+        else:
+            desc = f"{character_name} took {amount} {damage_type} damage from {source}"
+
+        return self._create_event(
+            event_type=EventType.DAMAGE,
+            description=desc,
+            data={
+                "character": character_name,
+                "amount": amount,
+                "damage_type": damage_type,
+                "source": source,
+                "is_lethal": is_lethal,
+            },
+            is_significant=is_lethal or amount >= 10,
+        )
+
+    def log_healing(
+        self,
+        character_name: str,
+        amount: int,
+        source: str = "unknown",
+    ) -> SessionEvent:
+        """
+        Log a healing event.
+
+        Args:
+            character_name: Who was healed
+            amount: Amount of healing
+            source: Source of healing
+
+        Returns:
+            Created SessionEvent
+        """
+        desc = f"{character_name} healed {amount} HP from {source}"
+
+        return self._create_event(
+            event_type=EventType.HEALING,
+            description=desc,
+            data={
+                "character": character_name,
+                "amount": amount,
+                "source": source,
+            },
+            is_significant=amount >= 10,
+        )
+
+    def log_dialogue(
+        self,
+        speaker: str,
+        summary: str,
+        is_npc: bool = True,
+    ) -> SessionEvent:
+        """
+        Log a dialogue event.
+
+        Args:
+            speaker: Who is speaking
+            summary: Summary of what was said
+            is_npc: Whether speaker is an NPC
+
+        Returns:
+            Created SessionEvent
+        """
+        desc = f'{speaker}: "{summary}"'
+
+        return self._create_event(
+            event_type=EventType.DIALOGUE,
+            description=desc,
+            data={
+                "speaker": speaker,
+                "summary": summary,
+                "is_npc": is_npc,
+            },
+            is_significant=False,
+        )
+
+    def log_discovery(
+        self,
+        what: str,
+        details: str = "",
+        character_name: str | None = None,
+    ) -> SessionEvent:
+        """
+        Log a discovery event.
+
+        Args:
+            what: What was discovered
+            details: Additional details
+            character_name: Who made the discovery
+
+        Returns:
+            Created SessionEvent
+        """
+        actor = character_name or "The party"
+
+        if details:
+            desc = f"{actor} discovered: {what} - {details}"
+        else:
+            desc = f"{actor} discovered: {what}"
+
+        return self._create_event(
+            event_type=EventType.DISCOVERY,
+            description=desc,
+            data={
+                "what": what,
+                "details": details,
+                "character": character_name,
+            },
+            is_significant=True,  # Discoveries are always significant
+        )
+
+    def log_movement(
+        self,
+        from_location: str,
+        to_location: str,
+    ) -> SessionEvent:
+        """
+        Log a movement/location change event.
+
+        Args:
+            from_location: Previous location
+            to_location: New location
+
+        Returns:
+            Created SessionEvent
+        """
+        desc = f"Moved from {from_location} to {to_location}"
+
+        return self._create_event(
+            event_type=EventType.MOVEMENT,
+            description=desc,
+            data={
+                "from": from_location,
+                "to": to_location,
+            },
+            is_significant=True,  # Location changes are significant
+        )
+
+    def log_combat_start(
+        self,
+        description: str,
+        combatants: list[str] | None = None,
+    ) -> SessionEvent:
+        """
+        Log combat starting.
+
+        Args:
+            description: Description of combat start
+            combatants: List of combatant names
+
+        Returns:
+            Created SessionEvent
+        """
+        return self._create_event(
+            event_type=EventType.COMBAT_START,
+            description=f"Combat began: {description}",
+            data={
+                "combatants": combatants or [],
+            },
+            is_significant=True,
+        )
+
+    def log_combat_end(
+        self,
+        outcome: str = "victory",
+        description: str = "",
+    ) -> SessionEvent:
+        """
+        Log combat ending.
+
+        Args:
+            outcome: Combat outcome (victory, defeat, fled)
+            description: Additional description
+
+        Returns:
+            Created SessionEvent
+        """
+        desc = f"Combat ended: {outcome}"
+        if description:
+            desc += f" - {description}"
+
+        return self._create_event(
+            event_type=EventType.COMBAT_END,
+            description=desc,
+            data={
+                "outcome": outcome,
+            },
+            is_significant=True,
+        )
+
+    def log_item_acquired(
+        self,
+        item_name: str,
+        character_name: str | None = None,
+        quantity: int = 1,
+    ) -> SessionEvent:
+        """
+        Log acquiring an item.
+
+        Args:
+            item_name: Name of item
+            character_name: Who got the item
+            quantity: Number of items
+
+        Returns:
+            Created SessionEvent
+        """
+        actor = character_name or "The party"
+
+        if quantity > 1:
+            desc = f"{actor} acquired {quantity}x {item_name}"
+        else:
+            desc = f"{actor} acquired {item_name}"
+
+        return self._create_event(
+            event_type=EventType.ITEM_ACQUIRED,
+            description=desc,
+            data={
+                "item": item_name,
+                "character": character_name,
+                "quantity": quantity,
+            },
+            is_significant=True,
+        )
+
+    def log_rest(
+        self,
+        rest_type: str,
+        character_name: str | None = None,
+        hp_recovered: int = 0,
+    ) -> SessionEvent:
+        """
+        Log a rest event.
+
+        Args:
+            rest_type: Type of rest (short, long)
+            character_name: Who rested
+            hp_recovered: HP recovered if applicable
+
+        Returns:
+            Created SessionEvent
+        """
+        actor = character_name or "The party"
+        desc = f"{actor} took a {rest_type} rest"
+
+        if hp_recovered > 0:
+            desc += f" and recovered {hp_recovered} HP"
+
+        return self._create_event(
+            event_type=EventType.REST,
+            description=desc,
+            data={
+                "rest_type": rest_type,
+                "character": character_name,
+                "hp_recovered": hp_recovered,
+            },
+            is_significant=True,
+        )
+
+    def log_death(
+        self,
+        character_name: str,
+        cause: str = "unknown",
+    ) -> SessionEvent:
+        """
+        Log a character death.
+
+        Args:
+            character_name: Who died
+            cause: Cause of death
+
+        Returns:
+            Created SessionEvent
+        """
+        return self._create_event(
+            event_type=EventType.DEATH,
+            description=f"{character_name} has fallen! Cause: {cause}",
+            data={
+                "character": character_name,
+                "cause": cause,
+            },
+            is_significant=True,  # Deaths are always significant
+        )
+
+    def log_level_up(
+        self,
+        character_name: str,
+        new_level: int,
+    ) -> SessionEvent:
+        """
+        Log a level up.
+
+        Args:
+            character_name: Who leveled up
+            new_level: New level
+
+        Returns:
+            Created SessionEvent
+        """
+        return self._create_event(
+            event_type=EventType.LEVEL_UP,
+            description=f"{character_name} reached level {new_level}!",
+            data={
+                "character": character_name,
+                "level": new_level,
+            },
+            is_significant=True,
+        )
+
+    def log_story_flag(
+        self,
+        flag: str,
+        value: object,
+        description: str = "",
+    ) -> SessionEvent:
+        """
+        Log a story flag change.
+
+        Args:
+            flag: Flag name
+            value: New value
+            description: Optional description
+
+        Returns:
+            Created SessionEvent
+        """
+        desc = description or f"Story progress: {flag}"
+
+        return self._create_event(
+            event_type=EventType.STORY_FLAG,
+            description=desc,
+            data={
+                "flag": flag,
+                "value": value,
+            },
+            is_significant=True,
+        )
+
+    def log_system(
+        self,
+        message: str,
+        data: dict[str, object] | None = None,
+    ) -> SessionEvent:
+        """
+        Log a system event.
+
+        Args:
+            message: System message
+            data: Optional data
+
+        Returns:
+            Created SessionEvent
+        """
+        return self._create_event(
+            event_type=EventType.SYSTEM,
+            description=message,
+            data=data or {},
+            is_significant=False,
+        )
+
+    # =========================================================================
+    # Retrieval Methods
+    # =========================================================================
+
+    def get_recent(
+        self,
+        count: int = 10,
+        event_type: EventType | None = None,
+        significant_only: bool = False,
+    ) -> list[SessionEvent]:
+        """
+        Get recent events with optional filtering.
+
+        Args:
+            count: Maximum events to return
+            event_type: Filter by event type
+            significant_only: Only return significant events
+
+        Returns:
+            List of matching events (most recent first)
+        """
+        filtered = self._events.copy()
+
+        if event_type is not None:
+            filtered = [e for e in filtered if e.event_type == event_type]
+
+        if significant_only:
+            filtered = [e for e in filtered if e.is_significant]
+
+        # Return most recent first
+        return list(reversed(filtered[-count:]))
+
+    def get_events_for_turn(self, turn: int) -> list[SessionEvent]:
+        """
+        Get all events for a specific turn.
+
+        Args:
+            turn: Turn number
+
+        Returns:
+            List of events from that turn
+        """
+        return [e for e in self._events if e.turn == turn]
+
+    def get_events_since(self, timestamp: datetime) -> list[SessionEvent]:
+        """
+        Get all events since a given timestamp.
+
+        Args:
+            timestamp: Cutoff timestamp
+
+        Returns:
+            List of events after timestamp
+        """
+        return [e for e in self._events if e.timestamp > timestamp]
+
+    def clear(self) -> None:
+        """Clear all logged events."""
+        self._events.clear()
+
+    def __len__(self) -> int:
+        """Return number of logged events."""
+        return len(self._events)

src/game/game_state.py

@@ -0,0 +1,367 @@
+"""
+DungeonMaster AI - Game State Management
+
+Minimal GameState stub for Phase 1 (MCP Integration).
+This provides the interface that tool wrappers need.
+Phase 4 will extend this with full implementation.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class GameStateProtocol(Protocol):
+    """
+    Protocol for game state access.
+
+    This interface allows MCP tool wrappers to update game state
+    without depending on the full GameState implementation.
+    Phase 4 will provide the complete implementation.
+    """
+
+    session_id: str
+    in_combat: bool
+    party: list[str]
+    recent_events: list[dict[str, object]]
+
+    def add_event(
+        self,
+        event_type: str,
+        description: str,
+        data: dict[str, object],
+    ) -> None:
+        """Add an event to recent events."""
+        ...
+
+    def get_character(self, character_id: str) -> dict[str, object] | None:
+        """Get character data from cache."""
+        ...
+
+    def update_character_cache(
+        self,
+        character_id: str,
+        data: dict[str, object],
+    ) -> None:
+        """Update character data in cache."""
+        ...
+
+    def set_combat_state(self, combat_state: dict[str, object] | None) -> None:
+        """Set or clear combat state."""
+        ...
+
+
+@dataclass
+class GameState:
+    """
+    Minimal game state stub for Phase 1.
+
+    Provides the basic interface that MCP tool wrappers need.
+    Phase 4 will extend this with:
+    - Full Pydantic models (GameState, CombatState, etc.)
+    - GameStateManager class
+    - State persistence (save/load)
+    - Story context building
+    """
+
+    # Core state
+    session_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    started_at: datetime = field(default_factory=datetime.now)
+    system: str = "dnd5e"
+
+    # Party management
+    party: list[str] = field(default_factory=list)
+    active_character_id: str | None = None
+
+    # Location
+    current_location: str = "Unknown"
+    current_scene: dict[str, object] = field(default_factory=dict)
+
+    # Combat
+    in_combat: bool = False
+    _combat_state: dict[str, object] | None = field(default=None, repr=False)
+
+    # Events
+    recent_events: list[dict[str, object]] = field(default_factory=list)
+    turn_count: int = 0
+
+    # Caches
+    _character_cache: dict[str, dict[str, object]] = field(
+        default_factory=dict,
+        repr=False,
+    )
+    _known_npcs: dict[str, dict[str, object]] = field(
+        default_factory=dict,
+        repr=False,
+    )
+
+    # Story tracking
+    story_flags: dict[str, object] = field(default_factory=dict)
+    current_adventure: str | None = None
+
+    # Metadata
+    last_updated: datetime = field(default_factory=datetime.now)
+
+    # Configuration
+    max_recent_events: int = field(default=20, repr=False)
+
+    def add_event(
+        self,
+        event_type: str,
+        description: str,
+        data: dict[str, object],
+    ) -> None:
+        """
+        Add an event to recent events list.
+
+        Keeps only the most recent events (default: 20).
+
+        Args:
+            event_type: Type of event (roll, combat, dialogue, etc.)
+            description: Human-readable description
+            data: Event-specific data
+        """
+        event = {
+            "type": event_type,
+            "description": description,
+            "data": data,
+            "timestamp": datetime.now().isoformat(),
+            "turn": self.turn_count,
+        }
+        self.recent_events.append(event)
+
+        # Trim to max size
+        if len(self.recent_events) > self.max_recent_events:
+            self.recent_events = self.recent_events[-self.max_recent_events :]
+
+        self.last_updated = datetime.now()
+
+    def get_character(self, character_id: str) -> dict[str, object] | None:
+        """
+        Get character data from cache.
+
+        Args:
+            character_id: Character ID to look up
+
+        Returns:
+            Character data dict or None if not cached
+        """
+        return self._character_cache.get(character_id)
+
+    def update_character_cache(
+        self,
+        character_id: str,
+        data: dict[str, object],
+    ) -> None:
+        """
+        Update character data in cache.
+
+        Args:
+            character_id: Character ID
+            data: Character data to cache
+        """
+        self._character_cache[character_id] = data
+        self.last_updated = datetime.now()
+
+    def set_combat_state(self, combat_state: dict[str, object] | None) -> None:
+        """
+        Set or clear combat state.
+
+        Args:
+            combat_state: Combat state dict, or None to clear
+        """
+        self._combat_state = combat_state
+        self.in_combat = combat_state is not None
+        self.last_updated = datetime.now()
+
+        # Log combat state change
+        if combat_state is not None:
+            self.add_event(
+                event_type="combat_start",
+                description="Combat has begun",
+                data={"combatants": combat_state.get("turn_order", [])},
+            )
+        else:
+            self.add_event(
+                event_type="combat_end",
+                description="Combat has ended",
+                data={},
+            )
+
+    @property
+    def combat_state(self) -> dict[str, object] | None:
+        """Get current combat state."""
+        return self._combat_state
+
+    def add_character_to_party(self, character_id: str) -> None:
+        """
+        Add a character to the party.
+
+        Args:
+            character_id: Character ID to add
+        """
+        if character_id not in self.party:
+            self.party.append(character_id)
+            # Set as active if first character
+            if self.active_character_id is None:
+                self.active_character_id = character_id
+            self.last_updated = datetime.now()
+
+    def remove_character_from_party(self, character_id: str) -> None:
+        """
+        Remove a character from the party.
+
+        Args:
+            character_id: Character ID to remove
+        """
+        if character_id in self.party:
+            self.party.remove(character_id)
+            # Clear active if removed
+            if self.active_character_id == character_id:
+                self.active_character_id = self.party[0] if self.party else None
+            # Clear from cache
+            self._character_cache.pop(character_id, None)
+            self.last_updated = datetime.now()
+
+    def set_location(
+        self,
+        location: str,
+        scene: dict[str, object] | None = None,
+    ) -> None:
+        """
+        Update current location.
+
+        Args:
+            location: Location name/description
+            scene: Optional scene details
+        """
+        self.current_location = location
+        if scene:
+            self.current_scene = scene
+
+        self.add_event(
+            event_type="movement",
+            description=f"Moved to {location}",
+            data={"location": location, "scene": scene or {}},
+        )
+        self.last_updated = datetime.now()
+
+    def increment_turn(self) -> int:
+        """
+        Increment turn counter.
+
+        Returns:
+            New turn count
+        """
+        self.turn_count += 1
+        self.last_updated = datetime.now()
+        return self.turn_count
+
+    def set_story_flag(self, flag: str, value: object) -> None:
+        """
+        Set a story/quest flag.
+
+        Args:
+            flag: Flag name
+            value: Flag value
+        """
+        self.story_flags[flag] = value
+        self.last_updated = datetime.now()
+
+    def get_story_flag(self, flag: str, default: object = None) -> object:
+        """
+        Get a story/quest flag.
+
+        Args:
+            flag: Flag name
+            default: Default value if not set
+
+        Returns:
+            Flag value or default
+        """
+        return self.story_flags.get(flag, default)
+
+    def add_known_npc(self, npc_id: str, data: dict[str, object]) -> None:
+        """
+        Add or update a known NPC.
+
+        Args:
+            npc_id: NPC identifier
+            data: NPC data
+        """
+        self._known_npcs[npc_id] = data
+        self.last_updated = datetime.now()
+
+    def get_known_npc(self, npc_id: str) -> dict[str, object] | None:
+        """
+        Get known NPC data.
+
+        Args:
+            npc_id: NPC identifier
+
+        Returns:
+            NPC data or None
+        """
+        return self._known_npcs.get(npc_id)
+
+    def get_recent_events_by_type(
+        self,
+        event_type: str,
+        limit: int = 10,
+    ) -> list[dict[str, object]]:
+        """
+        Get recent events filtered by type.
+
+        Args:
+            event_type: Event type to filter
+            limit: Maximum events to return
+
+        Returns:
+            List of matching events
+        """
+        matching = [e for e in self.recent_events if e.get("type") == event_type]
+        return matching[-limit:]
+
+    def to_summary(self) -> dict[str, object]:
+        """
+        Create a summary dict for LLM context.
+
+        Returns:
+            Summary dict with key state information
+        """
+        return {
+            "session_id": self.session_id,
+            "system": self.system,
+            "turn_count": self.turn_count,
+            "party_size": len(self.party),
+            "active_character": self.active_character_id,
+            "location": self.current_location,
+            "in_combat": self.in_combat,
+            "combat_round": (
+                self._combat_state.get("round") if self._combat_state else None
+            ),
+            "recent_events_count": len(self.recent_events),
+            "adventure": self.current_adventure,
+        }
+
+    def reset(self) -> None:
+        """Reset game state for new game."""
+        self.session_id = str(uuid.uuid4())
+        self.started_at = datetime.now()
+        self.party.clear()
+        self.active_character_id = None
+        self.current_location = "Unknown"
+        self.current_scene.clear()
+        self.in_combat = False
+        self._combat_state = None
+        self.recent_events.clear()
+        self.turn_count = 0
+        self._character_cache.clear()
+        self._known_npcs.clear()
+        self.story_flags.clear()
+        self.current_adventure = None
+        self.last_updated = datetime.now()

src/game/game_state_manager.py

@@ -0,0 +1,992 @@
+"""
+DungeonMaster AI - Game State Manager
+
+High-level manager for game state, integrating MCP tools,
+character caching, combat tracking, and save/load functionality.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .event_logger import EventLogger
+from .models import (
+    CharacterSnapshot,
+    CombatantStatus,
+    Combatant,
+    CombatState,
+    EventType,
+    GameSaveData,
+    NPCInfo,
+    SceneInfo,
+    SessionEvent,
+)
+
+if TYPE_CHECKING:
+    from src.mcp_integration.toolkit_client import TTRPGToolkitClient
+
+logger = logging.getLogger(__name__)
+
+
+class GameStateManager:
+    """
+    High-level manager for game state.
+
+    Orchestrates MCP tool integration, character caching, combat state,
+    event logging, and save/load functionality. This is the main interface
+    for game state management used by the agent orchestrator.
+    """
+
+    def __init__(
+        self,
+        toolkit_client: TTRPGToolkitClient | None = None,
+        max_recent_events: int = 50,
+        character_cache_ttl: int = 300,  # 5 minutes
+    ) -> None:
+        """
+        Initialize the game state manager.
+
+        Args:
+            toolkit_client: Optional MCP toolkit client for remote operations
+            max_recent_events: Maximum events to keep in memory
+            character_cache_ttl: Character cache TTL in seconds
+        """
+        self._toolkit_client = toolkit_client
+        self._max_recent_events = max_recent_events
+        self._character_cache_ttl = character_cache_ttl
+
+        # Session state
+        self._session_id = str(uuid.uuid4())
+        self._mcp_session_id: str | None = None
+        self._started_at = datetime.now()
+        self._turn_count = 0
+
+        # Party state
+        self._party_ids: list[str] = []
+        self._active_character_id: str | None = None
+
+        # Location state
+        self._current_location = "Unknown"
+        self._current_scene: SceneInfo | None = None
+
+        # Combat state
+        self._in_combat = False
+        self._combat_state: CombatState | None = None
+
+        # Tracking
+        self._story_flags: dict[str, object] = {}
+        self._known_npcs: dict[str, NPCInfo] = {}
+
+        # Caching
+        self._character_cache: dict[str, CharacterSnapshot] = {}
+        self._character_cache_times: dict[str, datetime] = {}
+
+        # Adventure
+        self._adventure_name: str | None = None
+
+        # Event logger
+        self._event_logger = EventLogger(
+            toolkit_client=toolkit_client,
+            max_events=max_recent_events,
+        )
+
+        logger.debug(f"GameStateManager initialized with session: {self._session_id}")
+
+    # =========================================================================
+    # Properties
+    # =========================================================================
+
+    @property
+    def session_id(self) -> str:
+        """Get the current session ID."""
+        return self._session_id
+
+    @property
+    def mcp_session_id(self) -> str | None:
+        """Get the MCP session ID if connected."""
+        return self._mcp_session_id
+
+    @property
+    def turn_count(self) -> int:
+        """Get the current turn count."""
+        return self._turn_count
+
+    @property
+    def party_ids(self) -> list[str]:
+        """Get list of character IDs in the party."""
+        return self._party_ids.copy()
+
+    @property
+    def active_character_id(self) -> str | None:
+        """Get the active character ID."""
+        return self._active_character_id
+
+    @property
+    def current_location(self) -> str:
+        """Get the current location name."""
+        return self._current_location
+
+    @property
+    def current_scene(self) -> SceneInfo | None:
+        """Get the current scene info."""
+        return self._current_scene
+
+    @property
+    def in_combat(self) -> bool:
+        """Check if combat is active."""
+        return self._in_combat
+
+    @property
+    def combat_state(self) -> CombatState | None:
+        """Get the current combat state."""
+        return self._combat_state
+
+    @property
+    def adventure_name(self) -> str | None:
+        """Get the loaded adventure name."""
+        return self._adventure_name
+
+    @property
+    def story_flags(self) -> dict[str, object]:
+        """Get all story flags."""
+        return self._story_flags.copy()
+
+    @property
+    def event_logger(self) -> EventLogger:
+        """Get the event logger."""
+        return self._event_logger
+
+    @property
+    def recent_events(self) -> list[SessionEvent]:
+        """Get recent events from the logger."""
+        return self._event_logger.events
+
+    # =========================================================================
+    # Session Lifecycle
+    # =========================================================================
+
+    async def new_game(self, adventure: str | None = None) -> str:
+        """
+        Start a new game session.
+
+        Resets all state and optionally starts an MCP session.
+
+        Args:
+            adventure: Optional adventure name
+
+        Returns:
+            The new session ID
+        """
+        # Reset state
+        self._session_id = str(uuid.uuid4())
+        self._started_at = datetime.now()
+        self._turn_count = 0
+        self._party_ids.clear()
+        self._active_character_id = None
+        self._current_location = "Unknown"
+        self._current_scene = None
+        self._in_combat = False
+        self._combat_state = None
+        self._story_flags.clear()
+        self._known_npcs.clear()
+        self._character_cache.clear()
+        self._character_cache_times.clear()
+        self._adventure_name = adventure
+
+        # Clear event logger
+        self._event_logger.clear()
+        self._event_logger.set_current_turn(0)
+
+        # Start MCP session if connected
+        if self._toolkit_client and self._toolkit_client.is_connected:
+            try:
+                result = await self._toolkit_client.call_tool(
+                    "mcp_start_session",
+                    {
+                        "campaign_name": adventure or "DungeonMaster AI Session",
+                        "system": "dnd5e",
+                    },
+                )
+                if isinstance(result, dict):
+                    self._mcp_session_id = str(result.get("session_id", ""))
+                    self._event_logger.set_mcp_session_id(self._mcp_session_id)
+                    logger.info(f"Started MCP session: {self._mcp_session_id}")
+            except Exception as e:
+                logger.warning(f"Failed to start MCP session: {e}")
+                self._mcp_session_id = None
+
+        # Log system event
+        self._event_logger.log_system(
+            f"New game started" + (f": {adventure}" if adventure else ""),
+            {"adventure": adventure},
+        )
+
+        logger.info(f"New game started with session: {self._session_id}")
+        return self._session_id
+
+    async def end_game(self) -> None:
+        """
+        End the current game session.
+
+        Ends the MCP session if connected and logs the event.
+        """
+        # End MCP session if active
+        if self._toolkit_client and self._mcp_session_id:
+            try:
+                await self._toolkit_client.call_tool(
+                    "mcp_end_session",
+                    {"session_id": self._mcp_session_id},
+                )
+                logger.info(f"Ended MCP session: {self._mcp_session_id}")
+            except Exception as e:
+                logger.warning(f"Failed to end MCP session: {e}")
+
+        # Log event
+        self._event_logger.log_system(
+            "Game ended",
+            {"turns": self._turn_count, "duration_minutes": self._get_session_duration()},
+        )
+
+        self._mcp_session_id = None
+
+    def _get_session_duration(self) -> int:
+        """Get session duration in minutes."""
+        delta = datetime.now() - self._started_at
+        return int(delta.total_seconds() / 60)
+
+    # =========================================================================
+    # Character Management
+    # =========================================================================
+
+    async def add_character(self, character_id: str) -> CharacterSnapshot | None:
+        """
+        Add a character to the party.
+
+        Fetches character data from MCP and caches it.
+
+        Args:
+            character_id: ID of character to add
+
+        Returns:
+            CharacterSnapshot if successful, None otherwise
+        """
+        # Check if already in party
+        if character_id in self._party_ids:
+            return self._character_cache.get(character_id)
+
+        # Fetch from MCP
+        snapshot = await self._fetch_character(character_id)
+        if snapshot is None:
+            logger.warning(f"Failed to fetch character: {character_id}")
+            return None
+
+        # Add to party
+        self._party_ids.append(character_id)
+
+        # Set as active if first character
+        if self._active_character_id is None:
+            self._active_character_id = character_id
+
+        # Log event
+        self._event_logger.log_system(
+            f"{snapshot.name} joined the party",
+            {"character_id": character_id, "name": snapshot.name},
+        )
+
+        logger.info(f"Added character to party: {snapshot.name} ({character_id})")
+        return snapshot
+
+    async def _fetch_character(self, character_id: str) -> CharacterSnapshot | None:
+        """
+        Fetch character data from MCP and cache it.
+
+        Args:
+            character_id: Character ID to fetch
+
+        Returns:
+            CharacterSnapshot if successful, None otherwise
+        """
+        if not self._toolkit_client or not self._toolkit_client.is_connected:
+            # Return cached if available
+            return self._character_cache.get(character_id)
+
+        try:
+            result = await self._toolkit_client.call_tool(
+                "mcp_get_character",
+                {"character_id": character_id},
+            )
+
+            if not isinstance(result, dict):
+                return None
+
+            if not result.get("success", False):
+                return None
+
+            snapshot = CharacterSnapshot.from_mcp_result(result)
+
+            # Cache the result
+            self._character_cache[character_id] = snapshot
+            self._character_cache_times[character_id] = datetime.now()
+
+            return snapshot
+
+        except Exception as e:
+            logger.warning(f"Failed to fetch character {character_id}: {e}")
+            return self._character_cache.get(character_id)
+
+    async def get_active_character(self) -> CharacterSnapshot | None:
+        """
+        Get the active character's data.
+
+        Refreshes from MCP if cache is stale.
+
+        Returns:
+            CharacterSnapshot if available, None otherwise
+        """
+        if self._active_character_id is None:
+            return None
+
+        # Check cache freshness
+        if self._is_cache_stale(self._active_character_id):
+            await self.refresh_character(self._active_character_id)
+
+        return self._character_cache.get(self._active_character_id)
+
+    def _is_cache_stale(self, character_id: str) -> bool:
+        """Check if a character's cache is stale."""
+        cache_time = self._character_cache_times.get(character_id)
+        if cache_time is None:
+            return True
+
+        age = datetime.now() - cache_time
+        return age.total_seconds() > self._character_cache_ttl
+
+    async def refresh_character(
+        self,
+        character_id: str,
+    ) -> CharacterSnapshot | None:
+        """
+        Force refresh a character's data from MCP.
+
+        Args:
+            character_id: Character to refresh
+
+        Returns:
+            Updated CharacterSnapshot if successful
+        """
+        return await self._fetch_character(character_id)
+
+    def set_active_character(self, character_id: str) -> bool:
+        """
+        Set the active character.
+
+        Args:
+            character_id: Character ID to make active
+
+        Returns:
+            True if successful, False if not in party
+        """
+        if character_id not in self._party_ids:
+            return False
+
+        self._active_character_id = character_id
+        return True
+
+    def remove_character(self, character_id: str) -> None:
+        """
+        Remove a character from the party.
+
+        Args:
+            character_id: Character to remove
+        """
+        if character_id in self._party_ids:
+            self._party_ids.remove(character_id)
+
+            # Clear active if removed
+            if self._active_character_id == character_id:
+                self._active_character_id = (
+                    self._party_ids[0] if self._party_ids else None
+                )
+
+            # Clear from cache
+            self._character_cache.pop(character_id, None)
+            self._character_cache_times.pop(character_id, None)
+
+    def get_character_snapshot(
+        self,
+        character_id: str,
+    ) -> CharacterSnapshot | None:
+        """
+        Get a character's cached snapshot.
+
+        Args:
+            character_id: Character ID
+
+        Returns:
+            CharacterSnapshot if cached, None otherwise
+        """
+        return self._character_cache.get(character_id)
+
+    def get_party_snapshots(self) -> list[CharacterSnapshot]:
+        """
+        Get all party members' cached snapshots.
+
+        Returns:
+            List of CharacterSnapshot objects
+        """
+        return [
+            self._character_cache[cid]
+            for cid in self._party_ids
+            if cid in self._character_cache
+        ]
+
+    # =========================================================================
+    # Tool Result Processing
+    # =========================================================================
+
+    async def update_from_tool_calls(
+        self,
+        tool_results: list[dict[str, object]],
+    ) -> None:
+        """
+        Update state based on MCP tool call results.
+
+        Args:
+            tool_results: List of {tool_name, result} dicts
+        """
+        for entry in tool_results:
+            tool_name = str(entry.get("tool_name", ""))
+            result = entry.get("result", {})
+
+            if not isinstance(result, dict):
+                continue
+
+            # Dispatch to appropriate handler
+            if "modify_hp" in tool_name:
+                await self._process_hp_change(result)
+            elif "start_combat" in tool_name:
+                await self._process_combat_start(result)
+            elif "end_combat" in tool_name:
+                await self._process_combat_end(result)
+            elif "next_turn" in tool_name:
+                await self._process_next_turn(result)
+            elif "add_condition" in tool_name:
+                await self._process_condition_change(result, added=True)
+            elif "remove_condition" in tool_name:
+                await self._process_condition_change(result, added=False)
+            elif "rest" in tool_name:
+                await self._process_rest(result)
+
+    async def _process_hp_change(self, result: dict[str, object]) -> None:
+        """Process HP modification result."""
+        character_id = str(result.get("character_id", ""))
+        if not character_id:
+            return
+
+        # Update cache
+        new_hp = int(result.get("new_hp", result.get("current_hp", 0)))
+        max_hp = int(result.get("max_hp", 1))
+        previous_hp = int(result.get("previous_hp", 0))
+
+        if character_id in self._character_cache:
+            snapshot = self._character_cache[character_id]
+            updated_data = snapshot.model_dump()
+            updated_data["hp_current"] = new_hp
+            updated_data["hp_max"] = max_hp
+            updated_data["cached_at"] = datetime.now()
+            self._character_cache[character_id] = CharacterSnapshot.model_validate(
+                updated_data
+            )
+
+        # Check for death
+        if new_hp <= 0 and previous_hp > 0:
+            name = str(result.get("name", "Character"))
+            is_damage = result.get("is_damage", True)
+            if is_damage:
+                self._event_logger.log_damage(
+                    character_name=name,
+                    amount=previous_hp - new_hp,
+                    damage_type=str(result.get("damage_type", "untyped")),
+                    source="unknown",
+                    is_lethal=True,
+                )
+
+            # Update combat state if applicable
+            if self._combat_state:
+                combatant = self._combat_state.get_combatant(character_id)
+                if combatant:
+                    self._combat_state.update_combatant(
+                        character_id,
+                        hp_current=new_hp,
+                        status=CombatantStatus.UNCONSCIOUS,
+                    )
+
+    async def _process_combat_start(self, result: dict[str, object]) -> None:
+        """Process combat start result."""
+        self._in_combat = True
+
+        # Build combatant list
+        combatants: list[Combatant] = []
+        turn_order = result.get("turn_order", [])
+
+        if isinstance(turn_order, list):
+            for i, entry in enumerate(turn_order):
+                if isinstance(entry, dict):
+                    combatants.append(
+                        Combatant(
+                            combatant_id=str(entry.get("id", str(uuid.uuid4()))),
+                            name=str(entry.get("name", f"Combatant {i + 1}")),
+                            initiative=int(entry.get("initiative", 0)),
+                            is_player=bool(entry.get("is_player", False)),
+                            hp_current=int(entry.get("hp_current", 10)),
+                            hp_max=int(entry.get("hp_max", 10)),
+                            armor_class=int(entry.get("ac", 10)),
+                            conditions=list(entry.get("conditions", [])),
+                            status=CombatantStatus.ACTIVE,
+                        )
+                    )
+
+        self._combat_state = CombatState(
+            combat_id=str(result.get("combat_id", str(uuid.uuid4()))),
+            round_number=1,
+            turn_index=0,
+            combatants=combatants,
+            started_at=datetime.now(),
+        )
+
+        # Log event
+        self._event_logger.log_combat_start(
+            description=str(result.get("description", "Combat began!")),
+            combatants=[c.name for c in combatants],
+        )
+
+    async def _process_combat_end(self, result: dict[str, object]) -> None:
+        """Process combat end result."""
+        outcome = str(result.get("outcome", "victory"))
+
+        self._event_logger.log_combat_end(
+            outcome=outcome,
+            description=str(result.get("description", "")),
+        )
+
+        self._in_combat = False
+        self._combat_state = None
+
+    async def _process_next_turn(self, result: dict[str, object]) -> None:
+        """Process next turn result."""
+        if not self._combat_state:
+            return
+
+        # Advance turn
+        new_combatant = self._combat_state.advance_turn()
+
+        if new_combatant:
+            # Update from result if provided
+            turn_index = result.get("turn_index")
+            if isinstance(turn_index, int):
+                self._combat_state.turn_index = turn_index
+
+            round_number = result.get("round_number")
+            if isinstance(round_number, int):
+                self._combat_state.round_number = round_number
+
+    async def _process_condition_change(
+        self,
+        result: dict[str, object],
+        added: bool,
+    ) -> None:
+        """Process condition add/remove result."""
+        character_id = str(result.get("character_id", ""))
+        condition = str(result.get("condition", ""))
+
+        if not character_id or not condition:
+            return
+
+        # Update character cache
+        if character_id in self._character_cache:
+            snapshot = self._character_cache[character_id]
+            conditions = snapshot.conditions.copy()
+
+            if added and condition not in conditions:
+                conditions.append(condition)
+            elif not added and condition in conditions:
+                conditions.remove(condition)
+
+            updated_data = snapshot.model_dump()
+            updated_data["conditions"] = conditions
+            updated_data["cached_at"] = datetime.now()
+            self._character_cache[character_id] = CharacterSnapshot.model_validate(
+                updated_data
+            )
+
+        # Update combat state if applicable
+        if self._combat_state:
+            combatant = self._combat_state.get_combatant(character_id)
+            if combatant:
+                conditions = combatant.conditions.copy()
+                if added and condition not in conditions:
+                    conditions.append(condition)
+                elif not added and condition in conditions:
+                    conditions.remove(condition)
+                self._combat_state.update_combatant(
+                    character_id, conditions=conditions
+                )
+
+    async def _process_rest(self, result: dict[str, object]) -> None:
+        """Process rest result."""
+        character_id = str(result.get("character_id", ""))
+        rest_type = str(result.get("rest_type", "short"))
+        hp_recovered = int(result.get("hp_recovered", 0))
+
+        # Refresh character from MCP
+        if character_id:
+            await self.refresh_character(character_id)
+
+        # Log event
+        name = str(result.get("name", "Character"))
+        self._event_logger.log_rest(
+            rest_type=rest_type,
+            character_name=name,
+            hp_recovered=hp_recovered,
+        )
+
+    # =========================================================================
+    # Event Management
+    # =========================================================================
+
+    def add_event(
+        self,
+        event_type: EventType,
+        description: str,
+        data: dict[str, object] | None = None,
+        is_significant: bool = False,
+    ) -> SessionEvent:
+        """
+        Add a game event.
+
+        Args:
+            event_type: Type of event
+            description: Human-readable description
+            data: Event-specific data
+            is_significant: Whether event is significant
+
+        Returns:
+            Created SessionEvent
+        """
+        return self._event_logger._create_event(
+            event_type=event_type,
+            description=description,
+            data=data,
+            is_significant=is_significant,
+        )
+
+    # =========================================================================
+    # Location Management
+    # =========================================================================
+
+    def set_location(
+        self,
+        location: str,
+        scene: SceneInfo | None = None,
+    ) -> None:
+        """
+        Update the current location.
+
+        Args:
+            location: Location name
+            scene: Optional scene info
+        """
+        old_location = self._current_location
+        self._current_location = location
+        self._current_scene = scene
+
+        # Log movement if location changed
+        if old_location != location and old_location != "Unknown":
+            self._event_logger.log_movement(old_location, location)
+
+    def add_known_npc(self, npc: NPCInfo) -> None:
+        """
+        Add or update a known NPC.
+
+        Args:
+            npc: NPC info to add
+        """
+        self._known_npcs[npc.npc_id] = npc
+
+    def get_npc(self, npc_id: str) -> NPCInfo | None:
+        """
+        Get a known NPC by ID.
+
+        Args:
+            npc_id: NPC ID
+
+        Returns:
+            NPCInfo if found, None otherwise
+        """
+        return self._known_npcs.get(npc_id)
+
+    def get_npcs_in_scene(self) -> list[NPCInfo]:
+        """
+        Get NPCs present in the current scene.
+
+        Returns:
+            List of NPCInfo objects
+        """
+        if not self._current_scene:
+            return []
+
+        return [
+            self._known_npcs[npc_id]
+            for npc_id in self._current_scene.npcs_present
+            if npc_id in self._known_npcs
+        ]
+
+    def set_story_flag(self, flag: str, value: object) -> None:
+        """
+        Set a story/quest flag.
+
+        Args:
+            flag: Flag name
+            value: Flag value
+        """
+        self._story_flags[flag] = value
+
+        # Log significant flags
+        self._event_logger.log_story_flag(flag, value)
+
+    def get_story_flag(self, flag: str, default: object = None) -> object:
+        """
+        Get a story/quest flag.
+
+        Args:
+            flag: Flag name
+            default: Default value
+
+        Returns:
+            Flag value or default
+        """
+        return self._story_flags.get(flag, default)
+
+    # =========================================================================
+    # Turn Management
+    # =========================================================================
+
+    def increment_turn(self) -> int:
+        """
+        Increment the turn counter.
+
+        Returns:
+            New turn count
+        """
+        self._turn_count += 1
+        self._event_logger.set_current_turn(self._turn_count)
+        return self._turn_count
+
+    # =========================================================================
+    # Save/Load
+    # =========================================================================
+
+    async def save(
+        self,
+        file_path: Path | str | None = None,
+        conversation_history: list[dict[str, object]] | None = None,
+    ) -> GameSaveData:
+        """
+        Save the current game state.
+
+        Args:
+            file_path: Optional path to save JSON file
+            conversation_history: Optional chat history to include
+
+        Returns:
+            GameSaveData object
+        """
+        # Refresh all character caches before saving
+        for character_id in self._party_ids:
+            await self.refresh_character(character_id)
+
+        # Build save data
+        save_data = GameSaveData(
+            version="1.0.0",
+            saved_at=datetime.now(),
+            session_id=self._session_id,
+            turn_count=self._turn_count,
+            party_ids=self._party_ids.copy(),
+            active_character_id=self._active_character_id,
+            character_snapshots=list(self._character_cache.values()),
+            current_location=self._current_location,
+            current_scene=self._current_scene,
+            in_combat=self._in_combat,
+            combat_state=self._combat_state,
+            story_flags=self._story_flags.copy(),
+            known_npcs=self._known_npcs.copy(),
+            recent_events=self._event_logger.events.copy(),
+            adventure_name=self._adventure_name,
+            conversation_history=conversation_history or [],
+        )
+
+        # Write to file if path provided
+        if file_path:
+            path = Path(file_path)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(save_data.model_dump_json(indent=2))
+            logger.info(f"Game saved to: {path}")
+
+        return save_data
+
+    async def load(self, file_path: Path | str) -> bool:
+        """
+        Load a saved game.
+
+        Args:
+            file_path: Path to save file
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            path = Path(file_path)
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+
+            save_data = GameSaveData.model_validate(data)
+
+            # Restore state
+            self._session_id = save_data.session_id
+            self._turn_count = save_data.turn_count
+            self._party_ids = save_data.party_ids.copy()
+            self._active_character_id = save_data.active_character_id
+            self._current_location = save_data.current_location
+            self._current_scene = save_data.current_scene
+            self._in_combat = save_data.in_combat
+            self._combat_state = save_data.combat_state
+            self._story_flags = dict(save_data.story_flags)
+            self._known_npcs = dict(save_data.known_npcs)
+            self._adventure_name = save_data.adventure_name
+
+            # Restore character cache
+            self._character_cache.clear()
+            self._character_cache_times.clear()
+            for snapshot in save_data.character_snapshots:
+                self._character_cache[snapshot.character_id] = snapshot
+                self._character_cache_times[snapshot.character_id] = datetime.now()
+
+            # Restore events
+            self._event_logger.clear()
+            for event in save_data.recent_events:
+                self._event_logger._events.append(event)
+            self._event_logger.set_current_turn(self._turn_count)
+
+            # Start new MCP session for loaded game
+            if self._toolkit_client and self._toolkit_client.is_connected:
+                try:
+                    result = await self._toolkit_client.call_tool(
+                        "mcp_start_session",
+                        {
+                            "campaign_name": f"Loaded: {self._adventure_name or 'Session'}",
+                            "system": "dnd5e",
+                        },
+                    )
+                    if isinstance(result, dict):
+                        self._mcp_session_id = str(result.get("session_id", ""))
+                        self._event_logger.set_mcp_session_id(self._mcp_session_id)
+                except Exception as e:
+                    logger.warning(f"Failed to start MCP session for loaded game: {e}")
+
+            # Log event
+            self._event_logger.log_system(
+                "Game loaded",
+                {"loaded_from": str(path)},
+            )
+
+            logger.info(f"Game loaded from: {path}")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to load game: {e}")
+            return False
+
+    def export_for_download(
+        self,
+        conversation_history: list[dict[str, object]] | None = None,
+    ) -> str:
+        """
+        Export game state as JSON string for browser download.
+
+        Args:
+            conversation_history: Optional chat history to include
+
+        Returns:
+            JSON string
+        """
+        save_data = GameSaveData(
+            version="1.0.0",
+            saved_at=datetime.now(),
+            session_id=self._session_id,
+            turn_count=self._turn_count,
+            party_ids=self._party_ids.copy(),
+            active_character_id=self._active_character_id,
+            character_snapshots=list(self._character_cache.values()),
+            current_location=self._current_location,
+            current_scene=self._current_scene,
+            in_combat=self._in_combat,
+            combat_state=self._combat_state,
+            story_flags=self._story_flags.copy(),
+            known_npcs=self._known_npcs.copy(),
+            recent_events=self._event_logger.events.copy(),
+            adventure_name=self._adventure_name,
+            conversation_history=conversation_history or [],
+        )
+
+        return save_data.model_dump_json(indent=2)
+
+    # =========================================================================
+    # Utilities
+    # =========================================================================
+
+    def set_toolkit_client(self, client: TTRPGToolkitClient | None) -> None:
+        """
+        Set or update the toolkit client.
+
+        Args:
+            client: New toolkit client
+        """
+        self._toolkit_client = client
+        self._event_logger.set_toolkit_client(client)
+
+    def to_summary(self) -> dict[str, object]:
+        """
+        Create a summary dict for quick state overview.
+
+        Returns:
+            Summary dict
+        """
+        return {
+            "session_id": self._session_id,
+            "turn_count": self._turn_count,
+            "party_size": len(self._party_ids),
+            "active_character": self._active_character_id,
+            "location": self._current_location,
+            "in_combat": self._in_combat,
+            "combat_round": self._combat_state.round_number
+            if self._combat_state
+            else None,
+            "adventure": self._adventure_name,
+            "event_count": len(self._event_logger),
+        }
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return (
+            f"GameStateManager("
+            f"session={self._session_id[:8]}..., "
+            f"turn={self._turn_count}, "
+            f"party={len(self._party_ids)}, "
+            f"combat={self._in_combat})"
+        )

src/game/models.py

@@ -0,0 +1,774 @@
+"""
+DungeonMaster AI - Game State Models
+
+Pydantic models for game entities including events, combat state,
+characters, NPCs, scenes, and adventure data.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field, computed_field
+
+
+# =============================================================================
+# Enums
+# =============================================================================
+
+
+class EventType(str, Enum):
+    """Types of game events for logging."""
+
+    ROLL = "roll"
+    COMBAT_START = "combat_start"
+    COMBAT_END = "combat_end"
+    COMBAT_ACTION = "combat_action"
+    DAMAGE = "damage"
+    HEALING = "healing"
+    MOVEMENT = "movement"
+    DIALOGUE = "dialogue"
+    DISCOVERY = "discovery"
+    ITEM_ACQUIRED = "item_acquired"
+    REST = "rest"
+    LEVEL_UP = "level_up"
+    DEATH = "death"
+    STORY_FLAG = "story_flag"
+    SYSTEM = "system"
+
+
+class CombatantStatus(str, Enum):
+    """Status of a combatant in combat."""
+
+    ACTIVE = "active"
+    UNCONSCIOUS = "unconscious"
+    DEAD = "dead"
+    FLED = "fled"
+
+
+class HPStatus(str, Enum):
+    """Health status based on HP percentage."""
+
+    HEALTHY = "healthy"  # > 50%
+    WOUNDED = "wounded"  # 25-50%
+    CRITICAL = "critical"  # 1-25%
+    UNCONSCIOUS = "unconscious"  # 0
+
+
+# =============================================================================
+# Event Models
+# =============================================================================
+
+
+class SessionEvent(BaseModel):
+    """
+    A single event in the game session.
+
+    Events are logged for context building and session history.
+    """
+
+    event_id: str = Field(
+        default_factory=lambda: str(uuid.uuid4()),
+        description="Unique event identifier",
+    )
+    event_type: EventType = Field(
+        description="Type of event",
+    )
+    description: str = Field(
+        description="Human-readable event description",
+    )
+    data: dict[str, object] = Field(
+        default_factory=dict,
+        description="Event-specific data",
+    )
+    timestamp: datetime = Field(
+        default_factory=datetime.now,
+        description="When the event occurred",
+    )
+    turn: int = Field(
+        default=0,
+        description="Game turn when event occurred",
+    )
+    is_significant: bool = Field(
+        default=False,
+        description="Whether this event is significant for context",
+    )
+
+
+# =============================================================================
+# Combat Models
+# =============================================================================
+
+
+class Combatant(BaseModel):
+    """
+    A participant in combat.
+
+    Tracks initiative, HP, conditions, and status.
+    """
+
+    combatant_id: str = Field(
+        description="Unique combatant identifier",
+    )
+    name: str = Field(
+        description="Combatant name",
+    )
+    initiative: int = Field(
+        description="Initiative roll result",
+    )
+    is_player: bool = Field(
+        default=False,
+        description="Whether this is a player character",
+    )
+    hp_current: int = Field(
+        default=0,
+        description="Current hit points",
+    )
+    hp_max: int = Field(
+        default=1,
+        description="Maximum hit points",
+    )
+    armor_class: int = Field(
+        default=10,
+        description="Armor class",
+    )
+    conditions: list[str] = Field(
+        default_factory=list,
+        description="Active conditions",
+    )
+    status: CombatantStatus = Field(
+        default=CombatantStatus.ACTIVE,
+        description="Combat status",
+    )
+
+    @computed_field
+    @property
+    def hp_percent(self) -> float:
+        """HP as percentage of max."""
+        if self.hp_max <= 0:
+            return 0.0
+        return (self.hp_current / self.hp_max) * 100.0
+
+    @computed_field
+    @property
+    def hp_status(self) -> HPStatus:
+        """Health status based on HP percentage."""
+        if self.hp_current <= 0:
+            return HPStatus.UNCONSCIOUS
+        pct = self.hp_percent
+        if pct > 50:
+            return HPStatus.HEALTHY
+        if pct > 25:
+            return HPStatus.WOUNDED
+        return HPStatus.CRITICAL
+
+    @computed_field
+    @property
+    def is_bloodied(self) -> bool:
+        """Whether combatant is at 50% HP or below."""
+        return self.hp_percent <= 50.0
+
+
+class CombatState(BaseModel):
+    """
+    State of an active combat encounter.
+
+    Tracks round, turn order, and all combatants.
+    """
+
+    combat_id: str = Field(
+        default_factory=lambda: str(uuid.uuid4()),
+        description="Unique combat identifier",
+    )
+    round_number: int = Field(
+        default=1,
+        description="Current combat round",
+    )
+    turn_index: int = Field(
+        default=0,
+        description="Index of current combatant in turn order",
+    )
+    combatants: list[Combatant] = Field(
+        default_factory=list,
+        description="All combatants in initiative order",
+    )
+    started_at: datetime = Field(
+        default_factory=datetime.now,
+        description="When combat started",
+    )
+
+    @computed_field
+    @property
+    def current_combatant(self) -> Optional[Combatant]:
+        """Get the combatant whose turn it is."""
+        if not self.combatants or self.turn_index >= len(self.combatants):
+            return None
+        return self.combatants[self.turn_index]
+
+    @computed_field
+    @property
+    def turn_order(self) -> list[str]:
+        """List of combatant names in initiative order."""
+        return [c.name for c in self.combatants]
+
+    @computed_field
+    @property
+    def active_combatants(self) -> list[Combatant]:
+        """List of combatants still active in combat."""
+        return [c for c in self.combatants if c.status == CombatantStatus.ACTIVE]
+
+    @computed_field
+    @property
+    def is_player_turn(self) -> bool:
+        """Whether it's currently a player's turn."""
+        current = self.current_combatant
+        return current.is_player if current else False
+
+    def advance_turn(self) -> Optional[Combatant]:
+        """
+        Advance to the next turn, skipping inactive combatants.
+
+        Returns:
+            The new current combatant, or None if combat should end.
+        """
+        if not self.active_combatants:
+            return None
+
+        # Find next active combatant
+        start_index = self.turn_index
+        attempts = 0
+        max_attempts = len(self.combatants)
+
+        while attempts < max_attempts:
+            self.turn_index = (self.turn_index + 1) % len(self.combatants)
+
+            # Check for new round
+            if self.turn_index == 0:
+                self.round_number += 1
+
+            current = self.combatants[self.turn_index]
+            if current.status == CombatantStatus.ACTIVE:
+                return current
+
+            attempts += 1
+
+        return None
+
+    def get_combatant(self, combatant_id: str) -> Optional[Combatant]:
+        """Get a combatant by ID."""
+        for c in self.combatants:
+            if c.combatant_id == combatant_id:
+                return c
+        return None
+
+    def update_combatant(self, combatant_id: str, **updates: object) -> bool:
+        """
+        Update a combatant's attributes.
+
+        Args:
+            combatant_id: ID of combatant to update
+            **updates: Attribute updates
+
+        Returns:
+            True if combatant was found and updated
+        """
+        for i, c in enumerate(self.combatants):
+            if c.combatant_id == combatant_id:
+                updated_data = c.model_dump()
+                updated_data.update(updates)
+                self.combatants[i] = Combatant.model_validate(updated_data)
+                return True
+        return False
+
+
+# =============================================================================
+# Character Models
+# =============================================================================
+
+
+class CharacterSnapshot(BaseModel):
+    """
+    Cached snapshot of character data from MCP.
+
+    Used for quick access without hitting MCP on every request.
+    """
+
+    character_id: str = Field(
+        description="Character ID from MCP",
+    )
+    name: str = Field(
+        description="Character name",
+    )
+    race: str = Field(
+        default="Unknown",
+        description="Character race",
+    )
+    character_class: str = Field(
+        default="Unknown",
+        description="Character class",
+    )
+    level: int = Field(
+        default=1,
+        description="Character level",
+    )
+    hp_current: int = Field(
+        default=0,
+        description="Current hit points",
+    )
+    hp_max: int = Field(
+        default=1,
+        description="Maximum hit points",
+    )
+    armor_class: int = Field(
+        default=10,
+        description="Armor class",
+    )
+    initiative_bonus: int = Field(
+        default=0,
+        description="Initiative modifier",
+    )
+    speed: int = Field(
+        default=30,
+        description="Movement speed in feet",
+    )
+    conditions: list[str] = Field(
+        default_factory=list,
+        description="Active conditions",
+    )
+    ability_scores: dict[str, int] = Field(
+        default_factory=lambda: {
+            "strength": 10,
+            "dexterity": 10,
+            "constitution": 10,
+            "intelligence": 10,
+            "wisdom": 10,
+            "charisma": 10,
+        },
+        description="Ability scores",
+    )
+    proficiency_bonus: int = Field(
+        default=2,
+        description="Proficiency bonus",
+    )
+    cached_at: datetime = Field(
+        default_factory=datetime.now,
+        description="When this snapshot was created",
+    )
+
+    @computed_field
+    @property
+    def hp_percent(self) -> float:
+        """HP as percentage of max."""
+        if self.hp_max <= 0:
+            return 0.0
+        return (self.hp_current / self.hp_max) * 100.0
+
+    @computed_field
+    @property
+    def hp_status(self) -> HPStatus:
+        """Health status based on HP percentage."""
+        if self.hp_current <= 0:
+            return HPStatus.UNCONSCIOUS
+        pct = self.hp_percent
+        if pct > 50:
+            return HPStatus.HEALTHY
+        if pct > 25:
+            return HPStatus.WOUNDED
+        return HPStatus.CRITICAL
+
+    @computed_field
+    @property
+    def is_bloodied(self) -> bool:
+        """Whether character is at 50% HP or below."""
+        return self.hp_percent <= 50.0
+
+    @classmethod
+    def from_mcp_result(cls, data: dict[str, object]) -> CharacterSnapshot:
+        """
+        Create a CharacterSnapshot from MCP get_character result.
+
+        Args:
+            data: Raw result from mcp_get_character
+
+        Returns:
+            CharacterSnapshot instance
+        """
+        # Handle nested character data
+        char_data = data.get("character", data)
+
+        # Extract ability scores
+        ability_scores = {}
+        raw_abilities = char_data.get("ability_scores", {})
+        if isinstance(raw_abilities, dict):
+            for ability in [
+                "strength",
+                "dexterity",
+                "constitution",
+                "intelligence",
+                "wisdom",
+                "charisma",
+            ]:
+                ability_scores[ability] = int(raw_abilities.get(ability, 10))
+        else:
+            ability_scores = {
+                "strength": 10,
+                "dexterity": 10,
+                "constitution": 10,
+                "intelligence": 10,
+                "wisdom": 10,
+                "charisma": 10,
+            }
+
+        return cls(
+            character_id=str(char_data.get("id", "")),
+            name=str(char_data.get("name", "Unknown")),
+            race=str(char_data.get("race", "Unknown")),
+            character_class=str(char_data.get("character_class", "Unknown")),
+            level=int(char_data.get("level", 1)),
+            hp_current=int(char_data.get("current_hp", char_data.get("hp_current", 0))),
+            hp_max=int(char_data.get("max_hp", char_data.get("hp_max", 1))),
+            armor_class=int(char_data.get("armor_class", 10)),
+            initiative_bonus=int(char_data.get("initiative_bonus", 0)),
+            speed=int(char_data.get("speed", 30)),
+            conditions=list(char_data.get("conditions", [])),
+            ability_scores=ability_scores,
+            proficiency_bonus=int(char_data.get("proficiency_bonus", 2)),
+        )
+
+
+# =============================================================================
+# NPC and Scene Models
+# =============================================================================
+
+
+class NPCInfo(BaseModel):
+    """
+    Information about an NPC.
+
+    Includes personality, voice, and dialogue hooks.
+    """
+
+    npc_id: str = Field(
+        description="Unique NPC identifier",
+    )
+    name: str = Field(
+        description="NPC name",
+    )
+    description: str = Field(
+        default="",
+        description="Physical and role description",
+    )
+    personality: str = Field(
+        default="",
+        description="Personality traits",
+    )
+    voice_profile: str = Field(
+        default="dm",
+        description="Voice profile for TTS",
+    )
+    dialogue_hooks: list[str] = Field(
+        default_factory=list,
+        description="Sample dialogue lines",
+    )
+    monster_stat_block: Optional[str] = Field(
+        default=None,
+        description="Monster stat block name if applicable",
+    )
+    relationship: str = Field(
+        default="neutral",
+        description="Relationship to players (friendly, neutral, hostile)",
+    )
+
+
+class SceneInfo(BaseModel):
+    """
+    Information about a location/scene.
+
+    Includes description, sensory details, exits, and present NPCs.
+    """
+
+    scene_id: str = Field(
+        description="Unique scene identifier",
+    )
+    name: str = Field(
+        description="Scene/location name",
+    )
+    description: str = Field(
+        default="",
+        description="Scene description",
+    )
+    sensory_details: dict[str, str] = Field(
+        default_factory=dict,
+        description="Sensory details (sight, sound, smell)",
+    )
+    exits: dict[str, str] = Field(
+        default_factory=dict,
+        description="Available exits (direction -> destination scene_id)",
+    )
+    npcs_present: list[str] = Field(
+        default_factory=list,
+        description="NPC IDs present in scene",
+    )
+    items: list[dict[str, object]] = Field(
+        default_factory=list,
+        description="Items in the scene",
+    )
+    encounter_id: Optional[str] = Field(
+        default=None,
+        description="Encounter ID if scene has combat",
+    )
+    searchable_objects: list[dict[str, object]] = Field(
+        default_factory=list,
+        description="Objects that can be searched/investigated",
+    )
+
+
+# =============================================================================
+# Save/Load Models
+# =============================================================================
+
+
+class GameSaveData(BaseModel):
+    """
+    Complete game state for save/load.
+
+    Includes all state needed to restore a game session.
+    """
+
+    version: str = Field(
+        default="1.0.0",
+        description="Save file version",
+    )
+    saved_at: datetime = Field(
+        default_factory=datetime.now,
+        description="When the game was saved",
+    )
+    session_id: str = Field(
+        description="Game session ID",
+    )
+    turn_count: int = Field(
+        default=0,
+        description="Current turn count",
+    )
+    party_ids: list[str] = Field(
+        default_factory=list,
+        description="Character IDs in party",
+    )
+    active_character_id: Optional[str] = Field(
+        default=None,
+        description="Currently active character ID",
+    )
+    character_snapshots: list[CharacterSnapshot] = Field(
+        default_factory=list,
+        description="Cached character data",
+    )
+    current_location: str = Field(
+        default="Unknown",
+        description="Current location name",
+    )
+    current_scene: Optional[SceneInfo] = Field(
+        default=None,
+        description="Current scene data",
+    )
+    in_combat: bool = Field(
+        default=False,
+        description="Whether combat is active",
+    )
+    combat_state: Optional[CombatState] = Field(
+        default=None,
+        description="Combat state if in combat",
+    )
+    story_flags: dict[str, object] = Field(
+        default_factory=dict,
+        description="Story/quest progress flags",
+    )
+    known_npcs: dict[str, NPCInfo] = Field(
+        default_factory=dict,
+        description="NPCs encountered (id -> info)",
+    )
+    recent_events: list[SessionEvent] = Field(
+        default_factory=list,
+        description="Recent session events",
+    )
+    adventure_name: Optional[str] = Field(
+        default=None,
+        description="Loaded adventure name",
+    )
+    conversation_history: list[dict[str, object]] = Field(
+        default_factory=list,
+        description="Chat history for restoration",
+    )
+
+
+# =============================================================================
+# Adventure Models
+# =============================================================================
+
+
+class AdventureMetadata(BaseModel):
+    """
+    Metadata for an adventure module.
+    """
+
+    name: str = Field(
+        description="Adventure name",
+    )
+    description: str = Field(
+        default="",
+        description="Adventure description",
+    )
+    difficulty: str = Field(
+        default="medium",
+        description="Difficulty level (easy, medium, hard)",
+    )
+    estimated_time: str = Field(
+        default="1-2 hours",
+        description="Estimated play time",
+    )
+    recommended_level: int = Field(
+        default=1,
+        description="Recommended character level",
+    )
+    tags: list[str] = Field(
+        default_factory=list,
+        description="Adventure tags",
+    )
+    author: str = Field(
+        default="DungeonMaster AI",
+        description="Adventure author",
+    )
+    version: str = Field(
+        default="1.0.0",
+        description="Adventure version",
+    )
+
+
+class EncounterData(BaseModel):
+    """
+    Data for a combat encounter.
+    """
+
+    encounter_id: str = Field(
+        description="Unique encounter identifier",
+    )
+    name: str = Field(
+        description="Encounter name",
+    )
+    description: str = Field(
+        default="",
+        description="Encounter description",
+    )
+    enemies: list[dict[str, object]] = Field(
+        default_factory=list,
+        description="Enemy definitions [{monster, count, name?}]",
+    )
+    difficulty: str = Field(
+        default="medium",
+        description="Encounter difficulty",
+    )
+    tactics: str = Field(
+        default="",
+        description="Enemy tactics description",
+    )
+    rewards: dict[str, object] = Field(
+        default_factory=dict,
+        description="Rewards (xp, loot)",
+    )
+
+
+class AdventureData(BaseModel):
+    """
+    Complete adventure data loaded from JSON.
+    """
+
+    metadata: AdventureMetadata = Field(
+        description="Adventure metadata",
+    )
+    starting_scene: dict[str, object] = Field(
+        description="Starting scene configuration",
+    )
+    scenes: list[dict[str, object]] = Field(
+        default_factory=list,
+        description="All scenes in the adventure",
+    )
+    npcs: list[dict[str, object]] = Field(
+        default_factory=list,
+        description="NPC definitions",
+    )
+    encounters: list[EncounterData] = Field(
+        default_factory=list,
+        description="Combat encounters",
+    )
+    loot_tables: list[dict[str, object]] = Field(
+        default_factory=list,
+        description="Loot table definitions",
+    )
+    victory_conditions: dict[str, object] = Field(
+        default_factory=dict,
+        description="Win conditions",
+    )
+    completion_narrative: str = Field(
+        default="",
+        description="Narrative text when adventure is completed",
+    )
+
+    @classmethod
+    def from_json(cls, data: dict[str, object]) -> AdventureData:
+        """
+        Create AdventureData from raw JSON data.
+
+        Args:
+            data: Parsed JSON adventure data
+
+        Returns:
+            AdventureData instance
+        """
+        # Parse metadata
+        metadata_raw = data.get("metadata", {})
+        if isinstance(metadata_raw, dict):
+            metadata = AdventureMetadata.model_validate(metadata_raw)
+        else:
+            metadata = AdventureMetadata(name="Unknown Adventure")
+
+        # Parse encounters
+        encounters_raw = data.get("encounters", [])
+        encounters = []
+        if isinstance(encounters_raw, list):
+            for enc in encounters_raw:
+                if isinstance(enc, dict):
+                    encounters.append(EncounterData.model_validate(enc))
+
+        return cls(
+            metadata=metadata,
+            starting_scene=dict(data.get("starting_scene", {})),
+            scenes=list(data.get("scenes", [])),
+            npcs=list(data.get("npcs", [])),
+            encounters=encounters,
+            loot_tables=list(data.get("loot_tables", [])),
+            victory_conditions=dict(data.get("victory_conditions", {})),
+            completion_narrative=str(data.get("completion_narrative", "")),
+        )
+
+    def get_scene(self, scene_id: str) -> Optional[dict[str, object]]:
+        """Get a scene by ID."""
+        for scene in self.scenes:
+            if isinstance(scene, dict) and scene.get("scene_id") == scene_id:
+                return scene
+        return None
+
+    def get_npc(self, npc_id: str) -> Optional[dict[str, object]]:
+        """Get an NPC by ID."""
+        for npc in self.npcs:
+            if isinstance(npc, dict) and npc.get("npc_id") == npc_id:
+                return npc
+        return None
+
+    def get_encounter(self, encounter_id: str) -> Optional[EncounterData]:
+        """Get an encounter by ID."""
+        for enc in self.encounters:
+            if enc.encounter_id == encounter_id:
+                return enc
+        return None

src/game/story_context.py

@@ -0,0 +1,601 @@
+"""
+DungeonMaster AI - Story Context Builder
+
+Builds formatted context strings for LLM prompts from game state.
+Manages token budgets and prioritizes information for context windows.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from .models import (
+    CombatState,
+    CombatantStatus,
+    CharacterSnapshot,
+    HPStatus,
+    NPCInfo,
+    SceneInfo,
+    SessionEvent,
+)
+
+if TYPE_CHECKING:
+    from .game_state_manager import GameStateManager
+
+logger = logging.getLogger(__name__)
+
+
+class StoryContextBuilder:
+    """
+    Builds LLM context strings from game state.
+
+    Formats party status, combat state, location, recent events,
+    and NPCs into a structured context for the DM agent.
+    Manages token budgets and prioritizes important information.
+    """
+
+    def __init__(
+        self,
+        max_tokens: int = 2000,
+        max_events: int = 10,
+        include_sensory_details: bool = True,
+    ) -> None:
+        """
+        Initialize the context builder.
+
+        Args:
+            max_tokens: Maximum estimated tokens for context
+            max_events: Maximum recent events to include
+            include_sensory_details: Whether to include sensory details
+        """
+        self._max_tokens = max_tokens
+        self._max_events = max_events
+        self._include_sensory = include_sensory_details
+
+    # =========================================================================
+    # Main Context Building
+    # =========================================================================
+
+    def build_full_context(self, manager: GameStateManager) -> str:
+        """
+        Build the complete context string for LLM prompts.
+
+        Args:
+            manager: GameStateManager with current state
+
+        Returns:
+            Formatted context string
+        """
+        sections: list[tuple[str, int]] = []  # (content, priority)
+
+        # Combat section (highest priority if in combat)
+        if manager.in_combat and manager.combat_state:
+            combat_section = self.build_combat_summary(manager.combat_state)
+            sections.append((combat_section, 100))
+
+        # Party section (high priority)
+        party_section = self.build_party_summary(manager)
+        if party_section:
+            sections.append((party_section, 90))
+
+        # Location section
+        location_section = self._build_location_section(manager)
+        if location_section:
+            sections.append((location_section, 70))
+
+        # Recent events section
+        events_section = self._build_events_section(manager)
+        if events_section:
+            sections.append((events_section, 60))
+
+        # NPCs section
+        npcs_section = self._build_npcs_section(manager)
+        if npcs_section:
+            sections.append((npcs_section, 50))
+
+        # Combine sections within token budget
+        return self._combine_sections(sections)
+
+    def _combine_sections(
+        self,
+        sections: list[tuple[str, int]],
+    ) -> str:
+        """
+        Combine sections within token budget.
+
+        Args:
+            sections: List of (content, priority) tuples
+
+        Returns:
+            Combined context string
+        """
+        # Sort by priority (highest first)
+        sections.sort(key=lambda x: x[1], reverse=True)
+
+        result_parts: list[str] = []
+        current_tokens = 0
+
+        for content, priority in sections:
+            section_tokens = self._estimate_tokens(content)
+
+            if current_tokens + section_tokens <= self._max_tokens:
+                result_parts.append(content)
+                current_tokens += section_tokens
+            else:
+                # Try to truncate section to fit
+                remaining_tokens = self._max_tokens - current_tokens
+                if remaining_tokens > 100:  # Worth including something
+                    truncated = self._truncate_to_tokens(content, remaining_tokens)
+                    if truncated:
+                        result_parts.append(truncated)
+                        current_tokens += self._estimate_tokens(truncated)
+                break
+
+        return "\n\n".join(result_parts)
+
+    # =========================================================================
+    # Combat Summary
+    # =========================================================================
+
+    def build_combat_summary(self, combat: CombatState) -> str:
+        """
+        Build a combat state summary.
+
+        Args:
+            combat: Current combat state
+
+        Returns:
+            Formatted combat summary
+        """
+        lines: list[str] = []
+
+        # Header
+        lines.append(f"**COMBAT - Round {combat.round_number}**")
+
+        # Turn order
+        for i, combatant in enumerate(combat.combatants):
+            # Skip dead/fled combatants
+            if combatant.status in (CombatantStatus.DEAD, CombatantStatus.FLED):
+                continue
+
+            # Current turn marker
+            is_current = i == combat.turn_index
+            marker = ">" if is_current else " "
+
+            # Player/Enemy tag
+            tag = "Player" if combatant.is_player else "Enemy"
+
+            # HP status
+            hp_status = self._get_hp_status_string(combatant.hp_current, combatant.hp_max)
+            hp_display = f"{combatant.hp_current}/{combatant.hp_max} HP"
+
+            # Conditions
+            conditions_str = ""
+            if combatant.conditions:
+                conditions_str = f" [{', '.join(combatant.conditions)}]"
+            elif combatant.status == CombatantStatus.UNCONSCIOUS:
+                conditions_str = " [Unconscious]"
+
+            # Status indicator for unconscious
+            status_suffix = ""
+            if combatant.status == CombatantStatus.UNCONSCIOUS:
+                status_suffix = " - DOWN"
+
+            # Build line
+            turn_indicator = " <- Your Turn" if is_current and combatant.is_player else ""
+            line = (
+                f"{marker} {combatant.initiative}: {combatant.name} ({tag}) - "
+                f"{hp_display} [{hp_status}]{conditions_str}{status_suffix}{turn_indicator}"
+            )
+            lines.append(line)
+
+        return "\n".join(lines)
+
+    # =========================================================================
+    # Party Summary
+    # =========================================================================
+
+    def build_party_summary(self, manager: GameStateManager) -> str:
+        """
+        Build a party status summary.
+
+        Args:
+            manager: GameStateManager with party data
+
+        Returns:
+            Formatted party summary
+        """
+        snapshots = manager.get_party_snapshots()
+        if not snapshots:
+            return ""
+
+        lines: list[str] = ["**Party Status:**"]
+
+        for snapshot in snapshots:
+            # Active marker
+            is_active = snapshot.character_id == manager.active_character_id
+            active_marker = " (Active)" if is_active else ""
+
+            # HP status
+            hp_status = self._get_hp_status_string(snapshot.hp_current, snapshot.hp_max)
+            hp_display = f"{snapshot.hp_current}/{snapshot.hp_max} HP"
+
+            # Conditions
+            conditions_str = ""
+            if snapshot.conditions:
+                conditions_str = f" [Conditions: {', '.join(snapshot.conditions)}]"
+
+            # Class and level
+            class_info = f"Lvl {snapshot.level} {snapshot.character_class}"
+
+            line = (
+                f"- {snapshot.name}{active_marker}: {hp_display} [{hp_status}] "
+                f"- {class_info}{conditions_str}"
+            )
+            lines.append(line)
+
+        return "\n".join(lines)
+
+    # =========================================================================
+    # Location Section
+    # =========================================================================
+
+    def _build_location_section(self, manager: GameStateManager) -> str:
+        """
+        Build location/scene section.
+
+        Args:
+            manager: GameStateManager with location data
+
+        Returns:
+            Formatted location section
+        """
+        lines: list[str] = []
+
+        # Location header
+        lines.append(f"**Location: {manager.current_location}**")
+
+        scene = manager.current_scene
+        if scene:
+            # Description
+            if scene.description:
+                lines.append(scene.description)
+
+            # Sensory details (if enabled)
+            if self._include_sensory and scene.sensory_details:
+                sensory_parts: list[str] = []
+                for sense, detail in scene.sensory_details.items():
+                    if detail:
+                        sensory_parts.append(f"*{sense.capitalize()}*: {detail}")
+                if sensory_parts:
+                    lines.append("\n".join(sensory_parts))
+
+            # Exits
+            if scene.exits:
+                exits_str = ", ".join(
+                    f"{direction} to {dest}"
+                    for direction, dest in scene.exits.items()
+                )
+                lines.append(f"*Exits*: {exits_str}")
+
+        return "\n".join(lines)
+
+    # =========================================================================
+    # Events Section
+    # =========================================================================
+
+    def _build_events_section(self, manager: GameStateManager) -> str:
+        """
+        Build recent events section.
+
+        Args:
+            manager: GameStateManager with events
+
+        Returns:
+            Formatted events section
+        """
+        # Get significant events first, then recent
+        events = manager.event_logger.get_recent(
+            count=self._max_events,
+            significant_only=False,
+        )
+
+        if not events:
+            return ""
+
+        # Filter to most relevant
+        significant = [e for e in events if e.is_significant]
+        recent = events[:5]  # Last 5 events
+
+        # Combine, preferring significant
+        to_show: list[SessionEvent] = []
+        seen_ids: set[str] = set()
+
+        for event in significant + recent:
+            if event.event_id not in seen_ids:
+                to_show.append(event)
+                seen_ids.add(event.event_id)
+            if len(to_show) >= self._max_events:
+                break
+
+        if not to_show:
+            return ""
+
+        lines: list[str] = ["**Recent Events:**"]
+        for event in to_show:
+            lines.append(f"- {event.description}")
+
+        return "\n".join(lines)
+
+    # =========================================================================
+    # NPCs Section
+    # =========================================================================
+
+    def _build_npcs_section(self, manager: GameStateManager) -> str:
+        """
+        Build NPCs present section.
+
+        Args:
+            manager: GameStateManager with NPC data
+
+        Returns:
+            Formatted NPCs section
+        """
+        npcs = manager.get_npcs_in_scene()
+        if not npcs:
+            return ""
+
+        lines: list[str] = ["**NPCs Present:**"]
+
+        for npc in npcs:
+            # Name and brief description
+            desc = npc.description[:100] + "..." if len(npc.description) > 100 else npc.description
+            line = f"- {npc.name}: {desc}"
+
+            # Add personality hint if available
+            if npc.personality:
+                personality_short = (
+                    npc.personality[:50] + "..."
+                    if len(npc.personality) > 50
+                    else npc.personality
+                )
+                line += f" ({personality_short})"
+
+            lines.append(line)
+
+        return "\n".join(lines)
+
+    # =========================================================================
+    # Helper Methods
+    # =========================================================================
+
+    def _get_hp_status_string(self, hp_current: int, hp_max: int) -> str:
+        """
+        Get HP status string from current/max HP.
+
+        Args:
+            hp_current: Current HP
+            hp_max: Maximum HP
+
+        Returns:
+            Status string (Healthy, Wounded, Critical, Unconscious)
+        """
+        if hp_current <= 0:
+            return "Unconscious"
+
+        if hp_max <= 0:
+            return "Unknown"
+
+        percent = (hp_current / hp_max) * 100
+
+        if percent > 50:
+            return "Healthy"
+        elif percent > 25:
+            return "Wounded"
+        else:
+            return "Critical"
+
+    def _estimate_tokens(self, text: str) -> int:
+        """
+        Estimate token count for text.
+
+        Uses rough approximation of 4 characters per token.
+
+        Args:
+            text: Text to estimate
+
+        Returns:
+            Estimated token count
+        """
+        return len(text) // 4
+
+    def _truncate_to_tokens(self, text: str, max_tokens: int) -> str:
+        """
+        Truncate text to fit within token budget.
+
+        Args:
+            text: Text to truncate
+            max_tokens: Maximum tokens
+
+        Returns:
+            Truncated text
+        """
+        max_chars = max_tokens * 4
+
+        if len(text) <= max_chars:
+            return text
+
+        # Find a good break point
+        truncated = text[:max_chars]
+
+        # Try to break at a newline
+        last_newline = truncated.rfind("\n")
+        if last_newline > max_chars * 0.5:
+            return truncated[:last_newline]
+
+        # Try to break at a sentence
+        for punct in [".", "!", "?"]:
+            last_punct = truncated.rfind(punct)
+            if last_punct > max_chars * 0.5:
+                return truncated[: last_punct + 1]
+
+        # Just truncate with ellipsis
+        return truncated[:-3] + "..."
+
+    # =========================================================================
+    # Specialized Context Builders
+    # =========================================================================
+
+    def build_combat_context(self, manager: GameStateManager) -> str:
+        """
+        Build context optimized for combat situations.
+
+        Prioritizes combat state, current combatant, and party HP.
+
+        Args:
+            manager: GameStateManager
+
+        Returns:
+            Combat-focused context
+        """
+        if not manager.in_combat or not manager.combat_state:
+            return self.build_full_context(manager)
+
+        sections: list[str] = []
+
+        # Combat state (required)
+        sections.append(self.build_combat_summary(manager.combat_state))
+
+        # Party HP summary
+        party_section = self.build_party_summary(manager)
+        if party_section:
+            sections.append(party_section)
+
+        # Current location (brief)
+        sections.append(f"**Location:** {manager.current_location}")
+
+        return "\n\n".join(sections)
+
+    def build_exploration_context(self, manager: GameStateManager) -> str:
+        """
+        Build context optimized for exploration.
+
+        Prioritizes location details, sensory info, and NPCs.
+
+        Args:
+            manager: GameStateManager
+
+        Returns:
+            Exploration-focused context
+        """
+        sections: list[str] = []
+
+        # Location (detailed)
+        location_section = self._build_location_section(manager)
+        if location_section:
+            sections.append(location_section)
+
+        # NPCs
+        npcs_section = self._build_npcs_section(manager)
+        if npcs_section:
+            sections.append(npcs_section)
+
+        # Party status (brief)
+        party_section = self.build_party_summary(manager)
+        if party_section:
+            sections.append(party_section)
+
+        # Recent events
+        events_section = self._build_events_section(manager)
+        if events_section:
+            sections.append(events_section)
+
+        return "\n\n".join(sections)
+
+    def build_social_context(self, manager: GameStateManager) -> str:
+        """
+        Build context optimized for social encounters.
+
+        Prioritizes NPC information and dialogue history.
+
+        Args:
+            manager: GameStateManager
+
+        Returns:
+            Social-focused context
+        """
+        sections: list[str] = []
+
+        # NPCs (detailed)
+        npcs = manager.get_npcs_in_scene()
+        if npcs:
+            lines: list[str] = ["**NPCs Present:**"]
+            for npc in npcs:
+                lines.append(f"\n**{npc.name}**")
+                if npc.description:
+                    lines.append(npc.description)
+                if npc.personality:
+                    lines.append(f"*Personality*: {npc.personality}")
+                if npc.dialogue_hooks:
+                    lines.append(f"*Might say*: \"{npc.dialogue_hooks[0]}\"")
+            sections.append("\n".join(lines))
+
+        # Location (brief)
+        sections.append(f"**Location:** {manager.current_location}")
+
+        # Recent dialogue events
+        dialogue_events = manager.event_logger.get_recent(
+            count=5,
+            event_type=None,  # Get all, filter below
+        )
+        dialogue_lines: list[str] = ["**Recent Conversation:**"]
+        for event in dialogue_events:
+            if "dialogue" in event.event_type.value.lower():
+                dialogue_lines.append(f"- {event.description}")
+        if len(dialogue_lines) > 1:
+            sections.append("\n".join(dialogue_lines))
+
+        # Party status
+        party_section = self.build_party_summary(manager)
+        if party_section:
+            sections.append(party_section)
+
+        return "\n\n".join(sections)
+
+    def build_minimal_context(self, manager: GameStateManager) -> str:
+        """
+        Build minimal context for token-constrained situations.
+
+        Only includes essential information.
+
+        Args:
+            manager: GameStateManager
+
+        Returns:
+            Minimal context string
+        """
+        parts: list[str] = []
+
+        # Combat status
+        if manager.in_combat and manager.combat_state:
+            current = manager.combat_state.current_combatant
+            if current:
+                parts.append(
+                    f"Combat Round {manager.combat_state.round_number}, "
+                    f"{current.name}'s turn"
+                )
+
+        # Location
+        parts.append(f"Location: {manager.current_location}")
+
+        # Active character HP
+        for snapshot in manager.get_party_snapshots():
+            if snapshot.character_id == manager.active_character_id:
+                parts.append(
+                    f"Active: {snapshot.name} "
+                    f"({snapshot.hp_current}/{snapshot.hp_max} HP)"
+                )
+                break
+
+        return " | ".join(parts)

src/mcp_integration/__init__.py

@@ -0,0 +1,86 @@
+"""
+DungeonMaster AI - MCP Integration Package
+
+Provides connection management, tool wrappers, and graceful degradation
+for the TTRPG-Toolkit MCP server integration.
+
+Usage:
+    ```python
+    from src.mcp_integration import (
+        TTRPGToolkitClient,
+        ConnectionManager,
+        GameAwareTools,
+        TOOL_CATEGORIES,
+    )
+
+    # Create and connect client
+    manager = ConnectionManager()
+    await manager.connect()
+
+    # Get tools for agents
+    all_tools = await manager.get_tools()
+    rules_tools = await manager.get_tools(categories=["rules"])
+
+    # Wrap with game awareness
+    wrapper = GameAwareTools(game_state=state)
+    enhanced_tools = wrapper.wrap_tools(all_tools)
+    ```
+"""
+
+from .connection_manager import ConnectionManager
+from .exceptions import (
+    MCPCircuitBreakerOpenError,
+    MCPConnectionError,
+    MCPIntegrationError,
+    MCPInvalidResponseError,
+    MCPTimeoutError,
+    MCPToolExecutionError,
+    MCPToolNotFoundError,
+    MCPUnavailableError,
+)
+from .fallbacks import FallbackHandler
+from .models import (
+    CircuitBreakerState,
+    CombatantInfo,
+    CombatStateResult,
+    ConnectionState,
+    DiceRollResult,
+    FormattedResult,
+    GameStateProtocol,
+    HPChangeResult,
+    MCPConnectionStatus,
+    RollType,
+)
+from .tool_wrappers import GameAwareTools
+from .toolkit_client import TOOL_CATEGORIES, TTRPGToolkitClient
+
+__all__ = [
+    # Exceptions
+    "MCPIntegrationError",
+    "MCPConnectionError",
+    "MCPTimeoutError",
+    "MCPToolNotFoundError",
+    "MCPToolExecutionError",
+    "MCPUnavailableError",
+    "MCPCircuitBreakerOpenError",
+    "MCPInvalidResponseError",
+    # Models & Enums
+    "ConnectionState",
+    "CircuitBreakerState",
+    "RollType",
+    "GameStateProtocol",
+    "FormattedResult",
+    "DiceRollResult",
+    "HPChangeResult",
+    "CombatantInfo",
+    "CombatStateResult",
+    "MCPConnectionStatus",
+    # Client & Connection
+    "TTRPGToolkitClient",
+    "TOOL_CATEGORIES",
+    "ConnectionManager",
+    # Tool Wrappers
+    "GameAwareTools",
+    # Fallbacks
+    "FallbackHandler",
+]

src/mcp_integration/connection_manager.py

@@ -0,0 +1,565 @@
+"""
+DungeonMaster AI - MCP Connection Manager
+
+Manages MCP connection lifecycle with health checks, automatic reconnection,
+circuit breaker pattern, and graceful degradation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import random
+import time
+from collections.abc import Sequence
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from llama_index.core.tools import FunctionTool
+
+from src.config.settings import get_settings
+
+from .exceptions import (
+    MCPCircuitBreakerOpenError,
+    MCPUnavailableError,
+)
+from .fallbacks import FallbackHandler
+from .models import (
+    CircuitBreakerState,
+    ConnectionState,
+    MCPConnectionStatus,
+)
+from .toolkit_client import TTRPGToolkitClient
+
+if TYPE_CHECKING:
+    from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class CircuitBreaker:
+    """
+    Circuit breaker pattern implementation.
+
+    Prevents repeated calls to a failing service by tracking failures
+    and temporarily rejecting requests when failure threshold is reached.
+
+    States:
+    - CLOSED: Normal operation, requests allowed
+    - OPEN: Too many failures, requests rejected for reset_timeout
+    - HALF_OPEN: Testing if service recovered with a single request
+    """
+
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        reset_timeout: float = 30.0,
+        half_open_max_calls: int = 1,
+    ) -> None:
+        """
+        Initialize circuit breaker.
+
+        Args:
+            failure_threshold: Failures before opening circuit
+            reset_timeout: Seconds to wait before trying again
+            half_open_max_calls: Max calls allowed in half-open state
+        """
+        self.failure_threshold = failure_threshold
+        self.reset_timeout = reset_timeout
+        self.half_open_max_calls = half_open_max_calls
+
+        self._state = CircuitBreakerState.CLOSED
+        self._failure_count = 0
+        self._last_failure_time: float | None = None
+        self._half_open_calls = 0
+
+    @property
+    def state(self) -> CircuitBreakerState:
+        """Get current circuit breaker state."""
+        # Check if we should transition from OPEN to HALF_OPEN
+        if (
+            self._state == CircuitBreakerState.OPEN
+            and self._last_failure_time is not None
+        ):
+            elapsed = time.time() - self._last_failure_time
+            if elapsed >= self.reset_timeout:
+                self._state = CircuitBreakerState.HALF_OPEN
+                self._half_open_calls = 0
+                logger.info("Circuit breaker transitioned to HALF_OPEN")
+
+        return self._state
+
+    @property
+    def is_open(self) -> bool:
+        """Check if circuit is open (rejecting requests)."""
+        return self.state == CircuitBreakerState.OPEN
+
+    @property
+    def time_until_retry(self) -> float | None:
+        """Seconds until retry is allowed, or None if not in OPEN state."""
+        if self._state != CircuitBreakerState.OPEN:
+            return None
+        if self._last_failure_time is None:
+            return None
+        elapsed = time.time() - self._last_failure_time
+        remaining = self.reset_timeout - elapsed
+        return max(0.0, remaining)
+
+    def record_success(self) -> None:
+        """Record a successful call."""
+        if self._state == CircuitBreakerState.HALF_OPEN:
+            # Successful call in half-open means we can close
+            self._state = CircuitBreakerState.CLOSED
+            logger.info("Circuit breaker closed after successful recovery")
+
+        self._failure_count = 0
+        self._last_failure_time = None
+
+    def record_failure(self) -> None:
+        """Record a failed call."""
+        self._failure_count += 1
+        self._last_failure_time = time.time()
+
+        if self._state == CircuitBreakerState.HALF_OPEN:
+            # Failure in half-open means service still failing
+            self._state = CircuitBreakerState.OPEN
+            logger.warning("Circuit breaker reopened after half-open failure")
+        elif self._failure_count >= self.failure_threshold:
+            self._state = CircuitBreakerState.OPEN
+            logger.warning(
+                f"Circuit breaker opened after {self._failure_count} failures"
+            )
+
+    def allow_request(self) -> bool:
+        """
+        Check if a request should be allowed.
+
+        Returns:
+            True if request is allowed, False if should be rejected.
+        """
+        state = self.state  # This may transition OPEN -> HALF_OPEN
+
+        if state == CircuitBreakerState.CLOSED:
+            return True
+
+        if state == CircuitBreakerState.HALF_OPEN:
+            if self._half_open_calls < self.half_open_max_calls:
+                self._half_open_calls += 1
+                return True
+            return False
+
+        # OPEN state
+        return False
+
+    def reset(self) -> None:
+        """Reset circuit breaker to initial state."""
+        self._state = CircuitBreakerState.CLOSED
+        self._failure_count = 0
+        self._last_failure_time = None
+        self._half_open_calls = 0
+
+
+class ConnectionManager:
+    """
+    Manages MCP connection lifecycle with health checks and reconnection.
+
+    Features:
+    - Automatic reconnection with exponential backoff
+    - Circuit breaker to prevent hammering failed server
+    - Health check monitoring
+    - Graceful degradation via FallbackHandler
+    - Connection status tracking
+
+    Example:
+        ```python
+        manager = ConnectionManager()
+        connected = await manager.connect()
+
+        if manager.is_available:
+            tools = await manager.get_tools()
+            result = await manager.execute_tool("roll", {"notation": "1d20"})
+        else:
+            # Fallback handling
+            result = await manager.execute_with_fallback("roll", {"notation": "1d20"})
+        ```
+    """
+
+    def __init__(
+        self,
+        toolkit_client: TTRPGToolkitClient | None = None,
+        max_retries: int | None = None,
+        retry_delay: float | None = None,
+        fallback_handler: FallbackHandler | None = None,
+    ) -> None:
+        """
+        Initialize connection manager.
+
+        Args:
+            toolkit_client: Pre-configured client, or None to create new one
+            max_retries: Max reconnection attempts (default from settings)
+            retry_delay: Base delay between retries (default from settings)
+            fallback_handler: Handler for graceful degradation
+        """
+        settings = get_settings()
+
+        self._client = toolkit_client or TTRPGToolkitClient()
+        self._max_retries: int = max_retries or settings.mcp.mcp_retry_attempts
+        self._retry_delay: float = retry_delay or settings.mcp.mcp_retry_delay
+        self._fallback_handler = fallback_handler or FallbackHandler()
+
+        # Connection state
+        self._state = ConnectionState.DISCONNECTED
+        self._last_successful_call: datetime | None = None
+        self._consecutive_failures = 0
+        self._last_error: str | None = None
+
+        # Circuit breaker
+        self._circuit_breaker = CircuitBreaker(
+            failure_threshold=5,
+            reset_timeout=30.0,
+        )
+
+        # Health check task
+        self._health_check_task: asyncio.Task[None] | None = None
+        self._health_check_interval = 60.0  # seconds
+
+    @property
+    def state(self) -> ConnectionState:
+        """Get current connection state."""
+        return self._state
+
+    @property
+    def is_available(self) -> bool:
+        """Check if MCP is available for use."""
+        return (
+            self._state == ConnectionState.CONNECTED
+            and not self._circuit_breaker.is_open
+        )
+
+    @property
+    def client(self) -> TTRPGToolkitClient:
+        """Get the underlying toolkit client."""
+        return self._client
+
+    def get_status(self) -> MCPConnectionStatus:
+        """Get detailed connection status."""
+        return MCPConnectionStatus(
+            state=self._state,
+            is_available=self.is_available,
+            url=self._client.url,
+            last_successful_call=self._last_successful_call,
+            consecutive_failures=self._consecutive_failures,
+            circuit_breaker_state=self._circuit_breaker.state,
+            tools_count=self._client.tools_count,
+            error_message=self._last_error,
+        )
+
+    async def connect(self) -> bool:
+        """
+        Connect to MCP server with retry logic.
+
+        Returns:
+            True if connection successful, False otherwise.
+        """
+        self._state = ConnectionState.CONNECTING
+        logger.info("Attempting to connect to MCP server...")
+
+        for attempt in range(self._max_retries):
+            try:
+                await self._client.connect()
+                self._state = ConnectionState.CONNECTED
+                self._consecutive_failures = 0
+                self._last_successful_call = datetime.now()
+                self._last_error = None
+                self._circuit_breaker.reset()
+
+                logger.info("Successfully connected to MCP server")
+                return True
+
+            except Exception as e:
+                self._consecutive_failures += 1
+                self._last_error = str(e)
+                logger.warning(
+                    f"Connection attempt {attempt + 1}/{self._max_retries} failed: {e}"
+                )
+
+                if attempt < self._max_retries - 1:
+                    delay = self._calculate_backoff_delay(attempt)
+                    logger.info(f"Retrying in {delay:.2f} seconds...")
+                    await asyncio.sleep(delay)
+
+        self._state = ConnectionState.ERROR
+        logger.error(f"Failed to connect after {self._max_retries} attempts")
+        return False
+
+    async def disconnect(self) -> None:
+        """Disconnect from MCP server."""
+        # Stop health check task if running
+        if self._health_check_task and not self._health_check_task.done():
+            self._health_check_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._health_check_task
+
+        await self._client.disconnect()
+        self._state = ConnectionState.DISCONNECTED
+        logger.info("Disconnected from MCP server")
+
+    async def health_check(self) -> bool:
+        """
+        Perform health check by listing tools.
+
+        Returns:
+            True if healthy, False otherwise.
+        """
+        try:
+            await self._client.list_tool_names()
+            self._last_successful_call = datetime.now()
+            self._consecutive_failures = 0
+            self._circuit_breaker.record_success()
+            return True
+
+        except Exception as e:
+            self._consecutive_failures += 1
+            self._circuit_breaker.record_failure()
+            logger.warning(f"Health check failed: {e}")
+            return False
+
+    async def get_tools(
+        self,
+        categories: Sequence[str] | None = None,
+    ) -> Sequence[FunctionTool]:
+        """
+        Get tools with automatic reconnection on failure.
+
+        Args:
+            categories: Optional list of categories to filter.
+
+        Returns:
+            Sequence of FunctionTool objects.
+
+        Raises:
+            MCPUnavailableError: If MCP is unavailable after reconnection attempt.
+        """
+        if not self.is_available:
+            await self._attempt_reconnect()
+
+        if not self.is_available:
+            raise MCPUnavailableError(
+                "MCP server is unavailable",
+                reason=self._last_error,
+            )
+
+        try:
+            tools: Sequence[FunctionTool]
+            if categories:
+                tools = await self._client.get_tools_by_category(categories)
+            else:
+                tools = await self._client.get_all_tools()
+
+            self._last_successful_call = datetime.now()
+            self._circuit_breaker.record_success()
+            return tools
+
+        except Exception as e:
+            self._circuit_breaker.record_failure()
+            self._last_error = str(e)
+            logger.error(f"Failed to get tools: {e}")
+
+            # Try reconnection
+            if await self._attempt_reconnect():
+                # Retry after reconnection
+                if categories:
+                    return await self._client.get_tools_by_category(categories)
+                return await self._client.get_all_tools()
+
+            raise MCPUnavailableError(
+                "Unable to get tools after reconnection",
+                reason=str(e),
+            ) from e
+
+    async def execute_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+    ) -> Any:
+        """
+        Execute a tool with connection management.
+
+        Args:
+            tool_name: Name of the tool to call.
+            arguments: Tool arguments.
+
+        Returns:
+            Tool result.
+
+        Raises:
+            MCPCircuitBreakerOpenError: If circuit breaker is open.
+            MCPUnavailableError: If MCP is unavailable.
+        """
+        # Check circuit breaker
+        if not self._circuit_breaker.allow_request():
+            retry_after = self._circuit_breaker.time_until_retry
+            raise MCPCircuitBreakerOpenError(retry_after_seconds=retry_after)
+
+        if not self.is_available:
+            await self._attempt_reconnect()
+
+        if not self.is_available:
+            raise MCPUnavailableError(
+                "MCP server is unavailable",
+                reason=self._last_error,
+            )
+
+        try:
+            result = await self._client.call_tool(tool_name, arguments)
+            self._last_successful_call = datetime.now()
+            self._consecutive_failures = 0
+            self._circuit_breaker.record_success()
+            return result
+
+        except Exception as e:
+            self._consecutive_failures += 1
+            self._circuit_breaker.record_failure()
+            self._last_error = str(e)
+            raise
+
+    async def execute_with_fallback(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+    ) -> Any:
+        """
+        Execute tool with automatic fallback on failure.
+
+        If MCP fails and a fallback handler can handle the tool,
+        uses the fallback. Otherwise, raises the original error.
+
+        Args:
+            tool_name: Name of the tool to call.
+            arguments: Tool arguments.
+
+        Returns:
+            Tool result (from MCP or fallback).
+
+        Raises:
+            MCPUnavailableError: If MCP fails and no fallback available.
+        """
+        try:
+            return await self.execute_tool(tool_name, arguments)
+
+        except (MCPUnavailableError, MCPCircuitBreakerOpenError) as e:
+            # Try fallback
+            if self._fallback_handler.can_handle(tool_name):
+                logger.info(f"Using fallback for tool '{tool_name}'")
+                return await self._fallback_handler.handle(tool_name, arguments)
+
+            # No fallback available
+            raise MCPUnavailableError(
+                f"MCP unavailable and no fallback for '{tool_name}'",
+                reason=str(e),
+            ) from e
+
+    async def _attempt_reconnect(self) -> bool:
+        """
+        Attempt reconnection with exponential backoff.
+
+        Returns:
+            True if reconnection successful, False otherwise.
+        """
+        if self._state == ConnectionState.RECONNECTING:
+            # Already reconnecting
+            return False
+
+        self._state = ConnectionState.RECONNECTING
+        logger.info("Attempting to reconnect to MCP server...")
+
+        for attempt in range(self._max_retries):
+            try:
+                await self._client.disconnect()
+                await self._client.connect()
+
+                self._state = ConnectionState.CONNECTED
+                self._consecutive_failures = 0
+                self._last_successful_call = datetime.now()
+                self._circuit_breaker.reset()
+
+                logger.info("Reconnection successful")
+                return True
+
+            except Exception as e:
+                logger.warning(f"Reconnection attempt {attempt + 1} failed: {e}")
+                delay = self._calculate_backoff_delay(attempt)
+                await asyncio.sleep(delay)
+
+        self._state = ConnectionState.ERROR
+        logger.error("All reconnection attempts failed")
+        return False
+
+    def _calculate_backoff_delay(self, attempt: int) -> float:
+        """
+        Calculate delay with exponential backoff and jitter.
+
+        Args:
+            attempt: Current attempt number (0-indexed).
+
+        Returns:
+            Delay in seconds.
+        """
+        # Exponential backoff
+        delay: float = self._retry_delay * (2**attempt)
+
+        # Cap at 30 seconds
+        delay = min(delay, 30.0)
+
+        # Add jitter (10% random variation)
+        jitter: float = delay * 0.1 * random.random()
+        delay += jitter
+
+        return delay
+
+    async def start_health_monitoring(self) -> None:
+        """Start background health check monitoring."""
+        if self._health_check_task and not self._health_check_task.done():
+            logger.warning("Health monitoring already running")
+            return
+
+        self._health_check_task = asyncio.create_task(self._health_check_loop())
+        logger.info("Started health check monitoring")
+
+    async def stop_health_monitoring(self) -> None:
+        """Stop background health check monitoring."""
+        if self._health_check_task and not self._health_check_task.done():
+            self._health_check_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._health_check_task
+            logger.info("Stopped health check monitoring")
+
+    async def _health_check_loop(self) -> None:
+        """Background task for periodic health checks."""
+        while True:
+            try:
+                await asyncio.sleep(self._health_check_interval)
+
+                if self._state == ConnectionState.CONNECTED:
+                    healthy = await self.health_check()
+                    if not healthy:
+                        logger.warning("Health check failed, attempting reconnection")
+                        await self._attempt_reconnect()
+
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Health check loop error: {e}")
+
+    def get_unavailable_message(self) -> str:
+        """Get user-friendly message when MCP is unavailable."""
+        return self._fallback_handler.get_unavailable_message()
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return (
+            f"ConnectionManager(state={self._state.value}, "
+            f"available={self.is_available}, "
+            f"failures={self._consecutive_failures})"
+        )

src/mcp_integration/exceptions.py

@@ -0,0 +1,119 @@
+"""
+DungeonMaster AI - MCP Integration Exceptions
+
+Custom exception hierarchy for clear error handling in MCP operations.
+"""
+
+from __future__ import annotations
+
+
+class MCPIntegrationError(Exception):
+    """Base exception for all MCP integration errors."""
+
+    def __init__(self, message: str = "An MCP integration error occurred") -> None:
+        self.message = message
+        super().__init__(self.message)
+
+
+class MCPConnectionError(MCPIntegrationError):
+    """Raised when connection to MCP server fails."""
+
+    def __init__(
+        self,
+        message: str = "Failed to connect to MCP server",
+        url: str | None = None,
+    ) -> None:
+        self.url = url
+        if url:
+            message = f"{message}: {url}"
+        super().__init__(message)
+
+
+class MCPTimeoutError(MCPIntegrationError):
+    """Raised when an MCP operation times out."""
+
+    def __init__(
+        self,
+        message: str = "MCP operation timed out",
+        timeout_seconds: float | None = None,
+        operation: str | None = None,
+    ) -> None:
+        self.timeout_seconds = timeout_seconds
+        self.operation = operation
+        if timeout_seconds and operation:
+            message = f"{message}: {operation} after {timeout_seconds}s"
+        elif timeout_seconds:
+            message = f"{message} after {timeout_seconds}s"
+        super().__init__(message)
+
+
+class MCPToolNotFoundError(MCPIntegrationError):
+    """Raised when a requested tool does not exist."""
+
+    def __init__(self, tool_name: str) -> None:
+        self.tool_name = tool_name
+        super().__init__(f"Tool not found: {tool_name}")
+
+
+class MCPToolExecutionError(MCPIntegrationError):
+    """Raised when tool execution fails."""
+
+    def __init__(
+        self,
+        tool_name: str,
+        original_error: Exception | None = None,
+        message: str | None = None,
+    ) -> None:
+        self.tool_name = tool_name
+        self.original_error = original_error
+        if message:
+            error_msg = message
+        elif original_error:
+            error_msg = f"Tool '{tool_name}' execution failed: {original_error}"
+        else:
+            error_msg = f"Tool '{tool_name}' execution failed"
+        super().__init__(error_msg)
+
+
+class MCPUnavailableError(MCPIntegrationError):
+    """Raised when the MCP server is unavailable."""
+
+    def __init__(
+        self,
+        message: str = "MCP server is currently unavailable",
+        reason: str | None = None,
+    ) -> None:
+        self.reason = reason
+        if reason:
+            message = f"{message}: {reason}"
+        super().__init__(message)
+
+
+class MCPCircuitBreakerOpenError(MCPIntegrationError):
+    """Raised when the circuit breaker is open and rejecting requests."""
+
+    def __init__(
+        self,
+        message: str = "Circuit breaker is open - too many recent failures",
+        retry_after_seconds: float | None = None,
+    ) -> None:
+        self.retry_after_seconds = retry_after_seconds
+        if retry_after_seconds:
+            message = f"{message}. Retry after {retry_after_seconds:.1f}s"
+        super().__init__(message)
+
+
+class MCPInvalidResponseError(MCPIntegrationError):
+    """Raised when MCP server returns an invalid or unexpected response."""
+
+    def __init__(
+        self,
+        message: str = "Invalid response from MCP server",
+        tool_name: str | None = None,
+        response: object | None = None,
+    ) -> None:
+        self.tool_name = tool_name
+        self.response = response
+        if tool_name:
+            message = f"{message} for tool '{tool_name}'"
+        super().__init__(message)

src/mcp_integration/fallbacks.py

@@ -0,0 +1,360 @@
+"""
+DungeonMaster AI - MCP Fallback Handlers
+
+Provides fallback functionality when MCP server is unavailable.
+Local dice rolling ensures basic gameplay can continue.
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+import re
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+class FallbackHandler:
+    """
+    Provides fallback functionality when MCP server is unavailable.
+
+    Currently supports:
+    - Basic dice rolling (roll, roll_check)
+
+    Future fallbacks could include:
+    - Cached monster/spell data
+    - Basic character stat lookups
+    """
+
+    # Tools that have fallback implementations
+    SUPPORTED_TOOLS: set[str] = {"roll", "roll_check", "mcp_roll", "mcp_roll_check"}
+
+    # Regex for parsing dice notation
+    # Matches: 2d6, 1d20+5, 4d6-2, d8, 2d10+3
+    DICE_PATTERN = re.compile(
+        r"^(\d*)d(\d+)([+-]\d+)?$",
+        re.IGNORECASE,
+    )
+
+    # Advanced dice notation (keep highest/lowest)
+    # Matches: 4d6kh3, 2d20kl1
+    ADVANCED_DICE_PATTERN = re.compile(
+        r"^(\d+)d(\d+)(k[hl])(\d+)?([+-]\d+)?$",
+        re.IGNORECASE,
+    )
+
+    def can_handle(self, tool_name: str) -> bool:
+        """Check if a fallback exists for this tool."""
+        return tool_name in self.SUPPORTED_TOOLS
+
+    def get_unavailable_message(self) -> str:
+        """User-friendly message about limited functionality."""
+        return (
+            "The game server is temporarily unavailable. "
+            "Some features like rules lookup and character management are limited, "
+            "but basic dice rolling still works."
+        )
+
+    async def handle_roll(
+        self,
+        notation: str,
+        reason: str | None = None,
+        secret: bool = False,
+    ) -> dict[str, object]:
+        """
+        Local dice rolling fallback.
+
+        Supports:
+        - Basic: 2d6, 1d20+5, d8
+        - Keep highest: 4d6kh3 (roll 4d6, keep highest 3)
+        - Keep lowest: 2d20kl1 (disadvantage)
+
+        Args:
+            notation: Dice notation string
+            reason: Optional reason for the roll
+            secret: Whether this is a secret roll (not shown to players)
+
+        Returns:
+            Result dict compatible with MCP roll tool format
+        """
+        notation = notation.strip().lower()
+        timestamp = datetime.now().isoformat()
+
+        # Try advanced notation first (keep highest/lowest)
+        advanced_match = self.ADVANCED_DICE_PATTERN.match(notation)
+        if advanced_match:
+            return self._roll_advanced(
+                advanced_match,
+                notation,
+                reason,
+                secret,
+                timestamp,
+            )
+
+        # Try basic notation
+        basic_match = self.DICE_PATTERN.match(notation)
+        if basic_match:
+            return self._roll_basic(
+                basic_match,
+                notation,
+                reason,
+                secret,
+                timestamp,
+            )
+
+        # Invalid notation
+        logger.warning(f"Invalid dice notation in fallback: {notation}")
+        return {
+            "success": False,
+            "error": f"Invalid dice notation: {notation}",
+            "degraded_mode": True,
+        }
+
+    def _roll_basic(
+        self,
+        match: re.Match[str],
+        notation: str,
+        reason: str | None,
+        secret: bool,
+        timestamp: str,
+    ) -> dict[str, object]:
+        """Handle basic dice notation like 2d6+3."""
+        num_dice = int(match.group(1)) if match.group(1) else 1
+        die_size = int(match.group(2))
+        modifier = int(match.group(3)) if match.group(3) else 0
+
+        # Sanity checks
+        if num_dice < 1 or num_dice > 100:
+            return {
+                "success": False,
+                "error": f"Invalid number of dice: {num_dice} (must be 1-100)",
+                "degraded_mode": True,
+            }
+        if die_size < 2 or die_size > 100:
+            return {
+                "success": False,
+                "error": f"Invalid die size: d{die_size} (must be d2-d100)",
+                "degraded_mode": True,
+            }
+
+        # Roll the dice
+        rolls = [random.randint(1, die_size) for _ in range(num_dice)]
+        total = sum(rolls) + modifier
+
+        # Build breakdown string
+        if modifier > 0:
+            breakdown = f"[{', '.join(map(str, rolls))}] + {modifier}"
+        elif modifier < 0:
+            breakdown = f"[{', '.join(map(str, rolls))}] - {abs(modifier)}"
+        else:
+            breakdown = f"[{', '.join(map(str, rolls))}]"
+
+        return {
+            "success": True,
+            "notation": notation,
+            "total": total,
+            "rolls": rolls,
+            "dice": rolls,  # Alias for compatibility
+            "individual_rolls": rolls,  # Another alias
+            "modifier": modifier,
+            "breakdown": breakdown,
+            "formatted": f"{notation} = {breakdown} = {total}",
+            "reason": reason or "",
+            "secret": secret,
+            "timestamp": timestamp,
+            "degraded_mode": True,
+        }
+
+    def _roll_advanced(
+        self,
+        match: re.Match[str],
+        notation: str,
+        reason: str | None,
+        secret: bool,
+        timestamp: str,
+    ) -> dict[str, object]:
+        """Handle advanced dice notation like 4d6kh3."""
+        num_dice = int(match.group(1))
+        die_size = int(match.group(2))
+        keep_type = match.group(3).lower()  # kh or kl
+        keep_count = int(match.group(4)) if match.group(4) else 1
+        modifier = int(match.group(5)) if match.group(5) else 0
+
+        # Sanity checks
+        if num_dice < 1 or num_dice > 100:
+            return {
+                "success": False,
+                "error": f"Invalid number of dice: {num_dice}",
+                "degraded_mode": True,
+            }
+        if keep_count > num_dice:
+            return {
+                "success": False,
+                "error": f"Cannot keep {keep_count} dice from {num_dice} rolled",
+                "degraded_mode": True,
+            }
+
+        # Roll all dice
+        rolls = [random.randint(1, die_size) for _ in range(num_dice)]
+
+        # Keep highest or lowest
+        sorted_rolls = sorted(rolls, reverse=(keep_type == "kh"))
+        kept_rolls = sorted_rolls[:keep_count]
+        dropped_rolls = sorted_rolls[keep_count:]
+
+        total = sum(kept_rolls) + modifier
+
+        # Build breakdown string
+        kept_str = f"[{', '.join(map(str, kept_rolls))}]"
+        dropped_str = f" (dropped: {', '.join(map(str, dropped_rolls))})" if dropped_rolls else ""
+
+        if modifier > 0:
+            breakdown = f"{kept_str}{dropped_str} + {modifier}"
+        elif modifier < 0:
+            breakdown = f"{kept_str}{dropped_str} - {abs(modifier)}"
+        else:
+            breakdown = f"{kept_str}{dropped_str}"
+
+        return {
+            "success": True,
+            "notation": notation,
+            "total": total,
+            "rolls": rolls,
+            "dice": rolls,
+            "individual_rolls": rolls,
+            "kept_rolls": kept_rolls,
+            "dropped_rolls": dropped_rolls,
+            "modifier": modifier,
+            "breakdown": breakdown,
+            "formatted": f"{notation} = {breakdown} = {total}",
+            "reason": reason or "",
+            "secret": secret,
+            "timestamp": timestamp,
+            "degraded_mode": True,
+        }
+
+    async def handle_roll_check(
+        self,
+        modifier: int = 0,
+        dc: int | None = None,
+        advantage: bool = False,
+        disadvantage: bool = False,
+        skill_name: str | None = None,
+    ) -> dict[str, object]:
+        """
+        Local ability check/save fallback.
+
+        Rolls 1d20 with modifier, handles advantage/disadvantage.
+
+        Args:
+            modifier: Modifier to add to the roll
+            dc: Difficulty class to check against
+            advantage: Roll with advantage (2d20 keep highest)
+            disadvantage: Roll with disadvantage (2d20 keep lowest)
+            skill_name: Name of skill/ability for logging
+
+        Returns:
+            Result dict compatible with MCP roll_check format
+        """
+        timestamp = datetime.now().isoformat()
+
+        # Roll d20(s)
+        if advantage and not disadvantage:
+            rolls = [random.randint(1, 20), random.randint(1, 20)]
+            d20_result = max(rolls)
+            roll_type = "advantage"
+        elif disadvantage and not advantage:
+            rolls = [random.randint(1, 20), random.randint(1, 20)]
+            d20_result = min(rolls)
+            roll_type = "disadvantage"
+        else:
+            rolls = [random.randint(1, 20)]
+            d20_result = rolls[0]
+            roll_type = "normal"
+
+        total = d20_result + modifier
+
+        # Check success/failure
+        success = None
+        result_str = ""
+        if dc is not None:
+            success = total >= dc
+            result_str = "SUCCESS" if success else "FAILURE"
+
+        # Build breakdown
+        if len(rolls) > 1:
+            rolls_str = f"[{rolls[0]}, {rolls[1]}] → {d20_result}"
+        else:
+            rolls_str = str(d20_result)
+
+        if modifier >= 0:
+            breakdown = f"{rolls_str} + {modifier}"
+        else:
+            breakdown = f"{rolls_str} - {abs(modifier)}"
+
+        # Build formatted string
+        skill_part = f" ({skill_name})" if skill_name else ""
+        dc_part = f" vs DC {dc}" if dc is not None else ""
+        result_part = f" - {result_str}" if result_str else ""
+        formatted = f"d20{skill_part} = {breakdown} = {total}{dc_part}{result_part}"
+
+        return {
+            "success": True,
+            "total": total,
+            "d20_result": d20_result,
+            "rolls": rolls,
+            "modifier": modifier,
+            "dc": dc,
+            "check_success": success,
+            "result": result_str.lower() if result_str else None,
+            "roll_type": roll_type,
+            "is_critical": d20_result == 20,
+            "is_fumble": d20_result == 1,
+            "skill_name": skill_name,
+            "breakdown": breakdown,
+            "formatted": formatted,
+            "timestamp": timestamp,
+            "degraded_mode": True,
+        }
+
+    async def handle(
+        self,
+        tool_name: str,
+        arguments: dict[str, object],
+    ) -> dict[str, object]:
+        """
+        Route a tool call to the appropriate fallback handler.
+
+        Args:
+            tool_name: Name of the tool
+            arguments: Tool arguments
+
+        Returns:
+            Fallback result or error dict
+        """
+        # Normalize tool name (remove mcp_ prefix if present)
+        normalized_name = tool_name.replace("mcp_", "")
+
+        if normalized_name == "roll":
+            reason_val = arguments.get("reason")
+            return await self.handle_roll(
+                notation=str(arguments.get("notation", "1d20")),
+                reason=str(reason_val) if reason_val else None,
+                secret=bool(arguments.get("secret", False)),
+            )
+        elif normalized_name == "roll_check":
+            dc_val = arguments.get("dc")
+            return await self.handle_roll_check(
+                modifier=int(str(arguments.get("modifier", 0))),
+                dc=int(str(dc_val)) if dc_val is not None else None,
+                advantage=bool(arguments.get("advantage", False)),
+                disadvantage=bool(arguments.get("disadvantage", False)),
+                skill_name=str(arguments.get("skill_name")) if arguments.get("skill_name") else None,
+            )
+        else:
+            return {
+                "success": False,
+                "error": f"No fallback available for tool: {tool_name}",
+                "degraded_mode": True,
+            }

src/mcp_integration/models.py

@@ -0,0 +1,335 @@
+"""
+DungeonMaster AI - MCP Integration Models
+
+Pydantic models for enhanced tool results and protocols for game state access.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, Field
+
+
+class ConnectionState(str, Enum):
+    """Connection state for MCP server."""
+
+    DISCONNECTED = "disconnected"
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    ERROR = "error"
+    RECONNECTING = "reconnecting"
+
+
+class CircuitBreakerState(str, Enum):
+    """Circuit breaker states for connection management."""
+
+    CLOSED = "closed"  # Normal operation
+    OPEN = "open"  # Rejecting requests due to failures
+    HALF_OPEN = "half_open"  # Testing if service recovered
+
+
+class RollType(str, Enum):
+    """Types of dice rolls for formatting."""
+
+    STANDARD = "standard"
+    ATTACK = "attack"
+    DAMAGE = "damage"
+    SAVE = "save"
+    CHECK = "check"
+    INITIATIVE = "initiative"
+
+
+# =============================================================================
+# Protocols for loose coupling
+# =============================================================================
+
+
+@runtime_checkable
+class GameStateProtocol(Protocol):
+    """
+    Protocol for game state access.
+
+    This interface allows tool wrappers to update game state without
+    depending on the full GameState implementation (coming in Phase 4).
+    """
+
+    session_id: str
+    in_combat: bool
+    party: list[str]
+    recent_events: list[dict[str, object]]
+
+    def add_event(
+        self,
+        event_type: str,
+        description: str,
+        data: dict[str, object],
+    ) -> None:
+        """Add an event to recent events."""
+        ...
+
+    def get_character(self, character_id: str) -> dict[str, object] | None:
+        """Get character data from cache."""
+        ...
+
+    def update_character_cache(
+        self,
+        character_id: str,
+        data: dict[str, object],
+    ) -> None:
+        """Update character data in cache."""
+        ...
+
+    def set_combat_state(self, combat_state: dict[str, object] | None) -> None:
+        """Set or clear combat state."""
+        ...
+
+
+# =============================================================================
+# Base Result Models
+# =============================================================================
+
+
+class FormattedResult(BaseModel):
+    """
+    Base class for formatted tool results.
+
+    All tool wrappers return results in this format to provide
+    multiple output formats for different consumers.
+    """
+
+    raw_result: dict[str, object] = Field(
+        default_factory=dict,
+        description="Original MCP tool result",
+    )
+    chat_display: str = Field(
+        default="",
+        description="Markdown formatted for chat display",
+    )
+    ui_data: dict[str, object] = Field(
+        default_factory=dict,
+        description="Structured data for UI components",
+    )
+    voice_narration: str = Field(
+        default="",
+        description="TTS-friendly plain text for voice narration",
+    )
+
+    # Side effect tracking
+    state_updated: bool = Field(
+        default=False,
+        description="Whether game state was updated",
+    )
+    events_logged: list[str] = Field(
+        default_factory=list,
+        description="List of event types logged to session",
+    )
+    ui_updates_needed: list[str] = Field(
+        default_factory=list,
+        description="UI components that need refresh",
+    )
+
+
+# =============================================================================
+# Dice Roll Models
+# =============================================================================
+
+
+class DiceRollResult(FormattedResult):
+    """Enhanced dice roll result with game context."""
+
+    notation: str = Field(
+        default="",
+        description="Dice notation (e.g., '2d6+3')",
+    )
+    individual_rolls: list[int] = Field(
+        default_factory=list,
+        description="Individual dice results",
+    )
+    modifier: int = Field(
+        default=0,
+        description="Modifier applied to roll",
+    )
+    total: int = Field(
+        default=0,
+        description="Total roll result",
+    )
+    roll_type: RollType = Field(
+        default=RollType.STANDARD,
+        description="Type of roll for context",
+    )
+    is_critical: bool = Field(
+        default=False,
+        description="Natural 20 on d20",
+    )
+    is_fumble: bool = Field(
+        default=False,
+        description="Natural 1 on d20",
+    )
+    success: bool | None = Field(
+        default=None,
+        description="Success/failure for checks with DC",
+    )
+    dc: int | None = Field(
+        default=None,
+        description="Difficulty class if applicable",
+    )
+    reason: str = Field(
+        default="",
+        description="Reason for the roll",
+    )
+    timestamp: datetime = Field(
+        default_factory=datetime.now,
+        description="When the roll occurred",
+    )
+
+
+# =============================================================================
+# HP Change Models
+# =============================================================================
+
+
+class HPChangeResult(FormattedResult):
+    """Enhanced HP modification result with death handling."""
+
+    character_id: str = Field(
+        default="",
+        description="Character ID",
+    )
+    character_name: str = Field(
+        default="Unknown",
+        description="Character name for display",
+    )
+    previous_hp: int = Field(
+        default=0,
+        description="HP before modification",
+    )
+    current_hp: int = Field(
+        default=0,
+        description="HP after modification",
+    )
+    max_hp: int = Field(
+        default=1,
+        description="Maximum HP",
+    )
+    change_amount: int = Field(
+        default=0,
+        description="Absolute value of HP change",
+    )
+    is_damage: bool = Field(
+        default=False,
+        description="True if damage, False if healing",
+    )
+    damage_type: str | None = Field(
+        default=None,
+        description="Type of damage if applicable",
+    )
+    is_unconscious: bool = Field(
+        default=False,
+        description="Character is at 0 HP or below",
+    )
+    requires_death_save: bool = Field(
+        default=False,
+        description="Character needs to make death saves",
+    )
+    is_dead: bool = Field(
+        default=False,
+        description="Character died (massive damage)",
+    )
+    is_bloodied: bool = Field(
+        default=False,
+        description="Character is at 50% HP or below",
+    )
+
+
+# =============================================================================
+# Combat State Models
+# =============================================================================
+
+
+class CombatantInfo(BaseModel):
+    """Information about a combatant in initiative order."""
+
+    id: str = Field(description="Combatant ID")
+    name: str = Field(description="Combatant name")
+    initiative: int = Field(description="Initiative roll result")
+    is_player: bool = Field(default=False, description="Is this a player character")
+    is_current: bool = Field(default=False, description="Is it this combatant's turn")
+    hp_current: int = Field(default=0, description="Current HP")
+    hp_max: int = Field(default=1, description="Maximum HP")
+    hp_percent: float = Field(default=100.0, description="HP percentage")
+    conditions: list[str] = Field(default_factory=list, description="Active conditions")
+    status: str = Field(default="healthy", description="Status string")
+
+
+class CombatStateResult(FormattedResult):
+    """Enhanced combat state result."""
+
+    action: str = Field(
+        default="",
+        description="Combat action: start, end, next_turn, etc.",
+    )
+    round_number: int | None = Field(
+        default=None,
+        description="Current combat round",
+    )
+    current_combatant: str | None = Field(
+        default=None,
+        description="Name of current combatant",
+    )
+    current_combatant_is_player: bool = Field(
+        default=False,
+        description="Whether current combatant is a player",
+    )
+    turn_order: list[CombatantInfo] = Field(
+        default_factory=list,
+        description="Initiative order with combatant info",
+    )
+    combat_ended: bool = Field(
+        default=False,
+        description="Whether combat has ended",
+    )
+
+
+# =============================================================================
+# Connection Status Model
+# =============================================================================
+
+
+class MCPConnectionStatus(BaseModel):
+    """Status information for MCP connection."""
+
+    state: ConnectionState = Field(
+        default=ConnectionState.DISCONNECTED,
+        description="Current connection state",
+    )
+    is_available: bool = Field(
+        default=False,
+        description="Whether MCP is available for use",
+    )
+    url: str = Field(
+        default="",
+        description="MCP server URL",
+    )
+    last_successful_call: datetime | None = Field(
+        default=None,
+        description="When the last successful call was made",
+    )
+    consecutive_failures: int = Field(
+        default=0,
+        description="Number of consecutive failures",
+    )
+    circuit_breaker_state: CircuitBreakerState = Field(
+        default=CircuitBreakerState.CLOSED,
+        description="Circuit breaker state",
+    )
+    tools_count: int = Field(
+        default=0,
+        description="Number of available tools",
+    )
+    error_message: str | None = Field(
+        default=None,
+        description="Last error message if any",
+    )

src/mcp_integration/tool_wrappers.py

@@ -0,0 +1,1003 @@
+"""
+DungeonMaster AI - Game-Aware Tool Wrappers
+
+Wraps MCP tools with game state awareness and side effects.
+Provides enhanced results formatted for chat, UI, and voice.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import Awaitable, Callable, Sequence
+from datetime import datetime
+from functools import wraps
+from typing import TYPE_CHECKING
+
+from llama_index.core.tools import FunctionTool
+
+from src.utils.formatters import (
+    format_dice_roll,
+    format_hp_change,
+    format_initiative_order,
+)
+
+from .models import (
+    CombatantInfo,
+    CombatStateResult,
+    DiceRollResult,
+    FormattedResult,
+    GameStateProtocol,
+    HPChangeResult,
+    RollType,
+)
+
+if TYPE_CHECKING:
+    from typing import Any
+
+    from .toolkit_client import TTRPGToolkitClient
+
+logger = logging.getLogger(__name__)
+
+
+# Type aliases for callbacks
+SessionLogger = Callable[[str, str, dict[str, object]], Awaitable[None]]
+UINotifier = Callable[[str, dict[str, object]], None]
+
+
+# =============================================================================
+# Voice Formatting Helpers
+# =============================================================================
+
+
+def format_roll_for_voice(
+    total: int,
+    roll_type: RollType,
+    is_critical: bool = False,
+    is_fumble: bool = False,
+    success: bool | None = None,
+    skill_name: str | None = None,
+) -> str:
+    """
+    Format dice roll for TTS narration.
+
+    Args:
+        total: Roll total
+        roll_type: Type of roll
+        is_critical: Natural 20
+        is_fumble: Natural 1
+        success: Success/failure for checks
+        skill_name: Name of skill if applicable
+
+    Returns:
+        TTS-friendly text
+    """
+    # Critical/fumble announcements
+    if is_critical:
+        return f"Natural twenty! Critical success with a total of {total}!"
+    if is_fumble:
+        return "Natural one. Critical failure."
+
+    # Base narration by roll type
+    skill_part = f" for {skill_name}" if skill_name else ""
+
+    templates = {
+        RollType.ATTACK: f"Attack roll{skill_part}, {total}.",
+        RollType.DAMAGE: f"{total} points of damage.",
+        RollType.SAVE: f"Saving throw{skill_part}, {total}.",
+        RollType.CHECK: f"Ability check{skill_part}, you rolled a {total}.",
+        RollType.INITIATIVE: f"Initiative, {total}.",
+        RollType.STANDARD: f"You rolled {total}.",
+    }
+
+    base = templates.get(roll_type, f"Result: {total}")
+
+    # Add success/failure
+    if success is not None:
+        base += " Success!" if success else " Failed."
+
+    return base
+
+
+def format_hp_for_voice(
+    character_name: str,
+    change_amount: int,
+    current_hp: int,
+    max_hp: int,
+    is_damage: bool,
+    is_unconscious: bool = False,
+    is_dead: bool = False,
+) -> str:
+    """
+    Format HP change for TTS narration.
+
+    Args:
+        character_name: Name of character
+        change_amount: Absolute value of HP change
+        current_hp: HP after change
+        max_hp: Maximum HP
+        is_damage: True if damage, False if healing
+        is_unconscious: Character is at 0 HP
+        is_dead: Character died from massive damage
+
+    Returns:
+        TTS-friendly text
+    """
+    if is_dead:
+        return f"{character_name} is slain by massive damage!"
+
+    if is_unconscious and is_damage:
+        return f"{character_name} takes {change_amount} damage and falls unconscious!"
+
+    if is_damage:
+        if current_hp <= max_hp // 4:
+            return f"{character_name} takes {change_amount} damage and is badly wounded!"
+        return f"{character_name} takes {change_amount} damage."
+
+    # Healing
+    if current_hp >= max_hp:
+        return f"{character_name} is fully healed!"
+    return f"{character_name} recovers {change_amount} hit points."
+
+
+def format_combat_turn_for_voice(
+    combatant_name: str,
+    is_player: bool,
+    round_number: int,
+) -> str:
+    """
+    Format combat turn announcement for TTS.
+
+    Args:
+        combatant_name: Name of current combatant
+        is_player: Whether combatant is a player character
+        round_number: Current round number
+
+    Returns:
+        TTS-friendly text
+    """
+    if is_player:
+        return f"Round {round_number}. It's your turn, {combatant_name}. What do you do?"
+    return f"{combatant_name} takes their turn."
+
+
+# =============================================================================
+# Roll Type Detection
+# =============================================================================
+
+
+def detect_roll_type(
+    _tool_name: str,
+    arguments: dict[str, object],
+    result: dict[str, object],
+) -> RollType:
+    """
+    Detect the type of roll from context.
+
+    Args:
+        tool_name: Name of the tool called
+        arguments: Tool arguments
+        result: Tool result
+
+    Returns:
+        Detected RollType
+    """
+    # Check explicit roll_type in arguments
+    if "roll_type" in arguments:
+        try:
+            return RollType(arguments["roll_type"])
+        except ValueError:
+            pass
+
+    # Check check_type in result (from roll_check)
+    check_type = str(result.get("check_type", "")).lower()
+    if "attack" in check_type:
+        return RollType.ATTACK
+    if "save" in check_type or "saving" in check_type:
+        return RollType.SAVE
+    if "initiative" in check_type:
+        return RollType.INITIATIVE
+
+    # Check reason field for hints
+    reason = str(arguments.get("reason", "")).lower()
+    if "attack" in reason:
+        return RollType.ATTACK
+    if "damage" in reason:
+        return RollType.DAMAGE
+    if "save" in reason or "saving" in reason:
+        return RollType.SAVE
+    if "check" in reason or "ability" in reason:
+        return RollType.CHECK
+    if "initiative" in reason:
+        return RollType.INITIATIVE
+
+    return RollType.STANDARD
+
+
+# =============================================================================
+# Game Aware Tools Wrapper Class
+# =============================================================================
+
+
+class GameAwareTools:
+    """
+    Wraps MCP tools with game state awareness and side effects.
+
+    This class enhances raw MCP tools to:
+    1. Automatically log actions to the game session
+    2. Update game state after tool calls
+    3. Format results for chat, UI, and voice
+    4. Trigger appropriate UI updates
+    5. Handle special game logic (death saves, combat transitions)
+
+    Example:
+        ```python
+        # Get raw tools from MCP
+        raw_tools = await toolkit_client.get_all_tools()
+
+        # Wrap with game awareness
+        wrapper = GameAwareTools(
+            game_state=game_state,
+            toolkit_client=toolkit_client,
+            session_logger=log_session_event,
+            ui_notifier=notify_ui,
+        )
+        enhanced_tools = wrapper.wrap_tools(raw_tools)
+
+        # Use with LlamaIndex agent
+        agent = FunctionAgent(tools=enhanced_tools, ...)
+        ```
+    """
+
+    # Tool name sets for category detection
+    ROLL_TOOLS = {"roll", "roll_check", "roll_table", "mcp_roll", "mcp_roll_check"}
+    HP_TOOLS = {"modify_hp", "mcp_modify_hp"}
+    COMBAT_START_TOOLS = {"start_combat", "mcp_start_combat"}
+    COMBAT_END_TOOLS = {"end_combat", "mcp_end_combat"}
+    COMBAT_TURN_TOOLS = {"next_turn", "mcp_next_turn"}
+
+    def __init__(
+        self,
+        game_state: GameStateProtocol | None = None,
+        toolkit_client: TTRPGToolkitClient | None = None,
+        session_logger: SessionLogger | None = None,
+        ui_notifier: UINotifier | None = None,
+    ) -> None:
+        """
+        Initialize GameAwareTools.
+
+        Args:
+            game_state: Reference to game state for updates (optional)
+            toolkit_client: MCP toolkit client for additional calls (optional)
+            session_logger: Async callback for logging events to session
+            ui_notifier: Callback for notifying UI of changes
+        """
+        self._game_state = game_state
+        self._toolkit_client = toolkit_client
+        self._session_logger = session_logger
+        self._ui_notifier = ui_notifier
+
+    async def _safe_call_logger(
+        self,
+        event_type: str,
+        description: str,
+        data: dict[str, object],
+    ) -> None:
+        """
+        Safely call session logger, handling both sync and async callbacks.
+
+        This method ensures the logger is called correctly regardless of whether
+        it returns an awaitable or not, preventing "NoneType can't be used in
+        'await' expression" errors.
+        """
+        if not self._session_logger:
+            return
+        try:
+            result = self._session_logger(event_type, description, data)
+            if inspect.isawaitable(result):
+                await result
+        except Exception as e:
+            logger.warning(f"Session logger call failed: {e}")
+
+    def wrap_tools(
+        self,
+        tools: Sequence[FunctionTool],
+    ) -> list[FunctionTool]:
+        """
+        Wrap a list of MCP tools with game-aware enhancements.
+
+        Args:
+            tools: List of raw MCP FunctionTools
+
+        Returns:
+            List of enhanced FunctionTools
+        """
+        wrapped_tools = []
+
+        for tool in tools:
+            tool_name = tool.metadata.name or ""
+            normalized_name = tool_name.replace("mcp_", "")
+
+            # Select appropriate wrapper based on tool category
+            if tool_name in self.ROLL_TOOLS or normalized_name in self.ROLL_TOOLS:
+                wrapped = self._wrap_roll_tool(tool)
+            elif tool_name in self.HP_TOOLS or normalized_name in self.HP_TOOLS:
+                wrapped = self._wrap_hp_tool(tool)
+            elif (
+                tool_name in self.COMBAT_START_TOOLS
+                or normalized_name in self.COMBAT_START_TOOLS
+            ):
+                wrapped = self._wrap_combat_start_tool(tool)
+            elif (
+                tool_name in self.COMBAT_END_TOOLS
+                or normalized_name in self.COMBAT_END_TOOLS
+            ):
+                wrapped = self._wrap_combat_end_tool(tool)
+            elif (
+                tool_name in self.COMBAT_TURN_TOOLS
+                or normalized_name in self.COMBAT_TURN_TOOLS
+            ):
+                wrapped = self._wrap_combat_turn_tool(tool)
+            else:
+                wrapped = self._wrap_generic(tool)
+
+            wrapped_tools.append(wrapped)
+
+        logger.debug(f"Wrapped {len(wrapped_tools)} tools with game awareness")
+        return wrapped_tools
+
+    def _wrap_roll_tool(self, tool: FunctionTool) -> FunctionTool:
+        """Wrap dice rolling tool with game-aware enhancements."""
+        original_fn = tool.async_fn if tool.async_fn is not None else tool.fn
+
+        @wraps(original_fn)
+        async def wrapped_roll(**kwargs: Any) -> DiceRollResult:
+            # Call original tool
+            if tool.async_fn is not None:
+                raw_result = await tool.async_fn(**kwargs)
+            else:
+                raw_result = tool.fn(**kwargs)
+
+            # Extract result dict
+            result_dict = self._extract_result_dict(raw_result)
+
+            # Detect roll type
+            roll_type = detect_roll_type(tool.metadata.name or "", kwargs, result_dict)
+
+            # Extract roll data
+            notation = str(result_dict.get("notation", kwargs.get("notation", "")))
+            rolls = result_dict.get("rolls", result_dict.get("dice", []))
+            if not isinstance(rolls, list):
+                rolls = []
+            modifier = int(str(result_dict.get("modifier", 0)))
+            total = int(str(result_dict.get("total", 0)))
+            dc = result_dict.get("dc")
+            success = result_dict.get("success", result_dict.get("check_success"))
+
+            # Check for crits (d20 only)
+            is_d20 = "d20" in notation.lower() or roll_type in (
+                RollType.ATTACK,
+                RollType.SAVE,
+                RollType.CHECK,
+            )
+            is_critical = is_d20 and len(rolls) >= 1 and 20 in rolls
+            is_fumble = is_d20 and len(rolls) >= 1 and 1 in rolls and 20 not in rolls
+
+            # Format for display
+            chat_display = format_dice_roll(
+                notation=notation,
+                individual_rolls=rolls,
+                modifier=modifier,
+                total=total,
+                is_check=roll_type in (RollType.CHECK, RollType.SAVE),
+                dc=int(str(dc)) if dc is not None else None,
+                success=bool(success) if success is not None else None,
+            )
+
+            # Format for UI
+            ui_data = {
+                "notation": notation,
+                "rolls": rolls,
+                "modifier": modifier,
+                "total": total,
+                "roll_type": roll_type.value,
+                "is_critical": is_critical,
+                "is_fumble": is_fumble,
+                "success": success,
+                "dc": dc,
+                "timestamp": datetime.now().isoformat(),
+            }
+
+            # Format for voice
+            voice_narration = format_roll_for_voice(
+                total=total,
+                roll_type=roll_type,
+                is_critical=is_critical,
+                is_fumble=is_fumble,
+                success=bool(success) if success is not None else None,
+                skill_name=kwargs.get("skill_name"),
+            )
+
+            # Create enhanced result
+            enhanced_result = DiceRollResult(
+                raw_result=result_dict,
+                chat_display=chat_display,
+                ui_data=ui_data,
+                voice_narration=voice_narration,
+                notation=notation,
+                individual_rolls=rolls,
+                modifier=modifier,
+                total=total,
+                roll_type=roll_type,
+                is_critical=is_critical,
+                is_fumble=is_fumble,
+                success=bool(success) if success is not None else None,
+                dc=int(str(dc)) if dc is not None else None,
+                reason=str(kwargs.get("reason", "")),
+                ui_updates_needed=["dice_panel", "roll_history"],
+            )
+
+            # Side effects
+            await self._log_roll_event(enhanced_result, kwargs)
+            self._add_roll_to_game_state(enhanced_result)
+
+            return enhanced_result
+
+        return FunctionTool.from_defaults(
+            async_fn=wrapped_roll,
+            name=tool.metadata.name,
+            description=tool.metadata.description,
+        )
+
+    def _wrap_hp_tool(self, tool: FunctionTool) -> FunctionTool:
+        """Wrap HP modification tool with death handling."""
+        original_fn = tool.async_fn if tool.async_fn is not None else tool.fn
+
+        @wraps(original_fn)
+        async def wrapped_modify_hp(**kwargs: Any) -> HPChangeResult:
+            # Get character ID and amount
+            character_id = str(kwargs.get("character_id", ""))
+            amount = int(kwargs.get("amount", 0))
+            damage_type = kwargs.get("damage_type")
+
+            # Get previous HP from cache if available
+            prev_hp = 0
+            max_hp = 1
+            char_name = "Unknown"
+
+            if self._game_state:
+                char_data = self._game_state.get_character(character_id)
+                if char_data:
+                    hp_data = char_data.get("hit_points")
+                    if isinstance(hp_data, dict):
+                        prev_hp = int(str(hp_data.get("current", 0)))
+                        max_hp = int(str(hp_data.get("maximum", 1)))
+                    char_name = str(char_data.get("name", "Unknown"))
+
+            # Call original tool
+            if tool.async_fn is not None:
+                raw_result = await tool.async_fn(**kwargs)
+            else:
+                raw_result = tool.fn(**kwargs)
+
+            result_dict = self._extract_result_dict(raw_result)
+
+            # Get new HP from result
+            current_hp_val = result_dict.get(
+                "current_hp", result_dict.get("new_hp", prev_hp + amount)
+            )
+            current_hp = int(str(current_hp_val))
+            if "max_hp" in result_dict:
+                max_hp = int(str(result_dict["max_hp"]))
+            if "character_name" in result_dict:
+                char_name = str(result_dict["character_name"])
+
+            is_damage = amount < 0
+            change_amount = abs(amount)
+
+            # Death checks
+            is_unconscious = current_hp <= 0
+            requires_death_save = is_unconscious and prev_hp > 0 and is_damage
+            is_dead = is_damage and current_hp <= -max_hp  # Massive damage
+
+            # Bloodied check (50% HP)
+            is_bloodied = 0 < current_hp <= max_hp // 2
+
+            # Format for display
+            chat_display = format_hp_change(
+                character_name=char_name,
+                previous_hp=prev_hp,
+                current_hp=max(0, current_hp),
+                max_hp=max_hp,
+                is_damage=is_damage,
+            )
+
+            if is_dead:
+                chat_display += (
+                    "\n**DEATH!** Massive damage has killed the character instantly!"
+                )
+            elif requires_death_save:
+                chat_display += "\n*Death saving throws begin next turn.*"
+
+            # Format for UI
+            ui_data = {
+                "character_id": character_id,
+                "character_name": char_name,
+                "hp_previous": prev_hp,
+                "hp_current": current_hp,
+                "hp_max": max_hp,
+                "hp_percent": (max(0, current_hp) / max_hp * 100) if max_hp > 0 else 0,
+                "is_unconscious": is_unconscious,
+                "is_bloodied": is_bloodied,
+                "is_critical": 0 < current_hp <= max_hp // 4,
+                "is_dead": is_dead,
+            }
+
+            # Format for voice
+            voice_narration = format_hp_for_voice(
+                character_name=char_name,
+                change_amount=change_amount,
+                current_hp=max(0, current_hp),
+                max_hp=max_hp,
+                is_damage=is_damage,
+                is_unconscious=is_unconscious,
+                is_dead=is_dead,
+            )
+
+            # Create enhanced result
+            ui_updates = ["character_sheet"]
+            if self._game_state and self._game_state.in_combat:
+                ui_updates.append("combat_tracker")
+
+            enhanced_result = HPChangeResult(
+                raw_result=result_dict,
+                chat_display=chat_display,
+                ui_data=ui_data,
+                voice_narration=voice_narration,
+                character_id=character_id,
+                character_name=char_name,
+                previous_hp=prev_hp,
+                current_hp=current_hp,
+                max_hp=max_hp,
+                change_amount=change_amount,
+                is_damage=is_damage,
+                damage_type=str(damage_type) if damage_type else None,
+                is_unconscious=is_unconscious,
+                requires_death_save=requires_death_save,
+                is_dead=is_dead,
+                is_bloodied=is_bloodied,
+                ui_updates_needed=ui_updates,
+            )
+
+            # Side effects
+            await self._log_hp_event(enhanced_result)
+            self._update_character_hp(enhanced_result)
+
+            return enhanced_result
+
+        return FunctionTool.from_defaults(
+            async_fn=wrapped_modify_hp,
+            name=tool.metadata.name,
+            description=tool.metadata.description,
+        )
+
+    def _wrap_combat_start_tool(self, tool: FunctionTool) -> FunctionTool:
+        """Wrap combat start tool."""
+        original_fn = tool.async_fn if tool.async_fn is not None else tool.fn
+
+        @wraps(original_fn)
+        async def wrapped_start_combat(**kwargs: Any) -> CombatStateResult:
+            # Call original tool
+            if tool.async_fn is not None:
+                raw_result = await tool.async_fn(**kwargs)
+            else:
+                raw_result = tool.fn(**kwargs)
+
+            result_dict = self._extract_result_dict(raw_result)
+
+            # Extract combat state
+            turn_order_raw = result_dict.get("turn_order", [])
+            turn_order: list[object] = list(turn_order_raw) if isinstance(turn_order_raw, list) else []
+            current_idx = int(str(result_dict.get("current_turn_index", 0)))
+            round_num = int(str(result_dict.get("round", 1)))
+
+            # Build combatant info list
+            combatants: list[CombatantInfo] = []
+            for i, combatant in enumerate(turn_order):
+                if isinstance(combatant, dict):
+                    hp_curr = int(str(combatant.get("hp_current", 0)))
+                    hp_max = int(str(combatant.get("hp_max", 1)))
+                    combatants.append(
+                        CombatantInfo(
+                            id=str(combatant.get("id", f"combatant_{i}")),
+                            name=str(combatant.get("name", f"Combatant {i + 1}")),
+                            initiative=int(str(combatant.get("initiative", 0))),
+                            is_player=bool(combatant.get("is_player", False)),
+                            is_current=i == current_idx,
+                            hp_current=hp_curr,
+                            hp_max=hp_max,
+                            hp_percent=(hp_curr / hp_max * 100) if hp_max > 0 else 0,
+                            conditions=list(combatant.get("conditions", [])),
+                            status=self._get_hp_status(hp_curr, hp_max),
+                        )
+                    )
+
+            current_combatant = (
+                combatants[current_idx].name if combatants else "Unknown"
+            )
+            is_player = combatants[current_idx].is_player if combatants else False
+
+            # Format for display
+            chat_display = "**Combat Begins!**\n\n"
+            if combatants:
+                chat_display += format_initiative_order(
+                    [c.model_dump() for c in combatants],
+                    current_idx,
+                )
+
+            # Format for UI
+            ui_data = {
+                "round": round_num,
+                "combatants": [c.model_dump() for c in combatants],
+                "current_combatant_name": current_combatant,
+                "combat_started": True,
+            }
+
+            # Format for voice
+            voice_narration = (
+                f"Roll for initiative! Combat begins. "
+                f"{current_combatant} goes first."
+            )
+
+            enhanced_result = CombatStateResult(
+                raw_result=result_dict,
+                chat_display=chat_display,
+                ui_data=ui_data,
+                voice_narration=voice_narration,
+                action="start",
+                round_number=round_num,
+                current_combatant=current_combatant,
+                current_combatant_is_player=is_player,
+                turn_order=combatants,
+                ui_updates_needed=["combat_tracker"],
+                state_updated=True,
+            )
+
+            # Side effects
+            if self._game_state:
+                self._game_state.set_combat_state(result_dict)
+
+            if self._ui_notifier:
+                self._ui_notifier("show_combat_tracker", ui_data)
+
+            await self._log_combat_event("combat_start", result_dict)
+
+            return enhanced_result
+
+        return FunctionTool.from_defaults(
+            async_fn=wrapped_start_combat,
+            name=tool.metadata.name,
+            description=tool.metadata.description,
+        )
+
+    def _wrap_combat_end_tool(self, tool: FunctionTool) -> FunctionTool:
+        """Wrap combat end tool."""
+        original_fn = tool.async_fn if tool.async_fn is not None else tool.fn
+
+        @wraps(original_fn)
+        async def wrapped_end_combat(**kwargs: Any) -> CombatStateResult:
+            # Call original tool
+            if tool.async_fn is not None:
+                raw_result = await tool.async_fn(**kwargs)
+            else:
+                raw_result = tool.fn(**kwargs)
+
+            result_dict = self._extract_result_dict(raw_result)
+
+            # Format for display
+            chat_display = "**Combat Ends!**\n\n*The dust settles...*"
+
+            # Format for UI
+            ui_data: dict[str, object] = {"combat_ended": True}
+
+            # Format for voice
+            voice_narration = "The battle is over."
+
+            enhanced_result = CombatStateResult(
+                raw_result=result_dict,
+                chat_display=chat_display,
+                ui_data=ui_data,
+                voice_narration=voice_narration,
+                action="end",
+                combat_ended=True,
+                ui_updates_needed=["combat_tracker"],
+                state_updated=True,
+            )
+
+            # Side effects
+            if self._game_state:
+                self._game_state.set_combat_state(None)
+
+            if self._ui_notifier:
+                self._ui_notifier("hide_combat_tracker", {})
+
+            await self._log_combat_event("combat_end", result_dict)
+
+            return enhanced_result
+
+        return FunctionTool.from_defaults(
+            async_fn=wrapped_end_combat,
+            name=tool.metadata.name,
+            description=tool.metadata.description,
+        )
+
+    def _wrap_combat_turn_tool(self, tool: FunctionTool) -> FunctionTool:
+        """Wrap next turn tool."""
+        original_fn = tool.async_fn if tool.async_fn is not None else tool.fn
+
+        @wraps(original_fn)
+        async def wrapped_next_turn(**kwargs: Any) -> CombatStateResult:
+            # Call original tool
+            if tool.async_fn is not None:
+                raw_result = await tool.async_fn(**kwargs)
+            else:
+                raw_result = tool.fn(**kwargs)
+
+            result_dict = self._extract_result_dict(raw_result)
+
+            # Extract updated combat state
+            turn_order_raw = result_dict.get("turn_order", [])
+            turn_order: list[object] = list(turn_order_raw) if isinstance(turn_order_raw, list) else []
+            current_idx = int(str(result_dict.get("current_turn_index", 0)))
+            round_num = int(str(result_dict.get("round", 1)))
+
+            # Build combatant info
+            combatants: list[CombatantInfo] = []
+            for i, combatant in enumerate(turn_order):
+                if isinstance(combatant, dict):
+                    hp_curr = int(str(combatant.get("hp_current", 0)))
+                    hp_max = int(str(combatant.get("hp_max", 1)))
+                    combatants.append(
+                        CombatantInfo(
+                            id=str(combatant.get("id", f"combatant_{i}")),
+                            name=str(combatant.get("name", f"Combatant {i + 1}")),
+                            initiative=int(str(combatant.get("initiative", 0))),
+                            is_player=bool(combatant.get("is_player", False)),
+                            is_current=i == current_idx,
+                            hp_current=hp_curr,
+                            hp_max=hp_max,
+                            hp_percent=(hp_curr / hp_max * 100) if hp_max > 0 else 0,
+                            conditions=list(combatant.get("conditions", [])),
+                            status=self._get_hp_status(hp_curr, hp_max),
+                        )
+                    )
+
+            current_combatant = (
+                combatants[current_idx].name if combatants else "Unknown"
+            )
+            is_player = combatants[current_idx].is_player if combatants else False
+
+            # Format for display
+            chat_display = format_initiative_order(
+                [c.model_dump() for c in combatants],
+                current_idx,
+            )
+
+            # Format for UI
+            ui_data = {
+                "round": round_num,
+                "combatants": [c.model_dump() for c in combatants],
+                "current_combatant_name": current_combatant,
+            }
+
+            # Format for voice
+            voice_narration = format_combat_turn_for_voice(
+                combatant_name=current_combatant,
+                is_player=is_player,
+                round_number=round_num,
+            )
+
+            enhanced_result = CombatStateResult(
+                raw_result=result_dict,
+                chat_display=chat_display,
+                ui_data=ui_data,
+                voice_narration=voice_narration,
+                action="next_turn",
+                round_number=round_num,
+                current_combatant=current_combatant,
+                current_combatant_is_player=is_player,
+                turn_order=combatants,
+                ui_updates_needed=["combat_tracker"],
+                state_updated=True,
+            )
+
+            # Side effects
+            if self._game_state:
+                self._game_state.set_combat_state(result_dict)
+
+            return enhanced_result
+
+        return FunctionTool.from_defaults(
+            async_fn=wrapped_next_turn,
+            name=tool.metadata.name,
+            description=tool.metadata.description,
+        )
+
+    def _wrap_generic(self, tool: FunctionTool) -> FunctionTool:
+        """
+        Generic wrapper for tools that don't need special handling.
+        Still adds basic logging.
+        """
+        original_fn = tool.async_fn if tool.async_fn is not None else tool.fn
+
+        @wraps(original_fn)
+        async def wrapped_generic(**kwargs: Any) -> FormattedResult:
+            # Call original tool
+            if tool.async_fn is not None:
+                raw_result = await tool.async_fn(**kwargs)
+            else:
+                raw_result = tool.fn(**kwargs)
+
+            result_dict = self._extract_result_dict(raw_result)
+
+            # Create basic formatted result
+            result = FormattedResult(
+                raw_result=result_dict,
+                chat_display=str(result_dict.get("formatted", str(raw_result))),
+                ui_data=result_dict,
+                voice_narration="",
+            )
+
+            # Log generic tool call
+            await self._safe_call_logger(
+                "tool_call",
+                f"Called {tool.metadata.name}",
+                {"tool": tool.metadata.name, "args": kwargs},
+            )
+
+            return result
+
+        return FunctionTool.from_defaults(
+            async_fn=wrapped_generic,
+            name=tool.metadata.name,
+            description=tool.metadata.description,
+        )
+
+    # =============================================================================
+    # Helper Methods
+    # =============================================================================
+
+    def _extract_result_dict(self, raw_result: Any) -> dict[str, object]:
+        """Extract dict from various result types."""
+        if isinstance(raw_result, dict):
+            return raw_result
+
+        # Handle ToolOutput
+        if hasattr(raw_result, "raw_output"):
+            output = raw_result.raw_output
+            if isinstance(output, dict):
+                return output
+            return {"result": output}
+
+        # Handle Pydantic models
+        if hasattr(raw_result, "model_dump"):
+            dumped = raw_result.model_dump()
+            if isinstance(dumped, dict):
+                return dumped
+            return {"result": dumped}
+
+        return {"result": raw_result}
+
+    def _get_hp_status(self, hp_current: int, hp_max: int) -> str:
+        """Get status string from HP values."""
+        if hp_current <= 0:
+            return "down"
+        if hp_current <= hp_max // 4:
+            return "critical"
+        if hp_current <= hp_max // 2:
+            return "wounded"
+        return "healthy"
+
+    async def _log_roll_event(
+        self,
+        result: DiceRollResult,
+        kwargs: dict[str, Any],
+    ) -> None:
+        """Log roll event to session."""
+        event_data = {
+            "notation": result.notation,
+            "total": result.total,
+            "rolls": result.individual_rolls,
+            "roll_type": result.roll_type.value,
+            "reason": kwargs.get("reason", ""),
+        }
+        if result.is_critical:
+            event_data["critical"] = True
+        if result.is_fumble:
+            event_data["fumble"] = True
+
+        await self._safe_call_logger(
+            "dice_roll",
+            f"Rolled {result.notation} = {result.total}",
+            event_data,
+        )
+        result.events_logged.append("dice_roll")
+
+    def _add_roll_to_game_state(self, result: DiceRollResult) -> None:
+        """Add roll to game state recent events."""
+        if not self._game_state:
+            return
+
+        self._game_state.add_event(
+            event_type="roll",
+            description=f"Roll: {result.notation} = {result.total}",
+            data={
+                "notation": result.notation,
+                "total": result.total,
+                "roll_type": result.roll_type.value,
+                "is_critical": result.is_critical,
+                "is_fumble": result.is_fumble,
+            },
+        )
+        result.state_updated = True
+
+    async def _log_hp_event(self, result: HPChangeResult) -> None:
+        """Log HP change event to session."""
+        event_type = "damage" if result.is_damage else "healing"
+        description = (
+            f"{result.character_name}: "
+            f"{result.previous_hp} -> {result.current_hp} HP"
+        )
+
+        await self._safe_call_logger(
+            event_type,
+            description,
+            {
+                "character_id": result.character_id,
+                "change": -result.change_amount
+                if result.is_damage
+                else result.change_amount,
+                "is_unconscious": result.is_unconscious,
+                "is_dead": result.is_dead,
+            },
+        )
+        result.events_logged.append(event_type)
+
+    def _update_character_hp(self, result: HPChangeResult) -> None:
+        """Update character HP in game state cache."""
+        if not self._game_state:
+            return
+
+        # Update cache
+        char_data = self._game_state.get_character(result.character_id)
+        if char_data:
+            hp_data = char_data.get("hit_points")
+            if not isinstance(hp_data, dict):
+                hp_data = {}
+                char_data["hit_points"] = hp_data
+            hp_data["current"] = result.current_hp
+            self._game_state.update_character_cache(result.character_id, char_data)
+
+        # Log event
+        self._game_state.add_event(
+            event_type="hp_change",
+            description=(
+                f"{result.character_name} "
+                f"{'takes' if result.is_damage else 'heals'} "
+                f"{result.change_amount}"
+            ),
+            data=result.ui_data,
+        )
+        result.state_updated = True
+
+    async def _log_combat_event(
+        self,
+        event_type: str,
+        data: dict[str, object],
+    ) -> None:
+        """Log combat event to session."""
+        await self._safe_call_logger(
+            event_type,
+            f"Combat {event_type.replace('combat_', '')}",
+            data,
+        )

src/mcp_integration/toolkit_client.py

@@ -0,0 +1,520 @@
+"""
+DungeonMaster AI - TTRPG Toolkit MCP Client
+
+Core client for connecting to the TTRPG-Toolkit MCP server.
+Uses llama-index-tools-mcp for connection management and tool conversion.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from llama_index.core.tools import FunctionTool
+from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
+
+from src.config.settings import get_settings
+
+from .exceptions import (
+    MCPConnectionError,
+    MCPToolExecutionError,
+    MCPToolNotFoundError,
+)
+
+if TYPE_CHECKING:
+    from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Tool Category Mapping
+# =============================================================================
+
+TOOL_CATEGORIES: dict[str, list[str]] = {
+    "dice": [
+        "roll",
+        "roll_check",
+        "roll_table",
+        "get_roll_statistics",
+        # MCP prefixed versions
+        "mcp_roll",
+        "mcp_roll_check",
+        "mcp_roll_table",
+        "mcp_get_roll_statistics",
+    ],
+    "character": [
+        "create_character",
+        "get_character",
+        "modify_hp",
+        "rest",
+        "generate_ability_scores",
+        "add_condition",
+        "remove_condition",
+        "update_character",
+        "level_up",
+        "add_item",
+        "remove_item",
+        # MCP prefixed versions
+        "mcp_create_character",
+        "mcp_get_character",
+        "mcp_modify_hp",
+        "mcp_rest",
+        "mcp_generate_ability_scores",
+        "mcp_add_condition",
+        "mcp_remove_condition",
+    ],
+    "rules": [
+        "search_rules",
+        "get_monster",
+        "search_monsters",
+        "get_spell",
+        "search_spells",
+        "get_class_info",
+        "get_race_info",
+        "get_item",
+        "get_condition",
+        # MCP prefixed versions
+        "mcp_search_rules",
+        "mcp_get_monster",
+        "mcp_search_monsters",
+        "mcp_get_spell",
+        "mcp_search_spells",
+        "mcp_get_class_info",
+        "mcp_get_race_info",
+    ],
+    "generators": [
+        "generate_name",
+        "generate_npc",
+        "generate_encounter",
+        "generate_loot",
+        "generate_location",
+        # MCP prefixed versions
+        "mcp_generate_name",
+        "mcp_generate_npc",
+        "mcp_generate_encounter",
+        "mcp_generate_loot",
+        "mcp_generate_location",
+    ],
+    "combat": [
+        "start_combat",
+        "roll_all_initiatives",
+        "get_turn_order",
+        "next_turn",
+        "apply_damage",
+        "apply_condition",
+        "remove_combat_condition",
+        "end_combat",
+        "get_combat_status",
+        # MCP prefixed versions
+        "mcp_start_combat",
+        "mcp_roll_all_initiatives",
+        "mcp_get_turn_order",
+        "mcp_next_turn",
+        "mcp_apply_damage",
+        "mcp_end_combat",
+        "mcp_get_combat_status",
+    ],
+    "session": [
+        "start_session",
+        "end_session",
+        "log_event",
+        "get_session_summary",
+        "add_session_note",
+        "get_session_history",
+        "list_sessions",
+        # MCP prefixed versions
+        "mcp_start_session",
+        "mcp_end_session",
+        "mcp_log_event",
+        "mcp_get_session_summary",
+        "mcp_add_session_note",
+    ],
+}
+
+
+class TTRPGToolkitClient:
+    """
+    Client for connecting to TTRPG-Toolkit MCP server.
+
+    Uses llama-index-tools-mcp's BasicMCPClient for connection
+    and McpToolSpec for converting MCP tools to LlamaIndex FunctionTool objects.
+
+    Example:
+        ```python
+        client = TTRPGToolkitClient()
+        await client.connect()
+
+        # Get all tools for DM agent
+        all_tools = await client.get_all_tools()
+
+        # Get only rules tools for Rules agent
+        rules_tools = await client.get_tools_by_category(["rules"])
+
+        # Direct tool call
+        result = await client.call_tool("roll", {"notation": "2d6+3"})
+        ```
+    """
+
+    def __init__(
+        self,
+        mcp_url: str | None = None,
+        timeout: int | None = None,
+    ) -> None:
+        """
+        Initialize the TTRPG Toolkit client.
+
+        Args:
+            mcp_url: MCP server URL. Defaults to settings.mcp.ttrpg_toolkit_mcp_url
+            timeout: Connection timeout in seconds. Defaults to settings.mcp.mcp_connection_timeout
+        """
+        settings = get_settings()
+
+        self._url = mcp_url or settings.mcp.ttrpg_toolkit_mcp_url
+        self._timeout = timeout or settings.mcp.mcp_connection_timeout
+
+        # Internal state
+        self._client: BasicMCPClient | None = None
+        self._tool_spec: McpToolSpec | None = None
+        self._tools_cache: list[FunctionTool] | None = None
+        self._tools_by_name: dict[str, FunctionTool] | None = None
+        self._connected = False
+
+        logger.debug(f"TTRPGToolkitClient initialized with URL: {self._url}")
+
+    @property
+    def url(self) -> str:
+        """Get the MCP server URL."""
+        return self._url
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if client is connected."""
+        return self._connected
+
+    @property
+    def tools_count(self) -> int:
+        """Get number of cached tools."""
+        return len(self._tools_cache) if self._tools_cache else 0
+
+    async def connect(self) -> TTRPGToolkitClient:
+        """
+        Establish connection to MCP server.
+
+        Creates BasicMCPClient and McpToolSpec, then fetches and caches
+        all available tools to verify the connection.
+
+        Returns:
+            Self for method chaining.
+
+        Raises:
+            MCPConnectionError: If connection fails.
+        """
+        # Return early if already connected
+        if self._connected and self._client is not None:
+            logger.debug("Already connected to MCP server, skipping reconnection")
+            return self
+
+        logger.info(f"Connecting to MCP server at {self._url}...")
+
+        try:
+            # Create the MCP client
+            # BasicMCPClient auto-detects SSE vs streamable-http based on URL
+            self._client = BasicMCPClient(
+                command_or_url=self._url,
+                timeout=self._timeout,
+            )
+
+            # Create the tool spec for tool conversion
+            self._tool_spec = McpToolSpec(
+                client=self._client,
+                allowed_tools=None,  # Get all tools
+            )
+
+            # Fetch tools to verify connection
+            # This also caches the tools
+            self._tools_cache = await self._tool_spec.to_tool_list_async()
+
+            # Build name lookup dict
+            self._tools_by_name = {
+                tool.metadata.name: tool for tool in self._tools_cache
+                if tool.metadata.name is not None
+            }
+
+            self._connected = True
+            logger.info(
+                f"Connected to MCP server with {len(self._tools_cache)} tools available"
+            )
+
+            return self
+
+        except Exception as e:
+            self._connected = False
+            self._client = None
+            self._tool_spec = None
+            self._tools_cache = None
+            self._tools_by_name = None
+
+            logger.error(f"Failed to connect to MCP server: {e}")
+            raise MCPConnectionError(
+                f"Failed to connect to MCP server: {e}",
+                url=self._url,
+            ) from e
+
+    async def disconnect(self) -> None:
+        """
+        Gracefully close connection and clear cache.
+
+        Safe to call even if not connected.
+        """
+        logger.info("Disconnecting from MCP server...")
+
+        self._client = None
+        self._tool_spec = None
+        self._tools_cache = None
+        self._tools_by_name = None
+        self._connected = False
+
+        logger.info("Disconnected from MCP server")
+
+    async def get_all_tools(self) -> Sequence[FunctionTool]:
+        """
+        Get all available tools as LlamaIndex FunctionTool objects.
+
+        Uses cached tools if available.
+
+        Returns:
+            Sequence of FunctionTool objects.
+
+        Raises:
+            MCPConnectionError: If not connected.
+        """
+        if not self._connected or self._tools_cache is None:
+            raise MCPConnectionError(
+                "Not connected to MCP server. Call connect() first."
+            )
+
+        return self._tools_cache
+
+    async def get_tools_by_category(
+        self,
+        categories: Sequence[str],
+    ) -> list[FunctionTool]:
+        """
+        Get tools filtered by category names.
+
+        Args:
+            categories: List of category names from TOOL_CATEGORIES.
+                       Valid categories: dice, character, rules, generators, combat, session
+
+        Returns:
+            Filtered list of FunctionTool objects.
+
+        Raises:
+            MCPConnectionError: If not connected.
+        """
+        if not self._connected or self._tools_cache is None:
+            raise MCPConnectionError(
+                "Not connected to MCP server. Call connect() first."
+            )
+
+        # Build set of allowed tool names from categories
+        allowed_names: set[str] = set()
+        for category in categories:
+            if category in TOOL_CATEGORIES:
+                allowed_names.update(TOOL_CATEGORIES[category])
+            else:
+                logger.warning(f"Unknown tool category: {category}")
+
+        # Filter tools by name
+        filtered_tools = [
+            tool
+            for tool in self._tools_cache
+            if tool.metadata.name is not None and (
+                tool.metadata.name in allowed_names
+                or tool.metadata.name.replace("mcp_", "") in allowed_names
+            )
+        ]
+
+        logger.debug(
+            f"Filtered {len(filtered_tools)} tools from categories: {categories}"
+        )
+
+        return filtered_tools
+
+    async def get_tool_by_name(self, tool_name: str) -> FunctionTool | None:
+        """
+        Get a specific tool by name.
+
+        Args:
+            tool_name: Name of the tool to find.
+
+        Returns:
+            FunctionTool if found, None otherwise.
+        """
+        if not self._connected or self._tools_by_name is None:
+            return None
+
+        # Try exact match first
+        tool = self._tools_by_name.get(tool_name)
+        if tool:
+            return tool
+
+        # Try with mcp_ prefix
+        tool = self._tools_by_name.get(f"mcp_{tool_name}")
+        if tool:
+            return tool
+
+        # Try without mcp_ prefix
+        if tool_name.startswith("mcp_"):
+            tool = self._tools_by_name.get(tool_name[4:])
+
+        return tool
+
+    async def call_tool(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+    ) -> Any:
+        """
+        Call a tool directly without going through an agent.
+
+        Useful for direct API access and internal operations.
+
+        Args:
+            tool_name: Name of the tool to call.
+            arguments: Arguments to pass to the tool.
+
+        Returns:
+            Tool result (type varies by tool).
+
+        Raises:
+            MCPConnectionError: If not connected.
+            MCPToolNotFoundError: If tool doesn't exist.
+            MCPToolExecutionError: If tool execution fails.
+        """
+        if not self._connected:
+            raise MCPConnectionError(
+                "Not connected to MCP server. Call connect() first."
+            )
+
+        tool = await self.get_tool_by_name(tool_name)
+        if tool is None:
+            raise MCPToolNotFoundError(tool_name)
+
+        try:
+            logger.debug(f"Calling tool '{tool_name}' with args: {arguments}")
+            result = await tool.acall(**arguments)
+
+            # FunctionTool.acall returns ToolOutput, extract raw_output
+            if hasattr(result, "raw_output"):
+                return result.raw_output
+            return result
+
+        except Exception as e:
+            logger.error(f"Tool '{tool_name}' execution failed: {e}")
+            raise MCPToolExecutionError(tool_name, e) from e
+
+    def call_tool_sync(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+    ) -> Any:
+        """
+        Synchronous wrapper for call_tool.
+
+        Uses asyncio.run() for synchronous contexts.
+        Prefer call_tool() in async code.
+
+        Args:
+            tool_name: Name of the tool to call.
+            arguments: Arguments to pass to the tool.
+
+        Returns:
+            Tool result.
+        """
+        import asyncio
+
+        return asyncio.run(self.call_tool(tool_name, arguments))
+
+    async def list_tool_names(self) -> list[str]:
+        """
+        Get list of all available tool names.
+
+        Returns:
+            List of tool names.
+
+        Raises:
+            MCPConnectionError: If not connected.
+        """
+        if not self._connected or self._tools_by_name is None:
+            raise MCPConnectionError("Not connected to MCP server.")
+
+        return list(self._tools_by_name.keys())
+
+    async def has_tool(self, tool_name: str) -> bool:
+        """
+        Check if a tool is available.
+
+        Args:
+            tool_name: Name of the tool to check.
+
+        Returns:
+            True if tool exists, False otherwise.
+        """
+        tool = await self.get_tool_by_name(tool_name)
+        return tool is not None
+
+    def get_category_for_tool(self, tool_name: str) -> str | None:
+        """
+        Get the category for a tool name.
+
+        Args:
+            tool_name: Name of the tool.
+
+        Returns:
+            Category name or None if not found.
+        """
+        # Normalize name (remove mcp_ prefix)
+        normalized = tool_name.replace("mcp_", "")
+
+        for category, tools in TOOL_CATEGORIES.items():
+            if normalized in tools or tool_name in tools:
+                return category
+
+        return None
+
+    async def refresh_tools(self) -> int:
+        """
+        Refresh the cached tool list from the server.
+
+        Useful after server updates or if tools might have changed.
+
+        Returns:
+            Number of tools now available.
+
+        Raises:
+            MCPConnectionError: If not connected or refresh fails.
+        """
+        if not self._connected or self._tool_spec is None:
+            raise MCPConnectionError("Not connected to MCP server.")
+
+        try:
+            self._tools_cache = await self._tool_spec.to_tool_list_async()
+            self._tools_by_name = {
+                tool.metadata.name: tool for tool in self._tools_cache
+                if tool.metadata.name is not None
+            }
+            logger.info(f"Refreshed tool cache: {len(self._tools_cache)} tools")
+            return len(self._tools_cache)
+
+        except Exception as e:
+            logger.error(f"Failed to refresh tools: {e}")
+            raise MCPConnectionError(f"Failed to refresh tools: {e}") from e
+
+    def __repr__(self) -> str:
+        """String representation."""
+        status = "connected" if self._connected else "disconnected"
+        tools = self.tools_count
+        return f"TTRPGToolkitClient(url={self._url!r}, status={status}, tools={tools})"

src/utils/__init__.py

@@ -0,0 +1,53 @@
+"""
+DungeonMaster AI - Utilities Package
+
+Helper functions for formatting, validation, and common operations.
+"""
+
+from src.utils.formatters import (
+    format_ability_modifier,
+    format_adventure_intro,
+    format_character_summary,
+    format_combat_turn,
+    format_condition_list,
+    format_currency,
+    format_dice_roll,
+    format_hp_change,
+    format_initiative_order,
+)
+from src.utils.validators import (
+    ValidationError,
+    sanitize_for_tts,
+    validate_ability_score,
+    validate_adventure_data,
+    validate_character_name,
+    validate_dice_notation,
+    validate_hp,
+    validate_level,
+    validate_player_input,
+    validate_session_data,
+)
+
+__all__ = [
+    # Formatters
+    "format_dice_roll",
+    "format_hp_change",
+    "format_combat_turn",
+    "format_ability_modifier",
+    "format_currency",
+    "format_condition_list",
+    "format_initiative_order",
+    "format_character_summary",
+    "format_adventure_intro",
+    # Validators
+    "ValidationError",
+    "validate_dice_notation",
+    "validate_character_name",
+    "validate_ability_score",
+    "validate_level",
+    "validate_hp",
+    "validate_player_input",
+    "validate_session_data",
+    "validate_adventure_data",
+    "sanitize_for_tts",
+]

src/utils/formatters.py

@@ -0,0 +1,278 @@
+"""
+DungeonMaster AI - Output Formatters
+
+Utilities for formatting game data for display in chat and UI components.
+"""
+
+from typing import Any
+
+
+def format_dice_roll(
+    notation: str,
+    individual_rolls: list[int],
+    modifier: int,
+    total: int,
+    is_check: bool = False,
+    dc: int | None = None,
+    success: bool | None = None,
+) -> str:
+    """
+    Format a dice roll result for display.
+
+    Args:
+        notation: The dice notation (e.g., "2d6+3")
+        individual_rolls: List of individual die results
+        modifier: The modifier applied to the roll
+        total: The final total
+        is_check: Whether this was an ability check/save
+        dc: Difficulty class if this was a check
+        success: Whether the check succeeded (if applicable)
+
+    Returns:
+        Formatted string for display
+    """
+    # Format individual dice
+    dice_str = ", ".join(str(r) for r in individual_rolls)
+
+    # Build the breakdown
+    if modifier > 0:
+        breakdown = f"[{dice_str}] + {modifier}"
+    elif modifier < 0:
+        breakdown = f"[{dice_str}] - {abs(modifier)}"
+    else:
+        breakdown = f"[{dice_str}]"
+
+    # Check for critical (d20 rolls)
+    is_critical = False
+    is_fumble = False
+    if len(individual_rolls) == 1 and individual_rolls[0] == 20:
+        is_critical = "d20" in notation.lower()
+    if len(individual_rolls) == 1 and individual_rolls[0] == 1:
+        is_fumble = "d20" in notation.lower()
+
+    # Build result string
+    result_parts = [f"{notation} = {breakdown} = **{total}**"]
+
+    if is_critical:
+        result_parts.append("**CRITICAL!**")
+    elif is_fumble:
+        result_parts.append("*Critical Failure!*")
+
+    if is_check and dc is not None:
+        if success:
+            result_parts.append(f"vs DC {dc}: **Success!**")
+        else:
+            result_parts.append(f"vs DC {dc}: *Failure*")
+
+    return " ".join(result_parts)
+
+
+def format_hp_change(
+    character_name: str,
+    previous_hp: int,
+    current_hp: int,
+    max_hp: int,
+    is_damage: bool,
+) -> str:
+    """
+    Format an HP change for display.
+
+    Args:
+        character_name: Name of the character
+        previous_hp: HP before the change
+        current_hp: HP after the change
+        max_hp: Maximum HP
+        is_damage: True if damage, False if healing
+
+    Returns:
+        Formatted string for display
+    """
+    change = abs(current_hp - previous_hp)
+
+    if is_damage:
+        if current_hp <= 0:
+            return f"**{character_name}** takes {change} damage and falls unconscious! (0/{max_hp} HP)"
+        elif current_hp <= max_hp // 4:
+            return f"**{character_name}** takes {change} damage and is badly wounded! ({current_hp}/{max_hp} HP)"
+        else:
+            return f"**{character_name}** takes {change} damage. ({current_hp}/{max_hp} HP)"
+    else:
+        if current_hp >= max_hp:
+            return f"**{character_name}** is fully healed! ({max_hp}/{max_hp} HP)"
+        else:
+            return f"**{character_name}** heals {change} HP. ({current_hp}/{max_hp} HP)"
+
+
+def format_combat_turn(
+    combatant_name: str,
+    initiative: int,
+    is_player: bool,
+    round_number: int,
+) -> str:
+    """
+    Format a combat turn announcement.
+
+    Args:
+        combatant_name: Name of the combatant whose turn it is
+        initiative: Their initiative value
+        is_player: Whether this is a player character
+        round_number: Current combat round
+
+    Returns:
+        Formatted string for display
+    """
+    if is_player:
+        return f"**Round {round_number}** - It's your turn, **{combatant_name}**! (Initiative: {initiative})"
+    else:
+        return f"**Round {round_number}** - **{combatant_name}** takes their turn. (Initiative: {initiative})"
+
+
+def format_ability_modifier(score: int) -> str:
+    """
+    Format an ability score modifier for display.
+
+    Args:
+        score: The ability score (1-30)
+
+    Returns:
+        Formatted modifier string (e.g., "+2" or "-1")
+    """
+    modifier = (score - 10) // 2
+    if modifier >= 0:
+        return f"+{modifier}"
+    return str(modifier)
+
+
+def format_currency(gp: int = 0, sp: int = 0, cp: int = 0) -> str:
+    """
+    Format currency for display.
+
+    Args:
+        gp: Gold pieces
+        sp: Silver pieces
+        cp: Copper pieces
+
+    Returns:
+        Formatted currency string
+    """
+    parts = []
+    if gp > 0:
+        parts.append(f"{gp} gp")
+    if sp > 0:
+        parts.append(f"{sp} sp")
+    if cp > 0:
+        parts.append(f"{cp} cp")
+
+    if not parts:
+        return "0 gp"
+    return ", ".join(parts)
+
+
+def format_condition_list(conditions: list[str]) -> str:
+    """
+    Format a list of conditions for display.
+
+    Args:
+        conditions: List of condition names
+
+    Returns:
+        Formatted string or empty message
+    """
+    if not conditions:
+        return "None"
+    return ", ".join(conditions)
+
+
+def format_initiative_order(
+    combatants: list[dict[str, Any]],
+    current_turn_index: int,
+) -> str:
+    """
+    Format the initiative order for display.
+
+    Args:
+        combatants: List of combatant dictionaries with name, initiative, hp info
+        current_turn_index: Index of current turn combatant
+
+    Returns:
+        Formatted initiative order string
+    """
+    lines = ["**Initiative Order:**"]
+
+    for i, combatant in enumerate(combatants):
+        marker = ">" if i == current_turn_index else " "
+        name = combatant.get("name", "Unknown")
+        init = combatant.get("initiative", 0)
+        hp_current = combatant.get("hp_current", 0)
+        hp_max = combatant.get("hp_max", 1)
+
+        hp_percent = (hp_current / hp_max) * 100 if hp_max > 0 else 0
+        if hp_percent > 50:
+            status = "Healthy"
+        elif hp_percent > 25:
+            status = "Wounded"
+        elif hp_percent > 0:
+            status = "Critical"
+        else:
+            status = "Down"
+
+        lines.append(f"{marker} {init:2d} | {name} ({status})")
+
+    return "\n".join(lines)
+
+
+def format_character_summary(character: dict[str, Any]) -> str:
+    """
+    Format a character summary for context.
+
+    Args:
+        character: Character data dictionary
+
+    Returns:
+        Formatted character summary
+    """
+    name = character.get("name", "Unknown")
+    race = character.get("race", "Unknown")
+    char_class = character.get("class", "Unknown")
+    level = character.get("level", 1)
+
+    hp = character.get("hit_points", {})
+    hp_current = hp.get("current", 0)
+    hp_max = hp.get("maximum", 1)
+
+    ac = character.get("armor_class", 10)
+    conditions = character.get("conditions", [])
+
+    summary = f"**{name}** - Level {level} {race} {char_class}\n"
+    summary += f"HP: {hp_current}/{hp_max} | AC: {ac}\n"
+
+    if conditions:
+        summary += f"Conditions: {format_condition_list(conditions)}"
+
+    return summary
+
+
+def format_adventure_intro(adventure_data: dict[str, Any]) -> str:
+    """
+    Format an adventure introduction for the opening narration.
+
+    Args:
+        adventure_data: Adventure JSON data
+
+    Returns:
+        Formatted introduction text
+    """
+    metadata = adventure_data.get("metadata", {})
+    starting_scene = adventure_data.get("starting_scene", {})
+
+    name = metadata.get("name", "Unnamed Adventure")
+    description = metadata.get("description", "")
+    narrative = starting_scene.get("narrative", "Your adventure begins...")
+
+    intro = f"# {name}\n\n"
+    if description:
+        intro += f"*{description}*\n\n"
+    intro += "---\n\n"
+    intro += str(narrative)
+
+    return intro

src/utils/validators.py

@@ -0,0 +1,276 @@
+"""
+DungeonMaster AI - Input Validators
+
+Utilities for validating user input and game data.
+"""
+
+import re
+from typing import Any
+
+
+class ValidationError(Exception):
+    """Custom exception for validation errors."""
+
+    def __init__(self, message: str, field: str | None = None):
+        self.message = message
+        self.field = field
+        super().__init__(self.message)
+
+
+def validate_dice_notation(notation: str) -> bool:
+    """
+    Validate dice notation format.
+
+    Valid formats:
+    - d20, D20
+    - 2d6, 2D6
+    - 1d8+5, 1d8-2
+    - 4d6kh3 (keep highest 3)
+    - 2d20kl1 (keep lowest 1, disadvantage)
+
+    Args:
+        notation: The dice notation string
+
+    Returns:
+        True if valid, False otherwise
+    """
+    # Pattern for standard dice notation with optional modifiers and keep syntax
+    pattern = r"^(\d+)?[dD](\d+)(kh\d+|kl\d+)?([+-]\d+)?$"
+    return bool(re.match(pattern, notation.strip()))
+
+
+def validate_character_name(name: str) -> tuple[bool, str]:
+    """
+    Validate a character name.
+
+    Args:
+        name: The proposed character name
+
+    Returns:
+        Tuple of (is_valid, error_message or empty string)
+    """
+    if not name or not name.strip():
+        return False, "Character name cannot be empty"
+
+    name = name.strip()
+
+    if len(name) < 2:
+        return False, "Character name must be at least 2 characters"
+
+    if len(name) > 50:
+        return False, "Character name must be 50 characters or less"
+
+    # Allow letters, spaces, apostrophes, and hyphens
+    if not re.match(r"^[a-zA-Z][a-zA-Z\s'\-]*$", name):
+        return False, "Character name must start with a letter and contain only letters, spaces, apostrophes, and hyphens"
+
+    return True, ""
+
+
+def validate_ability_score(score: int, method: str = "standard") -> tuple[bool, str]:
+    """
+    Validate an ability score.
+
+    Args:
+        score: The ability score value
+        method: The generation method ("standard", "point_buy", "rolled")
+
+    Returns:
+        Tuple of (is_valid, error_message or empty string)
+    """
+    if not isinstance(score, int):
+        return False, "Ability score must be an integer"
+
+    if method == "point_buy":
+        if score < 8 or score > 15:
+            return False, "Point buy scores must be between 8 and 15"
+    elif method == "standard":
+        valid_scores = [8, 10, 12, 13, 14, 15]
+        if score not in valid_scores:
+            return False, f"Standard array scores must be one of {valid_scores}"
+    else:  # rolled or other
+        if score < 3 or score > 18:
+            return False, "Rolled scores must be between 3 and 18"
+
+    return True, ""
+
+
+def validate_level(level: int) -> tuple[bool, str]:
+    """
+    Validate a character level.
+
+    Args:
+        level: The character level
+
+    Returns:
+        Tuple of (is_valid, error_message or empty string)
+    """
+    if not isinstance(level, int):
+        return False, "Level must be an integer"
+
+    if level < 1 or level > 20:
+        return False, "Level must be between 1 and 20"
+
+    return True, ""
+
+
+def validate_hp(
+    current: int, maximum: int, allow_negative: bool = False
+) -> tuple[bool, str]:
+    """
+    Validate HP values.
+
+    Args:
+        current: Current HP
+        maximum: Maximum HP
+        allow_negative: Whether to allow negative current HP (for massive damage)
+
+    Returns:
+        Tuple of (is_valid, error_message or empty string)
+    """
+    if not isinstance(current, int) or not isinstance(maximum, int):
+        return False, "HP values must be integers"
+
+    if maximum < 1:
+        return False, "Maximum HP must be at least 1"
+
+    if not allow_negative and current < 0:
+        return False, "Current HP cannot be negative"
+
+    if allow_negative and current < -maximum:
+        return False, "Current HP cannot be less than negative maximum HP"
+
+    return True, ""
+
+
+def validate_player_input(
+    message: str, max_length: int = 1000
+) -> tuple[bool, str, str]:
+    """
+    Validate and sanitize player input.
+
+    Args:
+        message: The player's input message
+        max_length: Maximum allowed length
+
+    Returns:
+        Tuple of (is_valid, sanitized_message, error_message)
+    """
+    if not message:
+        return False, "", "Please enter an action or message"
+
+    # Strip and normalize whitespace
+    sanitized = " ".join(message.split())
+
+    if len(sanitized) > max_length:
+        return False, "", f"Message is too long (max {max_length} characters)"
+
+    # Check for potentially problematic content
+    # (In a real app, might want more sophisticated content filtering)
+    if sanitized.count("```") > 4:
+        return False, sanitized, "Message contains too many code blocks"
+
+    return True, sanitized, ""
+
+
+def validate_session_data(data: dict[str, Any]) -> tuple[bool, str]:
+    """
+    Validate session/save data structure.
+
+    Args:
+        data: The session data dictionary
+
+    Returns:
+        Tuple of (is_valid, error_message or empty string)
+    """
+    required_fields = ["session_id", "started_at", "system"]
+
+    for field in required_fields:
+        if field not in data:
+            return False, f"Missing required field: {field}"
+
+    if data.get("system") not in ["dnd5e", "pathfinder2e", "call_of_cthulhu", "fate"]:
+        return False, "Invalid game system"
+
+    if "party" in data and not isinstance(data["party"], list):
+        return False, "Party must be a list"
+
+    if "game_state" in data:
+        state = data["game_state"]
+        if "in_combat" in state and not isinstance(state["in_combat"], bool):
+            return False, "in_combat must be a boolean"
+
+    return True, ""
+
+
+def validate_adventure_data(data: dict[str, Any]) -> tuple[bool, str]:
+    """
+    Validate adventure JSON structure.
+
+    Args:
+        data: The adventure data dictionary
+
+    Returns:
+        Tuple of (is_valid, error_message or empty string)
+    """
+    if "metadata" not in data:
+        return False, "Adventure must have metadata"
+
+    metadata = data["metadata"]
+    required_metadata = ["name", "description", "difficulty"]
+    for field in required_metadata:
+        if field not in metadata:
+            return False, f"Metadata missing required field: {field}"
+
+    if "starting_scene" not in data:
+        return False, "Adventure must have a starting_scene"
+
+    if "scenes" not in data or not isinstance(data["scenes"], list):
+        return False, "Adventure must have a scenes array"
+
+    if len(data["scenes"]) == 0:
+        return False, "Adventure must have at least one scene"
+
+    # Validate scene references
+    scene_ids = {scene.get("scene_id") for scene in data["scenes"]}
+    starting_id = data["starting_scene"].get("scene_id")
+    if starting_id not in scene_ids:
+        return False, f"Starting scene '{starting_id}' not found in scenes"
+
+    return True, ""
+
+
+def sanitize_for_tts(text: str) -> str:
+    """
+    Sanitize text for text-to-speech processing.
+
+    Removes or converts elements that might cause TTS issues.
+
+    Args:
+        text: The raw text
+
+    Returns:
+        Sanitized text suitable for TTS
+    """
+    # Remove markdown formatting
+    text = re.sub(r"\*\*(.+?)\*\*", r"\1", text)  # Bold
+    text = re.sub(r"\*(.+?)\*", r"\1", text)  # Italic
+    text = re.sub(r"~~(.+?)~~", r"\1", text)  # Strikethrough
+    text = re.sub(r"`(.+?)`", r"\1", text)  # Inline code
+    text = re.sub(r"```[\s\S]*?```", "", text)  # Code blocks
+    text = re.sub(r"^#{1,6}\s+", "", text, flags=re.MULTILINE)  # Headers
+
+    # Remove links, keep text
+    text = re.sub(r"\[(.+?)\]\(.+?\)", r"\1", text)
+
+    # Remove emojis (basic pattern)
+    text = re.sub(
+        r"[\U0001F600-\U0001F64F\U0001F300-\U0001F5FF\U0001F680-\U0001F6FF\U0001F1E0-\U0001F1FF]",
+        "",
+        text,
+    )
+
+    # Normalize whitespace
+    text = " ".join(text.split())
+
+    return text.strip()

src/voice/__init__.py

@@ -0,0 +1,130 @@
+"""
+DungeonMaster AI - Voice Package
+
+ElevenLabs integration for voice synthesis and narration.
+
+This module provides:
+- VoiceClient: Production-ready ElevenLabs client with circuit breaker
+- NarrationProcessor: Text preprocessing for optimal TTS
+- Voice profiles: Pre-configured voices for DM, NPCs, and monsters
+- Comprehensive error handling and graceful degradation
+
+Example Usage:
+    ```python
+    from src.voice import VoiceClient, NarrationProcessor, VoiceType
+
+    # Initialize client
+    client = VoiceClient()
+    await client.initialize()
+
+    # Process and synthesize
+    processor = NarrationProcessor()
+    processed = processor.process_for_tts("Roll a 1d20 for HP!")
+
+    if client.is_available:
+        audio = await client.synthesize(processed, VoiceType.DM)
+    ```
+"""
+
+# Exceptions
+from src.voice.exceptions import (
+    VoiceAPIError,
+    VoiceAuthenticationError,
+    VoiceCircuitBreakerOpenError,
+    VoiceConfigurationError,
+    VoiceIntegrationError,
+    VoiceNotFoundError,
+    VoiceQuotaExhaustedError,
+    VoiceRateLimitError,
+    VoiceSynthesisError,
+    VoiceUnavailableError,
+)
+
+# Models
+from src.voice.models import (
+    NarrationResult,
+    ProcessedNarration,
+    SynthesisRequest,
+    SynthesisResult,
+    TextSegment,
+    VoiceCircuitState,
+    VoiceModelType,
+    VoiceProfile,
+    VoiceServiceState,
+    VoiceServiceStatus,
+    VoiceSynthesisSettings,
+    VoiceType,
+)
+
+# Voice Profiles
+from src.voice.voice_profiles import (
+    VOICE_PROFILES,
+    get_all_profiles,
+    get_voice_id,
+    get_voice_profile,
+    get_voice_profile_by_name,
+    get_voice_settings,
+    reset_profiles_cache,
+    select_voice_for_context,
+    select_voice_from_game_context,
+    select_voice_from_npc_data,
+)
+
+# Text Processing
+from src.voice.text_processor import NarrationProcessor
+
+# Voice Client
+from src.voice.elevenlabs_client import (
+    AudioCache,
+    RateLimiter,
+    VoiceCircuitBreaker,
+    VoiceClient,
+)
+
+__all__ = [
+    # Exceptions
+    "VoiceIntegrationError",
+    "VoiceAPIError",
+    "VoiceRateLimitError",
+    "VoiceQuotaExhaustedError",
+    "VoiceAuthenticationError",
+    "VoiceUnavailableError",
+    "VoiceCircuitBreakerOpenError",
+    "VoiceNotFoundError",
+    "VoiceSynthesisError",
+    "VoiceConfigurationError",
+    # Models - Enums
+    "VoiceType",
+    "VoiceCircuitState",
+    "VoiceServiceState",
+    "VoiceModelType",
+    # Models - Settings
+    "VoiceSynthesisSettings",
+    "VoiceProfile",
+    # Models - Requests/Results
+    "SynthesisRequest",
+    "SynthesisResult",
+    "TextSegment",
+    "ProcessedNarration",
+    "NarrationResult",
+    # Models - Status
+    "VoiceServiceStatus",
+    # Voice Profiles
+    "VOICE_PROFILES",
+    "get_voice_profile",
+    "get_voice_profile_by_name",
+    "get_voice_id",
+    "get_voice_settings",
+    "get_all_profiles",
+    "reset_profiles_cache",
+    "select_voice_for_context",
+    "select_voice_from_npc_data",
+    "select_voice_from_game_context",
+    # Text Processing
+    "NarrationProcessor",
+    # Voice Client
+    "VoiceClient",
+    "VoiceCircuitBreaker",
+    "RateLimiter",
+    "AudioCache",
+]