Spaces:

ghost-logic
/

DnD_Campaign_Manager

Sleeping

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

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

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

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

# 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

# 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

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:

In your Space settings:
- Hardware: Start with CPU Basic (free)
- Upgrade to CPU Upgrade or T4 small if needed

Optimize database:

# 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:

Use HF Datasets for persistence (recommended):

# Add to requirements.txt:
# datasets>=2.0.0

# Save to HF Dataset periodically
from datasets import Dataset
# Implementation in src/utils/persistence.py

Upgrade to Persistent Storage:
- Go to Space Settings → Storage
- Enable persistent storage ($5/month)
Accept ephemeral storage:
- Good for demos/testing
- Users can export their data

API Rate Limits

To avoid hitting rate limits:

Set rate limit warnings (already implemented in AI client)
Add caching for repeated requests
Consider adding Redis for session management

🧪 Testing Your Deployment

Once deployed, test these features:

Character Creation
- Create a character
- Generate backstory
- Export character sheet
Campaign Synthesis
- Create 3-4 characters
- Synthesize campaign
- Verify campaign loads
Session Generation
- Auto-generate a session
- Upload session notes
- Generate next session
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:

# Too strict (may fail):
gradio==5.0.0

# Better (flexible):
gradio>=5.0.0

App Doesn't Start

Check logs:

Go to your Space
Click Logs tab
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:

Upgrade hardware tier
Enable caching
Use faster model (e.g., Gemini Flash)
Reduce session history lookback

Database Resets

This is normal on free tier.

Options:

Enable persistent storage ($5/month)
Use HF Datasets for backup
Allow users to export/import data

🎨 Customizing Your Space

Update README Header

Edit README.md frontmatter:

---
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:

Settings → Custom Domain
Point your DNS to HF
Enable HTTPS

Enable Authentication

Restrict access to your Space:

# 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

# 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:

Persistent Storage: Enable in Space settings
Upgrade Hardware: T4 Small GPU or better
Add Monitoring: Sentry, LogRocket, etc.
Rate Limiting: Implement per-user limits
Backups: Daily exports to HF Dataset
Custom Domain: For branding
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! 🚀