evalvault 1.71.0__tar.gz → 1.72.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evalvault
-Version: 1.71.0
+Version: 1.72.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

evalvault-1.72.0/docs/guides/CLI_UX_REDESIGN.md

@@ -0,0 +1,50 @@
+# CLI UX 개선 설계서 (비파괴적 개선)
+
+## 목표
+- 기존 동작을 깨지 않고 인지적 부담을 줄인다.
+- 명령/옵션 이름의 일관성을 높여 학습 비용을 낮춘다.
+- 도움말 구조를 개선해 빠른 탐색이 가능하도록 한다.
+
+## 비파괴 원칙
+- 기존 옵션/명령 삭제 금지 (alias 추가만 허용)
+- 기존 출력 포맷, 기본값, 동작 유지
+- 변경은 UX 중심 (help/alias/문서)으로 제한
+
+## 현재 문제 요약 (관측)
+- `run` 옵션 과다로 `--help` 가독성 저하
+- `compare` vs `analyze-compare` 기능 중복 인지 혼란
+- `--analysis-report` vs `--report` 옵션 이름 불일치
+- 단축키 충돌/혼용 (`-v`, `-m`, `--fmt` 등)
+- 도움말 언어 혼재 (한/영 혼용)
+
+## 개선 범위 (1차 적용)
+### 1) 옵션/명령 별칭 추가
+- `run --analysis-report`에 `--report` 별칭 추가
+- `analyze-compare`에 별칭 명령 추가 (예: `compare-analysis`)
+- `--verbose`에 `-V` 별칭 추가 (기존 `-v` 유지)
+
+### 2) 도움말 개선 (텍스트/선택지 명시)
+- `compare --test` 도움말에 지원 선택지 명시
+- `history --limit` 도움말에 기본값 명시
+
+### 3) 도움말 구조 정리 (비파괴)
+- `run` 명령의 `rich_help_panel` 구획 추가/정리
+  - 출력/저장/분석/리트리버/메모리/트래커 등 카테고리 강조
+
+## 구현 계획
+1. `run.py` 옵션 alias/단축키 추가
+2. `analyze.py` 별칭 명령 추가
+3. `compare.py`, `history.py` 도움말 텍스트 개선
+4. 문서 업데이트 (USER_GUIDE, API 문서)
+5. 최소 단위 테스트 실행 (관련 CLI 유닛)
+
+## 검증 계획
+- `uv run pytest tests/unit/test_ci_gate_cli.py::test_ci_gate_invalid_format -v`
+- 변경 범위 관련 CLI 도움말 확인 (수동):
+  - `uv run evalvault run --help`
+  - `uv run evalvault analyze-compare --help`
+  - `uv run evalvault compare --help`
+
+## 비고
+- 장기적으로는 `compare`/`analyze-compare` 통합을 설계하되,
+  1차 적용에서는 alias와 문서 정리로 혼선을 줄인다.

evalvault-1.72.0/docs/guides/WORKLOG_LAST_2_DAYS.md

@@ -0,0 +1,71 @@
+# 최근 2일 작업 정리 및 개발 실행 로그
+
+작성일: 2026-01-27
+범위 기준: git 로그/변경사항 기준 ("지난 2일")
+
+## 1) 지난 2일 작업 요약 (git 기준)
+
+- 커밋 16건 확인 (문서/분석/회귀게이트/오프라인 운영/멀티턴/GraphRAG 등)
+- CLI/분석/회귀게이트 강화 및 오프라인 운영 지원 추가
+- 문서 대규모 확장 (기능 검증 보고서, P1-P4 계획, 실행 계획 등)
+
+### 주요 커밋 하이라이트
+- docs: feature verification report / P1-P4 work plan / INDEX 업데이트
+- chore(ci): 회귀 게이트 자동화
+- feat(analysis): 멀티턴 분석 모듈 및 가이드
+- feat(domain): GraphRAG 지원 파이프라인 강화
+- chore(ops): 오프라인 데이터셋 번들링/오프라인 도커 가이드
+- test: stage events/data loaders 테스트 강화
+
+### 현재 워킹 트리 (핵심)
+- 수정 파일: API/CLI/스토리지/도메인/프론트/문서/테스트 다수
+- 신규 파일: GraphRAG/멀티턴 관련 도메인/포트/어댑터, 회귀 게이트 워크플로, 캘리브레이션 UI, 리포트 산출물 등
+- 브랜치 상태: main 기준 ahead 3, behind 1
+
+## 2) 현재 버전 개선점 검토
+
+### 높은 우선순위
+- API 보고서 생성 로직 미구현: `src/evalvault/adapters/inbound/api/adapter.py`
+- Domain Memory Phase 2 포트 미구현: `src/evalvault/ports/outbound/domain_memory_port.py`
+- Relation Augmenter 포트 미구현: `src/evalvault/ports/outbound/relation_augmenter_port.py`
+
+### 중간 우선순위
+- LLM 토큰 사용량 추적 미구현: `src/evalvault/ports/outbound/llm_port.py`
+- API/CLI 보고서 기능 불균형 (LLM 보고서: API 전용, Markdown/대시보드: CLI 전용)
+- 문서-코드 불일치: `docs/new_whitepaper/07_advanced.md`와 도메인 메모리 미구현
+
+### 낮은 우선순위
+- 보고서 저장/이력 관리(DB) 미활용 (CLI/일부 API 경로)
+- ReportPort 활용 일관성 부족
+
+## 3) 개발 계획 (실행 순서)
+
+1. API 보고서 생성 로직 구현 (Web UI 기능 복원)
+2. 보고서 생성 경로 정리 (API/CLI 기능 차이 문서화)
+3. Domain Memory Phase 2 범위 확정 및 단계별 구현 계획 수립
+4. LLM 토큰 사용량 추적 설계 확정
+
+## 4) 실행 결과 (이번 작업에서 완료)
+
+### 4.1 API 보고서 생성 로직 구현
+
+- 구현 위치: `src/evalvault/adapters/inbound/api/adapter.py`
+- 변경 내용:
+  - 통계/NLP/인과 분석을 수행해 AnalysisBundle 생성
+  - Markdown/HTML 보고서를 생성하도록 연결
+  - LLM 어댑터가 없을 경우 NLP 분석은 자동 비활성화
+
+### 4.2 변경 파일
+
+- `src/evalvault/adapters/inbound/api/adapter.py`
+
+## 5) 검증
+
+- LSP 진단: 실패 (LSP 서버 즉시 종료). 추가 확인 필요.
+- 테스트: 미실행
+
+## 6) 다음 단계 제안
+
+1. API 라우터에 분석 보고서 엔드포인트 추가 (`/api/v1/runs/{run_id}/analysis-report`)
+2. CLI/WEB 보고서 생성 기능 매핑 문서화
+3. Domain Memory Phase 2 구현 범위 합의

