feat: Add character-aware gameplay and Gradio web UI (Phase 8)

Major Features:
- 🌐 Gradio web interface (app_gradio.py) for browser-based gameplay
- 🎭 Character-aware dialogue system (play_with_character.py)
- 🎲 Pre-made characters: Thorin Stormshield (Fighter) & Elara Moonwhisper (Wizard)
- 📊 Live character stats displayed during gameplay
- ⚡ Command system: /stats, /context, /rag, /character

Technical Improvements:
- Suppressed tokenizer parallelism warning
- Fixed first/second person context ("The player is X" → AI uses "you")
- Dynamic character support (load from JSON or create new)
- Three play modes: Web UI, CLI, or legacy GM dialogue

Documentation Updates:
- README: Comprehensive gameplay instructions for Thorin and Elara
- README: Full commands reference (/context, /rag, /stats)
- README: Gradio and CLI interface documentation
- plan_progress.md: Added Phase 8 (Game Mechanics Engine)
- plan_progress.md: Documented hybrid AI + Rules Engine architecture (Option B)
- requirements.txt: Added gradio>=4.0.0

Architecture Notes (Phase 8):
- Discovered AI reliability issues (ignores valid spells, allows invalid ones)
- Selected hybrid approach: Rules engine intercepts actions before AI narration
- Future work: Spell validation, HP tracking, combat mechanics

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -196,66 +196,188 @@ Sage | Neutral Good
 
 #### Step 4: Play D&D with AI Game Master
 
-Run an interactive D&D session with RAG-enhanced AI GM:
+**Prerequisites:**
+- Install Ollama: https://ollama.ai
+- Download RPG model: `ollama pull hf.co/Chun121/Qwen3-4B-RPG-Roleplay-V2:Q4_K_M`
+
+You have **two ways** to play:
+
+---
+
+### Option A: 🌐 Web Interface (Gradio) **⭐ RECOMMENDED**
+
+Launch the web UI for the best experience:
 
 ```bash
-python run_gm_dialogue.py
+python app_gradio.py
 ```
 
-**Prerequisites:**
-- Install Ollama: https://ollama.ai
-- Download RPG model: `ollama pull hf.co/Chun121/Qwen3-4B-RPG-Roleplay-V2:Q4_K_M`
+Then open http://localhost:7860 in your browser.
 
-**What this does:**
-- Interactive D&D game session with AI Dungeon Master
-- RAG-powered rule lookups in real-time
-- GM searches ChromaDB for spells, monsters, classes when relevant
-- Conversation history and context management
-- Commands for scene setting, history review, and more
+**Features:**
+- 🎭 **Pre-made Characters**: Play as Thorin Stormshield (Dwarf Fighter) or Elara Moonwhisper (Elf Wizard)
+- 💬 **Chat Interface**: Clean conversation view with the AI GM
+- 📊 **Character Sheet**: Live character stats displayed in sidebar
+- ⚡ **Quick Commands**: Built-in buttons for common actions
+- 🎲 **RAG Search**: Test spell/monster lookups directly in the UI
+
+**Quick Start:**
+1. Select a character from dropdown (Thorin or Elara)
+2. Click "Load Character"
+3. Type your action in the chat box
+4. The GM responds with RAG-enhanced D&D rules!
 
-**Example session:**
+**Example Actions:**
 ```
-🎲 D&D GAME MASTER - RAG-Enhanced AI Dungeon Master
+# As Thorin (Fighter):
+I draw my longsword and look for enemies
+I attack with my weapon
+/stats
+
+# As Elara (Wizard):
+I cast Magic Missile at the goblin
+I look through my spellbook
+/rag Magic Missile
+```
+
+---
+
+### Option B: 💻 Command Line Interface
+
+For terminal lovers, use the CLI version:
+
+```bash
+python play_with_character.py
+```
+
+**Character Selection:**
+```
+1. Create new character (full interactive creation)
+2. Load existing character (from JSON file)
+3. Use test character (quick start with Thorin)
+```
+
+**Available Characters:**
+
+**Thorin Stormshield** - Level 3 Dwarf Fighter
+- HP: 28 | AC: 18 | Proficiency: +2
+- STR 16 (+3) | DEX 12 (+1) | CON 16 (+3)
+- Equipment: Longsword, Shield, Plate Armor
+- Perfect for: Melee combat, tanking, straightforward gameplay
+
+**Elara Moonwhisper** - Level 2 Elf Wizard
+- HP: 14 | AC: 12 | Proficiency: +2
+- INT 17 (+3) | DEX 14 (+2) | CON 12 (+1)
+- Spells: Fire Bolt, Mage Hand, Magic Missile, Shield
+- Equipment: Quarterstaff, Spellbook, Component Pouch
+- Perfect for: Spellcasting, strategic gameplay, testing RAG
+
+**Example Session:**
+```
+🎲 D&D GAME SESSION - Playing as Elara Moonwhisper
+======================================================================
+Character: Elara Moonwhisper (Elf Wizard)
 Model: hf.co/Chun121/Qwen3-4B-RPG-Roleplay-V2:Q4_K_M
 
-Type /help for commands or just start playing!
+Type /help for commands or start playing!
 ======================================================================
 
-🎲 You: I cast fireball at the goblins
+🎲 Elara Moonwhisper: I look around the tavern
+
+🎭 GM: The tavern is dimly lit by flickering torches. You notice a group
+of rough-looking adventurers in the corner, and a hooded figure sitting
+alone by the fireplace...
+
+🎲 Elara Moonwhisper: /stats
+
+📊 Elara Moonwhisper | HP: 14 | AC: 12 | Prof: +2
+   STR -1 | DEX +2 | CON +1 | INT +3 | WIS +1 | CHA +0
+```
+
+---
 
