refactor: Reorganize project structure and enhance Gradio app

**Project Structure:**
- Created organized directory structure (characters/, tests/, docs/, web/)
- Moved test files to tests/ directory with updated imports
- Moved documentation to docs/ directory
- Moved Gradio apps to web/ directory
- Created characters/ directory for JSON character files

**Character System:**
- Added image_path field to Character class (placeholder for future GAN generation)
- Exported Thorin and Elara as JSON files in characters/ directory
- Characters now loaded from JSON files instead of hardcoded

**Gradio App Enhancements:**
- Added character creation tab with full interactive UI
- Character creator includes: race, class, ability scores, background, alignment
- Equipment auto-assigned based on class
- Character image display (placeholder for future GAN)
- Characters now dynamically loaded from JSON files
- Improved UI with tabs for Play Game and Create Character

**Docker Updates:**
- Updated start.sh to point to web/app_gradio.py
- Maintained Docker compatibility with new structure

**Testing:**
- All tests passing (20/20)
- Updated test imports for new directory structure
- Fixed syntax error in test_all_collections.py

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

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

characters/elara_moonwhisper.json

@@ -0,0 +1,43 @@
+{
+  "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"
+  ],
+  "image_path": null
+}

characters/thorin_stormshield.json

@@ -0,0 +1,40 @@
+{
+  "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": [],
+  "image_path": null
+}

dnd_rag_system/systems/character_creator.py

@@ -52,6 +52,9 @@ class Character:
     equipment: List[str] = field(default_factory=list)
     spells: List[str] = field(default_factory=list)
 
+    # Character Image (for future GAN generation)
+    image_path: Optional[str] = None
+
     def get_ability_modifier(self, score: int) -> int:
         """Calculate ability modifier from score."""
         return (score - 10) // 2

start.sh

@@ -19,4 +19,4 @@ fi
 
 # Start the Gradio application
 echo "Starting Gradio app..."
-python app_gradio.py
+python web/app_gradio.py

test_all_collections.py → tests/test_all_collections.py

@@ -11,7 +11,7 @@ from pathlib import Path
 from typing import Dict, List, Tuple
 
 # Add project to path
-project_root = Path(__file__).parent
+project_root = Path(__file__).parent.parent
 sys.path.insert(0, str(project_root))
 
 from dnd_rag_system.core.chroma_manager import ChromaDBManager
@@ -349,10 +349,11 @@ class RAGTestSuite:
             found_darkvision = any(meta.get('darkvision', 0) > 0
                                   for meta in results['metadatas'][0])
 
