agent-viz

Activo continuo que amplía la comunicación entre humanos y agentes de IA, del chat a lo visual (gráficos, diagramas de árbol, mapas de calor, diagramas de flujo). Se comparte entre Kaggle / AtCoder Heuristic / desarrollo de modelos de trading.

Política de composición (basada en la investigación del 2026-08-24)

• Columna vertebral del registro = MLflow (file store local). El agente escribe y el humano ve con mlflow ui

• Gráficos personalizados = HTML autocontenido (Plotly). Se renderizan en línea en la vista de artefactos de MLflow

• Lo que se mantiene por cuenta propia es solo una capa fina de «esquema común de libro de registro de ensayos», «componentes de informe» y «adaptadores de dominio»

Fuente original de la investigación: KnowledgeBase 00_Inbox/人間とAIエージェントのビジュアル意思疎通ツール 調査メモ

Related MCP server: Querytree MCP Server

Fase 0 (implementada)

• agentviz.schema — Esquema común de libro de registro de ensayos. 1 ensayo = TrialRecord, caso = seed / fold / período

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

• agentviz.report — build_report. HTML autocontenido con tabla de libro de registro de ensayos + evolución de métricas + mapa de calor de puntuaciones relativas por caso × por ensayo

Uso

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

El almacén predeterminado es %AGENTVIZ_STORE%; si no está configurado, ~\dev\Projects\agent-viz\store.

Fase 1 (implementada)

