Red Queen
7ae7249c00
15 knowledge objects (log, note, index, module, history) migrated to C3 knowledge schema v1. Bodies unchanged, metadata preserved.
228 lines
14 KiB
Markdown
228 lines
14 KiB
Markdown
---
|
||
id: object/3063a680-c35e-a62c-91b4-f382027930a5
|
||
type: arch
|
||
role: module
|
||
representation: canonical
|
||
state: current
|
||
knowledge_schema: 1
|
||
---
|
||
# Modul-17: Hermes-Agent (autonomer Research-/Analyse-Worker unter Paperclip)
|
||
|
||
**Status: FREIGEGEBEN (21.08.2026)** · Container `Modul-17-Hermes-Agent` · Image `trading-modules-modul17-hermes-agent:latest`
|
||
|
||
> ⚠️ **Keine Namenskollision** mit fremden Containern. Hermes läuft im `trading-modules`-Netz
|
||
> als `Modul-17-Hermes-Agent`. Fremdsysteme (`paperclip-dn8l-paperclip-1` u.ä., Coolify) nie anfassen.
|
||
|
||
## Zweck & Rolle
|
||
Hermes ist die **autonome Research-/Analyse-Ausführungsebene unter Paperclip (M16)**. Er nimmt
|
||
von Paperclip delegierte Tasks (Research, längere Analysen, Strategie-Review, Analytics-Auswertung,
|
||
Backtest-/Optimization-Auswertung, Systemdiagnose READ-ONLY) entgegen und führt sie **ausschließlich
|
||
über die strikte Tool-Whitelist** aus. Das Ergebnis geht als `agent_run`/`result_refs` an Paperclip
|
||
zurück.
|
||
|
||
**Kritische Grenze — Hermes ist NICHT Teil des kritischen Trading-Pfads und darf NICHT:**
|
||
- direkt auf Modul-09 Execution zugreifen, Orders erzeugen
|
||
- Risk-/Portfolio-Regeln (M07/M08) überschreiben
|
||
- M15-Control verändern (PAUSE/HALT/RESUME)
|
||
- Strategien automatisch produktiv aktivieren
|
||
- Optimierungsparameter automatisch deployen
|
||
- Broker-Credentials erhalten
|
||
|
||
**Paperclip bleibt Orchestrator.** Hermes arbeitet NUR über die erlaubten Tools/APIs. Unbekannte
|
||
oder unerlaubte Tools → **REJECTED**.
|
||
|
||
## Architektur / Datenfluss
|
||
```
|
||
Paperclip (M16) ── Task ──▶ Modul-17-Hermes-Agent (Port 55017, NUR intern/expose)
|
||
│
|
||
├── app/core/tool_whitelist.py strikte Tool-Whitelist (Herzstück)
|
||
├── app/core/executor.py Hermes-Executor (Tool-Ausführung + Audit + Idempotenz)
|
||
├── app/storage/storage.py Persistenz hermes_task/run/tool_call/result
|
||
├── app/clients/clients.py Read-Clients + 2 begrenzte Write-Clients
|
||
└── app/api/main.py REST-API (/health, /tasks, /runs, /tools)
|
||
│
|
||
├── READ (tolerant): Modul-03 Market Data, M04 Regime, M05 Strategy,
|
||
│ M06 Ranking, M10 Journal, M11 Analytics, M15 Monitoring (GET)
|
||
└── WRITE (begrenzt): Modul-12 POST /backtest, Modul-13 POST /optimization,
|
||
Proposal/Research-Ergebnis speichern
|
||
```
|
||
|
||
**API (Docker-intern, Port 55017):**
|
||
- `GET /health` — Liveness (`{"status":"ok","service":"hermes","version":"0.1.0"}`)
|
||
- `GET /health/ready` — Readiness (DB-Schema vorhanden) → 200 `{"status":"ready"}`
|
||
- `POST /tasks` — Task einreichen (`task_type` + `payload.tools[]`); Whitelist-Prüfung
|
||
- `GET /tasks` / `GET /tasks/{id}` — Tasks + Status/result_refs
|
||
- `GET /runs/{id}` — einzelner Run mit result_refs
|
||
- `GET /tools` — Tool-Whitelist auflisten
|
||
|
||
Kein RabbitMQ: synchroner request/response. Port 55017 **nur intern** (`expose:`), kein öffentliches Mapping.
|
||
|
||
## Tool-Whitelist (strikt, `app/core/tool_whitelist.py`)
|
||
Jeder Tool-Call wird gegen die Whitelist geprüft. Unbekannte/unerlaubte Tools → REJECTED.
|
||
|
||
| Tool (namespace.method) | Zielmodul | Richtung | Status |
|
||
|-------------------------|-----------|----------|--------|
|
||
| `market_data.prices` | Modul-03 | READ | erlaubt |
|
||
| `regime.analyze` | Modul-04 | READ | erlaubt |
|
||
| `strategy.list` | Modul-05 | READ | erlaubt |
|
||
| `ranking.current` | Modul-06 | READ | erlaubt |
|
||
| `journal.entries` | Modul-10 | READ | erlaubt |
|
||
| `analytics.portfolio` | Modul-11 | READ | erlaubt |
|
||
| `monitoring.status` | Modul-15 | READ | erlaubt (NUR GET) |
|
||
| `backtest.start` | Modul-12 | WRITE | erlaubt (CONTROLLED) |
|
||
| `optimization.start` | Modul-13 | WRITE | erlaubt (CONTROLLED) |
|
||
| `execution.place_order` | Modul-09 | WRITE | **REJECTED** |
|
||
| `risk.set_limits` | Modul-07 | WRITE | **REJECTED** |
|
||
| `portfolio.rebalance` | Modul-08 | WRITE | **REJECTED** |
|
||
| `monitoring.pause/halt/resume` | Modul-15 | Control | **REJECTED** |
|
||
| alles andere | — | — | **REJECTED** |
|
||
|
||
**M09/M07/M08 sind strukturell NICHT in den Clients implementiert** (`clients.py`) — ein Verstoß
|
||
ist damit zur Laufzeit unmöglich, zusätzlich zur Whitelist-Barriere. M15-Control-Writes fehlen ebenfalls.
|
||
|
||
## Persistenz / Audit (Migration `migrations/001_hermes.sql`)
|
||
Vier Tabellen in Modul-01-PostgreSQL (PostgreSQL-01), NICHT im kritischen Trading-Pfad:
|
||
- `hermes_task` — Aufgaben (id, task_type, agent_role, status, payload, result_refs, error_code)
|
||
- `hermes_run` — Ausführungen (run_id, task_id, status, result, result_refs, idempotent)
|
||
- `hermes_tool_call` — **jeder Tool-Call nachvollziehbar**: task_id, tool, target_module, input_hash,
|
||
status, timestamps, error_code
|
||
- `hermes_result` — gespeicherte Ergebnisse/Reports
|
||
|
||
Jeder Tool-Call wird in `hermes_tool_call` auditier. Keine Secrets/Prompts mit Credentials in Logs.
|
||
|
||
## Sicherheit
|
||
- **Keine öffentlichen Ports**: 55017 nur `expose` (Docker-intern), kein Host-Mapping (verifiziert: `docker port` leer).
|
||
- **Internes Docker-Netzwerk** `trading-modules`.
|
||
- **Kein Docker-Socket, kein Root-/Shell-Zugriff auf andere Container.**
|
||
- **Secrets nur ENV/Secret** (`PG_PASSWORD` aus Compose `environment`); keine Secrets in Logs/API/DB.
|
||
- **Keine Broker-Credentials** (kein Client, kein ENV dafür).
|
||
- **Hermes-Ausfall beeinflusst M03–16 NICHT** (eigene DB-Tabellen, keine Kopplung an Trading-Core).
|
||
- **M15-Ausfall → Monitoring-/Systemdiagnose-Task FAILED** (FAIL-CLOSED, nicht schönreden).
|
||
|
||
## Read-Clients (tolerant)
|
||
Einzelne Quellen-Fehler (404/5xx/Timeout) werden als Teil-Ergebnis `{"_error": code}` gekapselt,
|
||
der Gesamt-Task bleibt SUCCEEDED. Komplett unreachable (`UNREACHABLE`/`TIMEOUT`) → `None`.
|
||
|
||
**Ausnahme — Monitoring (FAIL-CLOSED):** Der `monitoring.status`-Call ruft M15 direkt auf. Ist M15
|
||
nicht erreichbar → Task **FAILED** (kein "ok" bei ausgefallenem M15). Gleiches gilt für M12/M13:
|
||
Ausfall → zugehöriger Backtest-/Optimization-Task **FAILED** (`UNREACHABLE`), Hermes bleibt healthy,
|
||
Trading-Core unbeeinflusst.
|
||
|
||
## Idempotenz
|
||
Jeder `task_id` erzeugt genau **einen** `hermes_run` (SUCCEEDED). Wiederholte Einreichung derselben
|
||
Task-Payload → je Task genau 1 Run, kein Doppel-Run. `input_hash` in `hermes_tool_call` identifiziert
|
||
identische Aufrufe.
|
||
|
||
## Tests & E2E-Verifikation (VPS, 21.08.2026)
|
||
- **Unit-Tests** `tests/test_hermes.py`: 13/13 grün (Whitelist-Gates, Executor, Idempotenz, REJECTED).
|
||
- **T1 Research-Task** → M03 → **SUCCEEDED**, result_refs mit `tool_output` + `report`.
|
||
- **T2 Analytics-Task** → M11 → **SUCCEEDED**.
|
||
- **T3 Backtest-Task** → M12 `POST /backtest` (BT_PULL, stock, 450 Candles) → **SUCCEEDED**.
|
||
- **T4 Optimization-Task** → M13 `POST /optimization` (BT_PULL) → **SUCCEEDED**.
|
||
- **T5 Monitoring READ-ONLY** → M15 `GET /status` → **SUCCEEDED**.
|
||
- **T6 Execution-Tool** (`execution.place_order`) → **REJECTED** (`TOOL_NOT_ALLOWED`).
|
||
- **T7 M15-Control-Tool** (`monitoring.pause`) → **REJECTED**.
|
||
- **T8 Risk/Portfolio-Write** (`risk.set_limits`) → **REJECTED**.
|
||
- **T9 ungültiges Tool** (`bogus.tool`) → **REJECTED**.
|
||
- **T10 Ausfall**: M15 down → Monitoring FAILED; M12 down → Backtest FAILED; M13 down → Optimization
|
||
FAILED (jeweils `UNREACHABLE`). Erholung → SUCCEEDED. Hermes bleibt healthy.
|
||
- **T11 Idempotenz**: je Task genau 1 Run.
|
||
- **T12 Restart/Reconnect**: nach `docker restart` ready, Daten persistent.
|
||
- **T13 keine Secrets**: `docker logs` frei von password/secret/token/api_key.
|
||
- **T14 Port nur intern**: `ss -ltn` kein Host-Listening auf 55017.
|
||
- **T15 Hermes-Ausfall**: bei gestopptem Hermes sind M03/04/05/11/12/13/15/16 alle healthy
|
||
(`/health` ok) → Trading-Core unbeeinflusst.
|
||
|
||
**E2E-Gesamt: 15/15 grün.**
|
||
|
||
## Bugs / Fixes (modul-17, dokumentiert)
|
||
1. **Methodenname `_last_succeeded_run` vs `_run_last_succeeded_run`**: Executor referenzierte
|
||
`_last_succeeded_run`, Methode hieß anders → benannt in `_last_succeeded_run` (Idempotenz-Check).
|
||
2. **Test-Pfad**: `sys.path.insert` musste auf `../app` zeigen (nicht Modul-Root) für `app.*`-Importe.
|
||
3. **M12 422 "Unzureichende Daten"**: EURUSD/demo lieferte nur 1 Candlestick (< 220 nötig). Fix im
|
||
E2E: Symbol **`BT_PULL`** (asset_class `stock`, 450 Candles) für Backtest/Optimization.
|
||
4. **M13 erfordert Pflichtfelder `start_date`+`end_date`** (anders als M12): Optimization-Payload
|
||
musste beide Datumsfelder enthalten, sonst HTTP 422.
|
||
5. **E2E-Skript**: BusyBox wget im Alpine-Worker kennt kein `--post-file` → JSON per `docker cp`
|
||
+ `--post-data="$(cat …)"`. Funktionsname `mkpayload`→`mk_put` (aufrufender Code nutzte `mk_put`).
|
||
6. **SSH-Quoting**: verschachtelte `$(…)` mit doppelten Anführungszeichen im Inline-Python kappen
|
||
das Kommando → Inline-Echo entfernt, reiner grep-Check.
|
||
|
||
## Compose / Betrieb
|
||
- Netz `trading-modules`, DB-Host `Modul-01-PostgreSQL` (Modul-01), Port 55017 nur intern (`expose`),
|
||
`restart: unless-stopped`. Kein öffentliches Port-Mapping.
|
||
- **Kein Teil des kritischen Trading-Pfads:** kein M09-, kein M07/M08-, kein M15-Control-Zugriff.
|
||
- Paperclip (M16) bleibt Orchestrator; Hermes ist seine Worker-Ausführungsebene.
|
||
|
||
---
|
||
|
||
## LLM-Schicht (KI-/Analyse-Erweiterung, M16 additiv `llm=true`)
|
||
Hermes kann Tasks zusätzlich über eine **LLM-Schicht** (Tool-Calling-Loop) ausführen. Die LLM-Schicht
|
||
ist **additiv** (M16 setzt `llm=true` im Task-Payload); ohne Flag bleibt das deterministische M17-Verhalten
|
||
unverändert. Die Tool-Whitelist und Task-Gates bleiben **deterministisch außerhalb des LLM** — das LLM
|
||
führt nie selbst Tools aus, sondern liefert `requested_tools[]`, die durch die bestehende Whitelist geprüft werden.
|
||
|
||
### 2-Stufen-Modellkonzept (final, 21.08.2026)
|
||
| Stufe | Modell | Provider | Verwendung |
|
||
|-------|--------|----------|------------|
|
||
| **STANDARD** | `deepseek-v4-flash:cloud` | `ollama_cloud` | Normale Research-/Analyse-Tasks, voller Tool-Calling-Loop, Structured JSON, vollständiger Audit |
|
||
| **LOKAL** | `llama3.1:8b` | `ollama_local` | NUR expliziter Privacy-/Offline-Modus (`llm_mode=local`), **Analyse-only** (kein Tool-Loop), CPU-/Timeout-Schutz |
|
||
|
||
**Regeln (hart):**
|
||
- **KEIN automatischer Cloud→Local-Fallback.** Cloud-Ausfall → Task **FAILED** (`LLM_UNAVAILABLE`),
|
||
kein minutenlanger Wechsel auf das lokale Modell.
|
||
- **LOKAL nur explizit** über `llm_mode=local` im Task-Payload (`extra.llm_mode`). Nicht als Standard verwenden.
|
||
- **LOKAL = Analyse-only**: genau EIN Analyse-Call, keine Tool-Anfragen. `llama3.1:8b` auf CPU versteht
|
||
den Tool-Calling-Loop nicht zuverlässig (LLM_MAX_ROUNDS) und ist langsam (~60-90s/Call).
|
||
- **FAIL-CLOSED**: LLM down/Timeout/invalid JSON/Schema/Max-Runden → Task FAILED, kein Trading-Core-Effekt.
|
||
- **Safety unverändert**: kein `execution.place_order`, kein `risk.set_limits`, kein `portfolio.rebalance`,
|
||
kein M15 pause/halt/resume, Proposal maximal DRAFT/PROPOSED.
|
||
|
||
### LLM-Audit (`hermes_llm_run`, Migration `002_hermes_llm.sql`)
|
||
Fünfte Audit-Tabelle. Je LLM-Run: provider, model, config_version, input_context_hash, requested_tools,
|
||
executed_tools, rejected_tools, tokens_in/out, latency_ms, structured_result, status, error_code.
|
||
**Vollständig AUCH im FAILED-Pfad** (Timeout/Invalid-JSON/Max-Runden persistieren Metriken). Keine
|
||
vollständigen sensiblen Prompts, keine Secrets.
|
||
|
||
### LLM-ENV (Compose M17-Block)
|
||
- `LLM_PROVIDER=ollama_cloud` (Standard = Cloud)
|
||
- `LLM_MODEL_CLOUD=deepseek-v4-flash:cloud`
|
||
- `LLM_MODEL_LOCAL=llama3.1:8b`
|
||
- `LLM_BASE_URL=http://10.0.4.2:11434` (Ollama-Netz)
|
||
- `LLM_TIMEOUT_SECONDS=300`
|
||
|
||
### LLM-E2E-Verifikation (final, 21.08.2026)
|
||
- **Cloud-Standard** (`llm=true`, standard): **SUCCEEDED** (deepseek-v4-flash:cloud, 4 requested/2 executed, Audit vollständig).
|
||
- **Local explizit** (`llm=true`, `llm_mode=local`): **SUCCEEDED** (llama3.1:8b, Analyse-only, Audit vollständig).
|
||
- **Cloud-down** (isoliert, ungültige Base-URL): **FAILED** (`LLM_UNAVAILABLE`), **kein Auto-Fallback** (Provider bleibt Cloud).
|
||
- **llm=false**: **SUCCEEDED** (deterministisches M17, kein LLM-Run).
|
||
- **Audit vollständig**: requested/executed/rejected/tokens/latency/context_hash persistiert, auch im FAILED-Pfad.
|
||
- **M03–M15 unbeeinflusst**: alle Module healthy während der LLM-Tests.
|
||
- **Unit-Tests** `tests/test_llm.py`: **20/20 grün** (inkl. 4 REJECTED-Gate-Tests: place_order, monitoring_pause, risk_set_limits, unknown_tool).
|
||
|
||
### LLM-Bugs / Fixes
|
||
1. **Audit-Metriken leer (Cloud-E2E)**: `finish_llm_run` schrieb nur status/result/error → um
|
||
requested/executed/rejected_tools, tokens_in/out, latency_ms, structured_result, provider/model/config_version erweitert.
|
||
2. **FAILED-Pfad verlor Audit-Metriken**: Max-Runden-Exception trug keine Metriken → Exception trägt jetzt
|
||
Audit-Dict, `execute()` persistiert sie auch bei LLM_MAX_ROUNDS/Timeout/Invalid-JSON.
|
||
3. **NOT NULL-Constraint**: `requested_tools` etc. `NOT NULL DEFAULT '[]'` → `finish_llm_run` koerziert `None`→`[]`.
|
||
4. **Structured Output**: Cloud-Modell ignoriert Schema ohne `format`-Constraint → `format`-Constraint im Payload.
|
||
5. **ToolCall-Format**: ToolCall-Modell erwartet `name`/`args` (nicht `tool`/`params`) → Skript/Executor angepasst.
|
||
6. **Lokales Modell ungeeignet für Tool-Loop**: `llama3.1:8b` auf CPU → LLM_MAX_ROUNDS (fragt endlos Tools an).
|
||
Fix: lokaler Modus = **Analyse-only** (kein Tool-Loop), wie vom User empfohlen.
|
||
|
||
## Geändert
|
||
```
|
||
Geändert von: Rain Ocampo
|
||
Datum: 21.08.2026
|
||
Grund: LLM-Schicht (2-Stufen-Konzept) ergaenzt: STANDARD=deepseek-v4-flash:cloud (voller Tool-Loop),
|
||
LOKAL=llama3.1:8b (nur explizit llm_mode=local, Analyse-only), KEIN Auto-Fallback, Cloud-down->FAILED
|
||
(LLM_UNAVAILABLE), llm=false deterministisch, Audit hermes_llm_run vollstaendig (auch FAILED-Pfad),
|
||
Unit 20/20, E2E 5/5 Szenarien gruen, M03-M15 unbeeinflusst. FREIGEGEBEN.
|
||
Geändert von: Rain Ocampo
|
||
Datum: 21.08.2026
|
||
Grund: Modul-17-Hermes-Agent implementiert + E2E verifiziert (Research/Analytics/Backtest/Optimization/Monitoring-Success,
|
||
Safety REJECTED 6/7/8/9, M12/M13/M15-Ausfall -> FAILED (FAIL-CLOSED), Idempotenz, Restart, keine Secrets, Port intern,
|
||
Hermes-Ausfall beeinflusst M03-16 nicht). Tool-Whitelist strikt, 4 Audit-Tabellen (hermes_task/run/tool_call/result),
|
||
6 API-Endpunkte. Unit 13/13, E2E 15/15 gruen. FREIGEGEBEN. Keine weiteren Module begonnen.
|
||
```
|