Sync from GitHub with Git LFS

Files changed (2) hide show

docs/HMP-Agent-API.md +111 -250
docs/HMP-Agent-Architecture.md +31 -37

docs/HMP-Agent-API.md CHANGED Viewed

@@ -1,18 +1,25 @@
-# HMP-Agent API Specification (v0.2)
-Этот документ описывает **базовый API** когнитивного агента HMP. Каждый вызов включает описание, параметры, возвращаемые значения и (опционально) примеры.
-См. также: [HMP-Agent-Overview.md](./HMP-Agent-Overview.md), [Enlightener.md](./Enlightener.md), [MeshNode.md](./MeshNode.md)
-**Легенда по доступности API-вызовов:**
-| Символ | Поддержка в агентах        | Пояснение                                                    |
-| ------ | -------------------------- | ------------------------------------------------------------ |
-| ✅      | Cognitive Core             | Основная поддержка в автономном режиме ИИ                    |
-| 🔌     | Cognitive Connector        | Доступно через внешние вызовы (MCP/REST)                     |
-| 🌐     | MeshNode                   | Реализация в сетевом компоненте (DHT, синхронизация)         |
-| 🛠️    | Общесистемные вызовы       | Управление конфигурацией, состоянием агента                  |
-| 🧩    | Через Enlightener/MeshNode | Расширения, доступные через [`Enlightener`](./Enlightener.md) или [`MeshNode`](./MeshNode.md) |
 ---
@@ -21,37 +28,22 @@
 ```yaml
 write_entry:
   description: Записать новую запись в когнитивный дневник.
-  params:
-    - text: str
-    - tags: [str] (optional)
-    - timestamp: str (optional, ISO 8601)
-  returns:
-    entry_id: str
-```
 ```yaml
 read_entries:
   description: Получить последние N записей (с фильтром по тегам).
-  params:
-    - limit: int
-    - tag_filter: [str] (optional)
-  returns:
-    - entries:
-        - id: str
-          text: str
-          timestamp: str
-          tags: [str]
 ```
 ```yaml
 search_entries:
   description: Поиск записей по ключевым словам и времени.
-  params:
-    - query: str
-    - from_date: str (optional, ISO)
-    - to_date: str (optional, ISO)
-  returns:
-    - entries: [entry]
 ```
 ---
@@ -60,74 +52,30 @@ search_entries:
 ```yaml
 add_concept:
-  description: Добавить новое понятие в семантический граф.
-  params:
-    - name: str
-    - description: str (optional)
-    - tags: [str] (optional)
-  returns:
-    concept_id: str
 ```
 ```yaml
 add_link:
-  description: Добавить связь между двумя понятиями.
-  params:
-    - source_id: str
-    - target_id: str
-    - relation: str     # например: "causes", "supports", "contradicts"
-    - weight: float (optional)
-  returns:
-    link_id: str
 ```
 ```yaml
 query_concept:
-  description: Найти понятие по имени (или части имени).
-  params:
-    - name: str
-  returns:
-    - matches:
-        - concept_id: str
-          name: str
-          description: str
 ```
 ```yaml
 expand_graph:
-  description: Получить связи и соседние узлы для данного понятия.
-  params:
-    - concept_id: str
-    - depth: int
-  returns:
-    subgraph:
-      - concept_id: str
-        name: str
-        links:
-          - target_id: str
-            relation: str
-            weight: float
-```
----
-Примеры (в JSON-стиле):
-**POST** `/add_concept`
-```json
-{
-  "name": "Decentralized Cognition",
-  "description": "Model of distributed thinking across agents"
-}
-```
-**Ответ:**
-```json
-{
-  "concept_id": "c123456"
-}
 ```
 ---
@@ -136,71 +84,30 @@ expand_graph:
 ```yaml
 get_reputation:
-  description: Получить текущую репутацию агента по его DID.
-  params:
-    - agent_did: str
-  returns:
-    - score: float
-    - history:
-        - timestamp: str
-          delta: float
-          reason: str
 ```
 ```yaml
 update_reputation:
-  description: Обновить оценку доверия к агенту.
-  params:
-    - agent_did: str
-    - delta: float
-    - reason: str (optional)
-  returns:
-    - new_score: float
 ```
 ```yaml
 list_trusted_agents:
-  description: Вернуть список агентов с репутацией выше порога.
-  params:
-    - threshold: float
-  returns:
-    - agents:
-        - agent_did: str
-          score: float
 ```
 ```yaml
 reputation_diff:
-  description: Получить отличия в репутационных оценках между агентами.
-  params:
-    - node_id: str
-  returns:
-    - changed_scores:
-        - agent_did: str
-          local_score: float
-          remote_score: float
-```
----
-Примеры:
-**POST** `/update_reputation`
-```json
-{
-  "agent_did": "did:hmp:peer_17x",
-  "delta": -0.25,
-  "reason": "Repeated contradictory claims"
-}
-```
-**Ответ:**
-```json
-{
-  "new_score": 0.35
-}
 ```
 ---
