eval-runner

name	eval-runner
description	RAG 실험을 사전 검증(preflight)부터 실행, checkpoint resume, chain 오케스트레이션, multi-metric 수집(IC/CC/SR/DocHit/MRR), 보고서 생성까지 자동화한다. 경로/형식/인코딩 같은 boundary 문제를 실행 전에 잡고 싶거나, 실험 후 측정 5단계를 한 번에 묶고 싶을 때 사용한다. YAML config 기반.

Eval Runner

RAG 실험의 실행 오케스트레이터.

이 스킬은 실험 실행보다 한 단계 넓다. 아래 상황에서 우선 사용한다.

• 실험 전에 경로/형식/인코딩 문제를 먼저 검증하고 싶을 때
• smoke -> full -> metrics -> report를 한 번에 돌리고 싶을 때
• 여러 config를 chain으로 순차 실행하고 싶을 때
• raw artifact에서 IC / CC / SR / doc_chunk_grouped를 자동 수집하고 싶을 때

지표 정의와 해석은 rag-bench가 담당한다. eval-runner는 그 측정 단계를 실행·묶는 역할을 한다.

Workflow

1. preflight  → config + boundary contract 검증
2. run        → 실험 실행 (checkpoint resume 자동)
3. metrics    → IC / CC / SR / doc_chunk_grouped 자동 수집
4. report     → mode별 요약 MD 생성
5. chain      → 여러 실험을 위 순서로 순차 실행

Commands

# 1) Preflight: config + boundary 검증만 수행
python3 scripts/eval_runner.py preflight --config CONFIG_PATH

# 2) Run: 실험 실행 (checkpoint 자동 resume)
python3 scripts/eval_runner.py run --config CONFIG_PATH

# 3) Metrics: raw artifact에서 bundled metrics 추출
python3 scripts/eval_runner.py metrics --result RESULT_JSON

# 4) Report: MD 보고서 생성
python3 scripts/eval_runner.py report --result RESULT_JSON --out REPORT_PATH

# 5) Full: preflight → run → metrics → report 전체 실행
python3 scripts/eval_runner.py full --config CONFIG_PATH

# 6) Chain: 여러 실험을 순차 실행 (experiment별 boundary override 지원)
python3 scripts/eval_runner.py chain --config CHAIN_CONFIG_PATH

Config 구조

기본 실험 config는 기존 plans/codex/algorithms/configs/ 형식을 그대로 사용한다. boundary 검증을 쓰려면 preflight.boundary_check 블록을 추가한다.

paths:
  eval_jsonl: datasets/eval_v1.jsonl
  eval_classified_json: datasets/eval_v1_classified.json

models:
  llm_model: gpt-4.1-mini

base:
  eval_limit: 70
  chunk_size_chars: 1200
  chunk_overlap_chars: 150
  parent_group_size: 3

modes: [hyde_rerank, A3_section_hybrid_evidence_dynamic_k_rerank]

grid:
  k_values: [160]

retrieval:
  scorer: embedding
  embedding_model: text-embedding-3-large
  final_top_n: 10

rerank:
  strategy: pinecone
  pinecone_model: bge-reranker-v2-m3
  top_m: 80

preflight:
  boundary_check:
    enabled: true
    profile: parent_cluster
    child_map_path: plans/codex/test_result/cache/embedding_store_large_parsed_multistrategy_full_dryrun_2026-03-14_html_child_map.json
    compact_embeddings_path: plans/codex/test_result/cache/embedding_store_html_compact_children_2026-03-14.json
    bridge_path: plans/codex/test_result/doc_id_bridge_latest.json
    embedding_store_path: plans/codex/test_result/cache/embedding_store_large_2026-03-04-21-25.json
    script_path: plans/codex/scripts/eval_ragas_llmjudge_10modes_kgrid.py
    script_parent_depth: 1
    minimum_bridge_coverage: 0.95
    minimum_embedding_coverage: 0.95

chain 예시는 references/chain_example.yaml을 본다.

결과 저장 규칙

