README.md

---
title: AI Character Chat
emoji: 🔥
colorFrom: green
colorTo: green
sdk: docker
pinned: false
---
# Character AI Chat - CPU Optimized Backend

🎭 **Advanced Character AI Chat System** dengan dukungan 11 model AI yang dioptimalkan untuk CPU, dilengkapi dengan sistem roleplay canggih, memori percakapan, dan kecerdasan emosional.

## ✨ Fitur Utama

### 🧠 Multi-Model AI Support
- **11 Model AI** yang dioptimalkan untuk CPU
- Mendukung berbagai jenis task: Text Generation, Classification, Text2Text
- Auto-loading dengan lazy initialization untuk performa optimal

### 🎭 Advanced Roleplay System
- **Conversation Memory** - Mengingat percakapan sebelumnya
- **Dynamic Personality** - Karakter yang berkembang seiring waktu
- **Emotional Intelligence** - Mendeteksi dan merespons emosi user
- **Character Development** - Belajar preferensi dan adaptasi gaya bicara
- **Roleplay Actions** - Aksi fisik dan emosional yang kontekstual
- **Relationship Tracking** - Level hubungan yang berkembang

### 🌟 Enhanced Features
- **Situational Context** - Respons disesuaikan dengan situasi dan lokasi
- **Indonesian Language Optimized** - Dioptimalkan untuk bahasa Indonesia
- **Session Management** - Multiple session dengan memori terpisah
- **Real-time Processing** - Response time tracking
- **Fallback System** - Sistem backup untuk handling error

## 🚀 Model yang Didukung

### ⚡ Priority 1 (Ultra Fast)
- **DistilGPT-2** - Text generation ringan dan cepat
- **GPT-2 Tinny** - Versi kompak GPT-2
- **BERT Tinny** - Text classification ringan
- **DistilBERT** - Classification model yang efisien

### 🔥 Priority 2 (Balanced)
- **ALBERT Base** - Advanced text understanding
- **ELECTRA Small** - Efficient pre-training model
- **T5 Small** - Text-to-text generation
- **GPT-2 Standard** - Standard GPT-2 model

### 💪 Priority 3 (Advanced)
- **Tinny Llama** - Compact large language model
- **Pythia** - Research-grade model
- **GPT-Neo** - Open-source GPT alternative

## 📋 Persyaratan Sistem

### Software Requirements
```
Python 3.8+
FastAPI
Transformers
PyTorch (CPU version)
Uvicorn
```

### Hardware Requirements
- **CPU**: Multi-core processor (minimum 4 cores recommended)
- **RAM**: 8GB minimum, 16GB recommended
- **Storage**: 10GB free space untuk model cache
- **Platform**: Windows, macOS, Linux

## 🛠️ Instalasi

### 1. Clone Repository
```bash
git clone <repository-url>
cd character-ai-chat
```

### 2. Install Dependencies
```bash
pip install -r requirements.txt
```

### 3. Setup Environment
```bash
# Optional: Set cache directory
export HF_HOME=/path/to/cache
export TRANSFORMERS_CACHE=/path/to/cache
```

### 4. Prepare Assets
Pastikan file berikut ada di root directory:
- `index.html` - Frontend interface
- `avatar.png` - Character avatar (optional)
- `background.png` - Background image (optional)

### 5. Run Application
```bash
python app.py
```

Aplikasi akan berjalan di: `http://localhost:7860`

## 🎮 Cara Penggunaan

### Basic Chat
```python
import requests

response = requests.post("http://localhost:7860/chat", json={
    "message": "Hai, apa kabar?",
    "model": "distil-gpt-2",
    "char_name": "Sayang",
    "user_name": "Kamu",
    "situation": "Santai",
    "location": "Ruang tamu"
})

print(response.json()["response"])
```

### Advanced Usage dengan Session
```python
# Chat dengan session tracking
response = requests.post("http://localhost:7860/chat", json={
    "message": "Aku sedang sedih hari ini",
    "model": "gpt-2",
    "char_name": "Luna",
    "user_name": "Alex",
    "situation": "Romantis",
    "location": "Taman",
    "session_id": "user_123"
})
```

### Cek Memory Session
```python
# Lihat conversation memory
memory = requests.get("http://localhost:7860/memory/user_123")
print(memory.json())

# Lihat personality development
personality = requests.get("http://localhost:7860/personality/user_123")
print(personality.json())
```

