agent-viz

Постоянно развивающийся актив для расширения коммуникации между человеком и AI-агентами — от чата к визуальным форматам (графы, древовидные диаграммы, тепловые карты, блок-схемы). Используется совместно для Kaggle / AtCoder Heuristic / разработки торговых моделей.

Политика структуры (на основе исследования от 2026-08-24)

• Хребет записей = MLflow (локальное file store). Агенты пишут, человек смотрит через mlflow ui

• Пользовательские графики = самодостаточный HTML (Plotly). Отрисовываются инлайн в представлении артефактов MLflow

• Своё держим только тонкий слой: «общая схема журнала экспериментов», «компоненты отчётов», «доменные адаптеры»

Первоисточник исследования: KnowledgeBase 00_Inbox/人間とAIエージェントのビジュアル意思疎通ツール 調査メモ

Related MCP server: Querytree MCP Server

Phase 0 (реализовано)

• agentviz.schema — общая схема журнала экспериментов. 1 эксперимент = TrialRecord, кейс = seed / fold / период

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

• 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. Для соревнований, где метрика определяется как среднее по баллам за каждый лейбл (например, 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, ...). Кейс = окно walk-forward. OOS — метрика oos_score, HTML тир-шита прикрепляется через log_trial(artifact_paths=...)

• agentviz.report — добавлен scatter-график обобщающего разрыва (автоматически показывается при наличии 2+ экспериментов с lb_score / oos_score. 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 не отражается, надёжный fallback — кнопка «Перезагрузить».

Phase 3 (реализовано) — точки принятия решений

Если feedback обрабатывает одно往返 «замечание → реакция» вида «этот слой слабый, исправь», то decisions обрабатывает вопросы, где «нельзя двигаться дальше, пока не решено, что брать». Формы разные, поэтому разделены.

• agentviz.decisions — хранилище точек принятия решений (JSONL только на добавление, store/decisions.jsonl). propose / decide / supersede

• Варианты имеют флаг measured. Если неизмеренные варианты нельзя показать рядом с измеренными, «лучший среди измеренных» будет ошибочно прочитан как «лучший»

• Зависимости между решениями задаются через blocks. ready() возвращает только те, чьи зависимости уже решены

• Каждый вариант ссылается на эксперименты журнала через evidence_trials

Распределение первоисточников: описание зафиксированных решений — первоисточник в Vault KnowledgeBase. decisions держит рабочую поверхность (варианты, ссылки на обоснования, состояние) и указывает на Vault через vault_ref. Один и тот же текст в обоих местах не дублируется.

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 и не удаляются с графика, а остаются серыми (если удалить, читатель не отличит «выбрал удобное подмножество» от «исключил кейсы с другими условиями»). На панели тоже есть поле выбора «кейсы для исключения из агрегации (можно несколько)»; при выборе график и статистика обновляются на месте (та же функция, что cases в MCP compare_trials и 3-й элемент pairs в build_report)

• Стратифицированные средние strata_means — показывает «в этом слое ранг меняется местами». Определение слоёв (доменное знание) держит вызывающая сторона

• Рычаг решения decision_leverage — какое решение решать первым. Две предпосылки (1 решение = 1 фактор, только живые варианты) каждый раз прилагаются как premises

• Детализация по кейсам case_scores / dot-strip график — «абсолютная сложность кейса», исчезающая в относительной тепловой карте, пассивно попадает в поле зрения как порядок сортировки

• Потолок оракула headroom — для идей типа ослабления ограничений (scheduled sampling и т.п.) до реализации измеряется верхняя граница прогоном оракула. В premises включаются: оракул неприменим, это верхняя граница, и если ниже порога — систематически отказываемся

• Scatter-график обобщающего разрыва — автоматически показывается при 2+ экспериментах с lb_score / oos_score

Операционные компоненты

• Архив экспериментов set_archived / archive_trial — решённые по мере продвижения фаз эксперименты обратимо скрываются, сохраняя разрешающую способность визуализации (не удаляются. История остаётся в MLflow)

• Тёмный режим — отчёты поддерживают prefers-color-scheme (графики Plotly следуют через relayout)

• 17 MCP-инструментов панели (13 на чтение + на запись: семейство add_feedback, decide / archive_trial, point_at_comparison / clear_comparison_pointer. Последние два не меняют журнал, а двигают только то сравнение, которое видит экран человека)

Примеры реального применения (кейс-стади)

• 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; из-под среднего 0.6807 всплыло, что 1/3 метрики фактически не обучена. В последующих сравнениях выяснилось, что нужно ограничение агрегации парной разности (по всем 12 лейблам среднее -0.040, но при сужении до лейблов с приходящим градиентом рычаг -0.090. Если бы решали только по среднему, ошиблись бы более чем вдвое)

• examples/ingest_ahc069.py — импорт 1133 экспериментов из фактических логов собственного AHC-раннера

Дорожная карта

• Визуализация корреляционной матрицы остатков (сделано вручную для оценки разнообразия блендов. Кандидат на компонентизацию)

• Хранилище именованных слоёв (персистентность «указаний» человека)

• run alias (ссылка на одно измерение из нескольких контекстов решений. Урок из того, как переиспользование экспериментов сломало видимость)

• Адаптер формата pahcer (добавить, когда появится реальный вывод)

• Оптимизация размера отчётов (с Plotly ~4.9 МБ/шт. Измерено, что для чтения агентом это не мешает)