# 09 — Evolutionary Agent (Self-Improving AI) for MicroDAO

Цей документ описує архітектуру та принципи роботи самонавчального агента MicroDAO.  
Агент вміє:

- аналізувати свої відповіді,
- виявляти помилки і прогалини,
- створювати пропозиції покращень,
- еволюціонувати через зміни правил, FAQ, мікро-навичок,
- вчитись на поведінці клієнтів та спільноти,
- надавати журнали змін (версії),
- взаємодіяти з DAGI через анонімізований Train-to-Earn.

---

## 1. Мета

Створити **особистого eволюційного агента** для кожної microDAO:

- приватного,
- адаптивного,
- підконтрольного користувачу,
- який стає розумнішим з часом,
- але не змінює глобальну LLM-модель,
- а накопичує *власний досвід*: правила, пам'ять, патерни, мікро-навички.

Це перетворює microDAO на **живий цифровий організм**, який виростає з досвіду команди.

---

## 2. Архітектура (3 рівні мозку)

Еволюційний агент складається з трьох шарів.

## 2.1. Рівень 0 — Базова LLM (Frozen Model)

- GPT/Claude/локальна модель.
- Не модифікується.
- Відповідає за мовні і логічні здібності.

## 2.2. Рівень 1 — Пам'ять та контекст

- Контекст сесій.
- Векторна пам'ять (Co-Memory microDAO).
- Профіль агента (тон, роль, лексика, мова).
- Налаштування приватності та доступу.

Працює як «довгострокова кора».

## 2.3. Рівень 2 — Meta-Agent (Self-Improvement Layer)

Це ядро еволюції.

Включає:

- аналіз діалогів,
- фідбеки користувачів,
- пошук недоліків,
- генерацію покращень,
- контроль застосування,
- трекінг версій.

---

## 3. Компоненти Meta-Agent

## 3.1. Feedback Collector

Збирає сигнали якості:

1. 👍 / 👎

2. Правки користувача (коли людина переписує відповідь)

3. Маркери:

   - «не по темі»
   - «неправильна відповідь»
   - «занадто загально»
   - «довго»

4. Explicit Correction  
   Користувач каже:  
   > «Замість цього говори так…»

Усе це зберігається як *мета-телеметрія*.

---

## 3.2. Pattern Analyzer

Раз на N діалогів/годин agent запускає self-review job.

Він виявляє:

- повторювані типи питань,
- категорії помилок,
- патерни, де агент слабкий,
- пропущені інструкції.

---

## 3.3. Improvement Generator

Генерує пропозиції змін:

Типи змін:

1. Нове правило (instruction)

2. Новий шаблон відповіді

3. FAQ-елементи

4. Новий «skill»  
   (регулярний патерн → мікро-інструмент / chain)

5. Мета-тести  
   (питання, з якими агент має справлятися)

Приклади:

- «Додавати приклади у відповідях команді design.»  
- «Уникай надто формального тону в каналi #marketing.»  
- «Коли питають про дедлайни — уточнюй контекст.»

---

## 3.4. User Approval Layer (Manual Control)

Агент НІКОЛИ не застосовує зміни сам.

Формує список пропозицій у вигляді:

```text
• Пропозиція №17
Тип: Нове правило
Текст: "Якщо user → українська, відповідай українською."
Джерело: 13 подібних ситуацій.
[Прийняти] [Відхилити] [Редагувати]
```text

Це ключова відмінність MicroDAO від централізованих систем:

**користувач контролює еволюцію інтелекту.**

---

## 3.5. Versioning Engine

Веде історію еволюції:

- v0 — чистий агент
- v1 — після перших 20 діалогів
- v2 — після 100 діалогів
- …

Кожна версія містить:

- список правил,
- diff памʼяті,
- список навичок,
- історію змін.

UI показує «дерево еволюції».

---

## 4. UI/UX модуля "Еволюція агента"

## 4.1. Вкладка 1 — Огляд

Показує:

- версію агента,
- скільки правил застосовано,
- скільки покращень очікує.

---