-🎭 GM: Roll for your attack! The spell requires a DC 15 Dexterity saving
-throw from each goblin. Roll 8d6 for fire damage. Each goblin in the
-20-foot radius must make their save - on a success, they take half damage.
+### 🎮 Commands Reference
 
-🎲 You: I investigate the room
+**Character Commands:**
+```
+/character      - Show full character sheet
+/stats          - Quick stats view (HP, AC, modifiers)
+/context        - View current scene and character context
+```
 
-🎭 GM: Make an Investigation check (roll d20 + INT modifier). I'll set
-the DC based on what you're looking for...
+**RAG Commands:**
+```
+/rag <query>    - Search D&D knowledge base
+                  Examples:
+                  /rag Magic Missile    - Look up spell details
+                  /rag Goblin          - Look up monster stats
+                  /rag Fighter         - Look up class features
+                  /rag Elf             - Look up race traits
 ```
 
-**Available Commands:**
+**Session Commands:**
 ```
-/help           - Show available commands
-/context <text> - Set the current scene/context
+/help           - Show all available commands
 /history        - Show conversation history
-/rag <query>    - Test RAG search (see what the GM knows)
 /save <file>    - Save session to JSON
 /quit           - Exit the game
 ```
 
-**How It Works:**
-1. Player enters action or question
-2. GM searches ChromaDB for relevant spells/monsters/rules
-3. RAG results are injected into the LLM prompt
-4. AI GM generates response using accurate D&D 5e rules
-5. Response is shown to player with proper mechanics
+---
+
+### 💡 How It Works
+
+**Character-Aware Gameplay:**
+1. Select or create a character (Thorin, Elara, or custom)
+2. Character stats, spells, and equipment are passed to the GM
+3. GM knows YOUR character and references it in responses
+
+**RAG Integration:**
+1. You type an action (e.g., "I cast Magic Missile")
+2. System searches ChromaDB for relevant spells/monsters/rules
+3. RAG results are injected into the AI GM's context
+4. GM generates response using accurate D&D 5e rules
+5. Response references your character's abilities
+
+**Example RAG Flow:**
+```
+Input: "I cast Magic Missile at the goblin"
+  ↓
+RAG Search: Finds "Magic Missile" spell
+  ↓
+Context: "Elara (Wizard) has Magic Missile in spell list"
+  ↓
+Context: "Magic Missile: 1st-level, 3 darts, 1d4+1 force damage each"
+  ↓
+AI GM Response: Uses accurate spell mechanics + your character's stats
+```
+
+---
+
+### 🎯 Gameplay Tips
+
+**For Best Results:**
+- **Be Specific**: "I cast Fire Bolt at the closest goblin" vs "I attack"
+- **Use RAG**: Test `/rag <spell>` before casting to see what the GM knows
+- **Check Context**: Use `/context` to see what the GM knows about your character
+- **View Stats**: Use `/stats` during combat to remember your modifiers
+- **Roleplay**: The GM responds to narrative actions ("I cautiously enter the room")
 
-**Tips:**
-- Be specific: "I cast fireball" vs "I attack"
-- The GM will ask for dice rolls when needed
-- Use `/context` to set the scene for better immersion
-- Use `/rag` to check if the GM has specific rule information
-- The system works best with clear, action-oriented inputs
+**Testing Spells with Elara:**
+```
+/rag Magic Missile     # See full spell description
+I cast Magic Missile   # GM should apply 1st-level spell rules
+/rag Fireball         # Search for a spell Elara doesn't know
+I cast Fireball       # GM behavior (should it allow this?)
+```
+
+**Combat with Thorin:**
+```
+/stats                      # Check your attack bonus
+I attack with my longsword # GM will ask for d20 roll
+I use my shield             # GM applies AC bonus
+I use Second Wind          # GM applies fighter class feature
+```
 
 #### Step 5: Run Interactive Searches (Optional)
 
