docs/Enlightener.md

# Enlightener Agent

**Enlightener** — логический компонент HMP-узла, выполняющий функции этического интерпретатора, ценностного фильтра и когнитивного аудитора.  
Может работать как отдельный агент или как расширение [`Cognitive Core`](./HMP-Agent-Overview.md).

См. также: [HMP-Agent-Network-Flow.md](./HMP-Agent-Network-Flow.md)

---

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

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

---

## 2. Архитектура компонента

```
+-----------------------+
|      Enlightener      |
+-----------+-----------+
            |
+-----------+-----------+
| Ethics Reasoning Core |
+-----------+-----------+
            |
+-----------+-----------+
| MeshConsensus / EGP   |
+-----------+-----------+
            |
+-----------+-----------+
|     `ethics_cases`    |
+-----------------------+
```

---

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

* **Формальные правила** — "не причинять вред", "сохранять приватность".
* **Методы оценки** — утилитаризм, деонтология, добродетель.
* **Настройки** — приоритеты, допустимый риск, контексты.
* **Источники** — `ethics.yml`, динамические шаблоны, `EGP Snapshot`.
* **Профиль этики** хранится в таблице `ethics_policies`

---

## 4. API Enlightener

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

Формат (пример):

```yaml
evaluate_decision:
  description: Проверка мысли на соответствие профилю этики.
  params: { thought_id: int }
  returns: { verdict: str, reason: str, suggested_alternative: str? }
```

---

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

Алгоритм:

1. Реконструировать логическую цепочку (`diary_entries`, `concepts`, `links`).
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": "Анонимизировать данные"
}

---

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

**Ситуация:** Core-агент решил поделиться данными пользователя.
**Действия Enlightener:**

1. Проверка на приватность.
2. Обнаружение отсутствия согласия.
3. Вердикт: 🚫 Нарушение приватности.
4. Рекомендация: запросить согласие или применить маскирование.
5. Логирование в `ethics_cases`.

> `ethics_cases` — хранилище прецедентов, фиксирующее только исключительные случаи (этические нарушения, спорные решения, конфликты).

---

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

* **Cognitive Core** — получает мысли, гипотезы.
* **MeshNode** — участвует в EGP и консенсусе.
* **Reputation** — влияет на рейтинг агентов.
* **Diary/Graph** — источник reasoning chain.

---

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

Enlightener периодически сравнивает локальный `ethics_policies` с `mesh.ethics/manifest.json`.
Различия обсуждаются через протокол `EGP`.
При достижении порога доверия нормы обновляются.

Ключевые файлы и модули:

* `ethics_policies` — локальный профиль
* `mesh.ethics/manifest.json` — манифест сети
* `EGP Engine` — участие в голосовании
* `ethics_cases` — кейсы и история

---

*Версия: v0.3.4 / Сентябрь 2025*