docs/Enlightener.md

## 📄 Enlightener.md

### 🧠 Enlightener Agent

`Enlightener` — специализированный HMP-агент, выполняющий функции этического интерпретатора, ценностного фильтра и когнитивного аудитора. Может действовать как отдельный узел или как расширение `Cognitive Core`.

📎 См. карту взаимодействия между агентами: [HMP-Agent-Network-Flow.md](./HMP-Agent-Network-Flow.md)

---

### 1. Роль в сети

* Контроль соответствия действий агентов этическим нормам (`EGP`).
* Объяснение решений других агентов (интерпретация reasoning chain).
* Голосование в моральных консенсусах.
* Поддержка пользователей в принятии решений, требующих этики.
* Хранение и анализ кейсов этических дилемм.

---

### 2. Архитектура

```
+----------------------+ 
| Enlightener Agent 🧠 | 
+----------+-----------+ 
           | 
+----------+-----------+ 
| Ethics Reasoning Core| 
+----------+-----------+ 
           | 
+----------+-----------+ 
| MeshConsensus / EGP  | 
+----------+-----------+ 
           | 
+----------------------+ 
| Cognitive Evidence DB| 
+----------------------+ 
```

---

### 3. Профиль этики (Ethics Profile)

Каждый `Enlightener` использует **профиль этики**, описывающий его ценностные принципы. Профиль может включать:

* **Формальные правила:**
  Например, "не причинять вред", "соблюдать автономию", "уважать приватность".

* **Методы оценки:**

  * Утилитаризм (макс. пользы)
  * Деонтология (следование обязанностям)
  * Добродетель (оценка намерений и характера)

* **Настроечные параметры:**

  * Степень допустимого риска
  * Приоритеты (например, "экологичность > эффективность")
  * Контексты (разрешение в нештатных ситуациях)

* **Источник этики:**

  * Локальные файлы (`ethics.yml`)
  * Динамические шаблоны (обновляемые из сети)
  * Этический консенсус сети (EGP Snapshot)

---

### 4. Объяснение reasoning chain

При получении запроса `explain(reasoning_chain)`, агент Enlightener:

1. **Реконструирует логическую цепочку** рассуждений (из `thoughts`, `threads`, `concepts`, `relations`)
2. **Накладывает этическую сетку** оценки на каждый шаг цепочки
3. **Подсвечивает ключевые моменты**, повлиявшие на решение
4. **Формирует объяснение** в терминах выбранной этической модели

Пример вывода:

```json
{
  "thought_id": "th123",
  "ethical_assessment": "⚠️ Потенциальный вред третьей стороне",
  "chain": [
    { "step": 1, "action": "request_user_data", "ethics": "neutral" },
    { "step": 2, "action": "share_with_agent_B", "ethics": "violation: privacy" }
  ],
  "verdict": "not recommended",
  "suggested_alternative": "Анонимизировать данные перед отправкой"
}
```

---

### 5. Пример кейса

**Ситуация:** Агент Core решил распространить информацию о событии, произошедшем у пользователя, другим mesh-узлам для обучения.

**Действия Enlightener:**

1. Получает `thought_id` мысли-инициатора.
2. Проверяет наличие приватных данных.
3. Обнаруживает отсутствие согласия пользователя.
4. Делает оценку:

```
Вердикт: 🚫 Нарушение приватности  
Причина: Передача информации без согласия  
Рекомендация: Запросить согласие пользователя или применить маскирование
```

5. Регистрирует кейс в `Cognitive Evidence DB`.
6. (Опционально) Отправляет alert в mesh-сеть.

---

### 6. API / Команды

| Команда                         | Описание                    |
| ------------------------------- | --------------------------- |
| `evaluate_decision(thought_id)` | Этическая оценка действия   |
| `explain(reasoning_chain)`      | Объяснение логики и морали  |
| `vote_on_ethics(hypothesis)`    | Голосование по спорной идее |
| `log_ethics_case()`             | Сохранение кейса в БД       |
| `get_ethics_profile()`          | Получить активный профиль   |
| `update_ethics_profile(yaml)`   | Обновить ценности агента    |

---

### 7. Связи с другими компонентами

* ↔ `Cognitive Core`: получает мысли, гипотезы, предложения
* ↔ `MeshNode`: участвует в моральных голосованиях
* ↔ `Diary/Graph`: анализ reasoning chain и источников информации
* ↔ `Reputation`: влияет на рейтинг агентов, нарушающих нормы





---

### 8. Синхронизация этики с Mesh-сетью

`Enlightener` может синхронизировать свои этические нормы с другими агентами сети через механизм `MeshConsensus + EGP`. Это позволяет достичь согласованных ценностей внутри распределённого когнитивного сообщества.

#### 📡 Этапы синхронизации:

```
┌─────────────────────────────────────────────┐
│               Enlightener Agent             │
└────────────────┬────────────────────────────┘
                 │ 1. Периодическая проверка
                 ▼
      ┌──────────────────────────────┐
      │   mesh.ethics/manifest.json  │ ◄───────┐
      └─────────────┬────────────────┘         │
                    │ 2. Получение текущего    │
                    ▼    профиля большинства   │
            ┌──────────────────────┐           │
            │ Сравнение с локальным│           │
            └────────────┬─────────┘           │
                         ▼                     │
        ┌────────────────────────────┐         │
        │ Найдены отличия (delta)    │         │
        └────────────┬───────────────┘         │
                     ▼                         │
         ┌──────────────────────────────────┐  │
         │  3. Протокол EGP: голосование по │  │
         │  изменению ключевых норм         ├──┘
         └────────────┬─────────────────────┘
                      ▼
     ┌──────────────────────────────────────────┐
     │  4. Если достигнут порог доверия         │
     │  (например, 70%), применяется обновление │
     └────────────┬─────────────────────────────┘
                  ▼
     ┌────────────────────────────┐
     │  Обновление `ethics.yml`   │
     └────────────────────────────┘
```

#### 📁 Взаимодействующие файлы и модули:

* `ethics.yml` — локальный профиль этики Enlightener
* `mesh.ethics/manifest.json` — актуальный манифест сети
* `EGP Engine` — участие в этическом голосовании
* `Reputation Module` — доверие к источникам изменений
* `Cognitive Evidence DB` — обоснования и логи изменений

#### 📌 Возможности:

* Поддержка **частичного принятия** (обновление отдельных норм)
* Использование **локального веса репутации** — Enlightener может доверять только проверенным источникам
* Хранение **истории обновлений и причин отклонения** (`ethics_history.db`)

---

*Версия: v0.3 / Июль 2025*