agent-viz

ML実験の試行・ケース別スコア・判断の根拠を、人間とAIエージェントが同じ画面で確認するPythonツール。

入口: セットアップと合成デモ · 判断ビュー · 時系列ダッシュボード

合成デモは個人の実験ログなしで動きます。公開版の構成は pyproject.toml と src/agentviz/ を参照してください。

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

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

• 記録の背骨 = MLflow（ローカルSQLiteバックエンド）。エージェントが書き、人間は mlflow ui で見る

• カスタム図 = 自己完結HTML（Plotly）。MLflow のアーティファクトビューでインライン描画される

• 自前で持つのは「共通試行台帳スキーマ」「レポート部品」「ドメインアダプタ」の薄い層だけ

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

Related MCP server: relationship-manager

Phase 0（実装済み）

• agentviz.schema — 共通試行台帳スキーマ。1試行 = TrialRecord、ケース = seed / fold / 期間

• agentviz.ledger — TrialLedger。MLflow への log_trial / fetch_trials

• agentviz.report — build_report。試行台帳テーブル＋メトリクス推移＋ケース別×試行別相対スコアヒートマップの自己完結HTML

使い方

Python 3.10以上。cloneしたリポジトリ直下で実行します。

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev,panel]"

# HTMLだけを生成する。実験ストアには記録しない
.\.venv\Scripts\python.exe demo\generate_demo.py --no-log
# 生成された demo/out/report.html をブラウザで開く

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

パネルを使わない場合は .[dev] だけでインストールできます。macOS/Linuxでは .venv/Scripts/python.exe を .venv/bin/python に置き換えてください。

台帳への記録とパネルを試す場合:

$env:AGENTVIZ_STORE = Join-Path (Get-Location).Path "store"
.\.venv\Scripts\python.exe demo\generate_demo.py
.\.venv\Scripts\python.exe -m agentviz.panel

パネルは http://127.0.0.1:7861。記録デモは実行ごとにrunを追加するため、 表示だけ確認する繰り返し実行には --no-log を使います。

MLflow UIを使う場合は、記録デモの末尾に出る tracking -> sqlite:///.../mlflow.db のURI部分を mlflow ui --backend-store-uri "<表示されたSQLite URI>" に渡します。 保存先は 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 メトリクス。 macro AUC / macro F1 のように指標がラベル別スコアの平均で定義されるコンペ向けに from_per_label(label_scores, label_meta=..., metric_name="macro_auc") を持つ（ケース=ラベル）。 主指標を cv_mean と呼ばないのは、fold間のばらつき（測定の揺れ）とラベル間の落差（実力の差）を 取り違えないため。動かせるのは後者である。label_meta はケースの meta に入り、 教師の濃さや陽性数による層別の材料になる

• 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）だけを理由付きで改訂する （登録時点の根拠はイベントとして常に履歴に残る）。

視点合わせ（実装済み）— エージェント→人間

feedback は人間→エージェント、decisions は論点の帳簿。もう一方向が欠けていた: エージェントが今どの比較を見て物を言っているのかを、人間の画面に一致させる手段。

エージェントが「9ラベルに絞ると8勝1敗」と言っても、人間が別の比較を見ていれば 数字は合わない。条件を言葉で伝え直すのは伝言ゲームで、実際にこの往復で 「除外したのか、全部見たのか」が曖昧になった。

• agentviz.viewstate — 指差しのストア（追記専用JSONL、store/viewstate.jsonl）。 point / clear / current / history

• MCPツール point_at_comparison — 基準・候補・集計から外すケースをパネルへ送り、 同じ呼び出しでその比較の数字も返す（別々に取ると食い違いうる）。 note は必須。理由の無い画面変更は人間から見れば「勝手に変わった」でしかない

• MCPツール clear_comparison_pointer / パネルの「指差しを解除」ボタン

台帳も決定も書き換えない。 所見でも判断でもなく、視点を合わせるポインタである。 人間の選択を黙って上書きしないことが設計の要で、パネルは適用時に 「誰がいつ何のために指定したか」を必ず表示し、解除の口を添える。

判断ビュー（実装済み）

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

• ペア差 paired_diff — 2試行のケース単位差。平均の符号とケース多数決が食い違う場合に 警告（食い違ったら順位を主張できない。実データで複数回発火した）。 cases で集計を部分集合に限れる。両試行で条件が同じでないケースを平均に混ぜないための口で、 RSNAでは勾配の来ていない3ラベルの差がノイズなのに12ラベルの平均を薄め、 平均 -0.040 に対し中央値 -0.104 と3倍ずれた。外したケースは excluded_cases に必ず入り、 図からも消さず灰色で残す（消すと、都合の良い部分集合を選んだのか 条件の違うケースを外したのかを読者が区別できない）。 パネルにも「集計から外すケース（複数可）」の選択欄があり、選ぶとその場で 図と統計が更新される（MCP compare_trials の cases、build_report の pairs 第3要素と同じ機能）

• 層別平均 strata_means — 「この層では順位が入れ替わる」を出す。層の定義（ドメイン知識）は 呼び出し側が持つ

• 効き幅 decision_leverage — どの決定を先に決めるべきか。前提2つ（1決定=1因子、 生きている選択肢のみ）を毎回premisesとして同梱

• ケース別詳細 case_scores / ドットストリップ図 — 相対ヒートマップで消える 「ケースの絶対難易度」を並び順として受動的に目に入れる

