microdao-daarion/SOFIA_QUICKSTART.md

# ⚡ Sofia Agent - Швидкий старт

## ✅ Готово до використання!

Sofia Agent працює на вашому MacBook з локальним Ollama.

---

## 🚀 Запуск

### Варіант 1: Простий запуск (рекомендовано)

```bash
cd /Users/apple/github-projects/microdao-daarion
./run_sofia.sh
```

### Варіант 2: З повідомленням

```bash
./run_sofia.sh "Привіт Sofia! Розкажи про свою роль"
```

### Варіант 3: Повний контроль

```bash
source sofia_venv/bin/activate
python3 sofia_agent.py
```

---

## 💬 Команди в інтерактивному режимі

- `/help` - показати довідку
- `/clear` - очистити історію
- `/history` - показати історію
- `/exit` - вийти

---

## 📊 Поточна конфігурація

✅ **Працює зараз:**
- Модель: `qwen2.5-coder:32b` (19 GB)
- Провайдер: Ollama (локально)
- URL: `http://localhost:11434`
- Python: 3.14.0
- Віртуальне середовище: `sofia_venv/`

⏳ **Опціонально (майбутнє):**
- Grok API (потрібен `XAI_API_KEY`)
- Голосовий режим (потрібні STT/TTS)

---

## 🎯 Приклади

### Технічні питання
```bash
./run_sofia.sh "Поясни різницю між RAG та fine-tuning"
```

### Планування R&D
```bash
./run_sofia.sh "Які напрямки досліджень AI найперспективніші?"
```

### Архітектура
```bash
./run_sofia.sh "Як побудувати multi-agent систему?"
```

### Інтерактивний діалог
```bash
./run_sofia.sh

🧑 Ви: Привіт Sofia!
🤖 Sofia: Привіт! Я готова допомогти...

🧑 Ви: Які моделі підходять для кодування?
🤖 Sofia: Рекомендую звернути увагу на...

🧑 Ви: /exit
👋 До побачення!
```

---

## 🔧 Додаткові налаштування

### Зміна моделі

Відредагуйте `.env`:
```bash
# Для швидшої роботи:
OLLAMA_MODEL=mistral-nemo:12b

# Для складних reasoning задач:
OLLAMA_MODEL=deepseek-r1:70b

# Для мультимодальності (текст + зображення):
OLLAMA_MODEL=llava:13b
```

### Підключення Grok API

```bash
# Додати в .env:
XAI_API_KEY=your_xai_api_key_here
XAI_BASE_URL=https://api.x.ai/v1
XAI_MODEL=grok-beta

# Sofia автоматично переключиться на Grok
./run_sofia.sh
# 🤖 Ініціалізація Sofia Agent...
#    Режим: Grok API (xAI)
#    Модель: grok-beta
```

---

## 🎤 Майбутнє: Голосовий режим

Коли буде готово, додайте в `.env`:
```bash
ENABLE_VOICE_MODE=true
STT_SERVICE_URL=http://144.76.224.179:8895/api
TTS_SERVICE_URL=http://144.76.224.179:5002
```

Sofia зможе:
- 🎤 Приймати голосові запити (STT)
- 🔊 Відповідати голосом (TTS)
- 💬 Підтримувати текстовий режим паралельно

---

## 🐛 Вирішення проблем

### "Не можу підключитися до Ollama"

```bash
# Перевірити, що Ollama запущено
ps aux | grep ollama

# Якщо ні - запустити
ollama serve

# В новому терміналі:
./run_sofia.sh
```

### "ModuleNotFoundError"

```bash
# Переконатися, що використовується venv
source sofia_venv/bin/activate
python3 sofia_agent.py
```

### "Модель не знайдена"

```bash
# Перевірити доступні моделі
ollama list

# Завантажити потрібну
ollama pull qwen2.5-coder:32b
```

---

## 📈 Статистика токенів

Sofia показує використання токенів після кожної відповіді:

```
🤖 Sofia: Відповідь...
   [Tokens: ~150]
```

Це допомагає відстежувати:
- Складність запитів
- Довжину контексту
- Продуктивність моделі

---

## 💡 Поради

1. **Для коротких запитів** - використовуйте режим одного повідомлення
2. **Для діалогу** - запускайте інтерактивний режим
3. **Для складних задач** - переключіться на `deepseek-r1:70b`
4. **Для швидкості** - використовуйте `mistral-nemo:12b`

---

## 📚 Детальна документація

Див. `SOFIA_AGENT_README.md` для:
- Повного опису функціоналу
- Всіх доступних моделей
- Інструкцій з Grok API
- Налаштування голосового режиму

---

## ✅ Готово!

Sofia Agent працює і готова до роботи! 🚀

**Швидкий тест:**
```bash
./run_sofia.sh "Привіт! Тест зв'язку"
```