+            darkvision_races = [f"{m.get('name')} ({m.get('darkvision')}ft)" for m in results['metadatas'][0][:3] if m.get('darkvision', 0) > 0]
             self.assert_test(
                 "Race: Trait search finds races with darkvision",
                 found_darkvision,
-                f"Races: {[f\"{m.get('name')} ({m.get('darkvision')}ft)\" for m in results['metadatas'][0][:3] if m.get('darkvision', 0) > 0]}"
+                f"Races: {darkvision_races}"
             )
         else:
             self.assert_test(

test_entity_retrieval.py → tests/test_entity_retrieval.py

@@ -24,7 +24,7 @@ from pathlib import Path
 from typing import List, Dict, Set
 
 # Add project to path
-project_root = Path(__file__).parent
+project_root = Path(__file__).parent.parent
 sys.path.insert(0, str(project_root))
 
 from dnd_rag_system.core.chroma_manager import ChromaDBManager

test_spell_retrieval.py → tests/test_spell_retrieval.py

@@ -15,7 +15,7 @@ from pathlib import Path
 from typing import List, Dict, Tuple
 
 # Add project to path
-project_root = Path(__file__).parent
+project_root = Path(__file__).parent.parent
 sys.path.insert(0, str(project_root))
 
 from dnd_rag_system.core.chroma_manager import ChromaDBManager

test_spell_search.py → tests/test_spell_search.py

@@ -7,7 +7,7 @@ import sys
 from pathlib import Path
 
 # Add project to path
-project_root = Path(__file__).parent
+project_root = Path(__file__).parent.parent
 sys.path.insert(0, str(project_root))
 
 from dnd_rag_system.core.chroma_manager import ChromaDBManager

app_gradio.py → web/app_gradio.py

@@ -3,6 +3,7 @@
 D&D Character-Aware Game - Gradio Web Interface
 
 Web UI for playing D&D with RAG-enhanced AI GM and character tracking.
+Includes character creation, loading, and image display.
 """
 
 import os
@@ -12,83 +13,97 @@ os.environ['TOKENIZERS_PARALLELISM'] = 'false'
 import gradio as gr
 import json
 from pathlib import Path
+from typing import Optional, List, Tuple
+from dataclasses import asdict
 
 # Add project to path
 import sys
-sys.path.insert(0, str(Path(__file__).parent))
+sys.path.insert(0, str(Path(__file__).parent.parent))
 
 from dnd_rag_system.core.chroma_manager import ChromaDBManager
-from dnd_rag_system.systems.character_creator import Character
+from dnd_rag_system.systems.character_creator import Character, CharacterCreator
 from dnd_rag_system.systems.gm_dialogue_unified import GameMaster
-
+from dnd_rag_system.config import settings
 
 # 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"]
-)
+# Paths
+CHARACTERS_DIR = Path(__file__).parent.parent / "characters"
+CHARACTERS_DIR.mkdir(exist_ok=True)
 
 # Global state
 current_character = None
 conversation_history = []
 
 
-def load_character(character_choice):
+def load_character_from_json(filepath: Path) -> Optional[Character]:
+    """Load character from JSON file."""
+    try:
+        with open(filepath, 'r') as f:
+            data = json.load(f)
+        return Character(**data)
+    except Exception as e:
+        print(f"Error loading character from {filepath}: {e}")
+        return None
+
+
+def save_character_to_json(character: Character, filename: str) -> str:
+    """Save character to JSON file."""
+    filepath = CHARACTERS_DIR / filename
+    try:
+        with open(filepath, 'w') as f:
+            json.dump(asdict(character), f, indent=2)
+        return str(filepath)
+    except Exception as e:
+        return f"Error saving character: {e}"
+
+
+def get_available_characters() -> List[str]:
+    """Get list of available character files."""
+    characters = []
+
+    # Load pre-made characters
+    thorin_path = CHARACTERS_DIR / "thorin_stormshield.json"
+    elara_path = CHARACTERS_DIR / "elara_moonwhisper.json"
+
+    if thorin_path.exists():
+        characters.append("Thorin Stormshield (Dwarf Fighter)")
+    if elara_path.exists():
+        characters.append("Elara Moonwhisper (Elf Wizard)")
+
+    # Load custom characters
+    for json_file in CHARACTERS_DIR.glob("*.json"):
+        if json_file.name not in ["thorin_stormshield.json", "elara_moonwhisper.json"]:
+            char = load_character_from_json(json_file)
+            if char:
+                characters.append(f"{char.name} ({char.race} {char.character_class})")
+
+    return characters
+
+
+def load_character(character_choice: str) -> Tuple[str, str, list, Optional[str]]:
     """Load selected character and update context."""
     global current_character, conversation_history
 
     conversation_history = []
 
-    if character_choice == "Thorin Stormshield (Dwarf Fighter)":
-        current_character = THORIN
+    # Map character choice to file
+    if "Thorin" in character_choice:
+        filepath = CHARACTERS_DIR / "thorin_stormshield.json"
+    elif "Elara" in character_choice:
+        filepath = CHARACTERS_DIR / "elara_moonwhisper.json"
     else:
-        current_character = ELARA
+        # Try to find by character name
+        name = character_choice.split("(")[0].strip()
+        filepath = CHARACTERS_DIR / f"{name.lower().replace(' ', '_')}.json"
+
+    current_character = load_character_from_json(filepath)
+
+    if not current_character:
+        return "Error loading character", "", [], None
 
     # Set GM context
     char = current_character
@@ -109,11 +124,16 @@ EQUIPMENT: {', '.join(char.equipment[:5])}
 
     gm.set_context(context)
 
-    # Return character sheet
-    return format_character_sheet(), "", []
+    # Get character image if exists
+    char_image = None
+    if char.image_path and Path(char.image_path).exists():
+        char_image = char.image_path
+
+    # Return character sheet, clear input, empty chat, and image
+    return format_character_sheet(), "", [], char_image
 
 
-def format_character_sheet():
+def format_character_sheet() -> str:
     """Format character sheet for display."""
     if not current_character:
         return "No character selected"
@@ -155,7 +175,78 @@ def format_character_sheet():
     return sheet
 
 
-def chat(message, history):
+def create_character(name: str, race: str, char_class: str, background: str,
+                     alignment: str, str_val: int, dex_val: int, con_val: int,
+                     int_val: int, wis_val: int, cha_val: int) -> Tuple[str, str]:
+    """Create a new character with given parameters."""
+    global current_character
+
+    if not name:
+        return "❌ Please enter a character name", gr.update()
+
+    # Create character
+    character = Character(
+        name=name,
+        race=race,
+        character_class=char_class,
+        level=1,
+        strength=str_val,
+        dexterity=dex_val,
+        constitution=con_val,
+        intelligence=int_val,
+        wisdom=wis_val,
+        charisma=cha_val,
+        background=background,
+        alignment=alignment
+    )
+
+    # Calculate derived stats
+    hit_die_map = {
+        "Wizard": 6, "Sorcerer": 6,
+        "Rogue": 8, "Bard": 8, "Cleric": 8, "Druid": 8, "Monk": 8, "Warlock": 8,
+        "Fighter": 10, "Paladin": 10, "Ranger": 10,
+        "Barbarian": 12
+    }
+    hit_die = hit_die_map.get(char_class, 8)
+    character.hit_points = character.calculate_hit_points(hit_die)
+
+    dex_mod = character.get_ability_modifier(dex_val)
+    character.armor_class = 10 + dex_mod
+
+    # Add basic equipment
+    equipment_map = {
+        "Fighter": ["Longsword", "Shield", "Chainmail", "Backpack", "50 GP"],
+        "Wizard": ["Quarterstaff", "Spellbook", "Robes", "Component Pouch", "25 GP"],
+        "Rogue": ["Shortsword", "Leather Armor", "Thieves' Tools", "Backpack", "40 GP"],
+        "Cleric": ["Mace", "Shield", "Chainmail", "Holy Symbol", "30 GP"],
+        "Paladin": ["Longsword", "Shield", "Plate Armor", "Holy Symbol", "40 GP"],
+        "Ranger": ["Longbow", "Arrows (20)", "Leather Armor", "Backpack", "40 GP"],
+        "Barbarian": ["Greataxe", "Javelin (4)", "Leather Armor", "Backpack", "50 GP"],
+        "Bard": ["Rapier", "Lute", "Leather Armor", "Backpack", "35 GP"],
+        "Sorcerer": ["Quarterstaff", "Component Pouch", "Robes", "Backpack", "30 GP"],
+        "Warlock": ["Dagger", "Component Pouch", "Leather Armor", "Backpack", "35 GP"],
+        "Druid": ["Quarterstaff", "Druidic Focus", "Leather Armor", "Backpack", "30 GP"],
+        "Monk": ["Quarterstaff", "Darts (10)", "Robes", "Backpack", "20 GP"]
+    }
+    character.equipment = equipment_map.get(char_class, ["Basic gear", "50 GP"])
+
+    # Save character
+    filename = f"{name.lower().replace(' ', '_')}.json"
+    save_result = save_character_to_json(character, filename)
+
+    # Set as current character
+    current_character = character
+
+    # Update character list
+    new_choices = get_available_characters()
+
+    return (
+        f"✅ Character '{name}' created successfully!\nSaved to: {save_result}",
+        gr.update(choices=new_choices, value=f"{name} ({race} {char_class})")
+    )
+
+
+def chat(message: str, history: list) -> list:
     """Handle chat messages."""
     global conversation_history
 
@@ -239,7 +330,7 @@ Otherwise, just type your action and press Enter!"""
         ]
 
 
