agent-viz

Ein kontinuierliches Asset, das die Verständigung zwischen Menschen und KI-Agenten von Chat auf visuelle Darstellungen (Graphen, Baumdiagramme, Heatmaps, Flussdiagramme) erweitert. Gemeinsam genutzt für Kaggle / AtCoder Heuristic / Handelsmodell-Entwicklung.

Strukturansatz (basierend auf Recherche vom 2026-08-24)

• Rückgrat der Aufzeichnung = MLflow (lokaler File-Store). Agenten schreiben, Menschen sehen mit mlflow ui.

• Benutzerdefinierte Diagramme = eigenständiges HTML (Plotly). Werden inline in der MLflow-Artefaktansicht gerendert.

• Selbst gehalten wird nur eine dünne Schicht aus „gemeinsames Versuchsregister-Schema“, „Berichtskomponenten“ und „Domain-Adapter“.

Recherche-Original: KnowledgeBase 00_Inbox/人間とAIエージェントのビジュアル意思疎通ツール 調査メモ

Related MCP server: Querytree MCP Server

Phase 0 (implementiert)

• agentviz.schema — Gemeinsames Versuchsregister-Schema. 1 Versuch = TrialRecord, Fall = seed / fold / Zeitraum.

• agentviz.ledger — TrialLedger. log_trial / fetch_trials zu MLflow.

• agentviz.report — build_report. Eigenständiges HTML mit Versuchsregister-Tabelle + Metrikverlauf + Fall-×-Versuch-Relativ-Score-Heatmap.

Verwendung

# セットアップ
.venv\Scripts\python.exe -m pip install -e .[dev]

# テスト
.venv\Scripts\python.exe -m pytest

# デモ（合成AHCデータで台帳→レポート→MLflow記録）
.venv\Scripts\python.exe demo\generate_demo.py

# UI（共有ストアを表示）
.venv\Scripts\python.exe -m mlflow ui --backend-store-uri "<store path>"

Standard-Store ist %AGENTVIZ_STORE%, falls nicht gesetzt ~\dev\Projects\agent-viz\store.

Phase 1 (implementiert)