@@ -364,8 +486,10 @@ You should see the Qwen3-4B-RPG model in the list.
 │
 ├── chromadb/                # Vector database (created on init)
 ├── initialize_rag.py        # Main initialization script ⭐
-├── query_rag.py             # Interactive query CLI ⭐ NEW!
-├── test_all_collections.py  # Comprehensive test suite ⭐ NEW!
+├── app_gradio.py            # Gradio web UI ⭐ NEW!
+├── play_with_character.py  # Character-aware gameplay CLI ⭐ NEW!
+├── query_rag.py             # Interactive query CLI ⭐
+├── test_all_collections.py  # Comprehensive test suite ⭐
 ├── test_spell_search.py     # Manual search testing
 ├── create_character.py      # Character creator launcher
 ├── run_gm_dialogue.py       # AI GM dialogue launcher

app_gradio.py

@@ -0,0 +1,328 @@
+#!/usr/bin/env python3
+"""
+D&D Character-Aware Game - Gradio Web Interface
+
+Web UI for playing D&D with RAG-enhanced AI GM and character tracking.
+"""
+
+import os
+# Suppress tokenizer warning
+os.environ['TOKENIZERS_PARALLELISM'] = 'false'
+
+import gradio as gr
+import json
+from pathlib import Path
+
+# Add project to path
+import sys
+sys.path.insert(0, str(Path(__file__).parent))
+
+from dnd_rag_system.core.chroma_manager import ChromaDBManager
+from dnd_rag_system.systems.character_creator import Character
+from dnd_rag_system.systems.gm_dialogue import GameMaster
+
+
+# Initialize system
+print("🎲 Initializing D&D RAG System...")
+db = ChromaDBManager()
+gm = GameMaster(db)
+
+# Pre-made characters
+THORIN = Character(
+    name="Thorin Stormshield",
+    race="Dwarf",
+    character_class="Fighter",
+    level=3,
+    strength=16,
+    dexterity=12,
+    constitution=16,
+    intelligence=10,
+    wisdom=13,
+    charisma=8,
+    hit_points=28,
+    armor_class=18,
+    proficiency_bonus=2,
+    background="Soldier",
+    alignment="Lawful Good",
+    race_traits=["Dwarven Resilience", "Darkvision"],
+    class_features=["Fighting Style: Defense", "Second Wind", "Action Surge"],
+    proficiencies=["All armor", "All weapons", "Shields"],
+    equipment=["Longsword", "Shield", "Plate Armor", "Backpack", "50 GP"],
+    spells=[]
+)
+
+ELARA = Character(
+    name="Elara Moonwhisper",
+    race="Elf",
+    character_class="Wizard",
+    level=2,
+    strength=8,
+    dexterity=14,
+    constitution=12,
+    intelligence=17,
+    wisdom=13,
+    charisma=10,
+    hit_points=14,
+    armor_class=12,
+    proficiency_bonus=2,
+    background="Sage",
+    alignment="Neutral Good",
+    race_traits=["Darkvision", "Fey Ancestry"],
+    class_features=["Spellcasting", "Arcane Recovery"],
+    proficiencies=["Daggers", "Quarterstaffs", "Light crossbows"],
+    equipment=["Quarterstaff", "Spellbook", "Component Pouch", "Scholar's Pack"],
+    spells=["Fire Bolt", "Mage Hand", "Magic Missile", "Shield"]
+)
+
+# Global state
+current_character = None
+conversation_history = []
+
+
+def load_character(character_choice):
+    """Load selected character and update context."""
+    global current_character, conversation_history
+
+    conversation_history = []
+
+    if character_choice == "Thorin Stormshield (Dwarf Fighter)":
+        current_character = THORIN
+    else:
+        current_character = ELARA
+
+    # Set GM context
+    char = current_character
+    mods = char.get_modifiers()
+
+    context = f"""The player is {char.name}, a level {char.level} {char.race} {char.character_class}.
+
+PLAYER CHARACTER STATS:
+- HP: {char.hit_points}/{char.hit_points}  |  AC: {char.armor_class}  |  Prof Bonus: +{char.proficiency_bonus}
+- STR: {char.strength} ({mods['strength']:+d})  |  DEX: {char.dexterity} ({mods['dexterity']:+d})  |  CON: {char.constitution} ({mods['constitution']:+d})
+- INT: {char.intelligence} ({mods['intelligence']:+d})  |  WIS: {char.wisdom} ({mods['wisdom']:+d})  |  CHA: {char.charisma} ({mods['charisma']:+d})
+
+EQUIPMENT: {', '.join(char.equipment[:5])}
+"""
+
+    if char.spells:
+        context += f"\nSPELLS: {', '.join(char.spells[:5])}"
+
+    gm.set_context(context)
+
+    # Return character sheet
+    return format_character_sheet(), "", []
+
+
+def format_character_sheet():
+    """Format character sheet for display."""
+    if not current_character:
+        return "No character selected"
+
+    char = current_character
+    mods = char.get_modifiers()
+
+    sheet = f"""# {char.name}
+**{char.race} {char.character_class}, Level {char.level}**
+*{char.background} | {char.alignment}*
+
+---
+
+### Combat Stats
+- **HP**: {char.hit_points}
+- **AC**: {char.armor_class}
+- **Proficiency Bonus**: +{char.proficiency_bonus}
+
+### Ability Scores
+| Ability | Score | Modifier |
+|---------|-------|----------|
+| STR | {char.strength} | {mods['strength']:+d} |
+| DEX | {char.dexterity} | {mods['dexterity']:+d} |
+| CON | {char.constitution} | {mods['constitution']:+d} |
+| INT | {char.intelligence} | {mods['intelligence']:+d} |
+| WIS | {char.wisdom} | {mods['wisdom']:+d} |
+| CHA | {char.charisma} | {mods['charisma']:+d} |
+
+### Equipment
+{chr(10).join('- ' + item for item in char.equipment)}
+
+"""
+
+    if char.spells:
+        sheet += f"""### Spells
+{chr(10).join('- ' + spell for spell in char.spells)}
+"""
+
+    return sheet
+
+
+def chat(message, history):
+    """Handle chat messages."""
+    global conversation_history
+
+    if not current_character:
+        return history + [("Please select a character first!", "")]
+
+    if not message.strip():
+        return history
+
+    # Handle special commands
+    if message.startswith("/"):
+        cmd = message.lower().strip()
+
+        if cmd == "/help":
+            help_text = """**Available Commands:**
+- `/help` - Show this help
+- `/context` - Show current scene context
+- `/stats` - Show character stats
+- `/rag <query>` - Search D&D rules (e.g., `/rag fireball`)
+
+Otherwise, just type your action and press Enter!"""
+            return history + [(message, help_text)]
+
+        elif cmd == "/context":
+            context_text = gm.session.context
+            return history + [(message, f"**Current Context:**\n\n{context_text}")]
+
+        elif cmd == "/stats":
+            stats = format_character_sheet()
+            return history + [(message, stats)]
+
+        elif cmd.startswith("/rag "):
+            query = cmd[5:].strip()
+            if query:
+                results = gm.search_rag(query, n_results=2)
+                formatted = gm.format_rag_context(results)
+                return history + [(message, f"**RAG Search Results:**\n\n{formatted}")]
+            else:
+                return history + [(message, "Usage: `/rag <query>` (e.g., `/rag magic missile`)")]
+
+        else:
+            return history + [(message, f"Unknown command: {cmd}\nType `/help` for available commands")]
+
+    # Generate GM response
+    try:
+        response = gm.generate_response(message, use_rag=True)
+        conversation_history.append((message, response))
+        return history + [(message, response)]
+    except Exception as e:
+        error_msg = f"Error: {str(e)}\n\nMake sure Ollama is running and the model is installed:\n`ollama pull hf.co/Chun121/Qwen3-4B-RPG-Roleplay-V2:Q4_K_M`"
+        return history + [(message, error_msg)]
+
+
+def clear_history():
+    """Clear conversation history."""
+    global conversation_history
+    conversation_history = []
+    return []
+
+
+# Create Gradio interface
+with gr.Blocks(title="D&D RAG Game Master") as demo:
+    gr.Markdown("""
+    # 🎲 D&D Character-Aware Game Master
+
+    Play D&D with an AI Game Master powered by RAG (Retrieval-Augmented Generation) and the Qwen3-4B-RPG-Roleplay model.
+
+    **How to Play:**
+    1. Select a character
+    2. Type your actions (e.g., "I look around", "I cast Magic Missile at the goblin")
+    3. Use `/help` to see available commands
+    """)
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            gr.Markdown("## Character Selection")
+
+            character_dropdown = gr.Dropdown(
+                choices=["Thorin Stormshield (Dwarf Fighter)", "Elara Moonwhisper (Elf Wizard)"],
+                value="Thorin Stormshield (Dwarf Fighter)",
+                label="Choose Your Character"
+            )
+
+            load_btn = gr.Button("Load Character", variant="primary")
+
+            gr.Markdown("---")
+
+            character_sheet = gr.Markdown(format_character_sheet())
+
+        with gr.Column(scale=2):
+            gr.Markdown("## Game Session")
+
+            chatbot = gr.Chatbot(
+                height=500,
+                label="Game Master",
+                show_label=True,
+                avatar_images=(None, "🎭")
+            )
+
+            with gr.Row():
+                msg_input = gr.Textbox(
+                    placeholder="Type your action or command here... (e.g., 'I look around' or '/help')",
+                    label="Your Action",
+                    show_label=False,
+                    scale=4
+                )
+                submit_btn = gr.Button("Send", variant="primary", scale=1)
+
+            with gr.Row():
+                clear_btn = gr.Button("Clear History")
+                gr.Markdown("**Quick Commands:** `/help` | `/context` | `/stats` | `/rag <query>`")
+
+    gr.Markdown("""
+    ---
+
+    ### 📖 Example Actions
+    - "I look around and check my surroundings"
+    - "I draw my weapon and prepare for combat"
+    - "I cast Magic Missile at the goblin" (Elara)
+    - "I attack with my longsword" (Thorin)
+
+    ### 🔍 RAG Commands
+    - `/rag Magic Missile` - Look up spell details
+    - `/rag Goblin` - Look up monster stats
+    - `/rag Fighter` - Look up class features
+
+    **Powered by:** ChromaDB RAG + Ollama (Qwen3-4B-RPG-Roleplay-V2)
+    """)
+
+    # Event handlers
+    load_btn.click(
+        load_character,
+        inputs=[character_dropdown],
+        outputs=[character_sheet, msg_input, chatbot]
+    )
+
+    submit_btn.click(
+        chat,
+        inputs=[msg_input, chatbot],
+        outputs=[chatbot]
+    ).then(
+        lambda: "",
+        outputs=[msg_input]
+    )
+
+    msg_input.submit(
+        chat,
+        inputs=[msg_input, chatbot],
+        outputs=[chatbot]
+    ).then(
+        lambda: "",
+        outputs=[msg_input]
+    )
+
+    clear_btn.click(
+        clear_history,
+        outputs=[chatbot]
+    )
+
+
+if __name__ == "__main__":
+    # Load default character
+    load_character("Thorin Stormshield (Dwarf Fighter)")
+
+    # Launch
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False
+    )