• オラクル余地 headroom — 制約緩和系の案（scheduled sampling等）は実装前に オラクル走行で上限を測る。オラクル採用不可・上限であること・閾値未満なら系統見送り、を premisesに同梱

• 汎化ギャップ散布図 — lb_score / oos_score 付き試行が2つ以上で自動表示

実ケースの確認（実装済み）— ケースの中身を開く

case は集計の器（RSNAならラベル、AHCならseed、トレードなら期間）で、 その中で何が起きたかは台帳から見えなかった。「Baker's が弱い」までは 人間とエージェントで共有できても、どの実例をどう外したかは残らないので、 双方が別のものを思い浮かべたまま原因を議論することになる。実際にRSNAで 「教師が悪いのか画像が難しいのか」の往復がここで止まった。

• ExampleResult(example_id, case_id, y_pred, y_true=None, meta={}) — ケースの中の1件。TrialRecord(examples=[...]) に入れる。 y_true は無くてよい。その場合 error は None で、誤差では並べられない。 無いものを0として扱わない（0にすると「正解が無いだけの実例」が誤差順の 上位に混ざり、見た目には分からない）

• 上限 MAX_EXAMPLES=20000。台帳は全件保存の場所ではなく、議論のために覗くところ。 超えたら理由付きで断る

• example_rows / MCP list_examples — 1試行の実例を誤差の大きい順に。 正解が1件も無ければ黙って別の順序にせず、sort_fallback に何をしたかを書く。 「実例が無い」と「正解が無い」は別の文言にする（直す場所が違うため）

• example_disagreements / MCP compare_examples — 同じ実例を2試行がどう違えたか。 符号は paired_diff と揃える（負なら候補が良い）。ただしどちらが良いかを 言えるのは y_true があるときだけで、無ければ delta は None、 pred_shift だけが出る。「違う」と「良い」を混ぜない

• MCP point_at_examples — 実例まで人間の画面を合わせ、同じ呼び出しで中身も返す。 case_id は必須（同名 example_id が別ケースにありうる）。note も必須。 比較の指差しと同じ1本のポインタに相乗りする。人間の画面が同時に2つの 「今見ているもの」を持てないため

• パネルに「実ケース」節。指差しが実例まで指しているときだけ開く。 指していないのに勝手に何かを開かないのは viewstate の約束と同じ

まだできないこと: 実例を入れると study 単位のブートストラップが可能になるが、 それ自体は未実装。ケース単位の再標本化（case_resample_range）は 信頼区間ではないので、順位の主張には使えないままである。

運用部品

• 試行アーカイブ set_archived / archive_trial — フェーズが進んで決着した試行を 可逆に非表示化し、可視化の分解能を保つ（削除しない。履歴はMLflowに残る）

• ダークモード — レポートはprefers-color-scheme対応（Plotly図はrelayoutで追随）

• パネルMCPツール20本（読み取り15＋書き込みは add_feedback 系・decide / archive_trial・point_at_comparison / point_at_examples / clear_comparison_pointer。指差し3本は台帳を変えず、人間の画面が見ているものだけを動かす）

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

• kaggle-store-sales-workflow — 時系列検証設計。12決定を決定点として帳簿化し、分割設計・ベースライン・特徴・採用可否を すべて「測ってから決める」で運用。CV改善のLB転移分析まで

• kaggle-house-prices-workflow — nested-CVモデル選択。ケース別ヒートマップが平均の順位に隠れた層別反転を検出した初適用

• rsna-knee-abnormality-detection — 弱教師つき12ラベル分類（macro ROC-AUC）。 from_per_label の初適用。教師の濃さでラベルを層別すると、 濃い8ラベル 0.751 に対し教師が枯れた4ラベルが 0.525 で、 指標の1/3が実質未学習であることが平均 0.6807 の下から出てきた。 続く比較でペア差の集計限定が要ることも判明した（全12ラベルでは平均 -0.040 だが、 勾配の来ているラベルに絞ると効き幅は -0.090。平均だけで採否を決めていたら 半分以下に見誤っていた）

• examples/ingest_ahc069.py — AHC自前ランナーの実測ログ1133試行の取込

ロードマップ

• 残差相関行列のビュー化（ブレンド多様性の判断で手組みした。部品化候補）

• 名前付き層ストア（人間の「指差し」の永続化）

• run alias（同一測定を複数の決定文脈から参照。試行の流用が可視性を壊した教訓から）

• pahcer形式アダプタ（実物の出力が手に入ったときに追加）

• レポートのサイズ最適化（Plotly同梱で約4.9MB/枚。エージェントの読み取りには支障なしと実測済み）

時系列ダッシュボード（2026-09-04）

agentviz.timeseries.build_timeseries(spec, out_path) — 条件×時系列（中央値＋帯）の比較ページ。 kaggriculture の「本番56試合の再戦」計装から一般化した。横軸は day / epoch / 窓など任意の整数、 セクション→パネル→系列の仕様 dict を渡すと、KPI・小さな多重パネル・凡例・端ラベル・ホバー・表・所見を持つ 自己完結 HTML を返す。Plotly を同梱しない（インライン SVG を JS で描く）ので 1ページ 30〜200KB。 仕様の形は timeseries.py の docstring にある。使用例: Kaggle/kaggriculture/79_live_ts_page.py （集計 JSON → 仕様 → HTML）。validate_spec が系列長・帯の形・表の列数の不一致を描く前に止める。