• agentviz.adapters.ahc — Übernahme des eigenen AHC-Runner-Messformats. from_results_json (results/*.json) und from_experiments_jsonl (1 Zeile = 1 Experiment. Beschädigte Zeilen werden als Fehler zurückgegeben und fortgesetzt, Zeilen mit leeren Metriken werden aus per-seed-Ergebnissen neu berechnet und gerettet, absolute Pfade von anderen Geräten werden über results_dir per Dateiname aufgelöst).

• agentviz.adapters.kaggle — from_cv(fold_scores, lb_score=...). Fall = fold, LB ist lb_score-Metrik. Für Wettbewerbe, bei denen die Metrik als Durchschnitt der Label-Scores definiert ist (wie macro AUC / macro F1), gibt es from_per_label(label_scores, label_meta=..., metric_name="macro_auc") (Fall = Label). Die Hauptmetrik wird nicht cv_mean genannt, um die Streuung zwischen Folds (Messschwankung) nicht mit dem Unterschied zwischen Labels (Leistungsunterschied) zu verwechseln. Nur Letzteres ist beeinflussbar. label_meta geht in die Meta der Fälle ein und dient als Material für die Schichtung nach Lehrerdichte oder Positivzahl.

• agentviz.adapters.trade — from_walkforward(windows, ...). Fall = Walk-Forward-Fenster. OOS ist oos_score-Metrik, Tier-Sheet-HTML wird mit log_trial(artifact_paths=...) angehängt.

• agentviz.report — Generalisierungs-Lücken-Streudiagramm hinzugefügt (automatisch angezeigt, wenn mindestens 2 Versuche mit lb_score / oos_score vorhanden sind. CV vs LB wird wie IS vs OOS behandelt).

• agentviz.replay — build_replay(frames, infos, events). Eigenständiges HTML, das das Grundgerüst des selbstgebauten Replays von ahc069 (Seekbar, Wiedergabe, Einzelbild, ←→-Tasten, Event-Klick-Sprung) domänenunabhängig verallgemeinert.

Mit echten Daten bestätigt: Aus AtCoder\ahc\ahc069\experiments.jsonl (1191 Zeilen) wurden 1133 Versuche übernommen, bei 1130 Versuchen per-seed-Fallauflösung (examples/ingest_ahc069.py).

Phase 2 (implementiert) — Bidirektionalität

• agentviz.feedback — Original-Store für schichtweises Feedback (nur Anhängen, JSONL, store/feedback.jsonl). add / list / resolve

• agentviz.panel — Gradio-Panel und MCP-Server. Menschen sehen Versuchsregister und Heatmap und werfen schichtweise Hinweise ein (Zielversuch, Zielfall, Anweisung, Priorität); Agenten lesen sie über MCP-Tools, bearbeiten sie und schließen sie mit resolve_feedback.

# パネル起動（http://127.0.0.1:7861、ポートは AGENTVIZ_PANEL_PORT で変更）
.venv\Scripts\python.exe -m agentviz.panel

# Claude Code への登録（パネル起動中に）
claude mcp add --transport http agentviz http://127.0.0.1:7861/gradio_api/mcp/

Auch ohne MCP kann man direkt mit gradio_client oder agentviz.feedback.FeedbackStore lesen und schreiben. In Umgebungen, in denen die Dropdown-Auswahl der UI nicht übernommen wird, ist der „Neu laden“-Button ein zuverlässiger Fallback.

Phase 3 (implementiert) — Entscheidungspunkte

Während feedback eine einmalige Runde von Hinweis → Bearbeitung behandelt („Diese Schicht ist schwach, verbessere sie“), behandelt decisions Streitpunkte, bei denen man nicht weitermachen kann, bis entschieden ist, welche Option man nimmt. Da die Form unterschiedlich ist, sind sie getrennt.

• agentviz.decisions — Store für Entscheidungspunkte (nur Anhängen, JSONL, store/decisions.jsonl). propose / decide / supersede

• Optionen haben ein measured-Flag. Wenn ungemessene Optionen nicht neben gemessenen angezeigt werden können, wird „das Beste unter den Gemessenen“ fälschlich als „das Beste“ gelesen.

• Über blocks gibt es Abhängigkeiten zwischen Entscheidungen. ready() gibt nur die zurück, deren Abhängigkeiten abgeschlossen sind.

• Jede Option verweist über evidence_trials auf Versuche im Register.

Aufteilung der Originale: Für die Beschreibung endgültiger Entscheidungen ist der Vault der KnowledgeBase das Original. decisions hält nur die Arbeitsebene (Optionen, Evidenzlinks, Status) und verweist über vault_ref auf die Vault-Seite. Derselbe Text wird nicht in beiden gehalten.

decide ist die Schnittstelle zum Aufzeichnen menschlicher Entscheidungen. Der Agent listet Optionen auf (propose_decision), der Mensch wählt. chosen ist auf registrierte Schlüssel beschränkt, Freitext wird nicht akzeptiert (weil man sonst später nicht mehr maschinell nachvollziehen kann). revise_option überarbeitet nur den Zustand der Evidenz (evidence_trials / measured / note) mit Begründung (die Evidenz zum Zeitpunkt der Registrierung bleibt als Ereignis immer in der Historie).

Blickwinkel-Angleichung (implementiert) — Agent → Mensch

feedback ist Mensch → Agent, decisions ist das Buch der Streitpunkte. Eine Richtung fehlte: ein Mittel, um den Vergleich, den der Agent gerade betrachtet, mit dem Bildschirm des Menschen in Einklang zu bringen.

Selbst wenn der Agent sagt: „Wenn man auf 9 Labels reduziert, sind es 8 Siege und 1 Niederlage“, stimmen die Zahlen nicht, wenn der Mensch einen anderen Vergleich sieht. Die Bedingungen erneut in Worten zu übermitteln ist ein Stille-Post-Spiel; tatsächlich wurde in dieser Runde unklar, ob „ausgeschlossen“ oder „alle gesehen“ gemeint war.

• agentviz.viewstate — Store für Zeigegesten (nur Anhängen, JSONL, store/viewstate.jsonl). point / clear / current / history

• MCP-Tool point_at_comparison — sendet Basis, Kandidat und von der Aggregation ausgeschlossene Fälle an das Panel und gibt im selben Aufruf auch die Zahlen dieses Vergleichs zurück (bei getrennter Abfrage können sie abweichen). note ist Pflicht. Eine Bildschirmänderung ohne Grund ist für den Menschen nur „es hat sich von selbst geändert“.

• MCP-Tool clear_comparison_pointer / „Zeigegeste aufheben“-Button im Panel

Es werden weder Register noch Entscheidungen umgeschrieben. Es ist kein Befund und keine Entscheidung, sondern ein Zeiger, um die Blickwinkel anzugleichen. Menschliche Auswahl nicht stillschweigend zu überschreiben ist der Kern des Designs; das Panel zeigt bei der Anwendung immer an, „wer wann und wofür es angegeben hat“, und bietet eine Möglichkeit zum Aufheben.

Entscheidungsansichten (implementiert)

Da in der Praxis wiederholt auftrat, dass man mit einer „Durchschnitts-Rangliste“ allein nicht entscheiden kann, wurde das Grundgerüst der Entscheidung als Komponenten modularisiert. Alles wird in zwei Ansichten bereitgestellt: Mensch = Diagramm / Agent = JSON.

• Paardifferenz paired_diff — Fallweise Differenz zweier Versuche. Warnt, wenn das Vorzeichen des Durchschnitts und die Fallmehrheit abweichen (bei Abweichung kann man keine Rangfolge behaupten; ist bei echten Daten mehrfach aufgetreten). Mit cases kann man die Aggregation auf eine Teilmenge beschränken. Es ist die Schnittstelle, um Fälle, bei denen die Bedingungen in beiden Versuchen nicht gleich sind, nicht in den Durchschnitt zu mischen; bei RSNA war die Differenz der 3 Labels ohne Gradienten Rauschen, verdünnte aber den Durchschnitt über 12 Labels, sodass der Durchschnitt -0.040 gegenüber dem Median -0.104 um das Dreifache abwich. Ausgeschlossene Fälle landen immer in excluded_cases und bleiben im Diagramm als grau erhalten (würde man sie entfernen, könnte der Leser nicht unterscheiden, ob eine günstige Teilmenge gewählt oder Fälle mit anderen Bedingungen ausgeschlossen wurden). Das Panel hat ebenfalls ein Auswahlfeld „Von der Aggregation auszuschließende Fälle (mehrere möglich)“; bei Auswahl werden Diagramm und Statistik sofort aktualisiert (gleiche Funktion wie cases bei MCP compare_trials und das dritte Element von pairs in build_report).

• Schichtmittelwerte strata_means — zeigt „In dieser Schicht kehrt sich die Rangfolge um“. Die Definition der Schichten (Domänenwissen) liegt beim Aufrufer.

• Entscheidungshebel decision_leverage — welche Entscheidung zuerst getroffen werden sollte. Zwei Annahmen (1 Entscheidung = 1 Faktor, nur lebende Optionen) werden jedes Mal als premises mitgeliefert.

• Fallweise Details case_scores / Dot-Strip-Diagramm — bringt die „absolute Schwierigkeit der Fälle“, die in der relativen Heatmap verschwindet, passiv als Sortierreihenfolge ins Auge.

• Oracle-Spielraum headroom — für Vorschläge zur Lockerung von Beschränkungen (z. B. Scheduled Sampling) wird vor der Implementierung die Obergrenze per Oracle-Lauf gemessen. Oracle nicht übernehmbar, dass es eine Obergrenze ist, und bei Unterschreiten der Schwelle systematisch verwerfen, werden als premises mitgeliefert.

• Generalisierungs-Lücken-Streudiagramm — automatisch angezeigt, wenn mindestens 2 Versuche mit lb_score / oos_score vorhanden sind.

Betriebskomponenten

• Versuchsarchiv set_archived / archive_trial — blendet Versuche, die mit fortschreitender Phase abgeschlossen sind, reversibel aus und erhält so die Auflösung der Visualisierung (nicht löschen; Historie bleibt in MLflow).

• Dunkelmodus — Berichte unterstützen prefers-color-scheme (Plotly-Diagramme folgen per relayout).

• 17 Panel-MCP-Tools (13 lesend + schreibend: add_feedback-Familie, decide / archive_trial, point_at_comparison / clear_comparison_pointer. Die letzten beiden ändern das Register nicht, sondern bewegen nur den Vergleich, den der menschliche Bildschirm betrachtet).

Praxisbeispiele (Fallstudien)

• kaggle-store-sales-workflow — Zeitreihen-Validierungsdesign. 12 Entscheidungen als Entscheidungspunkte verbucht und alles – Split-Design, Baseline, Merkmale, Annahme/Ablehnung – nach dem Prinzip „erst messen, dann entscheiden“ betrieben. Bis hin zur LB-Transferanalyse der CV-Verbesserung.

• kaggle-house-prices-workflow — Nested-CV-Modellauswahl. Erste Anwendung, bei der die Fall-Heatmap eine in der Durchschnittsrangfolge verborgene Schichtumkehrung erkannte.

• rsna-knee-abnormality-detection — Schwach überwachte 12-Label-Klassifikation (macro ROC-AUC). Erste Anwendung von from_per_label. Wenn man die Labels nach Lehrerdichte schichtet, ergeben die 8 dichten Labels 0.751, während die 4 lehrerarmen Labels 0.525 erreichen; ein Drittel der Metrik ist praktisch ungelernnt – das kam unter dem Durchschnitt von 0.6807 hervor. In den folgenden Vergleichen zeigte sich auch, dass die Paardifferenz auf eine Teilmenge beschränkt werden muss (über alle 12 Labels beträgt der Durchschnitt -0.040, aber auf die Labels mit Gradienten beschränkt ist der Hebel -0.090; hätte man nur nach dem Durchschnitt entschieden, hätte man es um mehr als die Hälfte unterschätzt).

• examples/ingest_ahc069.py — Übernahme von 1133 Versuchen aus den Messprotokollen des eigenen AHC-Runners.

Roadmap

• Visualisierung der Residuen-Korrelationsmatrix (wurde manuell für die Bewertung der Blend-Diversität erstellt; Kandidat für Komponentisierung)

• Benannter Schicht-Store (Persistenz der menschlichen „Zeigegesten“)

• Run-Alias (dieselbe Messung aus mehreren Entscheidungskontexten referenzieren; aus der Lehre, dass die Wiederverwendung von Versuchen die Sichtbarkeit zerstörte)

• pahcer-Format-Adapter (wird hinzugefügt, sobald echte Ausgaben verfügbar sind)

• Größenoptimierung der Berichte (mit Plotly etwa 4,9 MB pro Stück; gemessen, dass es das Lesen durch Agenten nicht beeinträchtigt)