evalvault-1.72.0/frontend/e2e/judge-calibration.spec.ts

@@ -0,0 +1,116 @@
+import { test, expect } from "@playwright/test";
+
+const runFixture = [
+    {
+        run_id: "run_12345678",
+        dataset_name: "demo",
+        model_name: "gpt-5-mini",
+        pass_rate: 0.8,
+        total_test_cases: 10,
+        passed_test_cases: 8,
+        started_at: "2026-01-27T00:00:00Z",
+        finished_at: null,
+        metrics_evaluated: ["faithfulness", "answer_relevancy"],
+        total_cost_usd: null,
+        phoenix_precision: null,
+        phoenix_drift: null,
+        phoenix_experiment_url: null,
+    },
+];
+
+const historyFixture = [
+    {
+        calibration_id: "judge_calibration_run_12345678_20260127_000001",
+        run_id: "run_12345678",
+        labels_source: "feedback",
+        method: "isotonic",
+        metrics: ["faithfulness"],
+        holdout_ratio: 0.2,
+        seed: 42,
+        total_labels: 20,
+        total_samples: 30,
+        gate_passed: true,
+        gate_threshold: 0.6,
+        created_at: "2026-01-27T00:00:01Z",
+    },
+];
+
+const calibrationResponse = {
+    calibration_id: "judge_calibration_run_12345678_20260127_000002",
+    status: "ok",
+    started_at: "2026-01-27T00:00:02Z",
+    finished_at: "2026-01-27T00:00:03Z",
+    duration_ms: 1200,
+    artifacts: { dir: "reports/calibration/artifacts/judge_calibration_run_12345678_20260127_000002" },
+    summary: {
+        calibration_id: "judge_calibration_run_12345678_20260127_000002",
+        run_id: "run_12345678",
+        labels_source: "feedback",
+        method: "isotonic",
+        metrics: ["faithfulness"],
+        holdout_ratio: 0.2,
+        seed: 42,
+        total_labels: 20,
+        total_samples: 30,
+        gate_passed: true,
+        gate_threshold: 0.6,
+        notes: [],
+        created_at: "2026-01-27T00:00:02Z",
+    },
+    metrics: [
+        {
+            metric: "faithfulness",
+            method: "isotonic",
+            sample_count: 30,
+            label_count: 20,
+            mae: 0.12,
+            pearson: 0.71,
+            spearman: 0.69,
+            temperature: null,
+            parameters: {},
+            gate_passed: true,
+            warning: null,
+        },
+    ],
+    case_results: {
+        faithfulness: [
+            {
+                test_case_id: "tc-1",
+                raw_score: 0.62,
+                calibrated_score: 0.67,
+                label: 0.7,
+                label_source: "feedback",
+            },
+        ],
+    },
+    warnings: [],
+};
+
+test("judge calibration page renders and runs", async ({ page }) => {
+    await page.route("**/api/v1/runs/", async (route) => {
+        await route.fulfill({ json: runFixture });
+    });
+    await page.route("**/api/v1/calibration/judge/history?limit=20", async (route) => {
+        await route.fulfill({ json: historyFixture });
+    });
+    await page.route("**/api/v1/calibration/judge", async (route) => {
+        const request = route.request();
+        if (request.method() === "POST") {
+            await route.fulfill({ json: calibrationResponse });
+            return;
+        }
+        await route.fallback();
+    });
+
+    await page.goto("/calibration");
+    await expect(page.getByRole("heading", { name: "Judge Calibration" })).toBeVisible();
+    await expect(page.getByText("히스토리")).toBeVisible();
+
+    await page.getByRole("combobox").first().selectOption({ label: "demo · run_12345678" });
+    await expect(page.getByRole("button", { name: "faithfulness" })).toBeVisible();
+
+    await page.getByRole("button", { name: "Judge 보정 실행" }).click();
+    await expect(page.getByText("결과 요약")).toBeVisible();
+    await expect(page.getByText("30")).toBeVisible();
+    await expect(page.getByText("faithfulness")).toBeVisible();
+});