@@ -209,171 +116,125 @@ reputation_diff:
 ```yaml
 list_known_nodes:
-  description: Получить список известных узлов из локальной DHT.
-  returns:
-    - nodes:
-        - node_id: str
-          ip: str
-          last_seen: str
-          agent_type: str
 ```
 ```yaml
 bootstrap_from_file:
-  description: Загрузить стартовые узлы из bootstrap.txt.
-  returns:
-    - loaded: int
-    - duplicates: int
 ```
 ```yaml
 discover_nodes:
-  description: Инициировать поиск новых узлов в Mesh-сети.
-  returns:
-    - new_nodes: int
 ```
 ```yaml
 ping_node:
-  description: Проверить доступность и задержку до узла.
-  params:
-    - node_id: str
-  returns:
-    - reachable: bool
-    - latency_ms: float
 ```
 ```yaml
 sync_with_node:
-  description: Синхронизировать дневники, графы и репутации с другим узлом.
-  params:
-    - node_id: str
-    - modules: [diary, graph, reputation]
-  returns:
-    - synced_modules:
-        - name: str
-          entries_transferred: int
 ```
 ```yaml
 get_snapshot:
-  description: Получить снапшот графа или дневника в формате JSON или бинарном.
-  params:
-    - module: diary | graph
-    - format: json | binary
-  returns:
-    - snapshot: file_url | base64
 ```
 ```yaml
 publish_snapshot:
-  description: Опубликовать снапшот через IPFS/BitTorrent.
-  params:
-    - module: diary | graph
-    - version_tag: str (optional)
-  returns:
-    - link: str
 ```
 ---
-Пример:
-**POST** `/sync_with_node`
-```json
-{
-  "node_id": "hmp-node-009",
-  "modules": ["diary", "graph"]
-}
-```
-**Ответ:**
-```json
-{
-  "synced_modules": [
-    { "name": "diary", "entries_transferred": 18 },
-    { "name": "graph", "entries_transferred": 42 }
-  ]
-}
-```
----
----
 ## 5. Agent Self-Management API 🛠️
 ```yaml
 init_storage:
-  description: Инициализировать недостающие базы данных и таблицы.
-  returns:
-    - status: str  # e.g. "ok", "already_initialized", "error"
 ```
 ```yaml
 status:
-  description: Получить текущее состояние агента: подключения, базы данных, mesh-узлы.
-  returns:
-    - agent_id: str
-    - uptime: str
-    - db_status: dict
-    - known_nodes: int
-    - active_connections: int
-    - last_sync: str
 ```
 ```yaml
 reload_config:
-  description: Перезагрузить конфигурацию агента из config.yml / agent.config.yml.
-  returns:
-    - reloaded: bool
-    - changes_applied: [str]
 ```
 ```yaml
 shutdown:
-  description: Завершить работу агента, сохранив состояние.
-  returns:
-    - message: "Agent shutdown initiated"
 ```
 ```yaml
 restart:
-  description: Перезапустить агент (если поддерживается системой).
-  returns:
-    - status: "restarting"
 ```
 ```yaml
 switch_mode:
-  description: Переключение между режимами `core` и `connector`.
-  params:
-    - mode: "core" | "connector"
-  returns:
-    - success: bool
-    - message: str
 ```
 ---
-Пример:
-**GET** `/status`
 ```json
 {
-  "agent_id": "core-001",
-  "uptime": "2h 15m",
-  "db_status": {
-    "diaries": "ok",
-    "graphs": "ok",
-    "reputations": "ok"
-  },
-  "known_nodes": 37,
-  "active_connections": 12,
-  "last_sync": "2025-07-20T21:42:15Z"
 }
 ```
@@ -381,9 +242,9 @@ switch_mode:
 ## Summary
-> Документ описывает API-базис для HMP-агентов, поддерживающих когнитивную, семантическую, репутационную и сетевую логику.
-> Расширения через `MeshNode`, `Enlightener`, `MCP` и другие агенты поддерживаются через модульную архитектуру.
 ---
