luke_scribe/docs/verification-checklist.md

luke_scribe 전체 구현 검증 체크리스트

브랜치: feat/full-platform · 기준 문서: .omc/plans/consensus-luke-scribe-stt-api.md (v2.3) 검증 환경: CPU-only, ffmpeg/GPU/Redis 미설치 → mock 기반 검증 (사용자 승인 범위)

범례: ✅ 통과 · ⬜ 미확인 · ❌ 실패

1. 기반 (scaffold & config)

• pyproject.toml — 패키지 메타, 의존성(optional extras), ruff 설정
• .env.example — 전체 설정 키 문서화 (LUKESCRIBE_ 프리픽스)
• run.sh — venv 생성 + 설치 + 서버 실행 원스톱
• src/luke_scribe/config.py — pydantic-settings, 모델/장치/큐/상한/보관/LLM/터널 설정
• src/luke_scribe/errors.py — typed 오류 계층 (코드 + retryable + HTTP 매핑)
• src/luke_scribe/__init__.py — 패키지 버전

2. 하드웨어 감지 (devices)

• devices/vram_probe.py — GPU/시스템 정보 조회 (nvidia-ml-py, psutil)
• devices/profile.py — DeviceProfile 모델 (등급/정밀도/워커수/경고)
• devices/manager.py — T0~T3 능력 등급, 정밀도 결정, 워커수 산정, override 검증
• CPU-only 폴백 + 경고 (auto 모드)

3. 엔진 (engine)

• engine/base.py — TranscriptionOptions/TranscriptionOutcome 계약
• engine/faster_whisper_engine.py — faster-whisper 래퍼, lazy 세그먼트 + 협조적 취소
• engine/model_registry.py — 모델 다운로드/캐시/오프라인 처리
• engine/owner.py — EngineOwner 단일 GPU 소유자, 우선순위 락, OOM 강등 체인(2회 캡, 영속화)
• 실시간 가설 스텁 (emit_hypothesis)

4. 오디오 (audio)

• audio/ingest.py — ffprobe 형식 검증, 4h/2GB 상한, ffmpeg 16kHz 스트리밍 정규화
• 종료 경로 임시파일 정리 + 취소 시 프로세스 그룹 kill
• audio/vad.py — 레인별 VAD 소유자 계약, 상태형 스트리밍 VAD

5. 잡 큐 (jobqueue)

• jobqueue/jobs.py — Job 상태머신 (queued→processing→terminal, CAS, lease)
• jobqueue/broker.py — InProc 브로커 + Redis/RQ(no-fork) 브로커 + 폴백
• jobqueue/cancel.py — 협조적 취소 토큰
• jobqueue/worker.py — 워커 (리스 하트비트, progress throttle, 크래시 복구 reconciler)
• jobqueue/redis_broker.py — Redis 구현 (설치 시 import, 미설치 폴백)

6. 파이프라인 (pipeline)

• pipeline/batch.py — 인제스트→전사→후처리→결과 조립, 종료 경로 정리
• pipeline/realtime.py — LocalAgreement (prefix 일치, 중복 확정 방지, 단조 타임스탬프, 버퍼 절단)

7. 후처리 (postprocess)

• postprocess/glossary.py — 도메인 용어 복원 (span-aware, 이중 매칭 방지)
• postprocess/rules.py — 표기 규칙 (vLLM 공백, 공백 축소)
• postprocess/confidence.py — 신뢰도 플래그/게이트
• postprocess/llm.py — LLM 보정 (기본 off, allowlist SSRF 가드, 감사 로그)
• postprocess/pipeline.py — 모드별 조합 (none/glossary/rules/llm)

8. 결과 저장 (results)

• results/models.py — TranscriptResult v1 스키마 (불변 계약, 확장 필드)
• results/store.py — UUID 키 저장, 경로 트래버설 차단, 심볼릭 링크 거부, 원자적 쓰기
• results/formats.py — JSON/TXT/SRT/VTT 렌더링
• results/retention.py — 7일 TTL (터미널 상태만, ISO/float 타임스탬프, mtime 폴백)
• privacy-first: 전사 완료 후 원본 오디오 즉시 삭제 (delete_source, delete_derived)

9. API (api)

• api/app.py — 앱 팩토리, lifespan(브로커/reconciler/모델 프로비저닝/터널/세션 가드)
• 오류→HTTP 매핑 (401/403/404/413/422/429/500 envelope)
• api/deps.py — KeyStore (peppered HMAC 다이제스트, 상수시간 비교, 평문 미저장)
• 스코프 강제 + Job 소유권 (남의 job 접근 403)
• api/schemas.py — 요청/응답 스키마
• api/routes/jobs.py — 생성(202)/조회/결과/취소, 4h/2GB 413, 큐 만재 429
• api/routes/admin.py — /health(공개), /v1/system, /v1/models (admin 스코프)
• api/routes/stream.py — WebSocket 실시간 (init 인증, 프레임/세션 상한, 유휴 타임아웃)

10. CLI (cli)

• cli.py — detect/transcribe/bench/serve/key 생성 (typer + rich)
• benchmark/ — turbo vs large-v3 벤치마크 러너/메트릭/매니페스트

11. 운영 산출물 (ops)

• docker/Dockerfile.cpu / Dockerfile.gpu / docker-compose.yml
• connectivity/tunnel.py — Cloudflare Quick Tunnel
• observability/ — 로깅(JSON 옵션) + 메트릭
• diarization/ — pyannote 화자 분리 스텁
• README.md — 설치/사용법/API/CLI 문서
• docs/schemas/transcript-result-v1.schema.json — 결과 JSON 스키마
• benchmarks/manifest.yaml.example, samples/README.md

12. 테스트 & 품질

• 단위 테스트: devices, engine owner, jobs/broker, metrics, postprocess, realtime, formats, store, keystore, ingest
• 통합 테스트: worker 수명주기/취소/크래시복구, API 인증/소유권/큐/결과
• 127개 테스트 전체 통과
• ruff lint + format 클린
• 코드 리뷰 반영 (프라이버시 계약, 보관 갭, Redis 오류 필드, 완료 순서, 유휴 타임아웃, 중복 확정)

---

실행 검증 (이 환경에서 직접 실행한 것)

# pytest 결과
127 passed, 1 warning in 0.32s

# ruff
All checks passed!  |  68 files already formatted (FORMAT CLEAN)

# import 검증
40/40 모듈 import 성공

# CLI
luke-scribe --help        → detect/transcribe/bench/serve/key 정상
luke-scribe detect        → device=cpu | ct=int8 | tier=T0
luke-scribe key --create  → 1회 키 출력 + 다이제스트 64자 hex만 저장 (평문 없음)

# API 스모크 (TestClient — 전부 PASS)
health          → PASS (status=ok, model_ready=false)
no-key 401      → PASS
bad-key 401     → PASS
scope 403       → PASS
create 202      → PASS
job get 200     → PASS
result 409(미완료) → PASS
cancel 200      → PASS
oversize 413    → PASS
queue-full 429  → PASS (Retry-After: 5 헤더 포함)

# 산출물
README/run.sh/pyproject/.env.example/Docker×2/compose/schema/manifest → 전부 존재
schema JSON valid · pyproject 파싱 OK (extras 6종) · run.sh 구문 OK · compose YAML valid