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. 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 메트릭. 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개 이상이면 자동 표시

운영 부품

• 시행 아카이브 set_archived / archive_trial — 페이즈가 진행되어 결착된 시행을 가역적으로 비표시화하고, 가시화의 분해능을 유지한다(삭제하지 않는다. 이력은 MLflow에 남는다)

• 다크 모드 — 리포트는 prefers-color-scheme 대응(Plotly 도표는 relayout으로 추종)

• 패널 MCP 도구 17개(읽기 13＋쓰기는 add_feedback 계·decide / archive_trial·point_at_comparison / clear_comparison_pointer. 마지막 2개는 대장을 바꾸지 않고, 인간의 화면이 보고 있는 비교만 움직인다)

실운용의 적용 예(케이스 스터디)

• 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/장. 에이전트의 읽기에는 지장 없음이 실측 완료)