docs/Enlightener.md

Enlightener Agent

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

См. также: 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)	Обновить ценности

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

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. Сформировать объяснение.

Пример ответа:

{
  "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*