-def clear_history():
+def clear_history() -> list:
     """Clear conversation history."""
     global conversation_history
     conversation_history = []
@@ -247,78 +338,144 @@ def clear_history():
 
 
 # Create Gradio interface
-with gr.Blocks(title="D&D RAG Game Master") as demo:
+with gr.Blocks(title="D&D RAG Game Master", theme=gr.themes.Soft()) 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.
+    Play D&D with an AI Game Master powered by RAG (Retrieval-Augmented Generation).
 
-    **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
+    **Features:**
+    - Play as pre-made characters (Thorin, Elara)
+    - Create your own custom characters
+    - Character images (placeholder for future GAN generation)
+    - RAG-powered rule lookups
     """)
 
-    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
-            )
-
+    with gr.Tabs():
+        # Tab 1: Play Game
+        with gr.Tab("🎮 Play Game"):
             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.Column(scale=1):
+                    gr.Markdown("## Character")
+
+                    character_dropdown = gr.Dropdown(
+                        choices=get_available_characters(),
+                        value=get_available_characters()[0] if get_available_characters() else None,
+                        label="Choose Your Character"
+                    )
+
+                    load_btn = gr.Button("Load Character", variant="primary")
+
+                    # Character Image
+                    char_image = gr.Image(
+                        label="Character Portrait",
+                        type="filepath",
+                        interactive=False,
+                        height=200
+                    )
+
+                    gr.Markdown("*Image will be generated via GAN in future update*")
+
+                    gr.Markdown("---")
+
+                    character_sheet = gr.Markdown("No character loaded")
+
+                with gr.Column(scale=2):
+                    gr.Markdown("## Game Session")
+
+                    chatbot = gr.Chatbot(
+                        height=500,
+                        label="Game Master",
+                        show_label=True
+                    )
+
+                    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"
+            - "I attack with my longsword"
+
+            ### 🔍 RAG Commands
+            - `/rag Magic Missile` - Look up spell details
+            - `/rag Goblin` - Look up monster stats
+            - `/rag Fighter` - Look up class features
+            """)
+
+        # Tab 2: Create Character
+        with gr.Tab("✨ Create Character"):
+            gr.Markdown("""
+            ## Create Your D&D Character
+
+            Fill in the fields below to create a new character. Your character will be saved and available in the character dropdown.
+            """)
 
             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 + AI Language Model (Auto-detected: Ollama locally, HF Inference API on Spaces)