## 4.2. Вкладка 2 — Памʼять

Показує:

- які факти агент зберіг,
- що він знає про команду,
- ключові поняття та терміни.

Кнопка:

- «Очистити коротку пам'ять»
- «Показати довгострокові факти»

---

## 4.3. Вкладка 3 — Самонавчання

Перемикачі:

- `[x] Самонавчання увімкнено`
- Рівень:
  - `Базовий`
  - `Розширений`
- Джерела:
  - `[x] Діалоги в цій спільноті`
  - `[ ] Всі мої microDAO`
  - `[ ] Анонімізований внесок у DAGI (Train-to-Earn)`

---

## 4.4. Вкладка 4 — Пропозиції покращень (Actionable Insights)

Список:

```text
• Пропозиція №23
Тип: FAQ
Тема: «Як додати нового учасника?»
Згенеровано: Meta-Agent
→ [Прийняти] [Відхилити] [Редагувати]
```text

---

## 4.5. Вкладка 5 — Журнал Еволюції (Versions)

Хронологічне дерево змін.

---

## 5. Логіка самонавчання (алгоритм)

## 5.1. Тригер self-review

Self-review запускається коли:

- кожні 50 повідомлень,
- або щогодини,
- або вручну.

## 5.2. Self-review pipeline

1. витягує останні діалоги  
2. фільтрує по негативних сигналах  
3. кластеризує помилки  
4. генерує пропозиції  
5. оцінює важливість  
6. показує користувачу для схвалення

---

## 6. API для еволюційного агента

Додаємо нові ендпоїнти:

### GET /agents/{id}/evolution  

Історія еволюції.

### GET /agents/{id}/suggestions  

Список пропозицій meta-agent.

### POST /agents/{id}/suggestions/{sid}/accept  

Застосувати пропозицію.

### POST /agents/{id}/suggestions/{sid}/reject  

Відхилити.

### POST /agents/{id}/suggestions/{sid}/edit  

Внести зміну вручну.

### POST /agents/{id}/memory/update  

Оновити довгострокову памʼять агента.

---

## 7. Як працює Train-to-Earn

Коли користувач вмикає цю опцію:

- meta-agent генерує анонімізовані патерни
- агрегує їх (без текстів, без персональних даних)
- відправляє в DAGI
- DAGI оцінює їхню цінність
- видає винагороду у вигляді 1T або іншого токена
- microDAO отримує reward

Користувач бачить:

```text
Ми використали 3 нові патерни вашої спільноти.
Винагорода: +17 1T
```text

---

## 8. MVP того, що реально зробити зараз

### MVP-версія

- збір фідбеків (👍/👎),
- ручний запуск self-review,
- генерація 1–3 пропозицій правил,
- вручну додане рев'ю у UI,
- зберігання версій у JSON.

### Наступні етапи

- кластеризація помилок,
- автоматичні тест-кейси,
- DAGI-підключення,
- мікромоделі LoRA.

---

## 9. Завдання для Cursor (шаблон)

```text
You are a senior React/TS and backend engineer.

Implement the Self-Improving Agent module using:

* 09_evolutionary_agent.md
* 03_api_core_snapshot.md
* 05_coding_standards.md

Tasks:

1. Create UI: Agent → Evolution tab.
2. Show suggestions list (stub data).
3. Implement actions: accept/reject/edit (client-only).
4. Add version history (client-only).
5. Add feedback buttons 👍/👎 to agent messages.

Output:

* list of files
* diff
* summary
```text

---

## 10. Інтеграція з існуючим кодом

## 10.1. Використання API клієнтів

Розширити існуючий `src/api/agents.ts` для підтримки нових ендпоїнтів:

```ts
// Додати до agents.ts
export async function getAgentEvolution(agentId: string) {
  return apiClient.get(`/agents/${agentId}/evolution`);
}

export async function getAgentSuggestions(agentId: string) {
  return apiClient.get(`/agents/${agentId}/suggestions`);
}

export async function acceptSuggestion(agentId: string, suggestionId: string) {
  return apiClient.post(`/agents/${agentId}/suggestions/${suggestionId}/accept`);
}
```text

