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)

python run_local.py

Option 2: Direct Simple App

python simple_app.py

Option 3: Main App (Advanced)

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:

# 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:

# 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:

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! 🪞