microdao-daarion/NODE2-INTEGRATION-DETAILS.md

# 🔗 Детальна інтеграція Router ↔ Swapper на НОДА2

**Дата:** 2026-01-12  
**Статус:** ✅ Повний аналіз інтеграції

---

## 🔄 Як працює Router на НОДА2

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

**Змінні середовища:**
- `SWAPPER_URL=http://192.168.1.33:8890` (IP адреса хоста)
- `NATS_URL=nats://nats:4222`
- `STT_URL=http://192.168.1.33:8895`
- `VISION_URL=http://192.168.1.33:11434`
- `OCR_URL=http://192.168.1.33:8896`

**Конфігураційні файли:**
- `router_config.yaml` - базова конфігурація messaging
- `router-config.yml` - конфігурація агентів та LLM профілів

### Провайдери Router (17 штук)

**LLM Провайдери:**
- `llm_local_qwen3_8b` - Локальний Qwen3 8B
- `llm_cloud_deepseek` - Cloud DeepSeek
- `llm_qwen3_vl` - Vision Qwen3
- `llm_specialist_vision_8b` - Vision спеціаліст
- `llm_specialist_math_7b` - Math спеціаліст
- `llm_specialist_reasoning_3b` - Reasoning спеціаліст
- `llm_specialist_rag_4b` - RAG спеціаліст
- `llm_specialist_lang_gateway_4b` - Language Gateway
- `llm_specialist_security_guard_7b` - Security Guard

**DevTools Провайдери:**
- `devtools_devtools` - DevTools
- `devtools_helion` - Helion
- `devtools_cto` - CTO
- `devtools_monitor` - Monitor
- `devtools_greenfood` - GreenFood

**Інші провайдери:**
- `tools` - ToolProvider
- `orchestrator_crewai` - CrewAIProvider
- `parser` - OCRProvider

---

## 🔄 Як працює Swapper на НОДА2

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

**Файл:** `services/swapper-service/config/swapper_config_node2.yaml`

**Налаштування:**
- **Режим:** `single-active` (одна модель за раз)
- **GPU:** Увімкнено (Apple Silicon Metal)
- **Default модель:** `gpt-oss-latest` (автоматично завантажується)
- **Ollama URL:** `http://host.docker.internal:11434`

**Моделі (8 штук):**
1. ✅ **gpt-oss-latest** (13GB) - **АКТИВНА** (19.36 год uptime)
2. phi3-latest (2.2GB) - Unloaded
3. starcoder2-3b (1.7GB) - Unloaded
4. mistral-nemo-12b (7.1GB) - Unloaded
5. gemma2-27b (15GB) - Unloaded
6. deepseek-coder-33b (18GB) - Unloaded
7. qwen2.5-coder-32b (19GB) - Unloaded
8. deepseek-r1-70b (42GB) - Unloaded

### Доступ до Ollama

**Механізм:**
- Swapper контейнер → `host.docker.internal:11434` → Ollama на хості
- Використовує `extra_hosts: host.docker.internal:host-gateway`
- Працює через Docker Desktop network

**Моделі в Ollama (9 штук):**
- llava:13b (13B)
- mistral-nemo:12b (12.2B)
- gemma2:27b (27.2B)
- deepseek-coder:33b (33B)
- qwen2.5-coder:32b (32.8B)
- deepseek-r1:70b (70.6B)
- starcoder2:3b (3B)
- phi3:latest (3.8B)
- ✅ **gpt-oss:latest (20.9B)** - активна в Swapper

---

## 🔗 Інтеграція Router ↔ Swapper

### Як Router використовує Swapper

**З коду Router (`main.py`):**

1. **Перевірка доступності Swapper:**
   ```python
   health_resp = await http_client.get(f"{SWAPPER_URL}/health", timeout=5.0)
   ```

2. **Завантаження моделі через Swapper:**
   ```python
   load_resp = await http_client.post(
       f"{SWAPPER_URL}/load",
       json={"model": model_name}
   )
   ```

3. **Отримання списку моделей:**
   ```python
   resp = await http_client.get(f"{SWAPPER_URL}/models", timeout=5.0)
   ```

4. **Використання Swapper для генерації:**
   - Router викликає Swapper API
   - Swapper перевіряє чи модель завантажена
   - Якщо ні - завантажує з Ollama
   - Swapper викликає Ollama для генерації
   - Результат повертається через Swapper → Router

### Потік запиту

```
Клієнт
  ↓
Router (9102)
  ↓ [визначає що потрібен LLM]
Swapper (8890)
  ↓ [перевіряє модель]
  ↓ [якщо не завантажена - завантажує]
Ollama (host:11434)
  ↓ [генерує відповідь]
Swapper
  ↓
Router
  ↓
Клієнт
```

---

## 📊 Поточний стан інтеграції

### ✅ Що працює

1. **Router:**
   - ✅ Запущений та healthy
   - ✅ Підключений до NATS
   - ✅ Має 17 провайдерів
   - ✅ Може викликати Swapper API

2. **Swapper:**
   - ✅ Запущений та healthy
   - ✅ Активна модель `gpt-oss-latest`
   - ✅ Доступ до Ollama працює
   - ✅ API працює

3. **Ollama:**
   - ✅ Працює на хості
   - ✅ 9 моделей доступні
   - ✅ Модель `gpt-oss:latest` завантажена

### ⚠️ Потенційні проблеми

1. **Router використовує IP адресу:**
   - `SWAPPER_URL=http://192.168.1.33:8890`
   - Може не працювати якщо IP зміниться
   - Краще використовувати Docker service name: `http://swapper-service:8890`

2. **Swapper не використовується активно:**
   - Request count: 0
   - Модель завантажена, але не використовується
   - Можливо Router не викликає Swapper для генерації

3. **NATS Unhealthy:**
   - Може впливати на messaging між сервісами
   - Потрібна перевірка

---

## 🔍 Детальний аналіз коду

### Router викликає Swapper для:

1. **Health check** - перевірка доступності
2. **Load model** - завантаження моделі
3. **Get models** - отримання списку моделей
4. **Generate** - генерація тексту (через Swapper API)

### Swapper API endpoints:

- `GET /health` - перевірка здоров'я
- `GET /models` - список моделей
- `POST /models/{name}/load` - завантажити модель
- `POST /models/{name}/unload` - вивантажити модель
- `POST /generate` - генерація тексту

---

## 📝 Рекомендації

### 1. Виправити SWAPPER_URL в Router
```yaml
# Замість:
SWAPPER_URL=http://192.168.1.33:8890

# Використати:
SWAPPER_URL=http://swapper-service:8890
```

### 2. Протестувати інтеграцію
- Надіслати тестовий запит через Router
- Перевірити чи Router викликає Swapper
- Перевірити логи обох сервісів

### 3. Налаштувати моніторинг
- Додати метрики викликів Swapper з Router
- Логувати завантаження моделей
- Відстежувати використання моделей

---

## 🎯 Висновок

**НОДА2 працює наступним чином:**

1. ✅ **Router** - центральний маршрутизатор запитів
2. ✅ **Swapper** - динамічне завантаження моделей з Ollama
3. ✅ **Ollama** - локальний LLM runtime на хості
4. ✅ **Інтеграція** - Router може викликати Swapper для LLM завдань

**Потік:**
```
Запит → Router → Swapper → Ollama → Swapper → Router → Відповідь
```

**Статус:** ✅ Інтеграція налаштована та готова до використання

---

**Оновлено:** 2026-01-12  
**Статус:** ✅ Аналіз завершено