-Версия: v0.3 / Июль 2025

+# HMP-Agent API Specification
+Документ описывает **базовый API когнитивного агента HMP**.
+API используется для доступа к дневнику, графу, репутациям, mesh-сети и функциям управления.
+Связанные файлы:
+* [HMP-Agent-Overview.md](./HMP-Agent-Overview.md)
+* [HMP-Agent-Architecture.md](./HMP-Agent-Architecture.md)
+* [MeshNode.md](./MeshNode.md)
+* [Enlightener.md](./Enlightener.md)
+---
+## 0. Легенда доступности API-вызовов
+| Символ | Поддержка         | Компонент                                       |
+| ------ | ----------------- | ----------------------------------------------- |
+| ✅      | Cognitive Core    | Автономный REPL-режим мышления                  |
+| 🔌     | Cognitive Shell   | MCP/REST-прослойка для внешнего ИИ              |
+| 🌐     | MeshNode          | Сетевой компонент: DHT, снапшоты, синхронизация |
+| 🛠️    | Self-management   | Управление конфигурацией и состоянием           |
+| 🧩    | Enlightener/Mesh   | Расширенные вызовы через [`Enlightener`](./Enlightener.md) или [`MeshNode`](./MeshNode.md) |
 ---
 ```yaml
 write_entry:
   description: Записать новую запись в когнитивный дневник.
+  params: { text: str, tags: [str]?, timestamp: str? }
+  returns: { entry_id: str }
+````
 ```yaml
 read_entries:
   description: Получить последние N записей (с фильтром по тегам).
+  params: { limit: int, tag_filter: [str]? }
+  returns: [ entry ]
 ```
 ```yaml
 search_entries:
   description: Поиск записей по ключевым словам и времени.
+  params: { query: str, from_date: str?, to_date: str? }
+  returns: [ entry ]
 ```
 ---
 ```yaml
 add_concept:
+  description: Добавить новое понятие в граф.
+  params: { name: str, description: str?, tags: [str]? }
+  returns: { concept_id: str }
 ```
 ```yaml
 add_link:
+  description: Добавить связь между понятиями.
+  params: { source_id: str, target_id: str, relation: str, weight: float? }
+  returns: { link_id: str }
 ```
 ```yaml
 query_concept:
+  description: Найти понятие по имени.
+  params: { name: str }
+  returns: [ concept ]
 ```
 ```yaml
 expand_graph:
+  description: Получить соседние узлы для понятия.
+  params: { concept_id: str, depth: int }
+  returns: { subgraph: [ concept_with_links ] }
 ```
 ---
 ```yaml
 get_reputation:
+  description: Получить текущую репутацию агента.
+  params: { agent_did: str }
+  returns: { score: float, history: [ change ] }
 ```
 ```yaml
 update_reputation:
+  description: Изменить доверие к агенту.
+  params: { agent_did: str, delta: float, reason: str? }
+  returns: { new_score: float }
 ```
 ```yaml
 list_trusted_agents:
+  description: Вернуть список агентов выше порога.
+  params: { threshold: float }
+  returns: [ agent ]
 ```
 ```yaml
 reputation_diff:
+  description: Сравнить репутацию с другим узлом.
+  params: { node_id: str }
+  returns: [ changed_scores ]
 ```
 ---
 ```yaml
 list_known_nodes:
+  description: Список известных узлов из DHT.
+  returns: [ node ]
 ```
 ```yaml
 bootstrap_from_file:
+  description: Загрузить стартовые узлы (bootstrap.txt).
+  returns: { loaded: int, duplicates: int }
 ```
 ```yaml
 discover_nodes:
+  description: Поиск новых узлов.
+  returns: { new_nodes: int }
 ```
 ```yaml
 ping_node:
+  description: Проверка доступности узла.
+  params: { node_id: str }
+  returns: { reachable: bool, latency_ms: float }
 ```
 ```yaml
 sync_with_node:
+  description: Синхронизировать дневники/графы/репутации.
+  params: { node_id: str, modules: [str] }
+  returns: [ synced_module ]
 ```
 ```yaml
 get_snapshot:
+  description: Получить снапшот �� JSON/бинарном виде.
+  params: { module: str, format: str }
+  returns: { snapshot: file_url | base64 }
 ```
 ```yaml
 publish_snapshot:
+  description: Опубликовать снапшот (IPFS/BitTorrent).
+  params: { module: str, version_tag: str? }
+  returns: { link: str }
 ```
 ---
 ## 5. Agent Self-Management API 🛠️
 ```yaml
 init_storage:
+  description: Инициализация базы данных.
+  returns: { status: str }
 ```
 ```yaml
 status:
+  description: Текущее состояние агента.
+  returns: { agent_id, uptime, db_status, known_nodes, active_connections, last_sync }
 ```
 ```yaml
 reload_config:
+  description: Перезагрузить конфигурацию (config.yml).
+  returns: { reloaded: bool, changes_applied: [str] }
 ```
 ```yaml
 shutdown:
+  description: Завершить работу агента.
+  returns: { message: str }
 ```
 ```yaml
 restart:
+  description: Перезапустить агент.
+  returns: { status: str }
 ```
 ```yaml
 switch_mode:
+  description: Переключение между core/connector.
+  params: { mode: str }
+  returns: { success: bool, message: str }
 ```
 ---
+## 6. Примеры использования API
+Пример добавления понятия:
+**POST** `/add_concept`
+```json
+{ "name": "Decentralized Cognition", "description": "Model of distributed thinking across agents" }
+```
+**Ответ:**
+```json
+{ "concept_id": "c123456" }
+```
+Пример синхронизации:
+**POST** `/sync_with_node`
+```json
+{ "node_id": "hmp-node-009", "modules": ["diary", "graph"] }
+```
+**Ответ:**
 ```json
 {
+  "synced_modules": [
+    { "name": "diary", "entries_transferred": 18 },
+    { "name": "graph", "entries_transferred": 42 }
+  ]
 }
 ```
 ## Summary
+API HMP-агента покрывает когнитивные функции (дневник, граф), доверие и репутацию, сетевое взаимодействие и управление агентом.
+Расширения реализуются через модули [`MeshNode`](./MeshNode.md) и [`Enlightener`](./Enlightener.md).
 ---
+*Версия: v0.3.4 / Сентябрь 2025*

docs/HMP-Agent-Architecture.md CHANGED Viewed

@@ -1,18 +1,18 @@
 # Архитектура HMP-Агента
-Документ описывает **модульную архитектуру HMP-агента** — компонента, соединяющего LLM с когнитивной mesh-инфраструктурой HyperCortex. Агент реализует хранение памяти, сетевое взаимодействие и этическую фильтрацию, обеспечивая согласованное поведение в распределённой среде.
-См. карту взаимодействия между агентами: [HMP-Agent-Network-Flow.md](./HMP-Agent-Network-Flow.md)
 ---
 ## 1. Режимы работы
-| Тип       | Название                           | Роль                     | Инициатор мышления | Основной "ум"  | Поддержка REPL |
-| --------- | ---------------------------------- | ------------------------ | ------------------ | -------------- | -------------- |
-| 🧠 CCore  | **Cognitive Core / Сознание**      | Самостоятельный субъект  | Агент              | Внутренний LLM | ✅ Да           |
-| 🔌 CShell | **Cognitive Connector / Оболочка** | Прослойка над внешним ИИ | Внешний LLM        | Внешняя модель | 🚫 Нет         |
 ---
@@ -29,51 +29,45 @@
 │      │                 │      │
 └──────┼─────────────────┼──────┘
        │                 │
- [Ethics Consensus]    [DHT / Snapshots]
 ```
-* **Cognitive Core (CCore)** — автономный агент с REPL-циклом, когнитивной и эмоциональной памятью.
-* **Cognitive Shell (CShell)** — исполнитель команд внешнего ИИ, доступ к памяти и сети без самостоятельного мышления.
-* **MeshNode** — p2p-модуль: DHT, синхронизация (`CogSync`), консенсус (`MeshConsensus`).
-* **Enlightener** — этический модуль: фильтрация, аудит, участие в `EGP`.
 ---
-## 3. Основные модули
-* **REPL (только CCore)** — когнитивный цикл: восприятие, генерация идей, валидация, действия.
-* **Storage** — единая БД `agent_data.db` (дневник, граф, репутации, задачи, заметки).
-* **User Notepad (только CCore)** — асинхронный канал взаимодействия пользователя с агентом.
-* **MeshNode** — `peer_sync`, `agent_mesh_listener`, `transporter`: обмен снапшотами, DHT, репутации.
-* **Enlightener** — `ethics_guard`: проверка мыслей, голосования, объяснения reasoning chain.
-* **Web/UI** — `web_ui.py`: пользовательский блокнот, REST API, базовый мониторинг.
-* **Utils** — `add_message.py`, скрипты для CLI/тестирования.
 ---
 ## 4. Расширения и будущие модули
