From 8b79c3585155c9427c7d1b659585e90375d044bb Mon Sep 17 00:00:00 2001 From: Richard Date: Thu, 16 Jul 2026 10:09:50 +0200 Subject: [PATCH] Docs: Konzept Supervisor-Modul (KI-Analyse, Entscheidungsjournal, Dossiers) Co-Authored-By: Claude Opus 4.8 --- docs/konzepte/KONZEPT-Modul-Supervisor.md | 163 ++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 docs/konzepte/KONZEPT-Modul-Supervisor.md diff --git a/docs/konzepte/KONZEPT-Modul-Supervisor.md b/docs/konzepte/KONZEPT-Modul-Supervisor.md new file mode 100644 index 0000000..25c9174 --- /dev/null +++ b/docs/konzepte/KONZEPT-Modul-Supervisor.md @@ -0,0 +1,163 @@ +# Konzept: Modul „Supervisor" (KI-gestützte Handels-Analyse & Forensik) + +> Stand: 2026-07-16 +> Ziel: ALLES, was PolyTrader getan (und bewusst NICHT getan) hat, auf einfachem Wege detailliert +> analysierbar machen — Logs, DB-Einträge und das echte Geschehen auf der Plattform — und die Analyse +> durch ein KI-Modell (OpenRouter) durchführen lassen: Warum hat ein Trade funktioniert? Warum nicht? +> Woran lag es? +> **Leitidee: Erst das Datenfundament, dann die KI.** Ein Modell kann nur erklären, was aufgezeichnet +> wurde. Die Analyse ist maximal so gut wie die Rekonstruierbarkeit unserer Entscheidungen. + +--- + +## 0. Datenlage-Audit: Was haben wir, was fehlt? + +### Vorhanden ✅ +| Quelle | Inhalt | Qualität für Analyse | +|---|---|---| +| `core_trade_log` (TradeRecord) | abgeschlossene Trades aller Module | gut (strukturiert), aber nur das ERGEBNIS | +| Modul-Logs (`mod_copytrading_closed_trades`, `rf_*`) | Modul-Details inkl. Fees, SourceTrader, Cluster | gut | +| Terminal-/Datei-Logs (`/Logs`, Freitext) | Verlauf inkl. `TradeReasoning` (Begründungen) | schlecht maschinenlesbar: Freitext, deutsch, ohne IDs | +| `rf_candidates` | Scanner-Entscheidungen inkl. Reject-Grund | **Vorbild!** genau das Muster, das wir überall brauchen | +| geplant: `acc_ledger` (Accounting-Modul) | unabhängige Plattform-Ground-Truth je Wallet | schließt „echtes Geschehen auf der Plattform" | + +### Fehlend ❌ (die eigentlichen Lücken) +1. **Entscheidungsjournal** — der größte Gap. Jede Engine-Entscheidung (BUY/SELL ausgeführt, abgelehnt, + übersprungen) existiert nur als Freitext-Log. Nicht abfragbar („zeig alle MaxBuyPrice-Rejects der + Woche"), nicht mit dem späteren Marktausgang verknüpfbar („was WÄRE aus den Rejects geworden?" — + das ist die halbe Strategie-Kalibrierung!). +2. **Order-Lifecycle nicht persistiert** — Platzierungsversuche, CLOB-Responses, Cancels, Leiter-Stufen + (Preis je Stufe, Wartezeiten, Floor-Erreichung) stehen nur im Log. Für „warum schlechter Fill?" + brauchen wir die Kette als Daten. +3. **Korrelation** — es gibt keine `SignalId`, die Signal → Entscheidung(en) → Order(s) → ClosedTrade + verbindet. Ohne sie ist jedes „Dossier" Handarbeit über Zeitstempel. +4. **Markt-Kontext zum Entscheidungszeitpunkt** — mindestens Signalpreis vs. erzielter Preis vs. + Zeitversatz (Latenz!); mit Phase 1 (Orderbuch) auch Spread/Tiefe. Ohne Kontext kann niemand + beurteilen, ob eine Entscheidung RICHTIG war — nur ob sie gut AUSGING. +5. **Strukturierte Logs** — zusätzlich zum Text ein JSONL-Sink (Timestamp, Level, Source, CorrelationId, + Message, Data), damit Logs filterbar/parsebar sind statt grep-über-Freitext. + +--- + +## 1. Frage 1 — Aufbereitung: das „Trade-Dossier" als zentrale Einheit + +**S-0: Datenfundament (Core, nützt sofort auch OHNE KI — z. B. beim Zielland-Debugging):** +- `core_decision_journal`: eine Zeile je Entscheidung. Felder: `SignalId`, Timestamp, Modul, AccountId, + TokenId, Side, Decision (Executed/Rejected/Skipped/Deferred), **ReasonCode (Enum!)** (z. B. + `MaxBuyPriceExceeded`, `PartialSellBelowThreshold`, `ExitPendingSkip`, `SpamBlock`, `BudgetExhausted`, + `BelowPolymarketMinimum`, …), Kontext-Zahlen (SignalPreis, Limitwert, verfügbares Budget, …) als + kompaktes JSON, Freitext wie bisher zusätzlich. + → Die bestehenden ~20 `TradeReasoning`-Stellen bleiben, schreiben aber ZUSÄTZLICH strukturiert. +- `core_order_events`: Order-Lifecycle (Placed/Rejected/Cancelled/LadderStep/Filled) mit Preisen, + CLOB-Response, `SignalId`. +- `SignalId` (GUID) im `CopySignal`/RF-Flow erzeugen und bis in `ClosedTrade`/`TradeRecord` durchreichen. +- JSONL-Log-Sink parallel zum Text-Log (TerminalLogger erweitert; CorrelationId=SignalId wo vorhanden). + +**S-1: Dossier-Generator (pur, testbar):** Für einen Trade / ein abgelehntes Signal alles zusammensetzen: +Signal → Journal-Einträge → Order-Events → Fill/Leiter-Verlauf → ClosedTrade/RF-Position → +`acc_ledger`-Einträge (Plattform-Wahrheit!) → Log-Ausschnitt (Zeitfenster+CorrelationId) → Marktdaten. +Ausgabe als JSON (fürs Modell) und Markdown (für Menschen). Dazu Perioden-Reports über `TradeAnalytics`. + +--- + +## 2. Frage 2 — WIE analysieren: OpenRouter-Agent mit Read-only-Tool-Registry + +**v1: Agent IM Prozess (kein separater MCP-Server nötig).** Wir kontrollieren beide Seiten — ein +Function-Calling-Loop gegen OpenRouter (Chat Completions + Tools) ist in C# klein und ohne neue +Abhängigkeit machbar (HttpClient + System.Text.Json). Der Agent bekommt: + +1. **System-Kontext:** ein kuratiertes, versioniertes Dokument `docs/analyse/ARCHITEKTUR-KONTEXT.md` + („So funktioniert PolyTrader": Module, Entscheidungswege, Reason-Codes, Limits, Leiter-Mechanik, + bekannte Eigenheiten). KEIN Code-Dump — destilliertes Verhalten. Wird bei Änderungen am Geld-Pfad + mitgepflegt (Checkliste). +2. **Read-only-Tools** (Registry im Supervisor-Modul): + - `query_trades(filter)` — Core-Trade-Log + - `query_decisions(filter)` — Entscheidungsjournal (inkl. Rejects!) + - `get_dossier(signalId | tokenId+account)` — das komplette Dossier + - `read_logs(zeitraum, level, correlationId, textfilter)` — JSONL-Logs + - `get_ledger(account, zeitraum)` + `get_ledger_diff(...)` — Plattform vs. eigene DB (Accounting) + - `get_kpis(scope)` — TradeAnalytics + - `get_architecture_context()` — das Kontext-Dokument + **Hart: KEIN Tool kann handeln, canceln oder schreiben.** Der Supervisor ist Beobachter. + +**Analyse-Modi:** +- **Einzeltrade-Forensik:** „Erkläre Trade X" → Dossier → Modell begründet mit Daten. +- **Batch-/Muster-Analyse:** „Alle Verlierer der letzten 14 Tage → gemeinsame Faktoren?" (Kategorie? + Uhrzeit? Master? Preisband? Latenz? Leiter-Floor-Fälle?) +- **Counterfactual:** „Was wurde abgelehnt und wie ist der Markt ausgegangen?" (Journal × Resolution). +- **Reconciliation-Anomalien:** DB ↔ Plattform-Differenzen erklären lassen. +- **Täglicher Supervisor-Bericht** (später): Kurzfassung via Threema. + +**MCP-Server-Light: ja, aber als Phase S-4.** Dieselbe Tool-Registry zusätzlich über einen lokalen +MCP-Endpoint exponieren → dann können auch externe Clients (Claude Code/Desktop) direkt gegen die +laufende App analysieren. Architektonisch nur ein zweiter Transport über dieselben Tools — deshalb +lohnt es, die Registry von Anfang an transport-agnostisch zu bauen. + +--- + +## 3. Frage 3 — Core- oder Modulebene? Hybrid. + +- **Datenfundament = Core.** Journal, Order-Events, SignalId, JSONL sind Core-Contracts (wie der + generische Trade-Log heute); alle Module schreiben hinein (Dual-Write-Muster existiert bereits). +- **Analyse = modulübergreifend.** Profitabilität ist eine Frage über Module/Accounts hinweg — genau + wie das Dashboard. +- **Modul-Spezifisches via Contract:** Core definiert `IAnalysisContextSource` (liefert z. B. + RF-Kandidaten-Kontext oder Copytrading-Master-Kontext zu einem Dossier); Module registrieren + Implementierungen per DI; der Supervisor konsumiert alle. So bleibt „Module kennen einander nicht" + gewahrt (beide Seiten referenzieren nur den Core). + +## 4. Frage 4 — Unterbringung: eigenes Modul „Supervisor" + +`src/PolyTrader.Modules.Supervisor/` als `IPolyTraderModule` (`Name="Supervisor"`, `DbPrefix="sup_"`), +Registrierung in `Program.cs`, referenziert nur den Core. Eigenes Fenster (Muster RF/Copytrading): +- Tab **Analyse** (Chat mit dem Agenten, Tool-Aufrufe sichtbar/expandierbar — Nachvollziehbarkeit!) +- Tab **Dossier-Browser** (Trade/Signal auswählen → Dossier ansehen, auch ohne KI) +- Tab **Berichte** (gespeicherte Analysen/Tagesberichte, `sup_reports`) +- Tab **Settings** (API-Key, Modellwahl je Aufgabe, Kosten-/Tokenbudget, Bericht-Zeitplan) + +Warum Modul statt Core-Fenster: passt ins etablierte Muster (eigene Persistenz `sup_reports`/ +`sup_conversations`, eigene Settings, eigener Launcher-Button), hält die KI-Abhängigkeit aus dem Core +heraus und ist einzeln abschaltbar. + +## 5. API-Key: ja, getrennt + +**Separater OpenRouter-Key für den Supervisor** (getrennt von künftigen Trading-Modul-Keys wie dem +AI-Markt-Rating): +1. **Kostenzuordnung** — Forensik-Sessions können tokenintensiv werden; sauber getrennt sichtbar. +2. **Spend-Limits je Key** bei OpenRouter → ein Analyse-Amok kann nie das Trading-Budget fressen (und umgekehrt). +3. **Unabhängige Rotation/Sperrung** (Incident-Response, siehe Sicherheitskonzept). +4. **Modellwahl je Aufgabe:** Routineberichte mit günstigem Modell, Tiefen-Forensik mit starkem Modell — je Aufgabe konfigurierbar. + +**Ablage:** beide Keys über die vorhandene `SecretProtection` (F1-Mechanik) verschlüsselt — nicht im +Klartext in DB/Config. + +## 6. Sicherheit (Verzahnung mit docs/sicherheit) + +- **OpenRouter = NEUER externer Datenempfänger.** Bewusste Erweiterung der Egress-Allowlist (§5.3 im + Sicherheitskonzept) + Dokumentation dort. Es verlassen uns: Trade-/Entscheidungs-/Log-Daten (Wallet- + Adressen sind ohnehin öffentlich on-chain). **Redaction-Schicht vor dem Versand:** niemals Secrets/ + Keys/Connection-Strings in Tool-Antworten (Log-Reader filtert Muster; Secrets stehen per F6-Prüfung + ohnehin nicht in Logs — Doppelboden bleibt). +- **Read-only by design:** kein Order-/Schreib-Tool. Damit ist auch Prompt-Injection über Fremdtexte + (Marktfragen in Dossiers) auf „falsche Analyse" begrenzt, kann aber nie handeln. +- Tool-Aufrufe des Agenten werden geloggt (sup_-Tabelle) — der Supervisor ist selbst auditierbar. + +## 7. Phasen + +- **S-0 Datenfundament (Core):** `core_decision_journal` + ReasonCode-Enum + `SignalId`-Durchreichung + + `core_order_events` + JSONL-Sink. Engine/Leiter/Monitor/RF schreiben strukturiert. Pure Logik + + Tests; Migrationen offline. **Sofortnutzen ohne KI** (abfragbare Rejects, Zielland-Debugging). +- **S-1 Dossier:** Generator (pur, testbar) + Dossier-Browser-UI (Modul-Skelett Supervisor). +- **S-2 Agent:** OpenRouter-Client (Core oder Modul), Tool-Registry (read-only), Analyse-Chat-Tab, + Architektur-Kontext-Dokument. +- **S-3 Berichte:** Batch-Analysen, Counterfactual-Report, täglicher Threema-Bericht. +- **S-4 MCP-Light (optional):** Tool-Registry zusätzlich als lokaler MCP-Server für externe Clients. + +## 8. Offene Entscheidungen (Richard) + +1. **Start mit S-0 sofort?** (Empfehlung: ja — nützt auch ohne KI und VOR dem Live-Start; alles + Weitere baut darauf.) +2. Counterfactual-Tracking („was wäre aus Rejects geworden") von Anfang an im Journal vorsehen + (Resolution-Nachverfolgung abgelehnter Signale) oder später? +3. Modellwahl-Defaults (günstig vs. stark) und Tokenbudget/Monat für den Supervisor. +4. Tagesbericht via Threema gewünscht (S-3)?