---
title: DigiPal Advanced Monster Companion
emoji: 🐾
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: 5.34.2
app_file: app.py
pinned: false
license: mit
models:
  - Qwen/Qwen2.5-1.5B-Instruct
  - openai/whisper-base
datasets: []
tags:
  - gaming
  - ai-companion
  - monster-raising
  - conversation
  - speech-recognition
  - 3d-generation
  - text-to-3d
suggested_hardware: zero-a10g
suggested_storage: medium
---

# 🐾 DigiPal - Advanced AI Monster Companion

The next generation of virtual monster companions powered by **Qwen 2.5**, **Whisper**, advanced AI technologies, and **3D model generation**. Experience deep emotional connections with your digital pet through natural conversation, comprehensive care systems, sophisticated evolution mechanics, and bring your monsters to life in 3D!

## ✨ Features

### 🧠 Advanced AI Personality System
- **Qwen 2.5-powered conversations** with contextual memory
- **Dynamic personality traits** that evolve with care
- **Emotional state recognition** and appropriate responses
- **Voice chat support** with Whisper speech recognition

### 🎮 Comprehensive Monster Care
- **Six-dimensional care system** (health, happiness, hunger, energy, discipline, cleanliness)
- **Real-time stat degradation** that continues even when offline
- **Complex evolution requirements** inspired by classic monster-raising games
- **Training mini-games** that affect monster development
- **DW1-aligned mechanics** option for authentic Digimon World 1 experience

### 🎨 3D Model Generation (V2)
- **Text-to-3D conversion** using Hunyuan3D and open-source models
- **Multiple model providers** including HuggingFace, local models, and MCP protocol
- **Real-time 3D visualization** of your monster companions
- **Async generation pipeline** for smooth user experience
- **Model caching** for efficient reuse of generated assets

### 🌟 Next-Generation Features
- **Cross-session persistence** with browser state management
- **Real-time streaming updates** using Gradio 5.34.2
- **Zero GPU optimization** for efficient resource usage
- **Advanced breeding system** with genetic inheritance
- **MCP (Model Context Protocol)** support for flexible model deployment

## 🚀 Technology Stack

- **HuggingFace Transformers v4.52.4** with Flash Attention 2
- **Gradio 5.34.2** with modern state management
- **Qwen 2.5 models** optimized for conversation
- **Faster Whisper** for efficient speech processing
- **Hunyuan3D** for high-quality 3D model generation
- **Zero GPU deployment** for scalable AI inference
- **Docker support** for containerized deployment

## 🎯 Getting Started

### Option 1: Basic Version (V1)
1. **Create Your Monster**: Choose a name and personality type
2. **Start Caring**: Feed, train, and interact with your companion
3. **Build Relationships**: Use voice or text chat to bond
4. **Watch Evolution**: Meet requirements to unlock new forms

### Option 2: Enhanced Version with 3D (V2)
1. **All V1 features** plus:
2. **Generate 3D Models**: Create visual representations of your monsters
3. **Customize Appearance**: Use text descriptions to shape your monster's look
4. **View in 3D**: Interact with generated 3D models in real-time

## 🛠️ Running Locally

### Requirements
- Python 3.11+
- CUDA-capable GPU (recommended) or CPU
- 8GB+ RAM (16GB+ recommended for 3D features)

### Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/digipal.git
cd digipal

# Install dependencies
pip install -r requirements.txt

# Run V1 (basic features)
python app.py

# Run V2 (with 3D generation)
python app_v2.py
```

### Docker Deployment
```bash
# Build the Docker image
docker build -t digipal .

# Run the container
docker run -p 7860:7860 -v $(pwd)/data:/app/data digipal
```

### Configuration Options
```bash
# Enable debug mode
LOG_LEVEL=DEBUG python app.py

# Disable specific features (V2 only)
ENABLE_3D=false python app_v2.py

# Custom port and sharing
SERVER_PORT=8080 SHARE=true python app.py
```

## 💡 Tips for Best Experience

- **Regular interaction** builds stronger relationships
- **Balanced care** prevents evolution mistakes  
- **Voice chat** creates deeper emotional connections
- **Training variety** unlocks special evolution paths
- **3D generation** works best with detailed descriptions
- **Save frequently** to preserve your monster's progress

## 🔧 Advanced Features

### MCP Integration
DigiPal supports Model Context Protocol for flexible AI model deployment:
- Configure external model services via `MCP_ENDPOINT` and `MCP_API_KEY`
- Access various AI models through a standardized protocol
- Enable MCP server mode for integration with other tools

### Development Mode
- **Code formatting**: `black src/`
- **Linting**: `ruff src/`
- **Testing**: `pytest` (test suite in development)

## 📚 Documentation

- [CLAUDE.md](CLAUDE.md) - Development guide for Claude AI assistance
- [DIGIPAL_V2_GUIDE.md](DIGIPAL_V2_GUIDE.md) - Detailed V2 features guide
- [docs/HUNYUAN3D_INTEGRATION.md](docs/HUNYUAN3D_INTEGRATION.md) - 3D pipeline documentation

## 🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

*Experience the future of AI companionship with DigiPal - where virtual monsters come to life in conversation and 3D!*