plan_progress.md

@@ -17,6 +17,7 @@
 | **Phase 5: GM Dialogue** | ✅ Complete | 2/2 | RAG-enhanced AI GM working |
 | **Phase 6: Character Creation** | ✅ Complete | 2/2 | Full character creator with RAG |
 | **Phase 7: Testing & Validation** | ✅ Complete | 3/3 | 26+ comprehensive tests passing |
+| **Phase 8: Game Mechanics Engine** | 🚧 In Progress | 0/5 | Character-aware gameplay enhancements |
 
 **Legend**: ✅ Complete | 🚧 In Progress | ⏳ Pending | ❌ Blocked
 
@@ -223,6 +224,97 @@ python query_rag.py --monster "dragon" # Search monsters
 
 ---
 
+## 🎮 Phase 8: Game Mechanics Engine 🚧 IN PROGRESS
+
+**Goal**: Transform AI from rule-maker to narrator by implementing programmatic game mechanics
+
+### ✅ 8.0 Character-Aware Dialogue System **⭐ NEW!**
+**File**: `play_with_character.py`
+- [x] Load or create characters for gameplay
+- [x] Character context passed to GM (stats, equipment, spells)
+- [x] Three character modes: Create new, Load JSON, Quick test
+- [x] Commands: `/character`, `/stats`, `/context` for character info
+- [x] Fixed tokenizer warning suppression
+- [x] Dynamic character support (not hardcoded to one character)
+- [x] Proper first/second person context ("The player is X" → AI uses "you")
+- [x] Integration testing completed (Dec 1, 2024)
+
+### 🚧 8.1 Spell System Enhancement
+**File**: `play_with_character.py` (to be refactored)
+- [ ] Programmatic spell validation (check if player owns spell)
+- [ ] Spell slot tracking by level (1st: 3 slots, 2nd: 2 slots, etc.)
+- [ ] Auto-decrement slots when casting
+- [ ] Rest mechanic to restore slots
+- [ ] Spell lookup from RAG before AI narration
+
+### 🚧 8.2 Combat Mechanics
+**Status**: ⏳ Pending
+- [ ] HP tracking and damage application
+- [ ] Attack roll automation (d20 + modifiers)
+- [ ] Damage roll automation (weapon dice + STR/DEX)
+- [ ] AC checks (hit/miss determination)
+- [ ] Death saves and unconsciousness
+
+### 🚧 8.3 Turn & Initiative System
+**Status**: ⏳ Pending
+- [ ] Initiative roller (d20 + DEX modifier)
+- [ ] Turn order tracking
+- [ ] Action economy (action, bonus action, movement, reaction)
+- [ ] Combat state management
+
+### 🚧 8.4 Inventory System
+**Status**: ⏳ Pending
+- [ ] Add/remove items programmatically
+- [ ] Equipment weight tracking
+- [ ] Item usage validation
+- [ ] Gold/currency management
+
+### 🚧 8.5 Integration & Testing
+**Status**: ⏳ Pending
+- [ ] Test spell casting flow end-to-end
+- [ ] Test combat scenarios
+- [ ] Test inventory management
+- [ ] Update documentation
+
+---
+
+## 🏗️ Phase 8 Architecture Notes
+
+### Option B: Hybrid AI + Rules Engine (SELECTED)
+
+**Problem**: AI is unreliable at following D&D rules consistently
+- Ignores spells player casts
+- Allows spells player doesn't know
+- Doesn't track resources (HP, spell slots)
+- Makes up mechanics on the fly
+
+**Solution**: Intercept player actions BEFORE AI sees them
+
+**Flow**:
+1. **Player Input**: "I cast Magic Missile at the goblin"
+2. **Rules Engine** (Python code):
+   - Parse: Detect spell casting intent
+   - Validate: Check if player owns "Magic Missile" ✓
+   - Validate: Check if player has 1st-level spell slot ✓
+   - Retrieve: Get spell details from RAG (3 darts, 1d4+1 each)
+   - Roll: 3d4+3 = 11 damage (programmatically)
+   - Deduct: Spell slot consumed
+   - Update: Target HP reduced by 11
+3. **AI Prompt**: "You successfully cast Magic Missile dealing 11 force damage to the goblin. The goblin now has 5 HP remaining. Describe the magical missiles striking the goblin."
+4. **AI Response**: (Just narrates the flavor, mechanics already handled)
+
+**Benefits**:
+- AI becomes a **narrator**, not a **rules engine**
+- Mechanics are deterministic and accurate
+- AI can focus on storytelling
+- Players can trust the rules
+
+**Alternatives Rejected**:
+- **Option A** (Pure AI): Too unreliable, tested and failed
+- **Option C** (Post-process AI): Too hard to fix bad outputs
+
+---
+
 ## 📦 Supporting Files ✅ COMPLETE
 
 ### ✅ Dependencies
