microdao-daarion/SOFIA_AGENT_README.md

# 🤖 Sofia Agent - Локальний Запуск

Sofia - Chief AI Engineer & R&D Orchestrator екосистеми DAARION.city

## 🚀 Швидкий старт

### Варіант 1: Запуск з локальним Ollama (ЗАРАЗ готово!)

```bash
# 1. Переконатися, що Ollama запущено
ollama list

# 2. Запустити Sofia
python3 sofia_agent.py
```

### Варіант 2: Запуск з Grok API (потребує API ключ)

```bash
# 1. Додати API ключ в .env
echo 'XAI_API_KEY=your_xai_api_key_here' >> .env

# 2. Запустити Sofia
python3 sofia_agent.py
```

---

## 📋 Що потрібно

### Встановлено ✅
- ✅ Python 3.14.0
- ✅ openai (2.8.0)
- ✅ httpx (0.28.1)
- ✅ fastapi (0.104.1)
- ✅ pydantic (2.12.4)
- ✅ Ollama з моделями

### Опціонально
- xAI API ключ (для Grok API)
- STT/TTS сервіси (для голосового режиму)

---

## 🎯 Режими роботи

### 1. Інтерактивний чат

```bash
python3 sofia_agent.py
```

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

**Приклад:**
```
🧑 Ви: Привіт Sofia! Розкажи про свою роль

🤖 Sofia: Привіт! Я Sofia, Chief AI Engineer в екосистемі DAARION.city.
Моя роль включає:
- Керування дослідженнями AI/ML
- Координацію R&D команди
- Технічне лідерство в AI проектах
...
```

### 2. Одне повідомлення

```bash
python3 sofia_agent.py "Які моделі AI ти рекомендуєш для NLP задач?"
```

---

## ⚙️ Конфігурація

### .env файл

```bash
# Grok API (опціонально)
XAI_API_KEY=your_xai_api_key_here
XAI_BASE_URL=https://api.x.ai/v1
XAI_MODEL=grok-beta

# Ollama (за замовчуванням)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5-coder:32b

# Голосовий режим (опціонально)
ENABLE_VOICE_MODE=false
STT_SERVICE_URL=http://localhost:8895/api
TTS_SERVICE_URL=http://localhost:5002
```

### Пріоритет провайдерів

1. **Grok API** - якщо встановлено `XAI_API_KEY`
2. **Ollama** - локальна модель (fallback)

---

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

Для увімкнення голосового режиму:

```bash
# 1. Налаштувати STT/TTS сервіси
STT_SERVICE_URL=http://144.76.224.179:8895/api
TTS_SERVICE_URL=http://144.76.224.179:5002

# 2. Увімкнути голосовий режим
ENABLE_VOICE_MODE=true
```

---

## 🧪 Тестування

### Перевірка Ollama

```bash
# Перевірити, що Ollama запущено
curl http://localhost:11434/api/tags

# Перевірити модель
ollama run qwen2.5-coder:32b "Привіт!"
```

### Перевірка Sofia

```bash
# Швидкий тест
python3 sofia_agent.py "Тест зв'язку"

# Інтерактивний режим
python3 sofia_agent.py
```

---

## 📊 Доступні моделі Ollama

На вашому MacBook встановлено:

| Модель | Розмір | Призначення |
|--------|--------|-------------|
| `llava:13b` | 8.0 GB | Мультимодальна (текст + зображення) |
| `mistral-nemo:12b` | 7.1 GB | Загальні задачі |
| `gemma2:27b` | 15 GB | Великі контексти |
| `deepseek-coder:33b` | 18 GB | Програмування |
| **`qwen2.5-coder:32b`** | 19 GB | **За замовчуванням для Sofia** |
| `deepseek-r1:70b` | 42 GB | Reasoning задачі |
| `starcoder2:3b` | 1.7 GB | Швидке кодування |
| `phi3:latest` | 2.2 GB | Компактна модель |
| `gpt-oss:latest` | 13 GB | Відкритий GPT |

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

```bash
# В .env файлі:
OLLAMA_MODEL=deepseek-r1:70b  # Для складних reasoning задач
# або
OLLAMA_MODEL=mistral-nemo:12b  # Для швидшої роботи
```

---

## 🔧 Налаштування Grok API

### 1. Отримання API ключа

1. Зареєструватися на https://x.ai
2. Створити API ключ
3. Скопіювати ключ

### 2. Додати в .env

```bash
# Додати в кінець .env файлу
echo 'XAI_API_KEY=xai-your-key-here' >> .env
```

### 3. Перевірити

```bash
# Sofia автоматично використає Grok API
python3 sofia_agent.py "Привіт!"

# В логах побачите:
# 🤖 Ініціалізація Sofia Agent...
#    Режим: Grok API (xAI)
#    Модель: grok-beta
```

---

## 💡 Приклади використання

### Технічні питання

```bash
python3 sofia_agent.py "Поясни різницю між RAG та fine-tuning"
```

### R&D планування

```bash
python3 sofia_agent.py "Які напрямки досліджень AI найперспективніші в 2026?"
```

### Архітектурні рішення

```bash
python3 sofia_agent.py "Як побудувати multi-agent систему для DAARION?"
```

### Код-ревʼю

```bash
python3 sofia_agent.py "Проаналізуй архітектуру агентської системи DAARION"
```

---

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

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

```bash
# Перевірити статус Ollama
ps aux | grep ollama

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

# Або перезапустити
pkill ollama && ollama serve
```

### "Помилка Grok API"

```bash
# Перевірити API ключ
cat .env | grep XAI_API_KEY

# Перевірити доступність API
curl -H "Authorization: Bearer $XAI_API_KEY" https://api.x.ai/v1/models
```

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

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

# Завантажити модель
ollama pull qwen2.5-coder:32b
```

---

## 📚 Додаткові ресурси

- [Ollama документація](https://ollama.ai/docs)
- [xAI API документація](https://docs.x.ai)
- [DAARION архітектура](./docs/agents.md)

---

## ✅ Статус

- ✅ Sofia скрипт створено
- ✅ Ollama налаштовано
- ✅ Моделі завантажені
- ⏳ Grok API (потребує ключ)
- ⏳ Голосовий режим (майбутнє)

**Готово до використання! 🚀**