icd10-coder 0.2.2

ICD-10 unified coder — deterministic ICD-10-CM (diagnosis) + ICD-10-PCS (procedure) code mapping with bundled CMS 2025 data

ICD-10 Unified Coder

진단(ICD-10-CM)과 시술(ICD-10-PCS)을 하나의 CLI/스킬로 매핑하는 통합 코딩 도구. 한국어·영문 의료 용어를 표준 ICD-10 코드로 변환한다. LLM 단독 대비 hallucination 없는 결정론적 조회.

icd10-cm + icd10-pcs 두 프로젝트를 통합한 배포 패키지. (SNOMED CT는 라이선스/규모 문제로 별도 유지 — 아래 참고.)

설치

pip install icd10-coder

데이터(CMS 2025, ~72MB)가 패키지에 번들되어 별도 다운로드가 필요 없다. 런타임 의존성 없음 (파이썬 표준 라이브러리 sqlite3만 사용).

구성

icd10_coder/                       # 설치되는 파이썬 패키지
├── coder.py                       # 통합 CLI 구현
└── data/                          # 배포물은 SQLite .db 두 개로 일원화
    ├── icd10cm.db        (22MB)  ICD-10-CM ~97K 진단코드 + FTS + ko_terms(한↔영)
    └── icd10pcs.db       (50MB)  ICD-10-PCS ~68K + 인덱스 + GEMs + 트리
                                  + abbreviations(약어) + bp_siblings + compound_sets(복합)
.claude/skills/icd10-coder/SKILL.md  # Claude Code 스킬 (라우팅 포함)
scripts/coder.py                     # 구 호출 경로 호환 shim
data_src/                            # DB 빌드 소스(배포 제외): abbreviations.tsv, body_part_hierarchy.json

데이터는 모두 SQLite에 통합되어 배포본은 .db 두 개뿐(느슨한 데이터 파일 없음). 한국어 용어(ko_terms)는 kmed 의학용어 사전에서 보강(SNOMED ID 제거, 한↔영 텍스트만).

사용법

설치 후 icd10-coder 명령(또는 python -m icd10_coder)을 사용한다.

icd10-coder dx   "type 2 diabetes with neuropathy"   # 진단 → CM
icd10-coder dx -k "심방세동"                          # 한국어
icd10-coder proc "laparoscopic cholecystectomy"      # 시술 → PCS
icd10-coder proc -k "복강경 담낭절제술"               # 한국어 (복합어 분해)
icd10-coder code 0FT44ZZ                             # 코드 상세 (CM/PCS 자동 판별)
icd10-coder code E11.40
icd10-coder hierarchy I48                            # 계층 탐색

서브커맨드 별칭: dx=cm=d, proc=pcs=p, code=c, hierarchy=h. 예: icd10-coder cm "심방세동", icd10-coder pcs "appendectomy".

자동 분류: 서브커맨드 없이 입력하면 CM·PCS를 병렬 조회해 더 잘 맞는 쪽으로 자동 라우팅한다 (코드 형태면 code로 위임). 강제하려면 cm/pcs를 명시.

icd10-coder "laparoscopic cholecystectomy"   # → [auto-route] ... ICD-10-PCS
icd10-coder "atrial fibrillation"            # → [auto-route] ... ICD-10-CM
icd10-coder 0FT44ZZ                          # → 코드 상세 (자동 판별)

Claude Code 스킬로는 python scripts/coder.py ... 호출도 그대로 동작한다(shim).

dx/code/hierarchy는 결정론적 조회. proc는 PCS 알파벳 인덱스 + GEMs + body-part 열거 브리지로 후보 컨텍스트를 출력하고, LLM(스킬)이 7자리 코드를 조립한다.

PCS 검색 파이프라인 (proc)

icd10-pcs 프로젝트의 v2 검색 개선이 내장돼 있다:

1. 인덱스 표제어 직접 조회 (Cholecystectomy → 0FT4)
2. 노이즈 단어 필터 + 수술 어간 우선 + round-robin FTS
3. 3자리 접두사 → body part 열거 브리지 (0GT → 0GTK 복원)
4. 출처순 정렬된 후보 접두사 + 트리 실재 코드 제시

벤치마크(gpt-oss-120b, 195건, SNUH/MOVER)에서 이 개선으로 TOP-5 정확도 29% → 47%.

데이터 라이선스

ICD-10-CM / ICD-10-PCS 모두 CMS 퍼블릭 도메인 → 자유 배포 가능.

통합 범위 메모

• 포함: ICD-10-CM(진단) + ICD-10-PCS(시술). 동일 패턴·공개 도메인·합계 72MB.
• 미포함: SNOMED CT. 이유 — (1) 규모(snomed.db 412MB + FAISS 2.8GB), (2) SNOMED/UMLS 라이선스 제약(자유 배포 불가), (3) 작업 종류가 다름(엔티티 스팬 추출+링킹). 향후 UMLS CUI 크로스워크(이 ICD 코드 ↔ SNOMED 개념)를 라이선스 보유 환경에서 별도 계층으로 추가 가능.