DProvenanceKit — AI 에이전트의 추론을 위한 회귀 테스트 (regression testing) 및 관측성 (observability) (Python, 의존성 없음)

모든 에이전트 프레임워크는 무엇이 일어났는지 기꺼이 알려줄 것입니다. 여기 토큰이 있고, 여기 도구 호출 (tool calls)이 있으며, 여기 트레이스 워터폴 (trace waterfall)이 있습니다. 하지만 그들 중 거의 어떤 것도 두 실행 사이에서 무엇이 변했는지, 그리고 그 변화가 회귀 (regression)인지 여부는 알려주지 않습니다.

그것이 바로 DProvenanceKit가 채우는 격차입니다. 이 도구는 에이전트의 각 실행을 쿼리 가능하고 차이 비교 (diffable)가 가능한 트레이스로 변환한 다음, 드리프트 (drift)에 실제로 대응할 수 있는 접점을 제공합니다:

실행 (Run) → 기록 (Record) → 쿼리 (Query) → 차이 비교 (Diff) → 회귀 탐지 (Detect regressions) → CI에서 게이트 역할 (Gate in CI)

핵심은 순수 Python 표준 라이브러리입니다. 제3자 의존성 (third-party dependencies)이 전혀 없습니다 (sqlite3, contextvars, threading, json, hashlib).
이는 Swift 라이브러리를 충실하게 포팅한 것이며, 두 라이브러리는 막연한 기대가 아니라 고정된 교차 언어 준수 사양 (cross-language conformance spec)에 의해 동작적으로 동일하게 유지됩니다.

한 가지 예시를 통한 설명입니다. 연구 에이전트 (research agent)가 지원 질문에 답변합니다. 정상적인 "골든 (golden)" 실행은 계획 (plan) → 검색 (search) → 순위 지정 (rank) → 검증 (verify) → 결정 (decide) 과정을 거칩니다. 이후의 PR이 이를 조용히 망가뜨립니다. 에이전트가 검색 도구를 루프 돌리고 검증을 건너뛰게 됩니다. 실행 가능한 하나의 스크립트 (python examples/end_to_end_demo.py)를 통해 모든 계층에서 이를 잡아내는 과정을 확인해 보세요:

── 1. 에이전트의 두 번의 실행 기록 ───────────────────────
golden: 5 단계 ext{['plan', 'search', 'rank', 'verify', 'decide']}
candidate: 8 단계 ext{['plan', 'search', 'search', 'search', 'search', 'search', 'search', 'decide']}
── 2. 의심스러운 패턴 쿼리 (검색은 수행했으나 검증은 수행하지 않음) ──
매칭된 실행: 1건 ext{['research-agent · PR-42']}
── 3. golden 실행 대비 candidate 검증 (Gate) ──────────
판정: REGRESSION (심각도 high, 강도 0.95)
제거된 핵심 단계: ext{['rank', 'verify']}
── 4. 즉시 사용 가능한 이상 징후 규칙 (Out-of-the-box anomaly rules) ───────────────────────
! [tool_drop:verify] 필수 단계 'verify'가 기록되지 않았습니다.
! [looping:search] 'search' 단계가 6회 반복되었습니다 (> 허용치 3회).
── 5. 구조적 차이 (Structural diff) ────────────────────────────────────
rank (Retriever) 제거 @seq 2
verify (Verifier) 제거 @seq 3
search (Retriever) 추가 @seq 2..6
OK — 모든 계층의 일치: candidate가 퇴보함 (verify 누락, search 반복).

이것이 작동하는 이유: 각 실행은 지문(fingerprint), 즉 에이전트 실행 경로의 구조적 정체성을 가집니다. 서로 달라지는(도구가 다른 순서로 호출되거나, 검색 단계가 건너뛰어지는 등) 두 실행은 서로 다른 지문을 생성합니다. 이는 LLM을 루프에 포함하지 않고도 계산할 수 있는 저렴하고 결정론적인(deterministic) 회귀 신호입니다. 단순히

LangChain / LangGraph 어댑터 — 콜백 (callbacks)이 자동으로 스팬 트리 (span tree)가 됩니다.
OpenAI Agents SDK — 한 번의 등록 (store)으로 모든 실행이 캡처됩니다.

프레임워크를 사용하지 않나요? 일반 함수에 @traced 데코레이터를 사용하세요 (동기(sync), 비동기(async), 제너레이터(generators) 모두 작동합니다). 캡처는 결함 방지(failure-proof) 설계로 되어 있어 — 코드의 동작을 변경하거나 예외(exceptions)를 삼키지 않습니다.

from dprovenancekit import InMemoryTraceStore, traced, traced_run, record_event

@traced
def search(query): ...

@traced
def answer(question, sources): ...

with traced_run(store, context_id="ticket-42"):
sources = search(question)
record_event("plan.chosen", {"strategy": "rag"})
reply = answer(question, sources)

패키지에 포함된 다른 기능들: 패리티 스위트 (parity suite)에 의해 동기화된 두 가지 백엔드 (in-memory + WAL SQLite) 상의 단일 쿼리 DSL; 결정론적 재생 (deterministic replay); 부하 차단 (load-shedding)이 조용히 일어나지 않도록 하는 우선순위 인식 백프레셔 (priority-aware backpressure); 공유 가능한 HTML 회귀 보고서 (regression reports); 그리고 8개의 표준 시나리오와 5개의 적대적 (adversarial) 시나리오 전반에서 Precision/Recall/F1 = 1.000을 기록하며 Swift 구현체와 케이스별로 일치하는 검증 코퍼스 (validation corpus). 총 168개의 테스트.

Apache-2.0. SDK와 모든 CI 툴링은 오픈 소스입니다. 대시보드를 원할 경우 별도로 호스팅되는 시각화 도구 (스팬 트리, 페이로드 검사기, side-by-side 시맨틱 디프)가 있지만, 이는 필수가 아닙니다 — 위의 모든 기능은 터미널에서 오프라인으로 실행됩니다.

pip install dprovenancekit
python examples/end_to_end_demo.py # 전체 아크(arc), 자기 검증(self-asserting)

핑거프린팅/얼라이먼트 (fingerprinting/alignment) 모델이나 교차 언어 부합 (cross-language conformance) 접근 방식에 대한 질문은 언제든 환영합니다 — 이 부분이 개발 과정에서 가장 흥미로운 지점이었습니다.