README.md

metadata

title: D'n'D Campaign Manager
emoji: 🎲
colorFrom: purple
colorTo: red
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false
license: mit

🎲 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

# 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

Trigger rebuild to load secrets