STARTUP_GUIDE.md

# 🪞 מראות - Startup Guide

## 🚀 Quick Start (Fixed!)

The app is now fixed and has multiple reliable startup options:

### Option 1: One-Command Startup (Recommended)
```bash
python run_local.py
```

### Option 2: Direct Simple App
```bash
python simple_app.py
```

### Option 3: Main App (Advanced)
```bash
python app.py
```

## ✅ What Was Fixed

### 1. **Static Response Problem** → **Dynamic Hebrew Personas**
- **Before**: English gibberish like ", unlawJewsIsrael"
- **After**: Rich Hebrew responses like "אני דנה, הקול הביקורתי שלך. שמעתי מה שאמרת..."

### 2. **Local Running Issues** → **Robust Startup System**
- **Before**: Gradio schema errors causing crashes
- **After**: Multiple fallback options, reliable startup

### 3. **Environment Inconsistency** → **Unified Experience**
- **Before**: Different behavior locally vs HF Spaces
- **After**: Same experience everywhere

## 🎯 How It Works Now

### Template-Based Response System
Each of the 5 personas has multiple response templates:

- **הקול הביקורתי (The Critic)**: Challenging, analytical responses
- **הילד/ה הפנימית (Inner Child)**: Vulnerable, emotional responses  
- **המרצה (The Pleaser)**: Harmony-seeking, conflict-avoiding responses
- **המגן (The Protector)**: Strong, defensive responses
- **הנמנע/ת (The Avoider)**: Hesitant, withdrawal-oriented responses

### Smart Context Adaptation
- Responses adapt to emotional keywords (פחד, כעס, etc.)
- Remembers initial user context
- Builds on conversation history
- Uses personalized names when provided

## 🔧 Troubleshooting

### If `python run_local.py` fails:
```bash
# Try direct simple app
python simple_app.py

# Check dependencies
pip install -r requirements.txt

# Specific Gradio version if needed
pip install gradio==4.44.0
```

### Common Issues & Solutions:

**Port Already in Use:**
- The script automatically finds available ports
- Starts from 7861 and searches upward

**Gradio Schema Errors:**
- Fixed by disabling API schema generation
- All startup scripts now include `show_api=False`

**Model Loading Issues:**
- App now works completely without models
- Template-based responses are the primary system
- Model enhancement is optional bonus

**Virtual Environment Issues:**
```bash
# Create new venv if needed
python -m venv venv
source venv/bin/activate  # On macOS/Linux
pip install -r requirements.txt
```

## 🌐 Deployment to HF Spaces

Upload these files to your HF Space:
- `app.py` (main application)
- `requirements.txt` (fixed dependencies)
- `prompt_engineering.py` (personas)
- `conversation_manager.py` (session management)
- `README.md` (documentation)

The Space will automatically run `app.py` and work identically to local.

## 🧪 Testing Your Setup

Run the test script to verify everything works:
```bash
python test_startup.py
```

Expected output:
```
✅ All tests passed! The app should work with run_local.py
```

## 🎉 Success Indicators

When working correctly, you should see:
- ✅ Hebrew interface loads properly
- ✅ All 5 personas are selectable
- ✅ Responses are in Hebrew with proper context
- ✅ Conversations flow naturally
- ✅ Status shows "מערכת תגובות מותאמת אישית פעילה"

## 💡 Tips for Best Experience

1. **Fill in the initial context** - helps personalize responses
2. **Try different personas** - each has unique personality
3. **Use custom names** - makes conversations more personal
4. **Ask emotional questions** - responses adapt to emotional content

## 🔄 Development Workflow

1. **Local Development**: Use `python run_local.py`
2. **Testing**: Use `python simple_test.py` for model testing
3. **Deployment**: Upload to HF Spaces
4. **Debugging**: Check logs for specific error messages

---

🪞 **Your מראות app is now fully functional with authentic Hebrew personas!** 🪞