evalvault 1.72.0__tar.gz → 1.72.1__tar.gz

{evalvault-1.72.0 → evalvault-1.72.1}/.gitignore

@@ -56,6 +56,10 @@ reports/*.xml
 reports/*.json
 reports/analysis/
 reports/analysis/**
+reports/comparison/
+reports/comparison/**
+reports/presentation_materials_*.md
+reports/ralph_loop_briefing.md
 reports/assets/
 reports/api-docs/
 !reports/.gitkeep
@@ -67,6 +71,9 @@ data/e2e_results/
 # HuggingFace tokenizer cache (lm-eval benchmarks)
 data/tokenizers/
 
+# Local raw data (should not be versioned)
+data/raw/
+
 # Local state data (should not be versioned)
 data/cache/
 data/db/

{evalvault-1.72.0 → evalvault-1.72.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evalvault
-Version: 1.72.0
+Version: 1.72.1
 Summary: RAG evaluation system using Ragas with Phoenix/Langfuse tracing
 Project-URL: Homepage, https://github.com/ntts9990/EvalVault
 Project-URL: Documentation, https://github.com/ntts9990/EvalVault#readme

{evalvault-1.72.0 → evalvault-1.72.1}/docs/INDEX.md

@@ -34,6 +34,7 @@
 - 상태 요약: `STATUS.md`
 - 로드맵: `ROADMAP.md`
 - 개발 백서(설계/운영/품질 기준): `new_whitepaper/INDEX.md`
+- 교과서형 총정리(handbook): `handbook/INDEX.md`
 
 ---
 

evalvault-1.72.1/docs/handbook/CHAPTERS/00_overview.md

@@ -0,0 +1,106 @@
+# 00. Overview
+
+> 내부용 본편(상세). 외부 공개 요약은 `docs/handbook/EXTERNAL.md`에 별도 작성.
+
+---
+
+## TL;DR
+
+- EvalVault는 **평가(Evaluation) → 분석(Analysis) → 비교(Compare) → 개선 루프**를 `run_id` 단위로 연결한다.
+- 실행 결과는 DB와 아티팩트로 남아 재현 가능하며, Web UI는 같은 DB를 바라볼 때 즉시 이어진다.
+- 관측(Phoenix/Langfuse), 표준(Open RAG Trace), 학습(Domain Memory), 분석 파이프라인(DAG)은 **옵션화**되어 필요할 때만 켠다.
+
+## 미션(1문장)
+
+RAG 시스템의 변경이 **진짜 개선인지**를 데이터셋·메트릭·(선택)트레이싱 관점에서 **재현 가능하게** 검증하고, 왜/어디서 깨지는지까지 설명 가능한 워크플로를 제공한다.
+
+## 대상 사용자(3)
+
+1) RAG를 운영하는 ML/플랫폼/백엔드 엔지니어
+2) 품질/회귀를 책임지는 QA/PM
+3) 반복 평가/벤치마크가 필요한 외부 사용자(컨설팅/솔루션/고객사 PoC)
+
+## 핵심 가치(3)
+
+1) 재현성: run 단위로 평가/분석/아티팩트/트레이스를 묶고 비교할 수 있다.
+2) 진단 가능성: 점수 변화의 원인을 모듈/스테이지/메트릭 레벨로 추적할 수 있다.
+3) 운영 옵션화: Phoenix/Langfuse/MLflow 같은 관측은 필요할 때만 켠다.
+
+## Non-goals(3)
+
+1) RAG 시스템 자체를 대신 구현/호스팅하지 않는다.
+2) 단일 점수 하나로 모든 품질을 대체하지 않는다(다중 메트릭/근거 기반).
+3) 특정 벤더/모델에 종속되지 않는다(OpenAI/Ollama/vLLM 등 옵션화).
+
+---
+
+## 핵심 개념 요약(공통 언어)
+
+- **run_id**: 평가 실행의 단일 식별자. 평가/분석/아티팩트/트레이스가 이 키로 묶인다.
+- **Artifacts**: 요약 리포트와 모듈별 원본 결과를 분리 저장한다.
+- **Stages**: 입력/검색/출력 단계를 이벤트와 메트릭으로 남겨 원인 추적을 가능하게 한다.
+- **Profiles**: `config/models.yaml`과 `.env`로 모델/임베딩을 바꾼다.
+- **Analysis Pipeline**: 의도 기반 DAG로 “왜”를 설명하는 분석을 실행한다.
+
+---
+
+## 최소 실행 시나리오(내부 개발자 기준)
+
+```bash
+uv run evalvault run --mode simple tests/fixtures/e2e/insurance_qa_korean.json \
+  --metrics faithfulness,answer_relevancy \
+  --profile dev \
+  --db data/db/evalvault.db \
+  --auto-analyze
+```
+
+이 실행으로 생성되는 대표 산출물:
+
+- 요약 JSON: `reports/analysis/analysis_<RUN_ID>.json`
+- 보고서(Markdown): `reports/analysis/analysis_<RUN_ID>.md`
+- 아티팩트 인덱스: `reports/analysis/artifacts/analysis_<RUN_ID>/index.json`
+
+---
+
+## CLI ↔ Web UI 연결
+
+```bash
+# Terminal 1
+uv run evalvault serve-api --reload
+
+# Terminal 2
+cd frontend
+npm install
+npm run dev
+```
+
+- CLI와 Web UI가 **같은 DB 경로**를 바라보면, CLI 실행 결과가 Web UI에 바로 노출된다.
+
+---
+
+## 문서 지도(다음으로 어디를 읽을지)
+
+- 구조/경계: `01_architecture.md`
+- 데이터/메트릭: `02_data_and_metrics.md`
+- 실행 흐름: `03_workflows.md`
+- 운영 런북: `04_operations.md`
+- 보안 경계: `05_security.md`
+- 품질/테스트: `06_quality_and_testing.md`
+- UX/제품: `07_ux_and_product.md`
+- 로드맵: `08_roadmap.md`
+
+## 근거 링크(3+)
+
+- 프로젝트 정의/핵심 개념: `../../README.md`
+- 상태/제약: `../STATUS.md`
+- 로드맵: `../ROADMAP.md`
+- 내부 백서(개요): `../new_whitepaper/01_overview.md`
+- 문서 운영 원칙: `../INDEX.md`
+
+---
+
+## 전문가 관점 체크리스트
+
+- [ ] run_id/아티팩트/트레이스가 하나의 흐름으로 설명되는가
+- [ ] 최소 실행 시나리오가 재현 가능한가
+- [ ] 옵션 기능(Phoenix/Langfuse/Domain Memory/DAG)이 “필수”처럼 서술되지 않는가

evalvault-1.72.1/docs/handbook/CHAPTERS/01_architecture.md

@@ -0,0 +1,50 @@
+# 01. Architecture
+
+## 목표
+
+EvalVault의 헥사고날(Ports & Adapters) 구조를 이해하고, 어떤 경계를 유지해야 확장/교체가 안전한지 정리한다.
+
+## 설계 원칙
+
+- SSoT는 `docs/new_whitepaper/02_architecture.md`이며, 구현은 문서에 맞춘다.
+- 도메인은 순수하게 유지하고, 인프라 의존은 포트/어댑터로 분리한다.
+- 어댑터는 포트(계약)에 맞춰 교체 가능해야 한다.
+- 설정과 런타임 선택은 코드가 아니라 프로필/환경 변수로 처리한다.
+
+## 코드 지도(핵심 경로)
+
+- 도메인 엔티티/서비스: `src/evalvault/domain/`
+- 포트(계약): `src/evalvault/ports/`
+- 어댑터(통합): `src/evalvault/adapters/`
+- 런타임 설정/프로필: `src/evalvault/config/`, `config/models.yaml`
+
+## 경계와 의존성 규칙
+
+- 도메인 -> 포트는 의존 가능, 포트 -> 도메인은 인터페이스만 유지
+- 어댑터 -> 포트 의존, 어댑터 -> 도메인 직접 의존은 최소화
+- 구성/프로필은 런타임에 주입하며 하드코딩 금지
+
+## 확장/교체 가이드
+
+1) 포트 정의: `src/evalvault/ports/outbound/` 또는 `src/evalvault/ports/inbound/`
+2) 어댑터 구현: `src/evalvault/adapters/outbound/` 또는 `src/evalvault/adapters/inbound/`
+3) 설정 연결: `src/evalvault/config/` 및 `config/models.yaml`
+
+예시 확장 포인트:
+- LLM 어댑터: `src/evalvault/adapters/outbound/llm/`
+- 트래커/관측: `src/evalvault/adapters/outbound/tracker/`
+- 스토리지: `src/evalvault/adapters/outbound/storage/`
+- 아티팩트 FS: `src/evalvault/adapters/outbound/artifact_fs.py`
+- 분석 파이프라인: `src/evalvault/adapters/outbound/analysis/`
+
+## 아키텍처 흐름(요약)
+
+1) CLI/API 입력 -> 도메인 서비스 호출
+2) 도메인 서비스 -> 포트를 통해 LLM/저장소/트래커 접근
+3) 실행 결과 -> run_id 기준 저장 및 분석/리포트로 연결
+
+## 참고(근거)
+
+- 내부 백서(SSoT): `../new_whitepaper/02_architecture.md`
+- 아키텍처/표준 관련: `../new_whitepaper/13_standards.md`
+- 포트/어댑터 문서: `../api/ports/inbound.md`, `../api/adapters/inbound.md`, `../api/adapters/outbound.md`

evalvault-1.72.1/docs/handbook/CHAPTERS/02_data_and_metrics.md

@@ -0,0 +1,74 @@
+# 02. Data & Metrics
+
+## 목표
+
+데이터셋 포맷, 메트릭, 임계값(threshold), 산출물(artifacts)이 어떻게 연결되는지 이해한다.
+
+## 데이터셋 스키마
+
+- 표준 스키마: `../../src/evalvault/domain/entities/dataset.py`
+- 템플릿: `../templates/` 및 `../../dataset_templates/`
+
+핵심 필드:
+- `test_cases[].question`, `test_cases[].answer`, `test_cases[].contexts`
+- 선택 필드: `test_cases[].ground_truth`, `test_cases[].metadata`
+- 데이터셋 전체 `thresholds`: 메트릭별 합격 기준
+
+샘플 데이터:
+- `../../tests/fixtures/sample_dataset.json`
+- `../../tests/fixtures/e2e/insurance_qa_korean.json`
+
+예시 명령:
+- `uv run evalvault run tests/fixtures/e2e/insurance_qa_korean.json --metrics faithfulness --profile dev --db data/db/evalvault.db --auto-analyze`
+
+## 임계값(Threshold) 처리
+
+우선순위(높음 -> 낮음):
+1) CLI override (`--thresholds`)
+2) Dataset `thresholds`
+3) 프로필 기본값 (`threshold_profiles.py`)
+4) 기본 fallback (도메인 서비스)
+
+관련 파일:
+- 프로필: `../../src/evalvault/domain/services/threshold_profiles.py`
+- CSV/Excel threshold 컬럼 매핑: `../../src/evalvault/adapters/outbound/dataset/thresholds.py`
+- 결과 엔티티: `../../src/evalvault/domain/entities/result.py`
+
+## 메트릭 체계
+
+- 레지스트리: `../../src/evalvault/domain/metrics/registry.py`
+- 메트릭 API 문서: `../api/domain/metrics.md`
+- 요약/도메인 메트릭: `../../src/evalvault/domain/metrics/`
+
+구성 차원:
+- source: ragas/custom
+- category: qa/summary/retrieval/domain
+- requirement: ground_truth/embeddings 여부
+
+예시:
+- QA: faithfulness, answer_relevancy, context_precision
+- Summary: summary_score, summary_faithfulness, entity_preservation
+- Retrieval: mrr, ndcg, hit_rate
+
+## 산출물(Artifacts)와 index.json
+
+분석 파이프라인은 `artifacts/` 아래에 노드별 JSON과 `index.json`을 생성한다.
+
+관련 파일:
+- 아티팩트 IO: `../../src/evalvault/adapters/inbound/cli/utils/analysis_io.py`
+- FS 포트: `../../src/evalvault/ports/outbound/artifact_fs_port.py`
+- FS 구현: `../../src/evalvault/adapters/outbound/artifact_fs.py`
+- 아티팩트 린트: `../../src/evalvault/domain/services/artifact_lint_service.py`
+
+## Excel/리포트
+
+- Excel export 스펙: `../guides/EVALVAULT_RUN_EXCEL_SHEETS.md`
+- DB export 구현: `../../src/evalvault/adapters/outbound/storage/base_sql.py`
+- 보고서 템플릿: `../templates/eval_report_templates.md`
+
+## 참고 경로
+
+- 사용자 가이드: `../guides/USER_GUIDE.md`
+- CLI 워크플로우: `../guides/RAG_CLI_WORKFLOW_TEMPLATES.md`
+- 도메인 엔티티: `../../src/evalvault/domain/entities/`
+- 메트릭 구현: `../../src/evalvault/domain/metrics/`

evalvault-1.72.1/docs/handbook/CHAPTERS/03_workflows.md

@@ -0,0 +1,58 @@
+# 03. Workflows
+
+## 목표
+
+EvalVault의 주요 실행 흐름(평가→분석→비교→리포트)을 CLI/Web UI 관점에서 이해한다.
+
+## 기본 실행 흐름
+
+1) `evalvault run`으로 평가 실행
+2) 결과를 DB/run_id로 저장
+3) `--auto-analyze` 또는 `evalvault analyze`로 분석/리포트 생성
+4) `history`/`compare`/`analyze-compare`로 재현 가능한 비교
+
+핵심 키:
+- `run_id`: 평가/분석/아티팩트가 묶이는 단일 식별자
+- `reports/analysis/artifacts/analysis_<RUN_ID>/index.json`: 분석 근거 인덱스
+
+## CLI 중심 워크플로우
+
+평가 실행:
+- `evalvault run <DATASET> --metrics ... --profile dev --db data/db/evalvault.db --auto-analyze`
+
+분석:
+- `evalvault analyze <RUN_ID> --profile dev --db data/db/evalvault.db --nlp --causal --playbook`
+- `evalvault pipeline analyze "<query>" --run-id <RUN_ID> --profile dev --db data/db/evalvault.db`
+
+비교:
+- `evalvault compare <RUN_A> <RUN_B> --profile dev --db data/db/evalvault.db`
+- `evalvault analyze-compare <RUN_A> <RUN_B> --profile dev --db data/db/evalvault.db --test t-test|mann-whitney`
+
+아티팩트/검증:
+- `evalvault artifacts lint reports/analysis/artifacts/analysis_<RUN_ID>`
+
+## 분석 파이프라인 구조
+
+- 엔티티/의도: `../../src/evalvault/domain/entities/analysis_pipeline.py`
+- 템플릿 레지스트리: `../../src/evalvault/domain/services/pipeline_template_registry.py`
+- 오케스트레이션: `../../src/evalvault/domain/services/pipeline_orchestrator.py`
+- 모듈 등록: `../../src/evalvault/adapters/outbound/analysis/pipeline_factory.py`
+- CLI 진입점: `../../src/evalvault/adapters/inbound/cli/commands/pipeline.py`
+
+## Web UI 연동 흐름
+
+- Web UI는 동일 DB를 사용하며 `run_id`로 CLI와 동기화된다.
+- 주요 API:
+  - `GET /api/v1/runs/{run_id}`
+  - `GET /api/v1/runs/{run_id}/report`
+  - `GET /api/v1/runs/{run_id}/analysis-report`
+  - `GET /api/v1/runs/{run_id}/dashboard`
+
+## 참고
+
+- 사용자 가이드: `../guides/USER_GUIDE.md`
+- 워크플로우 템플릿: `../guides/RAG_CLI_WORKFLOW_TEMPLATES.md`
+- 진단 플레이북: `../guides/EVALVAULT_DIAGNOSTIC_PLAYBOOK.md`
+- 데이터 흐름 백서: `../new_whitepaper/03_data_flow.md`
+- API/웹: `../../src/evalvault/adapters/inbound/api/`
+- CLI: `../../src/evalvault/adapters/inbound/cli/`

evalvault-1.72.1/docs/handbook/CHAPTERS/04_operations.md

@@ -0,0 +1,67 @@
+# 04. Operations
+
+## 목표
+
+프로필/설정, 실행 환경(로컬/도커), 관측 옵션(Phoenix/Langfuse) 등을 운영 관점에서 정리한다.
+
+## 프로필/설정
+
+- 프로필 정의: `../../config/models.yaml`
+- 런타임 설정: `../../src/evalvault/config/settings.py`
+- 환경 템플릿: `../../.env.example`, `../../.env.offline.example`
+
+운영 기본 원칙:
+- 프로필과 시크릿은 분리한다 (모델 정의는 git, 시크릿은 env).
+- `EVALVAULT_PROFILE`로 런타임 구성을 고정한다.
+
+## 실행 환경
+
+로컬:
+- 설치 가이드: `../getting-started/INSTALLATION.md`
+- API 서버: `uv run evalvault serve-api --reload`
+- Web UI: `frontend`에서 `npm run dev`
+
+예시 명령:
+- `cp .env.example .env`
+- `uv sync --extra dev`
+- `EVALVAULT_PROFILE=dev uv run evalvault serve-api --reload`
+- `cd frontend && npm install && npm run dev`
+
+도커:
+- 기본 스택: `../../docker-compose.yml`
+- 오프라인 스택: `../../docker-compose.offline.yml`
+- Langfuse 스택: `../../docker-compose.langfuse.yml`
+- Phoenix + OTel: `../../docker-compose.phoenix.yaml`
+
+오프라인 운영:
+- 이미지 export/import: `../../scripts/offline/`
+- 오프라인 가이드: `../guides/OFFLINE_DOCKER.md`
+
+## 관측/트레이싱
+
+옵션 구성:
+- Phoenix 추적: `../../src/evalvault/adapters/outbound/tracker/phoenix_adapter.py`
+- Langfuse 추적: `../../src/evalvault/adapters/outbound/tracker/langfuse_adapter.py`
+- MLflow 추적: `../../src/evalvault/adapters/outbound/tracker/mlflow_adapter.py`
+
+스펙/수집:
+- Open RAG Trace 스펙: `../architecture/open-rag-trace-spec.md`
+- Collector: `../architecture/open-rag-trace-collector.md`
+- 샘플: `../guides/OPEN_RAG_TRACE_SAMPLES.md`
+
+관련 스크립트:
+- OTel Collector 설정: `../../scripts/dev/otel-collector-config.yaml`
+- Phoenix 모니터링: `../../scripts/ops/phoenix_watch.py`
+
+## 운영 점검 체크리스트
+
+- `run_id` 기준으로 DB/아티팩트/트레이스를 교차 확인한다.
+- `reports/analysis/artifacts/analysis_<RUN_ID>/index.json`로 분석 근거를 찾는다.
+- `evalvault ops snapshot`으로 실행 환경을 기록한다.
+- Web UI/CLI가 같은 DB를 바라보는지 확인한다.
+
+## 참고
+
+- 운영 런북(SSoT): `../new_whitepaper/12_operations.md`
+- 오프라인 가이드: `../guides/OFFLINE_DOCKER.md`
+- 설정 API: `../api/config.md`

evalvault-1.72.1/docs/handbook/CHAPTERS/05_security.md

@@ -0,0 +1,46 @@
+# 05. Security
+
+## 목표
+
+시크릿/키/민감 데이터의 취급 원칙과 외부 공개 요약본의 경계 규칙을 고정한다.
+
+## 기본 원칙
+
+- 시크릿은 `.env`/환경변수로 관리하고, git 커밋 대상이 아니다.
+- 외부 공개 요약본(`../EXTERNAL.md`)에는 내부 경로/운영 절차/실데이터/수치를 포함하지 않는다.
+
+## 시크릿 관리
+
+- `secret://` 참조 지원: `../../src/evalvault/config/secret_manager.py`
+- 런타임 해석/검증: `../../src/evalvault/config/settings.py`
+- 환경 템플릿: `../../.env.example`
+
+## API 인증/토큰
+
+- API 토큰 인증: `../../src/evalvault/adapters/inbound/api/main.py`
+- 지식 API read/write 토큰: `../../src/evalvault/adapters/inbound/api/routers/knowledge.py`
+- MCP 토큰: `../../src/evalvault/adapters/inbound/api/routers/mcp.py`
+
+## 로깅/PII 마스킹
+
+- 로그 정제/PII 마스킹: `../../src/evalvault/adapters/outbound/tracker/log_sanitizer.py`
+- Phoenix/Langfuse/MLflow 트래커에서 공통 적용
+
+## 운영 스냅샷/레덕션
+
+- 환경 스냅샷 레덕션: `../../src/evalvault/domain/services/ops_snapshot_service.py`
+- CLI: `evalvault ops snapshot --redact ...`
+
+예시 명령:
+- `uv run evalvault ops snapshot --redact OPENAI_API_KEY --redact LANGFUSE_SECRET_KEY --redact DATABASE_URL`
+
+## 구성 보안
+
+- CORS/프로덕션 검증: `../../src/evalvault/config/settings.py`
+- Langfuse compose 시크릿 교체: `../../docker-compose.langfuse.yml`
+
+## 참고
+
+- 보안 문서: `../../SECURITY.md`
+- 내부 백서: `../new_whitepaper/11_security.md`
+- 보안 감사 로그: `../security_audit_worklog.md`

evalvault-1.72.1/docs/handbook/CHAPTERS/06_quality_and_testing.md

@@ -0,0 +1,45 @@
+# 06. Quality & Testing
+
+## 목표
+
+테스트/회귀 게이트/품질 기준을 이해하고, 변경이 실제 개선인지 검증하는 방법을 정리한다.
+
+## 품질 게이트 개요
+
+- CI 기본: `../../.github/workflows/ci.yml`
+- 회귀 게이트: `../../.github/workflows/regression-gate.yml`
+- 회귀 실행 스크립트: `../../scripts/ci/run_regression_gate.py`
+
+## 테스트 구성
+
+- pytest/ruff 설정: `../../pyproject.toml`
+- 유닛 테스트: `../../tests/unit/`
+- 통합 테스트: `../../tests/integration/`
+- E2E 시나리오: `../../tests/integration/test_e2e_scenarios.py`
+
+## 회귀 게이트 설정
+
+- 설정 파일: `../../config/regressions/ci.json`, `../../config/regressions/default.json`, `../../config/regressions/ux.json`
+- 서비스 로직: `../../src/evalvault/domain/services/regression_gate_service.py`
+- 러너: `../../src/evalvault/scripts/regression_runner.py`
+
+## 표준 명령
+
+테스트:
+- `uv run pytest tests -v`
+- `uv run pytest --cov=src --cov-report=term`
+
+린트/포맷:
+- `uv run ruff check src/ tests/`
+- `uv run ruff format src/ tests/`
+
+회귀 게이트:
+- `uv run python scripts/ci/run_regression_gate.py --config config/regressions/ci.json --format text`
+
+## 참고
+
+- 개발 가이드: `../guides/DEV_GUIDE.md`
+- 회귀 게이트: `../guides/CI_REGRESSION_GATE.md`
+- 릴리즈 체크리스트: `../guides/RELEASE_CHECKLIST.md`
+- 품질 백서: `../new_whitepaper/09_quality.md`
+- 테스트: `../../tests/`

evalvault-1.72.1/docs/handbook/CHAPTERS/07_ux_and_product.md

@@ -0,0 +1,56 @@
+# 07. UX & Product
+
+## 목표
+
+사용자 관점(제품)에서 EvalVault의 경험을 정리하고, Web UI/CLI의 의도와 사용 흐름을 통합한다.
+
+## 제품 관점 요약
+
+- 기본 사용자 흐름은 `run_id`를 중심으로 평가→분석→비교가 연결된다.
+- Web UI는 CLI의 핵심 워크플로를 시각적으로 재구성한다.
+
+## CLI <-> Web UI 매핑
+
+- 실행 목록: `history` -> Web UI 실행 리스트
+- 분석 실험실: `analyze`, `analyze-compare`, `pipeline` -> 분석 페이지
+- 비교 화면: `compare`, `analyze-compare` -> 비교 페이지
+- 산출물 확인: `artifacts lint`, `report` -> 리포트/아티팩트 뷰
+
+예시 흐름:
+- CLI 실행: `uv run evalvault run tests/fixtures/e2e/insurance_qa_korean.json --metrics faithfulness --profile dev --db data/db/evalvault.db --auto-analyze`
+- Web UI 확인: `http://localhost:5173` -> Dashboard -> Run Details -> Report/Dashboard
+
+## Web UI 범위
+
+- 계획/롤아웃: `../guides/WEBUI_CLI_ROLLOUT_PLAN.md`
+- 분석 이관: `../web_ui_analysis_migration_plan.md`
+- 프론트엔드 구현: `../../frontend/src/`
+
+주요 위치:
+- 페이지: `../../frontend/src/pages/`
+- 컴포넌트: `../../frontend/src/components/`
+- API 연동: `../../frontend/src/services/api.ts`
+
+대표 페이지:
+- Dashboard: 실행 리스트/필터/요약
+- Evaluation Studio: 실행 설정/프리셋
+- Analysis Lab: 인텐트 기반 분석 실행
+- Compare Runs: A/B 비교 및 메트릭 변화
+- Settings: 프로필/DB 경로 설정
+
+## CLI 전용 기능(현 상태)
+
+- Web UI는 `top_k`가 고정되어 있으며 고급 조정은 CLI/API 필요
+- 데이터셋/실험 업로드 및 프롬프트 매니페스트는 CLI 우선
+
+## CLI UX 개선 포인트
+
+- 비교 명령 중복 정리: `../guides/CLI_UX_REDESIGN.md`
+- 도움말/별칭 정비: `compare`/`analyze-compare`
+
+## 참고
+
+- Web UI 계획/확장: `../guides/WEBUI_CLI_ROLLOUT_PLAN.md`
+- CLI UX 개선: `../guides/CLI_UX_REDESIGN.md`
+- 사용자 가이드: `../guides/USER_GUIDE.md`
+- 프론트엔드: `../../frontend/src/`

evalvault-1.72.1/docs/handbook/CHAPTERS/08_roadmap.md

@@ -0,0 +1,25 @@
+# 08. Roadmap
+
+## 목표
+
+현재 로드맵을 요약하고, handbook 작성 과정에서 도출된 목적/우선순위 재조정 근거를 연결한다.
+
+## 우선순위 요약(P0-P3)
+
+- P0 (안정성/운영): 프로필 검증, CI/테스트 안정화, 기본 운영 안전장치
+- P1 (사용성): Web UI 핵심 워크플로, CLI/웹 공통 규약
+- P2 (관측성/표준): Open RAG Trace, Stage Events/Collector
+- P3 (성능 개선): Retrieval/리랭킹/GraphRAG 개선
+
+## 실행 근거
+
+- 상태 요약: `../STATUS.md`
+- 공식 로드맵: `../ROADMAP.md`
+- 백서 로드맵: `../new_whitepaper/14_roadmap.md`
+- 재조정 근거(부록): `../appendix-roadmap.md`
+
+## 실행 기록/계획
+
+- 실행 보고서: `../guides/P0_P3_EXECUTION_REPORT.md`
+- 작업 계획: `../guides/P1_P4_WORK_PLAN.md`
+- 다음 단계: `../guides/NEXT_STEPS_EXECUTION_PLAN.md`

evalvault-1.72.1/docs/handbook/EXTERNAL.md

@@ -0,0 +1,22 @@
+# EvalVault Handbook (External Summary)
+
+> 외부 공개용 요약본입니다. 내부 경로/운영 절차/실데이터/수치/시크릿은 포함하지 않습니다.
+
+## EvalVault가 하는 일
+
+EvalVault는 RAG(Retrieval-Augmented Generation) 시스템을 대상으로,
+"변경이 진짜 개선인지"를 데이터셋과 메트릭으로 재현 가능하게 검증하고
+결과를 이해/비교/공유할 수 있도록 돕는 평가·분석 워크플로 도구입니다.
+
+## 핵심 흐름
+
+1) 데이터셋 준비
+2) 메트릭 평가 실행
+3) 결과 요약 및 비교
+4) 문제 원인 분석(선택)
+
+## 문서
+
+- 내부 상세 handbook: `INDEX.md`
+- 사용자/운영 가이드: `../guides/USER_GUIDE.md`
+- 상태/로드맵: `../STATUS.md`, `../ROADMAP.md`

evalvault-1.72.1/docs/handbook/INDEX.md

@@ -0,0 +1,26 @@
+# EvalVault Handbook (교과서형 총정리)
+
+> 본편은 내부 독자 기준(상세)으로 작성하고, 외부 공개 요약은 `docs/handbook/EXTERNAL.md`로 분리합니다.
+
+---
+
+## 목차
+
+### 본편 (CHAPTERS)
+
+1) `CHAPTERS/00_overview.md`
+2) `CHAPTERS/01_architecture.md`
+3) `CHAPTERS/02_data_and_metrics.md`
+4) `CHAPTERS/03_workflows.md`
+5) `CHAPTERS/04_operations.md`
+6) `CHAPTERS/05_security.md`
+7) `CHAPTERS/06_quality_and_testing.md`
+8) `CHAPTERS/07_ux_and_product.md`
+9) `CHAPTERS/08_roadmap.md`
+
+### 부록 (Appendices)
+
+- `appendix-file-inventory.md` (전수 인벤토리 + 정독 증거)
+- `appendix-taxonomy.md` (문서/백서 분류 + 중복/갭 감사)
+- `appendix-roadmap.md` (목적/로드맵 재조정 근거)
+- `appendix-coverage-matrix.md` (파일-챕터 매핑)