evalvault 1.60.0__tar.gz → 1.62.0__tar.gz

{evalvault-1.60.0 → evalvault-1.62.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evalvault
-Version: 1.60.0
+Version: 1.62.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
@@ -46,6 +46,7 @@ Requires-Dist: uvicorn>=0.40.0
 Requires-Dist: xlrd
 Provides-Extra: analysis
 Requires-Dist: scikit-learn>=1.3.0; extra == 'analysis'
+Requires-Dist: xgboost>=2.0.0; extra == 'analysis'
 Provides-Extra: anthropic
 Requires-Dist: anthropic; extra == 'anthropic'
 Requires-Dist: langchain-anthropic; extra == 'anthropic'
@@ -86,6 +87,7 @@ Requires-Dist: rank-bm25>=0.2.2; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: scikit-learn<1.4.0,>=1.3.0; extra == 'dev'
 Requires-Dist: sentence-transformers>=5.2.0; extra == 'dev'
+Requires-Dist: xgboost>=2.0.0; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
 Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
@@ -294,7 +296,7 @@ EvalVault는 OpenTelemetry + OpenInference 기반의 **Open RAG Trace** 스키
 
 - 스펙: `docs/architecture/open-rag-trace-spec.md`
 - Collector: `docs/architecture/open-rag-trace-collector.md`
-- 샘플/내부 래퍼: `docs/guides/open-rag-trace-samples.md`, `docs/guides/open-rag-trace-internal-adapter.md`
+- 샘플/내부 래퍼: `docs/guides/OPEN_RAG_TRACE_SAMPLES.md`, `docs/guides/OPEN_RAG_TRACE_INTERNAL_ADAPTER.md`
 - 관련 문서: `docs/INDEX.md`, `docs/architecture/open-rag-trace-collector.md`
 
 ---

{evalvault-1.60.0 → evalvault-1.62.0}/README.en.md

@@ -150,8 +150,8 @@ The core contract is **module-level spans (`rag.module`) + log events + shared a
 **Docs**
 - `docs/architecture/open-rag-trace-spec.md`
 - `docs/architecture/open-rag-trace-collector.md`
-- `docs/guides/open-rag-trace-internal-adapter.md`
-- `docs/guides/open-rag-trace-samples.md`
+- `docs/guides/OPEN_RAG_TRACE_INTERNAL_ADAPTER.md`
+- `docs/guides/OPEN_RAG_TRACE_SAMPLES.md`
 
 ---
 

{evalvault-1.60.0 → evalvault-1.62.0}/README.md

@@ -178,7 +178,7 @@ EvalVault는 OpenTelemetry + OpenInference 기반의 **Open RAG Trace** 스키
 
 - 스펙: `docs/architecture/open-rag-trace-spec.md`
 - Collector: `docs/architecture/open-rag-trace-collector.md`
-- 샘플/내부 래퍼: `docs/guides/open-rag-trace-samples.md`, `docs/guides/open-rag-trace-internal-adapter.md`
+- 샘플/내부 래퍼: `docs/guides/OPEN_RAG_TRACE_SAMPLES.md`, `docs/guides/OPEN_RAG_TRACE_INTERNAL_ADAPTER.md`
 - 관련 문서: `docs/INDEX.md`, `docs/architecture/open-rag-trace-collector.md`
 
 ---

{evalvault-1.60.0 → evalvault-1.62.0}/docs/INDEX.md

@@ -37,8 +37,8 @@ docs/
 │   ├── DEV_GUIDE.md             # 개발 루틴/테스트/품질
 │   ├── CLI_MCP_PLAN.md          # CLI→MCP 이식 계획 (Living Doc)
 │   ├── RELEASE_CHECKLIST.md     # 배포 체크리스트
-│   ├── open-rag-trace-*.md      # Open RAG Trace 샘플/내부 래퍼
-│   └── open-rag-trace-*.md
+│   ├── OPEN_RAG_TRACE_*.md      # Open RAG Trace 샘플/내부 래퍼
+│   └── OPEN_RAG_TRACE_*.md
 ├── architecture/
 │   ├── open-rag-trace-spec.md   # Open RAG Trace 스펙
 │   └── open-rag-trace-collector.md

{evalvault-1.60.0 → evalvault-1.62.0}/docs/README.ko.md

@@ -328,8 +328,8 @@ uv run evalvault run-full tests/fixtures/e2e/insurance_qa_korean.json \
 - [new_whitepaper/INDEX.md](new_whitepaper/INDEX.md): 개발 백서 (설계/운영/품질 기준)
 - [architecture/open-rag-trace-spec.md](architecture/open-rag-trace-spec.md): Open RAG Trace 표준 (Draft)
 - [architecture/open-rag-trace-collector.md](architecture/open-rag-trace-collector.md): Collector 구성 예시
-- [guides/open-rag-trace-samples.md](guides/open-rag-trace-samples.md): 최소 계측 샘플
-- [guides/open-rag-trace-internal-adapter.md](guides/open-rag-trace-internal-adapter.md): 내부 시스템 최소 계측 래퍼
+- [guides/OPEN_RAG_TRACE_SAMPLES.md](guides/OPEN_RAG_TRACE_SAMPLES.md): 최소 계측 샘플
+- [guides/OPEN_RAG_TRACE_INTERNAL_ADAPTER.md](guides/OPEN_RAG_TRACE_INTERNAL_ADAPTER.md): 내부 시스템 최소 계측 래퍼
 - [CHANGELOG.md](https://github.com/ntts9990/EvalVault/blob/main/CHANGELOG.md): 릴리스 히스토리
 
 ---

{evalvault-1.60.0 → evalvault-1.62.0}/docs/architecture/open-rag-trace-spec.md

@@ -178,7 +178,7 @@ RAG 서비스 (OTel SDK) ── OTLP ──> OTel Collector ──> Phoenix /
 
 ## 관련 문서
 - [open-rag-trace-collector.md](open-rag-trace-collector.md): Collector 구성 예시
-- [../guides/open-rag-trace-samples.md](../guides/open-rag-trace-samples.md): 최소 계측 샘플
+- [../guides/OPEN_RAG_TRACE_SAMPLES.md](../guides/OPEN_RAG_TRACE_SAMPLES.md): 최소 계측 샘플
 
 ---
 

evalvault-1.62.0/docs/guides/AGENTS_SYSTEM_GUIDE.md

@@ -0,0 +1,142 @@
+AI 에이전트 시스템 설계부터 운영까지: 최신 연구 기반 전략 가이드
+
+문제의식: 최근 거대언어모델(LLM) 기반 AI 에이전트 시스템이 다양한 산업에 도입되며 주목받고 있다. 기업들은 고객 서비스, 소프트웨어 개발, 교육, 의료 등 여러 분야에서 복잡한 작업을 자동화하기 위해 에이전트를 구축하고 있다 . 그러나 여러 에이전트가 동적 경로를 따라 다양한 **도구(tool)**를 호출하며 복잡하게 상호작용하는 상황에서, 응답의 정확성과 적절성을 보장하는 것이 큰 과제로 떠오르고 있다 . 다시 말해, AI 에이전트 시스템이 제대로 믿을 수 있고 유용하게 동작하는지 평가하고 통제하는 방법론이 필요하다 .
+
+목표: 본 보고서는 AI 에이전트 시스템을 설계, 구현, 평가, 운영하는 전 과정을 체계적으로 검토하고, 최신 연구에 기반한 개선 전략을 제안한다. 특히 인지심리학적 관점에서 사용자와 개발자의 인지 부담을 줄이는 설계 원리를 강조하고, 편집자적 관점으로 문서 구조와 표현을 다듬었다. 또한 국문학적 관점에서 정확하고 일관된 용어를 사용하고, 피칭 전문가의 시각으로 핵심 메시지를 강조하며 시각화 가능한 요소를 포함하였다.
+
+구성: 보고서는 네 가지 전략적 질문을 중심으로 전개된다. 각 질문은 AI 에이전트 시스템 수명주기의 한 단계를 대변하며, 단계별로 왜 이러한 접근이 필요한지, 어떻게 실현할 것인지를 탐구한다:
+	1.	설계: “왜 단일 에이전트부터 시작해야 하는가?” – 복잡성을 통제하기 위한 초기 설계 전략을 다룬다.
+	2.	구현: “어떻게 모듈화된 아키텍처를 구현할 것인가?” – 유지보수성과 확장성을 높이는 구현 방법을 논의한다.
+	3.	평가: “AI 에이전트의 성능은 어떻게 평가해야 하는가?” – 에이전트의 지능과 행동을 종합적으로 측정하는 방법을 제시한다.
+	4.	운영: “운영 단계에서 어떻게 지속적으로 개선하고 통제할 것인가?” – 배포 후 시스템을 모니터링하고 안전하게 관리하는 방안을 설명한다.
+
+이러한 질문 구조를 통해 독자는 각 단계의 핵심 목표와 원칙을 탐색적으로 살펴볼 수 있다. 아래 각 섹션에서는 해당 질문에 대한 해답과 구체적인 전략을 제시한다.
+
+왜 단일 에이전트부터 시작해야 하는가? (설계 단계)
+
+복잡성의 함정: 여러 에이전트를 한꺼번에 도입하면 겉보기엔 사람 팀처럼 전문화를 통해 효율을 높일 수 있을 것 같지만, 현실에서는 조율 비용과 복잡성이 폭증할 위험이 있다  . 예를 들어 10개의 에이전트가 상호 협력하면 잠재적 상호작용 경로가 45개까지 늘어나고, 각 경로마다 문맥 손실이나 충돌이 발생할 가능성이 높아진다 . 이는 사람으로 치면 동시에 너무 많은 업무를 두서없이 처리하려는 상황과 같다. 인지심리학자 Herbert Simon의 말대로, 인간 두뇌의 한계로 복잡한 문제를 한꺼번에 완벽히 해결하는 것은 어렵다. 마찬가지로 에이전트 간 조율의 인지적 부담이 커지면 시스템 신뢰성과 성능이 급격히 떨어질 수 있다.
+
+단일 에이전트의 이점: 반면 단일 에이전트로 시작하면 전체 시스템을 하나의 맥락으로 유지할 수 있어 설계가 단순해지고 인지적 부담이 줄어든다. 모든 정보가 한 에이전트 내에 있으므로 기억(fragmented memory) 단편화나 정보 사일로 문제가 없다  . 여러 에이전트가 서로 정보를 주고받느라 발생하는 추가 비용도 없다. 실제로 한 연구에서는 복잡한 작업을 단일 에이전트로 처리할 때 API 호출 비용이 다중 에이전트 대비 1/15 수준으로 감소한 사례를 보고하였다 . 이는 불필요한 상호 통신을 줄인 결과로, 운영 비용 절감과 응답 지연 최소화에 유리하다.
+
+인지 부하 관점: 단일 에이전트 접근은 사용자 및 운영자의 이해 측면에서도 유리하다. 시스템 행동의 흐름을 한 눈에 파악할 수 있어 예측 가능성과 설명 가능성이 높아진다. 에이전트가 어떤 결정을 내리는지 추적하기 쉬우므로, 문제가 생겼을 때 디버깅이나 원인 분석이 수월하다. 이는 운영자가 시스템을 신뢰하고 통제할 수 있게 해준다. Hick의 법칙 등 인지심리 이론에 따르면, 사람은 선택지가 늘어날수록 판단에 어려움을 겪는데 , 동일하게 에이전트 구성도 단순할수록 의사결정 구조가 명확해져 성능 저하 위험이 줄어든다 . 요컨대, 처음에는 단순 구조로 핵심 과제를 해결하는 에이전트 하나를 제대로 만드는 것이 바람직하다. 이후 필요에 따라 점진적으로 구조를 확장해도 늦지 않다.
+
+다중 에이전트가 유효한 경우: 물론 모든 경우에 단일 에이전트만 써야 하는 것은 아니다. 문제를 병렬로 나누어 처리하면 큰 이점을 얻는 상황에서는 다중 에이전트가 효과적일 수 있다. 다음과 같은 조건에서는 다중 에이전트 전략을 고려할 수 있다:
+	•	작업 분할의 독립성: 문제를 여러 하위 문제로 완전히 독립적으로 나눌 수 있어, 에이전트들이 상호 통신 없이 병렬 처리가 가능한 경우 . (예: 각 에이전트가 서로 다른 데이터 세트를 분석하고 최종적으로 결과만 합치는 경우)
+	•	읽기 위주 작업: 에이전트들이 주로 데이터를 읽고 분석만 하며, **공유 상태를 수정(write)**하지 않는 경우 . 이때 각 에이전트는 타 에이전트의 결과를 변경하지 않고 충돌 없이 자신의 분석을 완료할 수 있다.
+	•	결과 통합의 단순성: 개별 에이전트의 산출물을 단순한 방식으로 결합할 수 있는 경우. 예를 들어 최종 오케스트레이션이 각 에이전트의 보고서를 나열하거나 평균내는 정도로 기계적으로 수행될 때, 복잡한 조율이 불필요하다  .
+	•	지연보다는 속도가 중요: 응답 속도 향상이 매우 중요해서, 다중 에이전트 병렬 처리로 지연을 줄이는 이득이 추가 비용보다 가치 있을 때 . (예: 금융 시장처럼 실시간 분석이 요구되는 분야에서는 속도 향상을 위해 비용 증가를 수용)
+
+위 조건을 만족하면 다중 에이전트 시스템은 단일 에이전트 대비 최대 8배 이상 빠른 처리나 더 많은 패턴 발견 등의 효과를 낼 수 있다고 보고된 바 있다(블룸버그 사례) . 다만 이 경우에도 운영 비용이 증가하고(블룸버그 사례에서 단일 대비 2.3배 비용 상승) , 이러한 장점을 얻기 위해서는 엄격한 오케스트레이션과 설계 통제가 전제되어야 한다 .
+
+요약: 대부분의 일반적인 경우, 단순한 출발점으로 시작하여 점진적으로 복잡성을 추가하는 것이 안전하다. 아래 표는 단일 vs. 다중 에이전트 접근의 주요 장단점을 요약한 것이다:
+
+전략	장점 (인지적/기술적 이익)	단점 (인지적/기술적 부담)
+단일 에이전트	- 통합된 맥락으로 일관성 유지- 에이전트 간 조율 오버헤드 없음- 설계 단순하며 디버깅 용이- 비용 및 지연 최소화 	- 하나의 에이전트가 모든 작업을 처리해야 함- 복잡한 문제에 대해 전문화 부족- 병렬 처리 이점 제한
+다중 에이전트	- 전문화된 역할로 복잡 작업 분담- 병렬 처리로 속도 향상 가능- 특정 에이전트는 심층 분석에 집중 	- 상호 조율 복잡성 증가 - 맥락 공유 어려움으로 오류 위험 - 운영 비용 상승 (컨텍스트 재구성 등) 
+
+위 비교에서 보듯, 단일 에이전트 방식은 인지적 부담과 기술적 부담이 모두 낮으며 초기에는 안정적인 선택이다. 이후 시스템이 성숙해지고 명확한 필요성이 생길 때, 그때 설계 원칙을 엄격히 지킨 다중 에이전트 구조를 신중히 도입하면 된다. 결론적으로 설계 단계에서는, “일단 한 명으로 완벽하게 뛰게 하고, 필요하면 팀을 늘린다”는 원칙이 성공 확률을 높여준다.
+
+(다음 단계: 설계 원칙을 정립했다면, 이제 이를 구현 단계에서 어떻게 실현할지 살펴보자. 단일 에이전트든 추후 다중 에이전트든 모듈화된 아키텍처로 구현하는 전략이 중요하다.)*
+
+어떻게 모듈화된 아키텍처를 구현할 것인가? (구현 단계)
+
+모듈화의 필요성: 모든 공학 분야에서 복잡한 시스템은 시간이 지남에 따라 모듈형 구성 요소들의 집합으로 진화해왔다 . 소프트웨어도 초기의 절차적 일체형 코드에서 벗어나, 오늘날에는 객체 지향과 API를 통해 잘 정의된 인터페이스를 가진 재사용 가능 컴포넌트들로 문제를 분할한다 . 이러한 모듈화는 변경이 발생해도 시스템 전체에 영향이 미치지 않도록 하여 유지보수성과 확장성을 높인다. AI 에이전트 시스템도 예외가 아니어서, 복잡도를 관리 가능하도록 쪼개는 설계가 필수적이다. LLM 중심의 초기 AI 시스템은 거대한 단일 모델에 의존했지만, 이는 신뢰성, 예측 가능성 면에서 한계를 드러냈다  . 반면 최근에는 모듈형 설계로 전환함으로써 높은 제어력과 품질을 확보하려는 움직임이 뚜렷하다 . 예컨대 OpenAI의 ChatGPT도 도구 플러그인, 외부 검색 등을 통합하며 다중 컴포넌트 구조로 발전하고 있다 .
+
+아키텍처 구성 요소: 구현 단계에서 우선적으로 할 일은 시스템을 논리적 구성 요소로 나누는 것이다. 일반적으로 AI 에이전트 시스템은 아래와 같은 계층적 구조를 갖는다  :
+	•	입출력 인터페이스: 에이전트가 다룰 입력 형식과 출력 형식을 모듈로 분리한다. 예를 들어 사용자 질의가 JSON이나 특정 도메인 언어로 주어질 경우 이를 처리/생성하는 별도 컴포넌트를 둔다.
+	•	데이터 기반 및 지식 저장소: 에이전트가 참고할 사실 데이터베이스나 벡터 검색 엔진 등을 구성한다. 이것이 시스템의 기저 정보를 제공하며, 모든 응답의 **사실적 근거(ground truth)**가 된다 .
+	•	결정론적 도구 모듈: 계산기, 데이터베이스 조회, API 호출 등 결과가 확정적인 기능들을 모듈화한다. 에이전트는 자연어로 지시를 내리고, 해당 모듈이 정해진 기능을 수행해 필요한 정보를 반환하도록 한다  . 이를 통해 LLM이 모든 것을 직접 처리하지 않고 룰 기반 컴포넌트와 협업할 수 있다.
+	•	일반 추론 엔진: 범용적인 상식과 언어 능력을 활용해 자연어 추론을 담당하는 핵심 LLM 모듈이다 . 이는 모듈화된 시스템의 두뇌 역할을 하며, 복잡한 요구를 계획하고 조정한다.
+	•	도메인 특화 추론 모듈 (선택): 필요한 경우 도메인 지식에 맞게 fine-tuning되었거나 프롬프트 체계가 특별히 설계된 전문 LLM을 별도로 둘 수 있다 . 예를 들어 의료 진단 에이전트라면 의료용 특화 모듈이 일반 LLM과 연동되어 더 정확한 전문 답변을 생성한다.
+	•	오케스트레이션(Orchestration) & 메모리 관리: 여러 모듈 간 흐름을 제어하는 오케스트레이션 로직을 구현한다. 각 단계의 입력/출력 연결, 작업 순서, 예외 처리 규칙 등을 명시적으로 코딩하여 결정론적 제어 흐름을 수립한다 . 또한 에이전트의 메모리(대화 이력, 중간 결과 저장 등)를 한 곳에서 관리하여, 정보가 흩어지지 않고 필요한 맥락이 유지되도록 한다.
+	•	평가 및 피드백 모듈: (이 부분은 흔히 간과되지만) 시스템의 성능을 측정하고 피드백을 주는 **평가 하네스(harness)**를 구축한다 . 예를 들어, 중요한 내부 단계마다 올바르게 진행되고 있는지 assertion이나 자체 검증(verify) 루틴을 넣거나, 최종 출력에 대해 미리 준비된 기준 질문-답변 쌍으로 정답률을 측정하는 모듈을 통합할 수 있다. 이 모듈은 개발 단계뿐만 아니라 운영 중에도 지속적인 품질 관리에 활용된다.
+
+위와 같이 역할별로 명확히 분리된 구성을 만들면 여러 가지 이점이 있다. 첫째, 개발 팀 내에서 각 모듈을 병렬로 개발하고 검증할 수 있어 인지 부담을 분산시킨다. 한 개발자가 시스템 전부를 머리에 담지 않고, 자신이 맡은 모듈의 로직에 집중하면 된다. 둘째, 문제가 발생했을 때 원인 모듈을 신속히 격리할 수 있어 디버깅이 수월하다. 예컨대 출력 오류가 지식 부족인지 추론 오류인지, 또는 도구 호출 실수인지 모듈별 로그를 통해 바로 파악할 수 있다. 셋째, 새로운 기능 추가나 모델 교체도 해당 모듈만 교체하면 되므로 확장성과 유지보수성이 극대화된다  . Databricks의 모듈형 에이전트 프레임워크 사례에서는, 이러한 모듈화된 접근이 신뢰성 향상, 유지관리 용이성, 확장성 제고로 이어져 기업 환경의 요구사항을 충족시켰다고 보고한다 . 마지막으로, 모듈 간 명확한 인터페이스 계약을 정의해 두면, 각 부분이 독립적으로 업그레이드되어도 시스템 전체의 인지적 일관성(consistency)을 해치지 않는다. 이는 운영자가 시스템을 이해하고 예측하는 데에도 도움이 된다.
+
+스킬 기반 단일 에이전트: 한편 최신 연구에서는 단일 에이전트 내부를 스킬(skill)이라는 모듈 단위로 분해하는 흥미로운 접근도 제시된다  . 여기서 스킬이란 특정 작업을 수행하는 내부 행동 모듈로, 일종의 에이전트 내부에 장착된 도구와 같다. 다중 에이전트 시스템의 전문 에이전트들을 한 에이전트의 스킬 라이브러리로 컴파일하여 협업 대신 내부 선택으로 대체할 수 있다는 개념이다 . 이러한 접근은 에이전트 간 대화 오버헤드를 제거하여 효율을 높이는 효과가 있다  . 실제 실험에서 스킬을 사용한 단일 에이전트는 복잡한 추론 작업에서 다중 에이전트 대비 토큰 사용량과 지연을 크게 줄이면서도 유사한 정확도를 보였다  . 이는 마치 사람이 여러 전문가 팀과 회의하느라 시간을 쓰기보다는, 머릿속에 여러 전문 **사고 도식(schemas)**을 익혀놓고 혼자 생각을 전환해가며 문제를 푸는 모습과 유사하다.
+
+다만 스킬 수가 지나치게 많아지면 새로운 문제가 발생한다. 인간도 한 번에 너무 많은 선택지가 있으면 결정 장애가 오듯이, LLM 에이전트도 내부 스킬이 과도하게 증가하면 선택 오류율이 급증하는 현상이 관찰되었다 . 연구에 따르면 스킬 라이브러리 크기가 일정 임계치를 넘어서면 성능 저하가 **완만한 감소가 아니라 급격한 전환 현상(phase transition)**처럼 나타난다  . 이는 인지과학의 작업기억 용량 한계와 유사한 양상으로, 한번에 너무 많은 정보를 처리하면 성능이 급격히 붕괴된다는 인지 부하 이론에 부합한다  . 이러한 발견은 계층적 구조의 중요성을 부각시킨다: 인간이 복잡한 정보를 카테고리로 묶어 체계를 세우듯, 스킬도 계층적으로 그룹화하면 선택 성능 저하를 완화할 수 있다는 것이다  . 따라서 구현 단계에서 만약 단일 에이전트 내 다수의 스킬을 설계한다면, 유사한 스킬들끼리는 범주화하고, 스킬 간 중복이나 과도한 유사성을 제거하여 **혼동(confusability)**을 줄이는 것이 중요하다 . 예를 들어 8±2 개 이하의 선택지로 메뉴를 계층화하는 것이 인간에게 최적이듯, 에이전트도 한 번에 그 정도 규모의 스킬만 고민하도록 트리 구조로 스킬을 배치할 수 있다.
+
+구현 요약 및 권고: 모듈화된 아키텍처 구현의 핵심은 “느슨하게 결합되고 강하게 응집된(loosely coupled, highly cohesive)” 컴포넌트들의 집합을 만드는 일이다. 각 모듈은 명확한 책임을 지니고, 공개된 인터페이스로만 소통하며, 내부 구현은 캡슐화한다. 이러한 시스템을 구축할 때 도움이 되는 체크리스트를 정리하면 다음과 같다:
+	•	문제 분해: 요구 기능을 분석하여 상호 작용은 최소화하면서 독립적인 모듈로 최대한 쪼갰는가?
+	•	인터페이스 정의: 모듈 간 주고받을 정보의 형식과 프로토콜을 명시적으로 설계했는가? (예: 함수 호출 시 입력/출력 JSON 스키마 정의)
+	•	오케스트레이션 구현: 에이전트의 흐름 제어 로직을 상태 기계 또는 그래프로 명확히 작성하여, 에이전트들이 예상 가능한 순서로 상호작용하게 했는가 ?
+	•	재사용성: 각 모듈은 다른 프로젝트에도 활용 가능하도록 일반화되어 있는가? 너무 구체적 의존성이 많다면 분리하거나 설정으로 관리하도록 수정.
+	•	확장 대비: 향후 새로운 도구나 모델을 추가할 경우 기존 모듈을 교체/확장하기 쉬운 구조인가? 모듈 추가 시 다른 부분에 영향이 없도록 설계했는가.
+	•	성능 모니터링 삽입: 중요한 모듈에는 로그 및 평가 포인트를 두어, 후에 성능을 계측하고 문제 발생 시 추적할 수 있도록 구현했는가.
+
+위 원칙을 준수하며 구현하면, 비로소 시스템의 뼈대가 갖춰지게 된다. 이제 다음으로 중요한 것은 이렇게 구현된 에이전트 시스템이 제대로 작동하는지 측정하고 개선하는 단계, 즉 평가 단계다.
+
+AI 에이전트의 성능은 어떻게 평가해야 하는가? (평가 단계)
+
+평가의 중요성: AI 에이전트 시스템은 전통 소프트웨어와 달리 확률적 거동을 보이며, 작동 과정이 복잡하고 결과의 정합성을 판단하기 어렵다 . 그럼에도 기업의 의사결정자나 사용자를 설득하려면 체계적인 평가 지표와 성과 증거가 필요하다. 그러나 현재까지 표준화된 벤치마크나 평가 척도가 부족하다는 점이 큰 도전으로 지적된다 . 일반적인 LLM 성능 평가 지표(예: 정확도, 유창성 등)는 에이전트의 복합적 행동을 충분히 반영하지 못한다 . 에이전트는 단순 답변 생성 외에도 계획 수립, 도구 활용, 멀티모달 처리, 사용자 상호작용까지 수행하기 때문에, 다차원적인 평가 프레임워크가 필요하다 .
+
+다차원 평가 지표: 최신 연구와 업계 사례를 살펴보면, **다음과 같은 축(dimension)**에서 에이전트 성능을 측정할 것을 권장한다:
+	•	임무 성공률 (Task Success Rate): 에이전트가 주어진 목표를 달성했는가를 비율로 측정한다 . 예를 들어 “사용자 문의 처리” 에이전트라면, 사용자의 문제를 실제로 해결하거나 만족시킨 세션의 비율이 될 것이다. 이 지표는 최종 산출의 효과성을 나타내며, 정량적인 1차 지표로 중요하다.
+	•	맥락 적합성 & 대응 품질: 에이전트의 응답이 주어진 맥락이나 질의에 적절히 부합하는지를 평가한다. 예를 들어 대화형 에이전트라면 **대화 일관성(coherence)**과 맥락 유지 능력을 본다 . 또한 에이전트가 도구를 사용하는 과정이 논리적 순서에 맞는지, 불필요한 시도를 남발하지는 않았는지도 살핀다. 이는 과정상의 정확성을 보는 지표다.
+	•	적응성 (Adaptability): 환경 변화나 새로운 요청 유형에 유연하게 대응할 수 있는지 측정한다 . 예컨대 지원하지 않던 기능 요구에 대해 학습이나 개선 없이 얼마나 대응가능한지, 혹은 오류 발생 시 재시도 전략이나 fallback이 있는지 평가한다. **회복탄력성(resilience)**도 이 범주에 포함된다.
+	•	안전성과 윤리: 에이전트가 유해하거나 편향된(output toxicity/bias) 응답을 생성하지 않고, 주어진 안전 가이드라인을 준수하는지 모니터링한다 . 이는 정성적 평가일 수 있으나, 최근에는 욕설/차별 발화 비율, 금지 주제 언급 여부 등을 정량화하기도 한다. 안전성 평가는 기업 평판과 사용자 신뢰를 위해 필수적이다.
+	•	사용자 만족도: 최종 사용자(또는 도메인 전문가)의 주관적 만족도를 조사한다 . 이는 설문조사, 인터뷰 또는 UX 평가를 통해 질적으로 수집할 수 있다. 예를 들어 응답의 유용성, 인터페이스의 편의성, 전반적 신뢰감 등에 대한 점수를 받는다. 자동화된 성능 지표가 포착하지 못하는 미묘한 실용성을 이 피드백이 보완해준다 .
+	•	효율성과 비용: 시스템의 응답 지연(latency), 처리량(thROUGHPUT), 컴퓨팅 자원 비용 등을 계측한다 . 특히 실시간 서비스라면 지연이 사용자 경험에 큰 영향을 주므로 SLI/SLO로 관리하고, 클라우드 API 비용이나 인프라 비용 대비 성능 향상을 ROI 관점에서 분석한다.
+
+위 항목들을 종합하여 평가해야 AI 에이전트의 전반적 가치를 객관적으로 나타낼 수 있다. 각 조직은 중요도에 따라 가중치를 둘 수 있지만, 한두 가지 지표만으로는 편향된 평가가 될 수 있으므로 가능하면 정량+정성 지표의 균형 잡힌 평가체계를 구축해야 한다  .
+
+평가 방법론: 이러한 지표를 활용할 때 어떻게 데이터를 수집하고 평가를 진행할지 방법론도 중요하다:
+	•	시나리오 기반 테스트: 실제 사용 시나리오를 최대한 모사한 테스트 세트를 만든다. 예를 들어 고객지원 챗봇이라면 다양한 문의 유형을 망라한 시나리오, 그리고 각 시나리오별 기대 답변이나 성공 기준을 정의한다. 최근에는 시나리오를 시뮬레이션 환경으로 만들어 에이전트를 반복적으로 평가하는 접근도 제안된다 .
+	•	자동화된 스크립트 평가: 정형화된 과제에 대해서는 자동 채점 시스템을 구축한다. 질문-답변 쌍을 만들어 에이전트의 답변을 정답과 비교하거나, 수치 계산의 정확성을 검사하는 등이다 . 다만 LLM의 유연한 응답 표현 때문에 정확 매칭이 어려우므로 루브릭 기반 채점이나 임베딩 유사도 활용 등도 고려된다.
+	•	휴먼 평가 및 사용자 연구: 정량 지표로 포착 어려운 부분은 실제 **인간 평가자(human raters)**를 활용한다. 예컨대 대화의 자연스러움이나 창의성은 다수 평가자에게 **평점(예: 1~5점)**을 매기게 하여 평균을 내는 방식으로 평가한다 . 현업 도메인 전문가에게 시연하고 피드백을 받거나, 최종 사용자 A/B 테스트를 통해 한쪽 시스템이 다른 쪽보다 선호되는지 실험할 수도 있다.
+	•	내부 과정 평가 (프로세스 평가): **“Not Just the Output”**이라는 말처럼, 에이전트의 최종 출력만 볼 것이 아니라 중간 추론 과정도 평가해야 한다는 의견이 많다. 예를 들어 에이전트가 문제를 풀 때 적절한 계획을 수립했는지, 필요한 정보를 제때 검색했는지, 오류가 발생하면 재시도를 했는지 등을 로그 분석이나 리플레이를 통해 검증한다. 이러한 과정 평가는 성능 저하 원인을 규명하고 개선점을 찾는 데 필수적이다  .
+	•	벤치마크와 경진대회: 가능하면 공개된 벤치마크 세트나 평가 플랫폼을 활용하여 객관적으로 비교한다. 현재까지는 표준화가 부족하지만, 예컨대 멀티에이전트 상호작용에 특화된 데이터셋이나 시나리오를 여러 기관이 공유하여 공동 평가를 진행하는 추세가 있다 . 이를 통해 우리 시스템의 수준을 업계 평균 또는 최첨단과 비교할 수 있다.
+
+평가의 조기 통합: 중요한 점은, 평가를 사후에 생각하지 말고 초기부터 설계에 통합하라는 것이다. 앞서 구현 단계에서 언급했듯, 개발 초기에 이미 평가 기준과 절차를 정해 두면 이후 개선 사이클을 돌릴 때 일관된 척도로 효과를 측정할 수 있다  . 예를 들어 Databricks의 Mosaic AI 에이전트 프레임워크는 개발 초기부터 평가 시나리오와 기준을 정의하고 이를 자동 실행하여, 새로운 변경이 성능에 미치는 영향을 지속적으로 모니터링한다고 한다 . 이러한 DevOps적 평가 통합은 에이전트 시스템의 데이터 주도 발전을 가능케 한다.
+
+평가 단계 요약 - 체크리스트: 효과적인 평가를 위해 아래와 같은 체크리스트를 참고할 수 있다:
+	•	명확한 성공 기준 설정: 에이전트의 목표와 역할에 비춰 무엇이 성공인지 정의했는가? (예: 사용자 문제가 해결된 상태를 성공으로 정의)
+	•	다양한 지표 수집: 정량 지표(정확도, 성공률, 응답속도 등)와 정성 지표(만족도, 자연스러움 등)를 균형 있게 수집하고 있는가?
+	•	테스트 케이스 확보: 대표 사용 시나리오를 포괄하는 테스트 세트를 마련했고, 정기적으로 이에 대해 평가를 수행하는가?
+	•	로그와 트레이스 활용: 에이전트의 내부 추론 로그를 저장하고 분석하여, 겉으로 드러나지 않는 오류 징후나 개선 포인트를 찾고 있는가?
+	•	사용자 피드백 루프: 실제 사용자나 베타테스터로부터 피드백을 수렴하는 채널이 있는가? 이를 통해 발견된 문제를 업데이트에 반영하는 루프가 구축되어 있는가?
+	•	지속적 평가 자동화: 코드 변경이나 모델 업데이트 시 자동으로 평가를 돌려 성능 변화를 감지하는 CI(Continuous Integration) 파이프라인이 있는가?
+
+평가 단계를 이행함으로써, 우리는 AI 에이전트 시스템의 강약점을 객관적으로 파악하고 데이터 기반 개선을 실현할 수 있다. 이러한 평가 결과는 경영진과 이해관계자에게 성과를 설득력 있게 제시하는 근거가 되며, 외부 발표 시에도 신뢰도를 높여준다.
+
+(다음 단계: 평가를 통해 시스템의 성능과 한계를 파악했다면, 마지막으로 이를 현업 운영 환경에서 어떻게 지속 관리하고 개선할지 살펴보자.)
+
+운영 단계에서 어떻게 지속적으로 개선하고 통제할 것인가? (운영 단계)
+
+운영의 과제: AI 에이전트 시스템을 성공적으로 설계·구현하여 배포했더라도, 운영 단계에서는 현실 환경에서 예상치 못한 문제가 발생할 수 있다. 모델 출력의 품질이 시간이 지나며 떨어지거나(예: 최신 정보 반영 부족), 사용자가 악의적으로 프롬프트를 넣어 부적절한 응답을 유도하려 할 수도 있다 . 또한 시스템이 정상 작동하더라도, 안전성이나 규제 준수 측면에서 모니터링이 필요하다. 운영자는 여러 에이전트 인스턴스가 실시간으로 돌아가는 상황에서 문제를 사전에 감지하고 빠르게 대응할 수 있어야 한다. 이를 위해서는 지속적 모니터링, 경보 체계, 모델 업데이트, 피드백 루프 등의 운영 전략이 요구된다.
+
+모니터링과 경보: 운영 환경에서 에이전트의 행동을 투명하게 추적하기 위해 종합 모니터링 시스템을 구축해야 한다. 예를 들어 Mosaic AI Gateway와 같은 솔루션은 에이전트 시스템에 대한 접근 제어, 레이트 리미팅, 페이로드 로깅, 입출력 필터링 등을 제공하여, 실행 중인 에이전트를 상시 모니터링하고 이상 징후를 포착할 수 있게 한다  . 이러한 게이트웨이는 특히 안전성, 편향, 품질 지표를 실시간으로 점검하여, 임계치를 벗어날 경우 운영자에게 경보를 보낸다 . 예컨대 응답에 금지된 단어가 검출되거나, 일정 시간 이상 답변 생성이 지연되면 자동 알람을 발생시켜 조치하게 한다. 대시보드를 통해 주요 성능 지표(성공률, 평균 응답시간, 사용자 만족도 등)의 추이를 시각화하고, 이상 값 발생 시 Drill-down하여 원인을 분석할 수 있어야 한다. 이러한 모니터링 시스템을 갖추면 운영자의 인지 부담을 줄여준다. 사람이 일일이 모든 대화를 검토하지 않더라도, 시스템이 요약된 정보와 문제 시그널을 제공하므로 의사결정에 집중할 수 있다.
+
+안전 및 보안 통제: 운영 중 가장 신경 써야 할 부분 중 하나는 **보안(Security)과 프라이버시, 윤리(Ethics)**다  . 에이전트가 외부와 상호작용하다 보면, 악의적인 시도로 **안전장치를 우회(jailbreak)**하려는 시도가 빈발한다 . 이를 막기 위해 다층 방어 전략을 도입해야 한다 . 첫째 레이어로는 **입력 필터링(guardrail)**이 있다. 예를 들어 사용자의 프롬프트를 분석해 금지된 요청이나 의도된 프롬프트 인젝션 공격 패턴이 감지되면 이를 차단하거나 변형하는 전처리 계층을 둔다 . OpenAI 등은 이미 이러한 시큐어 프롬프트 엔지니어링을 적용하고 있다. 둘째, 출력 필터링 및 검열이다. 에이전트의 최종 답변이 나가기 전 민감정보 노출이나 명확한 유해 발언이 없는지 후처리 필터를 거쳐 필요시 수정을 가한다 . 예컨대 개인정보가 포함되었으면 마스킹하거나, 공격적 언어를 순화하는 식이다. 셋째, 모델 자체의 강화이다. 사전에 유해 예시 데이터를 활용한 adversarial training을 통해 모델이 안전정책을 내재화하도록 하고 , 답변 생성 시 정책 준수 프로세스(예: 시스템 프롬프트로 가이드라인 제공)를 적용한다. 넷째, 프라이버시 보호를 위해 필요한 경우 차등_privacy 등의 기법을 활용해 모델이 학습 데이터의 개인 정보를 역추론하거나 유출하지 못하도록 한다 . 마지막으로, 감사 로그와 재현: 모든 상호작용을 안전하게 기록하여 사후에 문제가 발생하면 **감사(audit)**를 하고 개선에 활용한다. 금융, 의료 등 규제가 엄격한 분야에서는 이런 로그 관리와 재현 환경이 필수적이다.
+
+지속적 학습과 개선: 운영하면서 축적되는 데이터와 피드백은 귀중한 개선 자산이다. 이를 활용해 주기적인 모델 업데이트 또는 프롬프트 튜닝을 수행해야 한다. 예를 들어 사용자가 반복해서 질문하지만 에이전트가 대답하지 못하는 패턴이 발견되면, 해당 지식을 추가하거나 스킬을 확장하는 식으로 성능을 향상시킨다. 또한 평가 단계에서 구축한 지표 대시보드를 운영 중에도 활용하여, 시간 경과에 따른 성능 추이를 모니터링한다. 만약 성능 저하 추세가 보인다면 (예: 최신 정보 필요성 증가), 이에 맞춰 모델 재학습 또는 기존 모델 교체를 검토한다. A/B 테스트를 통해 새로운 모델이나 개선된 프롬프트 체계를 소규모 트래픽에 적용해보고 기존 버전과 비교하는 것도 안전한 개선 전략이다.
+
+운영 단계 체크리스트: 안정적인 운영과 지속적 개선을 위해 다음 사항들을 점검해볼 수 있다:
+	•	모니터링 대시보드 구비: 주요 성능, 품질, 안전 지표를 실시간으로 볼 수 있는 모니터링 시스템이 구축되어 있는가? 임계치 이상일 때 자동 알람이 오는가?
+	•	로그 및 추적 가능성: 모든 에이전트의 행동(질문, 답변, 도구 호출 등)이 적절히 로그로 남겨지고 보관되는가? 문제가 발생하면 해당 세션을 **재현(reproduce)**하여 분석할 수 있는가?
+	•	안전장치 적용: 입력 및 출력에 대해 멀티 레이어 필터링이 적용되어 있는가? (금지어 필터, 콘텐츠 모더레이션 등) 모델이 민감정보를 저장/출력하지 않도록 정책이 수립되고 구현되어 있는가?
+	•	보안 관리: API 키나 데이터베이스 자격증명 등 비밀정보 관리가 안전하게 되고 있는가? 외부 시스템 연동 시 권한 제어와 감사 로그가 확보되어 있는가?
+	•	모델 개선 사이클: 운영 중 얻은 데이터를 주기적으로 리뷰하고, 모델 재훈련이나 프롬프트 개선에 반영하는 주기적 업데이트 프로세스가 존재하는가? 그 결과를 다시 배포 전에 평가하여 검증하는 절차가 있는가?
+	•	인력 개입 계획: 에이전트가 처리하기 곤란한 상황(예: 규정상 사람 승인이 필요한 경우, 또는 에이전트 오류 시)에 사람 운영자가 개입할 수 있는 절차가 마련되어 있는가? 예를 들어 일정 확률로 답변 전에 인간 검토 단계 삽입, 실패 시 티켓화 등.
+
+위와 같은 운영 상의 관리가 이루어질 때, AI 에이전트 시스템은 초기 도입에서 그치지 않고 지속적으로 신뢰성과 성능을 향상시켜 나갈 수 있다. 이는 기술 리더십 관점에서 프로젝트의 장기 성공을 담보하고, 경영진에게는 안심하고 투자할 수 있는 근거를 제공한다. 또한 외부 발표나 고객 데모 시에도 “우리는 단지 모델을 출시한 게 아니라, 운영 단계까지 고려된 시스템을 갖추고 있다”는 메시지를 전달함으로써 전문성과 책임감을 강조할 수 있다.
+
+맺음말: 단계별 전략의 종합과 전망
+
+AI 에이전트 시스템을 구축하고 활용하는 것은 한 번에 끝나는 프로젝트가 아니라 계속되는 여정에 가깝다. 본 보고서에서는 그 여정을 설계-구현-평가-운영의 4단계로 구분하고, 각 단계마다 전략적 질문을 던져가며 최적의 실행 방안을 모색했다:
+	•	설계 단계에서는, 복잡성을 제어하고 인지적 부담을 완화하기 위해 먼저 단일 에이전트의 단순 구조로 시작할 것을 권고했다. 이는 향후 확장의 토대가 되며, 초기 실패 위험을 줄인다.
+	•	구현 단계에서는, 모듈화된 아키텍처를 통해 시스템을 구성함으로써 유연성, 유지보수성, 신뢰성을 확보하는 방안을 제시했다. 명확히 정의된 모듈과 인터페이스는 개발과 이해를 용이하게 하고, 필요 시 계층적 설계와 스킬 라이브러리로 내부 복잡도를 관리할 수 있다.
+	•	평가 단계에서는, 다차원적인 지표와 종합적인 방법론을 활용해 에이전트의 성능을 면밀히 측정하는 전략을 다루었다. 이를 통해 얻은 정량/정성 데이터는 시스템 개선의 나침반이 되며, 이해관계자 설득의 근거 자료가 된다.
+	•	운영 단계에서는, 모니터링과 안전장치를 갖춘 지속적 관리로 실제 환경에서의 안정성을 담보하는 방법을 제안했다. 또한 지속적 학습을 통해 시간이 지날수록 지능과 성능이 향상되는 자기진화형 시스템으로 발전시킬 수 있음을 강조했다.
+
+이러한 단계별 전략들은 각각 독립적으로 중요할 뿐 아니라, 선순환 사이클로 연결될 때 최대의 효과를 낸다. 설계 원칙이 올바로 구현되고, 구현된 시스템이 엄밀히 평가되며, 평가 결과가 운영 개선에 활용되고, 운영 중 얻은 인사이트가 다시 설계 개선으로 이어지는 학습 루프를 구축하는 것이다. 이를 통해 AI 에이전트 시스템은 처음에 세운 목표를 뛰어넘어, 예측하지 못했던 새로운 기회와 가치를 창출할 수 있다.
+
+마지막으로, AI 에이전트 분야는 매우 빠르게 발전하고 있는 만큼 최신 연구 동향과 기술 도구에 지속적인 관심을 가져야 한다. 예를 들어 에이전트의 계획능력을 높이는 새로운 알고리즘, 멀티에이전트 협업을 돕는 프레임워크, 더 나은 평가를 위한 벤치마크 등이 속속 등장하고 있다. 이러한 지식을 유연한 전략 틀 안에 수용한다면, 우리의 AI 에이전트 시스템은 기술 리더십을 유지하면서도 안정적으로 성장해 나갈 것이다.
+
+참고문헌:
+	1.	Singh, Y. V. (2025). Not Just the Output: A Smarter Way to Evaluate AI Agent Systems. Medium. (데이터 사이언스 커뮤니티의 에이전트 도입 현황과 평가 필요성 논의) 
+	2.	Bhavsar, P. (2025). Why Multi-Agent Systems Fail. Galileo AI Blog. (다중 에이전트 시스템의 조율 비용 문제와 성공/실패 요인 분석)  
+	3.	Li, X. (2026). When Single-Agent with Skills Replace Multi-Agent Systems and When They Fail. arXiv:2601.04748. (단일 에이전트의 스킬 기반 모듈화와 인지적 한계에 대한 연구)  
+	4.	Rao, N., Zaharia, M., Wendell, P. (2024). AI Agent Systems: Modular Engineering for Reliable Enterprise AI Applications. Databricks Blog. (엔터프라이즈용 AI 에이전트의 모듈러 아키텍처와 평가/모니터링 전략)  
+	5.	Liang, G., & Tong, Q. (2025). LLM-Powered AI Agent Systems and Their Applications in Industry. Proceedings of IEEE ICMLA 2025 (또는 arXiv:2505.16120). (LLM 기반 에이전트 시스템의 산업 활용과 과제 - 평가 지표 부족, 보안 등 언급)  

{evalvault-1.60.0 → evalvault-1.62.0}/docs/guides/DEV_GUIDE.md

@@ -62,6 +62,15 @@ npm run dev
 
 ---
 
+## 타입체크 (Pyright 비활성화)
+
+EvalVault는 Ruff만 사용합니다. Pyright/Pylance 경고가 보이면 에디터 설정을 끄세요.
+
+- VS Code: 확장(“Pylance”, “Pyright”) 비활성화 또는 제거
+- VS Code 설정 예시: `"python.analysis.typeCheckingMode": "off"`
+
+---
+
 ## 문서 작업 규칙 (Docs)
 
 - `docs/`는 **현재 프로젝트에 필요한 문서만** 유지합니다. (중복/과거 정보는 삭제)
@@ -74,4 +83,4 @@ npm run dev
 
 - 설계/컴포넌트/운영 기준: `docs/new_whitepaper/INDEX.md`
 - CLI→MCP 이식 계획: `docs/guides/CLI_MCP_PLAN.md`
-- Open RAG Trace 스펙/샘플: `docs/architecture/open-rag-trace-spec.md`, `docs/guides/open-rag-trace-samples.md`
+- Open RAG Trace 스펙/샘플: `docs/architecture/open-rag-trace-spec.md`, `docs/guides/OPEN_RAG_TRACE_SAMPLES.md`

{evalvault-1.60.0 → evalvault-1.62.0}/docs/guides/USER_GUIDE.md

@@ -819,8 +819,8 @@ OpenTelemetry + OpenInference 기반의 **Open RAG Trace 표준**을 따르세
 **관련 문서**
 - `docs/architecture/open-rag-trace-spec.md`
 - `docs/architecture/open-rag-trace-collector.md`
-- `docs/guides/open-rag-trace-internal-adapter.md`
-- `docs/guides/open-rag-trace-samples.md`
+- `docs/guides/OPEN_RAG_TRACE_INTERNAL_ADAPTER.md`
+- `docs/guides/OPEN_RAG_TRACE_SAMPLES.md`
 
 ### 임베딩 분석 & 내보내기
 
@@ -1201,7 +1201,7 @@ Langfuse에는 테스트 케이스별 스팬과 메트릭 점수가 기록되며
 - [new_whitepaper/INDEX.md](../new_whitepaper/INDEX.md) - 개발 백서(설계/운영/품질 기준)
 - [open-rag-trace-spec.md](../architecture/open-rag-trace-spec.md) - Open RAG Trace 표준
 - [open-rag-trace-collector.md](../architecture/open-rag-trace-collector.md) - Collector 구성 가이드
-- [open-rag-trace-internal-adapter.md](open-rag-trace-internal-adapter.md) - 내부 시스템 계측
+- [OPEN_RAG_TRACE_INTERNAL_ADAPTER.md](OPEN_RAG_TRACE_INTERNAL_ADAPTER.md) - 내부 시스템 계측
 - [CHANGELOG.md](https://github.com/ntts9990/EvalVault/blob/main/CHANGELOG.md) - 변경 이력
 
 ### 외부 리소스

evalvault-1.62.0/docs/guides/rag_human_feedback_calibration_implementation_plan.md

@@ -0,0 +1,218 @@
+# RAG 인간 피드백 보정: 상세 구현 계획서
+
+본 문서는 `docs/guides/rag_human_feedback_calibration.md`의 설계를 기반으로 EvalVault에 **사람 만족도 보정(calibration) 기능**을 구현하기 위한 상세 실행 계획을 정리합니다.
+
+---
+
+## 1. 목표/성공 기준
+
+### 목표
+- 대표 샘플 기반 인간 평가 수집 → 보정 모델 학습 → 전체 결과에 보정 점수 적용.
+- RAGAS 점수와 사용자 만족도 괴리를 줄이고, 이해 가능한 보정 지표를 제공.
+
+### 성공 기준
+- DB에 `satisfaction_feedback` 저장/조회 가능.
+- Run 상세 응답에 `calibrated_satisfaction`, `imputed`, `imputation_source` 포함.
+- CLI `evalvault calibrate` 실행 시 보정 모델 성능 요약 출력.
+- Web UI에서 평가 입력/조회/보정 점수 표시.
+
+---
+
+## 2. 전제 및 스코프
+
+### 전제
+- 문서에 제시된 정책을 기본값으로 채택:
+  - 만족도 라벨: 1~5
+  - Thumb 피드백: up/down/none (약한 레이블)
+  - 보정 점수: `calibrated_satisfaction`
+  - 결측치 보정 규칙: thumb → 매핑, 없으면 모델 예측
+
+### 스코프
+- 백엔드: StoragePort, SQL 스키마, API, CLI, 도메인 서비스
+- 프론트엔드: RunDetails UI에 만족도 평가 탭 + 보정 점수 표시
+- 모델: 선형 회귀 + XGBoost 회귀(선형은 설명용)
+
+### 비스코프(초기)
+- 실시간 온라인 학습, A/B 실험 자동 트리거
+- 자동 평가자(LLM Judge) 연동
+
+---
+
+## 3. 아키텍처 개요
+
+### 데이터 플로우
+1) 대표 샘플 선정(클러스터링) → 2) 인간 평가 수집 → 3) 피처 생성 → 4) 모델 학습 → 5) 보정 점수 추정 → 6) UI 표시
+
+### 재사용 가능한 기존 컴포넌트
+- 클러스터링: `src/evalvault/domain/services/cluster_map_builder.py`
+- NLP 피처 패턴: `src/evalvault/adapters/outbound/analysis/nlp_adapter.py`
+- Storage 어댑터 패턴: `src/evalvault/adapters/outbound/storage/*_adapter.py`
+
+---
+
+## 4. 데이터 모델/스키마 설계
+
+### 신규 테이블
+`src/evalvault/adapters/outbound/storage/schema.sql`
+
+`satisfaction_feedback`
+- `id` (PK)
+- `run_id`
+- `test_case_id`
+- `satisfaction_score` (1~5, nullable)
+- `thumb_feedback` (`up`/`down`/`none`)
+- `comment` (nullable)
+- `rater_id` (nullable)
+- `created_at`
+
+### 결과 확장
+- 테스트 케이스 결과: `calibrated_satisfaction`, `imputed`, `imputation_source`
+- run summary: `avg_satisfaction_score`, `thumb_up_rate`, `imputed_ratio`
+
+---
+
+## 5. StoragePort/Adapter 설계
+
+### StoragePort 확장
+`src/evalvault/ports/outbound/storage_port.py`
+- `save_feedback(...)`
+- `list_feedback(run_id)`
+- `get_feedback_summary(run_id)`
+
+### 어댑터 확장
+- `src/evalvault/adapters/outbound/storage/sqlite_adapter.py`
+- `src/evalvault/adapters/outbound/storage/postgres_adapter.py`
+
+### 마이그레이션
+- 기존 DB에 `satisfaction_feedback` 테이블 추가
+- 인덱스: `run_id`, `test_case_id`
+
+---
+
+## 6. API 설계 (FastAPI)
+
+### 라우터 확장
+`src/evalvault/adapters/inbound/api/routers/runs.py`
+
+- `POST /api/v1/runs/{run_id}/feedback`
+  - 요청: `test_case_id`, `satisfaction_score?`, `thumb_feedback?`, `comment?`, `rater_id?`
+
+- `GET /api/v1/runs/{run_id}/feedback`
+  - 응답: 피드백 리스트
+
+- `GET /api/v1/runs/{run_id}`
+  - summary에 `avg_satisfaction_score`, `thumb_up_rate`, `imputed_ratio` 포함
+  - results[].metrics에 `calibrated_satisfaction`, `imputed`, `imputation_source` 포함
+
+---
+
+## 7. CLI 설계
+
+### 명령
+`src/evalvault/adapters/inbound/cli/commands/calibrate.py`
+
+```
+evalvault calibrate --run-id <ID> [--model linear|xgb|both] [--write-back]
+```
+
+### 출력
+- 모델 성능 요약: Pearson/Spearman, MAE
+- 피처 중요도(가능 시)
+
+---
+
+## 8. Web UI 설계
+
+`frontend/src/pages/RunDetails.tsx`
+
+### UI 기능
+- 탭: `만족도 평가`
+  - 별점(1~5), thumb up/down, 코멘트 입력
+  - 테스트 케이스별 저장
+
+### 표시
+- Summary 카드: 평균 만족도, Thumb Up 비율, 보정 비율
+- 메트릭 표에 `calibrated_satisfaction` 컬럼 추가
+
+---
+
+## 9. 보정/결측치 처리 규칙
+
+1. `satisfaction_score` 있음 → 그대로 사용
+2. 없고 `thumb_feedback` 있음 → 약한 레이블 매핑
+   - `up = 4.0`, `down = 2.0`
+3. 둘 다 없으면 모델 예측값 사용
+4. 모든 점수는 1~5로 클리핑
+5. `imputed` 및 `imputation_source` 필드 표시
+
+---
+
+## 10. 모델/피처 설계
+
+### 피처
+- RAGAS: `faithfulness`, `answer_relevancy`, `context_precision`, `context_recall`
+- 한국어 피처:
+  - 답변 길이
+  - 질문 키워드 누락률
+  - 형태소 다양성(TTR)
+
+### 모델
+- 기본: 선형회귀 (설명용)
+- 출력: XGBoost 회귀 (예측 성능용)
+
+### 의존성
+- `scikit-learn`은 이미 존재
+- `xgboost`는 `pyproject.toml`의 optional dependencies에 추가 필요
+
+---
+
+## 11. 대표 샘플링 전략
+
+### 1차 버전
+- `cluster_map_builder.py`의 KMeans + TF-IDF 임베딩 활용
+- 클러스터 당 centroid 가까운 케이스 1개씩 선택
+
+### 확장 버전
+- 불확실성 기반 샘플 추가 (예측값 2.4~2.6 등)
+
+---
+
+## 12. 테스트/검증 계획
+
+### 단위 테스트
+- StoragePort: save/list 피드백 동작
+- 보정 모델: 학습/예측 결과 shape 및 범위
+
+### 통합 테스트
+- API 엔드포인트: 저장/조회 동작
+
+### 품질 지표
+- 상관계수, MAE
+- Inter-rater agreement(가능 시): Cohen/Fleiss Kappa
+
+---
+
+## 13. 단계별 일정(제안)
+
+1. **DB/Storage 레이어 확장**
+2. **도메인 서비스(모델/보정 로직) 구현**
+3. **API 확장**
+4. **CLI 구현**
+5. **UI 통합**
+6. **테스트 및 검증**
+
+---
+
+## 14. 리스크 및 대응
+
+- **라벨 노이즈**: 평가 가이드 문서화 + 다중 평가자 평균
+- **샘플 편향**: 대표 샘플링 + 운영 중 추가 샘플링
+- **모델 과적합**: 단순 모델 우선, 교차검증
+
+---
+
+## 15. 참고 문서
+
+- `docs/guides/rag_human_feedback_calibration.md`
+- `src/evalvault/domain/services/cluster_map_builder.py`
+- `src/evalvault/adapters/outbound/analysis/nlp_adapter.py`