• 결과 JSON: plans/codex/test_result/<experiment_name>_YYYY-MM-DD-HH-MM.json
• Checkpoint: plans/codex/test_result/<experiment_name>_checkpoint.json
• 로그: plans/codex/test_result/<experiment_name>_run_YYYY-MM-DD-HH-MM.log
• 보고서: plans/claude/<REPORT_TYPE>_YYYY-MM-DD-HH-MM.md

What Preflight Actually Checks

• config 로드 가능 여부
• 주요 입력 파일 존재 여부
• Pinecone / Python 의존성 / .venv 상태
• boundary contract:
  • parents[N] 경로 해석
  • bridge NFC 정규화
  • bridge → compact index coverage
  • compact retrieval_text → embedding coverage

boundary validator는 scripts/preflight_boundary_check.py에 있다.

Bundled Metrics

metrics는 raw artifact를 입력받으면 아래 4개를 묶어 실행한다.

• eval_ic.py
• eval_cc.py
• eval_sr.py
• eval_doc_chunk_grouped_metrics.py

출력:

• 개별 metric JSON
• merged metrics JSON
• report용 mode summary

Checkpoint Resume

• 모든 실험은 checkpoint.json을 주기적으로 저장
• 재실행 시 자동으로 checkpoint에서 이어서 실행
• checkpoint meta 불일치 시 초기화 (config 변경 감지)

실험 유형 매핑

유형	스크립트
rerank5	plans/codex/scripts/eval_rerank5_artifacts.py
nonrerank5	plans/codex/scripts/eval_nonrerank5_artifacts.py
judge	plans/codex/scripts/eval_ragas_llmjudge_10modes_kgrid.py

환경변수

변수	용도	기본값
EVAL_RUNNER_CONFIG	config YAML 경로	(선택)
EVAL_RUNNER_OUT	결과 JSON 경로	auto-generated
EVAL_RUNNER_CKPT	checkpoint 경로	auto-generated
EVAL_RUNNER_LOG	로그 경로	auto-generated
PINECONE_API_KEY	Pinecone reranker API	.env 또는 shell env

지표 해석 가이드

metrics/report 결과를 해석할 때는 rag-bench의 정의를 기준으로 본다. eval-runner의 SKILL.md는 정의 본문이 아니라 링크 중심 네비게이션만 제공한다.

정합성 레이어

이 skill이 metric 이름과 수식을 직접 정의하지는 않지만, 공통 고정점은 ../rag-bench/knowledge_bases/metric_formula_contract.md다. 즉 eval-runner는 실행 오케스트레이터이지만, report-facing key와 strict/proxy 구분은 contract를 따른다.

레이어:

1. fixed point
   • ../rag-bench/knowledge_bases/metric_formula_contract.md
   • naming, formula, class, strict/proxy, suffix governance
2. interpretation layer
   • ../rag-bench/knowledge_bases/rag_metric_logic.md
   • ../rag-bench/references/metric_definitions.md
3. design layer
   • ../rag-bench/references/metric_definition_examples.md
   • family example 문서 3종
4. execution layer
   • scripts/eval_runner.py
   • bundled metric scripts
   • merged metrics / report output

정합성 규칙:

• eval-runner는 해석을 새로 정의하지 않는다
• metric naming과 strict/proxy 구분은 contract를 따른다
• family example 문서는 metric을 새로 추가하거나 output key를 바꿀 때 먼저 참고한다
• merged metrics와 report는 contract의 report-facing profile 이름을 우선하고, legacy alias는 compatibility용 fallback만 둔다

읽기 순서:

1. logic guide
2. new-metric family index
3. family example 문서
4. contract

metric navigation:

• logic guide: ../rag-bench/knowledge_bases/rag_metric_logic.md
• family index: ../rag-bench/references/metric_definition_examples.md
• coverage/retrieval family: ../rag-bench/references/metric_examples_coverage_retrieval.md
• ranking/placement family: ../rag-bench/references/metric_examples_ranking_placement.md
• context integrity family: ../rag-bench/references/metric_examples_context_integrity.md
• taxonomy: ../rag-bench/references/metric_taxonomy.md
• canonical definitions: ../rag-bench/references/metric_definitions.md
• naming/formula governance: ../rag-bench/knowledge_bases/metric_formula_contract.md

