agent-viz

人間とAIエージェントの意思疎通を、チャットからビジュアル（グラフ・樹形図・ヒートマップ・フローチャート）へ拡張する継続資産。Kaggle / AtCoder Heuristic / トレードモデル開発で共用する。

構成方針（2026-08-24 調査に基づく）

• 記録の背骨 = MLflow（ローカル file store）。エージェントが書き、人間は mlflow ui で見る
• カスタム図 = 自己完結HTML（Plotly）。MLflow のアーティファクトビューでインライン描画される
• 自前で持つのは「共通試行台帳スキーマ」「レポート部品」「ドメインアダプタ」の薄い層だけ

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

Phase 0（実装済み）

• agentviz.schema — 共通試行台帳スキーマ。1試行 = TrialRecord、ケース = seed / fold / 期間
• agentviz.ledger — TrialLedger。MLflow への log_trial / fetch_trials
• agentviz.report — build_report。試行台帳テーブル＋メトリクス推移＋ケース別×試行別相対スコアヒートマップの自己完結HTML

使い方

# セットアップ
.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>"

既定ストアは %AGENTVIZ_STORE%、未設定なら ~\dev\Projects\agent-viz\store。

Phase 1（実装済み）

• agentviz.adapters.ahc — 自前AHCランナー実測形式の取込。from_results_json（results/*.json）と from_experiments_jsonl（1行=1実験。壊れた行はエラーとして返して続行、metrics空の行はper-seed結果から再計算して救済、別端末の絶対パスは results_dir でファイル名解決）
• agentviz.adapters.kaggle — from_cv(fold_scores, lb_score=...)。ケース=fold、LBは lb_score メトリクス
• agentviz.adapters.trade — from_walkforward(windows, ...)。ケース=ウォークフォワード窓。OOSは oos_score メトリクス、ティアシートHTMLは log_trial(artifact_paths=...) で添付
• agentviz.report — 汎化ギャップ散布図を追加（lb_score / oos_score を持つ試行が2つ以上で自動表示。CV vs LB＝IS vs OOSを同型に扱う）
• agentviz.replay — build_replay(frames, infos, events)。ahc069自作リプレイの骨格（シークバー・再生・コマ送り・←→キー・イベントクリックジャンプ）をドメイン非依存に一般化した自己完結HTML

実データ確認済み: AtCoder\ahc\ahc069\experiments.jsonl（1191行）から1133試行を取込、1130試行でper-seedケース解決（examples/ingest_ahc069.py）。

Phase 2（実装済み）— 双方向化

• agentviz.feedback — 層別フィードバックの正本ストア（追記専用JSONL、store/feedback.jsonl）。add / list / resolve
• agentviz.panel — Gradioパネル兼MCPサーバー。人間は試行台帳・ヒートマップを見て層別指摘（対象試行・対象ケース・指示・優先度）を投函し、エージェントはMCPツールで読んで対応し 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/

MCPを使わない場合も gradio_client または agentviz.feedback.FeedbackStore で直接読み書きできる。 UIのドロップダウン選択が反映されない環境では「再読込」ボタンが確実なフォールバック。

Phase 3（実装済み）— 決定点

feedback が「この層が弱いから直せ」という指摘→対応の一往復を扱うのに対し、 decisions は「どれを採るか決まるまで先へ進めない」論点を扱う。形が違うので分けてある。

• agentviz.decisions — 決定点のストア（追記専用JSONL、store/decisions.jsonl）。propose / decide / supersede
• 選択肢は measured フラグを持つ。未測定の選択肢を測定済みと並べて表示できないと、「測った中で最良」を「最良」と誤読する
• blocks で決定間の依存を持つ。ready() は依存先が決着したものだけを返す
• 各選択肢は evidence_trials で台帳の試行を指す

正本の分担: 確定した判断の記述は KnowledgeBase の Vault が正本。 decisions が持つのは作業面（選択肢・根拠リンク・状態）で、vault_ref でVault側を指す。 同じ文章を両方に持たない。

decide は人間の判断を記録するための口である。エージェントが選択肢を並べ（propose_decision）、 人間が選ぶ。chosen は登録済みキーに限られ、自由記述は受け付けない（後から機械的に辿れなくなるため）。 revise_option は根拠の状態（evidence_trials / measured / note）だけを理由付きで改訂する （登録時点の根拠はイベントとして常に履歴に残る）。

判断ビュー（実装済み）

「平均の順位表」だけでは判断できない、が実戦で繰り返し出たため、判断の骨格を部品化した。 すべて 人間=図 / エージェント=JSON の二面で提供する。

• ペア差 paired_diff — 2試行のケース単位差。平均の符号とケース多数決が食い違う場合に 警告（食い違ったら順位を主張できない。実データで複数回発火した）
• 層別平均 strata_means — 「この層では順位が入れ替わる」を出す。層の定義（ドメイン知識）は 呼び出し側が持つ
• 効き幅 decision_leverage — どの決定を先に決めるべきか。前提2つ（1決定=1因子、 生きている選択肢のみ）を毎回premisesとして同梱
• ケース別詳細 case_scores / ドットストリップ図 — 相対ヒートマップで消える 「ケースの絶対難易度」を並び順として受動的に目に入れる
• オラクル余地 headroom — 制約緩和系の案（scheduled sampling等）は実装前に オラクル走行で上限を測る。オラクル採用不可・上限であること・閾値未満なら系統見送り、を premisesに同梱
• 汎化ギャップ散布図 — lb_score / oos_score 付き試行が2つ以上で自動表示

運用部品

• 試行アーカイブ set_archived / archive_trial — フェーズが進んで決着した試行を 可逆に非表示化し、可視化の分解能を保つ（削除しない。履歴はMLflowに残る）
• ダークモード — レポートはprefers-color-scheme対応（Plotly図はrelayoutで追随）
• パネルMCPツール15本（読み取り13＋書き込みは add_feedback 系と decide / archive_trial のみ）

実運用の適用例（ケーススタディ）

• kaggle-store-sales-workflow — 時系列検証設計。12決定を決定点として帳簿化し、分割設計・ベースライン・特徴・採用可否を すべて「測ってから決める」で運用。CV改善のLB転移分析まで
• kaggle-house-prices-workflow — nested-CVモデル選択。ケース別ヒートマップが平均の順位に隠れた層別反転を検出した初適用
• examples/ingest_ahc069.py — AHC自前ランナーの実測ログ1133試行の取込

ロードマップ

• 残差相関行列のビュー化（ブレンド多様性の判断で手組みした。部品化候補）
• 名前付き層ストア（人間の「指差し」の永続化）
• run alias（同一測定を複数の決定文脈から参照。試行の流用が可視性を壊した教訓から）
• pahcer形式アダプタ（実物の出力が手に入ったときに追加）
• レポートのサイズ最適化（Plotly同梱で約4.9MB/枚。エージェントの読み取りには支障なしと実測済み）