• agentviz.adapters.ahc — Importación del formato de medición real del runner AHC propio. from_results_json (results/*.json) y from_experiments_jsonl (1 línea = 1 experimento. Las líneas rotas se devuelven como error y se continúa; las líneas con metrics vacías se rescatan recalculando a partir de los resultados por seed; las rutas absolutas de otros dispositivos se resuelven por nombre de archivo con results_dir)

• agentviz.adapters.kaggle — from_cv(fold_scores, lb_score=...). Caso = fold, LB es la métrica lb_score. Para competiciones donde la métrica se define como el promedio de puntuaciones por etiqueta, como macro AUC / macro F1, dispone de from_per_label(label_scores, label_meta=..., metric_name="macro_auc") (caso = etiqueta). No se llama a la métrica principal cv_mean para no confundir la variación entre folds (fluctuación de la medición) con la brecha entre etiquetas (diferencia de capacidad). Lo que se puede mover es lo segundo. label_meta entra en el meta del caso y sirve de material para la estratificación por densidad de supervisión o número de positivos

• agentviz.adapters.trade — from_walkforward(windows, ...). Caso = ventana de walk-forward. OOS es la métrica oos_score; el HTML de la hoja de resultados se adjunta con log_trial(artifact_paths=...)

• agentviz.report — Se añade el diagrama de dispersión de brecha de generalización (se muestra automáticamente cuando hay 2 o más ensayos con lb_score / oos_score. CV vs LB = IS vs OOS se tratan de forma isomórfica)

• agentviz.replay — build_replay(frames, infos, events). Esqueleto del replay propio de ahc069 (barra de búsqueda, reproducción, avance fotograma a fotograma, teclas ←→, salto por clic en evento) generalizado de forma independiente del dominio en HTML autocontenido

Confirmado con datos reales: se importaron 1133 ensayos de AtCoder\ahc\ahc069\experiments.jsonl (1191 líneas), con resolución de casos por seed en 1130 ensayos (examples/ingest_ahc069.py).

Fase 2 (implementada) — Bidireccionalidad

• agentviz.feedback — Almacén original de comentarios estratificados (JSONL de solo añadido, store/feedback.jsonl). add / list / resolve

• agentviz.panel — Panel Gradio y servidor MCP a la vez. El humano ve el libro de registro de ensayos y el mapa de calor, envía señalamientos estratificados (ensayo objetivo, caso objetivo, instrucción, prioridad), y el agente los lee con herramientas MCP, los atiende y los cierra con 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/

Incluso sin usar MCP, se puede leer y escribir directamente con gradio_client o agentviz.feedback.FeedbackStore. En entornos donde la selección del desplegable de la UI no se refleja, el botón «Recargar» es un respaldo fiable.

Fase 3 (implementada) — Puntos de decisión

Mientras que feedback trata el señalamiento → respuesta de un solo intercambio, del tipo «esta capa es débil, arréglala», decisions trata cuestiones del tipo «no se puede avanzar hasta que se decida cuál adoptar». Como la forma es distinta, están separados.

• agentviz.decisions — Almacén de puntos de decisión (JSONL de solo añadido, store/decisions.jsonl). propose / decide / supersede

• Las opciones tienen un flag measured. Si no se pueden mostrar las opciones no medidas junto a las medidas, se malinterpreta «lo mejor entre lo medido» como «lo mejor»

• Con blocks se mantienen dependencias entre decisiones. ready() devuelve solo las que tienen resueltas sus dependencias

• Cada opción apunta a ensayos del libro de registro con evidence_trials

Reparto de fuentes originales: la descripción de los juicios ya determinados tiene como fuente original el Vault de KnowledgeBase. decisions mantiene la superficie de trabajo (opciones, enlaces de evidencia, estado) y apunta al lado del Vault con vault_ref. No se mantiene el mismo texto en ambos.

decide es la boca para registrar el juicio humano. El agente presenta las opciones (propose_decision) y el humano elige. chosen se limita a claves registradas; no se acepta texto libre (porque luego no se podría rastrear mecánicamente). revise_option solo revisa, con justificación, el estado de la evidencia (evidence_trials / measured / note) (la evidencia en el momento del registro siempre permanece en el historial como evento).

Alineación de perspectiva (implementada) — Agente → humano

feedback es humano → agente, y decisions es el libro de contabilidad de las cuestiones. Faltaba una dirección más: un medio para que la pantalla del humano coincida con qué comparación está mirando el agente al hablar.

Aunque el agente diga «si nos limitamos a 9 etiquetas, 8 victorias y 1 derrota», si el humano está viendo otra comparación, los números no cuadran. Re-transmitir las condiciones con palabras es un juego del teléfono roto; de hecho, en este intercambio se volvió ambiguo si se había «excluido» o «visto todo».

• agentviz.viewstate — Almacén de señalamiento (JSONL de solo añadido, store/viewstate.jsonl). point / clear / current / history

• Herramienta MCP point_at_comparison — Envía al panel la referencia, el candidato y los casos excluidos de la agregación, y en la misma llamada devuelve también los números de esa comparación (si se toman por separado pueden discrepar). note es obligatorio. Un cambio de pantalla sin razón no es más que «se cambió solo» desde la perspectiva del humano

• Herramienta MCP clear_comparison_pointer / botón «Liberar señalamiento» del panel

No se reescribe ni el libro de registro ni las decisiones. No es una observación ni un juicio, sino un puntero para alinear la perspectiva. No sobrescribir en silencio la elección del humano es el punto clave del diseño; el panel, al aplicar, muestra siempre «quién lo especificó, cuándo y para qué», y añade una vía para liberarlo.

Vista de juicio (implementada)

Como en la práctica real apareció repetidamente que «solo con la tabla de clasificación de promedios» no se puede juzgar, se ha convertido en componentes el esqueleto del juicio. Todo se ofrece en dos caras: humano = figura / agente = JSON.

• Diferencia por pares paired_diff — Diferencia por caso entre 2 ensayos. Advierte cuando el signo del promedio y la mayoría de casos discrepan (si discrepan, no se puede sostener la clasificación. Se disparó varias veces con datos reales). Con cases se puede limitar la agregación a un subconjunto. Es la vía para no mezclar en el promedio casos cuyas condiciones no son iguales en ambos ensayos; en RSNA, la diferencia de las 3 etiquetas sin gradiente era ruido y diluía el promedio de las 12 etiquetas, con una desviación de 3 veces entre el promedio -0.040 y la mediana -0.104. Los casos excluidos entran siempre en excluded_cases y no se eliminan de la figura, sino que permanecen en gris (si se eliminan, el lector no puede distinguir si se eligió un subconjunto conveniente o se excluyeron casos con condiciones distintas). El panel también tiene un campo de selección de «casos a excluir de la agregación (múltiples)»; al seleccionarlos, la figura y las estadísticas se actualizan al momento (misma función que cases de MCP compare_trials y el tercer elemento de pairs de build_report)

• Medias estratificadas strata_means — Muestra «en esta capa la clasificación se invierte». La definición de las capas (conocimiento de dominio) la tiene quien llama

• Palanca de decisión decision_leverage — Qué decisión conviene resolver primero. Las 2 premisas (1 decisión = 1 factor, solo opciones vivas) se incluyen siempre como premises

• Detalle por caso case_scores / diagrama de puntos — La «dificultad absoluta del caso» que desaparece en el mapa de calor relativo se hace ver pasivamente como orden de disposición

• Margen de oráculo headroom — Para propuestas de relajación de restricciones (scheduled sampling, etc.), antes de implementar se mide el límite superior con una ejecución de oráculo. Se incluyen en premises: el oráculo no es adoptable, es el límite superior, y si está por debajo del umbral se descarta sistemáticamente

• Diagrama de dispersión de brecha de generalización — Se muestra automáticamente cuando hay 2 o más ensayos con lb_score / oos_score

Componentes operativos

• Archivo de ensayos set_archived / archive_trial — Oculta de forma reversible los ensayos ya resueltos al avanzar de fase, y mantiene la resolución de la visualización (no se eliminan. El historial permanece en MLflow)

• Modo oscuro — Los informes son compatibles con prefers-color-scheme (las figuras de Plotly lo siguen con relayout)

• 17 herramientas MCP del panel (13 de lectura + escritura: familia add_feedback · decide / archive_trial · point_at_comparison / clear_comparison_pointer. Las 2 últimas no cambian el libro de registro; solo mueven la comparación que ve la pantalla del humano)

Ejemplos de aplicación en operación real (casos de estudio)

• kaggle-store-sales-workflow — Diseño de validación de series temporales. 12 decisiones contabilizadas como puntos de decisión, operando todo —diseño de partición, línea base, características, adopción o no— con «medir y luego decidir». Hasta análisis de transferencia a LB de la mejora de CV

• kaggle-house-prices-workflow — Selección de modelo con nested-CV. Primera aplicación donde el mapa de calor por caso detectó una inversión estratificada oculta en la clasificación de promedios

• rsna-knee-abnormality-detection — Clasificación de 12 etiquetas con supervisión débil (macro ROC-AUC). Primera aplicación de from_per_label. Al estratificar las etiquetas por densidad de supervisión, las 8 etiquetas densas dan 0.751 frente a 0.525 en las 4 etiquetas con supervisión agotada, y 1/3 de la métrica está prácticamente sin aprender, lo que salió a la luz bajo el promedio de 0.6807. En la comparación siguiente también se descubrió que se necesita limitar la agregación de la diferencia por pares (con las 12 etiquetas el promedio es -0.040, pero limitado a las etiquetas con gradiente, la palanca es -0.090. Si se hubiera decidido la adopción solo con el promedio, se habría subestimado a menos de la mitad)

• examples/ingest_ahc069.py — Importación de 1133 ensayos de los registros de medición real del runner propio de AHC

Hoja de ruta

• Visualización de la matriz de correlación de residuos (se hizo a mano para el juicio de diversidad de blends. Candidata a componente)

• Almacén de capas con nombre (persistencia del «señalamiento» del humano)

• run alias (referenciar la misma medición desde múltiples contextos de decisión. Lección aprendida de que la reutilización de ensayos rompió la visibilidad)

• Adaptador de formato pahcer (se añadirá cuando se obtenga la salida real)

• Optimización de tamaño de los informes (con Plotly incluido, ~4,9 MB/hoja. Medido: no supone obstáculo para la lectura del agente)