@dssp/dcsp 1.0.2 → 1.0.6

package/python/inspection_ai_engine_handoff/HANDOFF.md

@@ -0,0 +1,541 @@
+# 시공감리 AI 엔진 — 인계 문서
+
+> 받는 분: 시공감리 플랫폼을 개발하시는 분께.
+> 이 문서 하나로 통합에 필요한 정보 다 들어 있습니다. 질문 있으시면 알려주세요.
+
+---
+
+## 1. 이 엔진이 무엇을 하는가
+
+시공감리 플랫폼이 보낸 **(검측요청서 + 현장 사진)** 을 받아서 검사항목별로 **자동 판정**을 돌려주는 HTTP API 입니다.
+
+```
+[시공감리 플랫폼]                          [이 엔진]
+   검측요청서 (체크리스트) 받음
+        │
+        ├─ POST /plan-shots ──────────▶  ① 항목들을 LLM 이 분석
+        │   { checklist: [...] }          ② "이 검측은 N장으로 다음과 같이 찍어주세요" 응답
+        │   ◀ shot plan + 마크다운
+        │                                  → 앱이 화면에 가이드 표시
+        │
+   감리자가 사진 촬영
+        │
+        └─ POST /inspect ─────────────▶  ③ 항목별로 LLM 라우터가 처리방식 결정
+            (multipart)                    - "사진으로 판단 가능" → VLM (GPT-Vision)
+            images: [...]                  - "수치 측정 필요" → CV 모델 레지스트리에서 매칭
+            checklist: JSON string         ④ 각각 실행 → 항목별 verdict 반환
+            ◀ items: [{verdict, reason, ...}]
+                                            → 앱이 결과를 검측 체크리스트 화면에
+                                              "감리자 적합/부적합" 자동 채움
+```
+
+핵심 특성:
+- **체크리스트가 동적** — 매 요청마다 다른 항목을 받음. 공종 무관 (목공사, 마감, 콘크리트, 방수, 전기, 설비 등).
+- **항목별 처리방식이 동적** — LLM 라우터가 항목 텍스트만 보고 VLM/CV 중 결정.
+- **CV 모델은 외부 레지스트리** — `cv_models.json` 한 파일과 핸들러 함수 정의 만으로 추가/교체.
+- **Stateless** — DB·세션 없음. 결과 저장은 플랫폼 측에서.
+
+---
+
+## 2. 빠른 시작 (10분)
+
+```bash
+# 1) 압축 풀고 들어가서
+cd inspection_ai_engine
+
+# 2) 의존성
+pip install -r requirements.txt
+
+# 3) .env 확인 — 이미 임시 OpenAI 키가 들어있습니다.
+#    (운영 배포 전에 반드시 본인 키로 교체)
+cat .env
+
+# 4) 서버 실행
+python api.py
+#  → http://localhost:8000
+#  → Swagger UI: http://localhost:8000/docs
+```
+
+검증:
+```bash
+# 헬스체크
+curl http://localhost:8000/health
+
+# 검측요청서(checklist) + 사진으로 동작 확인
+curl -X POST http://localhost:8000/inspect \
+  -F "images=@some_photo.jpg" \
+  -F 'checklist=[{"item_id":"C-01","text":"청소상태는 양호한가?"}]'
+```
+
+> Swagger UI(`/docs`)에서 각 엔드포인트를 바로 시험해볼 수 있습니다.
+
+---
+
+## 3. 통합 시점에 알아둘 것
+
+### 검측요청서 화면 (스크린샷 기반) 의 통합 지점
+
+기존 검측 체크리스트 UI 에 버튼 2개 + 결과 처리 1곳 추가하시면 됩니다:
+
+| 위치 | 동작 | API 호출 |
+|---|---|---|
+| 상단 우측 "사진촬영" 옆 | **📋 AI 촬영 가이드** 버튼 | `POST /plan-shots` (체크리스트 전체) → 응답의 `markdown` 그대로 띄우거나 `shots` 로 커스텀 UI |
+| "사진촬영" 으로 사진들 모은 후 | **🤖 AI 자동 판정** 버튼 | `POST /inspect` (체크리스트 + 사진들) → `items_sorted` 로 각 항목 결과 |
+| `/inspect` 응답 처리 | 결과를 UI 에 반영 | `감리자` 컬럼 라디오 자동 선택 + `조치사항` 텍스트 채우기. `verdict=fail/hold` 면 빨강 강조. |
+
+### 권장 배치 구조 (보안)
+
+```
+[감리자 아이패드 앱] ── HTTPS ──▶ [당신네 플랫폼 백엔드] ── HTTP(내부망) ──▶ [이 엔진]
+                                       │                                       │
+                                       │ 인증/로깅/결과 DB 저장                  │ OpenAI API 호출
+                                       │                                       ▼
+                                       │                                  ┌──────────┐
+                                       │                                  │ OpenAI   │
+                                       │                                  └──────────┘
+```
+
+**OpenAI 키를 아이패드 앱에 넣지 마세요.** 반드시 플랫폼 백엔드에서 이 엔진으로 프록시.
+
+---
+
+## 4. HTTP API 상세
+
+서버 기본 `http://localhost:8000` (Swagger: `/docs`).
+
+### GET /health
+
+```json
+{
+  "ok": true,
+  "checklist_version": "inspection_engine_v1",
+  "server_time": 1716700000.123,
+  "n_cv_models": 2
+}
+```
+
+### GET /cv-models
+
+현재 등록된 CV 모델 레지스트리 조회.
+
+```json
+{
+  "schema_version": "1.0",
+  "n_models": 2,
+  "models": [
+    {
+      "model_id": "frame_alignment_v0",
+      "name": "수직·수평 편차 측정 (예제)",
+      "description": "...",
+      "applicable_to": ["수직 상태", "수평 상태", ...],
+      "required_shots": ["full_front"],
+      "output_keys": ["vertical_deviation_deg", "horizontal_deviation_deg", ...],
+      "status": "stub"
+    }
+  ]
+}
+```
+
+`status`:
+- `"stub"` — 메타만 등록돼 있고 실제 핸들러는 미구현. verdict 는 항상 `"pending"`.
+- `"ready"` — 실제 모델 동작 중.
+
+### POST /plan-shots
+
+체크리스트 → 통합 촬영 가이드 생성.
+
+**요청 body (JSON):**
+```json
+{
+  "checklist": [
+    { "item_id": "WD-FN-01", "text": "최종 마감상태 육안 확인", "category": "목공사 · 공사 완료" },
+    { "item_id": "WD-PT-01", "text": "도장마감 상태 확인 (얼룩, 색상 균일성)", "category": "목공사 · 공사 완료" }
+  ]
+}
+```
+
+**응답 (200):**
+```json
+{
+  "checklist_version": "inspection_engine_v1",
+  "shots": [
+    {
+      "shot_id": "full_front",
+      "title": "전체 풀샷 (정면)",
+      "instruction": "1~2m 떨어져 부재 전체가 한 프레임에 들어오도록...",
+      "must_show": ["부재 사방", "마감 표면 전체"],
+      "priority": 1,
+      "covers": ["WD-FN-01", "WD-PT-01"]
+    }
+  ],
+  "coverage": { "WD-FN-01": ["full_front"], "WD-PT-01": ["full_front"] },
+  "rationale": "마감 상태와 도장 균일성 모두 풀샷으로 동시 확인 가능...",
+  "markdown": "## 촬영 가이드\n\n..."
+}
+```
+
+- `priority`: 1=필수, 2=권장, 3=선택.
+- `coverage`: 각 항목을 커버하는 샷 ID 들. 빈 배열인 항목은 LLM 누락 가능성 — UI 에서 경고 표시 권장.
+- `markdown`: 마크다운 그대로 렌더링해도 됨.
+
+### POST /route (선택)
+
+체크리스트 → 항목별 라우팅 결정만 반환. `/inspect` 가 내부적으로 자동 실행하므로 필수 아님. 미리 보고 싶을 때 사용.
+
+**응답:**
+```json
+{
+  "decisions": [
+    {
+      "item_id": "WD-FN-01",
+      "mode": "vlm",
+      "model_id": null,
+      "rationale": "마감상태 육안 확인은 시각적 정성 판정이므로 VLM 적합.",
+      "confidence": 0.91
+    },
+    {
+      "item_id": "GN-VH-01",
+      "mode": "cv",
+      "model_id": "frame_alignment_v0",
+      "rationale": "수직·수평 측정은 정량 수치가 본질. frame_alignment_v0 적합.",
+      "confidence": 0.93
+    }
+  ]
+}
+```
+
+`mode`:
+- `"vlm"` — GPT-Vision 정성 판정.
+- `"cv"`  — CV 모델 호출. `model_id` 가 레지스트리의 모델.
+- `"cv_missing"` — CV 측정 필요하나 레지스트리에 적합 모델 없음. verdict 는 `"pending"` 반환.
+
+### POST /inspect
+
+현장 사진 + 체크리스트 → 자동 판정. **multipart/form-data**.
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `images` | file (반복) | 1~`INSPECTION_API_MAX_IMAGES` 장 (기본 8장). 파일당 최대 15MB. **JPEG/PNG/WebP/HEIC** (아이폰·아이패드 HEIC 그대로 가능). |
+| `checklist` | text (JSON 문자열) | 검측요청서 배열을 JSON 으로 직렬화 **(필수)**. |
+
+**응답 (200):**
+
+```json
+{
+  "checklist_version": "inspection_engine_v1",
+  "n_images": 3,
+  "n_items": 7,
+  "registry_summary": [
+    { "model_id": "frame_alignment_v0", "name": "...", "status": "stub" }
+  ],
+  "routing": [ /* /route 와 같은 구조 */ ],
+  "summary": { "pass": 3, "fail": 1, "hold": 1, "pending": 2, "error": 0, "total": 7 },
+  "items": [
+    {
+      "item_id": "WD-FN-01",
+      "category": "목공사 · 공사 완료",
+      "text": "최종 마감상태 육안 확인",
+      "routing": "vlm",
+      "route_rationale": "정성 판정이므로 VLM 적합.",
+      "route_confidence": 0.91,
+      "verdict": "pass",
+      "confidence": 0.87,
+      "reason": "Image #1 전체에서 마감면 균일, 얼룩/스크래치 미확인.",
+      "observation": "...",
+      "used_images": [1],
+      "elapsed_sec": 14.2
+    },
+    {
+      "item_id": "GN-VH-01",
+      "category": "일반",
+      "text": "주요 부재의 수직·수평 상태 확인 (기울기 측정)",
+      "routing": "cv",
+      "model_id": "frame_alignment_v0",
+      "route_rationale": "수치 측정이 본질.",
+      "route_confidence": 0.93,
+      "verdict": "pending",
+      "reason": "CV 모델 미연결 (담당자 구현 대기).",
+      "measurements": { "stub": true, "n_images_received": 3 },
+      "used_images": [],
+      "overlay_b64": null,
+      "elapsed_sec": 0.0
+    }
+  ],
+  "items_sorted": [ /* FAIL → HOLD → PASS → PENDING → ERROR 순 */ ],
+  "elapsed_total_sec": 41.0,
+  "summary_markdown": "# 시공감리 검사 결과\n\n..."
+}
+```
+
+`elapsed_total_sec`: 검사 전체 소요시간(초). `summary_markdown`: **감리자용 한글 라벨로
+렌더링된** 결과(적합/부적합/보류 등) — 그대로 화면에 띄워도 됩니다.
+
+**verdict (기계값) → 감리자용 한글 라벨 매핑** (UI 에서 이렇게 표시 권장):
+
+| `verdict` | 한글 라벨 | UI 처리 |
+|---|---|---|
+| `pass`    | 🟢 적합 | 감리자 컬럼 "적합" 자동 선택 |
+| `fail`    | 🔴 부적합 | "부적합" + `reason` 을 조치사항에 + 빨강 강조 |
+| `hold`    | 🟡 보류 (추가 확인 필요) | 사람이 직접 판단 — 노랑 강조 |
+| `pending` | ⏳ AI 미지원 (수동 확인) | 자동 측정 기능 미연결 → 수동 판단 |
+| `error`   | ❌ 분석 오류 | `traceback` 로그 + 사람 판단으로 폴백 |
+
+> JSON 의 `verdict`/`routing` 은 **기계값**(영문)으로 고정입니다. 위 한글 라벨은 UI 에서
+> 매핑하거나, `summary_markdown`(이미 한글)을 그대로 사용하세요.
+
+**에러 응답:**
+- 400 — 체크리스트 JSON 파싱 실패, 유효성 검증 실패, 이미지 없음/디코딩 실패.
+- 413 — 파일 개수/크기 초과.
+- 500 — OpenAI 클라이언트 초기화 실패 (`OPENAI_API_KEY` 누락 등).
+
+---
+
+## 5. 호출 예제
+
+### JavaScript (브라우저 또는 Node)
+
+```js
+// Step 1. 촬영 가이드
+const checklist = [
+  { item_id: "WD-FN-01", text: "최종 마감상태 육안 확인", category: "목공사 · 공사 완료" },
+  { item_id: "WD-PT-01", text: "도장마감 상태 확인",     category: "목공사 · 공사 완료" }
+];
+
+const planRes = await fetch("http://localhost:8000/plan-shots", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ checklist }),
+});
+const plan = await planRes.json();
+// → plan.shots[*] 로 UI 구성, plan.markdown 으로 통째 렌더링도 OK
+
+// Step 2. 검사 실행
+const fd = new FormData();
+for (const file of capturedFiles) fd.append("images", file);
+fd.append("checklist", JSON.stringify(checklist));
+
+const inspRes = await fetch("http://localhost:8000/inspect", {
+  method: "POST",
+  body: fd,
+});
+const result = await inspRes.json();
+
+// Step 3. UI 에 반영
+for (const item of result.items_sorted) {
+  const row = ui.findRow(item.item_id);
+  if (item.verdict === "pass") row.setSupervisorVerdict("적합");
+  if (item.verdict === "fail") {
+    row.setSupervisorVerdict("부적합");
+    row.setActionNotes(item.reason);
+  }
+  if (item.verdict === "hold")    row.highlight("yellow");
+  if (item.verdict === "pending") row.markAiUnsupported();
+}
+```
+
+### Python (서버측 프록시)
+
+```python
+import requests
+
+resp = requests.post(
+    "http://engine:8000/inspect",
+    files=[("images", open(p, "rb")) for p in photo_paths],
+    data={"checklist": json.dumps(checklist_items)},
+    timeout=300,
+)
+result = resp.json()
+```
+
+### curl
+
+```bash
+curl -X POST http://localhost:8000/inspect \
+  -F "images=@shot1.jpg" -F "images=@shot2.jpg" \
+  -F 'checklist=[{"item_id":"WD-FN-01","text":"최종 마감상태 육안 확인"}]'
+```
+
+---
+
+## 6. CV 모델 추가하는 법 (폴더 방식)
+
+CV 모델은 `cv_models/` 폴더 아래 **모델마다 자기 폴더**로 등록합니다. 시스템이 시작할 때
+이 폴더를 스캔해 레지스트리를 자동 조립합니다 — **공유 JSON 한 개를 다 같이 편집하지 않으므로**
+충돌·전체 파손 위험이 없습니다. (상세: `cv_models/README.md`)
+
+```
+cv_models/
+├── README.md
+├── _example_frame_alignment/   ← 작성 예시 ('_' 로 시작 → 스캔 제외, 비활성)
+│   ├── model.json
+│   └── handler.py
+└── <내모델_v1>/                ← 실제 모델 (폴더만 두면 자동 등록)
+    ├── model.json              ← 메타데이터
+    └── handler.py              ← def run(images) -> CVResult
+```
+
+**1) 예시 폴더 복사** — `_example_frame_alignment/` 를 통째로 복사해 **'_' 없는** 이름으로:
+   예) `cv_models/my_alignment_v1/`
+
+**2) `model.json` 채우기** (handler 경로는 안 적음 — 자동 연결):
+
+```json
+{
+  "model_id": "my_alignment_v1",
+  "name": "내가 만든 수직·수평 모델",
+  "description": "...",
+  "applicable_to": ["수직", "수평", "기울기"],
+  "input_spec":   { "required_shots": ["full_front"], "min_images": 1, "notes": "정면·수평정렬 필수" },
+  "output_schema": {
+    "vertical_deviation_deg":   { "type": "float", "desc": "..." },
+    "horizontal_deviation_deg": { "type": "float", "desc": "..." }
+  },
+  "verdict_rules": {
+    "tolerance": { "vertical_deviation_deg": 1.0, "horizontal_deviation_deg": 1.0 },
+    "logic": "두 편차 모두 tolerance 이내면 pass, 어느 하나라도 초과면 fail."
+  },
+  "status": "ready",
+  "version": "1.0.0"
+}
+```
+
+**3) `handler.py` 의 `run()` 구현:**
+
+```python
+from typing import Sequence
+from PIL import Image
+from cv_handlers import CVResult
+
+def run(images: Sequence[Image.Image]) -> CVResult:
+    # 모델 실행, 측정값 계산
+    return CVResult(
+        verdict="pass",                           # pass | fail | hold | pending
+        reason="수직 0.3°, 수평 0.2° — 둘 다 허용 1.0° 이내.",
+        measurements={"vertical_deviation_deg": 0.3, "horizontal_deviation_deg": 0.2},
+        used_images=[1],
+        overlay_b64=None,                         # 검출 시각화 PNG base64 (선택)
+    )
+```
+
+**4) 서버 재시작** — 끝. 라우터가 `description`/`applicable_to`/`output_keys` 를 보고 자동 매칭. 체크리스트 코드는 손 안 댐.
+
+### 모델 작성 시 주의
+
+- 함수 이름은 반드시 `run`, 시그니처는 `(images: Sequence[PIL.Image]) -> CVResult`. CVResult 정의는 `cv_handlers.py`.
+- `handler.py` 없이 `model.json` 만 두면 자동으로 `stub` 처리(결과 항상 `pending`). 메타만 먼저 등록 후 코드는 나중에 추가 가능.
+- 도면 등 외부 입력이 필요하면 모델 내부(또는 모델 폴더)에서 해결.
+- `verdict_rules.logic` 은 사람용 문서. 실제 판정 로직은 `run()` 안에서.
+- 폴더 하나의 `model.json` 이 깨져도 그 폴더만 건너뛰고 나머지는 정상 동작.
+
+---
+
+## 7. 파일 구성
+
+```
+inspection_ai_engine/
+├── api.py                  # HTTP API (FastAPI) — 플랫폼이 호출하는 진입점
+├── activities.py           # ★ 「AI 검측」 액티비티(화면↔함수): generate_shot_guide / run_inspection
+├── engine.py               # 검사 오케스트레이션
+├── checklist.py            # 입력 형식 검증(validate_checklist) + 버전
+├── shot_planner.py         # LLM 통합 샷 플래너 (촬영 가이드)
+├── shot_catalog.py         # 자주 쓰는 샷 카탈로그 (LLM 힌트)
+├── router.py               # LLM 항목별 라우터 (사진판독 | 측정 결정)
+├── vlm.py                  # GPT vision 판정 핸들러
+├── cv_handlers.py          # CVResult 정의 (CV 핸들러 공용 출력 타입)
+├── cv_model_registry.py    # 레지스트리 로더 (cv_models/ 폴더 스캔 + 핸들러 동적 import)
+├── cv_models/              # ★ CV 모델 저장소 (모델마다 폴더 1개, 자동 스캔)
+│   ├── README.md
+│   └── _example_frame_alignment/   # 작성 예시 (비활성)
+├── requirements.txt
+├── .env                    # API 키 (별도 전달 — 패키지에는 .env.example 만 포함)
+├── .env.example
+├── .gitignore
+├── HANDOFF.md              # 이 문서
+└── README.md
+```
+> 참고: 데모 UI(`demo_ui.py`)·비용추적(`cost_tracker.py`)·샘플 체크리스트는 검증/시연용이라
+> 배포 패키지에서 제외했습니다. 엔진은 이들 없이 정상 동작합니다.
+
+---
+
+## 8. 환경변수
+
+| 변수 | 기본값 | 의미 |
+|---|---|---|
+| `OPENAI_API_KEY` | (필수) | OpenAI 키. |
+| `OPENAI_MODEL` | `gpt-5.5` | VLM/라우터/플래너 공용. |
+| `REASONING_EFFORT` | `high` | `none\|low\|medium\|high\|xhigh`. |
+| `INSPECTION_API_PORT` | `8000` | HTTP 서버 포트. |
+| `INSPECTION_API_MAX_IMAGES` | `8` | 한 요청당 최대 이미지 수. |
+| `INSPECTION_API_MAX_BYTES` | `15728640` | 파일 한 장 최대 크기 (15MB). |
+| `INSPECTION_API_ALLOWED_ORIGINS` | `*` | CORS 화이트리스트. 운영에선 도메인 명시 권장. |
+| `CV_MODELS_DIR` | `./cv_models` | CV 모델 폴더 경로 (모델별 폴더를 스캔). |
+| `DEMO_UI_PORT` | `7870` | Gradio 데모 포트. |
+
+---
+
+## 9. 성능/비용 메모
+
+`/inspect` 의 LLM 호출 (항목 6개·VLM 4개 기준):
+
+| 단계 | 호출 수 | 비고 |
+|---|---|---|
+| 항목별 라우팅 | **1** (텍스트, 배치) | 전체 항목을 한 번에 분류 |
+| VLM 판정 | M (vlm 라우팅된 항목, 비전) | **동시 실행**(스레드풀) |
+| CV 판정 | 0 (LLM) | CV 모델 자체 추론 시간만 |
+
+- 라우팅은 1회 배치 호출, VLM 판정은 항목들을 **병렬**로 처리 → 전체 시간은 보통
+  **30초~1분** (가장 느린 VLM 1건 + 라우팅). reasoning·이미지 크기에 따라 변동.
+- 응답 dict 에 `elapsed_total_sec`(전체 소요시간)와 `cost`(추정 비용) 포함.
+- 타임아웃은 넉넉히 (3분 이상) 잡아두길 권장.
+
+**속도·비용 더 줄이기:**
+- `REASONING_EFFORT=medium` 또는 `low` (지연·비용 ↓, 미묘한 판정 정확도는 약간 trade).
+- 라우팅 재사용: `/plan-shots`/`/route` 의 결정을 `/inspect` 에 그대로 넘기면 라우팅을
+  한 번만 — 엔진의 `inspect_all(precomputed_decisions=...)` 로 지원 (API 노출은 필요 시 추가).
+
+---
+
+## 10. 트러블슈팅
+
+| 증상 | 원인/해결 |
+|---|---|
+| 500 — `OPENAI_API_KEY` 누락 | `.env` 확인 + 서버 재시작. |
+| 모든 항목이 `vlm` 으로만 가고 `cv` 가 안 골라짐 | 라우터가 `cv_models.json` 의 `applicable_to` / `description` 을 보고 매칭. 등록 키워드를 체크리스트 항목 텍스트에 맞게 확장. |
+| `cv_missing` 이 너무 자주 나옴 | 라우터가 cv 라우팅했는데 모델 없음. `applicable_to` 키워드 확장 또는 새 모델 추가. |
+| `/plan-shots` 의 `coverage` 에 빈 배열 | LLM 이 그 항목을 어느 샷에도 매핑 안 함. UI 에서 경고. 다시 호출하거나 effort 올림. |
+| CORS 에러 | `INSPECTION_API_ALLOWED_ORIGINS` 에 도메인 추가. |
+| 응답이 너무 오래 걸림 | reasoning + 이미지 큼 + high effort + 항목 많음. 타임아웃 5분+. `REASONING_EFFORT` 낮추기. |
+| OpenAI rate limit | 동시 요청 줄이거나 큐 도입. 현재 엔진은 순차 처리. |
+
+---
+
+## 11. 자주 받는 질문
+
+**Q: 체크리스트 항목 ID 는 자유로운가요?**
+A: 네. 문자열이면 뭐든 OK. 한 요청 내 중복만 없으면 됩니다.
+
+**Q: 항목별로 `routing: "vlm"` 같은 힌트를 우리가 강제로 줄 수 있나요?**
+A: 현재 API 는 라우터에 맡깁니다. override 가 필요하면 `/inspect` 에 `route_overrides: {item_id: "vlm"|"cv"}` 같은 필드 추가하면 됩니다 — 요청 주시면 추가합니다.
+
+**Q: 결과 저장은 어디서?**
+A: 엔진은 stateless. 플랫폼 측 DB 에 저장. 같은 검측건의 재검사도 매번 새로 호출.
+
+**Q: 사진을 Base64 로 보낼 수 있나요?**
+A: 현재는 multipart/form-data 만. Base64 JSON 도 받게 추가 가능 — 요청 주세요.
+
+**Q: 결과 스트리밍 (SSE) 은요?**
+A: 미지원. 1~3분 동안 한 번에 반환. 항목별 부분 결과 스트리밍이 필요하면 `/inspect/stream` SSE 엔드포인트 추가 가능.
+
+**Q: 도면을 같이 보낼 수 있나요?**
+A: 현재 API 인터페이스에는 도면 입력이 없습니다. `drawing_match_v0` 같은 도면 비교 CV 모델은 모델 내부에서 사전 등록된 도면을 참조하는 구조. 도면을 요청마다 보내는 API 가 필요하면 `/inspect` 에 `drawings` multipart 필드 추가 가능.
+
+**Q: 인증/권한은 어떻게?**
+A: 엔진 자체에는 없음. 앞단 (플랫폼 백엔드 또는 API 게이트웨이) 에서 처리하시면 됩니다. CORS 만 조심.
+
+**Q: 한 번에 한 명만 호출 가능한가요?**
+A: FastAPI 는 async 라 여러 요청 동시 수용. 다만 OpenAI 호출 자체는 순차. 부하 늘면 worker 늘리거나 큐.
+
+---
+
+문의: (보내실 분 정보)

