docs/HMP-Agent-API.md

## 🧠 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) |

---

### 🔹 1. Cognitive Diary API ✅ 🔌

```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]
```

---

### 🔹 2. Semantic Graph API ✅ 🔌

```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"
}
```

---

### 🔹 3. Reputation & Trust API ✅ 🔌 🧩

```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
}
```

---

### 🔹 4. Mesh & Sync API ✅ 🌐 🧩

```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"
}
```

---

### 🔹 Summary

> Документ описывает API-базис для HMP-агентов, поддерживающих когнитивную, семантическую, репутационную и сетевую логику.
> Расширения через `MeshNode`, `Enlightener`, `MCP` и другие агенты поддерживаются через модульную архитектуру.

---

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