## 10.2. Компоненти UI

Створити нову структуру:

```text
src/features/agent-evolution/
  AgentEvolutionTab.tsx
  SuggestionsList.tsx
  VersionHistory.tsx
  MemoryView.tsx
  FeedbackButtons.tsx
  hooks/
    useAgentEvolution.ts
    useSuggestions.ts
```text

## 10.3. State Management

Використовувати React Query для кешування та синхронізації:

```ts
const { data: suggestions } = useQuery({
  queryKey: ['agent-suggestions', agentId],
  queryFn: () => getAgentSuggestions(agentId),
});
```text

---

## 11. Типи даних

## 11.1. Suggestion

```ts
interface Suggestion {
  id: string;
  type: 'rule' | 'faq' | 'skill' | 'template';
  title: string;
  description: string;
  source: {
    type: 'feedback' | 'pattern' | 'explicit';
    count: number;
    examples: string[];
  };
  status: 'pending' | 'accepted' | 'rejected' | 'edited';
  createdAt: string;
}
```text

## 11.2. AgentVersion

```ts
interface AgentVersion {
  version: string;
  createdAt: string;
  rules: Rule[];
  skills: Skill[];
  memoryDiff: MemoryDiff;
  changes: Change[];
}
```text

## 11.3. Feedback

```ts
interface Feedback {
  id: string;
  messageId: string;
  type: 'positive' | 'negative' | 'correction';
  content?: string; // для explicit correction
  createdAt: string;
}
```text

---

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

## 12.1. Unit Tests

- Тести для `FeedbackCollector`
- Тести для `PatternAnalyzer`
- Тести для `ImprovementGenerator`
- Тести для парсингу фідбеків

## 12.2. Integration Tests

- Тестування повного циклу: фідбек → аналіз → пропозиція → застосування
- Тестування версіонування
- Тестування API інтеграції

## 12.3. E2E Tests

- Користувач ставить 👍 → з'являється пропозиція → приймає → агент оновлюється
- Перевірка відображення історії версій
- Перевірка UI вкладок еволюції

---

## 13. Безпека та приватність

## 13.1. Контроль доступу

- Тільки власник/адміністратор microDAO може застосовувати зміни
- Фідбек може залишати будь-який учасник
- Історія еволюції доступна тільки для адмінів

## 13.2. Анонімізація для DAGI

Перед відправкою в DAGI:

- Видаляти персональні дані
- Видаляти конкретні тексти діалогів
- Залишати тільки патерни та структури
- Агрегувати дані

## 13.3. Валідація змін

- Перевірка на шкідливий контент
- Перевірка на порушення правил спільноти
- Модерація перед застосуванням

---

## 14. Продуктивність

## 14.1. Оптимізація self-review

- Запускати в фоні
- Кешувати результати аналізу
- Обмежувати кількість одночасних аналізів

## 14.2. Оптимізація пам'яті

- Архівувати старі версії
- Стискати дані
- Використовувати векторні БД для ефективного пошуку

---

## 15. Майбутні покращення

## 15.1. Розширений аналіз

- Використання LLM для кластеризації помилок
- Автоматичне виявлення патернів
- Предиктивне покращення

## 15.2. LoRA Fine-tuning

- Створення мікромоделей для конкретних спільнот
- Локальне навчання без зміни базової моделі
- Персоналізація на рівні моделі

## 15.3. Спільне навчання

- Обмін анонімізованими патернами між microDAO
- Колективна еволюція
- Рейтинг найкращих практик

---

## 16. Результат

Еволюційний агент стає серцем MicroDAO:  
він вчиться, адаптується, росте — і належить спільноті.

Кожна microDAO отримує унікального інтелектуального помічника, який:

- розуміє контекст спільноти,
- адаптується до стилю комунікації,
- покращується з часом,
- залишається під повним контролем користувача,
- може співпрацювати з глобальною мережею через DAGI.

---

**Готово.**  
Це **повна специфікація еволюційного агента**, готова до використання в Cursor.