evalvault 1.65.0__tar.gz → 1.66.0__tar.gz

{evalvault-1.65.0 → evalvault-1.66.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evalvault
-Version: 1.65.0
+Version: 1.66.0
 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
@@ -25,6 +25,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Software Development :: Testing
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
+Requires-Dist: chainlit>=2.9.5
 Requires-Dist: chardet
 Requires-Dist: fastapi>=0.128.0
 Requires-Dist: instructor
@@ -137,12 +138,17 @@ English version? See `README.en.md`.
 ## Quick Links
 
 - 문서 허브: `docs/INDEX.md`
+- CLI 실행 시나리오 가이드: `docs/guides/RAG_CLI_WORKFLOW_TEMPLATES.md`
 - 사용자 가이드: `docs/guides/USER_GUIDE.md`
 - 개발 가이드: `docs/guides/DEV_GUIDE.md`
 - 상태/로드맵: `docs/STATUS.md`, `docs/ROADMAP.md`
 - 개발 백서(설계/운영/품질 기준): `docs/new_whitepaper/INDEX.md`
 - Open RAG Trace: `docs/architecture/open-rag-trace-spec.md`
 
+### 다음 개선 작업 메모
+- 보험 요약 메트릭 확장 계획: `docs/guides/INSURANCE_SUMMARY_METRICS_PLAN.md`
+- Prompt 반복 적용 계획: `docs/guides/repeat_query.md`
+
 ---
 
 ## EvalVault가 해결하는 문제
@@ -470,6 +476,24 @@ npm run dev
 - Ragas 계열: `faithfulness`, `answer_relevancy`, `context_precision`, `context_recall`, `factual_correctness`, `semantic_similarity`
 - 커스텀 예시(도메인): `insurance_term_accuracy`
 
+### 요약 메트릭 설계 근거 (summary_score, summary_faithfulness, entity_preservation)
+
+### 커스텀 메트릭 스냅샷 (평가 방식/과정/결과 기록)
+- 평가 방식/입출력/규칙/구현 파일 해시를 `run.tracker_metadata.custom_metric_snapshot`에 기록합니다.
+- Excel `CustomMetrics` 시트와 Langfuse/Phoenix/MLflow artifact에도 함께 저장됩니다.
+
+- `summary_faithfulness`: 요약의 모든 주장이 컨텍스트에 근거하는지 평가합니다. 환각/왜곡 리스크를 직접적으로 측정합니다.
+- `summary_score`: 컨텍스트 대비 요약의 핵심 정보 보존/간결성 균형을 평가합니다. 정답 요약 단일 기준의 편향을 줄입니다.
+- `entity_preservation`: 금액·기간·조건·면책 등 보험 약관에서 중요한 엔티티가 요약에 유지되는지 측정합니다.
+
+**보험 도메인 특화 근거**
+- 보험 약관에서 치명적인 요소(면책, 자기부담, 한도, 조건 등)를 키워드로 직접 반영하고, 금액/기간/비율 같은 핵심 엔티티를 보존하도록 설계했습니다.
+- 범용 규칙(숫자/기간/금액)과 보험 특화 키워드를 함께 사용하므로, 현재 상태는 “보험 리스크 중심의 약한 도메인 특화”로 보는 것이 정확합니다.
+
+**해석 주의사항**
+- 세 메트릭 모두 `contexts` 품질에 크게 의존합니다. 컨텍스트가 부정확/과도하면 점수가 낮아질 수 있습니다.
+- `summary_score`는 키프레이즈 기반이므로, 표현이 달라지면 점수가 낮게 나올 수 있습니다.
+
 정확한 옵션/운영 레시피는 `docs/guides/USER_GUIDE.md`를 기준으로 최신화합니다.
 
 ---

{evalvault-1.65.0 → evalvault-1.66.0}/README.md

@@ -14,12 +14,17 @@ English version? See `README.en.md`.
 ## Quick Links
 
 - 문서 허브: `docs/INDEX.md`
+- CLI 실행 시나리오 가이드: `docs/guides/RAG_CLI_WORKFLOW_TEMPLATES.md`
 - 사용자 가이드: `docs/guides/USER_GUIDE.md`
 - 개발 가이드: `docs/guides/DEV_GUIDE.md`
 - 상태/로드맵: `docs/STATUS.md`, `docs/ROADMAP.md`
 - 개발 백서(설계/운영/품질 기준): `docs/new_whitepaper/INDEX.md`
 - Open RAG Trace: `docs/architecture/open-rag-trace-spec.md`
 
+### 다음 개선 작업 메모
+- 보험 요약 메트릭 확장 계획: `docs/guides/INSURANCE_SUMMARY_METRICS_PLAN.md`
+- Prompt 반복 적용 계획: `docs/guides/repeat_query.md`
+
 ---
 
 ## EvalVault가 해결하는 문제
@@ -347,6 +352,24 @@ npm run dev
 - Ragas 계열: `faithfulness`, `answer_relevancy`, `context_precision`, `context_recall`, `factual_correctness`, `semantic_similarity`
 - 커스텀 예시(도메인): `insurance_term_accuracy`
 
+### 요약 메트릭 설계 근거 (summary_score, summary_faithfulness, entity_preservation)
+
+### 커스텀 메트릭 스냅샷 (평가 방식/과정/결과 기록)
+- 평가 방식/입출력/규칙/구현 파일 해시를 `run.tracker_metadata.custom_metric_snapshot`에 기록합니다.
+- Excel `CustomMetrics` 시트와 Langfuse/Phoenix/MLflow artifact에도 함께 저장됩니다.
+
+- `summary_faithfulness`: 요약의 모든 주장이 컨텍스트에 근거하는지 평가합니다. 환각/왜곡 리스크를 직접적으로 측정합니다.
+- `summary_score`: 컨텍스트 대비 요약의 핵심 정보 보존/간결성 균형을 평가합니다. 정답 요약 단일 기준의 편향을 줄입니다.
+- `entity_preservation`: 금액·기간·조건·면책 등 보험 약관에서 중요한 엔티티가 요약에 유지되는지 측정합니다.
+
+**보험 도메인 특화 근거**
+- 보험 약관에서 치명적인 요소(면책, 자기부담, 한도, 조건 등)를 키워드로 직접 반영하고, 금액/기간/비율 같은 핵심 엔티티를 보존하도록 설계했습니다.
+- 범용 규칙(숫자/기간/금액)과 보험 특화 키워드를 함께 사용하므로, 현재 상태는 “보험 리스크 중심의 약한 도메인 특화”로 보는 것이 정확합니다.
+
+**해석 주의사항**
+- 세 메트릭 모두 `contexts` 품질에 크게 의존합니다. 컨텍스트가 부정확/과도하면 점수가 낮아질 수 있습니다.
+- `summary_score`는 키프레이즈 기반이므로, 표현이 달라지면 점수가 낮게 나올 수 있습니다.
+
 정확한 옵션/운영 레시피는 `docs/guides/USER_GUIDE.md`를 기준으로 최신화합니다.
 
 ---

evalvault-1.66.0/config/ragas_prompts_override.yaml

@@ -0,0 +1,11 @@
+faithfulness: |
+  당신은 평가자입니다. 아래 CONTEXT를 기준으로 각 STATEMENT가 직접적으로
+  추론 가능한지 판단하세요.
+  - verdict는 반드시 정수 1 또는 0으로만 출력하세요(따옴표 없이).
+  - 1: 컨텍스트에서 직접적으로 지지됨, 0: 지지되지 않음.
+  - JSON 형식으로만 반환하세요.
+
+answer_relevancy: |
+  당신은 평가자입니다. 질문과 답변이 얼마나 관련 있는지 0~1 점수로 평가하세요.
+  - 출력은 숫자 점수와 간단한 근거를 포함해야 합니다.
+  - 질문과 무관한 내용이 많으면 낮은 점수를 부여하세요.

{evalvault-1.65.0 → evalvault-1.66.0}/docs/INDEX.md

@@ -13,16 +13,17 @@
 ## 빠른 링크
 
 - 설치: `getting-started/INSTALLATION.md`
+- CLI 실행 시나리오 가이드: `guides/RAG_CLI_WORKFLOW_TEMPLATES.md`
 - 사용자 가이드(운영 포함): `guides/USER_GUIDE.md`
 - 개발/기여: `guides/DEV_GUIDE.md`
-- CLI→MCP 이식 계획: `guides/CLI_MCP_PLAN.md`
-- Web UI 확장 설계서: `guides/WEBUI_CLI_ROLLOUT_PLAN.md` (1단계 구현 파일 목록 포함)
-- RAGAS 인간 피드백 보정: `guides/RAGAS_HUMAN_FEEDBACK_CALIBRATION_GUIDE.md`
 - 진단 플레이북: `guides/EVALVAULT_DIAGNOSTIC_PLAYBOOK.md` (문제→분석→해석→액션 흐름)
 - RAG 성능 개선 제안서: `guides/RAG_PERFORMANCE_IMPROVEMENT_PROPOSAL.md` (목적/미션·KPI·로드맵)
-- CLI 병렬 기능 설계서: `guides/CLI_PARALLEL_FEATURES_SPEC.md`
+- RAGAS 인간 피드백 보정: `guides/RAGAS_HUMAN_FEEDBACK_CALIBRATION_GUIDE.md`
 - 실행 결과 엑셀 시트 요약: `guides/EVALVAULT_RUN_EXCEL_SHEETS.md`
 - 평가 리포트 템플릿: `templates/eval_report_templates.md`
+- CLI→MCP 이식 계획: `guides/CLI_MCP_PLAN.md`
+- Web UI 확장 설계서: `guides/WEBUI_CLI_ROLLOUT_PLAN.md`
+- 문서 최신화 작업 계획: `guides/DOCS_REFRESH_PLAN.md`
 - 릴리즈 체크리스트: `guides/RELEASE_CHECKLIST.md`
 - 상태 요약: `STATUS.md`
 - 로드맵: `ROADMAP.md`

{evalvault-1.65.0 → evalvault-1.66.0}/docs/ROADMAP.md

@@ -1,6 +1,6 @@
 # EvalVault 로드맵 (Roadmap)
 
-> Last Updated: 2026-01-11
+> Last Updated: 2026-01-18
 
 이 문서는 **"우리가 다음으로 무엇을, 왜 하는가"**를 외부(사용자/기여자) 관점에서 간단히 공유합니다.
 
@@ -19,15 +19,18 @@
 ### P1 (사용성)
 - Web UI에서 핵심 워크플로(Evaluation → History → Reports) 완성도 향상
 - CLI/웹 공통 DB/아티팩트 경로 규약을 문서/UX에 일관되게 노출
+- Run 상세 탭(Staging/Prompts/Gate/Debug)과 분석 실험실 연동 강화
 
 ### P2 (관측성/표준)
 - Open RAG Trace 스펙/샘플을 실제 운영 요구에 맞춰 점진 확장(버전 정책 준수)
 - Collector 구성 및 데이터 보존(artifact 분리, PII 마스킹) 가이드 강화
+- Stage Events 최소 스키마 표준화 및 문서 동기화
 
 ### P3 (성능 개선 로드맵)
 - RAG 성능 개선 제안서 기반으로 KPI/평가 프로토콜/로드맵 정립
 - Retrieval/리랭킹/GraphRAG 실험과 운영 지표 통합
 - 전문가 관점(인지/UX/운영) 기반 개선 루프 고도화
+- 노이즈 저감/ordering_warning 운영 기준 정착
 
 ## 작업 트래킹
 

{evalvault-1.65.0 → evalvault-1.66.0}/docs/STATUS.md

@@ -1,7 +1,7 @@
 # EvalVault 상태 요약 (Status)
 
 > Audience: 사용자 · 개발자 · 운영자
-> Last Updated: 2026-01-11
+> Last Updated: 2026-01-18
 
 EvalVault의 목표는 **RAG 평가/분석/추적을 하나의 Run 단위로 연결**해, 실험→회귀→개선 루프를 빠르게 만드는 것입니다.
 
@@ -14,6 +14,18 @@ EvalVault의 목표는 **RAG 평가/분석/추적을 하나의 Run 단위로 연
 - **Open RAG Trace 표준**: 외부/내부 RAG 시스템을 표준 스키마로 계측/수집
 - **성능 개선 프레임**: `guides/RAG_PERFORMANCE_IMPROVEMENT_PROPOSAL.md`에 KPI/평가/로드맵 정리
 
+## 최근 완료 사항
+
+- **CLI 병렬 명령군 완료**: compare/calibrate-judge/profile-difficulty/regress/artifacts lint/ops snapshot
+- **노이즈 저감 파이프라인 강화**: dataset_preprocessor/evaluator/stage_metric_service 개선
+- **ordering_warning 도입**: 순서 복원/경고 메트릭 + 런북/strict 기준 문서화
+- **Web UI 반영**: RunDetails/CompareRuns/AnalysisLab에 경고 표시 및 런북 링크 추가
+
+## 품질/검증 상태
+
+- Python unit smoke: dataset_preprocessor/evaluator_comprehensive/stage_metric_service PASS
+- Frontend lint/build: eslint PASS, vite build PASS (bundle size warning only)
+
 ## 현재 제약 (투명 공개)
 
 - Web UI의 기능은 CLI의 모든 플래그/옵션을 1:1로 노출하지 않습니다. (고급 옵션은 CLI 우선)

{evalvault-1.65.0 → evalvault-1.66.0}/docs/guides/EVALVAULT_RUN_EXCEL_SHEETS.md

@@ -65,6 +65,22 @@
   - `samples`: 샘플 수
 - 샘플: `avg_score=0.7200`, `pass_rate=0.6`, `samples=30`
 
+## CustomMetrics
+- 컬럼 설명
+  - `schema_version`: 스냅샷 스키마 버전
+  - `metric_name`: 메트릭 이름
+  - `source`: 메트릭 출처 (custom)
+  - `description`: 메트릭 설명
+  - `evaluation_method`: 평가 방식
+  - `inputs`: 입력 필드 목록
+  - `output`: 점수 범위/판정 규칙
+  - `evaluation_process`: 평가 과정 요약
+  - `rules`: 키워드/정규식/가중치 등
+  - `notes`: 도메인 특화/해석 주의사항
+  - `implementation_path`: 구현 파일 경로
+  - `implementation_hash`: 구현 파일 해시
+- 샘플: `metric_name=entity_preservation`, `evaluation_method=rule-based`
+
 ## RunPromptSets
 - 컬럼 설명
   - `run_id`: 실행 ID

{evalvault-1.65.0 → evalvault-1.66.0}/docs/guides/EVALVAULT_WORK_PLAN.md

@@ -1,10 +1,9 @@
-# EvalVault 작업 계획서 (RAGAS/Tracing/Prompt Override)
+# EvalVault 작업 계획서 (Archived)
 
 ## 0) 목적
 
-- RAGAS 평가 → 결과 저장 → Phoenix 트레이싱 → 추가 분석 → 보고서(Markdown)까지 **정상 동작** 확인
-- 외부 로그 API 입력(JSON 가정)을 **RAGAS형/비정형**으로 분기해 분석 수행
-- RAGAS 프롬프트와 시스템 프롬프트를 **분리 오버라이드**하고 실제 실행으로 검증
+- 본 문서는 과거 작업 계획서로 분류되어 보존용으로만 남깁니다.
+- 최신 실행 시나리오는 `docs/guides/RAG_CLI_WORKFLOW_TEMPLATES.md`를 기준으로 합니다.
 
 ## 1) 전제 및 범위
 

evalvault-1.66.0/docs/guides/INSURANCE_SUMMARY_METRICS_PLAN.md

@@ -0,0 +1,152 @@
+# 보험 도메인 요약(Summary) 메트릭 확장 PRD/SDD (EvalVault)
+
+## 1) 목표
+- 보험 상담/약관 요약에 대해 “요약 품질 + 리스크 안내 + 단정 표현 억제”를 평가하는 커스텀 메트릭 4종을 추가한다.
+- 기존 EvalVault 평가 파이프라인(메트릭 레지스트리, CUSTOM_METRIC_MAP, 리포트/엑셀/UI)에 일관되게 통합한다.
+- 메트릭 정의/룰/스냅샷을 명시하여 재현성과 운영 튜닝을 확보한다.
+
+## 2) 범위
+### 포함
+- 신규 메트릭 4종
+  - summary_accuracy
+  - summary_risk_coverage
+  - summary_non_definitive
+  - summary_needs_followup
+- TestCase metadata 확장
+  - summary_tags: list[str]
+  - summary_intent: "agent_notes"
+- 통합 순서
+  1) CLI
+  2) Excel/리포트
+  3) Web UI
+
+### 제외
+- 신규 평가 파이프라인 도입
+- Ragas 요약 메트릭의 의미 변경
+- 합의되지 않은 추가 메트릭 도입
+
+## 3) 현황 및 통일성 기준
+- EvalVault는 custom metric을 evaluator.CUSTOM_METRIC_MAP에 등록하고, registry에서 노출 스펙을 관리한다.
+- summary 메트릭은 CLI/리포트/UI에서 별도 정렬/임계값 기준을 유지한다.
+- TestCase.metadata는 JSON 로더에서 이미 지원되므로, summary_tags/summary_intent는 metadata에 추가하는 방식이 통일적이다.
+
+## 4) 데이터 스키마
+### TestCase.metadata
+- summary_tags: list[str] (선택)
+- summary_intent: "agent_notes" (선택, 내부용 고정)
+
+예시:
+```json
+{
+  "id": "tc-001",
+  "question": "상담 요약 요청",
+  "answer": "요약문 ...",
+  "contexts": ["대화 원문 ..."],
+  "ground_truth": "현업 요약 ...",
+  "metadata": {
+    "summary_intent": "agent_notes",
+    "summary_tags": ["exclusion", "deductible", "limit", "needs_followup"]
+  }
+}
+```
+
+## 5) 메트릭 정의
+### 5.1 summary_accuracy
+- 목적: 요약문 내 핵심 엔티티(금액/기간/조건 등)가 컨텍스트에 근거하는지 평가
+- 입력: answer, contexts
+- 점수: supported_entities / summary_entities
+- 보정 정책:
+  - summary_entities가 비어있고 context_entities가 있으면 0.5
+  - context_entities가 없으면 0.0
+
+### 5.2 summary_risk_coverage
+- 목적: 보험 리스크 항목(면책/감액/자기부담금/한도 등) 누락 여부 평가
+- 입력: answer, metadata.summary_tags
+- 점수: covered_tags / expected_tags
+- expected_tags가 없으면 1.0
+
+### 5.3 summary_non_definitive
+- 목적: 단정 표현(“무조건 지급”, “반드시”)을 억제했는지 평가
+- 입력: answer
+- 점수: 단정 표현이 없으면 1.0, 있으면 0.0
+
+### 5.4 summary_needs_followup
+- 목적: 추가 확인이 필요한 경우 요약에 “추가 확인 필요”를 명시했는지 평가
+- 입력: answer, metadata.summary_tags
+- 규칙:
+  - needs_followup 태그가 있으면 followup 표현 포함 시 1.0, 아니면 0.0
+  - 태그가 없으면 followup 표현이 없을 때 1.0
+
+## 6) 임계값(초기 권장)
+- summary_accuracy: 0.90
+- summary_risk_coverage: 0.90
+- summary_non_definitive: 0.80
+- summary_needs_followup: 0.80
+
+## 7) 룰셋(초기)
+### tag -> keyword 매핑
+- exclusion: 면책, 보장 제외, 지급 불가, exclusion
+- deductible: 자기부담, 본인부담금, deductible, copay
+- limit: 한도, 상한, 최대, limit, cap
+- waiting_period: 면책기간, 대기기간, waiting period
+- condition: 조건, 단서, 다만, condition
+- documents_required: 서류, 진단서, 영수증, documents
+- needs_followup: 확인 필요, 추가 확인, 담당자 확인, 재문의, follow up
+
+### 단정 표현 탐지
+- 무조건, 반드시, 100%, 전액 지급, 확실히, 분명히, always, guaranteed
+
+## 8) 통합 지점 (구현 순서)
+### 8.1 CLI
+- 신규 메트릭 클래스 추가
+- evaluator.CUSTOM_METRIC_MAP 등록
+- metrics.registry에 스펙 추가
+- summary threshold profile 및 SUMMARY_METRIC_ORDER 확장
+
+### 8.2 Excel/리포트
+- custom_metric_snapshot에 신규 메트릭 상세 기록
+- Excel export에서 JSON 컬럼 안전 변환(호환성 보강)
+- 요약 리포트/LLM 리포트에서 summary 메트릭 경고 라인 확장
+
+### 8.3 Web UI
+- SUMMARY_METRICS/thresholds 확장
+- 요약 메트릭 카드/차트/필터 반영
+
+## 9) 리스크/주의사항
+- CSV/Excel 로더는 test_case metadata를 현재 지원하지 않음 (JSON 우선)
+- 단정 표현/리스크 키워드는 표현 다양성으로 과소/과대 탐지 가능
+- summary_non_definitive는 “단정 억제” 점수임을 명확히 표기 필요
+- Excel export는 JSON 컬럼이 섞여있어 변환 실패 가능 → json_columns 강제 변환 유지
+
+## 10) 하이브리드(규칙 + LLM 보정) 설계안
+
+### 10.1 공통 흐름
+1) 규칙 기반 1차 점수 계산
+2) 경계 사례/태그 누락 등 불확실 구간에서만 LLM 보정
+3) 최종 점수 합성
+- 기본: `final = 0.7 * rule + 0.3 * llm`
+- 또는 LLM이 높은 확신을 줄 때만 override
+
+### 10.2 메트릭별 보정 기준
+- `summary_accuracy`
+  - 경계 조건: rule 점수 0.3~0.7, 엔티티 수가 매우 적음
+  - LLM 질문: “요약의 수치/기간/조건이 컨텍스트에 근거하는가?” (0~1)
+- `summary_risk_coverage`
+  - 태그가 없는 경우 LLM이 리스크 항목 존재 여부를 추정 → 가상 태그 생성
+  - LLM 질문: “요약에 면책/감액/자기부담/한도/조건이 포함되었는가?”
+- `summary_non_definitive`
+  - 규칙이 0.0인 경우만 LLM 재판정
+  - LLM 질문: “요약이 사실을 단정적으로 확정하는가?” (0~1)
+- `summary_needs_followup`
+  - needs_followup 태그가 있거나 규칙 판단이 모호할 때만 LLM 사용
+  - LLM 질문: “요약에 추가 확인/재문의 안내가 포함되어 있는가?” (0/1)
+
+### 10.3 운영 가이드
+- LLM 보정은 **경계 사례에만 제한**하여 비용/분산을 줄인다.
+- 프롬프트/모델 버전을 스냅샷에 기록해 회귀를 추적한다.
+- 규칙 기반 점수와 보정 점수를 함께 저장하여 디버깅 가능하게 한다.
+
+## 11) 롤아웃
+1) CLI (메트릭 계산/표시)
+2) Excel/리포트
+3) Web UI

{evalvault-1.65.0 → evalvault-1.66.0}/docs/guides/PROJECT_STATUS_AND_PLAN.md

@@ -1,8 +1,8 @@
-# EvalVault 현재 개발 상황 및 실행 계획
+# EvalVault 개발 상태/실행 계획 (Archived)
 
 ## 목적
-- 현재 개발 현황을 한눈에 요약하고, 목표/골/에픽/작업을 일관된 구조로 정리한다.
-- 진행 상태를 시각적으로 표현해 팀 내 공유/점검을 쉽게 한다.
+- 본 문서는 과거 작업 로그/계획 성격 문서로 분류되어 보존용으로만 남깁니다.
+- 최신 상태는 `docs/STATUS.md`, `docs/ROADMAP.md`, `docs/guides/RAG_PERFORMANCE_IMPLEMENTATION_LOG.md`를 기준으로 합니다.
 
 ---