-    """)
-
-    # Event handlers
+                with gr.Column():
+                    char_name = gr.Textbox(label="Character Name", placeholder="e.g., Gandalf the Grey")
+
+                    with gr.Row():
+                        char_race = gr.Dropdown(
+                            choices=settings.DND_RACES,
+                            value="Human",
+                            label="Race"
+                        )
+                        char_class = gr.Dropdown(
+                            choices=settings.DND_CLASSES,
+                            value="Fighter",
+                            label="Class"
+                        )
+
+                    with gr.Row():
+                        char_background = gr.Textbox(label="Background", placeholder="e.g., Soldier, Sage, Folk Hero")
+                        char_alignment = gr.Textbox(label="Alignment", placeholder="e.g., Lawful Good, Chaotic Neutral")
+
+                with gr.Column():
+                    gr.Markdown("### Ability Scores")
+                    gr.Markdown("*Standard array: 15, 14, 13, 12, 10, 8*")
+
+                    with gr.Row():
+                        str_slider = gr.Slider(minimum=3, maximum=20, value=10, step=1, label="Strength")
+                        dex_slider = gr.Slider(minimum=3, maximum=20, value=10, step=1, label="Dexterity")
+
+                    with gr.Row():
+                        con_slider = gr.Slider(minimum=3, maximum=20, value=10, step=1, label="Constitution")
+                        int_slider = gr.Slider(minimum=3, maximum=20, value=10, step=1, label="Intelligence")
+
+                    with gr.Row():
+                        wis_slider = gr.Slider(minimum=3, maximum=20, value=10, step=1, label="Wisdom")
+                        cha_slider = gr.Slider(minimum=3, maximum=20, value=10, step=1, label="Charisma")
+
+            create_btn = gr.Button("Create Character", variant="primary", size="lg")
+            create_output = gr.Textbox(label="Status", interactive=False)
+
+            gr.Markdown("""
+            ---
+
+            **Note:** Equipment and spells will be automatically assigned based on your class.
+            Character images can be added later via the GAN generation feature (coming soon).
+            """)
+
+    # Event handlers - Play Game Tab
     load_btn.click(
         load_character,
         inputs=[character_dropdown],
-        outputs=[character_sheet, msg_input, chatbot]
+        outputs=[character_sheet, msg_input, chatbot, char_image]
     )
 
     submit_btn.click(
@@ -344,11 +501,18 @@ with gr.Blocks(title="D&D RAG Game Master") as demo:
         outputs=[chatbot]
     )
 
+    # Event handlers - Create Character Tab
+    create_btn.click(
+        create_character,
+        inputs=[
+            char_name, char_race, char_class, char_background, char_alignment,
+            str_slider, dex_slider, con_slider, int_slider, wis_slider, cha_slider
+        ],
+        outputs=[create_output, character_dropdown]
+    )
 
-if __name__ == "__main__":
-    # Load default character
-    load_character("Thorin Stormshield (Dwarf Fighter)")
 
+if __name__ == "__main__":
     # Launch
     demo.launch(
         server_name="0.0.0.0",