homeclaw/.smallclaw/databases/docs/howto.md

치과 용어 사전 (dental_dict) — 작업 가이드

디렉터리 구조 (.smallclaw/databases/)

dental_dict.db        SQLite DB (terms / categories / references_tb + FTS5)
config.py             경로·엔드포인트·API 키 위치 (하드코딩 금지, 여기서만 관리)
manage.py             단일 진입점 — 모든 작업은 서브커맨드로
workflow_terms.py     용어 추가 로직
workflow_images.py    이미지 매핑 로직 (9개 소스)
workflow_verify.py    이미지 적합성 검증 로직
seeds/                용어 seed JSON 파일 (JSONC: // 주석 허용)
scratch/              1회성 스크립트·로그·결과 작업 공간 (git-ignore, /tmp 대체)
docs/howto.md         이 문서
docs/archive_image_rounds/   완료된 라운드 스크립트·결과 보관
docs/archive_validation/     모델 비교·검증 결과 데이터 보관
dental_images/        다운로드된 이미지 (517MB) — git 미추적

명령어

cd .smallclaw/databases

python3 manage.py stats                     # 카테고리별 용어/이미지 커버리지
python3 manage.py add-terms --all           # seeds/ 의 모든 JSON 임포트
python3 manage.py add-terms seed_perio.json # 특정 seed 파일만
python3 manage.py add-images --source all   # 9개 소스 전체 이미지 매핑
python3 manage.py add-images --source pmc --pmc-category 치주
python3 manage.py verify --category 교정 --fix   # 잘못 매핑된 이미지 검증·제거
python3 manage.py reassign                  # 플레이스홀더 초기화 후 PMC 재배정

각 서브커맨드의 옵션은 manage.py <명령> --help 참조.

용어 추가 (add-terms)

seed 파일은 seeds/ 의 JSON 배열. 항목은 korean 필수, 나머지(english, latin, abbreviation, definition, category, synonyms, related_ids, pmids, icd_code, notes)는 선택. korean 또는 english 가 이미 있으면 건너뛰므로 재실행해도 안전. // 줄 주석 사용 가능.

이미지 매핑 (add-images)

--source all 실행 순서:

1. Kaggle 로컬 데이터셋
2. Roboflow 로컬 COCO JSON
3. Hugging Face 로컬 데이터셋
4. Radiopaedia URL 매핑
5. ITU 카탈로그 (placeholder)
6. Roboflow REST API (추가 프로젝트)
7. Zenodo REST API
8. Mendeley Data API
9. NLM Open-i (PMC figure-level 색인, 캡션을 검증 hint로 사용)
10. PMC Open Access figure URL (article HTML 스크레이핑)
11. Wikimedia Commons (가장 마지막, 가장 느림)

PMC·Open-i는 이미지 커버리지가 낮은 카테고리부터 자동 처리 (정적 목록 없이 매 실행 시 DB에서 동적 계산). 특정 카테고리만 처리하려면 --pmc-category / --openi-category.

Open-i (--source openi) — 카테고리별 50개 단위 권장:

python3 manage.py add-images --source openi --openi-category 구강병리 \
        --max-openi 50 --log scratch/openi_$(date +%Y%m%d_%H%M).log

각 term에 대해 영문명 + "dental" 로 검색, 상위 5장의 캡션을 검증 모델 (VERIFY_MODEL, 현재 qwen3.5)에 hint 로 주어 첫 통과 이미지를 즉시 저장.

--log <path> — add-images, verify, reassign 공통. stdout/stderr를 지정 파일에 동시 기록. 로그는 scratch/ 에 두는 게 컨벤션.

검증 후 저장: 모든 소스는 저장 전에 vision 모델로 이미지 적합성을 검증한다 (workflow_verify.verify_updates). PMC·Wikimedia는 원래부터 인라인 검증을 했고, 나머지 소스(kaggle/roboflow/huggingface/roboflow_api/zenodo/mendeley)는 수집한 후보를 일괄 검증해 부적합 건을 버린 뒤 commit 한다. Radiopaedia는 이미지가 아닌 문서 URL을 source_url에 저장하므로 검증 대상이 아니다. 검증을 건너뛰려면 --no-verify (Ollama 미동작 시나 빠른 대량 실행용 — PMC·Wikimedia는 항상 검증).

이미지 검증 (verify)

이미 image_url 이 있는 용어를 vision 모델(Ollama)로 재검사. --fix 를 주면 부적합 매핑을 image_url = NULL 로 비워서 다음 add-images 실행 시 다시 채움. 1회성 라운드 배정 스크립트는 docs/archive_image_rounds/ 에 보관됨.

작업 디렉터리 규칙

새 ad-hoc 스크립트·로그·결과 JSON은 /tmp 가 아니라 scratch/ 에 만든다. 재부팅에 안전하고 프로젝트와 함께 이동한다. 작업이 끝나면:

• 보존 가치 있음 → docs/archive_image_rounds/ (라운드 스크립트류) 또는 docs/archive_validation/ (검증 결과 JSON) 로 이동.
• 보존 가치 없음 → 삭제.

이미지 디렉터리 / 심링크

게이트웨이는 image_url 의 /api/files/uploads/dental_images/... 경로를 workspace/uploads/dental_images 심링크를 통해 서빙한다. 이 심링크는 → .smallclaw/databases/dental_images 를 가리키며 git에 추적되지 않으므로 새 환경에서는 수동 재생성이 필요하다:

ln -s ../../.smallclaw/databases/dental_images workspace/uploads/dental_images

주의사항

• DB 쓰기 패턴: 모든 함수는 수집 후 일괄 commit() (루프 안 증분 쓰기 금지)
• 진행 출력: 백그라운드 스크립트는 print(..., flush=True) 필수
• Wikimedia: 429 오류 시 자동 30초 대기, --delay 6 이상 권장
• PMC: --pmc-delay 0.4 이하로 낮추면 NCBI 차단 위험
• 이미 매핑된 용어는 건너뜀 (image_url IS NULL OR image_url = '' 조건)
• API 키는 .smallclaw/{roboflow,huggingface}_api_key.txt, .smallclaw/kaggle_api_token.txt — git-ignore 처리됨, 커밋 금지