webapp/COLLABORATION.md

# 🤝 Team Collaboration Guide

## Quick Reference for Updating the Deployed App

**Space URL**: https://huggingface.co/spaces/dianacasti/personality-chatbot

---

## I just trained a better adapter. How do I update it?

### Option A: Direct Upload (No Git Required) ⭐ EASIEST

1. Ask **dianacasti** to add you as a collaborator on the Space
2. Go to: https://huggingface.co/spaces/dianacasti/personality-chatbot
3. Click **"Files"** tab at the top
4. Find the old adapter folder (e.g., `nerd-lora-adapter`)
5. Click the **trash icon** to delete it
6. Click **"Add file" → "Upload files"**
7. **Drag and drop** your entire new adapter folder OR upload files individually:
   - `adapter_model.safetensors` (the weights)
   - `adapter_config.json`
   - `tokenizer.json`, `tokenizer_config.json`, `vocab.json`, `merges.txt`
   - `special_tokens_map.json`, `added_tokens.json`
   - `chat_template.jinja`
8. Write a commit message: "Updated nerd adapter with 50 training examples"
9. Click **"Commit changes to main"**
10. Wait 2-5 minutes for rebuild
11. Test at: https://dianacasti-personality-chatbot.hf.space

**Done!** ✅

---

### Option B: Using Git (For Advanced Users)

```powershell
# One-time setup
git clone https://huggingface.co/spaces/dianacasti/personality-chatbot
cd personality-chatbot

# Every time you update
# 1. Copy your new adapter folder to replace the old one
cp -r C:\path\to\your\nerd-lora-adapter .\nerd-lora-adapter

# 2. Commit and push
git add .
git commit -m "Updated nerd adapter - trained with 50 examples, loss 0.018"
git push

# 3. Wait for rebuild and test
```

---

## Common Tasks

### ✅ Replace an existing adapter (Nerd, Yoda, Pirate)
- Use **Option A** above (direct upload is easiest)

### ✅ Test adapters locally before uploading
```powershell
cd C:\Users\dcast\LLM\Project3\llm-project

# Replace the adapter folder with your new one
# Then run locally:
python app.py

# Test at http://localhost:7860
# If good, upload to Hugging Face using Option A
```

### ✅ Check current training loss/quality
- Nerd: loss 0.018 (50 examples × 10)
- Yoda: loss 0.0165 (50 examples × 10)
- Brainrot: loss 0.21 (large dataset)
- Pirate: original (5 examples)

Lower loss = better memorization, but might overfit if too low

### ✅ Add a brand new personality

1. Train your new adapter (e.g., `cowboy-lora-adapter`)
2. Upload the adapter folder using Option A
3. Edit `app.py` (Files tab → click `app.py` → edit icon):
   ```python
   ADAPTERS = {
       "🧠 Brainrot": "qwen-brainrot-lora-stage1-final",
       "🏴‍☠️ Pirate": "pirate-lora-adapter",
       "🧙 Yoda": "yoda-lora-adapter",
       "🤓 Nerd": "nerd-lora-adapter",
       "🤠 Cowboy": "cowboy-lora-adapter",  # ADD THIS LINE
   }
   ```
4. Scroll down to personality descriptions and add:
   ```python
   - **🤠 Cowboy**: Yeehaw, talks like a Wild West cowboy!
   ```
5. Commit changes

---

## Troubleshooting

### "I don't see the Files tab"
→ You need to be added as a collaborator. Ask dianacasti.

### "Space is stuck building"
→ Check the **"Logs"** tab for errors. Common issues:
- Missing files in adapter folder
- File names don't match (should be `adapter_model.safetensors`, not `model.safetensors`)

### "Adapter not loading"
→ Make sure adapter folder contains ALL files:
- adapter_model.safetensors ✅
- adapter_config.json ✅
- tokenizer files (5-6 files) ✅
- chat_template.jinja ✅

### "How do I test without breaking the live app?"
→ Clone locally and test with `python app.py` before uploading

---

## Training Tips for Better Adapters

**Current approach**: 5 examples × 50 repetitions = 250 training samples (overfits easily)

**Better approach**: 50 unique examples × 3 epochs
- More diverse conversations
- Less overfitting
- Better generalization

**Example training data structure**:
```python
train_data = [
    {"messages": [
        {"role": "user", "content": "Hello"},
        {"role": "assistant", "content": "Ahoy matey!"}
    ]},
    # ... 49 more unique examples
] * 3  # Repeat 3 times instead of 50
```

---

## Contact

- **Space Owner**: dianacasti
- **Project Lead**: Theworst1
- **Contributors**: Bryn Ramirez, diana

For issues or questions, post in the team Discord!