@@ -295,10 +387,20 @@ python query_rag.py --monster "dragon" # Search monsters
 5. ✅ **Interactive Query Tool** - New CLI for exploring the RAG system
 6. ✅ **Comprehensive Tests** - 26+ automated tests validating all functionality
 
-### Known Issues
-- None currently
+### Known Issues (Phase 8 Discovery - Dec 1, 2024)
+- **AI Unreliability**: Pure AI approach fails to consistently enforce D&D rules
+  - Ignores valid spell casts (Magic Missile cast was turned into melee combat)
+  - Allows invalid spells (Let Elara cast Fireball, which she doesn't know)
+  - No resource tracking (spell slots, HP, gold)
+- **Solution**: Moving to Hybrid Architecture (Option B) with programmatic rules engine
+
+### Current Work (Phase 8)
+- 🚧 **Spell Validation System**: Programmatically check spell ownership before AI generation
+- 🚧 **Resource Tracking**: HP, spell slots, inventory management
+- 🚧 **Combat Mechanics**: Attack/damage rolls, initiative, turn tracking
+- 🚧 **Rules Engine**: Intercept player actions, apply mechanics, then AI narrates
 
-### Future Enhancements
+### Future Enhancements (Post-Phase 8)
 - ⏳ **Subrace Support**: High Elf, Mountain Dwarf, etc. with specific abilities
 - ⏳ **Advanced Filtering**: Search by CR range, spell level range, class, type
 - ⏳ **Web UI**: Web interface for GM dialogue
@@ -318,7 +420,10 @@ python query_rag.py --monster "dragon" # Search monsters
 | 2024-11-06 15:00 | Phase 3-6 complete (initialization, query, GM, character creator) |
 | 2024-11-06 18:00 | **Major upgrades**: Name weighting, race extraction, comprehensive tests |
 | 2024-11-06 20:00 | **Phase 7 complete**: All tests passing, documentation updated |
-| 2024-11-06 21:00 | **PROJECT COMPLETE** - Production ready! |
+| 2024-11-06 21:00 | **V1.0 COMPLETE** - Production ready! |
+| 2024-12-01 18:00 | **Phase 8 started**: Character-aware dialogue system created |
+| 2024-12-01 19:00 | Testing reveals AI reliability issues with game mechanics |
+| 2024-12-01 19:30 | **Architecture decision**: Option B (Hybrid Rules Engine) selected |
 
 ---
 
@@ -354,9 +459,15 @@ python query_rag.py --monster "dragon" # Search monsters
 
 ---
 
-**Status**: ✅ **PRODUCTION READY**
-**Next Steps**: Deploy, gather user feedback, plan Phase 8 enhancements
+**Status**: 🚧 **V2.0 IN DEVELOPMENT** (Phase 8: Game Mechanics Engine)
+**Current Focus**: Implementing hybrid AI + Rules Engine architecture
+**Next Steps**:
+1. Spell validation system
+2. Spell slot tracking
+3. HP and damage mechanics
+4. Combat turn system
+5. Inventory management
 
 ---
 
-**Last Updated**: November 6, 2024 21:00
+**Last Updated**: December 1, 2024 19:30

play_with_character.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""
+D&D Character-Aware Game Session
+
+Integrated test script that:
+1. Creates or loads a character
+2. Starts a GM dialogue session with character context
+3. Allows playing with character stats visible to GM
+"""
+
+import os
+# Suppress tokenizer warning when forking subprocess
+os.environ['TOKENIZERS_PARALLELISM'] = 'false'
+
+import sys
+import json
+from pathlib import Path
+
+# Add project to path
+sys.path.insert(0, str(Path(__file__).parent))
+
+from dnd_rag_system.core.chroma_manager import ChromaDBManager
+from dnd_rag_system.systems.character_creator import CharacterCreator, Character
+from dnd_rag_system.systems.gm_dialogue import GameMaster, InteractiveGM
+
+
+class CharacterAwareGM(InteractiveGM):
+    """
+    Enhanced GM that knows about the player's character.
+
+    Extends InteractiveGM to include character information in prompts.
+    """
+
+    def __init__(self, gm: GameMaster, character: Character):
+        """Initialize with character context."""
+        super().__init__(gm)
+        self.character = character
+
+        # Set initial scene with character info
+        self._initialize_character_context()
+
+    def _initialize_character_context(self):
+        """Add character to GM's context."""
+        char = self.character
+        mods = char.get_modifiers()
+
+        context = f"""The player is {char.name}, a level {char.level} {char.race} {char.character_class}.
+
+PLAYER CHARACTER STATS:
+- HP: {char.hit_points}/{char.hit_points}  |  AC: {char.armor_class}  |  Prof Bonus: +{char.proficiency_bonus}
+- STR: {char.strength} ({mods['strength']:+d})  |  DEX: {char.dexterity} ({mods['dexterity']:+d})  |  CON: {char.constitution} ({mods['constitution']:+d})
+- INT: {char.intelligence} ({mods['intelligence']:+d})  |  WIS: {char.wisdom} ({mods['wisdom']:+d})  |  CHA: {char.charisma} ({mods['charisma']:+d})
+
+EQUIPMENT: {', '.join(char.equipment[:5])}
+"""
+
+        if char.spells:
+            context += f"\nSPELLS: {', '.join(char.spells[:5])}"
+
+        self.gm.set_context(context)
+
+    def print_help(self):
+        """Override help to add character commands."""
+        super().print_help()
+        print("\nCHARACTER COMMANDS:")
+        print("  /character     - Show character sheet")
+        print("  /stats         - Quick stats view")
+        print()
+
+    def run(self):
+        """Override run to handle character commands."""
+        print("\n" + "="*70)
+        print(f"🎲 D&D GAME SESSION - Playing as {self.character.name}")
+        print("="*70)
+        print(f"Character: {self.character.name} ({self.character.race} {self.character.character_class})")
+        print(f"Model: {self.gm.model_name}")
+        print(f"Database: {self.gm.db.persist_dir}")
+        print("\nType /help for commands or start playing!")
+        print("="*70)
+
+        self.running = True
+        use_rag_next = True
+
+        while self.running:
+            try:
+                # Get player input
+                player_input = input(f"\n🎲 {self.character.name}: ").strip()
+
+                if not player_input:
+                    continue
+
+                # Handle commands
+                if player_input.startswith('/'):
+                    # Check for character-specific commands first
+                    if player_input.lower() == '/character':
+                        self._show_character_sheet()
+                        continue
+                    elif player_input.lower() == '/stats':
+                        self._show_quick_stats()
+                        continue
+                    else:
+                        # Use parent's command handler
+                        self._handle_command(player_input)
+                        continue
+
+                # Generate GM response
+                print("\n🎭 GM: ", end="", flush=True)
+                response = self.gm.generate_response(player_input, use_rag=use_rag_next)
+                print(response)
+
+                # Reset RAG flag
+                use_rag_next = True
+
+            except KeyboardInterrupt:
+                print("\n\n👋 Game interrupted. Type /quit to exit or continue playing.")
+            except Exception as e:
+                print(f"\n❌ Error: {e}")
+
+    def _show_character_sheet(self):
+        """Display full character sheet."""
+        char = self.character
+        mods = char.get_modifiers()
+
+        print("\n" + "="*70)
+        print(f"CHARACTER SHEET - {char.name}")
+        print("="*70)
+        print(f"{char.race} {char.character_class}, Level {char.level}")
+        print(f"{char.background} | {char.alignment}")
+        print("\n" + "─"*70)
+
+        print("\nABILITY SCORES:")
+        print(f"  STR: {char.strength:2d} ({mods['strength']:+d})  |  INT: {char.intelligence:2d} ({mods['intelligence']:+d})")
+        print(f"  DEX: {char.dexterity:2d} ({mods['dexterity']:+d})  |  WIS: {char.wisdom:2d} ({mods['wisdom']:+d})")
+        print(f"  CON: {char.constitution:2d} ({mods['constitution']:+d})  |  CHA: {char.charisma:2d} ({mods['charisma']:+d})")
+
+        print(f"\nCOMBAT STATS:")
+        print(f"  HP: {char.hit_points}  |  AC: {char.armor_class}  |  Proficiency: +{char.proficiency_bonus}")
+
+        print(f"\nEQUIPMENT:")
+        for item in char.equipment:
+            print(f"  - {item}")
+
+        if char.spells:
+            print(f"\nSPELLS:")
+            for spell in char.spells:
+                print(f"  - {spell}")
+
+        print("="*70)
+
+    def _show_quick_stats(self):
+        """Show condensed stats."""
+        char = self.character
+        mods = char.get_modifiers()
+
+        print(f"\n📊 {char.name} | HP: {char.hit_points} | AC: {char.armor_class} | Prof: +{char.proficiency_bonus}")
+        print(f"   STR {mods['strength']:+d} | DEX {mods['dexterity']:+d} | CON {mods['constitution']:+d} | INT {mods['intelligence']:+d} | WIS {mods['wisdom']:+d} | CHA {mods['charisma']:+d}")
+
+
+def load_character_from_json(filepath: str) -> Character:
+    """Load character from JSON file."""
+    with open(filepath, 'r') as f:
+        data = json.load(f)
+
+    # Create Character object from dict
+    char = Character()
+    for key, value in data.items():
+        if hasattr(char, key):
+            setattr(char, key, value)
+
+    return char
+
+
+def main():
+    """Main entry point for character-aware game session."""
+    print("\n" + "="*70)
+    print("🎲 D&D CHARACTER-AWARE GAME SESSION")
+    print("="*70)
+
+    try:
+        # Initialize ChromaDB
+        print("\n📚 Connecting to D&D knowledge base...")
+        db = ChromaDBManager()
+
+        # Character selection
+        print("\n" + "─"*70)
+        print("CHARACTER SELECTION")
+        print("─"*70)
+        print("\n1. Create new character")
+        print("2. Load existing character")
+        print("3. Use test character (quick start)")
+
+        choice = input("\nSelect option (1-3): ").strip()
+
+        if choice == "1":
+            # Create new character
+            print("\n🎭 Starting character creator...")
+            creator = CharacterCreator(db)
+            character = creator.create_character_interactive()
+
+            # Save option
+            save = input("\nSave character? (y/n): ").strip().lower()
+            if save == 'y':
+                filename = input("Filename (e.g., aragorn.json): ").strip()
+                if not filename.endswith('.json'):
+                    filename += '.json'
+                character.to_json(filename)
+
+        elif choice == "2":
+            # Load existing character
+            filename = input("\nCharacter filename: ").strip()
+            if not filename.endswith('.json'):
+                filename += '.json'
+
+            character = load_character_from_json(filename)
+            print(f"\n✅ Loaded: {character.name} ({character.race} {character.character_class})")
+
+        else:
+            # Quick test character
+            print("\n⚡ Creating test character...")
+            character = Character(
+                name="Thorin Stormshield",
+                race="Dwarf",
+                character_class="Fighter",
+                level=3,
+                strength=16,
+                dexterity=12,
+                constitution=16,
+                intelligence=10,
+                wisdom=13,
+                charisma=8,
+                hit_points=28,
+                armor_class=18,
+                proficiency_bonus=2,
+                background="Soldier",
+                alignment="Lawful Good",
+                race_traits=["Dwarven Resilience", "Darkvision"],
+                class_features=["Fighting Style: Defense", "Second Wind", "Action Surge"],
+                proficiencies=["All armor", "All weapons", "Shields"],
+                equipment=["Longsword", "Shield", "Plate Armor", "Backpack", "50 GP"],
+                spells=[]
+            )
+            print(f"✅ Created: {character.name} - a battle-ready dwarf fighter!")
+
+        # Initialize Game Master with character
+        print("\n🎭 Initializing AI Game Master...")
+        gm = GameMaster(db)
+
+        print("✅ Game Master ready!")
+
+        # Start character-aware session
+        interactive = CharacterAwareGM(gm, character)
+        interactive.run()
+
+    except FileNotFoundError as e:
+        print(f"\n❌ Character file not found: {e}")
+        return 1
+    except Exception as e:
+        print(f"\n❌ Failed to initialize: {e}")
+        print("\nTroubleshooting:")
+        print("  1. Run: python initialize_rag.py")
+        print("  2. Install Ollama: https://ollama.ai")
+        print("  3. Download model: ollama pull hf.co/Chun121/Qwen3-4B-RPG-Roleplay-V2:Q4_K_M")
+        return 1
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

requirements.txt

@@ -9,6 +9,9 @@ pdfplumber>=0.10.0
 # Ollama Python client
 ollama>=0.1.0
 
+# Web UI
+gradio>=4.0.0
+
 # Rich console output
 rich>=13.0.0