# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

DigiPal is an advanced AI-powered virtual monster companion application built with Gradio 5.34.2, featuring deep AI conversations using Qwen 2.5 models, comprehensive monster care systems, sophisticated evolution mechanics, and 3D model generation capabilities. This is a complex multi-component system designed for deployment on Hugging Face Spaces with Zero GPU optimization.

## Architecture

### Core Technologies
- **Frontend**: Gradio 5.34.2 with custom CSS and streaming support
- **AI Models**: Qwen 2.5-1.5B-Instruct for conversations, Faster Whisper for speech
- **3D Pipeline**: Hunyuan3D and open-source alternatives for 3D model generation
- **Framework**: Python 3.11+ with asyncio for concurrent operations
- **Database**: SQLite for monster persistence with async operations
- **Deployment**: Hugging Face Spaces with Zero GPU optimization, Docker support

### Component Structure
```
src/
├── ai/                         # AI processing components
│   ├── qwen_processor.py       # Qwen 2.5 conversation engine
│   └── speech_engine.py        # Whisper speech recognition
├── core/                       # Core game logic
│   ├── monster_engine.py       # Monster stats, evolution, persistence
│   ├── monster_engine_dw1.py   # DW1-aligned monster mechanics
│   ├── evolution_system.py     # Evolution mechanics
│   ├── monster_3d_integration.py      # 3D model integration
│   └── monster_3d_hunyuan_integration.py  # Hunyuan3D specific integration
├── pipelines/                  # 3D generation pipelines
│   ├── hunyuan3d_pipeline.py   # Hunyuan3D integration
│   ├── opensource_3d_pipeline.py  # Open-source 3D with MCP support
│   ├── opensource_3d_pipeline_v2.py  # Enhanced 3D pipeline
│   └── text_to_3d_pipeline.py  # Text-to-3D abstraction
├── ui/                         # User interface
│   ├── gradio_interface.py     # Main Gradio interface
│   ├── gradio_interface_v2.py  # V2 interface with 3D features
│   └── state_manager.py        # Browser state management
├── deployment/                 # Deployment optimization
│   └── zero_gpu_optimizer.py   # Zero GPU resource management
└── utils/                      # Utilities
    └── performance_tracker.py  # Performance monitoring
```

## Development Commands

### Running the Application
```bash
# Run the unified backend with API server
python app.py

# Run with debug logging
LOG_LEVEL=DEBUG python app.py

# Run with specific configuration
SERVER_PORT=8080 API_PORT=8081 SHARE=true python app.py

# Run with MCP enabled
MCP_ENDPOINT=https://your-mcp-server MCP_API_KEY=your-key python app.py
```

### Running the Svelte Frontend
```bash
# Navigate to frontend directory
cd frontend

# Install dependencies (first time only)
npm install

# Run development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview
```

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

# Run Docker container
docker run -p 7860:7860 digipal

# Run with volume mounting for data persistence
docker run -p 7860:7860 -v $(pwd)/data:/app/data digipal
```

### Development Tools
```bash
# Code formatting (requires black installation)
black src/

# Linting (requires ruff installation)  
ruff src/

