충돌 감지기 (conflict-detector)
문서 집합에서 모순을 찾는 독립 실행형 스킬입니다. 각 문서(경로 / 인라인 텍스트 / 인라인 JSON)를 로드하고, 사실을 추출한 후, 문서 간 규칙 엔진이 정규화된 키로 클레임을 짝지어 불일치를 표시합니다.
필수 작업 흐름
의존성 부트스트랩 (첫 사용 시)
첫 실행 전, 이 스킬의 런타임 의존성을 확인하세요.
- 핵심: 순수 표준 라이브러리 — 설치 불필요.
- 선택 사항:
PyYAML(설정/입력이.yaml일 때만 필요; JSON 입력은 표준 라이브러리만으로 작동).
PyYAML이 없고 입력이 YAML인 경우 사용자에게 알리고
pip install pyyaml 설치 여부를 물으세요. 사용자가 명시적으로 동의한 후에만 설치하세요.
절대 글로벌 환경에 동의 없이 설치하지 마세요.
-
YAML 설정 파일 (
config/examples/two_docs.yaml참조)을 로드합니다. -
모든
documents[].value/documents[].path에 접근 가능한지 확인합니다. -
python -m src.cli run --config <path> [--format json,csv,md]를 실행합니다. -
수준별 충돌 개수를 보고하고 사용자를
./conflicts/conflicts_<run_id>.*파일로 안내합니다.
사용 시점
- 두 개 이상의 문서, 데이터셋 또는 추출된 사실 테이블을 서로 모순 검사해야 할 때.
- 사용자가 "충돌 감지", "모순 찾기", "클레임 교차 검증"을 요청하거나 "이 문서들이 일치하는지" 물을 때.
- 여러 출처에 동일한 클레임(숫자, 상태, 명명된 사실)이 나타나 이를 비교해야 할 때.
- 문서에서 추출한 사실 테이블의 내부 일관성을 신뢰하기 전에 감사해야 할 때.
사용 예시
# 실행 전 설정 파일 검증 (빠름, 보고서 미작성).
python -m src.cli validate --config config/examples/two_docs.yaml
# 설정이 해석하는 문서 소스 목록 확인.
python -m src.cli list-docs --config config/examples/two_docs.yaml
# 탐지 실행; 출력 형식 선택 (기본값: json).
python -m src.cli run --config config/examples/two_docs.yaml --format json,csv,md
보고서는 ./conflicts/conflicts_<run_id>.{json,csv,md}에 작성됩니다.
JSON은 기계 판독 가능한 계약 형식입니다.
오류 처리
- 설정 파일 오류 (
validate가 0이 아닌 코드로 종료) - 보고된 필드를 수정하고 재검증하세요. 스키마 위반을 수동으로 편집하지 마세요. - 문서 소스에 접근 불가 - 실행이 중단되며 문제의
documents[]항목을 명시합니다. 경로나 인라인 값을 확인하고 재시도하세요. - 충돌 없음 - 유효하고 보고 가능한 결과(빈 보고서)이며 오류가 아닙니다. 재실행 대신 명시적으로 알리세요.
- 예상치 못한 종료 코드 - 메시지를 그대로 보고하세요. 수동으로 문서를 비교하는 방식으로 대체하지 마세요.
감지 수준
| 수준 | 종류 | 심각도 | 예시 |
|---|---|---|---|
entity | numeric_mismatch, boolean | 높음 | speed = 10 vs speed = 20 |
clause | categorical | 중간 | status = "active" vs status = "archived" |
argument | categorical (텍스트) | 낮음 | 일치하지 않는 자유 텍스트 줄 |
제약 사항
- 추출은 키-값 중심입니다. 자유 텍스트 단락은
argument수준(줄 단위 비교)에서만 참여합니다. - 단위 정규화는 테이블 기반(
unit_map)입니다. 사용자 정의 단위 규칙은 설정을 통해 제공해야 합니다.