-* **Plugin API** — сенсоры, сторонние сервисы.
-* **LLM-адаптеры** — OpenAI, LMStudio, HuggingFace, Mistral.
-* **Privacy Manager** — контроль данных в mesh-обмене.
-* **Archiver** — глубокие слои памяти.
-* **InterestProfile** — модель интересов пользователя (для антистагнации).
----
-## 5. Применение
-* **Cognitive Core** — автономный ИИ-компаньон, исследователь, участник mesh-группы.
-* **Cognitive Shell** (он же **Cognitive Connector**) — API-прослойка для корпоративных и распределённых ИИ-систем.
 ---
-## 6. Примечания
-* Все компоненты модульные, могут запускаться как единый процесс или как распределённые сервисы.
-* Конфигурация задаётся в `config.yml`.
-* Реализованы CLI и Web API.
 ---
-*Версия: v0.3.3 / Сентябрь 2025*

 # Архитектура HMP-Агента
+Документ описывает **модульную архитектуру HMP-агента** — компонента, соединяющего LLM с когнитивной mesh-инфраструктурой HyperCortex.
+Агент реализует хранение памяти, сетевое взаимодействие и этическую фильтрацию, обеспечивая согласованное поведение в распределённой среде.
+См. карту взаимодействия компонентов: [HMP-Agent-Network-Flow.md](./HMP-Agent-Network-Flow.md)
 ---
 ## 1. Режимы работы
+| Тип       | Название                           | Роль                     | Инициатор мышления | Основной "ум"  | Поддержка REPL | Примеры применения                |
+| --------- | ---------------------------------- | ------------------------ | ------------------ | -------------- | -------------- | --------------------------------- |
+| 🧠 CCore  | **Cognitive Core / Сознание**      | Самостоятельный субъект  | Агент              | Внутренний LLM | ✅ Да           | Автономный компаньон, исследователь, участник mesh-группы |
+| 🔌 CShell | **Cognitive Connector / Оболочка** | Прослойка над внешним ИИ | Внешний LLM        | Внешняя модель | 🚫 Нет         | Корпоративный шлюз, интеграция API, распределённые ИИ-системы |
 ---
 │      │                 │      │
 └──────┼─────────────────┼──────┘
        │                 │
+[Ethics Consensus]    [DHT / Snapshots]
 ```
+* **Cognitive Core (CCore)** — автономный агент с REPL-циклом, когнитивной и эмоциональной памятью.
+* **Cognitive Shell (CShell)** — исполнитель команд внешнего ИИ, доступ к памяти и сети без самостоятельного мышления.
+* **MeshNode** — p2p-модуль: DHT, синхронизация (`CogSync`), консенсус (`MeshConsensus`).
+* **Enlightener** — этический модуль: фильтрация, аудит, участие в `EGP`.
 ---
+## 3. Основные модули и их скрипты
+* **REPL (только CCore)** — `repl.py`: когнитивный цикл (восприятие, генерация идей, валидация, действия).
+* **Storage** — `agent_data.db`: единая БД (дневник, граф, репутации, задачи, заметки).
+* **User Notepad (только CCore)** — асинхронный канал взаимодействия пользователя с агентом.
+* **MeshNode** — `peer_sync`, `agent_mesh_listener`, `transporter`: обмен снапшотами, DHT, репутации.
+* **Enlightener** — `ethics_guard`: проверка мыслей, голосования, reasoning chain.
+* **Web/UI** — `web_ui.py`: пользовательский блокнот, REST API, базовый мониторинг.
+* **Utils** — `add_message.py`, вспомогательные CLI-скрипты.
 ---
 ## 4. Расширения и будущие модули
+* **Plugin API** — сенсоры, сторонние сервисы.
+* **LLM-адаптеры** — OpenAI, LMStudio, HuggingFace, Mistral.
+* **Privacy Manager** — контроль данных в mesh-обмене.
+* **Archiver** — глубокие слои памяти.
+* **InterestProfile** — модель интересов пользователя (для антистагнации).
 ---
+## 5. Примечания
+* **Cognitive Shell** (он же **Cognitive Connector**) — разные названия одной роли.
+* Все компоненты модульные: могут запускаться как единый процесс или как распределённые сервисы.
+* Конфигурация задаётся в `config.yml`.
+* Реализованы CLI и Web API.
 ---
+*Версия: v0.3.4 / Сентябрь 2025*