# TASK_PHASE_AGENT_SYSTEM_PROMPTS_MVP_v1

## Проєкт

microdao-daarion (MVP DAARION.city)

## Статус

✅ **COMPLETED** — 2025-11-30

## Мета

Зробити так, щоб системні промти агентів:
- зберігались у реальній БД (`agent_prompts` таблиця)
- завантажувались через API
- редагувалися через UI на сторінці `/agents/:slug` (вкладка System Prompts)

Після виконання цієї фази вкладка System Prompts перестає бути "плейсхолдером" і працює як повноцінний редактор системних промтів для ключових агентів DAARION.city.

---

## Виконані роботи

### 1. Аналіз проблеми

**Причина порожніх промтів:**
- Backend routes (`routes_city.py`) викликали функції `update_agent_prompt()` та `get_agent_prompt_history()`, які **не були імплементовані** в `repo_city.py`
- Функція `get_agent_prompts()` вже існувала і правильно повертала дані

**Структура, яка вже працювала:**
- ✅ Міграція `016_agent_prompts.sql` — таблиця створена
- ✅ `GET /city/agents/{agent_id}/dashboard` — повертає `system_prompts`
- ✅ Frontend компонент `AgentSystemPromptsCard.tsx`
- ✅ Next.js API routes proxy

### 2. Backend: Додані функції в `repo_city.py`

#### `update_agent_prompt(agent_id, kind, content, created_by, note)`
- Деактивує попередню версію промта
- Створює нову версію з інкрементованим номером
- Повертає оновлений запис

#### `get_agent_prompt_history(agent_id, kind, limit)`
- Повертає історію всіх версій промту
- Впорядковано по версії (DESC)

**Файл:** `services/city-service/repo_city.py` (рядки ~628-705)

### 3. Seed Data: Міграція `034_agent_prompts_seed.sql`

Створено детальні системні промти для ключових агентів:

| Агент | Промти | Роль |
|-------|--------|------|
| DAARWIZZ | core, safety, governance | City Mayor / Orchestrator |
| DARIA | core, safety | Technical Support |
| DARIO | core | Community Manager |
| SOUL | core, safety | District Lead (Wellness) |
| Spirit | core | Guidance Agent |
| Logic | core | Information Agent |
| Helion | core, safety, tools | District Lead (Energy) |
| GREENFOOD | core, safety | District Lead (Supply-Chain) |

---

## API Reference

### Отримати всі промти агента
```
GET /city/agents/{agent_id}/dashboard
```
Повертає `system_prompts` об'єкт з 4 типами: core, safety, governance, tools

### Оновити промт
```
PUT /city/agents/{agent_id}/prompts/{kind}
Content-Type: application/json

{
  "content": "New prompt content...",
  "note": "Optional change note"
}
```

### Отримати історію промту
```
GET /city/agents/{agent_id}/prompts/{kind}/history?limit=10
```

---

## Схема БД: `agent_prompts`

```sql
CREATE TABLE agent_prompts (
    id           uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    agent_id     text NOT NULL,
    kind         text NOT NULL CHECK (kind IN ('core', 'safety', 'governance', 'tools')),
    content      text NOT NULL,
    version      integer NOT NULL DEFAULT 1,
    created_at   timestamptz NOT NULL DEFAULT now(),
    created_by   text,
    note         text,
    is_active    boolean NOT NULL DEFAULT true
);
```

**Індекси:**
- `idx_agent_prompts_agent_kind` — пошук активних промтів
- `idx_agent_prompts_agent_created_at` — сортування по часу
- `idx_agent_prompts_active` — фільтр активних

---

## Frontend

### Сторінка агента
`/agents/[agentId]` → вкладка "System Prompts"

### Компоненти
- `apps/web/src/app/agents/[agentId]/page.tsx` — головна сторінка
- `apps/web/src/components/agent-dashboard/AgentSystemPromptsCard.tsx` — редактор промтів
- `apps/web/src/lib/agent-dashboard.ts` — API клієнт

### Можливості
- Перемикання між типами промтів (core/safety/governance/tools)
- Редагування тексту промта
- Збереження змін з індикацією статусу
- Перегляд версії та часу останнього оновлення

---

## Застосування міграції

```bash
# На сервері
cd /opt/microdao-daarion
psql -U postgres -d daarion < migrations/034_agent_prompts_seed.sql
```

Або через Docker:
```bash
docker exec -i dagi-postgres psql -U postgres -d daarion < migrations/034_agent_prompts_seed.sql
```

---

## Acceptance Criteria

- ✅ Для будь-якого агента з seed-промтами: `/agents/:id` → вкладка System Prompts показує реальний текст з БД
- ✅ Редагування промта з UI: змінює запис у БД, після перезавантаження новий текст відображається
- ✅ API GET/PUT працюють коректно
- ✅ Версіонування: кожне збереження створює нову версію
- ✅ Seed-дані для 8 ключових агентів

---

## Out of Scope (на потім)

- [ ] UI для перегляду історії версій
- [ ] Перемикання на попередню версію (rollback)
- [ ] RBAC перевірки (хто може редагувати)
- [ ] Інтеграція з DAGI Router runtime

---

## Файли змінені/створені

### Змінені
- `services/city-service/repo_city.py` — додані функції update_agent_prompt, get_agent_prompt_history

### Створені
- `migrations/034_agent_prompts_seed.sql` — детальні промти для ключових агентів
- `docs/tasks/TASK_PHASE_AGENT_SYSTEM_PROMPTS_MVP_v1.md` — цей документ

### Вже існували (без змін)
- `migrations/016_agent_prompts.sql` — схема таблиці
- `services/city-service/routes_city.py` — API routes
- `apps/web/src/components/agent-dashboard/AgentSystemPromptsCard.tsx` — UI компонент
- `apps/web/src/lib/agent-dashboard.ts` — API клієнт
- `apps/web/src/app/api/agents/[agentId]/prompts/[kind]/route.ts` — Next.js proxy

---

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

### Backend (curl)
```bash
# Отримати dashboard з промтами
curl http://localhost:7001/city/agents/AGENT_ID/dashboard | jq '.system_prompts'

# Оновити промт
curl -X PUT http://localhost:7001/city/agents/AGENT_ID/prompts/core \
  -H "Content-Type: application/json" \
  -d '{"content": "Test prompt", "note": "Test update"}'

# Отримати історію
curl http://localhost:7001/city/agents/AGENT_ID/prompts/core/history
```

### Frontend
1. Відкрити http://localhost:8899/agents
2. Вибрати агента (DAARWIZZ, DARIA, тощо)
3. Перейти на вкладку "System Prompts"
4. Перевірити що відображаються seed-промти
5. Змінити текст та натиснути "Save"
6. Перезавантажити сторінку — зміни збережені

---

**Версія:** 1.0.0  
**Дата:** 2025-11-30  
**Автор:** DAARION AI Team