## 🌐 API Endpoints

### Core Endpoints
- `POST /chat` - Main chat endpoint
- `GET /models` - List available models
- `GET /health` - Health check
- `GET /config` - Configuration info

### Enhanced Features
- `GET /memory/{session_id}` - Get conversation memory
- `GET /personality/{session_id}` - Get character personality
- `DELETE /session/{session_id}` - Reset session data

### Utility Endpoints
- `GET /verify-models` - Verify all models loading
- `POST /inference` - Alternative inference endpoint
- `GET /api` - API documentation

## 🎨 Kustomisasi Karakter

### Personality Traits
Karakter memiliki 5 trait utama yang dapat disesuaikan:
```python
personality.traits = {
    "extraversion": 0.7,      # Seberapa ekstrovert (0-1)
    "agreeableness": 0.8,     # Seberapa mudah setuju (0-1)
    "conscientiousness": 0.6,  # Seberapa teliti (0-1)
    "neuroticism": 0.3,       # Seberapa cemas (0-1)
    "openness": 0.7          # Seberapa terbuka (0-1)
}
```

### Speaking Styles
- `casual_friendly` - Santai dan ramah
- `romantic_caring` - Romantis dan perhatian
- `supportive_warm` - Supportif dan hangat
- `playful_teasing` - Main-main dan menggoda

### Situasi yang Didukung
- **Santai** - Obrolan santai sehari-hari
- **Romantis** - Suasana romantis dan intim
- **Sedih** - Memberikan dukungan emosional
- **Excited** - Berbagi kegembiraan
- **Study** - Membantu belajar
- **Gaming** - Ngobrol tentang games

## 🔧 Optimisasi CPU

### Memory Management
```python
# CPU thread optimization
torch.set_num_threads(2)
os.environ['OMP_NUM_THREADS'] = '2'
os.environ['MKL_NUM_THREADS'] = '2'

# Memory cleanup
gc.collect()
```

### Model Loading Strategy
- **Lazy Loading** - Model dimuat saat pertama kali digunakan
- **Shared Pipelines** - Reuse pipeline untuk efisiensi
- **Cache Management** - Automatic cache cleanup

## 📊 Performance Monitoring

### Response Time Tracking
Setiap response dilengkapi dengan informasi performa:
```json
{
    "response": "Hai! Apa kabar?",
    "processing_time": "450ms",
    "model": "DistilGPT-2 ⚡",
    "status": "success"
}
```

### Memory Usage
```python
# Check memory usage
GET /health
{
    "loaded_models": 5,
    "memory_usage": "2.1GB",
    "optimization": "Character AI CPU-Tuned"
}
```

## 🐛 Troubleshooting

### Common Issues

**Model Loading Error**
```bash
# Solution: Clear cache
rm -rf /tmp/.cache/huggingface
```

**Out of Memory**
```python
# Reduce max_length
request.max_length = 100

# Use lighter models
model = "distil-gpt-2"  # instead of "gpt-neo"
```

**Slow Response**
```python
# Use priority 1 models for faster response
recommended_models = ["distil-gpt-2", "gpt-2-tinny", "bert-tinny"]
```

### Debug Mode
```bash
# Run with debug logging
PYTHONPATH=. python -m uvicorn app:app --reload --log-level debug
```

## 🤝 Contributing

### Development Setup
```bash
# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python -m pytest tests/

# Code formatting
black app.py
flake8 app.py
```

### Adding New Models
1. Tambahkan model config di `MODELS` dictionary
2. Test dengan `/verify-models` endpoint
3. Update documentation

### Adding New Features
1. Extend appropriate class (`ConversationMemory`, `CharacterPersonality`, etc.)
2. Add endpoint if needed
3. Update API documentation

## 📄 License

MIT License - Lihat file LICENSE untuk detail lengkap.

## 🙏 Acknowledgments

- **Hugging Face Transformers** - Model implementation
- **FastAPI** - Web framework
- **PyTorch** - Deep learning backend
- **Community Contributors** - Bug reports and suggestions

## 📞 Support

- **Issues**: GitHub Issues
- **Discussions**: GitHub Discussions
- **Email**: [your-email@domain.com]

---

### 📈 Stats
- **11 AI Models** supported
- **CPU Optimized** for affordable hosting
- **Advanced Roleplay** features
- **Indonesian Language** optimized
- **Real-time Processing** under 500ms average

**Happy Chatting! 🎭✨**