package/python/inspection_ai_engine_handoff/README.md

@@ -0,0 +1,83 @@
+# 시공감리 AI 엔진
+
+시공감리 플랫폼이 보낸 **검측요청서 + 현장 사진**을 받아 검사항목별로 자동 판정을 돌려주는 HTTP API.
+
+```
+[시공감리 플랫폼]                  [엔진]
+   검측요청서 받음
+        │
+        ├─ POST /plan-shots ────▶  LLM 이 항목들 보고 통합 촬영 가이드 생성
+        │                          → "이렇게 N장 찍으세요"
+        │
+   감리자가 사진 촬영
+        │
+        └─ POST /inspect ───────▶  ① LLM 라우터가 항목별 vlm/cv/cv_missing 결정
+                                    ② VLM 항목: GPT-Vision 정성 판정
+                                    ③ CV  항목: 레지스트리에서 모델 찾아 실행
+                                    → 항목별 verdict (pass/fail/hold/pending/error)
+```
+
+특징:
+- 체크리스트가 **동적** — 공종 무관
+- 항목별 처리 방식이 **LLM 결정** — 사람이 미리 태깅 안 함
+- CV 모델이 **외부 JSON 레지스트리** — 코드 수정 없이 모델 추가
+
+상세 통합 가이드는 **[HANDOFF.md](HANDOFF.md)** 참고.
+
+---
+
+## 빠른 시작
+
+```bash
+# 1. 의존성
+pip install -r requirements.txt
+
+# 2. .env 에 OpenAI 키 (이미 임시 키 들어있음, 운영 전 본인 키로 교체)
+
+# 3. API 서버
+python api.py
+#   → http://localhost:8000      (Swagger: /docs)
+
+# (선택) 데모 UI — 단독 동작 확인용
+python demo_ui.py
+#   → http://localhost:7870
+```
+
+기본 모델 `gpt-5.5` (reasoning). `.env` 의 `OPENAI_MODEL`/`REASONING_EFFORT` 로 변경.
+
+---
+
+## 파일 구성
+
+```
+inspection_ai_engine/
+├── api.py                  # HTTP API (FastAPI) — 플랫폼이 호출하는 진입점
+├── demo_ui.py              # Gradio 데모 UI (검증용)
+├── engine.py               # 검사 오케스트레이션
+├── checklist.py            # 디폴트 샘플 + validate_checklist
+├── shot_planner.py         # LLM 통합 샷 플래너
+├── shot_catalog.py         # 자주 쓰는 샷 카탈로그 (LLM 힌트)
+├── router.py               # LLM 항목별 라우터
+├── vlm.py                  # GPT vision VQA 핸들러
+├── cv_handlers.py          # CVResult 정의 (CV 핸들러 공용 출력 타입)
+├── cv_model_registry.py    # 레지스트리 로더 (cv_models/ 폴더 스캔)
+├── cv_models/              # ★ CV 모델 저장소 (모델마다 폴더 1개, 자동 스캔)
+│   ├── README.md           #    추가 방법 안내
+│   └── _example_frame_alignment/   # 작성 예시 (비활성)
+├── requirements.txt
+├── .env / .env.example
+├── HANDOFF.md              # 통합 가이드 (이거 보세요)
+└── README.md               # 이 파일
+```
+
+---
+
+## CV 모델 추가 (CV 팀)
+
+`cv_models/` 아래 **모델마다 폴더 하나**를 두면 자동 등록됩니다 (공유 파일 편집 없음):
+
+1. `cv_models/_example_frame_alignment/` 복사 → **'_' 없는** 이름으로 (예: `cv_models/my_v1/`).
+2. `model.json` 채우기 + `handler.py` 의 `run(images) -> CVResult` 구현.
+3. 서버 재시작 — 끝.
+
+자세한 내용은 [cv_models/README.md](cv_models/README.md) 또는 [HANDOFF.md §6](HANDOFF.md) 참고.