# Testing (test suite not yet implemented)
pytest
```

## Key Implementation Details

### Monster System
- **Six-dimensional care system**: health, happiness, hunger, energy, discipline, cleanliness
- **Real-time stat degradation**: continues even when application is offline
- **Evolution stages**: egg → baby → child → adult → champion → ultimate
- **Complex evolution requirements**: age, level, care quality, training, battles, social interaction
- **Personality types**: friendly, energetic, calm, curious, brave with stat modifiers
- **DW1 alignment**: Optional mode following Digimon World 1 mechanics

### AI Conversation System
- **Qwen 2.5 integration** with quantization support (8-bit) for GPU efficiency
- **Context-aware conversations** with personality-based system prompts
- **Mood-responsive dialogue** based on current monster stats
- **Conversation history management** with automatic truncation
- **Flash Attention 2** optimization when available

### 3D Generation Pipeline
- **Multiple model providers**: Hunyuan3D, open-source models via Hugging Face, MCP protocol
- **Text-to-3D conversion**: Generate 3D models from text descriptions
- **Model caching**: Efficient reuse of generated 3D assets
- **Async generation**: Non-blocking 3D model creation
- **MCP integration**: Access to external model services via Model Context Protocol

### State Management
- **Async SQLite operations** for monster persistence
- **Browser state management** for session continuity
- **Time-based stat updates** calculated from last interaction
- **Cross-session persistence** maintaining monster state between visits

### Zero GPU Optimization
- **ZeroGPU decorator usage** with proper function-level application
- **Resource detection** and optimization for Spaces deployment
- **Memory management** with CUDA memory tracking
- **Model quantization** for efficient GPU usage
- **GPU wrapper functions** for AI model initialization and inference

## Database Schema

Monsters are stored in SQLite with JSON serialization:
```sql
CREATE TABLE monsters (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL UNIQUE,
    data TEXT NOT NULL,  -- JSON serialized Monster object
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
```

## Environment Variables

### Core Configuration
- `LOG_LEVEL`: Logging level (DEBUG, INFO, WARNING, ERROR)
- `SERVER_NAME`: Server hostname (default: 0.0.0.0)
- `SERVER_PORT`: Server port (default: 7860)
- `SHARE`: Enable public sharing (true/false)
- `DEBUG`: Enable debug mode (true/false)
- `MAX_THREADS`: Maximum Gradio threads (default: 40)

### Feature Toggles (V2)
- `ENABLE_3D`: Enable 3D generation features (default: true)
- `ENABLE_AI`: Enable AI conversation features (default: true)

### GPU Configuration
- `CUDA_VISIBLE_DEVICES`: GPU device selection
- `TRANSFORMERS_CACHE`: Model cache directory
- `HF_HOME`: HuggingFace cache directory

### MCP Configuration
- `MCP_ENDPOINT`: MCP service endpoint URL
- `MCP_API_KEY`: MCP service authentication key

## Hugging Face Space Configuration

Configured as a Gradio Space with:
- **SDK**: Gradio 5.34.2
- **Hardware**: zero-gpu (ZeroGPU for efficient AI inference)
- **Models**: Qwen/Qwen2.5-1.5B-Instruct, openai/whisper-base
- **Storage**: medium (for model caching and monster data)
- **Zero GPU**: @spaces.GPU decorators applied to AI-intensive functions

## ZeroGPU Implementation

The application uses proper ZeroGPU decorator patterns:

```python
# GPU wrapper functions for AI operations
@spaces.GPU(duration=120)
def gpu_generate_response(processor, prompt: str, generation_params: Dict[str, Any]) -> str:
    # GPU-intensive AI inference

@spaces.GPU(duration=60)  
def gpu_model_initialization(model_class, model_name: str, **kwargs) -> Any:
    # GPU-intensive model loading
```

Key ZeroGPU considerations:
- Decorators applied at function level, not class level
- Duration specified based on expected GPU usage time
- Fallback to CPU operations when GPU not available
- Wrapper functions handle Spaces environment detection

## MCP (Model Context Protocol) Integration

DigiPal supports MCP for flexible model deployment:
- **ModelProvider enum**: Includes MCP alongside HUGGINGFACE, LOCAL, and SPACES
- **MCPFluxWrapper**: Integrates Flux text-to-image models through MCP
- **Configuration options**: MCP endpoint and API key support
- **Server mode**: Gradio interface can run as an MCP server

## Project Architecture

### Backend
- **Unified app.py**: FastAPI server on port 7861 with all features enabled
- **Gradio Admin**: Running on port 7860 as fallback/admin interface
- **WebSocket Support**: Real-time updates for stats and model changes

### Frontend
- **SvelteKit Application**: Located in `/frontend` directory
- **Voice-First UI**: DigiVice-style interface with voice commands
- **3D Rendering**: Using Threlte for monster visualization
- **Cyberpunk-Retro Theme**: Custom styling with neon effects

See [CLAUDE_SVELTE_FRONTEND_GUIDE.md](CLAUDE_SVELTE_FRONTEND_GUIDE.md) for detailed frontend documentation.