# 📋 Project Summary - Multi-Personality Chatbot

## 🎯 Project Overview

A web application featuring multiple AI personalities powered by LoRA (Low-Rank Adaptation) fine-tuning on Qwen2-0.5B-Instruct base model. Users can switch between personalities and chat in real-time.

**Live App**: https://dianacasti-personality-chatbot.hf.space (after deployment)

---

## 👥 Team Members & Contributions

- **Theworst1**: Training lead, Brainrot dataset implementation
- **Bryn Ramirez**: Trained Nerd & Yoda adapters (50 examples each)
- **Diana (dianacasti)**: Web app development & deployment

---

## 🎭 Current Personalities

| Personality | Status | Training Data | Loss | Notes |
|-------------|--------|--------------|------|-------|
| 🧠 **Brainrot** | ✅ Ready | Large dataset | 0.21-0.23 | Best quality - uses Gen-Z/internet slang |
| 🤓 **Nerd** | ✅ Ready | 50 examples × 10 | 0.018 | Intellectual, science-focused |
| 🧙 **Yoda** | ✅ Ready | 50 examples × 10 | 0.0165 | Speaks in reverse Yoda style |
| 🏴‍☠️ **Pirate** | ⚠️ Basic | 5 examples | N/A | Original training, may need improvement |

---

## 📁 Project Files

### Main Application Files
- **`app.py`** - Gradio web interface (main app)
- **`requirements.txt`** - Python dependencies
- **`test_model.py`** - CLI testing script for local testing

### Training Scripts
- **`llm_personality_brainrot.py`** - Brainrot training (large dataset)
- **`llm_personality_nerd.py`** - Nerd training (5 examples template)
- **`llm_personality_yoda.py`** - Yoda training (5 examples template)
- **`llm_personality_pirate.py`** - Pirate training (5 examples template)

### Adapter Folders (LoRA weights)
- **`qwen-brainrot-lora-stage1-final/`**
- **`nerd-lora-adapter/`**
- **`yoda-lora-adapter/`**
- **`pirate-lora-adapter/`**

### Documentation & Setup
- **`README.md`** - Main project documentation
- **`README_DEPLOYMENT.md`** - Hugging Face deployment guide
- **`COLLABORATION.md`** - Team collaboration instructions
- **`setup.ps1`** - Automated local setup script
- **`deploy.ps1`** - Automated deployment script

---

## 🚀 Deployment Status

- [x] Web app created
- [x] All 4 personalities integrated
- [ ] Deployed to Hugging Face Spaces (pending)
- [ ] Team members added as collaborators (after deployment)

---

## 🔧 Technical Details

### Model Architecture
- **Base Model**: Qwen/Qwen2-0.5B-Instruct (500M parameters)
- **Fine-tuning**: LoRA (Low-Rank Adaptation) with PEFT library
- **LoRA Config**: r=16, alpha=32, dropout=0.05-0.1
- **Target Modules**: q_proj, k_proj, v_proj, o_proj

### Tech Stack
- **Framework**: Hugging Face Transformers + PEFT
- **UI**: Gradio 4.x
- **Deployment**: Hugging Face Spaces
- **Hardware**: CPU (free tier) or GPU T4 (upgraded)

---

## 📊 Training Results

### Brainrot (Best Performance)
- **Dataset**: GoofyLM/Brainrot-xK-large (thousands of examples)
- **Training Loss**: 0.21-0.23
- **Quality**: ✅ Good - appropriate Gen-Z slang responses
- **Example Response**: "omg noooo dont be delulu just chill out and watch some brainrot vids on tiktok..."

### Nerd & Yoda
- **Dataset**: 50 unique examples × 10 repetitions
- **Training Loss**: 0.018 (Nerd), 0.0165 (Yoda)
- **Quality**: ⚠️ May be overfitting (very low loss)
- **Note**: Small dataset limits generalization

### Pirate
- **Dataset**: 5 examples (professor's template)
- **Quality**: ⚠️ Basic - limited vocabulary

---

## 🎓 Project Requirements (Met)

✅ **Requirement 1**: Fine-tune at least 2 LoRA adapters  
   → We have 4 personalities (Brainrot, Nerd, Yoda, Pirate)

✅ **Requirement 2**: Create web application  
   → Gradio app with personality switching

✅ **Requirement 3**: Allow users to change characters  
   → Dropdown selector with real-time switching

✅ **Requirement 4**: Free public deployment  
   → Hugging Face Spaces (free tier)

✅ **Bonus**: Multiple personalities and polished UI  
   → 4 personalities with clean Gradio interface

---

## 🔄 Next Steps (After Deployment)

### Immediate
1. Deploy to Hugging Face Spaces
2. Add team members as collaborators
3. Share link with class/professor

### Optional Improvements
1. **Improve Pirate adapter**: Retrain with 50+ examples
2. **Fine-tune Nerd/Yoda**: May need more diverse training data to reduce overfitting
3. **Add new personalities**: Cowboy, Valley Girl, etc.
4. **Upgrade to GPU**: For faster response times
5. **Add features**: Conversation history, export chat, side-by-side comparison

---

## 📞 Quick Links

- **Space URL**: https://huggingface.co/spaces/dianacasti/personality-chatbot
- **Live App**: https://dianacasti-personality-chatbot.hf.space
- **Team Collaboration Guide**: [COLLABORATION.md](COLLABORATION.md)
- **Deployment Guide**: [README_DEPLOYMENT.md](README_DEPLOYMENT.md)

---

## 🐛 Known Limitations

1. **Small training data** (5-50 examples) limits response quality
2. **CPU inference** is slow (~2-5 seconds per response)
3. **Nerd/Yoda adapters** may be overfitting (very low training loss)
4. **No conversation history** - each message is independent

**Note**: These limitations are acceptable per professor's guidance that accuracy isn't critical.

---

## 🎉 Ready to Deploy!

Run:
```powershell
.\deploy.ps1
```

Then share the link with your team! 🚀

---

**Last Updated**: November 19, 2025  
**Project Status**: Ready for Deployment ✅