Deploy D&D Campaign Manager v2

- Complete AI-powered D&D 5e character creator
- Autonomous campaign synthesis from party composition
- Session auto-generation with context from uploaded notes
- MCP server with 7 D&D 5e rules tools
- Campaign and session tracking
- Character export to formatted sheets
- Support for Claude, GPT-4, and Gemini

Features:
✨ Campaign synthesis (autonomous AI)
📖 Session auto-generation
🎯 Encounter balancing (MCP tools)
🧙 Character creation with AI backstories
📝 Session notes parsing and context integration

.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Environment
+.env
+*.env
+!.env.example
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/

DEPLOY_HF.md

@@ -0,0 +1,403 @@
+# 🚀 Deploying to Hugging Face Spaces
+
+Complete guide to deploying your D&D Campaign Manager to Hugging Face Spaces.
+
+## 📋 Pre-Deployment Checklist
+
+Before deploying, ensure you have:
+
+- [ ] Hugging Face account (free at https://huggingface.co)
+- [ ] API keys for at least one AI provider:
+  - Anthropic (recommended): https://console.anthropic.com
+  - OpenAI: https://platform.openai.com
+  - Google AI: https://makersuite.google.com
+
+## 🎯 Quick Deploy (Recommended)
+
+### Option 1: Upload Files to New Space
+
+1. **Create a New Space**
+   - Go to https://huggingface.co/new-space
+   - Space name: `dnd-campaign-manager` (or your choice)
+   - SDK: **Gradio**
+   - Visibility: **Public** (or Private)
+   - Click **Create Space**
+
+2. **Upload Files**
+
+   Upload these files from your project:
+
+   **Required Files:**
+   ```
+   app_v2.py                  # Main application
+   README_HF.md               # Space description (rename to README.md)
+   requirements_hf.txt        # Dependencies (rename to requirements.txt)
+   .env.example              # Environment variable template
+
+   src/                       # Entire src directory
+   mcp_server/               # Entire mcp_server directory
+   data/                      # Create empty folder for database
+   ```
+
+   **File Operations:**
+   - Rename `README_HF.md` → `README.md`
+   - Rename `requirements_hf.txt` → `requirements.txt`
+
+3. **Set Environment Variables (Secrets)**
+
+   In your Space settings → **Variables and secrets**:
+
+   Add at least ONE of these:
+   ```
+   ANTHROPIC_API_KEY = sk-ant-...
+   OPENAI_API_KEY = sk-...
+   GOOGLE_API_KEY = AIza...
+   ```
+
+   Optional variables:
+   ```
+   HUGGINGFACE_API_KEY = hf_...
+   PRIMARY_MODEL_PROVIDER = anthropic
+   PRIMARY_MODEL = claude-3-5-sonnet-20241022
+   ```
+
+4. **Wait for Build**
+   - HF Spaces will automatically install dependencies
+   - Build takes ~3-5 minutes
+   - Your app will be live at: `https://huggingface.co/spaces/YOUR_USERNAME/dnd-campaign-manager`
+
+## 🔧 Option 2: Git Push (Advanced)
+
+### Step 1: Clone Your Space
+
+```bash
+# Install git-lfs if you haven't
+git lfs install
+
+# Clone your space
+git clone https://huggingface.co/spaces/YOUR_USERNAME/dnd-campaign-manager
+cd dnd-campaign-manager
+```
+
+### Step 2: Copy Files
+
+```bash
+# From your dungeon-smasher-pro directory:
+cp app_v2.py path/to/dnd-campaign-manager/
+cp README_HF.md path/to/dnd-campaign-manager/README.md
+cp requirements_hf.txt path/to/dnd-campaign-manager/requirements.txt
+cp .env.example path/to/dnd-campaign-manager/
+
+# Copy directories
+cp -r src path/to/dnd-campaign-manager/
+cp -r mcp_server path/to/dnd-campaign-manager/
+mkdir -p path/to/dnd-campaign-manager/data
+```
+
+### Step 3: Commit and Push
+
+```bash
+cd path/to/dnd-campaign-manager
+
+git add .
+git commit -m "Initial deployment of D&D Campaign Manager"
+git push
+```
+
+### Step 4: Configure Secrets
+
+Go to your Space settings and add API keys as secrets (see Option 1, step 3).
+
+## 📁 Final Directory Structure on HF Space
+
+```
+dnd-campaign-manager/          # Your HF Space root
+├── README.md                  # Renamed from README_HF.md
+├── requirements.txt           # Renamed from requirements_hf.txt
+├── app_v2.py                  # Main app (HF will run this)
+├── .env.example              # Environment variable template
+│
+├── src/                       # Application source
+│   ├── agents/
+│   │   ├── campaign_agent.py
+│   │   └── character_agent.py
+│   ├── models/
+│   │   ├── campaign.py
+│   │   ├── character.py
+│   │   └── session_notes.py
+│   ├── ui/
+│   │   ├── app.py
+│   │   ├── components/
+│   │   └── tabs/
+│   └── utils/
+│       ├── ai_client.py
+│       └── file_parsers.py
+│
+├── mcp_server/               # MCP tools
+│   ├── dnd_mcp_server.py
+│   ├── mcp_config.json
+│   └── README.md
+│
+└── data/                     # Database (auto-created)
+    └── dnd_campaign_manager.db
+```
+
+## ⚙️ Configuration Tips
+
+### Memory Management
+
+HF Spaces free tier has 16GB RAM. If you encounter memory issues:
+
+1. **In your Space settings:**
+   - Hardware: Start with **CPU Basic** (free)
+   - Upgrade to **CPU Upgrade** or **T4 small** if needed
+
+2. **Optimize database:**
+   ```python
+   # Already implemented in campaign_agent.py
+   # Uses SQLite with limited result sets
+   ```
+
+### Persistent Storage
+
+**Important:** HF Spaces free tier has ephemeral storage. Your database will reset on Space restart.
+
+**Solutions:**
+
+1. **Use HF Datasets for persistence (recommended):**
+   ```python
+   # Add to requirements.txt:
+   # datasets>=2.0.0
+
+   # Save to HF Dataset periodically
+   from datasets import Dataset
+   # Implementation in src/utils/persistence.py
+   ```
+
+2. **Upgrade to Persistent Storage:**
+   - Go to Space Settings → Storage
+   - Enable persistent storage ($5/month)
+
+3. **Accept ephemeral storage:**
+   - Good for demos/testing
+   - Users can export their data
+
+### API Rate Limits
+
+To avoid hitting rate limits:
+
+1. **Set rate limit warnings** (already implemented in AI client)
+2. **Add caching** for repeated requests
+3. **Consider adding Redis** for session management
+
+## 🧪 Testing Your Deployment
+
+Once deployed, test these features:
+
+1. **Character Creation**
+   - Create a character
+   - Generate backstory
+   - Export character sheet
+
+2. **Campaign Synthesis**
+   - Create 3-4 characters
+   - Synthesize campaign
+   - Verify campaign loads
+
+3. **Session Generation**
+   - Auto-generate a session
+   - Upload session notes
+   - Generate next session
+
+4. **MCP Tools** (if using MCP server)
+   - Character validation
+   - Encounter CR calculation
+
+## 🐛 Troubleshooting
+
+### Build Fails
+
+**Error:** `Could not find a version that satisfies the requirement...`
+
+**Fix:** Check `requirements.txt` version constraints:
+```txt
+# Too strict (may fail):
+gradio==5.0.0
+
+# Better (flexible):
+gradio>=5.0.0
+```
+
+### App Doesn't Start
+
+**Check logs:**
+1. Go to your Space
+2. Click **Logs** tab
+3. Look for errors
+
+**Common issues:**
+- Missing API key → Add in Secrets
+- Import error → Check all files uploaded
+- Database path → Ensure `data/` directory exists
+
+### Slow Performance
+
+**Solutions:**
+1. Upgrade hardware tier
+2. Enable caching
+3. Use faster model (e.g., Gemini Flash)
+4. Reduce session history lookback
+
+### Database Resets
+
+**This is normal on free tier.**
+
+**Options:**
+1. Enable persistent storage ($5/month)
+2. Use HF Datasets for backup
+3. Allow users to export/import data
+
+## 🎨 Customizing Your Space
+
+### Update README Header
+
+Edit `README.md` frontmatter:
+
+```yaml
+---
+title: My D&D Campaign Manager
+emoji: ⚔️
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 5.0.0
+app_file: app_v2.py
+pinned: true
+license: mit
+tags:
+  - dnd
+  - ttrpg
+  - ai
+  - campaign-manager
+  - mcp
+---
+```
+
+### Add Custom Domain (Pro)
+
+HF Spaces Pro allows custom domains:
+1. Settings → Custom Domain
+2. Point your DNS to HF
+3. Enable HTTPS
+
+### Enable Authentication
+
+Restrict access to your Space:
+
+```python
+# In app_v2.py
+from src.ui import launch_ui
+
+if __name__ == "__main__":
+    launch_ui(auth=("admin", "your_password"))
+```
+
+Or use HF's built-in auth:
+- Settings → Access Control
+- Set to "Private" or "Token-gated"
+
+## 📊 Monitoring
+
+### View Analytics
+
+HF Spaces provides:
+- **App traffic** (visits, unique users)
+- **Resource usage** (CPU, memory)
+- **Build history**
+
+Access: Space Settings → Analytics
+
+### Add Custom Analytics
+
+```python
+# Add to app.py
+import gradio as gr
+
+def track_event(event_name):
+    # Log to your analytics service
+    pass
+
+# Add to Gradio components
+gr.Button("Create Character").click(
+    fn=lambda: track_event("character_created"),
+    ...
+)
+```
+
+## 🚀 Going to Production
+
+For serious production use:
+
+1. **Persistent Storage:** Enable in Space settings
+2. **Upgrade Hardware:** T4 Small GPU or better
+3. **Add Monitoring:** Sentry, LogRocket, etc.
+4. **Rate Limiting:** Implement per-user limits
+5. **Backups:** Daily exports to HF Dataset
+6. **Custom Domain:** For branding
+7. **Load Testing:** Test with multiple users
+
+## 💰 Cost Estimates
+
+**Free Tier:**
+- Hosting: Free
+- Storage: Ephemeral (resets on restart)
+- Hardware: CPU Basic
+- **Good for:** Demos, testing, low traffic
+
+**Paid Tiers:**
+- **Persistent Storage:** $5/month
+- **CPU Upgrade:** $0/hour (included)
+- **T4 Small (GPU):** $0.60/hour
+- **A10G Small:** $1.50/hour
+
+**API Costs (separate):**
+- Anthropic Claude: ~$3-15 per 1M tokens
+- OpenAI GPT-4: ~$10-30 per 1M tokens
+- Google Gemini: Free tier available
+
+## 📝 Checklist: Ready to Deploy?
+
+- [ ] All files ready (app_v2.py, src/, mcp_server/)
+- [ ] requirements_hf.txt renamed to requirements.txt
+- [ ] README_HF.md renamed to README.md
+- [ ] .env.example included (for local dev reference)
+- [ ] API keys ready to add as Secrets
+- [ ] HF Space created
+- [ ] Files uploaded or pushed
+- [ ] Secrets configured
+- [ ] Build succeeded
+- [ ] App tested
+
+## 🎉 You're Live!
+
+Once deployed, share your Space:
+
+```
+🎲 Check out my D&D Campaign Manager!
+https://huggingface.co/spaces/YOUR_USERNAME/dnd-campaign-manager
+
+Features:
+✨ AI-powered character creation
+🎯 Autonomous campaign synthesis
+📖 Auto-generated session plans
+⚔️ MCP-powered encounter balancing
+```
+
+---
+
+**Need help?**
+- HF Spaces Docs: https://huggingface.co/docs/hub/spaces
+- Gradio Docs: https://gradio.app/docs/
+- Open an issue on GitHub
+
+**Happy deploying!** 🚀

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dungeon Smasher Pro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,14 +1,108 @@
 ---
-title: DnD Campaign Manager
-emoji: 📚
-colorFrom: gray
-colorTo: indigo
+title: D'n'D Campaign Manager
+emoji: 🎲
+colorFrom: purple
+colorTo: red
 sdk: gradio
-sdk_version: 6.0.1
+sdk_version: 5.38.2
 app_file: app.py
 pinned: false
-license: apache-2.0
-short_description: Create characters, images and custom campaigns
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🎲 D'n'D Campaign Manager
+
+A complete AI-powered D&D 5e character creator and campaign management system built with Gradio.
+
+## Features
+
+### Character Creation
+- **AI-Powered Generation**: Create fully-detailed D&D 5e characters with backstories, personality traits, and equipment
+- **Race & Class Support**: All standard D&D 5e races and classes
+- **Background System**: Rich backgrounds with personality traits, ideals, bonds, and flaws
+- **Portrait Generation**: AI-generated character portraits using DALL-E 3 or HuggingFace
+- **Character Export**: Export to Markdown, JSON, or HTML character sheets
+
+### Campaign Management
+- **Campaign Synthesis**: AI creates complete campaigns tailored to your party composition
+- **Session Tracking**: Track campaign sessions and important events
+- **Character Integration**: Automatically weaves character backstories into campaign narrative
+- **Campaign Notes**: Detailed NPCs, locations, adventure hooks, and session outlines
+
+### What Makes This Special
+
+The **Campaign Synthesis** feature analyzes your entire party (backstories, alignments, classes, personalities) and generates:
+- Custom adventure hooks that tie into each character's background
+- NPCs connected to party members
+- Locations relevant to the party's story
+- Session-by-session progression outlines
+- Character connections explaining how the party knows each other
+- Villains with personal stakes for each PC
+
+## Configuration
+
+This app requires API keys for AI features. Set them as Hugging Face Space secrets:
+
+### Required (choose one):
+- `OPENAI_API_KEY` - For OpenAI GPT-4 (recommended for best results)
+- `ANTHROPIC_API_KEY` - For Claude models
+
+### Optional:
+- `HUGGINGFACE_TOKEN` - For HuggingFace image generation (fallback)
+- `GEMINI_API_KEY` - For Google Gemini models (optional alternative)
+
+## How to Use
+
+1. **Create Characters**: Go to "Create Character" tab and fill in the basic details
+2. **Select Party**: In "Campaign Management" → "Synthesize from Characters", select multiple characters
+3. **Generate Campaign**: Click "Synthesize Campaign" to create a custom campaign
+4. **Track Progress**: Use "Session Tracking" to record events and progress
+
+## Local Development
+
+```bash
+# Clone the repository
+git clone <your-repo-url>
+cd dungeon-smasher-pro
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Set up environment variables
+cp .env.example .env
+# Edit .env with your API keys
+
+# Run the app
+python3 app_v2.py
+```
+
+## Tech Stack
+
+- **Gradio 5.38.2** - Web UI framework
+- **OpenAI GPT-4** - Character and campaign generation
+- **DALL-E 3** - Portrait generation
+- **SQLite** - Character and campaign storage
+- **Pydantic** - Data validation
+
+## Architecture
+
+```
+src/
+├── agents/           # Business logic
+│   ├── character_agent.py
+│   └── campaign_agent.py
+├── models/           # Pydantic data models
+│   ├── character.py
+│   └── campaign.py
+├── ui/              # Gradio interface
+│   └── character_creator_ui.py
+└── utils/           # AI client utilities
+    └── ai_client.py
+```
+
+## Credits
+
+Built with ❤️ for D&D players and Dungeon Masters everywhere.
+
+## License
+

app_v2.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""
+D'n'D Campaign Manager - Main Application
+Launch the Gradio UI for character creation
+"""
+
+import sys
+from pathlib import Path
+
+# Add src to path
+sys.path.insert(0, str(Path(__file__).parent))
+
+from src.ui import launch_ui
+
+if __name__ == "__main__":
+    print("""
+    ╔═══════════════════════════════════════════════╗
+    ║   🎲 D'n'D Campaign Manager                   ║
+    ║   Complete D&D Character Creator              ║
+    ╚═══════════════════════════════════════════════╝
+
+    Starting Gradio interface...
+    """)
+
+    try:
+        launch_ui()
+    except KeyboardInterrupt:
+        print("\n\n👋 Shutting down gracefully...")
+    except Exception as e:
+        print(f"\n❌ Error: {e}")
+        import traceback
+        traceback.print_exc()

mcp_server/README.md

@@ -0,0 +1,335 @@
+# D&D Campaign Manager MCP Server
+
+A Model Context Protocol (MCP) server providing D&D 5e tools for AI agents and LLMs.
+
+## 🎲 What This MCP Server Provides
+
+This MCP server extends LLM capabilities with specialized D&D 5e tools for:
+- Character validation and rules compliance
+- Encounter difficulty calculation
+- XP award computation
+- Multiclass requirement checking
+- NPC stat block generation
+- Ability modifier calculations
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Install FastMCP
+pip install fastmcp
+
+# Run the MCP server
+python3 mcp_server/dnd_mcp_server.py
+```
+
+### Usage with Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "dnd-campaign-manager": {
+      "command": "python3",
+      "args": [
+        "/path/to/dungeon-smasher-pro/mcp_server/dnd_mcp_server.py"
+      ]
+    }
+  }
+}
+```
+
+## 📚 Available Tools
+
+### `validate_character`
+Validates D&D 5e character builds for rules compliance.
+
+**Parameters:**
+- `character_class` (string): Character class (e.g., "fighter")
+- `level` (int): Character level (1-20)
+- `ability_scores` (dict): Ability scores (e.g., `{"strength": 16, "dexterity": 14, ...}`)
+- `multiclass` (list, optional): List of multiclass names
+
+**Example:**
+```python
+validate_character(
+    character_class="fighter",
+    level=5,
+    ability_scores={"strength": 16, "dexterity": 14, "constitution": 15, "intelligence": 10, "wisdom": 12, "charisma": 8}
+)
+```
+
+**Returns:**
+```json
+{
+  "valid": true,
+  "errors": [],
+  "warnings": ["Low charisma (8) for fighter - recommend 13+"],
+  "hp_estimate": 49,
+  "hit_die": "d10",
+  "constitution_modifier": 2
+}
+```
+
+### `calculate_encounter_cr`
+Calculates encounter difficulty using D&D 5e rules.
+
+**Parameters:**
+- `party_levels` (list): Party member levels (e.g., `[5, 5, 4, 6]`)
+- `monster_crs` (list): Monster challenge ratings (e.g., `[2, 2, 0.5]`)
+- `difficulty_target` (string): Target difficulty ("easy", "medium", "hard", "deadly")
+
+**Example:**
+```python
+calculate_encounter_cr(
+    party_levels=[5, 5, 4, 6],
+    monster_crs=[2, 2, 0.5],
+    difficulty_target="medium"
+)
+```
+
+**Returns:**
+```json
+{
+  "difficulty": "hard",
+  "adjusted_xp": 2100,
+  "raw_xp": 1050,
+  "multiplier": 2.0,
+  "thresholds": {"easy": 1000, "medium": 2000, "hard": 3000, "deadly": 4400},
+  "target_met": false,
+  "recommendations": [],
+  "party_size": 4,
+  "monster_count": 3
+}
+```
+
+### `calculate_xp_award`
+Calculates XP rewards for defeated monsters.
+
+**Parameters:**
+- `party_size` (int): Number of players
+- `monster_crs` (list): CRs of defeated monsters
+
+**Example:**
+```python
+calculate_xp_award(party_size=4, monster_crs=[2, 2, 0.5])
+```
+
+**Returns:**
+```json
+{
+  "total_xp": 1150,
+  "xp_per_player": 287,
+  "party_size": 4,
+  "monsters_defeated": 3
+}
+```
+
+### `validate_multiclass`
+Checks multiclass requirements.
+
+**Parameters:**
+- `current_class` (string): Current primary class
+- `target_class` (string): Class to multiclass into
+- `ability_scores` (dict): Character ability scores
+
+**Example:**
+```python
+validate_multiclass(
+    current_class="fighter",
+    target_class="wizard",
+    ability_scores={"intelligence": 14, "strength": 16, ...}
+)
+```
+
+**Returns:**
+```json
+{
+  "valid": true,
+  "requirements_met": true,
+  "required": {"intelligence": 13},
+  "missing": [],
+  "can_multiclass": true
+}
+```
+
+### `generate_npc_stats`
+Generates balanced NPC stat blocks.
+
+**Parameters:**
+- `npc_name` (string): NPC name
+- `character_class` (string): NPC class
+- `level` (int): NPC level
+- `role` (string): Combat role ("tank", "damage", "support", "standard")
+
+**Example:**
+```python
+generate_npc_stats(
+    npc_name="Guard Captain",
+    character_class="fighter",
+    level=5,
+    role="tank"
+)
+```
+
+**Returns:**
+```json
+{
+  "name": "Guard Captain",
+  "class": "fighter",
+  "level": 5,
+  "role": "tank",
+  "hp": 49,
+  "hp_formula": "5d10 + 10",
+  "ac": 18,
+  "ability_scores": {"strength": 16, "dexterity": 12, "constitution": 16, ...},
+  "proficiency_bonus": 3,
+  "primary_ability": "strength",
+  "hit_die": "d10"
+}
+```
+
+### `get_ability_modifier`
+Calculates ability modifier from ability score.
+
+**Parameters:**
+- `ability_score` (int): Ability score (1-30)
+
+**Example:**
+```python
+get_ability_modifier(16)
+```
+
+**Returns:** `3`
+
+### `get_cr_for_solo_monster`
+Recommends CR for solo monster encounters.
+
+**Parameters:**
+- `party_level` (int): Average party level
+- `party_size` (int): Number of party members
+- `difficulty` (string): Desired difficulty
+
+**Example:**
+```python
+get_cr_for_solo_monster(party_level=5, party_size=4, difficulty="hard")
+```
+
+**Returns:**
+```json
+{
+  "recommended_cr": 7.0,
+  "target_xp": 3000,
+  "actual_xp": 2900,
+  "party_level": 5,
+  "party_size": 4,
+  "difficulty": "hard"
+}
+```
+
+## 🏗️ Architecture
+
+```
+mcp_server/
+├── __init__.py              # Package initialization
+├── dnd_mcp_server.py       # Main MCP server with tools
+├── mcp_config.json         # MCP configuration
+└── README.md               # Documentation
+```
+
+## 🎯 Use Cases
+
+### For DMs
+- Validate player character builds during session 0
+- Balance encounters on-the-fly
+- Generate quick NPC stats for improvised encounters
+- Calculate XP rewards accurately
+
+### For AI Agents
+- Autonomous character creation with rules compliance
+- Intelligent encounter design
+- Campaign balance analysis
+- NPC generation for story development
+
+### For Developers
+- Integrate D&D rules into LLM applications
+- Build D&D assistants and tools
+- Create automated campaign managers
+- Develop character builders with validation
+
+## 📊 Example Integration
+
+```python
+# Example: AI agent using MCP tools to balance an encounter
+
+# 1. Validate party
+for character in party:
+    validation = validate_character(
+        character_class=character.class,
+        level=character.level,
+        ability_scores=character.abilities
+    )
+    if not validation["valid"]:
+        print(f"Error: {validation['errors']}")
+
+# 2. Design encounter
+party_levels = [char.level for char in party]
+encounter = calculate_encounter_cr(
+    party_levels=party_levels,
+    monster_crs=[2, 2, 1, 0.5],
+    difficulty_target="medium"
+)
+
+# 3. Adjust if needed
+if encounter["difficulty"] != "medium":
+    print(f"Encounter is {encounter['difficulty']}, adjusting...")
+    # AI can now reason about how to adjust
+
+# 4. Calculate rewards
+xp = calculate_xp_award(
+    party_size=len(party),
+    monster_crs=[2, 2, 1, 0.5]
+)
+print(f"Party earns {xp['xp_per_player']} XP each")
+```
+
+## 🔧 Development
+
+### Adding New Tools
+
+1. Add tool function with `@mcp.tool()` decorator
+2. Document parameters and return values
+3. Add to tool list in `__main__`
+4. Update this README
+
+### Testing
+
+```bash
+# Test individual tools
+python3 -c "from mcp_server.dnd_mcp_server import *; print(validate_character('fighter', 5, {'strength': 16, 'dexterity': 14, 'constitution': 15, 'intelligence': 10, 'wisdom': 12, 'charisma': 8}))"
+```
+
+## 📝 License
+
+MIT License - See main project LICENSE
+
+## 🤝 Contributing
+
+Contributions welcome! Please:
+1. Follow D&D 5e SRD rules
+2. Add tests for new tools
+3. Update documentation
+4. Ensure backward compatibility
+
+## 🎲 D&D 5e SRD Compliance
+
+This MCP server implements rules from the D&D 5e System Reference Document (SRD).
+All content is from open game content under the OGL 1.0a.
+
+## 🔗 Links
+
+- [FastMCP Documentation](https://github.com/anthropics/anthropic-tools)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [D&D 5e SRD](https://dnd.wizards.com/resources/systems-reference-document)

mcp_server/__init__.py

@@ -0,0 +1,7 @@
+"""
+D&D Campaign Manager MCP Server
+
+Provides Model Context Protocol tools for D&D 5e campaign management.
+"""
+
+__version__ = "1.0.0"

mcp_server/dnd_mcp_server.py

@@ -0,0 +1,514 @@
+#!/usr/bin/env python3
+"""
+D&D Campaign Manager MCP Server
+
+Provides tools for D&D 5e rules, character validation, encounter design,
+and campaign management through the Model Context Protocol.
+
+Tools:
+- validate_character: Validate D&D 5e character builds
+- calculate_encounter_cr: Calculate encounter difficulty
+- lookup_spell: Get spell details and rules
+- lookup_monster: Get monster stat blocks
+- generate_npc: Create balanced NPC stat blocks
+- calculate_xp: Calculate XP awards for encounters
+- validate_multiclass: Check multiclass requirements
+- get_ability_modifier: Calculate ability modifiers
+"""
+
+import json
+import sys
+from typing import Any, Dict, List, Optional
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError:
+    print("Installing FastMCP...")
+    import subprocess
+    subprocess.check_call([sys.executable, "-m", "pip", "install", "fastmcp"])
+    from mcp.server.fastmcp import FastMCP
+
+# Initialize MCP server
+mcp = FastMCP("dnd-campaign-manager")
+
+
+# ============================================================================
+# D&D 5E RULES DATA
+# ============================================================================
+
+ABILITY_SCORES = ["strength", "dexterity", "constitution", "intelligence", "wisdom", "charisma"]
+
+CLASSES = {
+    "barbarian": {"hit_die": 12, "primary_ability": ["strength"]},
+    "bard": {"hit_die": 8, "primary_ability": ["charisma"]},
+    "cleric": {"hit_die": 8, "primary_ability": ["wisdom"]},
+    "druid": {"hit_die": 8, "primary_ability": ["wisdom"]},
+    "fighter": {"hit_die": 10, "primary_ability": ["strength", "dexterity"]},
+    "monk": {"hit_die": 8, "primary_ability": ["dexterity", "wisdom"]},
+    "paladin": {"hit_die": 10, "primary_ability": ["strength", "charisma"]},
+    "ranger": {"hit_die": 10, "primary_ability": ["dexterity", "wisdom"]},
+    "rogue": {"hit_die": 8, "primary_ability": ["dexterity"]},
+    "sorcerer": {"hit_die": 6, "primary_ability": ["charisma"]},
+    "warlock": {"hit_die": 8, "primary_ability": ["charisma"]},
+    "wizard": {"hit_die": 6, "primary_ability": ["intelligence"]}
+}
+
+MULTICLASS_REQUIREMENTS = {
+    "barbarian": {"strength": 13},
+    "bard": {"charisma": 13},
+    "cleric": {"wisdom": 13},
+    "druid": {"wisdom": 13},
+    "fighter": {"strength": 13, "dexterity": 13},  # OR condition
+    "monk": {"dexterity": 13, "wisdom": 13},
+    "paladin": {"strength": 13, "charisma": 13},
+    "ranger": {"dexterity": 13, "wisdom": 13},
+    "rogue": {"dexterity": 13},
+    "sorcerer": {"charisma": 13},
+    "warlock": {"charisma": 13},
+    "wizard": {"intelligence": 13}
+}
+
+XP_THRESHOLDS = {
+    1: {"easy": 25, "medium": 50, "hard": 75, "deadly": 100},
+    2: {"easy": 50, "medium": 100, "hard": 150, "deadly": 200},
+    3: {"easy": 75, "medium": 150, "hard": 225, "deadly": 400},
+    4: {"easy": 125, "medium": 250, "hard": 375, "deadly": 500},
+    5: {"easy": 250, "medium": 500, "hard": 750, "deadly": 1100},
+    6: {"easy": 300, "medium": 600, "hard": 900, "deadly": 1400},
+    7: {"easy": 350, "medium": 750, "hard": 1100, "deadly": 1700},
+    8: {"easy": 450, "medium": 900, "hard": 1400, "deadly": 2100},
+    9: {"easy": 550, "medium": 1100, "hard": 1600, "deadly": 2400},
+    10: {"easy": 600, "medium": 1200, "hard": 1900, "deadly": 2800},
+    11: {"easy": 800, "medium": 1600, "hard": 2400, "deadly": 3600},
+    12: {"easy": 1000, "medium": 2000, "hard": 3000, "deadly": 4500},
+    13: {"easy": 1100, "medium": 2200, "hard": 3400, "deadly": 5100},
+    14: {"easy": 1250, "medium": 2500, "hard": 3800, "deadly": 5700},
+    15: {"easy": 1400, "medium": 2800, "hard": 4300, "deadly": 6400},
+    16: {"easy": 1600, "medium": 3200, "hard": 4800, "deadly": 7200},
+    17: {"easy": 2000, "medium": 3900, "hard": 5900, "deadly": 8800},
+    18: {"easy": 2100, "medium": 4200, "hard": 6300, "deadly": 9500},
+    19: {"easy": 2400, "medium": 4900, "hard": 7300, "deadly": 10900},
+    20: {"easy": 2800, "medium": 5700, "hard": 8500, "deadly": 12700}
+}
+
+CR_TO_XP = {
+    0: 10, 0.125: 25, 0.25: 50, 0.5: 100,
+    1: 200, 2: 450, 3: 700, 4: 1100, 5: 1800,
+    6: 2300, 7: 2900, 8: 3900, 9: 5000, 10: 5900,
+    11: 7200, 12: 8400, 13: 10000, 14: 11500, 15: 13000,
+    16: 15000, 17: 18000, 18: 20000, 19: 22000, 20: 25000,
+    21: 33000, 22: 41000, 23: 50000, 24: 62000, 25: 75000,
+    26: 90000, 27: 105000, 28: 120000, 29: 135000, 30: 155000
+}
+
+ENCOUNTER_MULTIPLIERS = {
+    1: 1.0,
+    2: 1.5,
+    (3, 6): 2.0,
+    (7, 10): 2.5,
+    (11, 14): 3.0,
+    15: 4.0
+}
+
+
+# ============================================================================
+# MCP TOOLS
+# ============================================================================
+
+@mcp.tool()
+def get_ability_modifier(ability_score: int) -> int:
+    """
+    Calculate ability modifier from ability score.
+
+    Args:
+        ability_score: The ability score (1-30)
+
+    Returns:
+        The ability modifier
+
+    Example:
+        >>> get_ability_modifier(16)
+        3
+    """
+    return (ability_score - 10) // 2
+
+
+@mcp.tool()
+def validate_character(
+    character_class: str,
+    level: int,
+    ability_scores: Dict[str, int],
+    multiclass: Optional[List[str]] = None
+) -> Dict[str, Any]:
+    """
+    Validate a D&D 5e character build for rules compliance.
+
+    Args:
+        character_class: Primary class name (e.g., "fighter")
+        level: Character level (1-20)
+        ability_scores: Dict of ability scores (e.g., {"strength": 16, "dexterity": 14, ...})
+        multiclass: Optional list of multiclass names
+
+    Returns:
+        Validation result with errors and warnings
+
+    Example:
+        >>> validate_character("fighter", 5, {"strength": 16, "dexterity": 14, "constitution": 15, "intelligence": 10, "wisdom": 12, "charisma": 8})
+        {"valid": True, "errors": [], "warnings": [], "hp_estimate": 49}
+    """
+    errors = []
+    warnings = []
+
+    # Validate class
+    character_class = character_class.lower()
+    if character_class not in CLASSES:
+        errors.append(f"Invalid class: {character_class}")
+        return {"valid": False, "errors": errors, "warnings": warnings}
+
+    # Validate level
+    if level < 1 or level > 20:
+        errors.append(f"Level must be between 1 and 20, got {level}")
+
+    # Validate ability scores
+    for ability in ABILITY_SCORES:
+        if ability not in ability_scores:
+            errors.append(f"Missing ability score: {ability}")
+        elif ability_scores[ability] < 1 or ability_scores[ability] > 20:
+            warnings.append(f"{ability.title()} score {ability_scores[ability]} is unusual (normally 1-20)")
+
+    # Check primary ability scores
+    class_info = CLASSES[character_class]
+    for primary in class_info["primary_ability"]:
+        if primary in ability_scores and ability_scores[primary] < 13:
+            warnings.append(f"Low {primary} ({ability_scores[primary]}) for {character_class} - recommend 13+")
+
+    # Validate multiclassing
+    if multiclass:
+        for mc_class in multiclass:
+            mc_class = mc_class.lower()
+            if mc_class not in CLASSES:
+                errors.append(f"Invalid multiclass: {mc_class}")
+                continue
+
+            requirements = MULTICLASS_REQUIREMENTS[mc_class]
+            for ability, min_score in requirements.items():
+                if ability_scores.get(ability, 0) < min_score:
+                    errors.append(
+                        f"Multiclass {mc_class} requires {ability} {min_score}, "
+                        f"but character has {ability_scores.get(ability, 0)}"
+                    )
+
+    # Calculate estimated HP
+    hit_die = class_info["hit_die"]
+    con_mod = get_ability_modifier(ability_scores.get("constitution", 10))
+    hp_estimate = hit_die + (level - 1) * (hit_die // 2 + 1) + (level * con_mod)
+
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+        "warnings": warnings,
+        "hp_estimate": hp_estimate,
+        "hit_die": f"d{hit_die}",
+        "constitution_modifier": con_mod
+    }
+
+
+@mcp.tool()
+def calculate_encounter_cr(
+    party_levels: List[int],
+    monster_crs: List[float],
+    difficulty_target: str = "medium"
+) -> Dict[str, Any]:
+    """
+    Calculate encounter difficulty for D&D 5e.
+
+    Args:
+        party_levels: List of party member levels (e.g., [5, 5, 4, 6])
+        monster_crs: List of monster CRs (e.g., [2, 2, 0.5])
+        difficulty_target: Target difficulty ("easy", "medium", "hard", "deadly")
+
+    Returns:
+        Encounter analysis with difficulty rating and recommendations
+
+    Example:
+        >>> calculate_encounter_cr([5, 5, 4, 6], [2, 2, 0.5], "medium")
+        {"difficulty": "hard", "adjusted_xp": 2100, "threshold": {"easy": 1000, "medium": 2000, "hard": 3000, "deadly": 4400}}
+    """
+    # Calculate party XP thresholds
+    party_thresholds = {"easy": 0, "medium": 0, "hard": 0, "deadly": 0}
+    for level in party_levels:
+        level = min(max(level, 1), 20)  # Clamp to 1-20
+        for difficulty in ["easy", "medium", "hard", "deadly"]:
+            party_thresholds[difficulty] += XP_THRESHOLDS[level][difficulty]
+
+    # Calculate monster XP
+    total_monster_xp = sum(CR_TO_XP.get(cr, 0) for cr in monster_crs)
+
+    # Apply encounter multiplier based on number of monsters
+    num_monsters = len(monster_crs)
+    multiplier = 1.0
+    if num_monsters == 1:
+        multiplier = 1.0
+    elif num_monsters == 2:
+        multiplier = 1.5
+    elif 3 <= num_monsters <= 6:
+        multiplier = 2.0
+    elif 7 <= num_monsters <= 10:
+        multiplier = 2.5
+    elif 11 <= num_monsters <= 14:
+        multiplier = 3.0
+    else:
+        multiplier = 4.0
+
+    adjusted_xp = int(total_monster_xp * multiplier)
+
+    # Determine difficulty
+    if adjusted_xp < party_thresholds["easy"]:
+        difficulty = "trivial"
+    elif adjusted_xp < party_thresholds["medium"]:
+        difficulty = "easy"
+    elif adjusted_xp < party_thresholds["hard"]:
+        difficulty = "medium"
+    elif adjusted_xp < party_thresholds["deadly"]:
+        difficulty = "hard"
+    else:
+        difficulty = "deadly"
+
+    # Calculate recommendations
+    recommendations = []
+    if difficulty == "trivial":
+        recommendations.append("This encounter is too easy. Consider adding more monsters or increasing CR.")
+    elif difficulty == "deadly":
+        recommendations.append("This encounter is deadly! Ensure party has resources and escape options.")
+
+    if num_monsters > 6:
+        recommendations.append(f"Large number of monsters ({num_monsters}) may slow combat. Consider grouping or reducing.")
+
+    return {
+        "difficulty": difficulty,
+        "adjusted_xp": adjusted_xp,
+        "raw_xp": total_monster_xp,
+        "multiplier": multiplier,
+        "thresholds": party_thresholds,
+        "target_met": difficulty == difficulty_target,
+        "recommendations": recommendations,
+        "party_size": len(party_levels),
+        "monster_count": num_monsters
+    }
+
+
+@mcp.tool()
+def calculate_xp_award(
+    party_size: int,
+    monster_crs: List[float]
+) -> Dict[str, int]:
+    """
+    Calculate XP award per player for defeating monsters.
+
+    Args:
+        party_size: Number of players in party
+        monster_crs: List of monster CRs defeated
+
+    Returns:
+        XP breakdown
+
+    Example:
+        >>> calculate_xp_award(4, [2, 2, 0.5])
+        {"total_xp": 1150, "xp_per_player": 287}
+    """
+    total_xp = sum(CR_TO_XP.get(cr, 0) for cr in monster_crs)
+    xp_per_player = total_xp // party_size if party_size > 0 else 0
+
+    return {
+        "total_xp": total_xp,
+        "xp_per_player": xp_per_player,
+        "party_size": party_size,
+        "monsters_defeated": len(monster_crs)
+    }
+
+
+@mcp.tool()
+def validate_multiclass(
+    current_class: str,
+    target_class: str,
+    ability_scores: Dict[str, int]
+) -> Dict[str, Any]:
+    """
+    Check if character meets multiclass requirements.
+
+    Args:
+        current_class: Current primary class
+        target_class: Class to multiclass into
+        ability_scores: Character's ability scores
+
+    Returns:
+        Validation result with requirements
+
+    Example:
+        >>> validate_multiclass("fighter", "wizard", {"intelligence": 14, "strength": 16})
+        {"valid": True, "requirements_met": True, "required": {"intelligence": 13}}
+    """
+    current_class = current_class.lower()
+    target_class = target_class.lower()
+
+    if current_class not in CLASSES:
+        return {"valid": False, "error": f"Invalid current class: {current_class}"}
+
+    if target_class not in CLASSES:
+        return {"valid": False, "error": f"Invalid target class: {target_class}"}
+
+    # Check target class requirements
+    requirements = MULTICLASS_REQUIREMENTS[target_class]
+    requirements_met = True
+    missing = []
+
+    for ability, min_score in requirements.items():
+        if ability_scores.get(ability, 0) < min_score:
+            requirements_met = False
+            missing.append(f"{ability.title()} {min_score} (currently {ability_scores.get(ability, 0)})")
+
+    return {
+        "valid": True,
+        "requirements_met": requirements_met,
+        "required": requirements,
+        "missing": missing,
+        "can_multiclass": requirements_met
+    }
+
+
+@mcp.tool()
+def generate_npc_stats(
+    npc_name: str,
+    character_class: str,
+    level: int,
+    role: str = "standard"
+) -> Dict[str, Any]:
+    """
+    Generate NPC stat block for D&D 5e.
+
+    Args:
+        npc_name: NPC name
+        character_class: NPC class
+        level: NPC level
+        role: Combat role ("tank", "damage", "support", "standard")
+
+    Returns:
+        NPC stat block
+
+    Example:
+        >>> generate_npc_stats("Guard Captain", "fighter", 5, "tank")
+        {"name": "Guard Captain", "class": "fighter", "level": 5, "hp": 49, "ac": 18, ...}
+    """
+    character_class = character_class.lower()
+
+    if character_class not in CLASSES:
+        return {"error": f"Invalid class: {character_class}"}
+
+    class_info = CLASSES[character_class]
+
+    # Generate ability scores based on role
+    if role == "tank":
+        abilities = {"strength": 16, "dexterity": 12, "constitution": 16, "intelligence": 10, "wisdom": 12, "charisma": 10}
+    elif role == "damage":
+        abilities = {"strength": 16, "dexterity": 16, "constitution": 14, "intelligence": 10, "wisdom": 12, "charisma": 10}
+    elif role == "support":
+        abilities = {"strength": 10, "dexterity": 12, "constitution": 14, "intelligence": 14, "wisdom": 16, "charisma": 14}
+    else:  # standard
+        abilities = {"strength": 14, "dexterity": 14, "constitution": 14, "intelligence": 12, "wisdom": 12, "charisma": 12}
+
+    # Calculate stats
+    hit_die = class_info["hit_die"]
+    con_mod = get_ability_modifier(abilities["constitution"])
+    hp = hit_die + (level - 1) * (hit_die // 2 + 1) + (level * con_mod)
+
+    # Estimate AC based on class and role
+    base_ac = {"barbarian": 13, "fighter": 16, "paladin": 16, "ranger": 15, "rogue": 14}.get(character_class, 12)
+    if role == "tank":
+        base_ac += 2
+
+    # Proficiency bonus
+    proficiency = 2 + ((level - 1) // 4)
+
+    return {
+        "name": npc_name,
+        "class": character_class,
+        "level": level,
+        "role": role,
+        "hp": hp,
+        "hp_formula": f"{level}d{hit_die} + {level * con_mod}",
+        "ac": base_ac,
+        "ability_scores": abilities,
+        "proficiency_bonus": proficiency,
+        "primary_ability": class_info["primary_ability"][0],
+        "hit_die": f"d{hit_die}"
+    }
+
+
+@mcp.tool()
+def get_cr_for_solo_monster(party_level: int, party_size: int, difficulty: str = "medium") -> float:
+    """
+    Calculate appropriate CR for a solo monster encounter.
+
+    Args:
+        party_level: Average party level
+        party_size: Number of party members
+        difficulty: Desired difficulty ("easy", "medium", "hard", "deadly")
+
+    Returns:
+        Recommended CR
+
+    Example:
+        >>> get_cr_for_solo_monster(5, 4, "hard")
+        7.0
+    """
+    party_level = min(max(party_level, 1), 20)
+
+    # Get total party threshold for difficulty
+    total_threshold = XP_THRESHOLDS[party_level][difficulty] * party_size
+
+    # For solo monster, no multiplier
+    target_xp = total_threshold
+
+    # Find closest CR
+    best_cr = 0
+    best_diff = float('inf')
+
+    for cr, xp in CR_TO_XP.items():
+        diff = abs(xp - target_xp)
+        if diff < best_diff:
+            best_diff = diff
+            best_cr = cr
+
+    return {
+        "recommended_cr": best_cr,
+        "target_xp": target_xp,
+        "actual_xp": CR_TO_XP[best_cr],
+        "party_level": party_level,
+        "party_size": party_size,
+        "difficulty": difficulty
+    }
+
+
+# ============================================================================
+# MCP SERVER MAIN
+# ============================================================================
+
+if __name__ == "__main__":
+    print("🎲 D&D Campaign Manager MCP Server")
+    print("=" * 50)
+    print("Available Tools:")
+    print("  - validate_character: Validate character builds")
+    print("  - calculate_encounter_cr: Calculate encounter difficulty")
+    print("  - calculate_xp_award: Calculate XP rewards")
+    print("  - validate_multiclass: Check multiclass requirements")
+    print("  - generate_npc_stats: Generate NPC stat blocks")
+    print("  - get_ability_modifier: Calculate ability modifiers")
+    print("  - get_cr_for_solo_monster: Get CR for solo encounters")
+    print("=" * 50)
+    print("Starting MCP server...")
+
+    mcp.run()

mcp_server/mcp_config.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "dnd-campaign-manager": {
+      "command": "python3",
+      "args": [
+        "mcp_server/dnd_mcp_server.py"
+      ],
+      "description": "D&D 5e Campaign Management Tools",
+      "tools": [
+        "validate_character",
+        "calculate_encounter_cr",
+        "calculate_xp_award",
+        "validate_multiclass",
+        "generate_npc_stats",
+        "get_ability_modifier",
+        "get_cr_for_solo_monster"
+      ]
+    }
+  }
+}

requirements.txt

@@ -0,0 +1,37 @@
+# D&D Campaign Manager - Hugging Face Space Requirements
+# Production dependencies only
+
+# Core Framework
+gradio>=5.0.0
+pydantic>=2.0.0
+python-dotenv>=1.0.0
+
+# AI/LLM Providers
+anthropic>=0.39.0
+google-generativeai>=0.8.0
+openai>=1.54.0
+
+# MCP (Model Context Protocol)
+fastmcp>=0.2.0
+
+# Database & Storage
+# Note: SQLite is built into Python, no extra deps needed
+
+# Data Processing
+pyyaml>=6.0.0
+jinja2>=3.1.0
+
+# Dice & Game Mechanics
+dice>=4.0.0
+
+# Image Generation (Optional)
+pillow>=10.0.0
+requests>=2.31.0
+
+# Document Parsing
+python-docx>=1.1.0
+pypdf>=3.17.0
+
+# Utilities
+rich>=13.0.0
+tqdm>=4.66.0

setup_secrets.md

@@ -0,0 +1,56 @@
+# Setup Secrets on Hugging Face Spaces
+
+After uploading these files to your HF Space, configure secrets:
+
+## Required (at least one)
+
+Go to: **Settings → Variables and secrets**
+
+Add:
+
+```
+ANTHROPIC_API_KEY = sk-ant-...
+```
+
+OR
+
+```
+OPENAI_API_KEY = sk-...
+```
+
+OR
+
+```
+GOOGLE_API_KEY = AIza...
+```
+
+## Optional
+
+```
+HUGGINGFACE_API_KEY = hf_...
+PRIMARY_MODEL_PROVIDER = anthropic
+PRIMARY_MODEL = claude-3-5-sonnet-20241022
+```
+
+## Testing
+
+After setting secrets:
+1. Wait for Space to rebuild (~3-5 min)
+2. Open your app
+3. Create a test character
+4. Verify AI generation works
+
+## Troubleshooting
+
+**Build fails:**
+- Check requirements.txt syntax
+- Verify all files uploaded
+
+**App crashes:**
+- Check Logs tab for errors
+- Verify API keys in Secrets
+
+**No AI generation:**
+- Confirm at least one API key is set
+- Check API key is valid
+- Review error messages in Status box

src/__init__.py

@@ -0,0 +1,8 @@
+"""
+D'n'D Campaign Manager - TTRPG Platform
+A hackathon project for Gradio + Anthropic MCP
+"""
+
+__version__ = "2.0.0"
+__author__ = "Jesse Stucker"
+__description__ = "Complete TTRPG Campaign Management with MCP Integration"

src/agents/__init__.py

@@ -0,0 +1,9 @@
+"""
+Agents for D'n'D Campaign Manager
+"""
+
+from .character_agent import CharacterAgent
+
+__all__ = [
+    "CharacterAgent",
+]

src/agents/campaign_agent.py

@@ -0,0 +1,990 @@
+"""
+Campaign Agent for managing D&D campaigns
+"""
+import os
+import sqlite3
+import json
+from datetime import datetime
+from typing import Optional, List
+from src.models.campaign import Campaign, CampaignEvent, CampaignTheme, EventType
+from src.models.character import Character
+from src.models.session_notes import SessionNotes
+from src.utils.ai_client import get_ai_client
+
+
+class CampaignAgent:
+    """Agent for managing D&D campaigns"""
+
+    def __init__(self, db_path: str = "data/campaigns.db"):
+        """Initialize campaign agent"""
+        self.db_path = db_path
+        self.ai_client = get_ai_client()
+        self._ensure_database()
+
+    def _ensure_database(self):
+        """Ensure database and tables exist"""
+        os.makedirs(os.path.dirname(self.db_path), exist_ok=True)
+
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        # Campaigns table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS campaigns (
+                id TEXT PRIMARY KEY,
+                name TEXT NOT NULL,
+                theme TEXT NOT NULL,
+                setting TEXT NOT NULL,
+                world_name TEXT,
+                starting_location TEXT,
+                summary TEXT NOT NULL,
+                current_arc TEXT,
+                level_range TEXT,
+                main_conflict TEXT NOT NULL,
+                key_factions TEXT,
+                major_villains TEXT,
+                central_mysteries TEXT,
+                character_ids TEXT,
+                party_size INTEGER,
+                current_session INTEGER,
+                total_sessions INTEGER,
+                game_master TEXT,
+                is_active BOOLEAN,
+                homebrew_rules TEXT,
+                notes TEXT,
+                created_at TEXT,
+                updated_at TEXT,
+                last_session_date TEXT
+            )
+        """)
+
+        # Campaign events table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS campaign_events (
+                id TEXT PRIMARY KEY,
+                campaign_id TEXT NOT NULL,
+                session_number INTEGER NOT NULL,
+                event_type TEXT NOT NULL,
+                title TEXT NOT NULL,
+                description TEXT NOT NULL,
+                characters_involved TEXT,
+                npcs_involved TEXT,
+                locations TEXT,
+                consequences TEXT,
+                items_gained TEXT,
+                items_lost TEXT,
+                experience_awarded INTEGER,
+                timestamp TEXT,
+                importance INTEGER,
+                tags TEXT,
+                gm_notes TEXT,
+                player_visible BOOLEAN,
+                FOREIGN KEY (campaign_id) REFERENCES campaigns(id)
+            )
+        """)
+
+        # Session notes table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS session_notes (
+                id TEXT PRIMARY KEY,
+                campaign_id TEXT NOT NULL,
+                session_number INTEGER NOT NULL,
+                notes TEXT NOT NULL,
+                uploaded_at TEXT NOT NULL,
+                file_name TEXT,
+                file_type TEXT,
+                FOREIGN KEY (campaign_id) REFERENCES campaigns(id),
+                UNIQUE(campaign_id, session_number)
+            )
+        """)
+
+        conn.commit()
+        conn.close()
+
+    def create_campaign(
+        self,
+        name: str,
+        theme: str,
+        setting: str,
+        summary: str,
+        main_conflict: str,
+        game_master: str = "",
+        world_name: str = "",
+        starting_location: str = "",
+        level_range: str = "1-5",
+        party_size: int = 4
+    ) -> Campaign:
+        """Create a new campaign"""
+
+        # Generate campaign ID
+        campaign_id = name.lower().replace(" ", "-").replace("'", "")
+
+        # Create campaign
+        campaign = Campaign(
+            id=campaign_id,
+            name=name,
+            theme=CampaignTheme(theme),
+            setting=setting,
+            world_name=world_name,
+            starting_location=starting_location,
+            summary=summary,
+            main_conflict=main_conflict,
+            level_range=level_range,
+            party_size=party_size,
+            game_master=game_master,
+            current_session=1,
+            total_sessions=0,
+            is_active=True
+        )
+
+        # Save to database
+        self.save_campaign(campaign)
+
+        return campaign
+
+    def save_campaign(self, campaign: Campaign):
+        """Save campaign to database"""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cursor.execute("""
+            INSERT OR REPLACE INTO campaigns (
+                id, name, theme, setting, world_name, starting_location,
+                summary, current_arc, level_range, main_conflict,
+                key_factions, major_villains, central_mysteries,
+                character_ids, party_size, current_session, total_sessions,
+                game_master, is_active, homebrew_rules, notes,
+                created_at, updated_at, last_session_date
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """, (
+            campaign.id,
+            campaign.name,
+            campaign.theme.value,
+            campaign.setting,
+            campaign.world_name,
+            campaign.starting_location,
+            campaign.summary,
+            campaign.current_arc,
+            campaign.level_range,
+            campaign.main_conflict,
+            json.dumps(campaign.key_factions),
+            json.dumps(campaign.major_villains),
+            json.dumps(campaign.central_mysteries),
+            json.dumps(campaign.character_ids),
+            campaign.party_size,
+            campaign.current_session,
+            campaign.total_sessions,
+            campaign.game_master,
+            campaign.is_active,
+            json.dumps(campaign.homebrew_rules),
+            campaign.notes,
+            campaign.created_at.isoformat() if isinstance(campaign.created_at, datetime) else campaign.created_at,
+            campaign.updated_at.isoformat() if isinstance(campaign.updated_at, datetime) else campaign.updated_at,
+            campaign.last_session_date.isoformat() if campaign.last_session_date else None
+        ))
+
+        conn.commit()
+        conn.close()
+
+    def load_campaign(self, campaign_id: str) -> Optional[Campaign]:
+        """Load campaign from database"""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cursor.execute("SELECT * FROM campaigns WHERE id = ?", (campaign_id,))
+        row = cursor.fetchone()
+        conn.close()
+
+        if not row:
+            return None
+
+        # Convert row to dict
+        columns = [
+            'id', 'name', 'theme', 'setting', 'world_name', 'starting_location',
+            'summary', 'current_arc', 'level_range', 'main_conflict',
+            'key_factions', 'major_villains', 'central_mysteries',
+            'character_ids', 'party_size', 'current_session', 'total_sessions',
+            'game_master', 'is_active', 'homebrew_rules', 'notes',
+            'created_at', 'updated_at', 'last_session_date'
+        ]
+
+        data = {}
+        for i, col in enumerate(columns):
+            value = row[i]
+
+            # Parse JSON fields
+            if col in ['key_factions', 'major_villains', 'central_mysteries', 'character_ids', 'homebrew_rules']:
+                data[col] = json.loads(value) if value else []
+            else:
+                data[col] = value
+
+        return Campaign(**data)
+
+    def list_campaigns(self, active_only: bool = False) -> List[Campaign]:
+        """List all campaigns"""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        if active_only:
+            cursor.execute("SELECT id FROM campaigns WHERE is_active = 1")
+        else:
+            cursor.execute("SELECT id FROM campaigns")
+
+        campaign_ids = [row[0] for row in cursor.fetchall()]
+        conn.close()
+
+        return [self.load_campaign(cid) for cid in campaign_ids]
+
+    def delete_campaign(self, campaign_id: str) -> bool:
+        """Delete a campaign and all associated data"""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        # Delete session notes first
+        cursor.execute("DELETE FROM session_notes WHERE campaign_id = ?", (campaign_id,))
+
+        # Delete events
+        cursor.execute("DELETE FROM campaign_events WHERE campaign_id = ?", (campaign_id,))
+
+        # Delete campaign
+        cursor.execute("DELETE FROM campaigns WHERE id = ?", (campaign_id,))
+
+        deleted = cursor.rowcount > 0
+        conn.commit()
+        conn.close()
+
+        return deleted
+
+    def add_character_to_campaign(self, campaign_id: str, character_id: str) -> bool:
+        """Add a character to a campaign"""
+        campaign = self.load_campaign(campaign_id)
+        if not campaign:
+            return False
+
+        campaign.add_character(character_id)
+        self.save_campaign(campaign)
+        return True
+
+    def remove_character_from_campaign(self, campaign_id: str, character_id: str) -> bool:
+        """Remove a character from a campaign"""
+        campaign = self.load_campaign(campaign_id)
+        if not campaign:
+            return False
+
+        campaign.remove_character(character_id)
+        self.save_campaign(campaign)
+        return True
+
+    def start_new_session(self, campaign_id: str) -> bool:
+        """Start a new session for a campaign"""
+        campaign = self.load_campaign(campaign_id)
+        if not campaign:
+            return False
+
+        campaign.start_new_session()
+        self.save_campaign(campaign)
+        return True
+
+    def add_event(
+        self,
+        campaign_id: str,
+        event_type: str,
+        title: str,
+        description: str,
+        session_number: Optional[int] = None,
+        characters_involved: Optional[List[str]] = None,
+        npcs_involved: Optional[List[str]] = None,
+        locations: Optional[List[str]] = None,
+        importance: int = 3
+    ) -> Optional[CampaignEvent]:
+        """Add an event to a campaign"""
+        campaign = self.load_campaign(campaign_id)
+        if not campaign:
+            return None
+
+        # Use current session if not specified
+        if session_number is None:
+            session_number = campaign.current_session
+
+        # Create event
+        event_id = f"{campaign_id}-event-{datetime.now().timestamp()}"
+        event = CampaignEvent(
+            id=event_id,
+            campaign_id=campaign_id,
+            session_number=session_number,
+            event_type=EventType(event_type),
+            title=title,
+            description=description,
+            characters_involved=characters_involved or [],
+            npcs_involved=npcs_involved or [],
+            locations=locations or [],
+            importance=importance
+        )
+
+        # Save to database
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cursor.execute("""
+            INSERT INTO campaign_events (
+                id, campaign_id, session_number, event_type, title, description,
+                characters_involved, npcs_involved, locations, consequences,
+                items_gained, items_lost, experience_awarded, timestamp,
+                importance, tags, gm_notes, player_visible
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """, (
+            event.id,
+            event.campaign_id,
+            event.session_number,
+            event.event_type.value,
+            event.title,
+            event.description,
+            json.dumps(event.characters_involved),
+            json.dumps(event.npcs_involved),
+            json.dumps(event.locations),
+            json.dumps(event.consequences),
+            json.dumps(event.items_gained),
+            json.dumps(event.items_lost),
+            event.experience_awarded,
+            event.timestamp.isoformat(),
+            event.importance,
+            json.dumps(event.tags),
+            event.gm_notes,
+            event.player_visible
+        ))
+
+        conn.commit()
+        conn.close()
+
+        # Update campaign memory
+        campaign.add_event(event)
+        self.save_campaign(campaign)
+
+        return event
+
+    def get_campaign_events(self, campaign_id: str, session_number: Optional[int] = None) -> List[CampaignEvent]:
+        """Get events for a campaign"""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        if session_number:
+            cursor.execute(
+                "SELECT * FROM campaign_events WHERE campaign_id = ? AND session_number = ? ORDER BY timestamp",
+                (campaign_id, session_number)
+            )
+        else:
+            cursor.execute(
+                "SELECT * FROM campaign_events WHERE campaign_id = ? ORDER BY timestamp",
+                (campaign_id,)
+            )
+
+        rows = cursor.fetchall()
+        conn.close()
+
+        events = []
+        for row in rows:
+            event_data = {
+                'id': row[0],
+                'campaign_id': row[1],
+                'session_number': row[2],
+                'event_type': row[3],
+                'title': row[4],
+                'description': row[5],
+                'characters_involved': json.loads(row[6]) if row[6] else [],
+                'npcs_involved': json.loads(row[7]) if row[7] else [],
+                'locations': json.loads(row[8]) if row[8] else [],
+                'consequences': json.loads(row[9]) if row[9] else [],
+                'items_gained': json.loads(row[10]) if row[10] else [],
+                'items_lost': json.loads(row[11]) if row[11] else [],
+                'experience_awarded': row[12],
+                'timestamp': row[13],
+                'importance': row[14],
+                'tags': json.loads(row[15]) if row[15] else [],
+                'gm_notes': row[16],
+                'player_visible': row[17]
+            }
+            events.append(CampaignEvent(**event_data))
+
+        return events
+
+    def export_campaign_summary(self, campaign_id: str) -> str:
+        """Export campaign summary as markdown"""
+        campaign = self.load_campaign(campaign_id)
+        if not campaign:
+            return "Campaign not found"
+
+        return campaign.to_markdown()
+
+    def synthesize_campaign_from_characters(
+        self,
+        characters: List[Character],
+        game_master: str = "",
+        additional_notes: str = ""
+    ) -> Campaign:
+        """
+        Synthesize a campaign tailored to the provided characters using AI.
+
+        Analyzes the party composition, backstories, alignments, and creates
+        a custom campaign that fits the characters.
+        """
+
+        # Build character analysis
+        party_analysis = []
+        for char in characters:
+            party_analysis.append(f"""
+- **{char.name}** (Level {char.level} {char.race.value} {char.character_class.value})
+  - Alignment: {char.alignment.value}
+  - Background: {char.background.background_type}
+  - Backstory: {char.background.backstory[:200]}...
+  - Personality: {char.background.personality_traits[:150]}...""")
+
+        party_summary = "\n".join(party_analysis)
+
+        # Calculate party level range
+        levels = [char.level for char in characters]
+        min_level = min(levels)
+        max_level = max(levels)
+        avg_level = sum(levels) // len(levels)
+        level_range = f"{min_level}-{max_level}" if min_level != max_level else f"{min_level}"
+
+        # Determine appropriate challenge level
+        if avg_level <= 3:
+            tier = "Tier 1 (Local Heroes)"
+            scope = "local region or small kingdom"
+        elif avg_level <= 10:
+            tier = "Tier 2 (Heroes of the Realm)"
+            scope = "kingdom or large region"
+        elif avg_level <= 16:
+            tier = "Tier 3 (Masters of the Realm)"
+            scope = "continent or multiple kingdoms"
+        else:
+            tier = "Tier 4 (Masters of the World)"
+            scope = "entire world or planar"
+
+        # Create AI prompt for campaign synthesis
+        prompt = f"""You are an expert Dungeon Master creating a COMPLETE campaign guide for D&D 5e.
+
+**Party Composition ({len(characters)} characters, Level {level_range}):**
+{party_summary}
+
+**Campaign Tier:** {tier}
+**Appropriate Scope:** {scope}
+
+{f"**Additional DM Notes:** {additional_notes}" if additional_notes else ""}
+
+Create a DETAILED campaign that weaves all these characters together. Include:
+
+1. **Character Connections**: How do these characters know each other or become connected?
+2. **Personal Stakes**: What does each character have to lose/gain?
+3. **Villain Details**: Full profiles with motivations and how they threaten each PC
+4. **World Details**: Specific locations, politics, and cultural elements
+5. **Adventure Hooks**: 3-4 specific scenarios that pull characters in
+6. **First Session Outline**: Concrete opening scenario
+7. **Story Progression**: Where the campaign leads over 5-10 sessions
+
+Generate a comprehensive campaign document with these sections:
+
+**CAMPAIGN_NAME:** (Epic, memorable name - 2-5 words)
+
+**THEME:** (Choose ONE: High Fantasy, Dark Fantasy, Urban Fantasy, Political Intrigue, Horror, Exploration, Dungeon Crawl, or Custom)
+
+**WORLD_NAME:** (Name of the world/realm)
+
+**STARTING_LOCATION:** (Town, city, or region where adventure begins)
+
+**SETTING:** (3-4 sentences about the world, its current political state, and atmosphere)
+
+**SUMMARY:** (4-5 sentences explaining the campaign hook and what drives the story)
+
+**CONFLICT:** (2-3 sentences describing the central threat and why it matters)
+
+**FACTIONS:** (List 3-4 factions with brief descriptions, format: "Faction Name - description")
+
+**VILLAINS:** (2-3 detailed villain profiles with:
+- Name and role
+- Motivation (what they want and why)
+- Connection to party (which PCs they threaten and how)
+- Methods (how they operate)
+Format: "Villain Name - Role | Motivation | Connections | Methods")
+
+**CHARACTER_CONNECTIONS:** REQUIRED - For EACH party member listed above, explain how they fit (Format: "Name: connection details | Name2: connection details | ...")
+
+**ADVENTURE_HOOKS:** REQUIRED - List 3-4 specific hooks separated by pipes (Format: "Hook 1 details | Hook 2 details | Hook 3 details")
+
+**FIRST_SESSION:** REQUIRED - Detailed opening scene (Format: "Scene description")
+
+**SESSION_OUTLINES:** REQUIRED - Sessions 2-5 separated by pipes (Format: "Session 2 details | Session 3 details | Session 4 details | Session 5 details")
+
+**MYSTERIES:** REQUIRED - 2-3 mysteries separated by pipes (Format: "Mystery 1 | Mystery 2 | Mystery 3")
+
+**KEY_NPCS:** REQUIRED - 3-4 NPCs separated by pipes (Format: "NPC Name - role and connection | NPC2 Name - role and connection | ...")
+
+**LOCATIONS:** REQUIRED - 3-4 locations separated by pipes (Format: "Location Name - description | Location2 Name - description | ...")
+
+**STORY_ARC:** (First major story arc with clear beginning, middle, and climax)
+
+Format your response EXACTLY as follows (DO NOT SKIP ANY FIELDS):
+---
+CAMPAIGN_NAME: [name]
+THEME: [theme]
+WORLD_NAME: [world]
+STARTING_LOCATION: [location]
+SETTING: [setting details]
+SUMMARY: [campaign summary]
+CONFLICT: [main conflict]
+FACTIONS: [faction1 - desc | faction2 - desc | faction3 - desc]
+VILLAINS: [villain1 details | villain2 details]
+CHARACTER_CONNECTIONS: [char1: how they fit | char2: how they fit | char3: how they fit | char4: how they fit]
+ADVENTURE_HOOKS: [hook1 description in 2-3 sentences | hook2 description | hook3 description | hook4 description]
+FIRST_SESSION: [opening scene details]
+SESSION_OUTLINES: [session 2 outline | session 3 outline | session 4 outline | session 5 outline]
+MYSTERIES: [mystery1 details | mystery2 details | mystery3 details]
+KEY_NPCS: [NPC Name - their role and connection to party | NPC2 Name - role and connection | NPC3 Name - role | NPC4 Name - role]
+LOCATIONS: [Location Name - description of place | Location2 Name - description | Location3 Name - description | Location4 Name - description]
+STORY_ARC: [arc details]
+---
+
+IMPORTANT: Every field listed above MUST have content. Use pipe separators (|) between items in list fields."""
+
+        # Get AI response
+        response = self.ai_client.generate_creative(prompt)
+
+        # Parse the response
+        parsed = self._parse_campaign_synthesis(response)
+
+        # If critical fields are missing, make a second focused call
+        missing_fields = []
+        if not parsed.get('character_connections') or len(parsed.get('character_connections', [])) == 0:
+            missing_fields.append('CHARACTER_CONNECTIONS')
+        if not parsed.get('adventure_hooks') or len(parsed.get('adventure_hooks', [])) == 0:
+            missing_fields.append('ADVENTURE_HOOKS')
+        if not parsed.get('key_npcs') or len(parsed.get('key_npcs', [])) == 0:
+            missing_fields.append('KEY_NPCS')
+        if not parsed.get('locations') or len(parsed.get('locations', [])) == 0:
+            missing_fields.append('LOCATIONS')
+        if not parsed.get('session_outlines') or len(parsed.get('session_outlines', [])) == 0:
+            missing_fields.append('SESSION_OUTLINES')
+
+        if missing_fields:
+            # Make focused call for missing fields
+            fields_list = ' '.join(['**' + field + ':**' for field in missing_fields])
+            format_template = '\n'.join([field + ': [details | more details | etc]' for field in missing_fields])
+
+            followup_prompt = f"""Campaign: {parsed.get('name', 'Campaign')}
+Setting: {parsed.get('setting', '')}
+
+Party:
+{party_summary}
+
+Generate ONLY these missing campaign elements. Use pipe (|) separators between items:
+
+{fields_list}
+
+Format:
+---
+{format_template}
+---"""
+
+            followup_response = self.ai_client.generate_creative(followup_prompt)
+            followup_parsed = self._parse_campaign_synthesis(followup_response)
+
+            # Merge the results
+            for key in ['character_connections', 'adventure_hooks', 'key_npcs', 'locations', 'session_outlines']:
+                if key in followup_parsed and followup_parsed[key]:
+                    parsed[key] = followup_parsed[key]
+
+        # Create campaign
+        campaign = self.create_campaign(
+            name=parsed.get('name', 'Untitled Campaign'),
+            theme=parsed.get('theme', 'High Fantasy'),
+            setting=parsed.get('setting', 'A fantasy realm awaits...'),
+            summary=parsed.get('summary', 'An epic adventure begins...'),
+            main_conflict=parsed.get('conflict', 'Evil threatens the land...'),
+            game_master=game_master,
+            world_name=parsed.get('world_name', 'The Realm'),
+            starting_location=parsed.get('starting_location', 'The Crossroads'),
+            level_range=level_range,
+            party_size=len(characters)
+        )
+
+        # Load the created campaign and add additional details
+        campaign = self.load_campaign(campaign.id)
+
+        # Add factions, villains, and mysteries
+        if 'factions' in parsed:
+            campaign.key_factions = parsed['factions']
+        if 'villains' in parsed:
+            campaign.major_villains = parsed['villains']
+        if 'mysteries' in parsed:
+            campaign.central_mysteries = parsed['mysteries']
+        if 'story_arc' in parsed:
+            campaign.current_arc = parsed['story_arc']
+
+        # Add detailed campaign notes with all the extra information
+        campaign_notes = self._build_campaign_notes(parsed)
+        campaign.notes = campaign_notes
+
+        # Add all characters to the campaign
+        for char in characters:
+            campaign.add_character(char.id)
+
+        # Save updated campaign
+        self.save_campaign(campaign)
+
+        return campaign
+
+    def _build_campaign_notes(self, parsed: dict) -> str:
+        """Build detailed campaign notes from parsed data"""
+        notes = []
+
+        if 'character_connections' in parsed:
+            notes.append("## Character Connections\n")
+            for conn in parsed['character_connections']:
+                notes.append(f"- {conn}\n")
+            notes.append("\n")
+
+        if 'adventure_hooks' in parsed:
+            notes.append("## Adventure Hooks\n")
+            for i, hook in enumerate(parsed['adventure_hooks'], 1):
+                notes.append(f"{i}. {hook}\n")
+            notes.append("\n")
+
+        if 'first_session' in parsed:
+            notes.append("## First Session Opening\n")
+            notes.append(f"{parsed['first_session']}\n\n")
+
+        if 'session_outlines' in parsed:
+            notes.append("## Session Progression\n")
+            for i, outline in enumerate(parsed['session_outlines'], 2):
+                notes.append(f"**Session {i}:** {outline}\n")
+            notes.append("\n")
+
+        if 'key_npcs' in parsed:
+            notes.append("## Key NPCs\n")
+            for npc in parsed['key_npcs']:
+                notes.append(f"- {npc}\n")
+            notes.append("\n")
+
+        if 'locations' in parsed:
+            notes.append("## Key Locations\n")
+            for loc in parsed['locations']:
+                notes.append(f"- {loc}\n")
+            notes.append("\n")
+
+        return "".join(notes)
+
+    def _parse_campaign_synthesis(self, ai_response: str) -> dict:
+        """Parse AI response for campaign synthesis"""
+        parsed = {}
+
+        # Extract content between --- markers
+        if '---' in ai_response:
+            parts = ai_response.split('---')
+            if len(parts) >= 2:
+                content = parts[1]
+            else:
+                content = ai_response
+        else:
+            content = ai_response
+
+        # Parse each field
+        lines = content.strip().split('\n')
+        for line in lines:
+            if ':' in line:
+                key, value = line.split(':', 1)
+                key = key.strip().lower().replace('campaign_', '').replace('_', '_')
+                value = value.strip()
+
+                # Handle pipe-separated fields (detailed lists)
+                if key in ['factions', 'villains', 'character_connections', 'adventure_hooks',
+                          'session_outlines', 'mysteries', 'key_npcs', 'locations']:
+                    # Split by pipe and clean up each item
+                    parsed[key] = [item.strip() for item in value.split('|') if item.strip()]
+                else:
+                    parsed[key] = value
+
+        return parsed
+
+    def auto_generate_next_session(self, campaign_id: str) -> dict:
+        """
+        Autonomously generate the next session based on campaign progress.
+
+        This is a LOW-RISK autonomous feature that:
+        - Analyzes campaign state and previous sessions
+        - Generates structured session content
+        - Does NOT modify the campaign directly
+        - Returns session data for user review/approval
+
+        Args:
+            campaign_id: Campaign identifier
+
+        Returns:
+            dict with session details (title, opening, encounters, npcs, etc.)
+        """
+        campaign = self.load_campaign(campaign_id)
+        if not campaign:
+            return {"error": "Campaign not found"}
+
+        # Get session context
+        events = self.get_campaign_events(campaign_id)
+        session_events = [e for e in events if e.type == EventType.SESSION]
+        current_session_num = len(session_events) + 1
+        last_session = session_events[-1] if session_events else None
+
+        # Get session notes from previous sessions (last 2-3 sessions for context)
+        all_session_notes = self.get_session_notes(campaign_id)
+        recent_notes = all_session_notes[:3] if all_session_notes else []
+
+        # Build session notes context
+        notes_context = ""
+        if recent_notes:
+            notes_context = "\n**PREVIOUS SESSION NOTES:**\n\n"
+            for note in reversed(recent_notes):  # Chronological order
+                notes_context += f"**Session {note.session_number} Notes:**\n"
+                # Limit each session's notes to 2000 characters
+                truncated_notes = note.notes[:2000]
+                if len(note.notes) > 2000:
+                    truncated_notes += "\n... (notes truncated)"
+                notes_context += f"{truncated_notes}\n\n"
+
+        # Build last session context
+        if not notes_context:
+            if last_session:
+                last_session_info = f"**Last Session Summary:**\n{last_session.description}"
+            else:
+                last_session_info = "**Last Session Summary:**\nThis is the first session - use the campaign first session opening from the notes."
+        else:
+            last_session_info = notes_context
+
+        # Build context for AI
+        prompt = f"""You are an expert Dungeon Master planning the next D&D 5e session.
+
+**Campaign:** {campaign.name}
+**Theme:** {campaign.theme}
+**Setting:** {campaign.setting}
+**Current Arc:** {campaign.current_arc}
+**Party Size:** {campaign.party_size}
+**Session Number:** {current_session_num}
+
+**Main Conflict:** {campaign.main_conflict}
+
+**Key Factions:** {', '.join(campaign.key_factions) if campaign.key_factions else 'None yet'}
+
+**Major Villains:** {', '.join(campaign.major_villains) if campaign.major_villains else 'None yet'}
+
+{last_session_info}
+
+**Campaign Notes:**
+{campaign.notes[:1000] if campaign.notes else 'No additional notes'}
+
+---
+
+Based on what happened in the previous sessions (see session notes above), generate a complete
+session plan for Session {current_session_num} that:
+
+1. Builds on player choices and consequences documented in previous session notes
+2. Follows up on narrative threads mentioned in the notes
+3. Responds to how players engaged with NPCs and locations
+4. Incorporates improvised content that worked well
+5. Addresses unresolved plot hooks from the notes
+
+Include:
+
+1. **SESSION_TITLE:** A compelling title for this session (3-6 words)
+2. **OPENING_SCENE:** The opening narration/scene (2-3 paragraphs)
+3. **KEY_ENCOUNTERS:** 2-4 encounters (combat, social, exploration) separated by pipes (|)
+4. **NPCS_FEATURED:** NPCs that appear in this session, separated by pipes (|)
+5. **LOCATIONS:** Locations visited in this session, separated by pipes (|)
+6. **PLOT_DEVELOPMENTS:** Major plot points that advance this session, separated by pipes (|)
+7. **POTENTIAL_OUTCOMES:** 2-3 possible ways the session could end, separated by pipes (|)
+8. **REWARDS:** Treasure, XP, or story rewards, separated by pipes (|)
+9. **CLIFFHANGER:** Optional cliffhanger for next session (1-2 sentences)
+
+Format your response EXACTLY as:
+---
+SESSION_TITLE: [title]
+OPENING_SCENE: [opening narration in 2-3 paragraphs]
+KEY_ENCOUNTERS: [encounter 1 description | encounter 2 description | encounter 3 description]
+NPCS_FEATURED: [NPC name and role | NPC2 name and role | NPC3 name and role]
+LOCATIONS: [location 1 | location 2 | location 3]
+PLOT_DEVELOPMENTS: [development 1 | development 2 | development 3]
+POTENTIAL_OUTCOMES: [outcome 1 | outcome 2 | outcome 3]
+REWARDS: [reward 1 | reward 2 | reward 3]
+CLIFFHANGER: [cliffhanger sentence]
+---
+"""
+
+        # Generate session content
+        ai_response = self.ai_client.generate_creative(prompt)
+
+        # Parse the response
+        session_data = self._parse_session_generation(ai_response)
+
+        # Add metadata
+        session_data['session_number'] = current_session_num
+        session_data['campaign_id'] = campaign_id
+        session_data['generated_at'] = datetime.now().isoformat()
+        session_data['auto_generated'] = True
+        session_data['used_session_notes'] = len(recent_notes) > 0
+        session_data['notes_count'] = len(recent_notes)
+
+        return session_data
+
+    def _parse_session_generation(self, ai_response: str) -> dict:
+        """Parse AI response for session generation"""
+        parsed = {}
+
+        # Extract content between --- markers
+        if '---' in ai_response:
+            parts = ai_response.split('---')
+            content = parts[1] if len(parts) >= 2 else ai_response
+        else:
+            content = ai_response
+
+        # Parse each field
+        lines = content.strip().split('\n')
+        for line in lines:
+            if ':' in line:
+                key, value = line.split(':', 1)
+                key = key.strip().lower().replace(' ', '_')
+                value = value.strip()
+
+                # Handle pipe-separated fields
+                if key in ['key_encounters', 'npcs_featured', 'locations',
+                          'plot_developments', 'potential_outcomes', 'rewards']:
+                    parsed[key] = [item.strip() for item in value.split('|') if item.strip()]
+                else:
+                    parsed[key] = value
+
+        return parsed
+
+    def save_session_notes(
+        self,
+        campaign_id: str,
+        session_number: int,
+        notes: str,
+        file_name: Optional[str] = None,
+        file_type: Optional[str] = None
+    ) -> SessionNotes:
+        """
+        Save session notes for a campaign.
+
+        Args:
+            campaign_id: Campaign identifier
+            session_number: Session number
+            notes: Freeform session notes content
+            file_name: Optional original filename if uploaded
+            file_type: Optional file extension (.txt, .md, .docx, .pdf)
+
+        Returns:
+            SessionNotes object
+        """
+        # Create session notes object
+        session_notes = SessionNotes(
+            id=f"{campaign_id}-session-{session_number}",
+            campaign_id=campaign_id,
+            session_number=session_number,
+            notes=notes,
+            uploaded_at=datetime.now(),
+            file_name=file_name,
+            file_type=file_type
+        )
+
+        # Save to database (upsert - replace if exists)
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cursor.execute("""
+            INSERT OR REPLACE INTO session_notes
+            (id, campaign_id, session_number, notes, uploaded_at, file_name, file_type)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+        """, (
+            session_notes.id,
+            session_notes.campaign_id,
+            session_notes.session_number,
+            session_notes.notes,
+            session_notes.uploaded_at.isoformat(),
+            session_notes.file_name,
+            session_notes.file_type
+        ))
+
+        conn.commit()
+        conn.close()
+
+        return session_notes
+
+    def get_session_notes(
+        self,
+        campaign_id: str,
+        session_number: Optional[int] = None
+    ) -> List[SessionNotes]:
+        """
+        Get session notes for a campaign.
+
+        Args:
+            campaign_id: Campaign identifier
+            session_number: Optional specific session number (if None, returns all)
+
+        Returns:
+            List of SessionNotes objects (ordered by session number DESC)
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        if session_number is not None:
+            cursor.execute("""
+                SELECT id, campaign_id, session_number, notes, uploaded_at, file_name, file_type
+                FROM session_notes
+                WHERE campaign_id = ? AND session_number = ?
+            """, (campaign_id, session_number))
+        else:
+            cursor.execute("""
+                SELECT id, campaign_id, session_number, notes, uploaded_at, file_name, file_type
+                FROM session_notes
+                WHERE campaign_id = ?
+                ORDER BY session_number DESC
+            """, (campaign_id,))
+
+        rows = cursor.fetchall()
+        conn.close()
+
+        # Convert to SessionNotes objects
+        notes_list = []
+        for row in rows:
+            notes_list.append(SessionNotes(
+                id=row[0],
+                campaign_id=row[1],
+                session_number=row[2],
+                notes=row[3],
+                uploaded_at=datetime.fromisoformat(row[4]),
+                file_name=row[5],
+                file_type=row[6]
+            ))
+
+        return notes_list
+
+    def delete_session_notes(self, campaign_id: str, session_number: int) -> bool:
+        """
+        Delete session notes for a specific session.
+
+        Args:
+            campaign_id: Campaign identifier
+            session_number: Session number
+
+        Returns:
+            True if deleted, False if not found
+        """
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        cursor.execute("""
+            DELETE FROM session_notes
+            WHERE campaign_id = ? AND session_number = ?
+        """, (campaign_id, session_number))
+
+        deleted = cursor.rowcount > 0
+
+        conn.commit()
+        conn.close()
+
+        return deleted

src/agents/character_agent.py

@@ -0,0 +1,854 @@
+"""
+Character Creator Agent - D&D character generation for D'n'D Campaign Manager
+"""
+
+import uuid
+from typing import Optional, Dict, Any
+from datetime import datetime
+
+from src.models.character import (
+    Character, CharacterStats, CharacterBackground,
+    DnDRace, DnDClass, Alignment, HIT_DICE_BY_CLASS
+)
+from src.utils.ai_client import get_ai_client
+from src.utils.dice import DiceRoller
+from src.utils.database import get_database
+from src.utils.validators import validate_character
+from src.utils.image_generator import get_image_generator
+
+
+class CharacterAgent:
+    """Agent for creating D&D characters"""
+
+    def __init__(self):
+        self.ai_client = get_ai_client()
+        self.dice_roller = DiceRoller()
+        self.database = get_database()
+        try:
+            self.image_generator = get_image_generator()
+        except Exception as e:
+            print(f"Warning: Image generator not available: {e}")
+            self.image_generator = None
+
+    def create_character(
+        self,
+        name: Optional[str] = None,
+        race: Optional[DnDRace] = None,
+        character_class: Optional[DnDClass] = None,
+        level: int = 1,
+        background_type: Optional[str] = None,
+        personality_prompt: Optional[str] = None,
+        stats_method: str = "standard_array",  # "roll", "standard_array", "point_buy"
+        custom_stats: Optional[Dict[str, int]] = None,
+    ) -> Character:
+        """
+        Create a complete D&D character
+
+        Args:
+            name: Character name (auto-generated if None)
+            race: Character race (random if None)
+            character_class: Character class (random if None)
+            level: Starting level (1-20)
+            background_type: Background type
+            personality_prompt: Prompt to generate personality
+            stats_method: How to generate ability scores
+            custom_stats: Pre-set ability scores
+
+        Returns:
+            Complete Character object
+        """
+        # Generate character ID
+        character_id = str(uuid.uuid4())
+
+        # Generate name if not provided
+        if not name:
+            name = self._generate_name(race, character_class)
+
+        # Select race and class if not provided
+        if not race:
+            race = self._select_random_race()
+        if not character_class:
+            character_class = self._select_random_class()
+
+        # Generate ability scores
+        if custom_stats:
+            stats = CharacterStats(**custom_stats)
+        else:
+            stats = self._generate_stats(stats_method)
+
+        # Apply racial ability score bonuses (D&D 5e rule)
+        stats = self._apply_racial_bonuses(stats, race)
+
+        # Calculate HP
+        max_hp = self._calculate_starting_hp(character_class, stats.constitution_modifier, level)
+
+        # Generate background and personality
+        background = self._generate_background(
+            name, race, character_class, background_type, personality_prompt
+        )
+
+        # Generate alignment based on personality
+        alignment = self._determine_alignment(background)
+
+        # Get starting equipment
+        equipment = self._get_starting_equipment(character_class)
+
+        # Get class features
+        features = self._get_class_features(character_class, level)
+
+        # Get proficiencies
+        proficiencies = self._get_proficiencies(character_class, background.background_type)
+
+        # Calculate AC (base 10 + dex modifier)
+        armor_class = 10 + stats.dexterity_modifier
+
+        # Create character
+        character = Character(
+            id=character_id,
+            name=name,
+            race=race,
+            character_class=character_class,
+            level=level,
+            alignment=alignment,
+            stats=stats,
+            max_hit_points=max_hp,
+            current_hit_points=max_hp,
+            armor_class=armor_class,
+            background=background,
+            equipment=equipment,
+            features=features,
+            proficiencies=proficiencies,
+        )
+
+        # Validate character
+        is_valid, errors = validate_character(character)
+        if not is_valid:
+            raise ValueError(f"Character validation failed: {', '.join(errors)}")
+
+        # Save to database
+        self.save_character(character)
+
+        return character
+
+    def generate_name(
+        self,
+        race: Optional[DnDRace] = None,
+        character_class: Optional[DnDClass] = None,
+        gender: Optional[str] = None
+    ) -> str:
+        """
+        PUBLIC method to generate character name using AI
+        Can be called independently of character creation
+
+        Args:
+            race: Character race (optional)
+            character_class: Character class (optional)
+            gender: Character gender (optional)
+
+        Returns:
+            Generated character name
+        """
+        gender_text = f"\nGender: {gender}" if gender and gender != "Not specified" else ""
+
+        prompt = f"""Generate a single fantasy character name for a D&D character.
+
+Race: {race.value if race else 'any race'}
+Class: {character_class.value if character_class else 'any class'}{gender_text}
+
+Requirements:
+- Just the name, nothing else
+- Make it sound appropriate for the race{' and gender' if gender_text else ''}
+- Make it memorable and fitting for an adventurer
+- 2-3 words maximum
+
+Example formats:
+- "Thorin Ironforge" (Male Dwarf)
+- "Elara Moonwhisper" (Female Elf)
+- "Grunk Bonecrusher" (Male Orc)
+- "Pip Thornberry" (Any Halfling)
+
+Generate only the name:"""
+
+        try:
+            name = self.ai_client.generate_creative(prompt).strip()
+            # Clean up any extra text
+            name = name.split('\n')[0].strip('"\'')
+            return name
+        except Exception as e:
+            # Fallback to simple name generation
+            import random
+            prefixes = ["Brave", "Bold", "Swift", "Wise", "Dark", "Bright"]
+            suffixes = ["blade", "heart", "forge", "walker", "runner", "seeker"]
+            return f"{random.choice(prefixes)}{random.choice(suffixes)}"
+
+    def _generate_name(self, race: Optional[DnDRace], character_class: Optional[DnDClass]) -> str:
+        """
+        PRIVATE method - calls public generate_name
+        Kept for backward compatibility
+        """
+        return self.generate_name(race, character_class)
+
+    def _select_random_race(self) -> DnDRace:
+        """Select random race"""
+        import random
+        return random.choice(list(DnDRace))
+
+    def _select_random_class(self) -> DnDClass:
+        """Select random class"""
+        import random
+        return random.choice(list(DnDClass))
+
+    def _generate_stats(self, method: str) -> CharacterStats:
+        """Generate ability scores"""
+        if method == "roll":
+            # Roll 4d6 drop lowest
+            stats_dict = self.dice_roller.roll_stats()
+            return CharacterStats(**stats_dict)
+
+        elif method == "standard_array":
+            # Standard array: 15, 14, 13, 12, 10, 8
+            import random
+            array = [15, 14, 13, 12, 10, 8]
+            random.shuffle(array)
+            return CharacterStats(
+                strength=array[0],
+                dexterity=array[1],
+                constitution=array[2],
+                intelligence=array[3],
+                wisdom=array[4],
+                charisma=array[5]
+            )
+
+        elif method == "point_buy":
+            # Balanced point buy (27 points)
+            return CharacterStats(
+                strength=13,
+                dexterity=14,
+                constitution=13,
+                intelligence=12,
+                wisdom=10,
+                charisma=10
+            )
+
+        else:
+            # Default to standard array
+            return CharacterStats()
+
+    def _apply_racial_bonuses(self, stats: CharacterStats, race: DnDRace) -> CharacterStats:
+        """Apply racial ability score increases per D&D 5e PHB"""
+        racial_bonuses = {
+            DnDRace.HUMAN: {"strength": 1, "dexterity": 1, "constitution": 1,
+                           "intelligence": 1, "wisdom": 1, "charisma": 1},
+            DnDRace.ELF: {"dexterity": 2},
+            DnDRace.DWARF: {"constitution": 2},
+            DnDRace.HALFLING: {"dexterity": 2},
+            DnDRace.DRAGONBORN: {"strength": 2, "charisma": 1},
+            DnDRace.GNOME: {"intelligence": 2},
+            DnDRace.HALF_ELF: {"charisma": 2},  # +1 to two highest (auto-assigned)
+            DnDRace.HALF_ORC: {"strength": 2, "constitution": 1},
+            DnDRace.TIEFLING: {"charisma": 2, "intelligence": 1},
+            DnDRace.DROW: {"dexterity": 2, "charisma": 1},
+        }
+
+        bonuses = racial_bonuses.get(race, {})
+        stats_dict = stats.model_dump()
+
+        # Apply bonuses, capping at 20 per D&D 5e standard rules
+        for ability, bonus in bonuses.items():
+            stats_dict[ability] = min(20, stats_dict[ability] + bonus)
+
+        # Half-Elf special case: +1 to two highest abilities after CHA
+        if race == DnDRace.HALF_ELF:
+            # Find two highest abilities (excluding charisma which already got +2)
+            abilities_except_cha = [(k, v) for k, v in stats_dict.items() if k != "charisma"]
+            abilities_except_cha.sort(key=lambda x: x[1], reverse=True)
+
+            # Apply +1 to top two (capped at 20)
+            for i in range(min(2, len(abilities_except_cha))):
+                ability_name = abilities_except_cha[i][0]
+                stats_dict[ability_name] = min(20, stats_dict[ability_name] + 1)
+
+        return CharacterStats(**stats_dict)
+
+    def _calculate_starting_hp(self, character_class: DnDClass, con_modifier: int, level: int) -> int:
+        """Calculate starting hit points (D&D 5e rules)"""
+        hit_die = HIT_DICE_BY_CLASS.get(character_class, 8)
+
+        # First level: max hit die + con mod
+        # Subsequent levels: average of hit die + con mod
+        first_level_hp = hit_die + con_modifier
+        subsequent_hp = ((hit_die // 2) + 1 + con_modifier) * (level - 1)
+
+        return max(1, first_level_hp + subsequent_hp)
+
+    def _generate_background(
+        self,
+        name: str,
+        race: DnDRace,
+        character_class: DnDClass,
+        background_type: Optional[str],
+        personality_prompt: Optional[str]
+    ) -> CharacterBackground:
+        """Generate character background and personality using AI"""
+        system_prompt = """You are a D&D character background generator.
+Create compelling, detailed character backgrounds that feel authentic and provide hooks for roleplay.
+Be creative but grounded in D&D lore."""
+
+        prompt = f"""Generate a complete character background for:
+
+Name: {name}
+Race: {race.value}
+Class: {character_class.value}
+Background Type: {background_type or 'Adventurer'}
+{f'Additional guidance: {personality_prompt}' if personality_prompt else ''}
+
+Generate in this EXACT format:
+
+PERSONALITY TRAITS:
+- [trait 1]
+- [trait 2]
+
+IDEALS:
+[One core ideal that drives them]
+
+BONDS:
+[What/who they care about most]
+
+FLAWS:
+[A meaningful character flaw]
+
+BACKSTORY:
+[2-3 paragraphs of compelling backstory that explains how they became an adventurer]
+
+GOALS:
+- [goal 1]
+- [goal 2]
+
+Keep it concise but evocative. Focus on what makes this character interesting to play."""
+
+        response = self.ai_client.generate_creative(prompt, system_prompt=system_prompt)
+
+        # Parse response
+        background = self._parse_background_response(response, background_type or "Adventurer")
+
+        return background
+
+    def _parse_background_response(self, response: str, background_type: str) -> CharacterBackground:
+        """Parse AI response into CharacterBackground"""
+        lines = response.strip().split('\n')
+
+        traits = []
+        ideals = ""
+        bonds = ""
+        flaws = ""
+        backstory = ""
+        goals = []
+
+        current_section = None
+        backstory_lines = []
+
+        for line in lines:
+            line = line.strip()
+            if not line:
+                continue
+
+            if line.startswith('PERSONALITY TRAITS:'):
+                current_section = 'traits'
+            elif line.startswith('IDEALS:'):
+                current_section = 'ideals'
+            elif line.startswith('BONDS:'):
+                current_section = 'bonds'
+            elif line.startswith('FLAWS:'):
+                current_section = 'flaws'
+            elif line.startswith('BACKSTORY:'):
+                current_section = 'backstory'
+            elif line.startswith('GOALS:'):
+                current_section = 'goals'
+            elif line.startswith('-'):
+                content = line[1:].strip()
+                if current_section == 'traits':
+                    traits.append(content)
+                elif current_section == 'goals':
+                    goals.append(content)
+            else:
+                if current_section == 'ideals':
+                    ideals += line + " "
+                elif current_section == 'bonds':
+                    bonds += line + " "
+                elif current_section == 'flaws':
+                    flaws += line + " "
+                elif current_section == 'backstory':
+                    backstory_lines.append(line)
+
+        backstory = '\n'.join(backstory_lines).strip()
+
+        return CharacterBackground(
+            background_type=background_type,
+            personality_traits=traits[:3],  # Max 3 traits
+            ideals=ideals.strip(),
+            bonds=bonds.strip(),
+            flaws=flaws.strip(),
+            backstory=backstory,
+            goals=goals
+        )
+
+    def _determine_alignment(self, background: CharacterBackground) -> Alignment:
+        """Determine alignment based on personality"""
+        # Simple heuristic based on ideals and traits
+        ideals_lower = background.ideals.lower()
+
+        if 'law' in ideals_lower or 'order' in ideals_lower or 'honor' in ideals_lower:
+            if 'help' in ideals_lower or 'good' in ideals_lower or 'kind' in ideals_lower:
+                return Alignment.LAWFUL_GOOD
+            elif 'evil' in ideals_lower or 'power' in ideals_lower:
+                return Alignment.LAWFUL_EVIL
+            else:
+                return Alignment.LAWFUL_NEUTRAL
+
+        elif 'chaos' in ideals_lower or 'freedom' in ideals_lower:
+            if 'help' in ideals_lower or 'good' in ideals_lower:
+                return Alignment.CHAOTIC_GOOD
+            elif 'evil' in ideals_lower or 'selfish' in ideals_lower:
+                return Alignment.CHAOTIC_EVIL
+            else:
+                return Alignment.CHAOTIC_NEUTRAL
+
+        else:
+            if 'help' in ideals_lower or 'good' in ideals_lower:
+                return Alignment.NEUTRAL_GOOD
+            elif 'evil' in ideals_lower:
+                return Alignment.NEUTRAL_EVIL
+            else:
+                return Alignment.TRUE_NEUTRAL
+
+    def _get_starting_equipment(self, character_class: DnDClass) -> list:
+        """Get starting equipment for class"""
+        equipment_by_class = {
+            DnDClass.FIGHTER: ["Longsword", "Shield", "Chain Mail", "Explorer's Pack"],
+            DnDClass.WIZARD: ["Spellbook", "Quarterstaff", "Component Pouch", "Scholar's Pack"],
+            DnDClass.ROGUE: ["Shortbow", "Arrows (20)", "Leather Armor", "Thieves' Tools", "Burglar's Pack"],
+            DnDClass.CLERIC: ["Mace", "Scale Mail", "Holy Symbol", "Priest's Pack"],
+            DnDClass.RANGER: ["Longbow", "Arrows (20)", "Leather Armor", "Explorer's Pack"],
+            DnDClass.PALADIN: ["Longsword", "Shield", "Chain Mail", "Holy Symbol", "Priest's Pack"],
+            DnDClass.BARD: ["Rapier", "Lute", "Leather Armor", "Entertainer's Pack"],
+            DnDClass.BARBARIAN: ["Greataxe", "Javelin (4)", "Explorer's Pack"],
+            DnDClass.DRUID: ["Quarterstaff", "Leather Armor", "Druidic Focus", "Explorer's Pack"],
+            DnDClass.MONK: ["Shortsword", "Dart (10)", "Explorer's Pack"],
+            DnDClass.SORCERER: ["Dagger (2)", "Component Pouch", "Dungeoneer's Pack"],
+            DnDClass.WARLOCK: ["Crossbow", "Bolts (20)", "Leather Armor", "Component Pouch", "Scholar's Pack"],
+        }
+
+        return equipment_by_class.get(character_class, ["Basic Equipment"])
+
+    def _get_class_features(self, character_class: DnDClass, level: int) -> list:
+        """Get class features for level (D&D 5e PHB)"""
+        # Features by class and level
+        features_by_level = {
+            DnDClass.FIGHTER: {
+                1: ["Fighting Style", "Second Wind"],
+                2: ["Action Surge (1 use)"],
+                3: ["Martial Archetype"],
+                4: ["Ability Score Improvement"],
+                5: ["Extra Attack (1)"],
+                6: ["Ability Score Improvement"],
+                7: ["Martial Archetype Feature"],
+                8: ["Ability Score Improvement"],
+                9: ["Indomitable (1 use)"],
+                10: ["Martial Archetype Feature"],
+                11: ["Extra Attack (2)"],
+                12: ["Ability Score Improvement"],
+                13: ["Indomitable (2 uses)"],
+                14: ["Ability Score Improvement"],
+                15: ["Martial Archetype Feature"],
+                16: ["Ability Score Improvement"],
+                17: ["Action Surge (2 uses)", "Indomitable (3 uses)"],
+                18: ["Martial Archetype Feature"],
+                19: ["Ability Score Improvement"],
+                20: ["Extra Attack (3)"],
+            },
+            DnDClass.WIZARD: {
+                1: ["Spellcasting", "Arcane Recovery"],
+                2: ["Arcane Tradition"],
+                3: [],
+                4: ["Ability Score Improvement"],
+                5: [],
+                6: ["Arcane Tradition Feature"],
+                7: [],
+                8: ["Ability Score Improvement"],
+                9: [],
+                10: ["Arcane Tradition Feature"],
+                11: [],
+                12: ["Ability Score Improvement"],
+                13: [],
+                14: ["Arcane Tradition Feature"],
+                15: [],
+                16: ["Ability Score Improvement"],
+                17: [],
+                18: ["Spell Mastery"],
+                19: ["Ability Score Improvement"],
+                20: ["Signature Spells"],
+            },
+            DnDClass.ROGUE: {
+                1: ["Expertise", "Sneak Attack (1d6)", "Thieves' Cant"],
+                2: ["Cunning Action"],
+                3: ["Sneak Attack (2d6)", "Roguish Archetype"],
+                4: ["Ability Score Improvement"],
+                5: ["Sneak Attack (3d6)", "Uncanny Dodge"],
+                6: ["Expertise"],
+                7: ["Sneak Attack (4d6)", "Evasion"],
+                8: ["Ability Score Improvement"],
+                9: ["Sneak Attack (5d6)", "Roguish Archetype Feature"],
+                10: ["Ability Score Improvement"],
+                11: ["Sneak Attack (6d6)", "Reliable Talent"],
+                12: ["Ability Score Improvement"],
+                13: ["Sneak Attack (7d6)", "Roguish Archetype Feature"],
+                14: ["Blindsense"],
+                15: ["Sneak Attack (8d6)", "Slippery Mind"],
+                16: ["Ability Score Improvement"],
+                17: ["Sneak Attack (9d6)", "Roguish Archetype Feature"],
+                18: ["Elusive"],
+                19: ["Sneak Attack (10d6)", "Ability Score Improvement"],
+                20: ["Stroke of Luck"],
+            },
+            DnDClass.CLERIC: {
+                1: ["Spellcasting", "Divine Domain"],
+                2: ["Channel Divinity (1/rest)", "Divine Domain Feature"],
+                3: [],
+                4: ["Ability Score Improvement"],
+                5: ["Destroy Undead (CR 1/2)"],
+                6: ["Channel Divinity (2/rest)", "Divine Domain Feature"],
+                7: [],
+                8: ["Ability Score Improvement", "Destroy Undead (CR 1)", "Divine Domain Feature"],
+                9: [],
+                10: ["Divine Intervention"],
+                11: ["Destroy Undead (CR 2)"],
+                12: ["Ability Score Improvement"],
+                13: [],
+                14: ["Destroy Undead (CR 3)"],
+                15: [],
+                16: ["Ability Score Improvement"],
+                17: ["Destroy Undead (CR 4)", "Divine Domain Feature"],
+                18: ["Channel Divinity (3/rest)"],
+                19: ["Ability Score Improvement"],
+                20: ["Divine Intervention Improvement"],
+            },
+            DnDClass.RANGER: {
+                1: ["Favored Enemy", "Natural Explorer"],
+                2: ["Fighting Style", "Spellcasting"],
+                3: ["Ranger Archetype", "Primeval Awareness"],
+                4: ["Ability Score Improvement"],
+                5: ["Extra Attack"],
+                6: ["Favored Enemy Improvement", "Natural Explorer Improvement"],
+                7: ["Ranger Archetype Feature"],
+                8: ["Ability Score Improvement", "Land's Stride"],
+                9: [],
+                10: ["Natural Explorer Improvement", "Hide in Plain Sight"],
+                11: ["Ranger Archetype Feature"],
+                12: ["Ability Score Improvement"],
+                13: [],
+                14: ["Favored Enemy Improvement", "Vanish"],
+                15: ["Ranger Archetype Feature"],
+                16: ["Ability Score Improvement"],
+                17: [],
+                18: ["Feral Senses"],
+                19: ["Ability Score Improvement"],
+                20: ["Foe Slayer"],
+            },
+            DnDClass.PALADIN: {
+                1: ["Divine Sense", "Lay on Hands"],
+                2: ["Fighting Style", "Spellcasting", "Divine Smite"],
+                3: ["Divine Health", "Sacred Oath"],
+                4: ["Ability Score Improvement"],
+                5: ["Extra Attack"],
+                6: ["Aura of Protection"],
+                7: ["Sacred Oath Feature"],
+                8: ["Ability Score Improvement"],
+                9: [],
+                10: ["Aura of Courage"],
+                11: ["Improved Divine Smite"],
+                12: ["Ability Score Improvement"],
+                13: [],
+                14: ["Cleansing Touch"],
+                15: ["Sacred Oath Feature"],
+                16: ["Ability Score Improvement"],
+                17: [],
+                18: ["Aura Improvements"],
+                19: ["Ability Score Improvement"],
+                20: ["Sacred Oath Feature"],
+            },
+            DnDClass.BARD: {
+                1: ["Spellcasting", "Bardic Inspiration (d6)"],
+                2: ["Jack of All Trades", "Song of Rest (d6)"],
+                3: ["Bard College", "Expertise"],
+                4: ["Ability Score Improvement"],
+                5: ["Bardic Inspiration (d8)", "Font of Inspiration"],
+                6: ["Countercharm", "Bard College Feature"],
+                7: [],
+                8: ["Ability Score Improvement"],
+                9: ["Song of Rest (d8)"],
+                10: ["Bardic Inspiration (d10)", "Expertise", "Magical Secrets"],
+                11: [],
+                12: ["Ability Score Improvement"],
+                13: ["Song of Rest (d10)"],
+                14: ["Magical Secrets", "Bard College Feature"],
+                15: ["Bardic Inspiration (d12)"],
+                16: ["Ability Score Improvement"],
+                17: ["Song of Rest (d12)"],
+                18: ["Magical Secrets"],
+                19: ["Ability Score Improvement"],
+                20: ["Superior Inspiration"],
+            },
+            DnDClass.BARBARIAN: {
+                1: ["Rage (2/day)", "Unarmored Defense"],
+                2: ["Reckless Attack", "Danger Sense"],
+                3: ["Primal Path", "Rage (3/day)"],
+                4: ["Ability Score Improvement"],
+                5: ["Extra Attack", "Fast Movement"],
+                6: ["Path Feature", "Rage (4/day)"],
+                7: ["Feral Instinct"],
+                8: ["Ability Score Improvement"],
+                9: ["Brutal Critical (1 die)"],
+                10: ["Path Feature", "Rage (5/day)"],
+                11: ["Relentless Rage"],
+                12: ["Ability Score Improvement", "Rage (6/day)"],
+                13: ["Brutal Critical (2 dice)"],
+                14: ["Path Feature"],
+                15: ["Persistent Rage"],
+                16: ["Ability Score Improvement"],
+                17: ["Brutal Critical (3 dice)", "Rage (Unlimited)"],
+                18: ["Indomitable Might"],
+                19: ["Ability Score Improvement"],
+                20: ["Primal Champion"],
+            },
+            DnDClass.DRUID: {
+                1: ["Druidic", "Spellcasting"],
+                2: ["Wild Shape", "Druid Circle"],
+                3: [],
+                4: ["Wild Shape Improvement", "Ability Score Improvement"],
+                5: [],
+                6: ["Druid Circle Feature"],
+                7: [],
+                8: ["Wild Shape Improvement", "Ability Score Improvement"],
+                9: [],
+                10: ["Druid Circle Feature"],
+                11: [],
+                12: ["Ability Score Improvement"],
+                13: [],
+                14: ["Druid Circle Feature"],
+                15: [],
+                16: ["Ability Score Improvement"],
+                17: [],
+                18: ["Timeless Body", "Beast Spells"],
+                19: ["Ability Score Improvement"],
+                20: ["Archdruid"],
+            },
+            DnDClass.MONK: {
+                1: ["Unarmored Defense", "Martial Arts (1d4)"],
+                2: ["Ki", "Unarmored Movement"],
+                3: ["Monastic Tradition", "Deflect Missiles"],
+                4: ["Ability Score Improvement", "Slow Fall"],
+                5: ["Extra Attack", "Stunning Strike", "Martial Arts (1d6)"],
+                6: ["Ki-Empowered Strikes", "Monastic Tradition Feature"],
+                7: ["Evasion", "Stillness of Mind"],
+                8: ["Ability Score Improvement"],
+                9: ["Unarmored Movement Improvement"],
+                10: ["Purity of Body"],
+                11: ["Monastic Tradition Feature", "Martial Arts (1d8)"],
+                12: ["Ability Score Improvement"],
+                13: ["Tongue of the Sun and Moon"],
+                14: ["Diamond Soul"],
+                15: ["Timeless Body"],
+                16: ["Ability Score Improvement"],
+                17: ["Monastic Tradition Feature", "Martial Arts (1d10)"],
+                18: ["Empty Body"],
+                19: ["Ability Score Improvement"],
+                20: ["Perfect Self"],
+            },
+            DnDClass.SORCERER: {
+                1: ["Spellcasting", "Sorcerous Origin"],
+                2: ["Font of Magic"],
+                3: ["Metamagic (2 options)"],
+                4: ["Ability Score Improvement"],
+                5: [],
+                6: ["Sorcerous Origin Feature"],
+                7: [],
+                8: ["Ability Score Improvement"],
+                9: [],
+                10: ["Metamagic (3 options)"],
+                11: [],
+                12: ["Ability Score Improvement"],
+                13: [],
+                14: ["Sorcerous Origin Feature"],
+                15: [],
+                16: ["Ability Score Improvement"],
+                17: ["Metamagic (4 options)"],
+                18: ["Sorcerous Origin Feature"],
+                19: ["Ability Score Improvement"],
+                20: ["Sorcerous Restoration"],
+            },
+            DnDClass.WARLOCK: {
+                1: ["Otherworldly Patron", "Pact Magic"],
+                2: ["Eldritch Invocations (2)"],
+                3: ["Pact Boon"],
+                4: ["Ability Score Improvement"],
+                5: ["Eldritch Invocations (3)"],
+                6: ["Otherworldly Patron Feature"],
+                7: ["Eldritch Invocations (4)"],
+                8: ["Ability Score Improvement"],
+                9: ["Eldritch Invocations (5)"],
+                10: ["Otherworldly Patron Feature"],
+                11: ["Mystic Arcanum (6th level)"],
+                12: ["Ability Score Improvement", "Eldritch Invocations (6)"],
+                13: ["Mystic Arcanum (7th level)"],
+                14: ["Otherworldly Patron Feature"],
+                15: ["Mystic Arcanum (8th level)", "Eldritch Invocations (7)"],
+                16: ["Ability Score Improvement"],
+                17: ["Mystic Arcanum (9th level)"],
+                18: ["Eldritch Invocations (8)"],
+                19: ["Ability Score Improvement"],
+                20: ["Eldritch Master"],
+            },
+        }
+
+        # Get features for this class up to the current level
+        class_features_by_level = features_by_level.get(character_class, {})
+        all_features = []
+
+        for lvl in range(1, min(level + 1, 21)):
+            all_features.extend(class_features_by_level.get(lvl, []))
+
+        return all_features if all_features else ["Class Features"]
+
+    def _get_proficiencies(self, character_class: DnDClass, background: str) -> list:
+        """
+        Get proficiencies - includes fixed proficiencies and notes about choices
+        Players need to make skill choices in D&D 5e
+        """
+        # Saving throw proficiencies (FIXED - no choice)
+        saves = {
+            DnDClass.FIGHTER: ["Saving Throws: Strength, Constitution"],
+            DnDClass.WIZARD: ["Saving Throws: Intelligence, Wisdom"],
+            DnDClass.ROGUE: ["Saving Throws: Dexterity, Intelligence"],
+            DnDClass.CLERIC: ["Saving Throws: Wisdom, Charisma"],
+            DnDClass.RANGER: ["Saving Throws: Strength, Dexterity"],
+            DnDClass.PALADIN: ["Saving Throws: Wisdom, Charisma"],
+            DnDClass.BARD: ["Saving Throws: Dexterity, Charisma"],
+            DnDClass.BARBARIAN: ["Saving Throws: Strength, Constitution"],
+            DnDClass.DRUID: ["Saving Throws: Intelligence, Wisdom"],
+            DnDClass.MONK: ["Saving Throws: Strength, Dexterity"],
+            DnDClass.SORCERER: ["Saving Throws: Constitution, Charisma"],
+            DnDClass.WARLOCK: ["Saving Throws: Wisdom, Charisma"],
+        }
+
+        # Armor and weapon proficiencies (FIXED - no choice)
+        armor_weapons = {
+            DnDClass.FIGHTER: ["All armor", "All shields", "Simple weapons", "Martial weapons"],
+            DnDClass.WIZARD: ["Weapons: Daggers, Darts, Slings, Quarterstaffs, Light crossbows"],
+            DnDClass.ROGUE: ["Light armor", "Weapons: Simple weapons, Hand crossbows, Longswords, Rapiers, Shortswords", "Tools: Thieves' tools"],
+            DnDClass.CLERIC: ["Light armor", "Medium armor", "Shields", "Simple weapons"],
+            DnDClass.RANGER: ["Light armor", "Medium armor", "Shields", "Simple weapons", "Martial weapons"],
+            DnDClass.PALADIN: ["All armor", "All shields", "Simple weapons", "Martial weapons"],
+            DnDClass.BARD: ["Light armor", "Weapons: Simple weapons, Hand crossbows, Longswords, Rapiers, Shortswords", "Tools: Three musical instruments of your choice"],
+            DnDClass.BARBARIAN: ["Light armor", "Medium armor", "Shields", "Simple weapons", "Martial weapons"],
+            DnDClass.DRUID: ["Light armor (nonmetal)", "Medium armor (nonmetal)", "Shields (nonmetal)", "Weapons: Clubs, Daggers, Darts, Javelins, Maces, Quarterstaffs, Scimitars, Sickles, Slings, Spears", "Tools: Herbalism kit"],
+            DnDClass.MONK: ["Weapons: Simple weapons, Shortswords", "Tools: Choose one artisan's tool or musical instrument"],
+            DnDClass.SORCERER: ["Weapons: Daggers, Darts, Slings, Quarterstaffs, Light crossbows"],
+            DnDClass.WARLOCK: ["Light armor", "Simple weapons"],
+        }
+
+        # Skill choices (PLAYER MUST CHOOSE - provide guidance)
+        skill_choices = {
+            DnDClass.FIGHTER: ["Choose 2 skills from: Acrobatics, Animal Handling, Athletics, History, Insight, Intimidation, Perception, Survival"],
+            DnDClass.WIZARD: ["Choose 2 skills from: Arcana, History, Insight, Investigation, Medicine, Religion"],
+            DnDClass.ROGUE: ["Choose 4 skills from: Acrobatics, Athletics, Deception, Insight, Intimidation, Investigation, Perception, Performance, Persuasion, Sleight of Hand, Stealth"],
+            DnDClass.CLERIC: ["Choose 2 skills from: History, Insight, Medicine, Persuasion, Religion"],
+            DnDClass.RANGER: ["Choose 3 skills from: Animal Handling, Athletics, Insight, Investigation, Nature, Perception, Stealth, Survival"],
+            DnDClass.PALADIN: ["Choose 2 skills from: Athletics, Insight, Intimidation, Medicine, Persuasion, Religion"],
+            DnDClass.BARD: ["Choose any 3 skills"],
+            DnDClass.BARBARIAN: ["Choose 2 skills from: Animal Handling, Athletics, Intimidation, Nature, Perception, Survival"],
+            DnDClass.DRUID: ["Choose 2 skills from: Arcana, Animal Handling, Insight, Medicine, Nature, Perception, Religion, Survival"],
+            DnDClass.MONK: ["Choose 2 skills from: Acrobatics, Athletics, History, Insight, Religion, Stealth"],
+            DnDClass.SORCERER: ["Choose 2 skills from: Arcana, Deception, Insight, Intimidation, Persuasion, Religion"],
+            DnDClass.WARLOCK: ["Choose 2 skills from: Arcana, Deception, History, Intimidation, Investigation, Nature, Religion"],
+        }
+
+        # Background provides 2 additional skills (VARIES - typical examples provided)
+        background_note = f"Background ({background}): Grants 2 additional skill proficiencies (varies by background)"
+
+        # Combine all proficiencies
+        proficiencies = []
+        proficiencies.extend(saves.get(character_class, []))
+        proficiencies.extend(armor_weapons.get(character_class, []))
+        proficiencies.extend(skill_choices.get(character_class, []))
+        proficiencies.append(background_note)
+
+        return proficiencies
+
+    def save_character(self, character: Character):
+        """Save character to database"""
+        self.database.save(
+            entity_id=character.id,
+            entity_type="character",
+            data=character.to_dict()
+        )
+
+    def load_character(self, character_id: str) -> Optional[Character]:
+        """Load character from database"""
+        data = self.database.load(character_id, "character")
+        if data:
+            return Character(**data)
+        return None
+
+    def list_characters(self) -> list[Character]:
+        """List all saved characters"""
+        characters_data = self.database.load_all("character")
+        return [Character(**data) for data in characters_data]
+
+    def delete_character(self, character_id: str):
+        """Delete character from database"""
+        self.database.delete(character_id)
+
+    def generate_portrait(
+        self,
+        character: Character,
+        style: str = "fantasy art",
+        quality: str = "standard",
+        provider: str = "auto"
+    ) -> tuple[Optional[str], Optional[str]]:
+        """
+        Generate character portrait using DALL-E 3 or HuggingFace
+
+        Args:
+            character: Character to generate portrait for
+            style: Art style (e.g., "fantasy art", "digital painting", "anime")
+            quality: Image quality ("standard" or "hd") - OpenAI only
+            provider: "openai", "huggingface", or "auto"
+
+        Returns:
+            Tuple of (file_path, status_message)
+        """
+        if not self.image_generator:
+            return None, "❌ Image generation not available (API key required)"
+
+        try:
+            file_path, image_bytes = self.image_generator.generate_character_portrait(
+                character=character,
+                style=style,
+                quality=quality,
+                provider=provider
+            )
+
+            if file_path:
+                return file_path, f"✅ Portrait generated successfully!\nSaved to: {file_path}"
+            else:
+                return None, "❌ Failed to generate portrait"
+
+        except Exception as e:
+            return None, f"❌ Error generating portrait: {str(e)}"
+
+    def get_portrait_path(self, character_id: str) -> Optional[str]:
+        """Get saved portrait path for character"""
+        if not self.image_generator:
+            return None
+
+        return self.image_generator.get_portrait_path(character_id)

src/config.py

@@ -0,0 +1,157 @@
+"""
+Configuration management for D'n'D Campaign Manager
+Handles API keys, model settings, and application config
+"""
+
+import os
+from pathlib import Path
+from typing import Optional
+from pydantic import BaseModel, Field
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+class ModelConfig(BaseModel):
+    """Configuration for AI models"""
+    # Primary model for generation
+    primary_provider: str = Field(default="anthropic", description="anthropic, openai, or google")
+    primary_model: str = Field(default="claude-3-haiku-20240307", description="Model name")
+
+    # Memory model for long context
+    memory_provider: str = Field(default="google", description="Provider for campaign memory")
+    memory_model: str = Field(default="gemini-2.0-flash-exp", description="2M token context model")
+
+    # Temperature settings
+    creative_temp: float = Field(default=0.9, description="For character/story generation")
+    balanced_temp: float = Field(default=0.7, description="For general tasks")
+    precise_temp: float = Field(default=0.3, description="For rules/stats")
+
+    # Token limits
+    max_tokens_generation: int = Field(default=2000, description="For content generation")
+    max_tokens_memory: int = Field(default=1000000, description="For memory queries")
+
+
+class DatabaseConfig(BaseModel):
+    """Database configuration"""
+    db_type: str = Field(default="sqlite", description="Database type")
+    db_path: Path = Field(default=Path("data/dnd_campaign_manager.db"), description="SQLite path")
+
+    def ensure_db_dir(self):
+        """Ensure database directory exists"""
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+
+
+class MCPConfig(BaseModel):
+    """MCP Server configuration"""
+    server_name: str = Field(default="dnd-campaign-manager", description="MCP server name")
+    server_version: str = Field(default="2.0.0", description="MCP server version")
+
+    # MCP tools to expose
+    enable_character_tools: bool = Field(default=True, description="Character creation tools")
+    enable_campaign_tools: bool = Field(default=True, description="Campaign management tools")
+    enable_npc_tools: bool = Field(default=True, description="NPC generation tools")
+    enable_loot_tools: bool = Field(default=True, description="Loot generation tools")
+    enable_encounter_tools: bool = Field(default=True, description="Encounter generation tools")
+
+    # MCP resources to expose
+    enable_character_resources: bool = Field(default=True, description="Character data resources")
+    enable_campaign_resources: bool = Field(default=True, description="Campaign data resources")
+
+
+class AppConfig(BaseModel):
+    """Application configuration"""
+    app_name: str = Field(default="D'n'D Campaign Manager", description="Application name")
+    app_version: str = Field(default="2.0.0", description="Application version")
+
+    # Gradio settings
+    gradio_share: bool = Field(default=False, description="Enable Gradio sharing")
+    gradio_server_name: str = Field(default="0.0.0.0", description="Server host")
+    gradio_server_port: int = Field(default=7860, description="Server port")
+
+    # Data persistence
+    enable_persistence: bool = Field(default=True, description="Save data to database")
+    auto_backup: bool = Field(default=True, description="Auto-backup campaigns")
+    backup_interval_hours: int = Field(default=24, description="Backup interval")
+
+    # Feature flags
+    enable_image_generation: bool = Field(default=True, description="Character portraits")
+    enable_voice_generation: bool = Field(default=False, description="NPC voices (future)")
+    enable_music_generation: bool = Field(default=False, description="Background music (future)")
+
+
+class Config:
+    """Main configuration class"""
+
+    def __init__(self):
+        # API Keys
+        self.anthropic_api_key: Optional[str] = os.getenv("ANTHROPIC_API_KEY")
+        self.openai_api_key: Optional[str] = os.getenv("OPENAI_API_KEY")
+        self.google_api_key: Optional[str] = os.getenv("GOOGLE_API_KEY")
+        self.huggingface_api_key: Optional[str] = os.getenv("HUGGINGFACE_API_KEY")
+
+        # Sub-configurations
+        self.model = ModelConfig()
+        self.database = DatabaseConfig()
+        self.mcp = MCPConfig()
+        self.app = AppConfig()
+
+        # Validate configuration
+        self._validate()
+
+    def _validate(self):
+        """Validate configuration and API keys"""
+        if not self.anthropic_api_key and self.model.primary_provider == "anthropic":
+            raise ValueError("ANTHROPIC_API_KEY not found in environment")
+
+        if not self.google_api_key and self.model.memory_provider == "google":
+            raise ValueError("GOOGLE_API_KEY not found in environment for memory model")
+
+        # Ensure database directory exists
+        self.database.ensure_db_dir()
+
+    def get_model_config(self, task_type: str = "balanced") -> dict:
+        """Get model configuration for specific task type"""
+        temp_map = {
+            "creative": self.model.creative_temp,
+            "balanced": self.model.balanced_temp,
+            "precise": self.model.precise_temp
+        }
+
+        return {
+            "model": self.model.primary_model,
+            "temperature": temp_map.get(task_type, self.model.balanced_temp),
+            "max_tokens": self.model.max_tokens_generation
+        }
+
+    def get_memory_config(self) -> dict:
+        """Get configuration for memory/context model"""
+        return {
+            "model": self.model.memory_model,
+            "temperature": self.model.balanced_temp,
+            "max_tokens": self.model.max_tokens_memory
+        }
+
+
+# Global configuration instance
+config = Config()
+
+
+# Export commonly used values
+ANTHROPIC_API_KEY = config.anthropic_api_key
+GOOGLE_API_KEY = config.google_api_key
+OPENAI_API_KEY = config.openai_api_key
+HUGGINGFACE_API_KEY = config.huggingface_api_key
+
+DB_PATH = config.database.db_path
+MCP_SERVER_NAME = config.mcp.server_name
+
+# Data directories
+DATA_DIR = Path("data")
+CAMPAIGNS_DIR = DATA_DIR / "campaigns"
+CHARACTERS_DIR = DATA_DIR / "characters"
+TEMPLATES_DIR = DATA_DIR / "templates"
+
+# Ensure directories exist
+for directory in [DATA_DIR, CAMPAIGNS_DIR, CHARACTERS_DIR, TEMPLATES_DIR]:
+    directory.mkdir(parents=True, exist_ok=True)

src/models/__init__.py

@@ -0,0 +1,23 @@
+"""
+Data models for D'n'D Campaign Manager
+"""
+
+from .character import Character, CharacterStats, CharacterBackground
+from .campaign import Campaign, CampaignEvent, CampaignMemory
+from .npc import NPC, NPCPersonality, NPCRelationship
+from .game_objects import Item, Encounter, Location
+
+__all__ = [
+    "Character",
+    "CharacterStats",
+    "CharacterBackground",
+    "Campaign",
+    "CampaignEvent",
+    "CampaignMemory",
+    "NPC",
+    "NPCPersonality",
+    "NPCRelationship",
+    "Item",
+    "Encounter",
+    "Location",
+]

src/models/campaign.py

@@ -0,0 +1,275 @@
+"""
+Campaign and session management data models
+"""
+
+from datetime import datetime
+from typing import Optional, List, Dict, Any
+from enum import Enum
+from pydantic import BaseModel, Field
+
+
+class CampaignTheme(str, Enum):
+    """Campaign themes"""
+    HIGH_FANTASY = "High Fantasy"
+    DARK_FANTASY = "Dark Fantasy"
+    URBAN_FANTASY = "Urban Fantasy"
+    POLITICAL_INTRIGUE = "Political Intrigue"
+    HORROR = "Horror"
+    EXPLORATION = "Exploration"
+    DUNGEON_CRAWL = "Dungeon Crawl"
+    CUSTOM = "Custom"
+
+
+class EventType(str, Enum):
+    """Types of campaign events"""
+    COMBAT = "Combat"
+    SOCIAL = "Social"
+    EXPLORATION = "Exploration"
+    DISCOVERY = "Discovery"
+    PLOT_DEVELOPMENT = "Plot Development"
+    CHARACTER_MOMENT = "Character Moment"
+    NPC_INTERACTION = "NPC Interaction"
+    QUEST_UPDATE = "Quest Update"
+
+
+class CampaignEvent(BaseModel):
+    """Individual campaign event/memory"""
+    id: Optional[str] = Field(default=None, description="Event ID")
+    campaign_id: str = Field(description="Campaign this event belongs to")
+    session_number: int = Field(ge=1, description="Session number")
+
+    event_type: EventType = Field(description="Type of event")
+    title: str = Field(min_length=1, max_length=200, description="Event title")
+    description: str = Field(description="Full event description")
+
+    # Participants
+    characters_involved: List[str] = Field(default_factory=list, description="Character IDs")
+    npcs_involved: List[str] = Field(default_factory=list, description="NPC IDs")
+    locations: List[str] = Field(default_factory=list, description="Location names")
+
+    # Context
+    consequences: List[str] = Field(default_factory=list, description="Event consequences")
+    items_gained: List[str] = Field(default_factory=list, description="Items acquired")
+    items_lost: List[str] = Field(default_factory=list, description="Items lost")
+    experience_awarded: int = Field(ge=0, default=0, description="XP awarded")
+
+    # Metadata
+    timestamp: datetime = Field(default_factory=datetime.now)
+    importance: int = Field(ge=1, le=5, default=3, description="Event importance (1-5)")
+    tags: List[str] = Field(default_factory=list, description="Event tags")
+
+    # GM notes
+    gm_notes: str = Field(default="", description="Private GM notes")
+    player_visible: bool = Field(default=True, description="Visible to players")
+
+    def to_markdown(self) -> str:
+        """Convert to markdown"""
+        return f"""## {self.title}
+**Type:** {self.event_type.value} | **Importance:** {'⭐' * self.importance}
+**Session:** {self.session_number} | **Date:** {self.timestamp.strftime('%Y-%m-%d')}
+
+{self.description}
+
+**Participants:** {', '.join(self.characters_involved)}
+**NPCs:** {', '.join(self.npcs_involved)}
+**Locations:** {', '.join(self.locations)}
+
+**Consequences:**
+{chr(10).join(f"- {c}" for c in self.consequences)}
+"""
+
+
+class CampaignMemory(BaseModel):
+    """Searchable campaign memory/context"""
+    campaign_id: str = Field(description="Campaign ID")
+
+    # Full context for AI
+    full_context: str = Field(default="", description="Complete campaign context")
+
+    # Key information
+    major_npcs: Dict[str, str] = Field(default_factory=dict, description="NPC name -> description")
+    key_locations: Dict[str, str] = Field(default_factory=dict, description="Location -> description")
+    active_quests: List[str] = Field(default_factory=list, description="Current quests")
+    completed_quests: List[str] = Field(default_factory=list, description="Finished quests")
+
+    # Story beats
+    important_events: List[str] = Field(default_factory=list, description="Key story moments")
+    unresolved_threads: List[str] = Field(default_factory=list, description="Plot threads")
+    secrets_discovered: List[str] = Field(default_factory=list, description="Revealed secrets")
+    secrets_hidden: List[str] = Field(default_factory=list, description="Hidden secrets")
+
+    # Relationships
+    faction_standings: Dict[str, int] = Field(default_factory=dict, description="Faction name -> standing (-100 to 100)")
+    npc_relationships: Dict[str, str] = Field(default_factory=dict, description="NPC -> relationship status")
+
+    # Metadata
+    last_updated: datetime = Field(default_factory=datetime.now)
+    total_events: int = Field(ge=0, default=0)
+
+    def add_event_to_memory(self, event: CampaignEvent):
+        """Update memory with new event"""
+        self.total_events += 1
+
+        # Add NPCs
+        for npc in event.npcs_involved:
+            if npc not in self.major_npcs:
+                self.major_npcs[npc] = "Recently introduced"
+
+        # Add locations
+        for location in event.locations:
+            if location not in self.key_locations:
+                self.key_locations[location] = "Visited"
+
+        # Add to important events if high importance
+        if event.importance >= 4:
+            self.important_events.append(event.title)
+
+        self.last_updated = datetime.now()
+
+
+class Campaign(BaseModel):
+    """Complete D&D campaign"""
+    # Core identity
+    id: Optional[str] = Field(default=None, description="Campaign ID")
+    name: str = Field(min_length=1, max_length=100, description="Campaign name")
+    theme: CampaignTheme = Field(description="Campaign theme")
+
+    # Setting
+    setting: str = Field(description="Campaign setting description")
+    world_name: str = Field(default="", description="World/realm name")
+    starting_location: str = Field(default="", description="Starting location")
+
+    # Campaign info
+    summary: str = Field(description="Campaign summary/hook")
+    current_arc: str = Field(default="", description="Current story arc")
+    level_range: str = Field(default="1-5", description="Expected level range")
+
+    # Story elements
+    main_conflict: str = Field(description="Central conflict")
+    key_factions: List[str] = Field(default_factory=list, description="Important factions")
+    major_villains: List[str] = Field(default_factory=list, description="Main antagonists")
+    central_mysteries: List[str] = Field(default_factory=list, description="Ongoing mysteries")
+
+    # Characters
+    character_ids: List[str] = Field(default_factory=list, description="Player character IDs")
+    party_size: int = Field(ge=1, le=10, default=4, description="Expected party size")
+
+    # Session tracking
+    current_session: int = Field(ge=1, default=1, description="Current session number")
+    total_sessions: int = Field(ge=0, default=0, description="Total sessions played")
+
+    # Memory
+    memory: CampaignMemory = Field(default=None, description="Campaign memory")
+
+    # Metadata
+    game_master: str = Field(default="", description="GM name")
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)
+    last_session_date: Optional[datetime] = Field(default=None)
+
+    # Settings
+    is_active: bool = Field(default=True, description="Campaign active?")
+    homebrew_rules: List[str] = Field(default_factory=list, description="Custom rules")
+    notes: str = Field(default="", description="GM notes")
+
+    def __init__(self, **data):
+        super().__init__(**data)
+        if self.memory is None:
+            self.memory = CampaignMemory(campaign_id=self.id or "")
+
+    def add_character(self, character_id: str):
+        """Add character to campaign"""
+        if character_id not in self.character_ids:
+            self.character_ids.append(character_id)
+            self.updated_at = datetime.now()
+
+    def remove_character(self, character_id: str):
+        """Remove character from campaign"""
+        if character_id in self.character_ids:
+            self.character_ids.remove(character_id)
+            self.updated_at = datetime.now()
+
+    def start_new_session(self):
+        """Start a new session"""
+        self.current_session += 1
+        self.total_sessions += 1
+        self.last_session_date = datetime.now()
+        self.updated_at = datetime.now()
+
+    def add_event(self, event: CampaignEvent):
+        """Add event to campaign memory"""
+        self.memory.add_event_to_memory(event)
+        self.updated_at = datetime.now()
+
+    def to_context_string(self) -> str:
+        """Generate context string for AI"""
+        return f"""Campaign: {self.name}
+Theme: {self.theme.value}
+Setting: {self.setting}
+
+Main Conflict: {self.main_conflict}
+
+Current Arc: {self.current_arc}
+Session: {self.current_session}
+
+Key Factions: {', '.join(self.key_factions)}
+Major Villains: {', '.join(self.major_villains)}
+
+Active Quests: {', '.join(self.memory.active_quests)}
+Important Events: {', '.join(self.memory.important_events[-5:])}  # Last 5 events
+
+Party Size: {self.party_size}
+Level Range: {self.level_range}
+"""
+
+    def to_markdown(self) -> str:
+        """Generate markdown campaign summary"""
+        return f"""# {self.name}
+**{self.theme.value} Campaign**
+
+## Setting
+{self.setting}
+
+**World:** {self.world_name}
+**Starting Location:** {self.starting_location}
+
+## Campaign Summary
+{self.summary}
+
+## Main Conflict
+{self.main_conflict}
+
+## Current Story Arc
+{self.current_arc}
+
+## Key Elements
+**Factions:** {', '.join(self.key_factions)}
+**Villains:** {', '.join(self.major_villains)}
+**Mysteries:** {', '.join(self.central_mysteries)}
+
+## Party Information
+**Party Size:** {self.party_size}
+**Level Range:** {self.level_range}
+**Current Session:** {self.current_session}
+**Total Sessions:** {self.total_sessions}
+
+## Campaign Status
+**Active:** {'Yes' if self.is_active else 'No'}
+**Last Session:** {self.last_session_date.strftime('%Y-%m-%d') if self.last_session_date else 'Not started'}
+
+## GM Notes
+{self.notes}
+"""
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "name": "The Shattered Crown",
+                "theme": "High Fantasy",
+                "setting": "A kingdom torn by civil war",
+                "summary": "Adventurers must unite the realm",
+                "main_conflict": "Succession crisis threatens the kingdom",
+                "party_size": 4,
+                "level_range": "1-10"
+            }
+        }

src/models/character.py

@@ -0,0 +1,285 @@
+"""
+Character data models for D&D 5e characters
+"""
+
+from datetime import datetime
+from typing import Optional, List, Dict, Any
+from enum import Enum
+from pydantic import BaseModel, Field, validator
+
+
+class DnDRace(str, Enum):
+    """D&D 5e races"""
+    HUMAN = "Human"
+    ELF = "Elf"
+    DWARF = "Dwarf"
+    HALFLING = "Halfling"
+    DRAGONBORN = "Dragonborn"
+    GNOME = "Gnome"
+    HALF_ELF = "Half-Elf"
+    HALF_ORC = "Half-Orc"
+    TIEFLING = "Tiefling"
+    DROW = "Drow"
+
+
+class DnDClass(str, Enum):
+    """D&D 5e classes"""
+    BARBARIAN = "Barbarian"
+    BARD = "Bard"
+    CLERIC = "Cleric"
+    DRUID = "Druid"
+    FIGHTER = "Fighter"
+    MONK = "Monk"
+    PALADIN = "Paladin"
+    RANGER = "Ranger"
+    ROGUE = "Rogue"
+    SORCERER = "Sorcerer"
+    WARLOCK = "Warlock"
+    WIZARD = "Wizard"
+
+
+class Alignment(str, Enum):
+    """D&D alignments"""
+    LAWFUL_GOOD = "Lawful Good"
+    NEUTRAL_GOOD = "Neutral Good"
+    CHAOTIC_GOOD = "Chaotic Good"
+    LAWFUL_NEUTRAL = "Lawful Neutral"
+    TRUE_NEUTRAL = "True Neutral"
+    CHAOTIC_NEUTRAL = "Chaotic Neutral"
+    LAWFUL_EVIL = "Lawful Evil"
+    NEUTRAL_EVIL = "Neutral Evil"
+    CHAOTIC_EVIL = "Chaotic Evil"
+
+
+# D&D 5e Hit Dice by Class (shared constant to avoid duplication)
+HIT_DICE_BY_CLASS = {
+    DnDClass.BARBARIAN: 12,
+    DnDClass.FIGHTER: 10,
+    DnDClass.PALADIN: 10,
+    DnDClass.RANGER: 10,
+    DnDClass.BARD: 8,
+    DnDClass.CLERIC: 8,
+    DnDClass.DRUID: 8,
+    DnDClass.MONK: 8,
+    DnDClass.ROGUE: 8,
+    DnDClass.WARLOCK: 8,
+    DnDClass.SORCERER: 6,
+    DnDClass.WIZARD: 6,
+}
+
+
+class CharacterStats(BaseModel):
+    """D&D 5e ability scores and derived stats"""
+    strength: int = Field(ge=1, le=20, default=10, description="Strength score (1-20 per D&D 5e standard rules)")
+    dexterity: int = Field(ge=1, le=20, default=10, description="Dexterity score (1-20 per D&D 5e standard rules)")
+    constitution: int = Field(ge=1, le=20, default=10, description="Constitution score (1-20 per D&D 5e standard rules)")
+    intelligence: int = Field(ge=1, le=20, default=10, description="Intelligence score (1-20 per D&D 5e standard rules)")
+    wisdom: int = Field(ge=1, le=20, default=10, description="Wisdom score (1-20 per D&D 5e standard rules)")
+    charisma: int = Field(ge=1, le=20, default=10, description="Charisma score (1-20 per D&D 5e standard rules)")
+
+    @property
+    def strength_modifier(self) -> int:
+        """Calculate strength modifier"""
+        return (self.strength - 10) // 2
+
+    @property
+    def dexterity_modifier(self) -> int:
+        """Calculate dexterity modifier"""
+        return (self.dexterity - 10) // 2
+
+    @property
+    def constitution_modifier(self) -> int:
+        """Calculate constitution modifier"""
+        return (self.constitution - 10) // 2
+
+    @property
+    def intelligence_modifier(self) -> int:
+        """Calculate intelligence modifier"""
+        return (self.intelligence - 10) // 2
+
+    @property
+    def wisdom_modifier(self) -> int:
+        """Calculate wisdom modifier"""
+        return (self.wisdom - 10) // 2
+
+    @property
+    def charisma_modifier(self) -> int:
+        """Calculate charisma modifier"""
+        return (self.charisma - 10) // 2
+
+    def get_all_modifiers(self) -> Dict[str, int]:
+        """Get all ability modifiers"""
+        return {
+            "strength": self.strength_modifier,
+            "dexterity": self.dexterity_modifier,
+            "constitution": self.constitution_modifier,
+            "intelligence": self.intelligence_modifier,
+            "wisdom": self.wisdom_modifier,
+            "charisma": self.charisma_modifier,
+        }
+
+
+class CharacterBackground(BaseModel):
+    """Character background and personality"""
+    background_type: str = Field(default="Adventurer", description="Background archetype")
+    personality_traits: List[str] = Field(default_factory=list, description="2-3 personality traits")
+    ideals: str = Field(default="", description="Character's ideals")
+    bonds: str = Field(default="", description="Character's bonds")
+    flaws: str = Field(default="", description="Character's flaws")
+    backstory: str = Field(default="", description="Full backstory")
+    goals: List[str] = Field(default_factory=list, description="Character goals")
+
+
+class Character(BaseModel):
+    """Complete D&D 5e character"""
+    # Core identity
+    id: Optional[str] = Field(default=None, description="Unique character ID")
+    name: str = Field(min_length=1, max_length=100, description="Character name")
+    race: DnDRace = Field(description="Character race")
+    character_class: DnDClass = Field(description="Character class")
+    level: int = Field(ge=1, le=20, default=1, description="Character level")
+    alignment: Alignment = Field(default=Alignment.TRUE_NEUTRAL)
+    gender: Optional[str] = Field(default=None, description="Character gender")
+    skin_tone: Optional[str] = Field(default=None, description="Character skin tone/color")
+
+    # Stats
+    stats: CharacterStats = Field(default_factory=CharacterStats)
+    max_hit_points: int = Field(ge=1, default=10)
+    current_hit_points: int = Field(ge=0, default=10)
+    armor_class: int = Field(ge=1, default=10)
+    proficiency_bonus: int = Field(ge=2, default=2)
+
+    # Background & personality
+    background: CharacterBackground = Field(default_factory=CharacterBackground)
+
+    # Equipment & abilities
+    equipment: List[str] = Field(default_factory=list, description="Equipment list")
+    spells: List[str] = Field(default_factory=list, description="Known spells")
+    features: List[str] = Field(default_factory=list, description="Class features")
+    proficiencies: List[str] = Field(default_factory=list, description="Skill proficiencies")
+
+    # Portrait
+    portrait_url: Optional[str] = Field(default=None, description="Character portrait URL")
+    portrait_prompt: Optional[str] = Field(default=None, description="Prompt used for portrait")
+
+    # Metadata
+    campaign_id: Optional[str] = Field(default=None, description="Associated campaign")
+    player_name: Optional[str] = Field(default=None, description="Player's name")
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)
+
+    # Additional data
+    notes: str = Field(default="", description="GM/player notes")
+    experience_points: int = Field(ge=0, default=0)
+
+    @validator("proficiency_bonus", always=True)
+    def calculate_proficiency_bonus(cls, v, values):
+        """Calculate proficiency bonus based on level"""
+        level = values.get("level", 1)
+        return 2 + ((level - 1) // 4)
+
+    @validator("current_hit_points", always=True)
+    def validate_hp(cls, v, values):
+        """Ensure current HP doesn't exceed max HP"""
+        max_hp = values.get("max_hit_points", 10)
+        return min(v, max_hp)
+
+    def calculate_max_hp(self) -> int:
+        """Calculate max HP based on class and level (D&D 5e rules)"""
+        hit_die = HIT_DICE_BY_CLASS.get(self.character_class, 8)
+        con_mod = self.stats.constitution_modifier
+
+        # First level: max hit die + con mod (minimum 1)
+        first_level_hp = max(1, hit_die + con_mod)
+
+        # Subsequent levels: average (rounded up) + con mod (minimum 1 per level per D&D 5e)
+        hp_per_level = max(1, (hit_die // 2) + 1 + con_mod)
+        subsequent_hp = hp_per_level * (self.level - 1)
+
+        return first_level_hp + subsequent_hp
+
+    def take_damage(self, damage: int) -> int:
+        """Apply damage to character"""
+        self.current_hit_points = max(0, self.current_hit_points - damage)
+        self.updated_at = datetime.now()
+        return self.current_hit_points
+
+    def heal(self, healing: int) -> int:
+        """Heal character"""
+        self.current_hit_points = min(self.max_hit_points, self.current_hit_points + healing)
+        self.updated_at = datetime.now()
+        return self.current_hit_points
+
+    def level_up(self):
+        """Level up the character (D&D 5e rules)"""
+        if self.level < 20:
+            self.level += 1
+            # Recalculate proficiency bonus based on new level
+            self.proficiency_bonus = 2 + ((self.level - 1) // 4)
+            self.max_hit_points = self.calculate_max_hp()
+            self.current_hit_points = self.max_hit_points
+            self.updated_at = datetime.now()
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary"""
+        return self.model_dump()
+
+    def to_markdown(self) -> str:
+        """Generate markdown character sheet"""
+        return f"""# {self.name}
+**Level {self.level} {self.race.value} {self.character_class.value}**
+*{self.alignment.value}*
+
+## Ability Scores
+- **STR:** {self.stats.strength} ({self.stats.strength_modifier:+d})
+- **DEX:** {self.stats.dexterity} ({self.stats.dexterity_modifier:+d})
+- **CON:** {self.stats.constitution} ({self.stats.constitution_modifier:+d})
+- **INT:** {self.stats.intelligence} ({self.stats.intelligence_modifier:+d})
+- **WIS:** {self.stats.wisdom} ({self.stats.wisdom_modifier:+d})
+- **CHA:** {self.stats.charisma} ({self.stats.charisma_modifier:+d})
+
+## Combat Stats
+- **HP:** {self.current_hit_points}/{self.max_hit_points}
+- **AC:** {self.armor_class}
+- **Proficiency:** +{self.proficiency_bonus}
+
+## Background
+**{self.background.background_type}**
+
+{self.background.backstory}
+
+## Personality
+**Traits:** {', '.join(self.background.personality_traits)}
+**Ideals:** {self.background.ideals}
+**Bonds:** {self.background.bonds}
+**Flaws:** {self.background.flaws}
+
+## Equipment
+{chr(10).join(f"- {item}" for item in self.equipment)}
+
+## Notes
+{self.notes}
+"""
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "name": "Thorin Ironforge",
+                "race": "Dwarf",
+                "character_class": "Fighter",
+                "level": 3,
+                "alignment": "Lawful Good",
+                "stats": {
+                    "strength": 16,
+                    "dexterity": 12,
+                    "constitution": 15,
+                    "intelligence": 10,
+                    "wisdom": 13,
+                    "charisma": 8
+                },
+                "background": {
+                    "background_type": "Soldier",
+                    "backstory": "A veteran warrior seeking redemption."
+                }
+            }
+        }

src/models/game_objects.py

@@ -0,0 +1,195 @@
+"""
+Game objects: Items, Encounters, Locations
+"""
+
+from datetime import datetime
+from typing import Optional, List, Dict, Any
+from enum import Enum
+from pydantic import BaseModel, Field
+
+
+# ==================== ITEMS ====================
+
+class ItemRarity(str, Enum):
+    """D&D item rarity"""
+    COMMON = "Common"
+    UNCOMMON = "Uncommon"
+    RARE = "Rare"
+    VERY_RARE = "Very Rare"
+    LEGENDARY = "Legendary"
+    ARTIFACT = "Artifact"
+
+
+class ItemType(str, Enum):
+    """Item categories"""
+    WEAPON = "Weapon"
+    ARMOR = "Armor"
+    POTION = "Potion"
+    SCROLL = "Scroll"
+    WAND = "Wand"
+    RING = "Ring"
+    WONDROUS = "Wondrous Item"
+    TOOL = "Tool"
+    TREASURE = "Treasure"
+    CONSUMABLE = "Consumable"
+
+
+class Item(BaseModel):
+    """Magic items and equipment"""
+    id: Optional[str] = Field(default=None)
+    name: str = Field(min_length=1, max_length=100)
+    item_type: ItemType
+    rarity: ItemRarity = Field(default=ItemRarity.COMMON)
+
+    description: str = Field(description="Item description")
+    properties: List[str] = Field(default_factory=list, description="Magical properties")
+
+    requires_attunement: bool = Field(default=False)
+    attunement_requirements: Optional[str] = Field(default=None)
+
+    value_gp: int = Field(ge=0, default=0, description="Value in gold pieces")
+    weight_lbs: float = Field(ge=0, default=0, description="Weight in pounds")
+
+    charges: Optional[int] = Field(default=None, description="Current charges")
+    max_charges: Optional[int] = Field(default=None, description="Maximum charges")
+
+    flavor_text: str = Field(default="", description="Flavor/lore text")
+    history: str = Field(default="", description="Item history")
+
+    campaign_id: Optional[str] = Field(default=None)
+    owner_id: Optional[str] = Field(default=None, description="Current owner")
+
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+# ==================== ENCOUNTERS ====================
+
+class EncounterDifficulty(str, Enum):
+    """Encounter difficulty"""
+    EASY = "Easy"
+    MEDIUM = "Medium"
+    HARD = "Hard"
+    DEADLY = "Deadly"
+
+
+class EncounterType(str, Enum):
+    """Type of encounter"""
+    COMBAT = "Combat"
+    SOCIAL = "Social"
+    EXPLORATION = "Exploration"
+    PUZZLE = "Puzzle"
+    TRAP = "Trap"
+    MIXED = "Mixed"
+
+
+class Encounter(BaseModel):
+    """Combat/challenge encounter"""
+    id: Optional[str] = Field(default=None)
+    name: str = Field(min_length=1, max_length=100)
+    encounter_type: EncounterType
+    difficulty: EncounterDifficulty
+
+    party_level: int = Field(ge=1, le=20, description="Expected party level")
+    party_size: int = Field(ge=1, le=10, default=4, description="Expected party size")
+
+    description: str = Field(description="Encounter description")
+    setup: str = Field(default="", description="How to set up the encounter")
+
+    # Combat specific
+    enemies: List[Dict[str, Any]] = Field(default_factory=list, description="Enemy creatures")
+    enemy_tactics: str = Field(default="", description="How enemies fight")
+
+    # Environment
+    location: str = Field(default="", description="Where encounter takes place")
+    terrain_features: List[str] = Field(default_factory=list, description="Terrain elements")
+    environmental_effects: List[str] = Field(default_factory=list, description="Environmental hazards/effects")
+
+    # Rewards
+    experience_reward: int = Field(ge=0, default=0)
+    treasure: List[str] = Field(default_factory=list, description="Treasure rewards")
+
+    # Alternatives
+    alternative_solutions: List[str] = Field(default_factory=list, description="Non-combat solutions")
+    scaling_suggestions: str = Field(default="", description="How to scale difficulty")
+
+    # Metadata
+    campaign_id: Optional[str] = Field(default=None)
+    session_number: Optional[int] = Field(default=None)
+    completed: bool = Field(default=False)
+
+    notes: str = Field(default="", description="GM notes")
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+# ==================== LOCATIONS ====================
+
+class LocationType(str, Enum):
+    """Location categories"""
+    CITY = "City"
+    TOWN = "Town"
+    VILLAGE = "Village"
+    DUNGEON = "Dungeon"
+    WILDERNESS = "Wilderness"
+    CASTLE = "Castle"
+    TEMPLE = "Temple"
+    TAVERN = "Tavern"
+    SHOP = "Shop"
+    RUINS = "Ruins"
+    CAVE = "Cave"
+    FOREST = "Forest"
+    MOUNTAIN = "Mountain"
+    COAST = "Coast"
+    PLANE = "Plane"
+
+
+class Location(BaseModel):
+    """Places in the campaign world"""
+    id: Optional[str] = Field(default=None)
+    name: str = Field(min_length=1, max_length=100)
+    location_type: LocationType
+
+    description: str = Field(description="Location description")
+    atmosphere: str = Field(default="", description="Mood/feeling of the place")
+
+    # Geography
+    region: Optional[str] = Field(default=None, description="Larger region")
+    parent_location: Optional[str] = Field(default=None, description="Contains this location")
+    sub_locations: List[str] = Field(default_factory=list, description="Locations within this one")
+
+    # Details
+    population: Optional[int] = Field(default=None)
+    government: Optional[str] = Field(default=None)
+    notable_features: List[str] = Field(default_factory=list)
+    points_of_interest: List[str] = Field(default_factory=list)
+
+    # NPCs & Factions
+    notable_npcs: List[str] = Field(default_factory=list, description="NPC IDs")
+    controlling_faction: Optional[str] = Field(default=None)
+
+    # Resources
+    available_services: List[str] = Field(default_factory=list, description="Services available")
+    shops: List[str] = Field(default_factory=list, description="Shops/merchants")
+
+    # Secrets & hooks
+    secrets: List[str] = Field(default_factory=list, description="Hidden information")
+    rumors: List[str] = Field(default_factory=list, description="Local rumors")
+    plot_hooks: List[str] = Field(default_factory=list, description="Adventure hooks")
+
+    # Map
+    map_description: str = Field(default="", description="Layout/map description")
+    connected_locations: List[str] = Field(default_factory=list, description="Connected locations")
+    travel_times: Dict[str, str] = Field(default_factory=dict, description="Travel times to other locations")
+
+    # Metadata
+    campaign_id: Optional[str] = Field(default=None)
+    visited: bool = Field(default=False)
+    first_visit_session: Optional[int] = Field(default=None)
+
+    notes: str = Field(default="", description="GM notes")
+    created_at: datetime = Field(default_factory=datetime.now)
+
+    def mark_visited(self, session_number: int):
+        """Mark location as visited"""
+        if not self.visited:
+            self.visited = True
+            self.first_visit_session = session_number

src/models/npc.py

@@ -0,0 +1,246 @@
+"""
+NPC (Non-Player Character) data models
+"""
+
+from datetime import datetime
+from typing import Optional, List, Dict
+from enum import Enum
+from pydantic import BaseModel, Field
+
+
+class NPCRole(str, Enum):
+    """NPC roles in the story"""
+    QUEST_GIVER = "Quest Giver"
+    MERCHANT = "Merchant"
+    ALLY = "Ally"
+    RIVAL = "Rival"
+    VILLAIN = "Villain"
+    MENTOR = "Mentor"
+    INFORMANT = "Informant"
+    GUARD = "Guard"
+    NOBLE = "Noble"
+    COMMONER = "Commoner"
+    MONSTER = "Monster"
+    COMPANION = "Companion"
+
+
+class NPCDisposition(str, Enum):
+    """NPC attitude toward party"""
+    HOSTILE = "Hostile"
+    UNFRIENDLY = "Unfriendly"
+    NEUTRAL = "Neutral"
+    FRIENDLY = "Friendly"
+    HELPFUL = "Helpful"
+
+
+class NPCPersonality(BaseModel):
+    """NPC personality traits"""
+    traits: List[str] = Field(default_factory=list, description="2-3 personality traits")
+    mannerisms: List[str] = Field(default_factory=list, description="Physical mannerisms")
+    voice_description: str = Field(default="", description="How they sound")
+    motivations: List[str] = Field(default_factory=list, description="What drives them")
+    fears: List[str] = Field(default_factory=list, description="What they fear")
+    secrets: List[str] = Field(default_factory=list, description="Hidden secrets")
+
+
+class NPCRelationship(BaseModel):
+    """Relationship between NPC and character/party"""
+    character_id: str = Field(description="Character or 'party' for group")
+    relationship_type: str = Field(description="Type of relationship")
+    affinity: int = Field(ge=-100, le=100, default=0, description="Relationship strength")
+    history: str = Field(default="", description="Shared history")
+    notes: str = Field(default="", description="Relationship notes")
+
+
+class NPC(BaseModel):
+    """Non-player character"""
+    # Core identity
+    id: Optional[str] = Field(default=None, description="NPC ID")
+    name: str = Field(min_length=1, max_length=100, description="NPC name")
+    title: Optional[str] = Field(default=None, description="Title/honorific")
+
+    # Basic info
+    race: str = Field(description="NPC race/species")
+    age: Optional[str] = Field(default=None, description="Age or age category")
+    gender: Optional[str] = Field(default=None, description="Gender")
+    occupation: str = Field(description="Occupation/profession")
+
+    # Role in campaign
+    role: NPCRole = Field(description="Story role")
+    disposition: NPCDisposition = Field(default=NPCDisposition.NEUTRAL)
+    importance: int = Field(ge=1, le=5, default=3, description="Story importance (1-5)")
+
+    # Description
+    appearance: str = Field(description="Physical description")
+    personality: NPCPersonality = Field(default_factory=NPCPersonality)
+
+    # Game stats (optional)
+    challenge_rating: Optional[float] = Field(default=None, description="CR if combatant")
+    armor_class: Optional[int] = Field(default=None)
+    hit_points: Optional[int] = Field(default=None)
+
+    # Story elements
+    backstory: str = Field(default="", description="NPC backstory")
+    current_situation: str = Field(default="", description="Current circumstances")
+    goals: List[str] = Field(default_factory=list, description="NPC goals")
+    connections: List[str] = Field(default_factory=list, description="Connected NPCs/factions")
+
+    # Relationships
+    relationships: List[NPCRelationship] = Field(default_factory=list)
+
+    # Location & availability
+    location: Optional[str] = Field(default=None, description="Current location")
+    availability: str = Field(default="Available", description="When/where to find them")
+
+    # Dialogue
+    greeting: Optional[str] = Field(default=None, description="Standard greeting")
+    catchphrase: Optional[str] = Field(default=None, description="Memorable phrase")
+    dialogue_samples: List[str] = Field(default_factory=list, description="Sample dialogue")
+
+    # Items & abilities
+    notable_items: List[str] = Field(default_factory=list, description="Important items")
+    special_abilities: List[str] = Field(default_factory=list, description="Special abilities")
+
+    # Metadata
+    campaign_id: Optional[str] = Field(default=None, description="Associated campaign")
+    first_appearance: Optional[int] = Field(default=None, description="Session first appeared")
+    last_appearance: Optional[int] = Field(default=None, description="Session last appeared")
+    is_alive: bool = Field(default=True, description="Living status")
+
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)
+
+    # GM notes
+    gm_notes: str = Field(default="", description="Private GM notes")
+    plot_hooks: List[str] = Field(default_factory=list, description="Plot hooks involving this NPC")
+
+    def add_relationship(self, character_id: str, relationship_type: str, affinity: int = 0):
+        """Add or update relationship"""
+        for rel in self.relationships:
+            if rel.character_id == character_id:
+                rel.relationship_type = relationship_type
+                rel.affinity = affinity
+                self.updated_at = datetime.now()
+                return
+
+        # Create new relationship
+        new_rel = NPCRelationship(
+            character_id=character_id,
+            relationship_type=relationship_type,
+            affinity=affinity
+        )
+        self.relationships.append(new_rel)
+        self.updated_at = datetime.now()
+
+    def change_disposition(self, new_disposition: NPCDisposition):
+        """Change NPC disposition"""
+        self.disposition = new_disposition
+        self.updated_at = datetime.now()
+
+    def update_location(self, location: str):
+        """Update NPC location"""
+        self.location = location
+        self.updated_at = datetime.now()
+
+    def record_appearance(self, session_number: int):
+        """Record NPC appearance in session"""
+        if self.first_appearance is None:
+            self.first_appearance = session_number
+        self.last_appearance = session_number
+        self.updated_at = datetime.now()
+
+    def get_relationship_with(self, character_id: str) -> Optional[NPCRelationship]:
+        """Get relationship with specific character"""
+        for rel in self.relationships:
+            if rel.character_id == character_id:
+                return rel
+        return None
+
+    def to_roleplay_prompt(self) -> str:
+        """Generate prompt for AI to roleplay this NPC"""
+        return f"""You are roleplaying as {self.name}, a {self.race} {self.occupation}.
+
+APPEARANCE: {self.appearance}
+
+PERSONALITY:
+- Traits: {', '.join(self.personality.traits)}
+- Mannerisms: {', '.join(self.personality.mannerisms)}
+- Voice: {self.personality.voice_description}
+
+BACKGROUND: {self.backstory}
+
+CURRENT SITUATION: {self.current_situation}
+
+MOTIVATIONS: {', '.join(self.personality.motivations)}
+
+DISPOSITION: {self.disposition.value}
+
+TYPICAL GREETING: {self.greeting or 'Generic greeting'}
+
+Roleplay this character authentically, staying in character and reflecting their personality, motivations, and current circumstances.
+"""
+
+    def to_markdown(self) -> str:
+        """Generate markdown NPC sheet"""
+        return f"""# {self.name}
+{f'*{self.title}*' if self.title else ''}
+
+**{self.race} {self.occupation}** | **{self.role.value}**
+**Disposition:** {self.disposition.value} | **Importance:** {'⭐' * self.importance}
+
+## Appearance
+{self.appearance}
+
+## Personality
+**Traits:** {', '.join(self.personality.traits)}
+**Mannerisms:** {', '.join(self.personality.mannerisms)}
+**Voice:** {self.personality.voice_description}
+
+**Motivations:** {', '.join(self.personality.motivations)}
+**Fears:** {', '.join(self.personality.fears)}
+
+## Background
+{self.backstory}
+
+## Current Situation
+{self.current_situation}
+
+## Goals
+{chr(10).join(f"- {goal}" for goal in self.goals)}
+
+## Location & Availability
+**Location:** {self.location or 'Unknown'}
+**Availability:** {self.availability}
+
+## Connections
+{', '.join(self.connections)}
+
+## Dialogue
+**Greeting:** "{self.greeting or 'Hello there.'}"
+**Catchphrase:** "{self.catchphrase or 'N/A'}"
+
+## Combat Stats
+{f"**CR:** {self.challenge_rating} | **AC:** {self.armor_class} | **HP:** {self.hit_points}" if self.challenge_rating else "*Not a combatant*"}
+
+## Plot Hooks
+{chr(10).join(f"- {hook}" for hook in self.plot_hooks)}
+
+## GM Notes
+{self.gm_notes}
+"""
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "name": "Elara Moonwhisper",
+                "race": "Elf",
+                "occupation": "Sage",
+                "role": "Quest Giver",
+                "disposition": "Friendly",
+                "appearance": "Ancient elf with silver hair and piercing blue eyes",
+                "personality": {
+                    "traits": ["Wise", "Mysterious", "Patient"],
+                    "voice_description": "Soft and melodic"
+                }
+            }
+        }

src/models/session_notes.py

@@ -0,0 +1,31 @@
+"""
+Session Notes Model for D&D Campaign Manager
+"""
+from pydantic import BaseModel, Field
+from datetime import datetime
+from typing import Optional
+
+
+class SessionNotes(BaseModel):
+    """Model for campaign session notes"""
+
+    id: str = Field(..., description="Unique identifier for session notes")
+    campaign_id: str = Field(..., description="Campaign this session belongs to")
+    session_number: int = Field(..., description="Session number")
+    notes: str = Field(..., description="Freeform session notes content")
+    uploaded_at: datetime = Field(default_factory=datetime.now, description="When notes were uploaded")
+    file_name: Optional[str] = Field(None, description="Original filename if uploaded from file")
+    file_type: Optional[str] = Field(None, description="File extension (.txt, .md, .docx, .pdf)")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "id": "the-forgotten-forge-session-3",
+                "campaign_id": "the-forgotten-forge",
+                "session_number": 3,
+                "notes": "Session 3 - The Lost Temple\n\nThe party arrived at the temple ruins...",
+                "uploaded_at": "2024-01-15T20:30:00",
+                "file_name": "session_3_notes.txt",
+                "file_type": ".txt"
+            }
+        }

src/ui/__init__.py

@@ -0,0 +1,29 @@
+"""
+UI modules for D'n'D Campaign Manager
+
+This package now uses a modular architecture with the following structure:
+- app.py: Main application orchestrator
+- tabs/: Individual tab modules
+- components/: Reusable UI components
+- utils/: UI utility functions
+
+For backward compatibility, the old CharacterCreatorUI class is still available
+from character_creator_ui.py, but the new modular structure is recommended.
+"""
+
+# Import from new modular structure (recommended)
+from .app import DnDCampaignManagerApp, launch_ui
+
+# Import old monolithic class for backward compatibility
+from .character_creator_ui import CharacterCreatorUI, launch_ui as launch_ui_legacy
+
+# Export both for backward compatibility
+__all__ = [
+    # New modular structure (recommended)
+    "DnDCampaignManagerApp",
+    "launch_ui",
+
+    # Old monolithic structure (deprecated, for backward compatibility)
+    "CharacterCreatorUI",
+    "launch_ui_legacy",
+]

src/ui/app.py

@@ -0,0 +1,183 @@
+"""
+Main Application Orchestrator for D'n'D Campaign Manager
+Assembles all modular tabs into the complete Gradio interface
+"""
+
+import gradio as gr
+from src.agents.character_agent import CharacterAgent
+from src.agents.campaign_agent import CampaignAgent
+from src.ui.components.dropdown_manager import DropdownManager
+from src.ui.tabs import (
+    AboutTab,
+    CharacterCreateTab,
+    CharacterLoadTab,
+    CharacterManageTab,
+    CharacterPortraitTab,
+    CharacterExportTab,
+    CampaignCreateTab,
+    CampaignManageTab,
+    CampaignAddCharsTab,
+    CampaignSynthesizeTab,
+    SessionTrackingTab,
+)
+
+
+class DnDCampaignManagerApp:
+    """Main application class that orchestrates all UI components"""
+
+    def __init__(self):
+        # Initialize agents
+        self.character_agent = CharacterAgent()
+        self.campaign_agent = CampaignAgent()
+
+        # Initialize dropdown manager
+        self.dropdown_manager = DropdownManager(
+            character_agent=self.character_agent,
+            campaign_agent=self.campaign_agent
+        )
+
+        # Initialize tabs
+        self.about_tab = AboutTab()
+        self.character_create_tab = CharacterCreateTab(
+            character_agent=self.character_agent
+        )
+        self.character_load_tab = CharacterLoadTab(
+            character_agent=self.character_agent,
+            dropdown_manager=self.dropdown_manager
+        )
+        self.character_manage_tab = CharacterManageTab(
+            character_agent=self.character_agent,
+            dropdown_manager=self.dropdown_manager
+        )
+        self.character_portrait_tab = CharacterPortraitTab(
+            character_agent=self.character_agent,
+            dropdown_manager=self.dropdown_manager
+        )
+        self.character_export_tab = CharacterExportTab(
+            character_agent=self.character_agent,
+            dropdown_manager=self.dropdown_manager
+        )
+        self.campaign_create_tab = CampaignCreateTab(
+            campaign_agent=self.campaign_agent
+        )
+        self.campaign_manage_tab = CampaignManageTab(
+            campaign_agent=self.campaign_agent,
+            dropdown_manager=self.dropdown_manager
+        )
+        self.campaign_add_chars_tab = CampaignAddCharsTab(
+            character_agent=self.character_agent,
+            campaign_agent=self.campaign_agent,
+            dropdown_manager=self.dropdown_manager
+        )
+        self.campaign_synthesize_tab = CampaignSynthesizeTab(
+            character_agent=self.character_agent,
+            campaign_agent=self.campaign_agent,
+            dropdown_manager=self.dropdown_manager
+        )
+        self.session_tracking_tab = SessionTrackingTab(
+            campaign_agent=self.campaign_agent,
+            dropdown_manager=self.dropdown_manager
+        )
+
+    def create_interface(self) -> gr.Blocks:
+        """Create and assemble the complete Gradio interface"""
+        with gr.Blocks(title="D'n'D Campaign Manager - Character Creator", theme=gr.themes.Soft()) as interface:
+            gr.Markdown("""
+            # 🎲 D'n'D Campaign Manager
+            ## Complete D&D Character Creator
+
+            Create and manage complete D&D 5e characters for your campaigns!
+            """)
+
+            with gr.Tabs():
+                # Character tabs
+                self.character_create_tab.create()
+
+                character_dropdown = self.character_load_tab.create()
+                delete_character_dropdown = self.character_manage_tab.create()
+                portrait_character_dropdown = self.character_portrait_tab.create()
+                export_character_dropdown = self.character_export_tab.create()
+
+                # Campaign Management tab with sub-tabs
+                with gr.Tab("Campaign Management"):
+                    gr.Markdown("""
+                    ### 🎲 Campaign Management
+                    Create and manage your D&D campaigns, track sessions, and record events!
+                    """)
+
+                    with gr.Tabs():
+                        self.campaign_synthesize_tab.create()
+                        self.campaign_create_tab.create()
+                        manage_campaign_dropdown = self.campaign_manage_tab.create()
+                        add_char_campaign_dropdown, add_char_character_dropdown = self.campaign_add_chars_tab.create()
+                        session_campaign_dropdown, auto_session_campaign_dropdown, notes_campaign_dropdown, event_campaign_dropdown = self.session_tracking_tab.create()
+
+                # About tab
+                self.about_tab.create()
+
+            gr.Markdown("""
+            ---
+            ### Tips
+            - Enable "Use AI" options for more creative and detailed characters
+            - Use Standard Array for balanced characters
+            - Use Roll for random variation
+            - Save your character ID to load it later
+            - Check the character list to find previously created characters
+            """)
+
+            # Auto-populate dropdowns on interface load
+            def populate_all_dropdowns():
+                """Populate all dropdowns when interface loads"""
+                campaign_choices = self.dropdown_manager.get_campaign_dropdown_choices()
+                character_choices = self.dropdown_manager.get_character_dropdown_choices()
+
+                return [
+                    gr.update(choices=character_choices),  # character_dropdown
+                    gr.update(choices=character_choices),  # delete_character_dropdown
+                    gr.update(choices=character_choices),  # portrait_character_dropdown
+                    gr.update(choices=character_choices),  # export_character_dropdown
+                    gr.update(choices=campaign_choices),   # manage_campaign_dropdown
+                    gr.update(choices=campaign_choices),   # add_char_campaign_dropdown
+                    gr.update(choices=character_choices),  # add_char_character_dropdown
+                    gr.update(choices=campaign_choices),   # session_campaign_dropdown
+                    gr.update(choices=campaign_choices),   # auto_session_campaign_dropdown
+                    gr.update(choices=campaign_choices),   # notes_campaign_dropdown
+                    gr.update(choices=campaign_choices),   # event_campaign_dropdown
+                ]
+
+            interface.load(
+                fn=populate_all_dropdowns,
+                inputs=[],
+                outputs=[
+                    character_dropdown,
+                    delete_character_dropdown,
+                    portrait_character_dropdown,
+                    export_character_dropdown,
+                    manage_campaign_dropdown,
+                    add_char_campaign_dropdown,
+                    add_char_character_dropdown,
+                    session_campaign_dropdown,
+                    auto_session_campaign_dropdown,
+                    notes_campaign_dropdown,
+                    event_campaign_dropdown,
+                ]
+            )
+
+        return interface
+
+
+def launch_ui():
+    """Launch the Gradio interface"""
+    app = DnDCampaignManagerApp()
+    interface = app.create_interface()
+
+    interface.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True
+    )
+
+
+if __name__ == "__main__":
+    launch_ui()

src/ui/character_creator_ui.py

@@ -0,0 +1,1842 @@
+"""
+Gradio UI for Character Creator
+"""
+
+import gradio as gr
+from typing import Optional, Tuple
+import traceback
+
+from src.agents.character_agent import CharacterAgent
+from src.agents.campaign_agent import CampaignAgent
+from src.models.character import DnDRace, DnDClass
+from src.models.campaign import CampaignTheme
+from src.utils.validators import get_available_races, get_available_classes
+from src.utils.image_generator import RACE_SKIN_TONES
+from src.utils.character_sheet_exporter import CharacterSheetExporter
+
+
+class CharacterCreatorUI:
+    """Gradio interface for character creation"""
+
+    def __init__(self):
+        self.agent = CharacterAgent()
+        self.campaign_agent = CampaignAgent()
+        self.exporter = CharacterSheetExporter()
+
+    def _get_alignment_description(self, alignment: str) -> str:
+        """Get personality guidance based on alignment"""
+        descriptions = {
+            "Lawful Good": "a strong sense of justice, honor, and desire to help others within the rules",
+            "Neutral Good": "genuine kindness and desire to help, but flexibility in how they achieve good",
+            "Chaotic Good": "rebellious goodness, fighting for freedom and helping others by breaking unjust rules",
+            "Lawful Neutral": "strict adherence to law, order, and tradition above good or evil",
+            "True Neutral": "balance and pragmatism, avoiding extreme positions",
+            "Chaotic Neutral": "unpredictability, freedom-loving nature, and self-interest",
+            "Lawful Evil": "tyrannical control, following their own code while causing harm",
+            "Neutral Evil": "pure self-interest and willingness to harm others for personal gain",
+            "Chaotic Evil": "destructive chaos, cruelty, and disregard for any rules or others' wellbeing"
+        }
+        return descriptions.get(alignment, "their moral compass")
+
+    def generate_name_ui(
+        self,
+        race: str,
+        character_class: str,
+        gender: str,
+        alignment: str,
+    ) -> str:
+        """
+        Generate a character name using AI
+        This is a self-contained function that calls the agent's generate_name method
+        Alignment can influence name generation (e.g., darker names for evil characters)
+        """
+        try:
+            race_enum = DnDRace(race)
+            class_enum = DnDClass(character_class)
+
+            # Add alignment hint to the generation prompt
+            alignment_hint = None
+            if "Evil" in alignment:
+                alignment_hint = "with a darker, more menacing tone"
+            elif "Good" in alignment:
+                alignment_hint = "with a heroic, noble tone"
+            elif alignment == "Chaotic Neutral":
+                alignment_hint = "with a wild, unpredictable feel"
+
+            # Build custom prompt if we have alignment influence
+            if alignment_hint:
+                prompt = f"""Generate a single fantasy character name for a D&D character.
+
+Race: {race_enum.value}
+Class: {class_enum.value}
+Gender: {gender if gender != "Not specified" else "any"}
+Alignment: {alignment} - name should reflect this {alignment_hint}
+
+Requirements:
+- Just the name, nothing else
+- Make it sound appropriate for the race, gender, and alignment
+- {alignment_hint}
+- Make it memorable and fitting for an adventurer
+- 2-3 words maximum
+
+Examples:
+- Evil: "Malakai Shadowbane", "Drusilla Nightwhisper"
+- Good: "Elara Lightbringer", "Theron Brightheart"
+- Chaotic: "Raven Wildfire", "Zephyr Stormblade"
+
+Generate only the name:"""
+
+                name = self.agent.ai_client.generate_creative(prompt).strip()
+                name = name.split('\n')[0].strip('"\'')
+                return name
+            else:
+                # Use standard generation
+                name = self.agent.generate_name(
+                    race=race_enum,
+                    character_class=class_enum,
+                    gender=gender if gender != "Not specified" else None
+                )
+                return name
+
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    def create_character_ui(
+        self,
+        name: str,
+        race: str,
+        character_class: str,
+        level: int,
+        gender: str,
+        skin_tone: str,
+        alignment: str,
+        background_dropdown: str,
+        custom_background: str,
+        personality_prompt: str,
+        stats_method: str,
+        use_ai_background: bool,
+    ) -> Tuple[str, str]:
+        """
+        Create character with UI inputs
+
+        Returns:
+            Tuple of (character_sheet_markdown, status_message)
+        """
+        try:
+            # Validate inputs
+            if not name.strip():
+                return "", "❌ Error: Please provide a character name (use 'Generate Name' button or type one)"
+
+            if level < 1 or level > 20:
+                return "", "❌ Error: Level must be between 1 and 20"
+
+            # Convert race, class, and alignment
+            try:
+                race_enum = DnDRace(race)
+                class_enum = DnDClass(character_class)
+                from src.models.character import Alignment
+                alignment_enum = Alignment(alignment)
+            except ValueError as e:
+                return "", f"❌ Error: Invalid race, class, or alignment - {e}"
+
+            # Determine final background type
+            if background_dropdown == "Custom (enter below)":
+                final_background = custom_background.strip() if custom_background.strip() else "Adventurer"
+            else:
+                final_background = background_dropdown
+
+            # Create character with gender AND alignment in personality prompt
+            gender_hint = f"Character is {gender}. " if gender != "Not specified" else ""
+            alignment_hint = f"Character's alignment is {alignment}, so their personality and backstory should reflect {self._get_alignment_description(alignment)}. "
+
+            full_personality_prompt = gender_hint + alignment_hint + (personality_prompt if personality_prompt else "")
+
+            character = self.agent.create_character(
+                name=name,
+                race=race_enum,
+                character_class=class_enum,
+                level=level,
+                background_type=final_background,
+                personality_prompt=full_personality_prompt if use_ai_background else None,
+                stats_method=stats_method,
+            )
+
+            # Override alignment, gender, and skin tone if user specified
+            character.alignment = alignment_enum
+            character.gender = gender if gender != "Not specified" else None
+            character.skin_tone = skin_tone if skin_tone else None
+
+            # Generate markdown
+            markdown = character.to_markdown()
+
+            status = f"""✅ Character Created Successfully!
+
+**ID:** {character.id}
+**Name:** {character.name}
+**Race:** {character.race.value}
+**Class:** {character.character_class.value}
+**Level:** {character.level}
+
+Character has been saved to database."""
+
+            return markdown, status
+
+        except Exception as e:
+            error_msg = f"❌ Error creating character:\n\n{str(e)}\n\n{traceback.format_exc()}"
+            return "", error_msg
+
+    def load_character_ui(self, character_id: str) -> Tuple[str, str]:
+        """Load character by ID"""
+        try:
+            if not character_id.strip():
+                return "", "❌ Error: Please provide a character ID"
+
+            character = self.agent.load_character(character_id)
+
+            if character:
+                markdown = character.to_markdown()
+                status = f"✅ Loaded character: {character.name}"
+                return markdown, status
+            else:
+                return "", f"❌ Character not found: {character_id}"
+
+        except Exception as e:
+            return "", f"❌ Error loading character: {e}"
+
+    def list_characters_ui(self) -> Tuple[str, str]:
+        """List all saved characters"""
+        try:
+            characters = self.agent.list_characters()
+
+            if not characters:
+                return "", "No characters found in database."
+
+            # Create table
+            markdown = "# Saved Characters\n\n"
+            markdown += "| Name | Race | Class | Level | ID |\n"
+            markdown += "|------|------|-------|-------|----|\n"
+
+            for char in characters[-20:]:  # Last 20 characters
+                markdown += f"| {char.name} | {char.race.value} | {char.character_class.value} | {char.level} | `{char.id}` |\n"
+
+            status = f"✅ Found {len(characters)} character(s)"
+            return markdown, status
+
+        except Exception as e:
+            return "", f"❌ Error listing characters: {e}"
+
+    def delete_character_ui(self, character_id: str) -> str:
+        """Delete character by ID"""
+        try:
+            if not character_id.strip():
+                return "❌ Error: Please provide a character ID"
+
+            # Check if exists
+            character = self.agent.load_character(character_id)
+            if not character:
+                return f"❌ Character not found: {character_id}"
+
+            # Delete
+            self.agent.delete_character(character_id)
+            return f"✅ Deleted character: {character.name} ({character_id})"
+
+        except Exception as e:
+            return f"❌ Error deleting character: {e}"
+
+    def generate_portrait_ui(
+        self,
+        character_id: str,
+        style: str = "fantasy art",
+        quality: str = "standard",
+        provider: str = "auto"
+    ) -> Tuple[Optional[str], str]:
+        """
+        Generate character portrait
+
+        Returns:
+            Tuple of (image_path, status_message)
+        """
+        try:
+            if not character_id.strip():
+                return None, "❌ Error: Please provide a character ID"
+
+            # Load character
+            character = self.agent.load_character(character_id)
+            if not character:
+                return None, f"❌ Character not found: {character_id}"
+
+            # Generate portrait
+            file_path, status = self.agent.generate_portrait(
+                character=character,
+                style=style,
+                quality=quality,
+                provider=provider
+            )
+
+            return file_path, status
+
+        except Exception as e:
+            import traceback
+            error_msg = f"❌ Error generating portrait:\n\n{str(e)}\n\n{traceback.format_exc()}"
+            return None, error_msg
+
+    def export_character_sheet_ui(
+        self,
+        character_id: str,
+        export_format: str = "markdown"
+    ) -> str:
+        """
+        Export character sheet to file
+
+        Returns:
+            Status message with file path
+        """
+        try:
+            if not character_id.strip():
+                return "❌ Error: Please provide a character ID"
+
+            # Load character
+            character = self.agent.load_character(character_id)
+            if not character:
+                return f"❌ Character not found: {character_id}"
+
+            # Export to selected format
+            file_path = self.exporter.save_export(character, format=export_format)
+
+            return f"""✅ Character sheet exported successfully!
+
+**Character:** {character.name}
+**Format:** {export_format.upper()}
+**File:** {file_path}
+
+You can find the exported file in the data/exports/ directory."""
+
+        except Exception as e:
+            return f"❌ Error exporting character sheet:\n\n{str(e)}\n\n{traceback.format_exc()}"
+
+    def preview_export_ui(
+        self,
+        character_id: str,
+        export_format: str = "markdown"
+    ) -> Tuple[str, str]:
+        """
+        Preview character sheet export without saving
+
+        Returns:
+            Tuple of (preview_content, status_message)
+        """
+        try:
+            if not character_id.strip():
+                return "", "❌ Error: Please provide a character ID"
+
+            # Load character
+            character = self.agent.load_character(character_id)
+            if not character:
+                return "", f"❌ Character not found: {character_id}"
+
+            # Generate preview based on format
+            if export_format == "markdown":
+                preview = self.exporter.export_to_markdown(character)
+            elif export_format == "json":
+                preview = f"```json\n{self.exporter.export_to_json(character)}\n```"
+            elif export_format == "html":
+                preview = f"```html\n{self.exporter.export_to_html(character)}\n```"
+            else:
+                return "", f"❌ Unknown format: {export_format}"
+
+            status = f"✅ Preview generated for {character.name}"
+            return preview, status
+
+        except Exception as e:
+            return "", f"❌ Error generating preview:\n\n{str(e)}\n\n{traceback.format_exc()}"
+
+    # Campaign Management UI Methods
+    def create_campaign_ui(
+        self,
+        name: str,
+        theme: str,
+        setting: str,
+        summary: str,
+        main_conflict: str,
+        game_master: str,
+        world_name: str,
+        starting_location: str,
+        level_range: str,
+        party_size: int
+    ) -> str:
+        """Create a new campaign"""
+        try:
+            if not name.strip():
+                return "❌ Error: Please provide a campaign name"
+
+            campaign = self.campaign_agent.create_campaign(
+                name=name,
+                theme=theme,
+                setting=setting,
+                summary=summary,
+                main_conflict=main_conflict,
+                game_master=game_master,
+                world_name=world_name,
+                starting_location=starting_location,
+                level_range=level_range,
+                party_size=party_size
+            )
+
+            return f"""✅ Campaign Created Successfully!
+
+**ID:** {campaign.id}
+**Name:** {campaign.name}
+**Theme:** {campaign.theme.value}
+**Setting:** {campaign.setting}
+
+Campaign has been saved to database.
+Use the campaign ID to manage characters and sessions."""
+
+        except Exception as e:
+            return f"❌ Error creating campaign:\n\n{str(e)}\n\n{traceback.format_exc()}"
+
+    def list_campaigns_ui(self, active_only: bool = False) -> Tuple[str, str]:
+        """List all campaigns"""
+        try:
+            campaigns = self.campaign_agent.list_campaigns(active_only=active_only)
+
+            if not campaigns:
+                return "", "No campaigns found in database."
+
+            # Create table
+            markdown = "# Campaigns\n\n"
+            markdown += "| Name | Theme | Session | Status | ID |\n"
+            markdown += "|------|-------|---------|--------|----|\n"
+
+            for campaign in campaigns[-20:]:  # Last 20 campaigns
+                status = "Active" if campaign.is_active else "Inactive"
+                markdown += f"| {campaign.name} | {campaign.theme.value} | {campaign.current_session} | {status} | `{campaign.id}` |\n"
+
+            status = f"✅ Found {len(campaigns)} campaign(s)"
+            return markdown, status
+
+        except Exception as e:
+            return "", f"❌ Error listing campaigns: {e}"
+
+    def load_campaign_ui(self, campaign_id: str) -> Tuple[str, str]:
+        """Load campaign details"""
+        try:
+            if not campaign_id.strip():
+                return "", "❌ Error: Please provide a campaign ID"
+
+            campaign = self.campaign_agent.load_campaign(campaign_id)
+
+            if campaign:
+                markdown = campaign.to_markdown()
+                status = f"✅ Loaded campaign: {campaign.name}"
+                return markdown, status
+            else:
+                return "", f"❌ Campaign not found: {campaign_id}"
+
+        except Exception as e:
+            return "", f"❌ Error loading campaign: {e}"
+
+    def add_character_to_campaign_ui(self, campaign_id: str, character_id: str) -> str:
+        """Add a character to a campaign"""
+        try:
+            if not campaign_id.strip() or not character_id.strip():
+                return "❌ Error: Please provide both campaign ID and character ID"
+
+            # Verify character exists
+            character = self.agent.load_character(character_id)
+            if not character:
+                return f"❌ Character not found: {character_id}"
+
+            # Add to campaign
+            success = self.campaign_agent.add_character_to_campaign(campaign_id, character_id)
+
+            if success:
+                return f"✅ Added {character.name} to campaign!"
+            else:
+                return f"❌ Campaign not found: {campaign_id}"
+
+        except Exception as e:
+            return f"❌ Error: {str(e)}"
+
+    def start_session_ui(self, campaign_id: str) -> str:
+        """Start a new session"""
+        try:
+            if not campaign_id.strip():
+                return "❌ Error: Please provide a campaign ID"
+
+            campaign = self.campaign_agent.load_campaign(campaign_id)
+            if not campaign:
+                return f"❌ Campaign not found: {campaign_id}"
+
+            self.campaign_agent.start_new_session(campaign_id)
+
+            return f"""✅ Started Session {campaign.current_session + 1}!
+
+**Campaign:** {campaign.name}
+**New Session Number:** {campaign.current_session + 1}
+**Total Sessions:** {campaign.total_sessions + 1}"""
+
+        except Exception as e:
+            return f"❌ Error: {str(e)}"
+
+    def auto_generate_session_ui(self, campaign_id: str) -> str:
+        """Auto-generate next session using AI"""
+        try:
+            if not campaign_id.strip():
+                return "❌ Error: Please select a campaign"
+
+            campaign = self.campaign_agent.load_campaign(campaign_id)
+            if not campaign:
+                return f"❌ Campaign not found: {campaign_id}"
+
+            # Generate session using autonomous AI
+            session_data = self.campaign_agent.auto_generate_next_session(campaign_id)
+
+            if 'error' in session_data:
+                return f"❌ Error: {session_data['error']}"
+
+            # Format output for display
+            output = []
+            output.append(f"# 🤖 Auto-Generated Session {session_data.get('session_number', 'N/A')}")
+            output.append(f"\n**Campaign:** {campaign.name}")
+            output.append(f"\n**Session Title:** {session_data.get('session_title', 'Untitled')}")
+            output.append(f"\n---\n")
+
+            # Opening Scene
+            if 'opening_scene' in session_data:
+                output.append(f"## 🎬 Opening Scene\n\n{session_data['opening_scene']}\n\n")
+
+            # Key Encounters
+            if 'key_encounters' in session_data and session_data['key_encounters']:
+                output.append("## ⚔️ Key Encounters\n\n")
+                for i, encounter in enumerate(session_data['key_encounters'], 1):
+                    output.append(f"{i}. {encounter}\n")
+                output.append("\n")
+
+            # NPCs Featured
+            if 'npcs_featured' in session_data and session_data['npcs_featured']:
+                output.append("## 👥 NPCs Featured\n\n")
+                for npc in session_data['npcs_featured']:
+                    output.append(f"- {npc}\n")
+                output.append("\n")
+
+            # Locations
+            if 'locations' in session_data and session_data['locations']:
+                output.append("## 🗺️ Locations\n\n")
+                for loc in session_data['locations']:
+                    output.append(f"- {loc}\n")
+                output.append("\n")
+
+            # Plot Developments
+            if 'plot_developments' in session_data and session_data['plot_developments']:
+                output.append("## 📖 Plot Developments\n\n")
+                for i, dev in enumerate(session_data['plot_developments'], 1):
+                    output.append(f"{i}. {dev}\n")
+                output.append("\n")
+
+            # Potential Outcomes
+            if 'potential_outcomes' in session_data and session_data['potential_outcomes']:
+                output.append("## 🎲 Potential Outcomes\n\n")
+                for i, outcome in enumerate(session_data['potential_outcomes'], 1):
+                    output.append(f"{i}. {outcome}\n")
+                output.append("\n")
+
+            # Rewards
+            if 'rewards' in session_data and session_data['rewards']:
+                output.append("## 💰 Rewards\n\n")
+                for reward in session_data['rewards']:
+                    output.append(f"- {reward}\n")
+                output.append("\n")
+
+            # Cliffhanger
+            if 'cliffhanger' in session_data and session_data['cliffhanger']:
+                output.append(f"## 🎭 Cliffhanger\n\n{session_data['cliffhanger']}\n\n")
+
+            output.append("---\n\n")
+            output.append("✅ **Session plan generated successfully!**\n\n")
+            output.append("💡 **Next Steps:**\n")
+            output.append("- Review the session plan above\n")
+            output.append("- Adjust encounters/NPCs as needed for your table\n")
+            output.append("- Copy relevant sections to your session notes\n")
+            output.append("- Start the session when ready!\n")
+
+            return "".join(output)
+
+        except Exception as e:
+            import traceback
+            return f"❌ Error generating session:\n\n{str(e)}\n\n{traceback.format_exc()}"
+
+    def add_event_ui(
+        self,
+        campaign_id: str,
+        event_type: str,
+        title: str,
+        description: str,
+        importance: int
+    ) -> str:
+        """Add an event to the campaign"""
+        try:
+            if not campaign_id.strip():
+                return "❌ Error: Please provide a campaign ID"
+
+            if not title.strip() or not description.strip():
+                return "❌ Error: Please provide event title and description"
+
+            event = self.campaign_agent.add_event(
+                campaign_id=campaign_id,
+                event_type=event_type,
+                title=title,
+                description=description,
+                importance=importance
+            )
+
+            if event:
+                return f"""✅ Event Added!
+
+**Title:** {title}
+**Type:** {event_type}
+**Importance:** {'⭐' * importance}
+
+Event has been recorded in campaign history."""
+            else:
+                return f"❌ Campaign not found: {campaign_id}"
+
+        except Exception as e:
+            return f"❌ Error: {str(e)}"
+
+    def get_character_choices_ui(self) -> list:
+        """Get list of characters for selection"""
+        try:
+            characters = self.agent.list_characters()
+            if not characters:
+                return []
+
+            # Create choices as "Name (Race Class, Level X) - ID"
+            choices = []
+            for char in characters:
+                label = f"{char.name} ({char.race.value} {char.character_class.value}, Level {char.level})"
+                choices.append((label, char.id))
+
+            return choices
+        except Exception as e:
+            return []
+
+    def get_character_dropdown_choices(self) -> list:
+        """Get character choices for dropdown (returns IDs only)"""
+        try:
+            characters = self.agent.list_characters()
+            if not characters:
+                return []
+
+            # Create dropdown choices with nice labels
+            choices = []
+            for char in characters:
+                label = f"{char.name} ({char.race.value} {char.character_class.value}, Lvl {char.level})"
+                choices.append(label)
+
+            return choices
+        except Exception as e:
+            return []
+
+    def get_character_id_from_label(self, label: str) -> str:
+        """Extract character ID from dropdown label"""
+        try:
+            # Parse the label to get character name
+            if not label:
+                return ""
+
+            name = label.split(" (")[0] if " (" in label else label
+
+            # Find character by name
+            characters = self.agent.list_characters()
+            for char in characters:
+                if char.name == name:
+                    return char.id
+
+            return ""
+        except Exception as e:
+            return ""
+
+    def get_campaign_dropdown_choices(self) -> list:
+        """Get campaign choices for dropdown"""
+        try:
+            campaigns = self.campaign_agent.list_campaigns()
+            if not campaigns:
+                return []
+
+            choices = []
+            for campaign in campaigns:
+                label = f"{campaign.name} ({campaign.theme.value}, Session {campaign.current_session})"
+                choices.append(label)
+
+            return choices
+        except Exception as e:
+            return []
+
+    def get_campaign_id_from_label(self, label: str) -> str:
+        """Extract campaign ID from dropdown label"""
+        try:
+            if not label:
+                return ""
+
+            name = label.split(" (")[0] if " (" in label else label
+
+            campaigns = self.campaign_agent.list_campaigns()
+            for campaign in campaigns:
+                if campaign.name == name:
+                    return campaign.id
+
+            return ""
+        except Exception as e:
+            return ""
+
+    def synthesize_campaign_ui(
+        self,
+        selected_character_ids: list,
+        game_master: str,
+        additional_notes: str
+    ) -> str:
+        """Synthesize a campaign from selected characters"""
+        try:
+            # Check if any characters selected
+            if not selected_character_ids:
+                return "❌ Error: Please select at least one character"
+
+            # Load all characters
+            characters = []
+            for char_id in selected_character_ids:
+                char = self.agent.load_character(char_id)
+                if char:
+                    characters.append(char)
+
+            if not characters:
+                return "❌ Error: No valid characters found"
+
+            # Synthesize campaign
+            campaign = self.campaign_agent.synthesize_campaign_from_characters(
+                characters=characters,
+                game_master=game_master,
+                additional_notes=additional_notes
+            )
+
+            # Create response with character list
+            char_list = "\n".join([f"- {char.name} (Level {char.level} {char.race.value} {char.character_class.value})" for char in characters])
+
+            # Build comprehensive output with all campaign details
+            output = [f"""✅ Campaign Synthesized Successfully!
+
+**Campaign ID:** {campaign.id}
+**Campaign Name:** {campaign.name}
+**Theme:** {campaign.theme.value}
+**World:** {campaign.world_name}
+**Starting Location:** {campaign.starting_location}
+
+**Party Members ({len(characters)}):**
+{char_list}
+
+**Level Range:** {campaign.level_range}
+
+---
+
+## Campaign Overview
+
+**Summary:**
+{campaign.summary}
+
+**Main Conflict:**
+{campaign.main_conflict}
+
+**Current Story Arc:**
+{campaign.current_arc if campaign.current_arc else "See detailed notes below"}
+"""]
+
+            # Add factions if present
+            if campaign.key_factions:
+                output.append("\n## Key Factions\n")
+                for faction in campaign.key_factions:
+                    output.append(f"- {faction}\n")
+
+            # Add villains if present
+            if campaign.major_villains:
+                output.append("\n## Major Villains\n")
+                for villain in campaign.major_villains:
+                    output.append(f"- {villain}\n")
+
+            # Add mysteries if present
+            if campaign.central_mysteries:
+                output.append("\n## Central Mysteries\n")
+                for mystery in campaign.central_mysteries:
+                    output.append(f"- {mystery}\n")
+
+            # Add detailed campaign notes (includes character connections, hooks, sessions, NPCs, locations)
+            if campaign.notes:
+                output.append("\n---\n\n")
+                output.append(campaign.notes)
+
+            output.append(f"""
+
+---
+
+✅ **Campaign Created!** All characters have been added to the campaign.
+
+💡 **Next Steps:**
+- View full details in the "Manage Campaign" tab
+- Start your first session in "Session Tracking"
+- Add campaign events as your story unfolds""")
+
+            return "".join(output)
+
+        except Exception as e:
+            return f"❌ Error synthesizing campaign:\n\n{str(e)}\n\n{traceback.format_exc()}"
+
+    def create_interface(self) -> gr.Blocks:
+        """Create Gradio interface"""
+
+        with gr.Blocks(title="D'n'D Campaign Manager - Character Creator", theme=gr.themes.Soft()) as interface:
+            gr.Markdown("""
+            # 🎲 D'n'D Campaign Manager
+            ## Complete D&D Character Creator
+
+            Create and manage complete D&D 5e characters for your campaigns!
+            """)
+
+            with gr.Tabs():
+                # Tab 1: Create Character
+                with gr.Tab("Create Character"):
+                    gr.Markdown("### Character Creation")
+
+                    with gr.Row():
+                        with gr.Column():
+                            gr.Markdown("#### Basic Information")
+
+                            with gr.Row():
+                                name_input = gr.Textbox(
+                                    label="Character Name",
+                                    placeholder="Thorin Ironforge",
+                                    info="Type a name or generate one below",
+                                    scale=3
+                                )
+
+                            race_dropdown = gr.Dropdown(
+                                choices=get_available_races(),
+                                label="Race",
+                                value="Human",
+                                info="Character's race"
+                            )
+
+                            class_dropdown = gr.Dropdown(
+                                choices=get_available_classes(),
+                                label="Class",
+                                value="Fighter",
+                                info="Character's class"
+                            )
+
+                            gender_dropdown = gr.Dropdown(
+                                choices=["Male", "Female", "Non-binary", "Not specified"],
+                                label="Gender",
+                                value="Not specified",
+                                info="Character's gender"
+                            )
+
+                            skin_tone_dropdown = gr.Dropdown(
+                                choices=RACE_SKIN_TONES[DnDRace.HUMAN],  # Default to Human
+                                label="Skin Tone / Color",
+                                value=None,
+                                info="Select appropriate color for the race"
+                            )
+
+                            generate_name_btn = gr.Button("🎲 Generate Name", variant="secondary", size="sm")
+
+                            level_slider = gr.Slider(
+                                minimum=1,
+                                maximum=20,
+                                value=1,
+                                step=1,
+                                label="Level",
+                                info="Character level (1-20)"
+                            )
+
+                            alignment_dropdown = gr.Dropdown(
+                                choices=[
+                                    "Lawful Good", "Neutral Good", "Chaotic Good",
+                                    "Lawful Neutral", "True Neutral", "Chaotic Neutral",
+                                    "Lawful Evil", "Neutral Evil", "Chaotic Evil"
+                                ],
+                                label="Alignment",
+                                value="True Neutral",
+                                info="Character's moral alignment"
+                            )
+
+                        with gr.Column():
+                            gr.Markdown("#### Background & Personality")
+
+                            background_dropdown = gr.Dropdown(
+                                choices=[
+                                    "Acolyte", "Charlatan", "Criminal", "Entertainer",
+                                    "Folk Hero", "Guild Artisan", "Hermit", "Noble",
+                                    "Outlander", "Sage", "Sailor", "Soldier",
+                                    "Urchin", "Custom (enter below)"
+                                ],
+                                label="Background Type",
+                                value="Soldier",
+                                info="Select from D&D 5e backgrounds or choose Custom"
+                            )
+
+                            custom_background_input = gr.Textbox(
+                                label="Custom Background",
+                                placeholder="Enter your custom background...",
+                                value="",
+                                visible=False,
+                                info="Only used if 'Custom' is selected above"
+                            )
+
+                            use_ai_background = gr.Checkbox(
+                                label="Generate detailed backstory",
+                                value=True,
+                                info="Create a unique backstory for this character"
+                            )
+
+                            personality_input = gr.Textbox(
+                                label="Personality Guidance (Optional)",
+                                placeholder="A mysterious ranger who protects the forest...",
+                                lines=3,
+                                info="Guide AI in creating personality (if enabled)"
+                            )
+
+                            stats_method = gr.Radio(
+                                choices=["standard_array", "roll", "point_buy"],
+                                label="Ability Score Method",
+                                value="standard_array",
+                                info="How to generate ability scores"
+                            )
+
+                    create_btn = gr.Button("⚔️ Create Character", variant="primary", size="lg")
+
+                    gr.Markdown("---")
+
+                    with gr.Row():
+                        character_output = gr.Markdown(label="Character Sheet")
+                        status_output = gr.Textbox(label="Status", lines=8)
+
+                    # Toggle custom background visibility
+                    def toggle_custom_background(background_choice):
+                        return gr.update(visible=background_choice == "Custom (enter below)")
+
+                    # Update skin tone options when race changes
+                    def update_skin_tone_choices(race: str):
+                        try:
+                            race_enum = DnDRace(race)
+                            skin_tones = RACE_SKIN_TONES.get(race_enum, RACE_SKIN_TONES[DnDRace.HUMAN])
+                            return gr.update(choices=skin_tones, value=skin_tones[0] if skin_tones else None)
+                        except:
+                            return gr.update(choices=RACE_SKIN_TONES[DnDRace.HUMAN], value=RACE_SKIN_TONES[DnDRace.HUMAN][0])
+
+                    background_dropdown.change(
+                        fn=toggle_custom_background,
+                        inputs=[background_dropdown],
+                        outputs=[custom_background_input]
+                    )
+
+                    race_dropdown.change(
+                        fn=update_skin_tone_choices,
+                        inputs=[race_dropdown],
+                        outputs=[skin_tone_dropdown]
+                    )
+
+                    # Generate name action - includes alignment for more thematic names
+                    generate_name_btn.click(
+                        fn=self.generate_name_ui,
+                        inputs=[race_dropdown, class_dropdown, gender_dropdown, alignment_dropdown],
+                        outputs=[name_input]
+                    )
+
+                    # Create character action
+                    create_btn.click(
+                        fn=self.create_character_ui,
+                        inputs=[
+                            name_input,
+                            race_dropdown,
+                            class_dropdown,
+                            level_slider,
+                            gender_dropdown,
+                            skin_tone_dropdown,
+                            alignment_dropdown,
+                            background_dropdown,
+                            custom_background_input,
+                            personality_input,
+                            stats_method,
+                            use_ai_background,
+                        ],
+                        outputs=[character_output, status_output]
+                    )
+
+                # Tab 2: Load Character
+                with gr.Tab("Load Character"):
+                    gr.Markdown("### Load Saved Character")
+
+                    load_char_refresh_btn = gr.Button("🔄 Refresh Character List", variant="secondary")
+
+                    character_dropdown = gr.Dropdown(
+                        choices=[],
+                        label="Select Character",
+                        info="Choose a character from the list (type to search)",
+                        allow_custom_value=False,
+                        interactive=True
+                    )
+
+                    with gr.Row():
+                        load_btn = gr.Button("📂 Load Character", variant="primary")
+                        list_btn = gr.Button("📋 List All Characters")
+
+                    gr.Markdown("---")
+
+                    with gr.Row():
+                        loaded_character_output = gr.Markdown(label="Character Sheet")
+                        load_status_output = gr.Textbox(label="Status", lines=6)
+
+                    # Refresh character dropdown
+                    def refresh_character_dropdown():
+                        choices = self.get_character_dropdown_choices()
+                        return gr.update(choices=choices, value=None)
+
+                    load_char_refresh_btn.click(
+                        fn=refresh_character_dropdown,
+                        inputs=[],
+                        outputs=[character_dropdown]
+                    )
+
+                    # Load character action - convert dropdown label to ID
+                    def load_character_from_dropdown(label):
+                        char_id = self.get_character_id_from_label(label)
+                        return self.load_character_ui(char_id)
+
+                    load_btn.click(
+                        fn=load_character_from_dropdown,
+                        inputs=[character_dropdown],
+                        outputs=[loaded_character_output, load_status_output]
+                    )
+
+                    # List characters action
+                    list_btn.click(
+                        fn=self.list_characters_ui,
+                        inputs=[],
+                        outputs=[loaded_character_output, load_status_output]
+                    )
+
+                # Tab 3: Manage Characters
+                with gr.Tab("Manage Characters"):
+                    gr.Markdown("### Character Management")
+
+                    delete_refresh_btn = gr.Button("🔄 Refresh Character List", variant="secondary")
+
+                    delete_character_dropdown = gr.Dropdown(
+                        choices=[],
+                        label="Select Character to Delete",
+                        info="⚠️ Warning: This action cannot be undone! (type to search)",
+                        allow_custom_value=False,
+                        interactive=True
+                    )
+
+                    delete_btn = gr.Button("🗑️ Delete Character", variant="stop")
+
+                    delete_status_output = gr.Textbox(label="Status", lines=3)
+
+                    # Refresh delete character dropdown
+                    def refresh_delete_dropdown():
+                        choices = self.get_character_dropdown_choices()
+                        return gr.update(choices=choices, value=None)
+
+                    delete_refresh_btn.click(
+                        fn=refresh_delete_dropdown,
+                        inputs=[],
+                        outputs=[delete_character_dropdown]
+                    )
+
+                    # Delete character action - convert dropdown label to ID
+                    def delete_character_from_dropdown(label):
+                        char_id = self.get_character_id_from_label(label)
+                        return self.delete_character_ui(char_id)
+
+                    delete_btn.click(
+                        fn=delete_character_from_dropdown,
+                        inputs=[delete_character_dropdown],
+                        outputs=[delete_status_output]
+                    )
+
+                    gr.Markdown("---")
+
+                    with gr.Accordion("Quick Actions", open=False):
+                        quick_list_btn = gr.Button("📋 List All Characters")
+                        quick_list_output = gr.Markdown(label="Character List")
+                        quick_status = gr.Textbox(label="Status", lines=2)
+
+                        quick_list_btn.click(
+                            fn=self.list_characters_ui,
+                            inputs=[],
+                            outputs=[quick_list_output, quick_status]
+                        )
+
+                # Tab 4: Generate Portrait
+                with gr.Tab("Generate Portrait"):
+                    gr.Markdown("""
+                    ### 🎨 AI Character Portrait Generator
+                    Generate stunning character portraits using DALL-E 3 or HuggingFace!
+                    """)
+
+                    with gr.Row():
+                        with gr.Column():
+                            portrait_refresh_btn = gr.Button("🔄 Refresh Character List", variant="secondary")
+
+                            portrait_character_dropdown = gr.Dropdown(
+                                choices=[],
+                                label="Select Character",
+                                info="Choose a character to generate portrait for (type to search)",
+                                allow_custom_value=False,
+                                interactive=True
+                            )
+
+                            portrait_provider = gr.Radio(
+                                choices=["auto", "openai", "huggingface"],
+                                label="Image Provider",
+                                value="auto",
+                                info="Auto: Try OpenAI first, fallback to HuggingFace if needed"
+                            )
+
+                            portrait_style = gr.Dropdown(
+                                choices=[
+                                    "fantasy art",
+                                    "digital painting",
+                                    "anime style",
+                                    "oil painting",
+                                    "watercolor",
+                                    "comic book art",
+                                    "concept art"
+                                ],
+                                label="Art Style",
+                                value="fantasy art",
+                                info="Choose the artistic style"
+                            )
+
+                            portrait_quality = gr.Radio(
+                                choices=["standard", "hd"],
+                                label="Image Quality (OpenAI only)",
+                                value="standard",
+                                info="HD costs more tokens (OpenAI only)"
+                            )
+
+                            generate_portrait_btn = gr.Button(
+                                "🎨 Generate Portrait",
+                                variant="primary",
+                                size="lg"
+                            )
+
+                            portrait_status = gr.Textbox(
+                                label="Status",
+                                lines=4
+                            )
+
+                        with gr.Column():
+                            portrait_output = gr.Image(
+                                label="Generated Portrait",
+                                type="filepath",
+                                height=512
+                            )
+
+                    gr.Markdown("""
+                    **Providers:**
+                    - **OpenAI DALL-E 3**: High quality, costs $0.04/image (standard) or $0.08/image (HD)
+                    - **HuggingFace (Free!)**: Stable Diffusion XL, ~100 requests/day on free tier
+                    - **Auto**: Tries OpenAI first, automatically falls back to HuggingFace if billing issues
+
+                    Portraits are automatically saved to `data/portraits/` directory.
+
+                    **Tips:**
+                    - Use "auto" mode for seamless fallback
+                    - OpenAI HD quality produces better results but costs 2x
+                    - HuggingFace is free but may have a 30-60s warm-up time
+                    - Different styles work better for different races/classes
+                    """)
+
+                    # Refresh portrait character dropdown
+                    def refresh_portrait_dropdown():
+                        choices = self.get_character_dropdown_choices()
+                        return gr.update(choices=choices, value=None)
+
+                    portrait_refresh_btn.click(
+                        fn=refresh_portrait_dropdown,
+                        inputs=[],
+                        outputs=[portrait_character_dropdown]
+                    )
+
+                    # Generate portrait action - convert dropdown label to ID
+                    def generate_portrait_from_dropdown(label, style, quality, provider):
+                        char_id = self.get_character_id_from_label(label)
+                        return self.generate_portrait_ui(char_id, style, quality, provider)
+
+                    generate_portrait_btn.click(
+                        fn=generate_portrait_from_dropdown,
+                        inputs=[portrait_character_dropdown, portrait_style, portrait_quality, portrait_provider],
+                        outputs=[portrait_output, portrait_status]
+                    )
+
+                # Tab 5: Export Character Sheet
+                with gr.Tab("Export Character Sheet"):
+                    gr.Markdown("""
+                    ### 📄 Export Character Sheets
+                    Export your characters to formatted character sheets in multiple formats!
+                    """)
+
+                    with gr.Row():
+                        with gr.Column():
+                            export_char_refresh_btn = gr.Button("🔄 Refresh Character List", variant="secondary")
+
+                            export_character_dropdown = gr.Dropdown(
+                                choices=[],
+                                label="Select Character",
+                                info="Choose a character to export (type to search)",
+                                allow_custom_value=False,
+                                interactive=True
+                            )
+
+                            export_format = gr.Radio(
+                                choices=["markdown", "json", "html"],
+                                label="Export Format",
+                                value="markdown",
+                                info="Choose the format for your character sheet"
+                            )
+
+                            with gr.Row():
+                                preview_btn = gr.Button("👁️ Preview", variant="secondary")
+                                export_btn = gr.Button("💾 Export to File", variant="primary")
+
+                            export_status = gr.Textbox(
+                                label="Status",
+                                lines=6
+                            )
+
+                        with gr.Column():
+                            preview_output = gr.Markdown(
+                                label="Preview",
+                                value="Character sheet preview will appear here..."
+                            )
+
+                    gr.Markdown("""
+                    ### Format Descriptions
+
+                    **Markdown (.md)**
+                    - Clean, readable text format with tables
+                    - Perfect for sharing in Discord, GitHub, or note apps
+                    - Includes all character stats, features, and background
+                    - Easy to read and edit
+
+                    **JSON (.json)**
+                    - Structured data format
+                    - Perfect for importing into other tools or programs
+                    - Contains all character data in a machine-readable format
+                    - Great for backup or data transfer
+
+                    **HTML (.html)**
+                    - Styled character sheet that can be opened in a browser
+                    - Print-ready format (mimics official D&D character sheet)
+                    - Beautiful parchment styling with maroon borders
+                    - Can be converted to PDF using browser's print function
+
+                    All exports are saved to the `data/exports/` directory.
+                    """)
+
+                    # Refresh export character dropdown
+                    def refresh_export_dropdown():
+                        choices = self.get_character_dropdown_choices()
+                        return gr.update(choices=choices, value=None)
+
+                    export_char_refresh_btn.click(
+                        fn=refresh_export_dropdown,
+                        inputs=[],
+                        outputs=[export_character_dropdown]
+                    )
+
+                    # Preview action - convert dropdown label to ID
+                    def preview_from_dropdown(label, format):
+                        char_id = self.get_character_id_from_label(label)
+                        return self.preview_export_ui(char_id, format)
+
+                    preview_btn.click(
+                        fn=preview_from_dropdown,
+                        inputs=[export_character_dropdown, export_format],
+                        outputs=[preview_output, export_status]
+                    )
+
+                    # Export action - convert dropdown label to ID
+                    def export_from_dropdown(label, format):
+                        char_id = self.get_character_id_from_label(label)
+                        return self.export_character_sheet_ui(char_id, format)
+
+                    export_btn.click(
+                        fn=export_from_dropdown,
+                        inputs=[export_character_dropdown, export_format],
+                        outputs=[export_status]
+                    )
+
+                # Tab 6: Campaign Management
+                with gr.Tab("Campaign Management"):
+                    gr.Markdown("""
+                    ### 🎲 Campaign Management
+                    Create and manage your D&D campaigns, track sessions, and record events!
+                    """)
+
+                    with gr.Tabs():
+                        # Sub-tab: Synthesize Campaign
+                        with gr.Tab("🤖 Synthesize Campaign"):
+                            gr.Markdown("""
+                            ### Campaign Synthesis
+                            Select characters and automatically create a custom campaign tailored to your party!
+                            """)
+
+                            # Load character button
+                            load_characters_btn = gr.Button("🔄 Load Available Characters", variant="secondary")
+
+                            with gr.Row():
+                                with gr.Column():
+                                    synth_character_select = gr.CheckboxGroup(
+                                        choices=[],
+                                        label="Select Characters for Campaign",
+                                        info="Choose characters to include in your campaign"
+                                    )
+
+                                    synth_gm_name = gr.Textbox(
+                                        label="Game Master Name",
+                                        placeholder="Your name",
+                                        info="DM/GM running the campaign"
+                                    )
+
+                                    synth_notes = gr.Textbox(
+                                        label="Additional Notes (Optional)",
+                                        placeholder="Any specific themes, settings, or elements you'd like included...",
+                                        lines=4,
+                                        info="Guide the campaign creation process"
+                                    )
+
+                                    synthesize_btn = gr.Button("✨ Synthesize Campaign", variant="primary", size="lg")
+
+                                with gr.Column():
+                                    gr.Markdown("""
+                                    ### How It Works
+
+                                    1. **Load Characters**: Click "Load Available Characters" to see all your characters
+                                    2. **Select Party**: Check the boxes for characters you want in the campaign
+                                    3. **Add Context**: Optionally provide DM notes about themes or preferences
+                                    4. **Analyze Party**: The system analyzes:
+                                       - Character backstories and motivations
+                                       - Party composition and level
+                                       - Alignments and backgrounds
+                                       - Character personalities
+                                    5. **Campaign Created**: Get a fully-fledged campaign that:
+                                       - Ties into character backstories
+                                       - Provides appropriate challenges
+                                       - Creates opportunities for each character
+                                       - Includes factions, villains, and mysteries
+
+                                    **Example Party:**
+                                    - Thorin Ironforge (Dwarf Fighter, Level 3)
+                                    - Elara Moonwhisper (Elf Wizard, Level 3)
+                                    - Grimm Shadowstep (Halfling Rogue, Level 3)
+
+                                    The system will create a campaign that weaves their stories together!
+                                    """)
+
+                            synth_status = gr.Textbox(label="Campaign Details", lines=20)
+
+                            # Load characters button handler
+                            def update_character_choices():
+                                choices = self.get_character_choices_ui()
+                                if not choices:
+                                    return gr.update(choices=[], value=[])
+                                return gr.update(choices=choices, value=[])
+
+                            load_characters_btn.click(
+                                fn=update_character_choices,
+                                inputs=[],
+                                outputs=[synth_character_select]
+                            )
+
+                            synthesize_btn.click(
+                                fn=self.synthesize_campaign_ui,
+                                inputs=[synth_character_select, synth_gm_name, synth_notes],
+                                outputs=[synth_status]
+                            )
+
+                        # Sub-tab: Create Campaign
+                        with gr.Tab("Create Campaign"):
+                            gr.Markdown("### Create New Campaign")
+
+                            with gr.Row():
+                                with gr.Column():
+                                    campaign_name = gr.Textbox(
+                                        label="Campaign Name",
+                                        placeholder="The Shattered Crown",
+                                        info="Name of your campaign"
+                                    )
+
+                                    campaign_theme = gr.Dropdown(
+                                        choices=[theme.value for theme in CampaignTheme],
+                                        label="Campaign Theme",
+                                        value="High Fantasy",
+                                        info="Select the theme of your campaign"
+                                    )
+
+                                    campaign_gm = gr.Textbox(
+                                        label="Game Master Name",
+                                        placeholder="Your name",
+                                        info="DM/GM running the campaign"
+                                    )
+
+                                    campaign_party_size = gr.Slider(
+                                        minimum=1,
+                                        maximum=10,
+                                        value=4,
+                                        step=1,
+                                        label="Party Size",
+                                        info="Expected number of players"
+                                    )
+
+                                    campaign_level_range = gr.Textbox(
+                                        label="Level Range",
+                                        value="1-5",
+                                        placeholder="1-5",
+                                        info="Expected level range for the campaign"
+                                    )
+
+                                with gr.Column():
+                                    campaign_world = gr.Textbox(
+                                        label="World Name",
+                                        placeholder="Forgotten Realms",
+                                        info="Name of your world/realm"
+                                    )
+
+                                    campaign_starting = gr.Textbox(
+                                        label="Starting Location",
+                                        placeholder="Phandalin",
+                                        info="Where the adventure begins"
+                                    )
+
+                                    campaign_setting = gr.Textbox(
+                                        label="Setting Description",
+                                        placeholder="A war-torn kingdom...",
+                                        lines=3,
+                                        info="Describe the campaign setting"
+                                    )
+
+                                    campaign_summary = gr.Textbox(
+                                        label="Campaign Summary",
+                                        placeholder="The adventurers must...",
+                                        lines=3,
+                                        info="Brief campaign hook/summary"
+                                    )
+
+                                    campaign_conflict = gr.Textbox(
+                                        label="Main Conflict",
+                                        placeholder="A succession crisis threatens the kingdom",
+                                        lines=2,
+                                        info="Central conflict/tension"
+                                    )
+
+                            create_campaign_btn = gr.Button("⚔️ Create Campaign", variant="primary", size="lg")
+
+                            campaign_create_status = gr.Textbox(label="Status", lines=8)
+
+                            create_campaign_btn.click(
+                                fn=self.create_campaign_ui,
+                                inputs=[
+                                    campaign_name,
+                                    campaign_theme,
+                                    campaign_setting,
+                                    campaign_summary,
+                                    campaign_conflict,
+                                    campaign_gm,
+                                    campaign_world,
+                                    campaign_starting,
+                                    campaign_level_range,
+                                    campaign_party_size
+                                ],
+                                outputs=[campaign_create_status]
+                            )
+
+                        # Sub-tab: Manage Campaign
+                        with gr.Tab("Manage Campaign"):
+                            gr.Markdown("### Manage Campaign")
+
+                            manage_campaign_refresh_btn = gr.Button("🔄 Refresh Campaign List", variant="secondary")
+
+                            manage_campaign_dropdown = gr.Dropdown(
+                                choices=[],
+                                label="Select Campaign",
+                                info="Choose a campaign to view (type to search)",
+                                allow_custom_value=False,
+                                interactive=True
+                            )
+
+                            with gr.Row():
+                                load_campaign_btn = gr.Button("📂 Load Campaign", variant="primary")
+                                list_campaigns_btn = gr.Button("📋 List All Campaigns")
+
+                            gr.Markdown("---")
+
+                            with gr.Row():
+                                campaign_details = gr.Markdown(label="Campaign Details")
+                                campaign_status = gr.Textbox(label="Status", lines=6)
+
+                            # Refresh campaign dropdown
+                            def refresh_manage_campaign_dropdown():
+                                choices = self.get_campaign_dropdown_choices()
+                                return gr.update(choices=choices, value=None)
+
+                            manage_campaign_refresh_btn.click(
+                                fn=refresh_manage_campaign_dropdown,
+                                inputs=[],
+                                outputs=[manage_campaign_dropdown]
+                            )
+
+                            # Load campaign - convert dropdown label to ID
+                            def load_campaign_from_dropdown(label):
+                                campaign_id = self.get_campaign_id_from_label(label)
+                                return self.load_campaign_ui(campaign_id)
+
+                            load_campaign_btn.click(
+                                fn=load_campaign_from_dropdown,
+                                inputs=[manage_campaign_dropdown],
+                                outputs=[campaign_details, campaign_status]
+                            )
+
+                            list_campaigns_btn.click(
+                                fn=self.list_campaigns_ui,
+                                inputs=[],
+                                outputs=[campaign_details, campaign_status]
+                            )
+
+                        # Sub-tab: Add Characters
+                        with gr.Tab("Add Characters"):
+                            gr.Markdown("### Add Characters to Campaign")
+
+                            add_char_refresh_btn = gr.Button("🔄 Refresh Lists", variant="secondary")
+
+                            with gr.Row():
+                                add_char_campaign_dropdown = gr.Dropdown(
+                                    choices=[],
+                                    label="Select Campaign",
+                                    info="Choose the campaign to add characters to (type to search)",
+                                    allow_custom_value=False,
+                                    interactive=True
+                                )
+
+                                add_char_character_dropdown = gr.Dropdown(
+                                    choices=[],
+                                    label="Select Character",
+                                    info="Choose the character to add (type to search)",
+                                    allow_custom_value=False,
+                                    interactive=True
+                                )
+
+                            add_char_btn = gr.Button("➕ Add Character to Campaign", variant="primary")
+
+                            add_char_status = gr.Textbox(label="Status", lines=4)
+
+                            # Refresh both dropdowns
+                            def refresh_add_char_dropdowns():
+                                campaign_choices = self.get_campaign_dropdown_choices()
+                                character_choices = self.get_character_dropdown_choices()
+                                return (
+                                    gr.update(choices=campaign_choices, value=None),
+                                    gr.update(choices=character_choices, value=None)
+                                )
+
+                            add_char_refresh_btn.click(
+                                fn=refresh_add_char_dropdowns,
+                                inputs=[],
+                                outputs=[add_char_campaign_dropdown, add_char_character_dropdown]
+                            )
+
+                            # Add character - convert dropdown labels to IDs
+                            def add_char_from_dropdowns(campaign_label, character_label):
+                                campaign_id = self.get_campaign_id_from_label(campaign_label)
+                                character_id = self.get_character_id_from_label(character_label)
+                                return self.add_character_to_campaign_ui(campaign_id, character_id)
+
+                            add_char_btn.click(
+                                fn=add_char_from_dropdowns,
+                                inputs=[add_char_campaign_dropdown, add_char_character_dropdown],
+                                outputs=[add_char_status]
+                            )
+
+                            gr.Markdown("""
+                            **Tip:** Click "Refresh Lists" to load your campaigns and characters.
+                            """)
+
+                        # Sub-tab: Session Tracking
+                        with gr.Tab("Session Tracking"):
+                            gr.Markdown("### Track Campaign Sessions")
+
+                            session_refresh_btn = gr.Button("🔄 Refresh Campaign List", variant="secondary")
+
+                            session_campaign_dropdown = gr.Dropdown(
+                                choices=[],
+                                label="Select Campaign",
+                                info="Choose the campaign for session tracking (type to search)",
+                                allow_custom_value=False,
+                                interactive=True
+                            )
+
+                            start_session_btn = gr.Button("🎬 Start New Session", variant="primary")
+
+                            session_status = gr.Textbox(label="Status", lines=4)
+
+                            # Refresh session campaign dropdown
+                            def refresh_session_dropdown():
+                                choices = self.get_campaign_dropdown_choices()
+                                return gr.update(choices=choices, value=None)
+
+                            session_refresh_btn.click(
+                                fn=refresh_session_dropdown,
+                                inputs=[],
+                                outputs=[session_campaign_dropdown]
+                            )
+
+                            # Start session - convert dropdown label to ID
+                            def start_session_from_dropdown(label):
+                                campaign_id = self.get_campaign_id_from_label(label)
+                                return self.start_session_ui(campaign_id)
+
+                            start_session_btn.click(
+                                fn=start_session_from_dropdown,
+                                inputs=[session_campaign_dropdown],
+                                outputs=[session_status]
+                            )
+
+                            gr.Markdown("---")
+
+                            gr.Markdown("### 🤖 Auto-Generate Next Session")
+                            gr.Markdown("""
+                            **Autonomous Feature:** AI analyzes your campaign and automatically generates a complete session plan.
+
+                            This includes:
+                            - Opening scene narration
+                            - Key encounters (combat, social, exploration)
+                            - NPCs featured in the session
+                            - Locations to visit
+                            - Plot developments
+                            - Potential outcomes and rewards
+                            """)
+
+                            auto_session_refresh_btn = gr.Button("🔄 Refresh Campaign List", variant="secondary")
+
+                            auto_session_campaign_dropdown = gr.Dropdown(
+                                choices=[],
+                                label="Select Campaign",
+                                info="Choose campaign to generate next session for",
+                                allow_custom_value=False,
+                                interactive=True
+                            )
+
+                            auto_generate_session_btn = gr.Button("✨ Auto-Generate Next Session", variant="primary")
+
+                            auto_session_output = gr.Textbox(label="Generated Session Plan", lines=20)
+
+                            # Refresh auto-session campaign dropdown
+                            def refresh_auto_session_dropdown():
+                                choices = self.get_campaign_dropdown_choices()
+                                return gr.update(choices=choices, value=None)
+
+                            auto_session_refresh_btn.click(
+                                fn=refresh_auto_session_dropdown,
+                                inputs=[],
+                                outputs=[auto_session_campaign_dropdown]
+                            )
+
+                            # Auto-generate session
+                            def auto_generate_session_from_dropdown(label):
+                                campaign_id = self.get_campaign_id_from_label(label)
+                                return self.auto_generate_session_ui(campaign_id)
+
+                            auto_generate_session_btn.click(
+                                fn=auto_generate_session_from_dropdown,
+                                inputs=[auto_session_campaign_dropdown],
+                                outputs=[auto_session_output]
+                            )
+
+                            gr.Markdown("---")
+
+                            gr.Markdown("### Add Session Event")
+
+                            event_refresh_btn = gr.Button("🔄 Refresh Campaign List", variant="secondary")
+
+                            event_campaign_dropdown = gr.Dropdown(
+                                choices=[],
+                                label="Select Campaign",
+                                info="Choose the campaign to add event to (type to search)",
+                                allow_custom_value=False,
+                                interactive=True
+                            )
+
+                            event_type = gr.Dropdown(
+                                choices=["Combat", "Social", "Exploration", "Discovery", "Plot Development", "Character Moment", "NPC Interaction", "Quest Update"],
+                                label="Event Type",
+                                value="Combat",
+                                info="Type of event"
+                            )
+
+                            event_title = gr.Textbox(
+                                label="Event Title",
+                                placeholder="Battle at the Bridge",
+                                info="Short title for the event"
+                            )
+
+                            event_description = gr.Textbox(
+                                label="Event Description",
+                                placeholder="The party encountered a group of bandits...",
+                                lines=4,
+                                info="Detailed description of what happened"
+                            )
+
+                            event_importance = gr.Slider(
+                                minimum=1,
+                                maximum=5,
+                                value=3,
+                                step=1,
+                                label="Importance",
+                                info="How important is this event? (1-5 stars)"
+                            )
+
+                            add_event_btn = gr.Button("📝 Add Event", variant="primary")
+
+                            event_status = gr.Textbox(label="Status", lines=6)
+
+                            # Refresh event campaign dropdown
+                            def refresh_event_dropdown():
+                                choices = self.get_campaign_dropdown_choices()
+                                return gr.update(choices=choices, value=None)
+
+                            event_refresh_btn.click(
+                                fn=refresh_event_dropdown,
+                                inputs=[],
+                                outputs=[event_campaign_dropdown]
+                            )
+
+                            # Add event - convert dropdown label to ID
+                            def add_event_from_dropdown(campaign_label, event_type_val, title, description, importance):
+                                campaign_id = self.get_campaign_id_from_label(campaign_label)
+                                return self.add_event_ui(campaign_id, event_type_val, title, description, importance)
+
+                            add_event_btn.click(
+                                fn=add_event_from_dropdown,
+                                inputs=[
+                                    event_campaign_dropdown,
+                                    event_type,
+                                    event_title,
+                                    event_description,
+                                    event_importance
+                                ],
+                                outputs=[event_status]
+                            )
+
+                # Tab 7: About
+                with gr.Tab("About"):
+                    gr.Markdown("""
+                    ## About D'n'D Campaign Manager
+
+                    **Version:** 2.0.0
+                    **Built for:** Gradio + Anthropic MCP Hackathon
+
+                    ### Features
+                    - 🎲 Complete D&D 5e character creation
+                    - 📖 Automated name and backstory generation
+                    - 🎨 Character portrait generation (DALL-E 3 / HuggingFace SDXL)
+                    - 📊 Multiple ability score methods (Standard Array, Roll, Point Buy)
+                    - 💾 Database persistence
+                    - 📄 Markdown character sheet export
+                    - ✅ Full data validation
+
+                    ### Stat Methods
+                    - **Standard Array:** 15, 14, 13, 12, 10, 8 (balanced)
+                    - **Roll:** 4d6 drop lowest (random)
+                    - **Point Buy:** 27 points (customizable)
+
+                    ### Supported Races
+                    Human, Elf, Dwarf, Halfling, Dragonborn, Gnome, Half-Elf, Half-Orc, Tiefling
+
+                    ### Supported Classes
+                    Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, Wizard
+
+                    ### Tech Stack
+                    - **AI:** Anthropic Claude / Google Gemini / OpenAI DALL-E 3
+                    - **Framework:** Gradio
+                    - **Database:** SQLite
+                    - **Validation:** Pydantic
+
+                    ---
+
+                    *Built with ❤️ for the TTRPG community*
+                    """)
+
+            gr.Markdown("""
+            ---
+            ### Tips
+            - Enable "Use AI" options for more creative and detailed characters
+            - Use Standard Array for balanced characters
+            - Use Roll for random variation
+            - Save your character ID to load it later
+            - Check the character list to find previously created characters
+            """)
+
+            # Auto-populate dropdowns on interface load
+            def populate_all_dropdowns():
+                """Populate all dropdowns when interface loads"""
+                campaign_choices = self.get_campaign_dropdown_choices()
+                character_choices = self.get_character_dropdown_choices()
+
+                return [
+                    gr.update(choices=character_choices),  # character_dropdown
+                    gr.update(choices=character_choices),  # delete_character_dropdown
+                    gr.update(choices=character_choices),  # portrait_character_dropdown
+                    gr.update(choices=character_choices),  # export_character_dropdown
+                    gr.update(choices=campaign_choices),   # manage_campaign_dropdown
+                    gr.update(choices=campaign_choices),   # add_char_campaign_dropdown
+                    gr.update(choices=character_choices),  # add_char_character_dropdown
+                    gr.update(choices=campaign_choices),   # session_campaign_dropdown
+                    gr.update(choices=campaign_choices),   # auto_session_campaign_dropdown
+                    gr.update(choices=campaign_choices),   # event_campaign_dropdown
+                ]
+
+            interface.load(
+                fn=populate_all_dropdowns,
+                inputs=[],
+                outputs=[
+                    character_dropdown,
+                    delete_character_dropdown,
+                    portrait_character_dropdown,
+                    export_character_dropdown,
+                    manage_campaign_dropdown,
+                    add_char_campaign_dropdown,
+                    add_char_character_dropdown,
+                    session_campaign_dropdown,
+                    auto_session_campaign_dropdown,
+                    event_campaign_dropdown,
+                ]
+            )
+
+        return interface
+
+
+def launch_ui():
+    """Launch the Gradio interface"""
+    ui = CharacterCreatorUI()
+    interface = ui.create_interface()
+
+    interface.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True
+    )
+
+
+if __name__ == "__main__":
+    launch_ui()

src/ui/components/__init__.py

@@ -0,0 +1,7 @@
+"""
+Reusable UI components for D'n'D Campaign Manager
+"""
+
+from .dropdown_manager import DropdownManager
+
+__all__ = ["DropdownManager"]

src/ui/components/dropdown_manager.py

@@ -0,0 +1,120 @@
+"""
+Dropdown Manager for D'n'D Campaign Manager
+Handles dropdown creation and auto-population logic
+"""
+
+import gradio as gr
+from typing import List, Tuple, Optional
+from src.agents.character_agent import CharacterAgent
+from src.agents.campaign_agent import CampaignAgent
+
+
+class DropdownManager:
+    """Manages dropdowns and their auto-population"""
+
+    def __init__(self, character_agent: CharacterAgent, campaign_agent: CampaignAgent):
+        self.character_agent = character_agent
+        self.campaign_agent = campaign_agent
+
+    def get_character_dropdown_choices(self) -> List[str]:
+        """Get character choices for dropdown (returns labels)"""
+        try:
+            characters = self.character_agent.list_characters()
+            if not characters:
+                return []
+
+            # Create dropdown choices with nice labels
+            choices = []
+            for char in characters:
+                label = f"{char.name} ({char.race.value} {char.character_class.value}, Lvl {char.level})"
+                choices.append(label)
+
+            return choices
+        except Exception as e:
+            return []
+
+    def get_character_choices_for_checkboxgroup(self) -> List[Tuple[str, str]]:
+        """Get list of characters for checkbox selection (label, value pairs)"""
+        try:
+            characters = self.character_agent.list_characters()
+            if not characters:
+                return []
+
+            # Create choices as "Name (Race Class, Level X)" -> ID
+            choices = []
+            for char in characters:
+                label = f"{char.name} ({char.race.value} {char.character_class.value}, Level {char.level})"
+                choices.append((label, char.id))
+
+            return choices
+        except Exception as e:
+            return []
+
+    def get_character_id_from_label(self, label: str) -> str:
+        """Extract character ID from dropdown label"""
+        try:
+            # Parse the label to get character name
+            if not label:
+                return ""
+
+            name = label.split(" (")[0] if " (" in label else label
+
+            # Find character by name
+            characters = self.character_agent.list_characters()
+            for char in characters:
+                if char.name == name:
+                    return char.id
+
+            return ""
+        except Exception as e:
+            return ""
+
+    def get_campaign_dropdown_choices(self) -> List[str]:
+        """Get campaign choices for dropdown"""
+        try:
+            campaigns = self.campaign_agent.list_campaigns()
+            if not campaigns:
+                return []
+
+            choices = []
+            for campaign in campaigns:
+                label = f"{campaign.name} ({campaign.theme.value}, Session {campaign.current_session})"
+                choices.append(label)
+
+            return choices
+        except Exception as e:
+            return []
+
+    def get_campaign_id_from_label(self, label: str) -> str:
+        """Extract campaign ID from dropdown label"""
+        try:
+            if not label:
+                return ""
+
+            name = label.split(" (")[0] if " (" in label else label
+
+            campaigns = self.campaign_agent.list_campaigns()
+            for campaign in campaigns:
+                if campaign.name == name:
+                    return campaign.id
+
+            return ""
+        except Exception as e:
+            return ""
+
+    def refresh_character_dropdown(self) -> gr.update:
+        """Refresh character dropdown choices"""
+        choices = self.get_character_dropdown_choices()
+        return gr.update(choices=choices, value=None)
+
+    def refresh_campaign_dropdown(self) -> gr.update:
+        """Refresh campaign dropdown choices"""
+        choices = self.get_campaign_dropdown_choices()
+        return gr.update(choices=choices, value=None)
+
+    def refresh_character_checkboxgroup(self) -> gr.update:
+        """Refresh character checkbox group choices"""
+        choices = self.get_character_choices_for_checkboxgroup()
+        if not choices:
+            return gr.update(choices=[], value=[])
+        return gr.update(choices=choices, value=[])

src/ui/tabs/__init__.py

@@ -0,0 +1,29 @@
+"""
+Tab modules for D'n'D Campaign Manager UI
+"""
+
+from .about_tab import AboutTab
+from .character_create_tab import CharacterCreateTab
+from .character_load_tab import CharacterLoadTab
+from .character_manage_tab import CharacterManageTab
+from .character_portrait_tab import CharacterPortraitTab
+from .character_export_tab import CharacterExportTab
+from .campaign_create_tab import CampaignCreateTab
+from .campaign_manage_tab import CampaignManageTab
+from .campaign_add_chars_tab import CampaignAddCharsTab
+from .campaign_synthesize_tab import CampaignSynthesizeTab
+from .session_tracking_tab import SessionTrackingTab
+
+__all__ = [
+    "AboutTab",
+    "CharacterCreateTab",
+    "CharacterLoadTab",
+    "CharacterManageTab",
+    "CharacterPortraitTab",
+    "CharacterExportTab",
+    "CampaignCreateTab",
+    "CampaignManageTab",
+    "CampaignAddCharsTab",
+    "CampaignSynthesizeTab",
+    "SessionTrackingTab",
+]

src/ui/tabs/about_tab.py

@@ -0,0 +1,52 @@
+"""
+About Tab for D'n'D Campaign Manager
+"""
+
+import gradio as gr
+
+
+class AboutTab:
+    """About tab displaying application information"""
+
+    def __init__(self):
+        pass
+
+    def create(self) -> None:
+        """Create and return the About tab component"""
+        with gr.Tab("About"):
+            gr.Markdown("""
+            ## About D'n'D Campaign Manager
+
+            **Version:** 2.0.0
+            **Built for:** Gradio + Anthropic MCP Hackathon
+
+            ### Features
+            - 🎲 Complete D&D 5e character creation
+            - 📖 Automated name and backstory generation
+            - 🎨 Character portrait generation (DALL-E 3 / HuggingFace SDXL)
+            - 📊 Multiple ability score methods (Standard Array, Roll, Point Buy)
+            - 💾 Database persistence
+            - 📄 Markdown character sheet export
+            - ✅ Full data validation
+
+            ### Stat Methods
+            - **Standard Array:** 15, 14, 13, 12, 10, 8 (balanced)
+            - **Roll:** 4d6 drop lowest (random)
+            - **Point Buy:** 27 points (customizable)
+
+            ### Supported Races
+            Human, Elf, Dwarf, Halfling, Dragonborn, Gnome, Half-Elf, Half-Orc, Tiefling
+
+            ### Supported Classes
+            Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, Wizard
+
+            ### Tech Stack
+            - **AI:** Anthropic Claude / Google Gemini / OpenAI DALL-E 3
+            - **Framework:** Gradio
+            - **Database:** SQLite
+            - **Validation:** Pydantic
+
+            ---
+
+            *Built with ❤️ for the TTRPG community*
+            """)

src/ui/tabs/campaign_add_chars_tab.py

@@ -0,0 +1,106 @@
+"""
+Campaign Add Characters Tab for D'n'D Campaign Manager
+"""
+
+import gradio as gr
+from src.agents.character_agent import CharacterAgent
+from src.agents.campaign_agent import CampaignAgent
+from src.ui.components.dropdown_manager import DropdownManager
+
+
+class CampaignAddCharsTab:
+    """Add Characters to Campaign tab"""
+
+    def __init__(
+        self,
+        character_agent: CharacterAgent,
+        campaign_agent: CampaignAgent,
+        dropdown_manager: DropdownManager
+    ):
+        self.character_agent = character_agent
+        self.campaign_agent = campaign_agent
+        self.dropdown_manager = dropdown_manager
+
+    def add_character_to_campaign_ui(self, campaign_id: str, character_id: str) -> str:
+        """Add a character to a campaign"""
+        try:
+            if not campaign_id.strip() or not character_id.strip():
+                return "❌ Error: Please provide both campaign ID and character ID"
+
+            # Verify character exists
+            character = self.character_agent.load_character(character_id)
+            if not character:
+                return f"❌ Character not found: {character_id}"
+
+            # Add to campaign
+            success = self.campaign_agent.add_character_to_campaign(campaign_id, character_id)
+
+            if success:
+                return f"✅ Added {character.name} to campaign!"
+            else:
+                return f"❌ Campaign not found: {campaign_id}"
+
+        except Exception as e:
+            return f"❌ Error: {str(e)}"
+
+    def create(self) -> tuple:
+        """Create and return the Add Characters to Campaign tab component"""
+        with gr.Tab("Add Characters"):
+            gr.Markdown("### Add Characters to Campaign")
+
+            add_char_refresh_btn = gr.Button("🔄 Refresh Lists", variant="secondary")
+
+            with gr.Row():
+                add_char_campaign_dropdown = gr.Dropdown(
+                    choices=[],
+                    label="Select Campaign",
+                    info="Choose the campaign to add characters to (type to search)",
+                    allow_custom_value=False,
+                    interactive=True
+                )
+
+                add_char_character_dropdown = gr.Dropdown(
+                    choices=[],
+                    label="Select Character",
+                    info="Choose the character to add (type to search)",
+                    allow_custom_value=False,
+                    interactive=True
+                )
+
+            add_char_btn = gr.Button("➕ Add Character to Campaign", variant="primary")
+
+            add_char_status = gr.Textbox(label="Status", lines=4)
+
+            # Refresh both dropdowns
+            def refresh_add_char_dropdowns():
+                campaign_choices = self.dropdown_manager.get_campaign_dropdown_choices()
+                character_choices = self.dropdown_manager.get_character_dropdown_choices()
+                return (
+                    gr.update(choices=campaign_choices, value=None),
+                    gr.update(choices=character_choices, value=None)
+                )
+
+            add_char_refresh_btn.click(
+                fn=refresh_add_char_dropdowns,
+                inputs=[],
+                outputs=[add_char_campaign_dropdown, add_char_character_dropdown]
+            )
+
+            # Add character - convert dropdown labels to IDs
+            def add_char_from_dropdowns(campaign_label, character_label):
+                campaign_id = self.dropdown_manager.get_campaign_id_from_label(campaign_label)
+                character_id = self.dropdown_manager.get_character_id_from_label(character_label)
+                return self.add_character_to_campaign_ui(campaign_id, character_id)
+
+            add_char_btn.click(
+                fn=add_char_from_dropdowns,
+                inputs=[add_char_campaign_dropdown, add_char_character_dropdown],
+                outputs=[add_char_status]
+            )
+
+            gr.Markdown("""
+            **Tip:** Click "Refresh Lists" to load your campaigns and characters.
+            """)
+
+        # Return both dropdowns for auto-population
+        return add_char_campaign_dropdown, add_char_character_dropdown

src/ui/tabs/campaign_create_tab.py

@@ -0,0 +1,156 @@
+"""
+Campaign Create Tab for D'n'D Campaign Manager
+"""
+
+import gradio as gr
+import traceback
+from src.agents.campaign_agent import CampaignAgent
+from src.models.campaign import CampaignTheme
+
+
+class CampaignCreateTab:
+    """Create Campaign tab for creating new campaigns"""
+
+    def __init__(self, campaign_agent: CampaignAgent):
+        self.campaign_agent = campaign_agent
+
+    def create_campaign_ui(
+        self,
+        name: str,
+        theme: str,
+        setting: str,
+        summary: str,
+        main_conflict: str,
+        game_master: str,
+        world_name: str,
+        starting_location: str,
+        level_range: str,
+        party_size: int
+    ) -> str:
+        """Create a new campaign"""
+        try:
+            if not name.strip():
+                return "❌ Error: Please provide a campaign name"
+
+            campaign = self.campaign_agent.create_campaign(
+                name=name,
+                theme=theme,
+                setting=setting,
+                summary=summary,
+                main_conflict=main_conflict,
+                game_master=game_master,
+                world_name=world_name,
+                starting_location=starting_location,
+                level_range=level_range,
+                party_size=party_size
+            )
+
+            return f"""✅ Campaign Created Successfully!
+
+**ID:** {campaign.id}
+**Name:** {campaign.name}
+**Theme:** {campaign.theme.value}
+**Setting:** {campaign.setting}
+
+Campaign has been saved to database.
+Use the campaign ID to manage characters and sessions."""
+
+        except Exception as e:
+            return f"❌ Error creating campaign:\n\n{str(e)}\n\n{traceback.format_exc()}"
+
+    def create(self) -> None:
+        """Create and return the Create Campaign tab component"""
+        with gr.Tab("Create Campaign"):
+            gr.Markdown("### Create New Campaign")
+
+            with gr.Row():
+                with gr.Column():
+                    campaign_name = gr.Textbox(
+                        label="Campaign Name",
+                        placeholder="The Shattered Crown",
+                        info="Name of your campaign"
+                    )
+
+                    campaign_theme = gr.Dropdown(
+                        choices=[theme.value for theme in CampaignTheme],
+                        label="Campaign Theme",
+                        value="High Fantasy",
+                        info="Select the theme of your campaign"
+                    )
+
+                    campaign_gm = gr.Textbox(
+                        label="Game Master Name",
+                        placeholder="Your name",
+                        info="DM/GM running the campaign"
+                    )
+
+                    campaign_party_size = gr.Slider(
+                        minimum=1,
+                        maximum=10,
+                        value=4,
+                        step=1,
+                        label="Party Size",
+                        info="Expected number of players"
+                    )
+
+                    campaign_level_range = gr.Textbox(
+                        label="Level Range",
+                        value="1-5",
+                        placeholder="1-5",
+                        info="Expected level range for the campaign"
+                    )
+
+                with gr.Column():
+                    campaign_world = gr.Textbox(
+                        label="World Name",
+                        placeholder="Forgotten Realms",
+                        info="Name of your world/realm"
+                    )
+
+                    campaign_starting = gr.Textbox(
+                        label="Starting Location",
+                        placeholder="Phandalin",
+                        info="Where the adventure begins"
+                    )
+
+                    campaign_setting = gr.Textbox(
+                        label="Setting Description",
+                        placeholder="A war-torn kingdom...",
+                        lines=3,
+                        info="Describe the campaign setting"
+                    )
+
+                    campaign_summary = gr.Textbox(
+                        label="Campaign Summary",
+                        placeholder="The adventurers must...",
+                        lines=3,
+                        info="Brief campaign hook/summary"
+                    )
+
+                    campaign_conflict = gr.Textbox(
+                        label="Main Conflict",
+                        placeholder="A succession crisis threatens the kingdom",
+                        lines=2,
+                        info="Central conflict/tension"
+                    )
+
+            create_campaign_btn = gr.Button("⚔️ Create Campaign", variant="primary", size="lg")
+
+            campaign_create_status = gr.Textbox(label="Status", lines=8)
+
+            create_campaign_btn.click(
+                fn=self.create_campaign_ui,
+                inputs=[
+                    campaign_name,
+                    campaign_theme,
+                    campaign_setting,
+                    campaign_summary,
+                    campaign_conflict,
+                    campaign_gm,
+                    campaign_world,
+                    campaign_starting,
+                    campaign_level_range,
+                    campaign_party_size
+                ],
+                outputs=[campaign_create_status]
+            )

src/ui/tabs/campaign_manage_tab.py

@@ -0,0 +1,155 @@
+"""
+Campaign Manage Tab for D'n'D Campaign Manager
+"""
+
+import gradio as gr
+from typing import Tuple
+from src.agents.campaign_agent import CampaignAgent
+from src.ui.components.dropdown_manager import DropdownManager
+
+
+class CampaignManageTab:
+    """Manage Campaign tab for viewing and managing campaigns"""
+
+    def __init__(self, campaign_agent: CampaignAgent, dropdown_manager: DropdownManager):
+        self.campaign_agent = campaign_agent
+        self.dropdown_manager = dropdown_manager
+
+    def list_campaigns_ui(self, active_only: bool = False) -> Tuple[str, str]:
+        """List all campaigns"""
+        try:
+            campaigns = self.campaign_agent.list_campaigns(active_only=active_only)
+
+            if not campaigns:
+                return "", "No campaigns found in database."
+
+            # Create table
+            markdown = "# Campaigns\n\n"
+            markdown += "| Name | Theme | Session | Status | ID |\n"
+            markdown += "|------|-------|---------|--------|----|\n"
+
+            for campaign in campaigns[-20:]:  # Last 20 campaigns
+                status = "Active" if campaign.is_active else "Inactive"
+                markdown += f"| {campaign.name} | {campaign.theme.value} | {campaign.current_session} | {status} | `{campaign.id}` |\n"
+
+            status = f"✅ Found {len(campaigns)} campaign(s)"
+            return markdown, status
+
+        except Exception as e:
+            return "", f"❌ Error listing campaigns: {e}"
+
+    def load_campaign_ui(self, campaign_id: str) -> Tuple[str, str]:
+        """Load campaign details"""
+        try:
+            if not campaign_id.strip():
+                return "", "❌ Error: Please provide a campaign ID"
+
+            campaign = self.campaign_agent.load_campaign(campaign_id)
+
+            if campaign:
+                markdown = campaign.to_markdown()
+                status = f"✅ Loaded campaign: {campaign.name}"
+                return markdown, status
+            else:
+                return "", f"❌ Campaign not found: {campaign_id}"
+
+        except Exception as e:
+            return "", f"❌ Error loading campaign: {e}"
+
+    def delete_campaign_ui(self, campaign_id: str) -> str:
+        """Delete a campaign"""
+        try:
+            if not campaign_id.strip():
+                return "❌ Error: Please select a campaign to delete"
+
+            # Load campaign first to get name
+            campaign = self.campaign_agent.load_campaign(campaign_id)
+            if not campaign:
+                return f"❌ Campaign not found: {campaign_id}"
+
+            campaign_name = campaign.name
+
+            # Delete the campaign
+            success = self.campaign_agent.delete_campaign(campaign_id)
+
+            if success:
+                return f"""✅ **Campaign deleted successfully!**
+
+**Campaign:** {campaign_name}
+**ID:** {campaign_id}
+
+The campaign and all associated data (events, session notes) have been permanently removed.
+
+💡 **Tip:** Refresh the campaign list to see updated campaigns."""
+            else:
+                return f"❌ Failed to delete campaign: {campaign_id}"
+
+        except Exception as e:
+            return f"❌ Error deleting campaign: {str(e)}"
+
+    def create(self) -> gr.Dropdown:
+        """Create and return the Manage Campaign tab component"""
+        with gr.Tab("Manage Campaign"):
+            gr.Markdown("### Manage Campaign")
+
+            manage_campaign_refresh_btn = gr.Button("🔄 Refresh Campaign List", variant="secondary")
+
+            manage_campaign_dropdown = gr.Dropdown(
+                choices=[],
+                label="Select Campaign",
+                info="Choose a campaign to view (type to search)",
+                allow_custom_value=False,
+                interactive=True
+            )
+
+            with gr.Row():
+                load_campaign_btn = gr.Button("📂 Load Campaign", variant="primary")
+                list_campaigns_btn = gr.Button("📋 List All Campaigns")
+                delete_campaign_btn = gr.Button("🗑️ Delete Campaign", variant="stop")
+
+            gr.Markdown("---")
+
+            with gr.Row():
+                campaign_details = gr.Markdown(label="Campaign Details")
+                campaign_status = gr.Textbox(label="Status", lines=6)
+
+            # Refresh campaign dropdown
+            manage_campaign_refresh_btn.click(
+                fn=self.dropdown_manager.refresh_campaign_dropdown,
+                inputs=[],
+                outputs=[manage_campaign_dropdown]
+            )
+
+            # Load campaign - convert dropdown label to ID
+            def load_campaign_from_dropdown(label):
+                campaign_id = self.dropdown_manager.get_campaign_id_from_label(label)
+                return self.load_campaign_ui(campaign_id)
+
+            load_campaign_btn.click(
+                fn=load_campaign_from_dropdown,
+                inputs=[manage_campaign_dropdown],
+                outputs=[campaign_details, campaign_status]
+            )
+
+            list_campaigns_btn.click(
+                fn=self.list_campaigns_ui,
+                inputs=[],
+                outputs=[campaign_details, campaign_status]
+            )
+
+            # Delete campaign - convert dropdown label to ID and refresh list
+            def delete_campaign_from_dropdown(label):
+                campaign_id = self.dropdown_manager.get_campaign_id_from_label(label)
+                status = self.delete_campaign_ui(campaign_id)
+                # Refresh dropdown choices after deletion
+                updated_choices = self.dropdown_manager.refresh_campaign_dropdown()
+                return status, updated_choices
+
+            delete_campaign_btn.click(
+                fn=delete_campaign_from_dropdown,
+                inputs=[manage_campaign_dropdown],
+                outputs=[campaign_status, manage_campaign_dropdown]
+            )
+
+        # Return the dropdown for auto-population
+        return manage_campaign_dropdown

src/ui/tabs/campaign_synthesize_tab.py

@@ -0,0 +1,197 @@
+"""
+Campaign Synthesize Tab for D'n'D Campaign Manager
+"""
+
+import gradio as gr
+import traceback
+from src.agents.character_agent import CharacterAgent
+from src.agents.campaign_agent import CampaignAgent
+from src.ui.components.dropdown_manager import DropdownManager
+
+
+class CampaignSynthesizeTab:
+    """Synthesize Campaign tab for AI-powered campaign generation from characters"""
+
+    def __init__(
+        self,
+        character_agent: CharacterAgent,
+        campaign_agent: CampaignAgent,
+        dropdown_manager: DropdownManager
+    ):
+        self.character_agent = character_agent
+        self.campaign_agent = campaign_agent
+        self.dropdown_manager = dropdown_manager
+
+    def synthesize_campaign_ui(
+        self,
+        selected_character_ids: list,
+        game_master: str,
+        additional_notes: str
+    ) -> str:
+        """Synthesize a campaign from selected characters"""
+        try:
+            # Check if any characters selected
+            if not selected_character_ids:
+                return "❌ Error: Please select at least one character"
+
+            # Load all characters
+            characters = []
+            for char_id in selected_character_ids:
+                char = self.character_agent.load_character(char_id)
+                if char:
+                    characters.append(char)
+
+            if not characters:
+                return "❌ Error: No valid characters found"
+
+            # Synthesize campaign
+            campaign = self.campaign_agent.synthesize_campaign_from_characters(
+                characters=characters,
+                game_master=game_master,
+                additional_notes=additional_notes
+            )
+
+            # Create response with character list
+            char_list = "\n".join([f"- {char.name} (Level {char.level} {char.race.value} {char.character_class.value})" for char in characters])
+
+            # Build comprehensive output with all campaign details
+            output = [f"""✅ Campaign Synthesized Successfully!
+
+**Campaign ID:** {campaign.id}
+**Campaign Name:** {campaign.name}
+**Theme:** {campaign.theme.value}
+**World:** {campaign.world_name}
+**Starting Location:** {campaign.starting_location}
+
+**Party Members ({len(characters)}):**
+{char_list}
+
+**Level Range:** {campaign.level_range}
+
+---
+
+## Campaign Overview
+
+**Summary:**
+{campaign.summary}
+
+**Main Conflict:**
+{campaign.main_conflict}
+
+**Current Story Arc:**
+{campaign.current_arc if campaign.current_arc else "See detailed notes below"}
+"""]
+
+            # Add factions if present
+            if campaign.key_factions:
+                output.append("\n## Key Factions\n")
+                for faction in campaign.key_factions:
+                    output.append(f"- {faction}\n")
+
+            # Add villains if present
+            if campaign.major_villains:
+                output.append("\n## Major Villains\n")
+                for villain in campaign.major_villains:
+                    output.append(f"- {villain}\n")
+
+            # Add mysteries if present
+            if campaign.central_mysteries:
+                output.append("\n## Central Mysteries\n")
+                for mystery in campaign.central_mysteries:
+                    output.append(f"- {mystery}\n")
+
+            # Add detailed campaign notes (includes character connections, hooks, sessions, NPCs, locations)
+            if campaign.notes:
+                output.append("\n---\n\n")
+                output.append(campaign.notes)
+
+            output.append(f"""
+
+---
+
+✅ **Campaign Created!** All characters have been added to the campaign.
+
+💡 **Next Steps:**
+- View full details in the "Manage Campaign" tab
+- Start your first session in "Session Tracking"
+- Add campaign events as your story unfolds""")
+
+            return "".join(output)
+
+        except Exception as e:
+            return f"❌ Error synthesizing campaign:\n\n{str(e)}\n\n{traceback.format_exc()}"
+
+    def create(self) -> None:
+        """Create and return the Synthesize Campaign tab component"""
+        with gr.Tab("🤖 Synthesize Campaign"):
+            gr.Markdown("""
+            ### Campaign Synthesis
+            Select characters and automatically create a custom campaign tailored to your party!
+            """)
+
+            # Load character button
+            load_characters_btn = gr.Button("🔄 Load Available Characters", variant="secondary")
+
+            with gr.Row():
+                with gr.Column():
+                    synth_character_select = gr.CheckboxGroup(
+                        choices=[],
+                        label="Select Characters for Campaign",
+                        info="Choose characters to include in your campaign"
+                    )
+
+                    synth_gm_name = gr.Textbox(
+                        label="Game Master Name",
+                        placeholder="Your name",
+                        info="DM/GM running the campaign"
+                    )
+
+                    synth_notes = gr.Textbox(
+                        label="Additional Notes (Optional)",
+                        placeholder="Any specific themes, settings, or elements you'd like included...",
+                        lines=4,
+                        info="Guide the campaign creation process"
+                    )
+
+                    synthesize_btn = gr.Button("✨ Synthesize Campaign", variant="primary", size="lg")
+
+                with gr.Column():
+                    gr.Markdown("""
+                    ### How It Works
+
+                    1. **Load Characters**: Click "Load Available Characters" to see all your characters
+                    2. **Select Party**: Check the boxes for characters you want in the campaign
+                    3. **Add Context**: Optionally provide DM notes about themes or preferences
+                    4. **Analyze Party**: The system analyzes:
+                       - Character backstories and motivations
+                       - Party composition and level
+                       - Alignments and backgrounds
+                       - Character personalities
+                    5. **Campaign Created**: Get a fully-fledged campaign that:
+                       - Ties into character backstories
+                       - Provides appropriate challenges
+                       - Creates opportunities for each character
+                       - Includes factions, villains, and mysteries
+
+                    **Example Party:**
+                    - Thorin Ironforge (Dwarf Fighter, Level 3)
+                    - Elara Moonwhisper (Elf Wizard, Level 3)
+                    - Grimm Shadowstep (Halfling Rogue, Level 3)
+
+                    The system will create a campaign that weaves their stories together!
+                    """)
+
+            synth_status = gr.Textbox(label="Campaign Details", lines=20)
+
+            # Load characters button handler
+            load_characters_btn.click(
+                fn=self.dropdown_manager.refresh_character_checkboxgroup,
+                inputs=[],
+                outputs=[synth_character_select]
+            )
+
+            synthesize_btn.click(
+                fn=self.synthesize_campaign_ui,
+                inputs=[synth_character_select, synth_gm_name, synth_notes],
+                outputs=[synth_status]
+            )

src/ui/tabs/character_create_tab.py

@@ -0,0 +1,348 @@
+"""
+Character Create Tab for D'n'D Campaign Manager
+"""
+
+import gradio as gr
+from typing import Tuple
+import traceback
+from src.agents.character_agent import CharacterAgent
+from src.models.character import DnDRace, DnDClass, Alignment
+from src.utils.validators import get_available_races, get_available_classes
+from src.utils.image_generator import RACE_SKIN_TONES
+
+
+class CharacterCreateTab:
+    """Create Character tab for D&D character creation"""
+
+    def __init__(self, character_agent: CharacterAgent):
+        self.character_agent = character_agent
+
+    def _get_alignment_description(self, alignment: str) -> str:
+        """Get personality guidance based on alignment"""
+        descriptions = {
+            "Lawful Good": "a strong sense of justice, honor, and desire to help others within the rules",
+            "Neutral Good": "genuine kindness and desire to help, but flexibility in how they achieve good",
+            "Chaotic Good": "rebellious goodness, fighting for freedom and helping others by breaking unjust rules",
+            "Lawful Neutral": "strict adherence to law, order, and tradition above good or evil",
+            "True Neutral": "balance and pragmatism, avoiding extreme positions",
+            "Chaotic Neutral": "unpredictability, freedom-loving nature, and self-interest",
+            "Lawful Evil": "tyrannical control, following their own code while causing harm",
+            "Neutral Evil": "pure self-interest and willingness to harm others for personal gain",
+            "Chaotic Evil": "destructive chaos, cruelty, and disregard for any rules or others' wellbeing"
+        }
+        return descriptions.get(alignment, "their moral compass")
+
+    def generate_name_ui(
+        self,
+        race: str,
+        character_class: str,
+        gender: str,
+        alignment: str,
+    ) -> str:
+        """
+        Generate a character name using AI
+        Alignment can influence name generation (e.g., darker names for evil characters)
+        """
+        try:
+            race_enum = DnDRace(race)
+            class_enum = DnDClass(character_class)
+
+            # Add alignment hint to the generation prompt
+            alignment_hint = None
+            if "Evil" in alignment:
+                alignment_hint = "with a darker, more menacing tone"
+            elif "Good" in alignment:
+                alignment_hint = "with a heroic, noble tone"
+            elif alignment == "Chaotic Neutral":
+                alignment_hint = "with a wild, unpredictable feel"
+
+            # Build custom prompt if we have alignment influence
+            if alignment_hint:
+                prompt = f"""Generate a single fantasy character name for a D&D character.
+
+Race: {race_enum.value}
+Class: {class_enum.value}
+Gender: {gender if gender != "Not specified" else "any"}
+Alignment: {alignment} - name should reflect this {alignment_hint}
+
+Requirements:
+- Just the name, nothing else
+- Make it sound appropriate for the race, gender, and alignment
+- {alignment_hint}
+- Make it memorable and fitting for an adventurer
+- 2-3 words maximum
+
+Examples:
+- Evil: "Malakai Shadowbane", "Drusilla Nightwhisper"
+- Good: "Elara Lightbringer", "Theron Brightheart"
+- Chaotic: "Raven Wildfire", "Zephyr Stormblade"
+
+Generate only the name:"""
+
+                name = self.character_agent.ai_client.generate_creative(prompt).strip()
+                name = name.split('\n')[0].strip('"\'')
+                return name
+            else:
+                # Use standard generation
+                name = self.character_agent.generate_name(
+                    race=race_enum,
+                    character_class=class_enum,
+                    gender=gender if gender != "Not specified" else None
+                )
+                return name
+
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+    def create_character_ui(
+        self,
+        name: str,
+        race: str,
+        character_class: str,
+        level: int,
+        gender: str,
+        skin_tone: str,
+        alignment: str,
+        background_dropdown: str,
+        custom_background: str,
+        personality_prompt: str,
+        stats_method: str,
+        use_ai_background: bool,
+    ) -> Tuple[str, str]:
+        """
+        Create character with UI inputs
+
+        Returns:
+            Tuple of (character_sheet_markdown, status_message)
+        """
+        try:
+            # Validate inputs
+            if not name.strip():
+                return "", "❌ Error: Please provide a character name (use 'Generate Name' button or type one)"
+
+            if level < 1 or level > 20:
+                return "", "❌ Error: Level must be between 1 and 20"
+
+            # Convert race, class, and alignment
+            try:
+                race_enum = DnDRace(race)
+                class_enum = DnDClass(character_class)
+                alignment_enum = Alignment(alignment)
+            except ValueError as e:
+                return "", f"❌ Error: Invalid race, class, or alignment - {e}"
+
+            # Determine final background type
+            if background_dropdown == "Custom (enter below)":
+                final_background = custom_background.strip() if custom_background.strip() else "Adventurer"
+            else:
+                final_background = background_dropdown
+
+            # Create character with gender AND alignment in personality prompt
+            gender_hint = f"Character is {gender}. " if gender != "Not specified" else ""
+            alignment_hint = f"Character's alignment is {alignment}, so their personality and backstory should reflect {self._get_alignment_description(alignment)}. "
+
+            full_personality_prompt = gender_hint + alignment_hint + (personality_prompt if personality_prompt else "")
+
+            character = self.character_agent.create_character(
+                name=name,
+                race=race_enum,
+                character_class=class_enum,
+                level=level,
+                background_type=final_background,
+                personality_prompt=full_personality_prompt if use_ai_background else None,
+                stats_method=stats_method,
+            )
+
+            # Override alignment, gender, and skin tone if user specified
+            character.alignment = alignment_enum
+            character.gender = gender if gender != "Not specified" else None
+            character.skin_tone = skin_tone if skin_tone else None
+
+            # Generate markdown
+            markdown = character.to_markdown()
+
+            status = f"""✅ Character Created Successfully!
+
+**ID:** {character.id}
+**Name:** {character.name}
+**Race:** {character.race.value}
+**Class:** {character.character_class.value}
+**Level:** {character.level}
+
+Character has been saved to database."""
+
+            return markdown, status
+
+        except Exception as e:
+            error_msg = f"❌ Error creating character:\n\n{str(e)}\n\n{traceback.format_exc()}"
+            return "", error_msg
+
+    def create(self) -> None:
+        """Create and return the Create Character tab component"""
+        with gr.Tab("Create Character"):
+            gr.Markdown("### Character Creation")
+
+            with gr.Row():
+                with gr.Column():
+                    gr.Markdown("#### Basic Information")
+
+                    with gr.Row():
+                        name_input = gr.Textbox(
+                            label="Character Name",
+                            placeholder="Thorin Ironforge",
+                            info="Type a name or generate one below",
+                            scale=3
+                        )
+
+                    race_dropdown = gr.Dropdown(
+                        choices=get_available_races(),
+                        label="Race",
+                        value="Human",
+                        info="Character's race"
+                    )
+
+                    class_dropdown = gr.Dropdown(
+                        choices=get_available_classes(),
+                        label="Class",
+                        value="Fighter",
+                        info="Character's class"
+                    )
+
+                    gender_dropdown = gr.Dropdown(
+                        choices=["Male", "Female", "Non-binary", "Not specified"],
+                        label="Gender",
+                        value="Not specified",
+                        info="Character's gender"
+                    )
+
+                    skin_tone_dropdown = gr.Dropdown(
+                        choices=RACE_SKIN_TONES[DnDRace.HUMAN],  # Default to Human
+                        label="Skin Tone / Color",
+                        value=None,
+                        info="Select appropriate color for the race"
+                    )
+
+                    generate_name_btn = gr.Button("🎲 Generate Name", variant="secondary", size="sm")
+
+                    level_slider = gr.Slider(
+                        minimum=1,
+                        maximum=20,
+                        value=1,
+                        step=1,
+                        label="Level",
+                        info="Character level (1-20)"
+                    )
+
+                    alignment_dropdown = gr.Dropdown(
+                        choices=[
+                            "Lawful Good", "Neutral Good", "Chaotic Good",
+                            "Lawful Neutral", "True Neutral", "Chaotic Neutral",
+                            "Lawful Evil", "Neutral Evil", "Chaotic Evil"
+                        ],
+                        label="Alignment",
+                        value="True Neutral",
+                        info="Character's moral alignment"
+                    )
+
+                with gr.Column():
+                    gr.Markdown("#### Background & Personality")
+
+                    background_dropdown = gr.Dropdown(
+                        choices=[
+                            "Acolyte", "Charlatan", "Criminal", "Entertainer",
+                            "Folk Hero", "Guild Artisan", "Hermit", "Noble",
+                            "Outlander", "Sage", "Sailor", "Soldier",
+                            "Urchin", "Custom (enter below)"
+                        ],
+                        label="Background Type",
+                        value="Soldier",
+                        info="Select from D&D 5e backgrounds or choose Custom"
+                    )
+
+                    custom_background_input = gr.Textbox(
+                        label="Custom Background",
+                        placeholder="Enter your custom background...",
+                        value="",
+                        visible=False,
+                        info="Only used if 'Custom' is selected above"
+                    )
+
+                    use_ai_background = gr.Checkbox(
+                        label="Generate detailed backstory",
+                        value=True,
+                        info="Create a unique backstory for this character"
+                    )
+
+                    personality_input = gr.Textbox(
+                        label="Personality Guidance (Optional)",
+                        placeholder="A mysterious ranger who protects the forest...",
+                        lines=3,
+                        info="Guide AI in creating personality (if enabled)"
+                    )
+
+                    stats_method = gr.Radio(
+                        choices=["standard_array", "roll", "point_buy"],
+                        label="Ability Score Method",
+                        value="standard_array",
+                        info="How to generate ability scores"
+                    )
+
+            create_btn = gr.Button("⚔️ Create Character", variant="primary", size="lg")
+
+            gr.Markdown("---")
+
+            with gr.Row():
+                character_output = gr.Markdown(label="Character Sheet")
+                status_output = gr.Textbox(label="Status", lines=8)
+
+            # Toggle custom background visibility
+            def toggle_custom_background(background_choice):
+                return gr.update(visible=background_choice == "Custom (enter below)")
+
+            # Update skin tone options when race changes
+            def update_skin_tone_choices(race: str):
+                try:
+                    race_enum = DnDRace(race)
+                    skin_tones = RACE_SKIN_TONES.get(race_enum, RACE_SKIN_TONES[DnDRace.HUMAN])
+                    return gr.update(choices=skin_tones, value=skin_tones[0] if skin_tones else None)
+                except:
+                    return gr.update(choices=RACE_SKIN_TONES[DnDRace.HUMAN], value=RACE_SKIN_TONES[DnDRace.HUMAN][0])
+
+            background_dropdown.change(
+                fn=toggle_custom_background,
+                inputs=[background_dropdown],
+                outputs=[custom_background_input]
+            )
+
+            race_dropdown.change(
+                fn=update_skin_tone_choices,
+                inputs=[race_dropdown],
+                outputs=[skin_tone_dropdown]
+            )
+
+            # Generate name action - includes alignment for more thematic names
+            generate_name_btn.click(
+                fn=self.generate_name_ui,
+                inputs=[race_dropdown, class_dropdown, gender_dropdown, alignment_dropdown],
+                outputs=[name_input]
+            )
+
+            # Create character action
+            create_btn.click(
+                fn=self.create_character_ui,
+                inputs=[
+                    name_input,
+                    race_dropdown,
+                    class_dropdown,
+                    level_slider,
+                    gender_dropdown,
+                    skin_tone_dropdown,
+                    alignment_dropdown,
+                    background_dropdown,
+                    custom_background_input,
+                    personality_input,
+                    stats_method,
+                    use_ai_background,
+                ],
+                outputs=[character_output, status_output]
+            )

src/ui/tabs/character_export_tab.py

@@ -0,0 +1,187 @@
+"""
+Character Export Tab for D'n'D Campaign Manager
+"""
+
+import gradio as gr
+from typing import Tuple
+import traceback
+from src.agents.character_agent import CharacterAgent
+from src.ui.components.dropdown_manager import DropdownManager
+from src.utils.character_sheet_exporter import CharacterSheetExporter
+
+
+class CharacterExportTab:
+    """Export Character Sheet tab for exporting characters to various formats"""
+
+    def __init__(self, character_agent: CharacterAgent, dropdown_manager: DropdownManager):
+        self.character_agent = character_agent
+        self.dropdown_manager = dropdown_manager
+        self.exporter = CharacterSheetExporter()
+
+    def export_character_sheet_ui(
+        self,
+        character_id: str,
+        export_format: str = "markdown"
+    ) -> str:
+        """
+        Export character sheet to file
+
+        Returns:
+            Status message with file path
+        """
+        try:
+            if not character_id.strip():
+                return "❌ Error: Please provide a character ID"
+
+            # Load character
+            character = self.character_agent.load_character(character_id)
+            if not character:
+                return f"❌ Character not found: {character_id}"
+
+            # Export to selected format
+            file_path = self.exporter.save_export(character, format=export_format)
+
+            return f"""✅ Character sheet exported successfully!
+
+**Character:** {character.name}
+**Format:** {export_format.upper()}
+**File:** {file_path}
+
+You can find the exported file in the data/exports/ directory."""
+
+        except Exception as e:
+            return f"❌ Error exporting character sheet:\n\n{str(e)}\n\n{traceback.format_exc()}"
+
+    def preview_export_ui(
+        self,
+        character_id: str,
+        export_format: str = "markdown"
+    ) -> Tuple[str, str]:
+        """
+        Preview character sheet export without saving
+
+        Returns:
+            Tuple of (preview_content, status_message)
+        """
+        try:
+            if not character_id.strip():
+                return "", "❌ Error: Please provide a character ID"
+
+            # Load character
+            character = self.character_agent.load_character(character_id)
+            if not character:
+                return "", f"❌ Character not found: {character_id}"
+
+            # Generate preview based on format
+            if export_format == "markdown":
+                preview = self.exporter.export_to_markdown(character)
+            elif export_format == "json":
+                preview = f"```json\n{self.exporter.export_to_json(character)}\n```"
+            elif export_format == "html":
+                preview = f"```html\n{self.exporter.export_to_html(character)}\n```"
+            else:
+                return "", f"❌ Unknown format: {export_format}"
+
+            status = f"✅ Preview generated for {character.name}"
+            return preview, status
+
+        except Exception as e:
+            return "", f"❌ Error generating preview:\n\n{str(e)}\n\n{traceback.format_exc()}"
+
+    def create(self) -> gr.Dropdown:
+        """Create and return the Export Character Sheet tab component"""
+        with gr.Tab("Export Character Sheet"):
+            gr.Markdown("""
+            ### 📄 Export Character Sheets
+            Export your characters to formatted character sheets in multiple formats!
+            """)
+
+            with gr.Row():
+                with gr.Column():
+                    export_char_refresh_btn = gr.Button("🔄 Refresh Character List", variant="secondary")
+
+                    export_character_dropdown = gr.Dropdown(
+                        choices=[],
+                        label="Select Character",
+                        info="Choose a character to export (type to search)",
+                        allow_custom_value=False,
+                        interactive=True
+                    )
+
+                    export_format = gr.Radio(
+                        choices=["markdown", "json", "html"],
+                        label="Export Format",
+                        value="markdown",
+                        info="Choose the format for your character sheet"
+                    )
+
+                    with gr.Row():
+                        preview_btn = gr.Button("👁️ Preview", variant="secondary")
+                        export_btn = gr.Button("💾 Export to File", variant="primary")
+
+                    export_status = gr.Textbox(
+                        label="Status",
+                        lines=6
+                    )
+
+                with gr.Column():
+                    preview_output = gr.Markdown(
+                        label="Preview",
+                        value="Character sheet preview will appear here..."
+                    )
+
+            gr.Markdown("""
+            ### Format Descriptions
+
+            **Markdown (.md)**
+            - Clean, readable text format with tables
+            - Perfect for sharing in Discord, GitHub, or note apps
+            - Includes all character stats, features, and background
+            - Easy to read and edit
+
+            **JSON (.json)**
+            - Structured data format
+            - Perfect for importing into other tools or programs
+            - Contains all character data in a machine-readable format
+            - Great for backup or data transfer
+
+            **HTML (.html)**
+            - Styled character sheet that can be opened in a browser
+            - Print-ready format (mimics official D&D character sheet)
+            - Beautiful parchment styling with maroon borders
+            - Can be converted to PDF using browser's print function
+
+            All exports are saved to the `data/exports/` directory.
+            """)
+
+            # Refresh export character dropdown
+            export_char_refresh_btn.click(
+                fn=self.dropdown_manager.refresh_character_dropdown,
+                inputs=[],
+                outputs=[export_character_dropdown]
+            )
+
+            # Preview action - convert dropdown label to ID
+            def preview_from_dropdown(label, format):
+                char_id = self.dropdown_manager.get_character_id_from_label(label)
+                return self.preview_export_ui(char_id, format)
+
+            preview_btn.click(
+                fn=preview_from_dropdown,
+                inputs=[export_character_dropdown, export_format],
+                outputs=[preview_output, export_status]
+            )
+
+            # Export action - convert dropdown label to ID
+            def export_from_dropdown(label, format):
+                char_id = self.dropdown_manager.get_character_id_from_label(label)
+                return self.export_character_sheet_ui(char_id, format)
+
+            export_btn.click(
+                fn=export_from_dropdown,
+                inputs=[export_character_dropdown, export_format],
+                outputs=[export_status]
+            )
+
+        # Return the dropdown for auto-population
+        return export_character_dropdown

src/ui/tabs/character_load_tab.py

@@ -0,0 +1,109 @@
+"""
+Character Load Tab for D'n'D Campaign Manager
+"""
+
+import gradio as gr
+from typing import Tuple
+from src.agents.character_agent import CharacterAgent
+from src.ui.components.dropdown_manager import DropdownManager
+
+
+class CharacterLoadTab:
+    """Load Character tab for viewing saved characters"""
+
+    def __init__(self, character_agent: CharacterAgent, dropdown_manager: DropdownManager):
+        self.character_agent = character_agent
+        self.dropdown_manager = dropdown_manager
+
+    def load_character_ui(self, character_id: str) -> Tuple[str, str]:
+        """Load character by ID"""
+        try:
+            if not character_id.strip():
+                return "", "❌ Error: Please provide a character ID"
+
+            character = self.character_agent.load_character(character_id)
+
+            if character:
+                markdown = character.to_markdown()
+                status = f"✅ Loaded character: {character.name}"
+                return markdown, status
+            else:
+                return "", f"❌ Character not found: {character_id}"
+
+        except Exception as e:
+            return "", f"❌ Error loading character: {e}"
+
+    def list_characters_ui(self) -> Tuple[str, str]:
+        """List all saved characters"""
+        try:
+            characters = self.character_agent.list_characters()
+
+            if not characters:
+                return "", "No characters found in database."
+
+            # Create table
+            markdown = "# Saved Characters\n\n"
+            markdown += "| Name | Race | Class | Level | ID |\n"
+            markdown += "|------|------|-------|-------|----|\n"
+
+            for char in characters[-20:]:  # Last 20 characters
+                markdown += f"| {char.name} | {char.race.value} | {char.character_class.value} | {char.level} | `{char.id}` |\n"
+
+            status = f"✅ Found {len(characters)} character(s)"
+            return markdown, status
+
+        except Exception as e:
+            return "", f"❌ Error listing characters: {e}"
+
+    def create(self) -> gr.Dropdown:
+        """Create and return the Load Character tab component"""
+        with gr.Tab("Load Character"):
+            gr.Markdown("### Load Saved Character")
+
+            load_char_refresh_btn = gr.Button("🔄 Refresh Character List", variant="secondary")
+
+            character_dropdown = gr.Dropdown(
+                choices=[],
+                label="Select Character",
+                info="Choose a character from the list (type to search)",
+                allow_custom_value=False,
+                interactive=True
+            )
+
+            with gr.Row():
+                load_btn = gr.Button("📂 Load Character", variant="primary")
+                list_btn = gr.Button("📋 List All Characters")
+
+            gr.Markdown("---")
+
+            with gr.Row():
+                loaded_character_output = gr.Markdown(label="Character Sheet")
+                load_status_output = gr.Textbox(label="Status", lines=6)
+
+            # Refresh character dropdown
+            load_char_refresh_btn.click(
+                fn=self.dropdown_manager.refresh_character_dropdown,
+                inputs=[],
+                outputs=[character_dropdown]
+            )
+
+            # Load character action - convert dropdown label to ID
+            def load_character_from_dropdown(label):
+                char_id = self.dropdown_manager.get_character_id_from_label(label)
+                return self.load_character_ui(char_id)
+
+            load_btn.click(
+                fn=load_character_from_dropdown,
+                inputs=[character_dropdown],
+                outputs=[loaded_character_output, load_status_output]
+            )
+
+            # List characters action
+            list_btn.click(
+                fn=self.list_characters_ui,
+                inputs=[],
+                outputs=[loaded_character_output, load_status_output]
+            )
+
+        # Return the dropdown for auto-population
+        return character_dropdown

src/ui/tabs/character_manage_tab.py

@@ -0,0 +1,112 @@
+"""
+Character Manage Tab for D'n'D Campaign Manager
+"""
+
+import gradio as gr
+from typing import Tuple
+from src.agents.character_agent import CharacterAgent
+from src.ui.components.dropdown_manager import DropdownManager
+
+
+class CharacterManageTab:
+    """Manage Characters tab for deleting and viewing characters"""
+
+    def __init__(self, character_agent: CharacterAgent, dropdown_manager: DropdownManager):
+        self.character_agent = character_agent
+        self.dropdown_manager = dropdown_manager
+
+    def delete_character_ui(self, character_id: str) -> str:
+        """Delete character by ID"""
+        try:
+            if not character_id.strip():
+                return "❌ Error: Please provide a character ID"
+
+            # Check if exists
+            character = self.character_agent.load_character(character_id)
+            if not character:
+                return f"❌ Character not found: {character_id}"
+
+            # Delete
+            self.character_agent.delete_character(character_id)
+            return f"✅ Deleted character: {character.name} ({character_id})"
+
+        except Exception as e:
+            return f"❌ Error deleting character: {e}"
+
+    def list_characters_ui(self) -> Tuple[str, str]:
+        """List all saved characters"""
+        try:
+            characters = self.character_agent.list_characters()
+
+            if not characters:
+                return "", "No characters found in database."
+
+            # Create table
+            markdown = "# Saved Characters\n\n"
+            markdown += "| Name | Race | Class | Level | ID |\n"
+            markdown += "|------|------|-------|-------|----|\n"
+
+            for char in characters[-20:]:  # Last 20 characters
+                markdown += f"| {char.name} | {char.race.value} | {char.character_class.value} | {char.level} | `{char.id}` |\n"
+
+            status = f"✅ Found {len(characters)} character(s)"
+            return markdown, status
+
+        except Exception as e:
+            return "", f"❌ Error listing characters: {e}"
+
+    def create(self) -> gr.Dropdown:
+        """Create and return the Manage Characters tab component"""
+        with gr.Tab("Manage Characters"):
+            gr.Markdown("### Character Management")
+
+            delete_refresh_btn = gr.Button("🔄 Refresh Character List", variant="secondary")
+
+            delete_character_dropdown = gr.Dropdown(
+                choices=[],
+                label="Select Character to Delete",
+                info="⚠️ Warning: This action cannot be undone! (type to search)",
+                allow_custom_value=False,
+                interactive=True
+            )
+
+            delete_btn = gr.Button("🗑️ Delete Character", variant="stop")
+
+            delete_status_output = gr.Textbox(label="Status", lines=3)
+
+            # Refresh delete character dropdown
+            delete_refresh_btn.click(
+                fn=self.dropdown_manager.refresh_character_dropdown,
+                inputs=[],
+                outputs=[delete_character_dropdown]
+            )
+
+            # Delete character action - convert dropdown label to ID and refresh list
+            def delete_character_from_dropdown(label):
+                char_id = self.dropdown_manager.get_character_id_from_label(label)
+                status = self.delete_character_ui(char_id)
+                # Refresh dropdown choices after deletion
+                updated_choices = self.dropdown_manager.refresh_character_dropdown()
+                return status, updated_choices
+
+            delete_btn.click(
+                fn=delete_character_from_dropdown,
+                inputs=[delete_character_dropdown],
+                outputs=[delete_status_output, delete_character_dropdown]
+            )
+
+            gr.Markdown("---")
+
+            with gr.Accordion("Quick Actions", open=False):
+                quick_list_btn = gr.Button("📋 List All Characters")
+                quick_list_output = gr.Markdown(label="Character List")
+                quick_status = gr.Textbox(label="Status", lines=2)
+
+                quick_list_btn.click(
+                    fn=self.list_characters_ui,
+                    inputs=[],
+                    outputs=[quick_list_output, quick_status]
+                )
+
+        # Return the dropdown for auto-population
+        return delete_character_dropdown

src/ui/tabs/character_portrait_tab.py

@@ -0,0 +1,156 @@
+"""
+Character Portrait Tab for D'n'D Campaign Manager
+"""
+
+import gradio as gr
+from typing import Optional, Tuple
+from src.agents.character_agent import CharacterAgent
+from src.ui.components.dropdown_manager import DropdownManager
+
+
+class CharacterPortraitTab:
+    """Generate Portrait tab for AI character portrait generation"""
+
+    def __init__(self, character_agent: CharacterAgent, dropdown_manager: DropdownManager):
+        self.character_agent = character_agent
+        self.dropdown_manager = dropdown_manager
+
+    def generate_portrait_ui(
+        self,
+        character_id: str,
+        style: str = "fantasy art",
+        quality: str = "standard",
+        provider: str = "auto"
+    ) -> Tuple[Optional[str], str]:
+        """
+        Generate character portrait
+
+        Returns:
+            Tuple of (image_path, status_message)
+        """
+        try:
+            if not character_id.strip():
+                return None, "❌ Error: Please provide a character ID"
+
+            # Load character
+            character = self.character_agent.load_character(character_id)
+            if not character:
+                return None, f"❌ Character not found: {character_id}"
+
+            # Generate portrait
+            file_path, status = self.character_agent.generate_portrait(
+                character=character,
+                style=style,
+                quality=quality,
+                provider=provider
+            )
+
+            return file_path, status
+
+        except Exception as e:
+            import traceback
+            error_msg = f"❌ Error generating portrait:\n\n{str(e)}\n\n{traceback.format_exc()}"
+            return None, error_msg
+
+    def create(self) -> gr.Dropdown:
+        """Create and return the Generate Portrait tab component"""
+        with gr.Tab("Generate Portrait"):
+            gr.Markdown("""
+            ### 🎨 AI Character Portrait Generator
+            Generate stunning character portraits using DALL-E 3 or HuggingFace!
+            """)
+
+            with gr.Row():
+                with gr.Column():
+                    portrait_refresh_btn = gr.Button("🔄 Refresh Character List", variant="secondary")
+
+                    portrait_character_dropdown = gr.Dropdown(
+                        choices=[],
+                        label="Select Character",
+                        info="Choose a character to generate portrait for (type to search)",
+                        allow_custom_value=False,
+                        interactive=True
+                    )
+
+                    portrait_provider = gr.Radio(
+                        choices=["auto", "openai", "huggingface"],
+                        label="Image Provider",
+                        value="auto",
+                        info="Auto: Try OpenAI first, fallback to HuggingFace if needed"
+                    )
+
+                    portrait_style = gr.Dropdown(
+                        choices=[
+                            "fantasy art",
+                            "digital painting",
+                            "anime style",
+                            "oil painting",
+                            "watercolor",
+                            "comic book art",
+                            "concept art"
+                        ],
+                        label="Art Style",
+                        value="fantasy art",
+                        info="Choose the artistic style"
+                    )
+
+                    portrait_quality = gr.Radio(
+                        choices=["standard", "hd"],
+                        label="Image Quality (OpenAI only)",
+                        value="standard",
+                        info="HD costs more tokens (OpenAI only)"
+                    )
+
+                    generate_portrait_btn = gr.Button(
+                        "🎨 Generate Portrait",
+                        variant="primary",
+                        size="lg"
+                    )
+
+                    portrait_status = gr.Textbox(
+                        label="Status",
+                        lines=4
+                    )
+
+                with gr.Column():
+                    portrait_output = gr.Image(
+                        label="Generated Portrait",
+                        type="filepath",
+                        height=512
+                    )
+
+            gr.Markdown("""
+            **Providers:**
+            - **OpenAI DALL-E 3**: High quality, costs $0.04/image (standard) or $0.08/image (HD)
+            - **HuggingFace (Free!)**: Stable Diffusion XL, ~100 requests/day on free tier
+            - **Auto**: Tries OpenAI first, automatically falls back to HuggingFace if billing issues
+
+            Portraits are automatically saved to `data/portraits/` directory.
+
+            **Tips:**
+            - Use "auto" mode for seamless fallback
+            - OpenAI HD quality produces better results but costs 2x
+            - HuggingFace is free but may have a 30-60s warm-up time
+            - Different styles work better for different races/classes
+            """)
+
+            # Refresh portrait character dropdown
+            portrait_refresh_btn.click(
+                fn=self.dropdown_manager.refresh_character_dropdown,
+                inputs=[],
+                outputs=[portrait_character_dropdown]
+            )
+
+            # Generate portrait action - convert dropdown label to ID
+            def generate_portrait_from_dropdown(label, style, quality, provider):
+                char_id = self.dropdown_manager.get_character_id_from_label(label)
+                return self.generate_portrait_ui(char_id, style, quality, provider)
+
+            generate_portrait_btn.click(
+                fn=generate_portrait_from_dropdown,
+                inputs=[portrait_character_dropdown, portrait_style, portrait_quality, portrait_provider],
+                outputs=[portrait_output, portrait_status]
+            )
+
+        # Return the dropdown for auto-population
+        return portrait_character_dropdown

src/ui/tabs/session_tracking_tab.py

@@ -0,0 +1,599 @@
+"""
+Session Tracking Tab for D'n'D Campaign Manager
+"""
+
+import gradio as gr
+import traceback
+from src.agents.campaign_agent import CampaignAgent
+from src.ui.components.dropdown_manager import DropdownManager
+
+
+class SessionTrackingTab:
+    """Session Tracking tab for managing campaign sessions and events"""
+
+    def __init__(self, campaign_agent: CampaignAgent, dropdown_manager: DropdownManager):
+        self.campaign_agent = campaign_agent
+        self.dropdown_manager = dropdown_manager
+
+    def start_session_ui(self, campaign_id: str) -> str:
+        """Start a new session"""
+        try:
+            if not campaign_id.strip():
+                return "❌ Error: Please provide a campaign ID"
+
+            campaign = self.campaign_agent.load_campaign(campaign_id)
+            if not campaign:
+                return f"❌ Campaign not found: {campaign_id}"
+
+            self.campaign_agent.start_new_session(campaign_id)
+
+            return f"""✅ Started Session {campaign.current_session + 1}!
+
+**Campaign:** {campaign.name}
+**New Session Number:** {campaign.current_session + 1}
+**Total Sessions:** {campaign.total_sessions + 1}"""
+
+        except Exception as e:
+            return f"❌ Error: {str(e)}"
+
+    def get_session_notes_status(self, campaign_id: str) -> str:
+        """Get status of uploaded session notes for a campaign"""
+        try:
+            if not campaign_id.strip():
+                return ""
+
+            campaign = self.campaign_agent.load_campaign(campaign_id)
+            if not campaign:
+                return ""
+
+            # Get all session notes
+            all_notes = self.campaign_agent.get_session_notes(campaign_id)
+
+            if not all_notes:
+                return """
+📊 **Session Notes Status:** No notes uploaded yet
+
+💡 **Tip:** Upload your session notes below to get better AI-generated sessions!
+AI will use your notes to create sessions that respond to what actually happened."""
+
+            # Build status message
+            status = "📊 **Session Notes Available:**\n\n"
+            for note in sorted(all_notes, key=lambda x: x.session_number):
+                char_count = len(note.notes)
+                status += f"✅ Session {note.session_number} - {char_count} characters"
+                if note.file_name:
+                    status += f" ({note.file_name})"
+                status += "\n"
+
+            status += f"\n💡 AI will use these {len(all_notes)} session note(s) to generate contextual next sessions!"
+
+            return status
+
+        except Exception as e:
+            return f"❌ Error checking notes: {str(e)}"
+
+    def auto_generate_session_ui(self, campaign_id: str) -> str:
+        """Auto-generate next session using AI"""
+        try:
+            if not campaign_id.strip():
+                return "❌ Error: Please select a campaign"
+
+            campaign = self.campaign_agent.load_campaign(campaign_id)
+            if not campaign:
+                return f"❌ Campaign not found: {campaign_id}"
+
+            # Generate session using autonomous AI
+            session_data = self.campaign_agent.auto_generate_next_session(campaign_id)
+
+            if 'error' in session_data:
+                return f"❌ Error: {session_data['error']}"
+
+            # Format output for display
+            output = []
+            output.append(f"# 🤖 Auto-Generated Session {session_data.get('session_number', 'N/A')}")
+            output.append(f"\n**Campaign:** {campaign.name}")
+            output.append(f"\n**Session Title:** {session_data.get('session_title', 'Untitled')}")
+            output.append(f"\n---\n")
+
+            # Opening Scene
+            if 'opening_scene' in session_data:
+                output.append(f"## 🎬 Opening Scene\n\n{session_data['opening_scene']}\n\n")
+
+            # Key Encounters
+            if 'key_encounters' in session_data and session_data['key_encounters']:
+                output.append("## ⚔️ Key Encounters\n\n")
+                for i, encounter in enumerate(session_data['key_encounters'], 1):
+                    output.append(f"{i}. {encounter}\n")
+                output.append("\n")
+
+            # NPCs Featured
+            if 'npcs_featured' in session_data and session_data['npcs_featured']:
+                output.append("## 👥 NPCs Featured\n\n")
+                for npc in session_data['npcs_featured']:
+                    output.append(f"- {npc}\n")
+                output.append("\n")
+
+            # Locations
+            if 'locations' in session_data and session_data['locations']:
+                output.append("## 🗺️ Locations\n\n")
+                for loc in session_data['locations']:
+                    output.append(f"- {loc}\n")
+                output.append("\n")
+
+            # Plot Developments
+            if 'plot_developments' in session_data and session_data['plot_developments']:
+                output.append("## 📖 Plot Developments\n\n")
+                for i, dev in enumerate(session_data['plot_developments'], 1):
+                    output.append(f"{i}. {dev}\n")
+                output.append("\n")
+
+            # Potential Outcomes
+            if 'potential_outcomes' in session_data and session_data['potential_outcomes']:
+                output.append("## 🎲 Potential Outcomes\n\n")
+                for i, outcome in enumerate(session_data['potential_outcomes'], 1):
+                    output.append(f"{i}. {outcome}\n")
+                output.append("\n")
+
+            # Rewards
+            if 'rewards' in session_data and session_data['rewards']:
+                output.append("## 💰 Rewards\n\n")
+                for reward in session_data['rewards']:
+                    output.append(f"- {reward}\n")
+                output.append("\n")
+
+            # Cliffhanger
+            if 'cliffhanger' in session_data and session_data['cliffhanger']:
+                output.append(f"## 🎭 Cliffhanger\n\n{session_data['cliffhanger']}\n\n")
+
+            output.append("---\n\n")
+            output.append("✅ **Session plan generated successfully!**\n\n")
+            output.append("💡 **Next Steps:**\n")
+            output.append("- Review the session plan above\n")
+            output.append("- Adjust encounters/NPCs as needed for your table\n")
+            output.append("- Copy relevant sections to your session notes\n")
+            output.append("- Start the session when ready!\n")
+
+            return "".join(output)
+
+        except Exception as e:
+            return f"❌ Error generating session:\n\n{str(e)}\n\n{traceback.format_exc()}"
+
+    def save_session_notes_ui(
+        self,
+        campaign_id: str,
+        session_number: int,
+        file_path: str,
+        notes_text: str
+    ) -> str:
+        """Save session notes from file upload or text input"""
+        try:
+            if not campaign_id.strip():
+                return "❌ Please select a campaign"
+
+            campaign = self.campaign_agent.load_campaign(campaign_id)
+            if not campaign:
+                return f"❌ Campaign not found: {campaign_id}"
+
+            # Use file content if uploaded, otherwise use text area
+            content = ""
+            file_name = None
+            file_type = None
+
+            if file_path:
+                try:
+                    from src.utils.file_parsers import parse_uploaded_file, get_file_info
+                    from pathlib import Path
+
+                    content = parse_uploaded_file(file_path)
+                    file_info = get_file_info(file_path)
+                    file_name = file_info['name']
+                    file_type = file_info['extension']
+
+                except Exception as e:
+                    return f"❌ Error parsing file: {str(e)}"
+
+            elif notes_text.strip():
+                content = notes_text
+            else:
+                return "❌ Please upload a file or paste notes"
+
+            # Save to database
+            try:
+                self.campaign_agent.save_session_notes(
+                    campaign_id=campaign_id,
+                    session_number=int(session_number),
+                    notes=content,
+                    file_name=file_name,
+                    file_type=file_type
+                )
+
+                # Get updated session notes count
+                all_notes = self.campaign_agent.get_session_notes(campaign_id)
+                notes_count = len(all_notes)
+
+                # Build success message with context
+                message = f"""✅ **Session notes saved successfully!**
+
+**Campaign:** {campaign.name}
+**Session:** {session_number}
+**Content length:** {len(content)} characters
+**Source:** {'📎 File upload' if file_path else '✍️ Direct paste'}
+{f'**File:** {file_name}' if file_name else ''}
+
+---
+
+📊 **Your Campaign Now Has:**
+- {notes_count} session{'s' if notes_count != 1 else ''} with uploaded notes
+- Session {session_number} notes just added
+
+---
+
+🎯 **What You Can Do Next:**
+
+1. **Generate Session {int(session_number) + 1}:**
+   - Scroll up to **"Step 1: 🤖 Auto-Generate Next Session"**
+   - Select "{campaign.name}"
+   - Click "✨ Auto-Generate Next Session"
+   - AI will use your Session {session_number} notes to create contextual content!
+
+2. **Upload More Sessions:**
+   - Have notes from other sessions? Upload them too!
+   - More notes = better AI-generated sessions
+
+3. **Review Your Notes:**
+   - Your notes are saved and will be used automatically
+   - AI analyzes: player choices, NPCs, unresolved hooks, consequences
+
+---
+
+💡 **How It Works:**
+When you generate the next session (Step 1), the AI will:
+✅ Read your uploaded notes (last 2-3 sessions)
+✅ Build on what actually happened at your table
+✅ Address unresolved plot hooks you mentioned
+✅ Create encounters that respond to player decisions
+
+**Ready to generate Session {int(session_number) + 1}? Scroll up to Step 1!** ⬆️"""
+
+                return message
+
+            except Exception as e:
+                return f"❌ Error saving notes: {str(e)}"
+
+        except Exception as e:
+            return f"❌ Error: {str(e)}\n\n{traceback.format_exc()}"
+
+    def add_event_ui(
+        self,
+        campaign_id: str,
+        event_type: str,
+        title: str,
+        description: str,
+        importance: int
+    ) -> str:
+        """Add an event to the campaign"""
+        try:
+            if not campaign_id.strip():
+                return "❌ Error: Please provide a campaign ID"
+
+            if not title.strip() or not description.strip():
+                return "❌ Error: Please provide event title and description"
+
+            event = self.campaign_agent.add_event(
+                campaign_id=campaign_id,
+                event_type=event_type,
+                title=title,
+                description=description,
+                importance=importance
+            )
+
+            if event:
+                return f"""✅ Event Added!
+
+**Title:** {title}
+**Type:** {event_type}
+**Importance:** {'⭐' * importance}
+
+Event has been recorded in campaign history."""
+            else:
+                return f"❌ Campaign not found: {campaign_id}"
+
+        except Exception as e:
+            return f"❌ Error: {str(e)}"
+
+    def create(self) -> tuple:
+        """Create and return the Session Tracking tab component"""
+        with gr.Tab("Session Tracking"):
+            gr.Markdown("""
+            # 🎲 Session Tracking & Planning
+
+            **Workflow:** Auto-generate next session → Play the session → Upload notes afterward
+
+            ---
+            """)
+
+            # SECTION 1: Auto-Generate Next Session
+            gr.Markdown("## Step 1: 🤖 Auto-Generate Next Session")
+            gr.Markdown("""
+            **Before playing:** Let the AI create your session plan!
+
+            **Autonomous Feature:** AI analyzes your campaign and automatically generates a complete session plan.
+
+            This includes:
+            - Opening scene narration
+            - Key encounters (combat, social, exploration)
+            - NPCs featured in the session
+            - Locations to visit
+            - Plot developments
+            - Potential outcomes and rewards
+
+            💡 **Tip:** The AI uses your uploaded session notes from previous sessions to create contextual, story-driven content!
+            """)
+
+            auto_session_refresh_btn = gr.Button("🔄 Refresh Campaign List", variant="secondary")
+
+            auto_session_campaign_dropdown = gr.Dropdown(
+                choices=[],
+                label="Select Campaign",
+                info="Choose campaign to generate next session for",
+                allow_custom_value=False,
+                interactive=True
+            )
+
+            # Session notes status display
+            session_notes_status = gr.Markdown(
+                value="",
+                label="Session Notes Status"
+            )
+
+            auto_generate_session_btn = gr.Button("✨ Auto-Generate Next Session", variant="primary")
+
+            auto_session_output = gr.Textbox(label="Generated Session Plan", lines=20)
+
+            # Refresh auto-session campaign dropdown
+            auto_session_refresh_btn.click(
+                fn=self.dropdown_manager.refresh_campaign_dropdown,
+                inputs=[],
+                outputs=[auto_session_campaign_dropdown]
+            )
+
+            # Update session notes status when campaign is selected
+            def update_notes_status(campaign_label):
+                campaign_id = self.dropdown_manager.get_campaign_id_from_label(campaign_label)
+                return self.get_session_notes_status(campaign_id)
+
+            auto_session_campaign_dropdown.change(
+                fn=update_notes_status,
+                inputs=[auto_session_campaign_dropdown],
+                outputs=[session_notes_status]
+            )
+
+            # Auto-generate session
+            def auto_generate_session_from_dropdown(label):
+                campaign_id = self.dropdown_manager.get_campaign_id_from_label(label)
+                return self.auto_generate_session_ui(campaign_id)
+
+            auto_generate_session_btn.click(
+                fn=auto_generate_session_from_dropdown,
+                inputs=[auto_session_campaign_dropdown],
+                outputs=[auto_session_output]
+            )
+
+            gr.Markdown("---")
+
+            # SECTION 2: Start New Session
+            gr.Markdown("## Step 2: 🎬 Start New Session")
+            gr.Markdown("""
+            **Ready to play?** Start your session here!
+
+            This will:
+            - Increment the session counter
+            - Track that a new session has begun
+            - Prepare for event logging
+
+            💡 **When to use:** Right before you start playing with your group.
+            """)
+
+            session_refresh_btn = gr.Button("🔄 Refresh Campaign List", variant="secondary")
+
+            session_campaign_dropdown = gr.Dropdown(
+                choices=[],
+                label="Select Campaign",
+                info="Choose the campaign for session tracking (type to search)",
+                allow_custom_value=False,
+                interactive=True
+            )
+
+            start_session_btn = gr.Button("🎬 Start New Session", variant="primary")
+
+            session_status = gr.Textbox(label="Status", lines=4)
+
+            # Refresh session campaign dropdown
+            session_refresh_btn.click(
+                fn=self.dropdown_manager.refresh_campaign_dropdown,
+                inputs=[],
+                outputs=[session_campaign_dropdown]
+            )
+
+            # Start session - convert dropdown label to ID
+            def start_session_from_dropdown(label):
+                campaign_id = self.dropdown_manager.get_campaign_id_from_label(label)
+                return self.start_session_ui(campaign_id)
+
+            start_session_btn.click(
+                fn=start_session_from_dropdown,
+                inputs=[session_campaign_dropdown],
+                outputs=[session_status]
+            )
+
+            gr.Markdown("---")
+
+            # SECTION 3: Upload Session Notes
+            gr.Markdown("## Step 3: 📝 Upload Session Notes (After Playing)")
+            gr.Markdown("""
+            **Just finished a session?** Upload your DM notes here!
+
+            The AI will use your notes to generate better, more contextual next sessions.
+
+            **Supported formats:** .txt, .md, .docx, .pdf
+
+            **What to include:**
+            - What actually happened in the session
+            - Player choices and consequences
+            - Improvised content that worked well
+            - Unresolved plot hooks
+            - NPC interactions and developments
+
+            💡 **Why this matters:** When you generate the next session (Step 1), the AI reads these notes to create content that responds to your actual gameplay!
+            """)
+
+            notes_refresh_btn = gr.Button("🔄 Refresh Campaign List", variant="secondary")
+
+            notes_campaign_dropdown = gr.Dropdown(
+                choices=[],
+                label="Select Campaign",
+                info="Choose campaign to upload notes for"
+            )
+
+            notes_session_number = gr.Number(
+                label="Session Number",
+                value=1,
+                precision=0,
+                info="Which session are these notes for?"
+            )
+
+            notes_file_upload = gr.File(
+                label="Upload Session Notes File (Optional)",
+                file_types=['.txt', '.md', '.docx', '.pdf'],
+                type='filepath'
+            )
+
+            notes_text_area = gr.Textbox(
+                label="Or Paste Notes Directly",
+                lines=15,
+                placeholder="""Session 3 - The Lost Temple
+
+The party arrived at the temple ruins after a week of travel...
+
+Key moments:
+- Grimm discovered a hidden passage behind the altar
+- Elara deciphered ancient runes warning of a curse
+- Combat with temple guardians (party took heavy damage, used most healing)
+- Found the Crystal of Shadows but Thorin decided not to take it
+- NPC Velorin revealed he's been following them - claims to protect the crystal
+
+Unresolved:
+- Why was Velorin really following them?
+- What happens if they don't take the crystal? Will someone else?
+- The guardian mentioned "the ritual" before dying - what ritual?
+- Party suspects Velorin isn't telling the whole truth
+
+Next session setup:
+- Party needs to rest and heal
+- Velorin wants to talk
+- Strange shadows gathering outside temple""",
+                info="Freeform notes about what happened in the session"
+            )
+
+            save_notes_btn = gr.Button("💾 Save Session Notes", variant="primary")
+            notes_status = gr.Textbox(label="Status", lines=6)
+
+            # Refresh notes campaign dropdown
+            notes_refresh_btn.click(
+                fn=self.dropdown_manager.refresh_campaign_dropdown,
+                inputs=[],
+                outputs=[notes_campaign_dropdown]
+            )
+
+            # Save notes event handler
+            def save_notes_from_dropdown(campaign_label, session_num, file_path, notes_text):
+                campaign_id = self.dropdown_manager.get_campaign_id_from_label(campaign_label)
+                return self.save_session_notes_ui(campaign_id, session_num, file_path, notes_text)
+
+            save_notes_btn.click(
+                fn=save_notes_from_dropdown,
+                inputs=[notes_campaign_dropdown, notes_session_number, notes_file_upload, notes_text_area],
+                outputs=[notes_status]
+            )
+
+            gr.Markdown("---")
+
+            # SECTION 4: Add Session Event (Manual Tracking)
+            gr.Markdown("## Step 4: 📋 Add Session Event (Optional)")
+            gr.Markdown("""
+            **Want to manually track specific events?** Add them here!
+
+            This is optional - use it if you want to log specific moments during or after your session.
+
+            💡 **Note:** This is separate from session notes. Use this for quick event logging, and use session notes (Step 3) for comprehensive session summaries.
+            """)
+
+            event_refresh_btn = gr.Button("🔄 Refresh Campaign List", variant="secondary")
+
+            event_campaign_dropdown = gr.Dropdown(
+                choices=[],
+                label="Select Campaign",
+                info="Choose the campaign to add event to (type to search)",
+                allow_custom_value=False,
+                interactive=True
+            )
+
+            event_type = gr.Dropdown(
+                choices=["Combat", "Social", "Exploration", "Discovery", "Plot Development", "Character Moment", "NPC Interaction", "Quest Update"],
+                label="Event Type",
+                value="Combat",
+                info="Type of event"
+            )
+
+            event_title = gr.Textbox(
+                label="Event Title",
+                placeholder="Battle at the Bridge",
+                info="Short title for the event"
+            )
+
+            event_description = gr.Textbox(
+                label="Event Description",
+                placeholder="The party encountered a group of bandits...",
+                lines=4,
+                info="Detailed description of what happened"
+            )
+
+            event_importance = gr.Slider(
+                minimum=1,
+                maximum=5,
+                value=3,
+                step=1,
+                label="Importance",
+                info="How important is this event? (1-5 stars)"
+            )
+
+            add_event_btn = gr.Button("📝 Add Event", variant="primary")
+
+            event_status = gr.Textbox(label="Status", lines=6)
+
+            # Refresh event campaign dropdown
+            event_refresh_btn.click(
+                fn=self.dropdown_manager.refresh_campaign_dropdown,
+                inputs=[],
+                outputs=[event_campaign_dropdown]
+            )
+
+            # Add event - convert dropdown label to ID
+            def add_event_from_dropdown(campaign_label, event_type_val, title, description, importance):
+                campaign_id = self.dropdown_manager.get_campaign_id_from_label(campaign_label)
+                return self.add_event_ui(campaign_id, event_type_val, title, description, importance)
+
+            add_event_btn.click(
+                fn=add_event_from_dropdown,
+                inputs=[
+                    event_campaign_dropdown,
+                    event_type,
+                    event_title,
+                    event_description,
+                    event_importance
+                ],
+                outputs=[event_status]
+            )
+
+        # Return dropdowns for auto-population
+        return session_campaign_dropdown, auto_session_campaign_dropdown, notes_campaign_dropdown, event_campaign_dropdown

src/ui/utils/__init__.py

@@ -0,0 +1,5 @@
+"""
+Utility functions for D'n'D Campaign Manager UI
+"""
+
+__all__ = []

src/utils/__init__.py

@@ -0,0 +1,21 @@
+"""
+Utility functions and helpers
+"""
+
+from .ai_client import AIClient, get_ai_client
+from .dice import DiceRoller
+from .database import Database, get_database
+from .validators import validate_character, validate_campaign
+from .image_generator import ImageGenerator, get_image_generator
+
+__all__ = [
+    "AIClient",
+    "get_ai_client",
+    "DiceRoller",
+    "Database",
+    "get_database",
+    "validate_character",
+    "validate_campaign",
+    "ImageGenerator",
+    "get_image_generator",
+]

src/utils/ai_client.py

@@ -0,0 +1,294 @@
+"""
+AI Client Manager - Unified interface for multiple LLM providers
+Supports Anthropic Claude, Google Gemini, and OpenAI
+"""
+
+from typing import Optional, Dict, Any, List
+from enum import Enum
+import anthropic
+import google.generativeai as genai
+from openai import OpenAI
+
+from src.config import config
+
+
+class Provider(str, Enum):
+    """Supported AI providers"""
+    ANTHROPIC = "anthropic"
+    GOOGLE = "google"
+    OPENAI = "openai"
+
+
+class AIClient:
+    """Unified AI client supporting multiple providers"""
+
+    def __init__(self):
+        """Initialize all available clients"""
+        self.anthropic_client: Optional[anthropic.Anthropic] = None
+        self.google_client: Optional[Any] = None
+        self.openai_client: Optional[OpenAI] = None
+
+        self._initialize_clients()
+
+    def _initialize_clients(self):
+        """Initialize available AI clients based on API keys"""
+        # Anthropic Claude
+        if config.anthropic_api_key:
+            try:
+                self.anthropic_client = anthropic.Anthropic(
+                    api_key=config.anthropic_api_key
+                )
+            except Exception as e:
+                print(f"Failed to initialize Anthropic client: {e}")
+
+        # Google Gemini
+        if config.google_api_key:
+            try:
+                genai.configure(api_key=config.google_api_key)
+                self.google_client = genai
+            except Exception as e:
+                print(f"Failed to initialize Google client: {e}")
+
+        # OpenAI
+        if config.openai_api_key:
+            try:
+                self.openai_client = OpenAI(api_key=config.openai_api_key)
+            except Exception as e:
+                print(f"Failed to initialize OpenAI client: {e}")
+
+    def generate(
+        self,
+        prompt: str,
+        provider: Optional[Provider] = None,
+        model: Optional[str] = None,
+        temperature: float = 0.7,
+        max_tokens: int = 2000,
+        system_prompt: Optional[str] = None,
+    ) -> str:
+        """
+        Generate text using specified provider
+
+        Args:
+            prompt: User prompt
+            provider: AI provider to use (defaults to config)
+            model: Model name (defaults to config)
+            temperature: Sampling temperature
+            max_tokens: Maximum tokens to generate
+            system_prompt: System prompt for context
+
+        Returns:
+            Generated text
+        """
+        # Use defaults from config if not specified
+        if provider is None:
+            provider = Provider(config.model.primary_provider)
+        if model is None:
+            model = config.model.primary_model
+
+        # Route to appropriate provider
+        if provider == Provider.ANTHROPIC:
+            return self._generate_anthropic(prompt, model, temperature, max_tokens, system_prompt)
+        elif provider == Provider.GOOGLE:
+            return self._generate_google(prompt, model, temperature, max_tokens, system_prompt)
+        elif provider == Provider.OPENAI:
+            return self._generate_openai(prompt, model, temperature, max_tokens, system_prompt)
+        else:
+            raise ValueError(f"Unsupported provider: {provider}")
+
+    def _generate_anthropic(
+        self,
+        prompt: str,
+        model: str,
+        temperature: float,
+        max_tokens: int,
+        system_prompt: Optional[str],
+    ) -> str:
+        """Generate using Anthropic Claude"""
+        if not self.anthropic_client:
+            raise RuntimeError("Anthropic client not initialized")
+
+        messages = [{"role": "user", "content": prompt}]
+
+        kwargs = {
+            "model": model,
+            "messages": messages,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        }
+
+        if system_prompt:
+            kwargs["system"] = system_prompt
+
+        try:
+            response = self.anthropic_client.messages.create(**kwargs)
+            return response.content[0].text
+        except Exception as e:
+            raise RuntimeError(f"Anthropic API error: {e}")
+
+    def _generate_google(
+        self,
+        prompt: str,
+        model: str,
+        temperature: float,
+        max_tokens: int,
+        system_prompt: Optional[str],
+    ) -> str:
+        """Generate using Google Gemini"""
+        if not self.google_client:
+            raise RuntimeError("Google client not initialized")
+
+        try:
+            gemini_model = self.google_client.GenerativeModel(model)
+
+            generation_config = {
+                "temperature": temperature,
+                "max_output_tokens": max_tokens,
+            }
+
+            # Combine system prompt and user prompt
+            full_prompt = prompt
+            if system_prompt:
+                full_prompt = f"{system_prompt}\n\n{prompt}"
+
+            response = gemini_model.generate_content(
+                full_prompt,
+                generation_config=generation_config
+            )
+
+            return response.text
+        except Exception as e:
+            raise RuntimeError(f"Google API error: {e}")
+
+    def _generate_openai(
+        self,
+        prompt: str,
+        model: str,
+        temperature: float,
+        max_tokens: int,
+        system_prompt: Optional[str],
+    ) -> str:
+        """Generate using OpenAI"""
+        if not self.openai_client:
+            raise RuntimeError("OpenAI client not initialized")
+
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": prompt})
+
+        try:
+            response = self.openai_client.chat.completions.create(
+                model=model,
+                messages=messages,
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
+            return response.choices[0].message.content
+        except Exception as e:
+            raise RuntimeError(f"OpenAI API error: {e}")
+
+    def generate_with_memory(
+        self,
+        prompt: str,
+        context: str,
+        provider: Optional[Provider] = None,
+        model: Optional[str] = None,
+    ) -> str:
+        """
+        Generate with long context using memory model (Gemini 2.0)
+
+        Args:
+            prompt: User prompt
+            context: Long context/memory to include
+            provider: Provider to use (defaults to memory provider)
+            model: Model to use (defaults to memory model)
+
+        Returns:
+            Generated text
+        """
+        # Use memory provider by default
+        if provider is None:
+            provider = Provider(config.model.memory_provider)
+        if model is None:
+            model = config.model.memory_model
+
+        # Combine context and prompt
+        full_prompt = f"""# Campaign Context
+{context}
+
+# Current Query
+{prompt}
+
+Please answer based on the campaign context provided."""
+
+        return self.generate(
+            prompt=full_prompt,
+            provider=provider,
+            model=model,
+            temperature=config.model.balanced_temp,
+            max_tokens=config.model.max_tokens_memory,
+        )
+
+    def generate_creative(self, prompt: str, system_prompt: Optional[str] = None) -> str:
+        """Generate creative content (characters, stories, etc.)"""
+        return self.generate(
+            prompt=prompt,
+            temperature=config.model.creative_temp,
+            max_tokens=config.model.max_tokens_generation,
+            system_prompt=system_prompt,
+        )
+
+    def generate_precise(self, prompt: str, system_prompt: Optional[str] = None) -> str:
+        """Generate precise content (rules, stats, etc.)"""
+        return self.generate(
+            prompt=prompt,
+            temperature=config.model.precise_temp,
+            max_tokens=config.model.max_tokens_generation,
+            system_prompt=system_prompt,
+        )
+
+    def is_available(self, provider: Provider) -> bool:
+        """Check if provider is available"""
+        if provider == Provider.ANTHROPIC:
+            return self.anthropic_client is not None
+        elif provider == Provider.GOOGLE:
+            return self.google_client is not None
+        elif provider == Provider.OPENAI:
+            return self.openai_client is not None
+        return False
+
+
+# Global client instance
+_client: Optional[AIClient] = None
+
+
+def get_ai_client() -> AIClient:
+    """Get or create global AI client instance"""
+    global _client
+    if _client is None:
+        _client = AIClient()
+    return _client
+
+
+# Convenience functions
+def generate_text(
+    prompt: str,
+    temperature: float = 0.7,
+    max_tokens: int = 2000,
+    system_prompt: Optional[str] = None,
+) -> str:
+    """Quick text generation"""
+    client = get_ai_client()
+    return client.generate(prompt, temperature=temperature, max_tokens=max_tokens, system_prompt=system_prompt)
+
+
+def generate_creative_text(prompt: str, system_prompt: Optional[str] = None) -> str:
+    """Quick creative text generation"""
+    client = get_ai_client()
+    return client.generate_creative(prompt, system_prompt=system_prompt)
+
+
+def generate_precise_text(prompt: str, system_prompt: Optional[str] = None) -> str:
+    """Quick precise text generation"""
+    client = get_ai_client()
+    return client.generate_precise(prompt, system_prompt=system_prompt)

src/utils/character_sheet_exporter.py

@@ -0,0 +1,567 @@
+"""
+Character Sheet Export System - Generate D&D 5e Character Sheets
+Supports multiple formats: Markdown, JSON, PDF (future), PNG (future)
+"""
+
+from typing import Optional
+from pathlib import Path
+from datetime import datetime
+
+from src.models.character import Character, HIT_DICE_BY_CLASS
+
+
+class CharacterSheetExporter:
+    """Export D&D characters to various formats"""
+
+    def __init__(self):
+        self.output_dir = Path("data/exports")
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    def export_to_markdown(self, character: Character, include_portrait: bool = True) -> str:
+        """
+        Export character to detailed D&D 5e markdown format
+
+        Args:
+            character: Character to export
+            include_portrait: Whether to include portrait reference
+
+        Returns:
+            Markdown formatted character sheet
+        """
+        md = []
+
+        # Header with character name
+        md.append(f"# {character.name}")
+        md.append(f"*Level {character.level} {character.race.value} {character.character_class.value}*")
+        md.append(f"**{character.alignment.value}**")
+
+        if character.gender:
+            md.append(f"*{character.gender}*")
+
+        md.append("")
+        md.append("---")
+        md.append("")
+
+        # Portrait reference
+        if include_portrait and character.portrait_url:
+            md.append(f"![Character Portrait]({character.portrait_url})")
+            md.append("")
+
+        # Core Combat Stats
+        md.append("## ⚔️ Combat Statistics")
+        md.append("")
+        md.append(f"**Armor Class:** {character.armor_class}  ")
+        md.append(f"**Hit Points:** {character.current_hit_points} / {character.max_hit_points}  ")
+        md.append(f"**Hit Dice:** {character.level}d{HIT_DICE_BY_CLASS.get(character.character_class, 8)}  ")
+        md.append(f"**Proficiency Bonus:** +{character.proficiency_bonus}  ")
+        md.append(f"**Initiative:** {character.stats.dexterity_modifier:+d} (Dex)  ")
+        md.append(f"**Speed:** 30 ft.  ")
+        md.append(f"**Experience Points:** {character.experience_points} XP")
+        md.append("")
+
+        # Ability Scores - Clean vertical list format
+        md.append("## 💪 Ability Scores")
+        md.append("")
+
+        str_mod = character.stats.strength_modifier
+        dex_mod = character.stats.dexterity_modifier
+        con_mod = character.stats.constitution_modifier
+        int_mod = character.stats.intelligence_modifier
+        wis_mod = character.stats.wisdom_modifier
+        cha_mod = character.stats.charisma_modifier
+
+        md.append(f"- **Strength:** {character.stats.strength} ({str_mod:+d})")
+        md.append(f"- **Dexterity:** {character.stats.dexterity} ({dex_mod:+d})")
+        md.append(f"- **Constitution:** {character.stats.constitution} ({con_mod:+d})")
+        md.append(f"- **Intelligence:** {character.stats.intelligence} ({int_mod:+d})")
+        md.append(f"- **Wisdom:** {character.stats.wisdom} ({wis_mod:+d})")
+        md.append(f"- **Charisma:** {character.stats.charisma} ({cha_mod:+d})")
+        md.append("")
+
+        # Saving Throws - Clean vertical list
+        proficient_saves = [p for p in character.proficiencies if p.startswith("Saving Throws:")]
+        if proficient_saves:
+            md.append("## 🛡️ Saving Throws")
+            md.append("")
+
+            # Determine which saves get proficiency bonus
+            prof_str = "Strength" in proficient_saves[0]
+            prof_dex = "Dexterity" in proficient_saves[0]
+            prof_con = "Constitution" in proficient_saves[0]
+            prof_int = "Intelligence" in proficient_saves[0]
+            prof_wis = "Wisdom" in proficient_saves[0]
+            prof_cha = "Charisma" in proficient_saves[0]
+
+            prof_bonus = character.proficiency_bonus
+
+            str_save = str_mod + (prof_bonus if prof_str else 0)
+            dex_save = dex_mod + (prof_bonus if prof_dex else 0)
+            con_save = con_mod + (prof_bonus if prof_con else 0)
+            int_save = int_mod + (prof_bonus if prof_int else 0)
+            wis_save = wis_mod + (prof_bonus if prof_wis else 0)
+            cha_save = cha_mod + (prof_bonus if prof_cha else 0)
+
+            md.append(f"- **Strength:** {str_save:+d}{' ✓' if prof_str else ''}")
+            md.append(f"- **Dexterity:** {dex_save:+d}{' ✓' if prof_dex else ''}")
+            md.append(f"- **Constitution:** {con_save:+d}{' ✓' if prof_con else ''}")
+            md.append(f"- **Intelligence:** {int_save:+d}{' ✓' if prof_int else ''}")
+            md.append(f"- **Wisdom:** {wis_save:+d}{' ✓' if prof_wis else ''}")
+            md.append(f"- **Charisma:** {cha_save:+d}{' ✓' if prof_cha else ''}")
+            md.append("")
+            md.append("*✓ = Proficient (includes +{} proficiency bonus)*".format(prof_bonus))
+            md.append("")
+
+        # Proficiencies - separate into categories for clarity
+        md.append("## 🎯 Proficiencies")
+        md.append("")
+
+        if character.proficiencies:
+            # Group proficiencies by type
+            skills = [p for p in character.proficiencies if p.startswith("Choose") or p.startswith("Background")]
+            armor_weapons = [p for p in character.proficiencies if any(x in p for x in ["armor", "Weapons:", "weapons", "shields", "Tools:"])]
+            saves_list = [p for p in character.proficiencies if p.startswith("Saving Throws:")]
+
+            if skills:
+                md.append("### Skills")
+                for skill in skills:
+                    md.append(f"- {skill}")
+                md.append("")
+
+            if armor_weapons:
+                md.append("### Armor, Weapons & Tools")
+                for item in armor_weapons:
+                    md.append(f"- {item}")
+                md.append("")
+        else:
+            md.append("*No proficiencies listed*")
+            md.append("")
+
+        # Background
+        md.append("## 📖 Background & Personality")
+        md.append("")
+        md.append(f"**Background**: {character.background.background_type}")
+        md.append("")
+
+        if character.background.personality_traits:
+            md.append("**Personality Traits**:")
+            for trait in character.background.personality_traits:
+                md.append(f"- {trait}")
+            md.append("")
+
+        if character.background.ideals:
+            md.append(f"**Ideals**: {character.background.ideals}")
+            md.append("")
+
+        if character.background.bonds:
+            md.append(f"**Bonds**: {character.background.bonds}")
+            md.append("")
+
+        if character.background.flaws:
+            md.append(f"**Flaws**: {character.background.flaws}")
+            md.append("")
+
+        if character.background.backstory:
+            md.append("**Backstory**:")
+            md.append("")
+            md.append(character.background.backstory)
+            md.append("")
+
+        # Class Features
+        md.append("## ⚔️ Class Features")
+        md.append("")
+        if character.features:
+            for feature in character.features:
+                md.append(f"- **{feature}**")
+        else:
+            md.append("*No class features listed*")
+        md.append("")
+
+        # Equipment
+        md.append("## 🎒 Equipment")
+        md.append("")
+        if character.equipment:
+            for item in character.equipment:
+                md.append(f"- {item}")
+        else:
+            md.append("*No equipment listed*")
+        md.append("")
+
+        # Spells (if applicable)
+        if character.spells:
+            md.append("## ✨ Spells")
+            md.append("")
+            for spell in character.spells:
+                md.append(f"- {spell}")
+            md.append("")
+
+        # Notes
+        if character.notes:
+            md.append("## 📝 Notes")
+            md.append("")
+            md.append(character.notes)
+            md.append("")
+
+        # Footer
+        md.append("---")
+        md.append(f"*Character ID: {character.id}*")
+        md.append(f"*Created: {character.created_at.strftime('%Y-%m-%d %H:%M')}*")
+        md.append(f"*Last Updated: {character.updated_at.strftime('%Y-%m-%d %H:%M')}*")
+
+        return "\n".join(md)
+
+    def export_to_json(self, character: Character) -> str:
+        """
+        Export character to JSON format
+
+        Args:
+            character: Character to export
+
+        Returns:
+            JSON string
+        """
+        import json
+
+        char_dict = character.model_dump()
+
+        # Convert enums to strings for JSON serialization
+        char_dict['race'] = character.race.value
+        char_dict['character_class'] = character.character_class.value
+        char_dict['alignment'] = character.alignment.value
+
+        # Convert datetime objects
+        char_dict['created_at'] = character.created_at.isoformat()
+        char_dict['updated_at'] = character.updated_at.isoformat()
+
+        return json.dumps(char_dict, indent=2)
+
+    def export_to_html(self, character: Character) -> str:
+        """
+        Export character to styled HTML format (suitable for PDF conversion)
+
+        Args:
+            character: Character to export
+
+        Returns:
+            HTML string with embedded CSS
+        """
+        html = f"""<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <title>{character.name} - D&D 5e Character Sheet</title>
+    <style>
+        @page {{
+            size: letter;
+            margin: 0.5in;
+        }}
+
+        body {{
+            font-family: 'Bookman Old Style', 'Book Antiqua', serif;
+            max-width: 8.5in;
+            margin: 0 auto;
+            padding: 20px;
+            background: #f9f6f1;
+            color: #1a1a1a;
+        }}
+
+        .header {{
+            text-align: center;
+            border-bottom: 3px solid #8b0000;
+            padding-bottom: 10px;
+            margin-bottom: 20px;
+        }}
+
+        h1 {{
+            font-size: 32px;
+            margin: 0;
+            color: #8b0000;
+            text-transform: uppercase;
+            letter-spacing: 2px;
+        }}
+
+        .subtitle {{
+            font-size: 18px;
+            font-style: italic;
+            color: #444;
+            margin: 5px 0;
+        }}
+
+        .section {{
+            background: white;
+            border: 2px solid #8b0000;
+            border-radius: 8px;
+            padding: 15px;
+            margin: 15px 0;
+            box-shadow: 2px 2px 5px rgba(0,0,0,0.1);
+        }}
+
+        .section-title {{
+            font-size: 20px;
+            font-weight: bold;
+            color: #8b0000;
+            border-bottom: 2px solid #8b0000;
+            padding-bottom: 5px;
+            margin-bottom: 10px;
+            text-transform: uppercase;
+        }}
+
+        .stats-grid {{
+            display: grid;
+            grid-template-columns: repeat(3, 1fr);
+            gap: 10px;
+            margin: 10px 0;
+        }}
+
+        .stat-box {{
+            text-align: center;
+            background: #f0e6d6;
+            border: 2px solid #8b0000;
+            border-radius: 5px;
+            padding: 10px;
+        }}
+
+        .stat-label {{
+            font-weight: bold;
+            font-size: 12px;
+            color: #8b0000;
+            text-transform: uppercase;
+        }}
+
+        .stat-value {{
+            font-size: 24px;
+            font-weight: bold;
+            color: #1a1a1a;
+        }}
+
+        .abilities-grid {{
+            display: grid;
+            grid-template-columns: repeat(6, 1fr);
+            gap: 10px;
+            margin: 10px 0;
+        }}
+
+        .ability-box {{
+            text-align: center;
+            background: #f0e6d6;
+            border: 2px solid #8b0000;
+            border-radius: 50%;
+            padding: 15px 5px;
+            aspect-ratio: 1;
+            display: flex;
+            flex-direction: column;
+            justify-content: center;
+            align-items: center;
+        }}
+
+        .ability-name {{
+            font-weight: bold;
+            font-size: 10px;
+            color: #8b0000;
+        }}
+
+        .ability-score {{
+            font-size: 20px;
+            font-weight: bold;
+        }}
+
+        .ability-modifier {{
+            font-size: 14px;
+            color: #666;
+        }}
+
+        .list-item {{
+            padding: 5px 0;
+            border-bottom: 1px dotted #ccc;
+        }}
+
+        .list-item:last-child {{
+            border-bottom: none;
+        }}
+
+        .portrait {{
+            max-width: 200px;
+            max-height: 200px;
+            border: 3px solid #8b0000;
+            border-radius: 10px;
+            margin: 10px auto;
+            display: block;
+        }}
+
+        @media print {{
+            body {{
+                background: white;
+            }}
+            .section {{
+                page-break-inside: avoid;
+            }}
+        }}
+    </style>
+</head>
+<body>
+    <div class="header">
+        <h1>{character.name}</h1>
+        <div class="subtitle">Level {character.level} {character.race.value} {character.character_class.value}</div>
+        <div class="subtitle">{character.alignment.value}</div>
+        {f'<div class="subtitle">{character.gender}</div>' if character.gender else ''}
+    </div>
+"""
+
+        # Portrait
+        if character.portrait_url:
+            html += f'    <img src="{character.portrait_url}" class="portrait" alt="Character Portrait">\n\n'
+
+        # Core Stats
+        html += '    <div class="section">\n'
+        html += '        <div class="section-title">Core Statistics</div>\n'
+        html += '        <div class="stats-grid">\n'
+        html += f'            <div class="stat-box"><div class="stat-label">Armor Class</div><div class="stat-value">{character.armor_class}</div></div>\n'
+        html += f'            <div class="stat-box"><div class="stat-label">Hit Points</div><div class="stat-value">{character.current_hit_points}/{character.max_hit_points}</div></div>\n'
+        html += f'            <div class="stat-box"><div class="stat-label">Hit Dice</div><div class="stat-value">{character.level}d{HIT_DICE_BY_CLASS.get(character.character_class, 8)}</div></div>\n'
+        html += f'            <div class="stat-box"><div class="stat-label">Prof. Bonus</div><div class="stat-value">+{character.proficiency_bonus}</div></div>\n'
+        html += f'            <div class="stat-box"><div class="stat-label">Speed</div><div class="stat-value">30 ft</div></div>\n'
+        html += f'            <div class="stat-box"><div class="stat-label">Initiative</div><div class="stat-value">{character.stats.dexterity_modifier:+d}</div></div>\n'
+        html += '        </div>\n'
+        html += '    </div>\n\n'
+
+        # Ability Scores
+        html += '    <div class="section">\n'
+        html += '        <div class="section-title">Ability Scores</div>\n'
+        html += '        <div class="abilities-grid">\n'
+
+        abilities = [
+            ("STR", character.stats.strength, character.stats.strength_modifier),
+            ("DEX", character.stats.dexterity, character.stats.dexterity_modifier),
+            ("CON", character.stats.constitution, character.stats.constitution_modifier),
+            ("INT", character.stats.intelligence, character.stats.intelligence_modifier),
+            ("WIS", character.stats.wisdom, character.stats.wisdom_modifier),
+            ("CHA", character.stats.charisma, character.stats.charisma_modifier),
+        ]
+
+        for name, score, mod in abilities:
+            html += f'            <div class="ability-box">\n'
+            html += f'                <div class="ability-name">{name}</div>\n'
+            html += f'                <div class="ability-score">{score}</div>\n'
+            html += f'                <div class="ability-modifier">({mod:+d})</div>\n'
+            html += f'            </div>\n'
+
+        html += '        </div>\n'
+        html += '    </div>\n\n'
+
+        # Skills & Proficiencies
+        if character.proficiencies:
+            html += '    <div class="section">\n'
+            html += '        <div class="section-title">Skills & Proficiencies</div>\n'
+            for prof in character.proficiencies:
+                html += f'        <div class="list-item">✓ {prof}</div>\n'
+            html += '    </div>\n\n'
+
+        # Features
+        if character.features:
+            html += '    <div class="section">\n'
+            html += '        <div class="section-title">Class Features</div>\n'
+            for feature in character.features:
+                html += f'        <div class="list-item"><strong>{feature}</strong></div>\n'
+            html += '    </div>\n\n'
+
+        # Equipment
+        if character.equipment:
+            html += '    <div class="section">\n'
+            html += '        <div class="section-title">Equipment</div>\n'
+            for item in character.equipment:
+                html += f'        <div class="list-item">{item}</div>\n'
+            html += '    </div>\n\n'
+
+        # Background
+        html += '    <div class="section">\n'
+        html += '        <div class="section-title">Background & Personality</div>\n'
+        html += f'        <p><strong>Background:</strong> {character.background.background_type}</p>\n'
+
+        if character.background.personality_traits:
+            html += '        <p><strong>Personality Traits:</strong></p><ul>\n'
+            for trait in character.background.personality_traits:
+                html += f'            <li>{trait}</li>\n'
+            html += '        </ul>\n'
+
+        if character.background.ideals:
+            html += f'        <p><strong>Ideals:</strong> {character.background.ideals}</p>\n'
+
+        if character.background.bonds:
+            html += f'        <p><strong>Bonds:</strong> {character.background.bonds}</p>\n'
+
+        if character.background.flaws:
+            html += f'        <p><strong>Flaws:</strong> {character.background.flaws}</p>\n'
+
+        if character.background.backstory:
+            html += f'        <p><strong>Backstory:</strong></p>\n'
+            html += f'        <p>{character.background.backstory}</p>\n'
+
+        html += '    </div>\n\n'
+
+        # Spells
+        if character.spells:
+            html += '    <div class="section">\n'
+            html += '        <div class="section-title">Spells</div>\n'
+            for spell in character.spells:
+                html += f'        <div class="list-item">{spell}</div>\n'
+            html += '    </div>\n\n'
+
+        # Footer
+        html += '    <div style="text-align: center; margin-top: 30px; font-size: 12px; color: #666;">\n'
+        html += f'        <p>Character ID: {character.id}</p>\n'
+        html += f'        <p>Created: {character.created_at.strftime("%Y-%m-%d %H:%M")} | '
+        html += f'Last Updated: {character.updated_at.strftime("%Y-%m-%d %H:%M")}</p>\n'
+        html += '        <p><em>Generated by D\'n\'D Campaign Manager</em></p>\n'
+        html += '    </div>\n'
+
+        html += '</body>\n</html>'
+
+        return html
+
+    def save_export(self, character: Character, format: str = "markdown") -> str:
+        """
+        Save character sheet to file
+
+        Args:
+            character: Character to export
+            format: Export format ('markdown', 'json', 'html')
+
+        Returns:
+            Path to saved file
+        """
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        safe_name = "".join(c if c.isalnum() or c in (' ', '_') else '_' for c in character.name)
+        safe_name = safe_name.replace(' ', '_')
+
+        if format == "markdown":
+            content = self.export_to_markdown(character)
+            filename = f"{safe_name}_{timestamp}.md"
+            extension = ".md"
+        elif format == "json":
+            content = self.export_to_json(character)
+            filename = f"{safe_name}_{timestamp}.json"
+            extension = ".json"
+        elif format == "html":
+            content = self.export_to_html(character)
+            filename = f"{safe_name}_{timestamp}.html"
+            extension = ".html"
+        else:
+            raise ValueError(f"Unknown format: {format}")
+
+        file_path = self.output_dir / filename
+
+        with open(file_path, 'w', encoding='utf-8') as f:
+            f.write(content)
+
+        return str(file_path)
+
+
+# Global instance
+_exporter: Optional[CharacterSheetExporter] = None
+
+
+def get_exporter() -> CharacterSheetExporter:
+    """Get or create global exporter instance"""
+    global _exporter
+    if _exporter is None:
+        _exporter = CharacterSheetExporter()
+    return _exporter

src/utils/database.py

@@ -0,0 +1,227 @@
+"""
+Database utilities for SQLite persistence
+Simple key-value storage with JSON serialization
+"""
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Optional, Any, List, Dict
+from datetime import datetime
+
+from src.config import config
+
+
+class Database:
+    """Simple SQLite database for campaign data"""
+
+    def __init__(self, db_path: Optional[Path] = None):
+        """Initialize database connection"""
+        self.db_path = db_path or config.database.db_path
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self.conn: Optional[sqlite3.Connection] = None
+        self._initialize()
+
+    def _initialize(self):
+        """Initialize database and create tables"""
+        self.conn = sqlite3.connect(str(self.db_path), check_same_thread=False)
+        self.conn.row_factory = sqlite3.Row
+
+        # Create tables
+        self._create_tables()
+
+    def _create_tables(self):
+        """Create database tables"""
+        cursor = self.conn.cursor()
+
+        # Generic key-value store with type
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS entities (
+                id TEXT PRIMARY KEY,
+                type TEXT NOT NULL,
+                data TEXT NOT NULL,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+
+        # Index for faster lookups
+        cursor.execute("""
+            CREATE INDEX IF NOT EXISTS idx_entities_type ON entities(type)
+        """)
+
+        # Campaign events for memory
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS campaign_events (
+                id TEXT PRIMARY KEY,
+                campaign_id TEXT NOT NULL,
+                session_number INTEGER NOT NULL,
+                event_type TEXT NOT NULL,
+                data TEXT NOT NULL,
+                importance INTEGER DEFAULT 3,
+                timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                FOREIGN KEY (campaign_id) REFERENCES entities(id)
+            )
+        """)
+
+        cursor.execute("""
+            CREATE INDEX IF NOT EXISTS idx_events_campaign ON campaign_events(campaign_id)
+        """)
+
+        self.conn.commit()
+
+    def save(self, entity_id: str, entity_type: str, data: Dict[str, Any]):
+        """Save entity to database"""
+        cursor = self.conn.cursor()
+
+        # Serialize data to JSON
+        json_data = json.dumps(data, default=str)
+
+        cursor.execute("""
+            INSERT OR REPLACE INTO entities (id, type, data, updated_at)
+            VALUES (?, ?, ?, CURRENT_TIMESTAMP)
+        """, (entity_id, entity_type, json_data))
+
+        self.conn.commit()
+
+    def load(self, entity_id: str, entity_type: Optional[str] = None) -> Optional[Dict[str, Any]]:
+        """Load entity from database"""
+        cursor = self.conn.cursor()
+
+        if entity_type:
+            cursor.execute("""
+                SELECT data FROM entities WHERE id = ? AND type = ?
+            """, (entity_id, entity_type))
+        else:
+            cursor.execute("""
+                SELECT data FROM entities WHERE id = ?
+            """, (entity_id,))
+
+        row = cursor.fetchone()
+        if row:
+            return json.loads(row['data'])
+        return None
+
+    def load_all(self, entity_type: str) -> List[Dict[str, Any]]:
+        """Load all entities of a specific type"""
+        cursor = self.conn.cursor()
+
+        cursor.execute("""
+            SELECT data FROM entities WHERE type = ?
+            ORDER BY updated_at DESC
+        """, (entity_type,))
+
+        return [json.loads(row['data']) for row in cursor.fetchall()]
+
+    def delete(self, entity_id: str):
+        """Delete entity from database"""
+        cursor = self.conn.cursor()
+
+        cursor.execute("""
+            DELETE FROM entities WHERE id = ?
+        """, (entity_id,))
+
+        self.conn.commit()
+
+    def search(self, entity_type: str, query: str, limit: int = 10) -> List[Dict[str, Any]]:
+        """Simple text search in entity data"""
+        cursor = self.conn.cursor()
+
+        cursor.execute("""
+            SELECT data FROM entities
+            WHERE type = ? AND data LIKE ?
+            ORDER BY updated_at DESC
+            LIMIT ?
+        """, (entity_type, f"%{query}%", limit))
+
+        return [json.loads(row['data']) for row in cursor.fetchall()]
+
+    # Campaign Events specific methods
+    def save_campaign_event(self, event_data: Dict[str, Any]):
+        """Save campaign event for memory"""
+        cursor = self.conn.cursor()
+
+        cursor.execute("""
+            INSERT INTO campaign_events
+            (id, campaign_id, session_number, event_type, data, importance)
+            VALUES (?, ?, ?, ?, ?, ?)
+        """, (
+            event_data['id'],
+            event_data['campaign_id'],
+            event_data['session_number'],
+            event_data['event_type'],
+            json.dumps(event_data, default=str),
+            event_data.get('importance', 3)
+        ))
+
+        self.conn.commit()
+
+    def load_campaign_events(
+        self,
+        campaign_id: str,
+        session_number: Optional[int] = None,
+        limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """Load campaign events for memory context"""
+        cursor = self.conn.cursor()
+
+        query = """
+            SELECT data FROM campaign_events
+            WHERE campaign_id = ?
+        """
+        params = [campaign_id]
+
+        if session_number:
+            query += " AND session_number = ?"
+            params.append(session_number)
+
+        query += " ORDER BY timestamp DESC"
+
+        if limit:
+            query += " LIMIT ?"
+            params.append(limit)
+
+        cursor.execute(query, params)
+
+        return [json.loads(row['data']) for row in cursor.fetchall()]
+
+    def get_campaign_context(self, campaign_id: str, max_events: int = 50) -> str:
+        """Get formatted campaign context for AI"""
+        events = self.load_campaign_events(campaign_id, limit=max_events)
+
+        if not events:
+            return "No campaign history yet."
+
+        context_parts = ["# Campaign History\n"]
+
+        for event in reversed(events):  # Chronological order
+            context_parts.append(f"## Session {event['session_number']}: {event['title']}")
+            context_parts.append(f"**Type:** {event['event_type']}")
+            context_parts.append(f"{event['description']}\n")
+
+        return "\n".join(context_parts)
+
+    def close(self):
+        """Close database connection"""
+        if self.conn:
+            self.conn.close()
+
+    def __enter__(self):
+        """Context manager entry"""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit"""
+        self.close()
+
+
+# Global database instance
+_database: Optional[Database] = None
+
+
+def get_database() -> Database:
+    """Get or create global database instance"""
+    global _database
+    if _database is None:
+        _database = Database()
+    return _database

src/utils/dice.py

@@ -0,0 +1,151 @@
+"""
+Dice rolling utilities for D&D
+"""
+
+import random
+import re
+from typing import List, Tuple, Optional
+
+
+class DiceRoller:
+    """D&D dice roller with standard notation support"""
+
+    @staticmethod
+    def roll(notation: str) -> Tuple[int, List[int], str]:
+        """
+        Roll dice using standard notation (e.g., "2d6+3", "1d20", "4d6kh3")
+
+        Returns:
+            Tuple of (total, individual_rolls, explanation)
+        """
+        notation = notation.lower().strip()
+
+        # Parse notation: XdY+Z or XdY-Z or XdYkhN (keep highest N)
+        match = re.match(r'(\d+)?d(\d+)(?:kh(\d+))?([+-]\d+)?', notation)
+
+        if not match:
+            raise ValueError(f"Invalid dice notation: {notation}")
+
+        num_dice = int(match.group(1)) if match.group(1) else 1
+        die_size = int(match.group(2))
+        keep_highest = int(match.group(3)) if match.group(3) else None
+        modifier = int(match.group(4)) if match.group(4) else 0
+
+        # Validate
+        if num_dice < 1 or num_dice > 100:
+            raise ValueError("Number of dice must be between 1 and 100")
+        if die_size < 1 or die_size > 1000:
+            raise ValueError("Die size must be between 1 and 1000")
+
+        # Roll dice
+        rolls = [random.randint(1, die_size) for _ in range(num_dice)]
+
+        # Apply keep highest
+        if keep_highest:
+            if keep_highest >= num_dice:
+                kept_rolls = rolls
+            else:
+                sorted_rolls = sorted(rolls, reverse=True)
+                kept_rolls = sorted_rolls[:keep_highest]
+                dropped_rolls = sorted_rolls[keep_highest:]
+                explanation = f"Rolled {rolls}, kept {kept_rolls}, dropped {dropped_rolls}"
+        else:
+            kept_rolls = rolls
+            explanation = f"Rolled {rolls}"
+
+        total = sum(kept_rolls) + modifier
+
+        if modifier != 0:
+            explanation += f" {'+' if modifier > 0 else ''}{modifier} = {total}"
+        else:
+            explanation += f" = {total}"
+
+        return total, rolls, explanation
+
+    @staticmethod
+    def roll_stat() -> int:
+        """Roll a D&D ability score (4d6 keep highest 3)"""
+        total, _, _ = DiceRoller.roll("4d6kh3")
+        return total
+
+    @staticmethod
+    def roll_stats() -> dict:
+        """Roll a complete set of D&D ability scores"""
+        return {
+            "strength": DiceRoller.roll_stat(),
+            "dexterity": DiceRoller.roll_stat(),
+            "constitution": DiceRoller.roll_stat(),
+            "intelligence": DiceRoller.roll_stat(),
+            "wisdom": DiceRoller.roll_stat(),
+            "charisma": DiceRoller.roll_stat(),
+        }
+
+    @staticmethod
+    def advantage(notation: str = "1d20") -> Tuple[int, List[int], str]:
+        """Roll with advantage (roll twice, take higher)"""
+        result1, rolls1, _ = DiceRoller.roll(notation)
+        result2, rolls2, _ = DiceRoller.roll(notation)
+
+        if result1 >= result2:
+            return result1, rolls1, f"Advantage: rolled {rolls1} and {rolls2}, kept {result1}"
+        else:
+            return result2, rolls2, f"Advantage: rolled {rolls1} and {rolls2}, kept {result2}"
+
+    @staticmethod
+    def disadvantage(notation: str = "1d20") -> Tuple[int, List[int], str]:
+        """Roll with disadvantage (roll twice, take lower)"""
+        result1, rolls1, _ = DiceRoller.roll(notation)
+        result2, rolls2, _ = DiceRoller.roll(notation)
+
+        if result1 <= result2:
+            return result1, rolls1, f"Disadvantage: rolled {rolls1} and {rolls2}, kept {result1}"
+        else:
+            return result2, rolls2, f"Disadvantage: rolled {rolls1} and {rolls2}, kept {result2}"
+
+    @staticmethod
+    def roll_initiative(dex_modifier: int = 0) -> Tuple[int, str]:
+        """Roll initiative with dexterity modifier"""
+        result, rolls, _ = DiceRoller.roll("1d20")
+        total = result + dex_modifier
+        return total, f"Initiative: {rolls[0]} + {dex_modifier} = {total}"
+
+    @staticmethod
+    def roll_hit_points(hit_die: int, constitution_modifier: int, level: int) -> int:
+        """
+        Roll hit points for a character
+        First level: max hit die + con mod
+        Subsequent levels: roll hit die + con mod
+        """
+        if level < 1:
+            raise ValueError("Level must be at least 1")
+
+        # First level gets max
+        hp = hit_die + constitution_modifier
+
+        # Roll for subsequent levels
+        for _ in range(level - 1):
+            roll, _, _ = DiceRoller.roll(f"1d{hit_die}")
+            hp += roll + constitution_modifier
+
+        return max(1, hp)  # Minimum 1 HP
+
+
+# Convenience functions
+def roll(notation: str) -> Tuple[int, List[int], str]:
+    """Roll dice using standard notation"""
+    return DiceRoller.roll(notation)
+
+
+def roll_stats() -> dict:
+    """Roll complete set of ability scores"""
+    return DiceRoller.roll_stats()
+
+
+def roll_with_advantage(notation: str = "1d20") -> Tuple[int, List[int], str]:
+    """Roll with advantage"""
+    return DiceRoller.advantage(notation)
+
+
+def roll_with_disadvantage(notation: str = "1d20") -> Tuple[int, List[int], str]:
+    """Roll with disadvantage"""
+    return DiceRoller.disadvantage(notation)

src/utils/file_parsers.py

@@ -0,0 +1,125 @@
+"""
+File Parsing Utilities for Session Notes Upload
+Supports: .txt, .md, .docx, .pdf
+"""
+from pathlib import Path
+from typing import Optional
+
+
+def parse_uploaded_file(file_path: str) -> str:
+    """
+    Parse uploaded session notes file and extract text content.
+
+    Supported formats:
+    - .txt - Plain text
+    - .md - Markdown
+    - .docx - Microsoft Word (requires python-docx)
+    - .pdf - PDF documents (requires PyPDF2)
+
+    Args:
+        file_path: Path to uploaded file
+
+    Returns:
+        Extracted text content as string
+
+    Raises:
+        ValueError: If file type is not supported
+        Exception: If file parsing fails
+    """
+    path = Path(file_path)
+    extension = path.suffix.lower()
+
+    # Plain text and markdown (simple read)
+    if extension in ['.txt', '.md']:
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                return f.read()
+        except UnicodeDecodeError:
+            # Try with different encoding if UTF-8 fails
+            with open(file_path, 'r', encoding='latin-1') as f:
+                return f.read()
+
+    # Microsoft Word documents
+    elif extension == '.docx':
+        try:
+            import docx
+            doc = docx.Document(file_path)
+            paragraphs = [para.text for para in doc.paragraphs]
+            return '\n'.join(paragraphs)
+        except ImportError:
+            raise ImportError(
+                "python-docx is required to parse .docx files. "
+                "Install with: pip install python-docx"
+            )
+        except Exception as e:
+            raise Exception(f"Error parsing .docx file: {str(e)}")
+
+    # PDF documents
+    elif extension == '.pdf':
+        try:
+            import PyPDF2
+            text_content = []
+
+            with open(file_path, 'rb') as f:
+                pdf_reader = PyPDF2.PdfReader(f)
+
+                for page in pdf_reader.pages:
+                    text = page.extract_text()
+                    if text:
+                        text_content.append(text)
+
+            return '\n'.join(text_content)
+
+        except ImportError:
+            raise ImportError(
+                "PyPDF2 is required to parse .pdf files. "
+                "Install with: pip install PyPDF2"
+            )
+        except Exception as e:
+            raise Exception(f"Error parsing .pdf file: {str(e)}")
+
+    else:
+        raise ValueError(
+            f"Unsupported file type: {extension}. "
+            f"Supported formats: .txt, .md, .docx, .pdf"
+        )
+
+
+def validate_file_size(file_path: str, max_size_mb: int = 10) -> bool:
+    """
+    Validate that file size is within acceptable limits.
+
+    Args:
+        file_path: Path to file
+        max_size_mb: Maximum file size in megabytes (default: 10 MB)
+
+    Returns:
+        True if file size is acceptable, False otherwise
+    """
+    path = Path(file_path)
+
+    if not path.exists():
+        return False
+
+    file_size_mb = path.stat().st_size / (1024 * 1024)
+    return file_size_mb <= max_size_mb
+
+
+def get_file_info(file_path: str) -> dict:
+    """
+    Get information about uploaded file.
+
+    Args:
+        file_path: Path to file
+
+    Returns:
+        Dictionary with file information
+    """
+    path = Path(file_path)
+
+    return {
+        'name': path.name,
+        'extension': path.suffix.lower(),
+        'size_bytes': path.stat().st_size,
+        'size_mb': round(path.stat().st_size / (1024 * 1024), 2)
+    }

src/utils/image_generator.py

@@ -0,0 +1,590 @@
+"""
+Image Generation Utility - DALL-E 3 Integration for Character Portraits
+"""
+
+import os
+import base64
+from typing import Optional, Tuple, Literal
+from pathlib import Path
+import requests
+from io import BytesIO
+import openai
+from openai import OpenAI
+
+from src.config import config
+from src.models.character import Character, DnDRace, DnDClass
+
+ImageProvider = Literal["openai", "huggingface", "auto"]
+
+# Skin tone options by race (3-5 options each)
+RACE_SKIN_TONES = {
+    DnDRace.HUMAN: [
+        "Fair/Pale",
+        "Light",
+        "Medium/Olive",
+        "Tan/Brown",
+        "Deep/Dark"
+    ],
+    DnDRace.ELF: [
+        "Pale/Moonlight",
+        "Porcelain",
+        "Honey/Golden",
+        "Bronze",
+        "Dark Copper"
+    ],
+    DnDRace.DWARF: [
+        "Ruddy/Tan",
+        "Bronze",
+        "Deep Brown",
+        "Stone Gray"
+    ],
+    DnDRace.HALFLING: [
+        "Fair/Rosy",
+        "Light Tan",
+        "Medium Brown",
+        "Dark Brown"
+    ],
+    DnDRace.DRAGONBORN: [
+        "Brass (Golden)",
+        "Copper (Reddish)",
+        "Bronze (Brown)",
+        "Silver (Silvery)",
+        "Red (Crimson)",
+        "Blue (Sapphire)",
+        "Green (Emerald)",
+        "Black (Obsidian)",
+        "White (Pearl)"
+    ],
+    DnDRace.GNOME: [
+        "Fair/Pink",
+        "Tan/Sandy",
+        "Light Brown",
+        "Deep Brown"
+    ],
+    DnDRace.HALF_ELF: [
+        "Fair",
+        "Light Olive",
+        "Medium Tan",
+        "Brown",
+        "Dark"
+    ],
+    DnDRace.HALF_ORC: [
+        "Gray-Green",
+        "Olive-Green",
+        "Deep Green",
+        "Gray-Brown"
+    ],
+    DnDRace.TIEFLING: [
+        "Red",
+        "Purple",
+        "Blue-Gray",
+        "Dark Gray",
+        "Pink-Red"
+    ],
+    DnDRace.DROW: [
+        "Dark Gray",
+        "Purple-Black",
+        "Blue-Black",
+        "Obsidian Black"
+    ]
+}
+
+
+class ImageGenerator:
+    """Generate character portraits using DALL-E 3 or HuggingFace Inference"""
+
+    def __init__(self):
+        """Initialize image generator with available providers"""
+        self.openai_api_key = config.openai_api_key
+        self.hf_api_key = config.huggingface_api_key
+
+        self.output_dir = Path("data/portraits")
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+        # HuggingFace model for fallback (Stable Diffusion XL)
+        self.hf_model = "stabilityai/stable-diffusion-xl-base-1.0"
+
+        # Check available providers
+        self.has_openai = bool(self.openai_api_key)
+        self.has_hf = bool(self.hf_api_key)
+
+        if not self.has_openai and not self.has_hf:
+            raise ValueError(
+                "No image generation API keys found. "
+                "Please add OPENAI_API_KEY or HUGGINGFACE_API_KEY to your .env file"
+            )
+
+    def generate_character_portrait(
+        self,
+        character: Character,
+        style: str = "fantasy art",
+        quality: str = "standard",
+        size: str = "1024x1024",
+        provider: ImageProvider = "auto"
+    ) -> Tuple[Optional[str], Optional[bytes]]:
+        """
+        Generate a character portrait using DALL-E 3 or HuggingFace
+
+        Args:
+            character: Character object with full details
+            style: Art style (e.g., "fantasy art", "digital painting", "anime")
+            quality: Image quality ("standard" or "hd") - OpenAI only
+            size: Image size ("1024x1024", "1024x1792", "1792x1024")
+            provider: "openai", "huggingface", or "auto" (tries OpenAI first, falls back to HF)
+
+        Returns:
+            Tuple of (file_path, image_bytes)
+        """
+        # Build detailed prompt from character
+        prompt = self._build_character_prompt(character, style)
+
+        # Determine which provider to use
+        if provider == "auto":
+            # Try OpenAI first, fallback to HuggingFace
+            if self.has_openai:
+                try:
+                    image_bytes = self._generate_image_openai(prompt, quality, size)
+                except Exception as openai_error:
+                    print(f"OpenAI failed: {openai_error}")
+                    if self.has_hf:
+                        print("Falling back to HuggingFace Inference...")
+                        image_bytes = self._generate_image_huggingface(prompt)
+                    else:
+                        raise  # Re-raise OpenAI error if no fallback
+            elif self.has_hf:
+                image_bytes = self._generate_image_huggingface(prompt)
+            else:
+                raise ValueError("No image generation provider available")
+
+        elif provider == "openai":
+            if not self.has_openai:
+                raise ValueError("OpenAI API key not configured")
+            image_bytes = self._generate_image_openai(prompt, quality, size)
+
+        elif provider == "huggingface":
+            if not self.has_hf:
+                raise ValueError("HuggingFace API key not configured")
+            image_bytes = self._generate_image_huggingface(prompt)
+
+        else:
+            raise ValueError(f"Unknown provider: {provider}")
+
+        if image_bytes:
+            # Save to file
+            filename = f"{character.id}_portrait.png"
+            file_path = self.output_dir / filename
+
+            with open(file_path, 'wb') as f:
+                f.write(image_bytes)
+
+            return str(file_path), image_bytes
+
+        return None, None
+
+    def generate_custom_portrait(
+        self,
+        prompt: str,
+        character_id: Optional[str] = None,
+        quality: str = "standard",
+        size: str = "1024x1024"
+    ) -> Tuple[Optional[str], Optional[bytes]]:
+        """
+        Generate a portrait from custom prompt
+
+        Args:
+            prompt: Custom DALL-E prompt
+            character_id: Optional character ID for filename
+            quality: Image quality
+            size: Image size
+
+        Returns:
+            Tuple of (file_path, image_bytes)
+        """
+        try:
+            image_bytes = self._generate_image(prompt, quality, size)
+
+            if image_bytes:
+                # Save to file
+                if character_id:
+                    filename = f"{character_id}_custom_portrait.png"
+                else:
+                    import uuid
+                    filename = f"portrait_{uuid.uuid4().hex[:8]}.png"
+
+                file_path = self.output_dir / filename
+
+                with open(file_path, 'wb') as f:
+                    f.write(image_bytes)
+
+                return str(file_path), image_bytes
+
+            return None, None
+
+        except Exception as e:
+            print(f"Error generating custom image: {e}")
+            return None, None
+
+    def _build_character_prompt(self, character: Character, style: str) -> str:
+        """
+        Build detailed DALL-E prompt from character data
+
+        Includes race, class, gender, alignment, skin tone, physical description
+        """
+        # Base description
+        parts = []
+
+        # Rich style prefix
+        parts.append(f"Highly detailed {style} character portrait,")
+
+        # Determine gender for trait customization
+        character_gender = None
+        if hasattr(character, 'gender') and character.gender and character.gender != "Not specified":
+            character_gender = character.gender.lower()
+
+        # Build VERY strong gender emphasis
+        gender_prefix = ""
+        gender_features = ""
+
+        if character_gender == "female":
+            gender_prefix = "BEAUTIFUL FEMININE FEMALE WOMAN"
+            gender_features = "distinctly feminine facial features, soft feminine jawline, delicate bone structure, graceful feminine appearance"
+        elif character_gender == "male":
+            gender_prefix = "HANDSOME MASCULINE MALE MAN"
+            gender_features = "distinctly masculine facial features, strong masculine jawline, defined bone structure, rugged masculine appearance"
+        elif character_gender:
+            gender_prefix = character_gender.upper()
+            gender_features = "unique facial features"
+        else:
+            gender_prefix = "PERSON"
+            gender_features = "expressive facial features"
+
+        # Get skin tone with STRONG emphasis
+        skin_emphasis = ""
+        if hasattr(character, 'skin_tone') and character.skin_tone:
+            # Make skin tone VERY prominent
+            skin_emphasis = f"WITH {character.skin_tone.upper()} COLORED SKIN,"
+
+        # Build the core character description
+        parts.append(f"{gender_prefix} {character.race.value.upper()} {character.character_class.value.upper()} {skin_emphasis}")
+
+        # Add gender-specific features and race traits (passing gender for customization)
+        race_traits = self._get_race_traits(character.race, character_gender)
+        parts.append(f"{gender_features}, {race_traits},")
+
+        # Rich class-specific elements
+        class_elements = self._get_class_elements(character.character_class)
+        parts.append(f"{class_elements},")
+
+        # Alignment influence
+        alignment_mood = self._get_alignment_mood(character.alignment.value)
+        if alignment_mood:
+            parts.append(f"{alignment_mood},")
+
+        # Rich artistic details with gender reinforcement
+        parts.append("epic fantasy character portrait, professional illustration,")
+        if character_gender == "female":
+            parts.append("CLEARLY FEMALE CHARACTER, feminine beauty,")
+        elif character_gender == "male":
+            parts.append("CLEARLY MALE CHARACTER, masculine presence,")
+
+        parts.append("highly detailed face with intricate features, expressive eyes,")
+        parts.append("dramatic cinematic lighting with rim light, volumetric atmosphere,")
+        parts.append("sharp focus on facial features and expression,")
+        parts.append(f"masterpiece quality {style} artwork, trending on artstation, 8k resolution")
+
+        prompt = " ".join(parts)
+
+        # Ensure prompt isn't too long (DALL-E 3 has 4000 char limit)
+        if len(prompt) > 3000:
+            print(f"⚠️ Warning: Prompt truncated from {len(prompt)} to 3000 characters")
+            prompt = prompt[:3000]
+
+        return prompt
+
+    def _get_race_traits(self, race: DnDRace, gender: Optional[str] = None) -> str:
+        """Get ultra-detailed physical traits for race with gender-appropriate descriptions"""
+
+        if gender == "female":
+            traits = {
+                DnDRace.HUMAN: "FEMININE WOMAN with expressive almond or round eyes showing depth and intelligence, natural human facial proportions with soft cheekbones, graceful jawline, delicate yet strong features, smooth skin with subtle weathering from adventure, diverse beauty with character lines from experience, warm approachable mouth with natural lips, well-defined brow expressing emotion, elegant neck, hair framing face naturally (flowing, braided, or practical), subtle beauty marks or freckles adding character, human versatility and adaptability shown in features, CLEARLY FEMALE facial structure",
+
+                DnDRace.ELF: "FEMININE ELVEN WOMAN with long gracefully pointed ears swept back, sharp elegant angular features showing timeless beauty, almond-shaped luminous eyes with otherworldly gaze (colors like silver, gold, violet, or emerald), impossibly high sculpted cheekbones, delicate pointed chin, slender refined nose, soft bow-shaped lips, smooth porcelain-like skin with ageless quality, flowing silken hair (often silver, gold, auburn, or raven) cascading past shoulders or in elaborate braids, ethereal feminine grace, elegant arched eyebrows, slender graceful neck, mystical fey beauty radiating ancient wisdom, subtle glow to skin, CLEARLY FEMALE ELF with otherworldly elegance",
+
+                DnDRace.DWARF: "FEMININE DWARVEN WOMAN with strong beautiful features, thick lustrous hair in elaborate braids adorned with metal rings and gemstones, fierce intelligent eyes showing determination and warmth, pronounced cheekbones with weathered sun-kissed complexion, broad but feminine jawline, strong nose with character, full lips often set in confident expression, weathered skin from forge work and mountain living showing texture and history, ornate beard jewelry or traditional face tattoos (cultural choice), powerful neck and shoulders showing strength, earthen beauty combining power and femininity, hair in rich colors (copper, bronze, black, auburn), skin with ruddy or bronze undertones, CLEARLY FEMALE DWARF with warrior-artisan beauty",
+
+                DnDRace.HALFLING: "FEMININE HALFLING WOMAN with round friendly face showing youthful charm, large bright cheerful eyes (often hazel, brown, or green) sparkling with warmth and curiosity, naturally rosy cheeks with healthy glow, button nose, sweet gentle smile with dimples, soft rounded chin, curly or wavy tousled hair in warm colors (brown, auburn, golden, chestnut), smooth skin with youthful texture, delicate pointed ears (smaller than elves), laugh lines from joyful life, slightly plump cherubic features, cozy homely beauty radiating kindness, hair often adorned with flowers or ribbons, CLEARLY FEMALE HALFLING with welcoming maternal energy",
+
+                DnDRace.DRAGONBORN: "FEMININE DRAGONBORN WOMAN with elegant draconic head featuring graceful reptilian features, sleek scaled skin covering face and neck with metallic or chromatic sheen matching dragon ancestry, fierce yet intelligent eyes with slit pupils glowing with inner fire, refined snout with noble profile, sharp teeth visible when speaking, pronounced facial ridges and horns sweeping back elegantly, scales with iridescent quality catching light beautifully, no hair but decorative horn jewelry or scale paint, expressive eye ridges conveying emotion, strong graceful neck with visible scale texture, regal bearing combining dragon majesty with feminine grace, face scales in beautiful patterns, CLEARLY FEMALE DRAGONBORN with powerful elegant beauty",
+
+                DnDRace.GNOME: "FEMININE GNOME WOMAN with large expressive eyes full of endless curiosity and mischief (often in unusual colors like amber, turquoise, or violet), delicate upturned pointed nose, wild energetic hair in vibrant colors (pink, green, blue, purple, or natural tones) styled chaotically or with practical clips, mischievous playful grin showing cleverness, soft cheeks with youthful appearance, pointed chin, arched expressive eyebrows always moving with thought, smooth skin often smudged with grease or colored powder, tiny adorable ears, laugh lines around eyes from constant amusement, face showing brilliant intellect and creative energy, often wearing magnifying goggles or spectacles pushed up, CLEARLY FEMALE GNOME with inventive spirited beauty",
+
+                DnDRace.HALF_ELF: "FEMININE HALF-ELF WOMAN with subtly pointed ears (shorter than full elves), beautiful blend of human warmth and elven ethereal grace, refined yet approachable facial features, high but not extreme cheekbones, expressive eyes with hint of otherworldly luminescence (various colors with subtle glow), elegant straight nose between human and elven, soft lips with gentle smile, smooth skin with light natural glow, flowing hair in diverse colors showing mixed heritage, graceful neck and shoulders, features combining best of both ancestries, slightly elongated facial proportions, eyebrows with elegant arch, skin texture between human and elven smoothness, versatile beauty adaptable to any culture, CLEARLY FEMALE HALF-ELF with hybrid enchanting beauty",
+
+                DnDRace.HALF_ORC: "BEAUTIFUL FEMININE HALF-ORC WOMAN, CLEARLY FEMALE WARRIOR WOMAN, delicate small lower canines (petite feminine tusks barely visible), SOFT FEMININE FACIAL FEATURES with graceful cheekbones, FEMININE JAWLINE strong but elegant, fierce intelligent eyes showing both strength and compassion (colors like amber, green, brown), slightly prominent brow ridge adding character not masculinity, FEMININE NOSE with strong bridge, full lips with natural beauty, SMOOTH SKIN with greenish or grayish undertones (matching selected skin tone), LONG FLOWING HAIR in warrior braids or wild mane (black, brown, auburn, or dark green), graceful neck showing both power and femininity, war paint or tribal markings enhancing feminine beauty, ATHLETIC FEMININE PHYSIQUE radiating strength and grace, DISTINCTLY FEMALE ORC-BLOODED BEAUTY, warrior goddess appearance combining fierceness with unmistakable femininity, scarring or battle marks adding to beauty not diminishing it, WOMAN HALF-ORC FEMALE",
+
+                DnDRace.TIEFLING: "FEMININE TIEFLING WOMAN with elegant curved horns sweeping back from forehead or temples (ram-like, gazelle-like, or demonic style) adorned with jewelry, long graceful pointed tail often visible, exotic glowing eyes without pupils (colors like molten gold, burning silver, fiery red, violet, or emerald), sharp elegant cheekbones, delicate pointed chin, soft lips with hint of sharp canine teeth visible when smiling, EXOTIC SKIN in vibrant colors (deep crimson, wine red, purple, blue-gray, pink-red, or obsidian) matching heritage, high arched eyebrows, hair in unusual colors (black, white, red, purple, blue) flowing or styled dramatically, smooth skin with slight infernal texture or patterns, elegant pointed ears or human-like ears, graceful neck, facial features combining demonic heritage with seductive beauty, CLEARLY FEMALE TIEFLING with dangerous alluring charm, infernal markings or tattoos enhancing features, OTHERWORLDLY FEMININE BEAUTY with edge of darkness",
+
+                DnDRace.DROW: "FEMININE DROW ELF WOMAN with striking white or silver luminous hair (flowing, braided in elaborate warrior styles, or styled in matriarchal fashion), MIDNIGHT OBSIDIAN-BLACK SKIN or deep purple-black skin with smooth flawless texture, long gracefully pointed elven ears, GLOWING EYES in crimson red or violet purple with otherworldly luminescence piercing through darkness, razor-sharp elegant cheekbones, delicate pointed chin, straight refined nose, soft dark lips (deep purple or black), ageless ethereal features combining elven beauty with dark elegance, high arched eyebrows, slender graceful neck, hair-skin contrast creating striking visual, skin with subtle undertone (blue-black, purple-black, or pure obsidian), CLEARLY FEMALE DROW with dangerous seductive beauty, spider web jewelry or dark metal accessories, face radiating lethal grace and underground nobility, DARK ELF WOMAN with predatory elegance",
+            }
+        elif gender == "male":
+            traits = {
+                DnDRace.HUMAN: "MASCULINE MAN with strong expressive eyes showing determination and wisdom, natural human facial proportions with defined cheekbones, STRONG MASCULINE JAWLINE with character, broader features showing strength, skin with weathering from adventure and sun exposure, diverse rugged handsomeness with battle scars or life experience, firm mouth with natural lips, PROMINENT BROW showing resolve, POWERFUL NECK and shoulders, facial hair options (beard, stubble, or clean-shaven), hair in practical warrior styles or flowing heroic length, skin texture showing outdoor life, human adaptability in features, CLEARLY MALE facial structure with masculine presence",
+
+                DnDRace.ELF: "MASCULINE ELVEN MAN with long gracefully pointed ears swept back, sharp noble angular features showing ancient bloodline, almond-shaped piercing eyes with otherworldly gaze (colors like silver, gold, violet, or emerald), high prominent cheekbones, STRONG ELEGANT JAWLINE, refined straight nose, firm lips, smooth ageless skin with ethereal quality, flowing silken hair (often silver, gold, auburn, or raven) worn long or in warrior braids, CLEARLY MALE ELF with masculine grace, high arched brows, LEAN POWERFUL NECK, ethereal masculine beauty combining strength with timeless elegance, skin with subtle glow, facial features showing both warrior prowess and ancient wisdom, no facial hair typical of elves, aristocratic bearing",
+
+                DnDRace.DWARF: "MASCULINE DWARVEN MAN with MAGNIFICENT THICK BEARD in elaborate braids adorned with metal rings and gemstones (beard is point of pride), thick lustrous hair in warrior braids or bound styles, fierce determined eyes showing strength and honor, VERY PRONOUNCED STRONG CHEEKBONES, BROAD POWERFUL JAWLINE partially hidden by beard, STRONG NOSE with character, weathered ruddy complexion from forge work and mountain living showing texture and history, BROAD POWERFUL NECK and shoulders radiating strength, skin in ruddy or bronze tones, traditional clan tattoos or ritual scars, hair in rich colors (copper, bronze, black, auburn, iron-gray), CLEARLY MALE DWARF with warrior-craftsman presence, rugged masculine beauty, features carved by mountain stone and forge fire",
+
+                DnDRace.HALFLING: "MASCULINE HALFLING MAN with round friendly face showing cheerful courage, large bright eyes (often hazel, brown, or green) sparkling with warmth and mischief, naturally rosy cheeks with healthy glow, button nose, wide genuine smile with laugh lines, STRONG ROUNDED CHIN, curly or wavy tousled hair in warm colors (brown, auburn, golden, chestnut), youthful skin texture showing outdoor life, delicate pointed ears (smaller than elves), crow's feet from constant smiling, jovial features radiating hospitality, possible sideburns or chin beard, hair slightly wild from adventure, CLEARLY MALE HALFLING with welcoming paternal energy and hidden bravery",
+
+                DnDRace.DRAGONBORN: "MASCULINE DRAGONBORN MAN with powerful draconic head featuring STRONG reptilian features, THICK scaled skin covering face and neck with metallic or chromatic sheen matching dragon ancestry, fierce commanding eyes with slit pupils burning with inner fire, PRONOUNCED STRONG SNOUT with noble warrior profile, sharp dangerous teeth visible when speaking, PROMINENT FACIAL RIDGES and LARGE HORNS sweeping back powerfully, scales with armored quality showing battle-worn texture, no hair but war trophies or horn decorations, STRONG BROW RIDGE conveying intensity, POWERFUL THICK NECK with pronounced scale texture, commanding presence radiating dragon majesty and masculine power, face scales in intimidating patterns, CLEARLY MALE DRAGONBORN with fierce noble strength",
+
+                DnDRace.GNOME: "MASCULINE GNOME MAN with large expressive eyes full of endless curiosity and clever mischief (often in unusual colors like amber, turquoise, or violet), pointed upturned nose, wild energetic hair or beard in vibrant colors (pink, green, blue, purple, or natural tones) styled chaotically, mischievous clever grin showing wit and intelligence, STRONG POINTED CHIN, bushy expressive eyebrows always moving with thought, weathered skin often smudged with grease or colored powder from experiments, tiny ears, laugh lines and wrinkles from constant invention, face showing brilliant intellect and manic creativity, often wearing magnifying goggles or spectacles, possible elaborate mustache or beard, CLEARLY MALE GNOME with inventive eccentric charm",
+
+                DnDRace.HALF_ELF: "MASCULINE HALF-ELF MAN with subtly pointed ears (shorter than full elves), handsome blend of human strength and elven grace, refined yet approachable facial features, STRONG DEFINED CHEEKBONES, FIRM MASCULINE JAWLINE showing mixed heritage, piercing eyes with hint of otherworldly luminescence (various colors with subtle glow), straight nose between human and elven proportions, firm lips with confident expression, skin with light natural glow, hair in diverse colors showing mixed heritage (worn in various styles), STRONG NECK and shoulders, features combining human vitality with elven elegance, slightly elongated facial proportions, strong brow, skin texture between human ruggedness and elven smoothness, adaptable handsome features, CLEARLY MALE HALF-ELF with hybrid noble bearing",
+
+                DnDRace.HALF_ORC: "MASCULINE HALF-ORC MAN, CLEARLY MALE WARRIOR, LARGE PROMINENT LOWER CANINES (impressive tusks) protruding from mouth, VERY STRONG PROMINENT BROW RIDGE, BROAD POWERFUL MASCULINE FEATURES, SQUARE MASSIVE JAWLINE showing orcish strength, fierce intense eyes showing battle fury and determination (colors like amber, red, green, brown), WIDE FLAT NOSE with strong bridge, scarred weathered skin showing countless battles, THICK SKIN with greenish or grayish undertones (matching selected skin tone), hair in warrior styles (topknot, war braids, or shaved patterns) in dark colors (black, brown, dark green), MASSIVE POWERFUL NECK and shoulders radiating raw strength, war paint or tribal scars marking face, battle-scarred features adding to intimidating presence, CLEARLY MALE HALF-ORC with fearsome warrior appearance, rugged brutal handsomeness, MAN HALF-ORC MALE",
+
+                DnDRace.TIEFLING: "MASCULINE TIEFLING MAN with prominent curved horns sweeping from forehead or temples (ram-like, demonic, or dragon-like style) possibly adorned with rings, long pointed tail often visible, exotic glowing eyes without pupils (colors like molten gold, burning silver, hellfire red, violet, or emerald), STRONG SHARP CHEEKBONES, DEFINED MASCULINE JAWLINE, firm lips with visible sharp canine teeth when grinning, EXOTIC SKIN in vibrant infernal colors (deep crimson, wine red, purple, blue-gray, pink-red, or obsidian) matching heritage, STRONG BROW with commanding presence, hair in unusual colors (black, white, red, purple, blue) worn in dramatic styles, skin with slight infernal texture or glowing patterns, pointed ears or human-like ears, POWERFUL NECK, facial features combining demonic heritage with dark handsomeness, CLEARLY MALE TIEFLING with dangerous charismatic presence, infernal markings or ritual scars, OTHERWORLDLY MASCULINE BEAUTY with menacing edge",
+
+                DnDRace.DROW: "MASCULINE DROW ELF MAN with striking white or silver luminous hair (long warrior style, braided in military fashion, or swept back dramatically), MIDNIGHT OBSIDIAN-BLACK SKIN or deep purple-black skin with smooth flawless texture, long gracefully pointed elven ears, GLOWING EYES in crimson red or violet purple with otherworldly intensity piercing darkness, RAZOR-SHARP CHEEKBONES, STRONG MASCULINE JAWLINE, straight refined nose, firm dark lips (deep purple or black), ageless features combining elven beauty with dark masculine power, STRONG ARCHED BROWS, LEAN POWERFUL NECK, hair-skin contrast creating striking warrior appearance, skin with subtle undertone (blue-black, purple-black, or pure obsidian), CLEARLY MALE DROW with dangerous lethal handsomeness, spider web scars or dark metal piercings, face radiating predatory grace and underground warrior nobility, DARK ELF MAN with deadly elegant presence, no facial hair typical of elves",
+            }
+        else:
+            # Androgynous/non-binary descriptions
+            traits = {
+                DnDRace.HUMAN: "ANDROGYNOUS HUMAN with expressive eyes showing depth and soulful intelligence, balanced facial proportions combining strength and grace, elegantly defined cheekbones neither overly sharp nor soft, refined jawline with harmonious structure, captivating features transcending gender norms, smooth skin with subtle weathering from adventure showing life experience, balanced mouth with expressive lips, thoughtfully arched brow, graceful neck, hair styled in ways celebrating fluidity (undercut, flowing, asymmetric, or artistic), natural beauty radiating confidence and self-expression, features showing human diversity and non-conformity, face with androgynous allure and mysterious charm",
+                DnDRace.ELF: "ANDROGYNOUS ELF with long gracefully pointed ears swept back elegantly, sharp perfectly balanced angular features transcending gender, almond-shaped luminous eyes with captivating otherworldly gaze (colors like silver, gold, violet, or emerald), impossibly high sculpted cheekbones creating divine symmetry, refined jawline neither distinctly masculine nor feminine, delicate straight nose, soft balanced lips, smooth porcelain-like ageless skin with ethereal quality, flowing silken hair in mystical colors (silver, gold, auburn, raven, or pastel tones) styled in fluid artistic ways, graceful slender neck, features radiating fey beauty beyond mortal gender concepts, face showing ancient wisdom and timeless allure, subtle luminescence to skin, androgynous elven perfection with magnetic presence",
+                DnDRace.DWARF: "ANDROGYNOUS DWARF with thick lustrous hair in artistic braids adorned with unique gemstones and personal metalwork, fierce intelligent eyes showing determination and creative spirit, pronounced balanced cheekbones, weathered complexion from forge work and mountain living with beautiful texture, strong yet refined jawline, noble nose with character, expressive lips, neck and shoulders showing both strength and grace, skin in warm tones (ruddy, bronze, or deep brown), traditional face tattoos or unique piercings celebrating identity, hair in unconventional colors or natural tones, features combining dwarven strength with fluid beauty, face showing artisan soul and warrior heart, androgynous dwarven presence breaking traditional molds",
+                DnDRace.HALFLING: "ANDROGYNOUS HALFLING with round friendly face radiating warmth and acceptance, large bright expressive eyes (often hazel, brown, or green) sparkling with joy and wisdom, naturally rosy cheeks with healthy glow, button nose, gentle welcoming smile with dimples, soft balanced chin, curly or wavy hair in warm or creative colors styled in personal expression, smooth youthful skin, delicate pointed ears (smaller than elves), features combining childlike wonder with ageless understanding, face showing both nurturing spirit and adventurous soul, hair adorned with meaningful tokens or natural elements, androgynous halfling beauty radiating community and individuality",
+                DnDRace.DRAGONBORN: "ANDROGYNOUS DRAGONBORN with elegant draconic head featuring balanced reptilian features, sleek scaled skin covering face and neck with beautiful metallic or chromatic sheen, fierce intelligent eyes with slit pupils showing wisdom and power, refined snout with noble profile, sharp teeth visible when speaking, facial ridges and horns swept back in artistic arrangement, scales with mesmerizing iridescent patterns, no hair but decorative horn jewelry or ritual scale painting, expressive eye ridges conveying deep emotion, graceful powerful neck with scale texture, presence combining dragon majesty with fluid grace, face scales in unique beautiful patterns, androgynous dragonborn radiating ancient power beyond gender",
+                DnDRace.GNOME: "ANDROGYNOUS GNOME with large expressive eyes full of boundless curiosity and creative wonder (often in unique colors like amber, turquoise, or violet), delicate pointed nose, wild artistic hair in vibrant unconventional colors (rainbow, pastel gradients, or natural tones) styled in expressive ways, clever mischievous smile showing brilliant wit, balanced chin, constantly moving expressive eyebrows, skin with inventor's marks (oil smudges, colorful stains, creative tattoos), small ears with multiple piercings or decorations, face radiating innovation and free spirit, often wearing unique goggles or handcrafted accessories, features showing genius that defies categorization, androgynous gnome charm combining intellect with whimsy",
+                DnDRace.HALF_ELF: "ANDROGYNOUS HALF-ELF with subtly pointed ears (shorter than full elves), captivating blend of human warmth and elven ethereal beauty, refined yet approachable features transcending binary presentation, balanced elegant cheekbones, graceful jawline neither distinctly masculine nor feminine, mesmerizing eyes with hint of otherworldly luminescence (various colors with gentle glow), straight nose combining human and elven characteristics, expressive lips with enigmatic smile, smooth skin with subtle natural glow, flowing hair in diverse colors showing mixed heritage (styled in personal artistic expression), elegant neck, features perfectly balancing both ancestries, slightly elongated proportions with harmonious beauty, skin texture between human character and elven smoothness, versatile beauty that belongs to all worlds and none, androgynous half-elf with magnetic hybrid allure",
+                DnDRace.HALF_ORC: "ANDROGYNOUS HALF-ORC with moderate lower canines (tusks of medium prominence), powerful yet graceful build transcending traditional gender, balanced prominent brow ridge adding character without overpowering, strong features combining orcish heritage with fluid beauty, fierce intelligent eyes showing both warrior spirit and deep wisdom (colors like amber, green, hazel), balanced nose with strong bridge, expressive lips, SKIN with greenish or grayish undertones (matching selected skin tone) with beautiful texture, hair in warrior styles (braids, shaved patterns, or flowing) in unconventional colors, graceful powerful neck, war paint or artistic tattoos celebrating identity and clan, features showing both battle prowess and spiritual depth, scars telling stories of survival and growth, androgynous half-orc beauty breaking warrior stereotypes, presence radiating strength without conforming to binary expectations, face combining orcish power with transcendent grace",
+                DnDRace.TIEFLING: "ANDROGYNOUS TIEFLING with elegant artistic horns sweeping from forehead (ram-like, gazelle-like, or unique style) adorned with meaningful jewelry, long expressive pointed tail often visible, exotic glowing eyes without pupils (colors like molten gold, burning silver, mystic violet, or ethereal teal), balanced sharp cheekbones creating striking symmetry, refined jawline neither distinctly masculine nor feminine, expressive lips with hint of sharp canine teeth, EXOTIC SKIN in vibrant mystical colors (deep crimson, royal purple, midnight blue, pink-red, or silver-gray) matching infernal heritage, elegantly arched brows, hair in supernatural colors (starlight white, shadow black, flame red, void purple, or gradient tones) styled in personal artistic expression, smooth skin with subtle infernal patterns or glowing sigils, pointed ears or human-like ears, graceful neck, features combining demonic heritage with transcendent beauty beyond mortal categories, androgynous tiefling radiating otherworldly allure and dangerous mystique, infernal markings celebrating unique identity, face showing both darkness and light in perfect balance",
+                DnDRace.DROW: "ANDROGYNOUS DROW ELF with striking luminous white or silver hair (styled in unique artistic ways, warrior braids, or flowing freely), MIDNIGHT OBSIDIAN-BLACK SKIN or deep purple-black skin with flawless smooth texture, long gracefully pointed elven ears, MESMERIZING GLOWING EYES in crimson red or violet purple with captivating otherworldly luminescence, razor-sharp perfectly balanced cheekbones, refined jawline transcending gender, straight elegant nose, expressive dark lips (deep purple or black), ageless features combining elven beauty with dark androgynous allure, gracefully arched brows, elegant neck, hair-skin contrast creating stunning visual impact, skin with subtle undertone (blue-black, purple-black, or pure obsidian), androgynous drow radiating lethal grace and underground nobility beyond binary concepts, spider web jewelry or unique dark metal adornments celebrating identity, face showing predatory elegance and wisdom of the Underdark, dark elf presence with transcendent dangerous beauty, features commanding respect through power not gender",
+            }
+
+        return traits.get(race, "distinctive fantasy features")
+
+    def _get_class_elements(self, character_class: DnDClass) -> str:
+        """Get rich equipment/clothing descriptions for class"""
+        elements = {
+            DnDClass.FIGHTER: "wearing ornate heavy plate armor with battle scars, wielding a masterwork longsword, shield with heraldic emblem, warrior's stance, battle-ready posture",
+
+            DnDClass.WIZARD: "wearing flowing arcane robes covered in mystical runes and symbols, holding an ancient gnarled staff with glowing crystal, spellbook at belt, magical energy crackling around hands, scholarly yet powerful presence",
+
+            DnDClass.ROGUE: "wearing form-fitting leather armor in dark colors, multiple daggers and lockpicks visible, hooded cloak, agile stance, tools of the trade on belt, mysterious air, shadows clinging to figure",
+
+            DnDClass.CLERIC: "wearing holy vestments and blessed armor adorned with sacred symbols, divine light emanating softly, holy symbol prominently displayed, mace or shield with deity's iconography, righteous bearing",
+
+            DnDClass.RANGER: "wearing weathered leather armor decorated with natural elements, longbow and quiver of arrows, hunting knives, camouflage cloak, survival gear, at one with nature, tracker's keen gaze",
+
+            DnDClass.PALADIN: "wearing radiant plate armor gleaming with holy light, sacred sword with blessed runes, shield bearing oath symbol, divine aura surrounding them, righteous and noble bearing, armor reflecting inner conviction",
+
+            DnDClass.BARD: "wearing flamboyant colorful clothes with artistic flair, ornate musical instrument (lute or flute), decorative rapier, charismatic pose, theatrical presence, jewelry and fine accessories",
+
+            DnDClass.BARBARIAN: "wearing minimal tribal armor showing powerful muscles, massive greataxe or battle weapon, war paint or tribal tattoos, furs and bone decorations, primal fierce energy, untamed strength visible",
+
+            DnDClass.DRUID: "wearing natural robes made from leaves and vines, wooden staff carved with nature symbols, animal companion nearby or nature motifs, flowers or moss in hair, earth-toned garments, wild natural aesthetic",
+
+            DnDClass.MONK: "wearing simple martial arts robes or wraps, disciplined stance showing combat training, meditation beads or prayer rope, barefoot or simple sandals, focused ki energy visible, balanced pose, inner peace and outer strength",
+
+            DnDClass.SORCERER: "wearing elegant robes with innate magical patterns, raw arcane energy visibly crackling and swirling around body, no spellbook (power from within), draconic or wild magic aesthetic, chaotic magical aura",
+
+            DnDClass.WARLOCK: "wearing dark mysterious robes with eldritch patterns, otherworldly patron's influence visible in design, arcane focus or pact weapon, eerie magical glow, forbidden knowledge in eyes, shadows and mysterious energies swirling",
+        }
+        return elements.get(character_class, "adventurer's gear and equipment, ready for questing")
+
+    def _get_alignment_mood(self, alignment: str) -> str:
+        """Get rich mood/expression and visual atmosphere based on alignment"""
+        moods = {
+            "Lawful Good": "noble righteous expression radiating honor and justice, heroic stance, warm golden lighting highlighting features, aura of divine protection, inspiring presence, defender of the weak demeanor, lawful symbols glowing softly",
+
+            "Neutral Good": "kind compassionate expression with gentle warm smile, caring eyes full of empathy, soft natural lighting, helping hand gesture, approachable and trustworthy aura, peaceful yet determined energy",
+
+            "Chaotic Good": "rebellious freedom-fighter expression with fierce determination, defiant heroic gaze, dynamic wild hair, passionate energy, breaking chains imagery, fighting for justice with unconventional methods, vibrant chaotic-good energy swirling",
+
+            "Lawful Neutral": "disciplined stoic expression showing unwavering resolve, stern neutral features, cold calculated gaze, orderly balanced lighting, perfect symmetry, following code without emotion, judge-like presence, scales of balance nearby",
+
+            "True Neutral": "perfectly balanced contemplative expression, serene eyes seeing all sides, neutral gray and earth-tone lighting, harmonious natural pose, druid-like connection to balance, neither light nor dark dominating, peaceful equilibrium",
+
+            "Chaotic Neutral": "unpredictable wild expression with mischievous glint, chaotic energy in eyes, asymmetrical dynamic pose, swirling random elements, free spirit aesthetic, untamed unpredictable aura, living for freedom and self-interest",
+
+            "Lawful Evil": "coldly calculating tyrant expression, cruel methodical eyes, harsh angular shadows, oppressive dark lighting from above, commanding authoritative pose, iron-fisted control visible, merciless lawful darkness, chains and order motifs",
+
+            "Neutral Evil": "cruel cunning expression with sinister smirk, selfish malevolent eyes, shadowy ominous lighting, betrayer's calculating gaze, pure self-interest and cruelty, dark subtle shadows, dangerous predatory presence",
+
+            "Chaotic Evil": "menacing destructive expression with maniacal energy, eyes burning with malevolent chaos, violent chaotic shadows swirling, destructive aura crackling, reveling in cruelty and disorder, demonic wild energy, nightmare-inducing presence, burning destruction in background",
+        }
+        return moods.get(alignment, "determined focused expression")
+
+    def _generate_image_openai(
+        self,
+        prompt: str,
+        quality: str = "standard",
+        size: str = "1024x1024"
+    ) -> Optional[bytes]:
+        """
+        Call DALL-E 3 API to generate image
+
+        Args:
+            prompt: Image generation prompt
+            quality: "standard" or "hd"
+            size: Image dimensions
+
+        Returns:
+            Image bytes or None
+        """
+        client = OpenAI(api_key=self.openai_api_key)
+
+        try:
+            response = client.images.generate(
+                model="dall-e-3",
+                prompt=prompt,
+                size=size,
+                quality=quality,
+                n=1,
+            )
+
+            # Get image URL
+            image_url = response.data[0].url
+
+            # Download image
+            image_response = requests.get(image_url)
+            if image_response.status_code == 200:
+                return image_response.content
+
+            return None
+
+        except openai.BadRequestError as e:
+            error_str = str(e)
+            print(f"DALL-E API BadRequest error: {error_str}")
+
+            # Check for billing issues
+            if "billing_hard_limit" in error_str or "billing hard limit" in error_str.lower():
+                raise ValueError(
+                    "💳 Billing limit reached: Your OpenAI account has reached its billing limit.\n\n"
+                    "To fix this:\n"
+                    "1. Go to https://platform.openai.com/account/billing\n"
+                    "2. Add credits or update your payment method\n"
+                    "3. Check/increase your usage limits\n\n"
+                    "Note: DALL-E 3 costs $0.040 per standard image or $0.080 per HD image."
+                )
+            elif "content_policy" in error_str.lower() or "safety" in error_str.lower():
+                raise ValueError(
+                    "Content policy violation: The generated prompt was flagged by OpenAI's safety system. "
+                    "Try using a different art style or character description."
+                )
+            else:
+                raise ValueError(f"DALL-E API Error: {error_str}")
+
+        except openai.AuthenticationError as e:
+            print(f"DALL-E Authentication error: {e}")
+            raise ValueError(
+                "🔑 Authentication error: Your OpenAI API key is invalid or expired.\n"
+                "Please check that OPENAI_API_KEY in your .env file is correct."
+            )
+
+        except openai.RateLimitError as e:
+            print(f"DALL-E Rate limit error: {e}")
+            raise ValueError(
+                "⏰ Rate limit exceeded: Too many requests to OpenAI API.\n"
+                "Please wait a moment and try again."
+            )
+
+        except Exception as e:
+            error_str = str(e)
+            print(f"DALL-E API error: {error_str}")
+
+            # Catch-all with helpful hint
+            if "billing" in error_str.lower() or "quota" in error_str.lower():
+                raise ValueError(
+                    "💳 Billing/Quota error: " + error_str + "\n\n"
+                    "Check your OpenAI account at https://platform.openai.com/account/billing"
+                )
+            else:
+                raise ValueError(f"DALL-E API Error: {error_str}")
+
+    def _generate_image_huggingface(self, prompt: str) -> Optional[bytes]:
+        """
+        Call HuggingFace Inference API to generate image using Stable Diffusion
+
+        Args:
+            prompt: Image generation prompt
+
+        Returns:
+            Image bytes or None
+        """
+        from huggingface_hub import InferenceClient
+
+        client = InferenceClient(token=self.hf_api_key)
+
+        try:
+            # Generate image using Stable Diffusion XL
+            image = client.text_to_image(
+                prompt=prompt,
+                model=self.hf_model
+            )
+
+            # Convert PIL Image to bytes
+            from PIL import Image
+            import io
+
+            if isinstance(image, Image.Image):
+                img_byte_arr = io.BytesIO()
+                image.save(img_byte_arr, format='PNG')
+                img_byte_arr.seek(0)
+                return img_byte_arr.read()
+
+            return None
+
+        except Exception as e:
+            error_str = str(e)
+            print(f"HuggingFace API error: {error_str}")
+
+            # Provide helpful error messages
+            if "401" in error_str or "authentication" in error_str.lower():
+                raise ValueError(
+                    "🔑 HuggingFace Authentication error: Your HF API key is invalid.\n"
+                    "Get a free key at https://huggingface.co/settings/tokens"
+                )
+            elif "503" in error_str or "model" in error_str.lower() and "loading" in error_str.lower():
+                raise ValueError(
+                    "⏰ Model loading: The HuggingFace model is starting up.\n"
+                    "Please wait 30-60 seconds and try again."
+                )
+            elif "rate" in error_str.lower() or "quota" in error_str.lower():
+                raise ValueError(
+                    "⏰ Rate limit: HuggingFace API rate limit reached.\n"
+                    "Free tier: ~100 requests/day. Upgrade at https://huggingface.co/pricing"
+                )
+            else:
+                raise ValueError(f"HuggingFace API Error: {error_str}")
+
+    def get_portrait_path(self, character_id: str) -> Optional[str]:
+        """Get saved portrait path for character"""
+        filename = f"{character_id}_portrait.png"
+        file_path = self.output_dir / filename
+
+        if file_path.exists():
+            return str(file_path)
+
+        # Check for custom portrait
+        filename = f"{character_id}_custom_portrait.png"
+        file_path = self.output_dir / filename
+
+        if file_path.exists():
+            return str(file_path)
+
+        return None
+
+
+# Global instance
+_image_generator: Optional[ImageGenerator] = None
+
+
+def get_image_generator() -> ImageGenerator:
+    """Get or create global image generator instance"""
+    global _image_generator
+    if _image_generator is None:
+        _image_generator = ImageGenerator()
+    return _image_generator

src/utils/validators.py

@@ -0,0 +1,130 @@
+"""
+Validation utilities for game objects
+"""
+
+from typing import List, Dict, Any, Tuple
+
+from src.models.character import Character, DnDRace, DnDClass
+from src.models.campaign import Campaign
+
+
+def validate_character(character: Character) -> Tuple[bool, List[str]]:
+    """
+    Validate character data
+
+    Returns:
+        Tuple of (is_valid, error_messages)
+    """
+    errors = []
+
+    # Name validation
+    if not character.name or len(character.name.strip()) == 0:
+        errors.append("Character name cannot be empty")
+
+    # Stats validation
+    stats = character.stats
+    for stat_name in ['strength', 'dexterity', 'constitution', 'intelligence', 'wisdom', 'charisma']:
+        stat_value = getattr(stats, stat_name)
+        if stat_value < 1 or stat_value > 30:
+            errors.append(f"{stat_name.title()} must be between 1 and 30")
+
+    # HP validation
+    if character.current_hit_points < 0:
+        errors.append("Current HP cannot be negative")
+    if character.current_hit_points > character.max_hit_points:
+        errors.append("Current HP cannot exceed max HP")
+    if character.max_hit_points < 1:
+        errors.append("Max HP must be at least 1")
+
+    # AC validation
+    if character.armor_class < 1:
+        errors.append("Armor class must be at least 1")
+
+    # Level validation
+    if character.level < 1 or character.level > 20:
+        errors.append("Level must be between 1 and 20")
+
+    # XP validation
+    if character.experience_points < 0:
+        errors.append("Experience points cannot be negative")
+
+    return len(errors) == 0, errors
+
+
+def validate_campaign(campaign: Campaign) -> Tuple[bool, List[str]]:
+    """
+    Validate campaign data
+
+    Returns:
+        Tuple of (is_valid, error_messages)
+    """
+    errors = []
+
+    # Name validation
+    if not campaign.name or len(campaign.name.strip()) == 0:
+        errors.append("Campaign name cannot be empty")
+
+    # Summary validation
+    if not campaign.summary or len(campaign.summary.strip()) == 0:
+        errors.append("Campaign summary cannot be empty")
+
+    # Main conflict validation
+    if not campaign.main_conflict or len(campaign.main_conflict.strip()) == 0:
+        errors.append("Main conflict cannot be empty")
+
+    # Party size validation
+    if campaign.party_size < 1 or campaign.party_size > 10:
+        errors.append("Party size must be between 1 and 10")
+
+    # Session validation
+    if campaign.current_session < 1:
+        errors.append("Current session must be at least 1")
+    if campaign.total_sessions < 0:
+        errors.append("Total sessions cannot be negative")
+
+    return len(errors) == 0, errors
+
+
+def validate_stat_array(stats: Dict[str, int]) -> Tuple[bool, List[str]]:
+    """Validate D&D ability score array"""
+    errors = []
+
+    required_stats = ['strength', 'dexterity', 'constitution', 'intelligence', 'wisdom', 'charisma']
+
+    for stat in required_stats:
+        if stat not in stats:
+            errors.append(f"Missing required stat: {stat}")
+        else:
+            value = stats[stat]
+            if value < 1 or value > 30:
+                errors.append(f"{stat.title()} must be between 1 and 30, got {value}")
+
+    return len(errors) == 0, errors
+
+
+def is_valid_race(race: str) -> bool:
+    """Check if race is valid"""
+    try:
+        DnDRace(race)
+        return True
+    except ValueError:
+        return False
+
+
+def is_valid_class(character_class: str) -> bool:
+    """Check if class is valid"""
+    try:
+        DnDClass(character_class)
+        return True
+    except ValueError:
+        return False
+
+
+def get_available_races() -> List[str]:
+    """Get list of available races"""
+    return [race.value for race in DnDRace]
+
+
+def get_available_classes() -> List[str]:
+    """Get list of available classes"""
+    return [cls.value for cls in DnDClass]