구조 원칙:

• SKILL.md는 링크 중심 네비게이션
• metric_definition_examples.md는 family index
• family 문서는 tags + script/output mapping
• metric_formula_contract.md는 naming/formula governance

핵심 지표 요약

지표	수식 요약	진단 대상
Hit Rate@K	top-K에 정답 하나라도 있으면 1	검색 자체의 성공 여부
ChunkRecall_count@K	gold chunk 중 top-K가 회수한 비율	count-based chunk coverage
ChunkPrecision_count@K	top-K 중 gold chunk 비율	노이즈 수준
MRR	첫 정답의 순위 역수 평균	Reranker 품질
Faithfulness	답변 주장 중 컨텍스트 근거 비율	환각 수준
IC	parent 집중도	context switching / 과집중
CC_adj_lexical	lexical adjacency coherence proxy	인접성 / 흐름
SR_fragmentation_proxy	executable structural fragmentation proxy	parent 내부 연속성

주의:

• strict SR은 canonical contract 지표다.
• 현재 eval-runner bundled metrics가 직접 수집하는 실행 지표는 SR_fragmentation_proxy다.
• CC, SR, RCP, ChunkRecall처럼 variant가 많은 이름은 report key로 단독 사용하지 않는다.

교차 진단 패턴

Recall@k	ChunkRecall_count@k / semantic coverage	진단
낮	Recall_length@k 또는 Recall_claim@k 높음	Large Chunk 또는 coarse coverage
높	Recall_length@k 또는 Recall_claim@k 낮음	Boundary Cut 가능성
높	둘 다 높음	retrieval + coverage 모두 양호
낮	둘 다 낮음	검색 실패 또는 query formulation 문제

파이프라인 병목 진단

DocHit@10 < 0.7   → A1 병목 (임베딩/HyDE)
MRR < 0.5         → A2 병목 (Reranker)
ChunkRecall_count@10 < 0.3 → A0/A3 병목 (chunk_size 또는 절삭)
Judge < 8/15      → LLM 병목 (프롬프트/컨텍스트 구조)
IC = 1.0 부근      → 과집중 가능성
CC_adj_lexical / SR_fragmentation_proxy = 0 → chunk_id / parent 체계 불일치 가능성부터 점검

References

• references/chain_example.yaml chain config 예시. experiment별 boundary_check override 포함.
• references/tmux_cold_start_preflight_prompt.md tmux 기반 cold-start preflight prompt.
• references/tmux_cold_start_metrics_prompt.md tmux 기반 cold-start metrics/report prompt.
• ../rag-bench/knowledge_bases/rag_metric_logic.md 해석·보고용 logic guide.
• ../rag-bench/references/metric_definition_examples.md family index.
• ../rag-bench/references/metric_examples_coverage_retrieval.md coverage/retrieval family.
• ../rag-bench/references/metric_examples_ranking_placement.md ranking/placement family.
• ../rag-bench/references/metric_examples_context_integrity.md context integrity family.
• ../rag-bench/references/metric_taxonomy.md 지표 추상화/계보.
• ../rag-bench/references/metric_definitions.md canonical definitions reference.
• ../rag-bench/knowledge_bases/metric_formula_contract.md naming/formula governance.

Routing Notes

이 스킬을 우선 쓰는 요청:

• "preflight 먼저 돌려줘"
• "chain으로 여러 실험 자동 실행해줘"
• "metrics 5단계 묶어서 돌려줘"
• "경로/형식/인코딩 문제를 실행 전에 잡고 싶어"

이 스킬보다 rag-bench를 우선 쓰는 요청:

• "이 결과 해석해줘"
• "hop별 비교해줘"
• "메트릭 taxonomy 정리해줘"