@dssp/dcsp 1.0.2 → 1.0.6

package/python/inspection_ai_engine_handoff/__main__.py

@@ -0,0 +1,169 @@
+"""시공감리 AI 검측 — operato-runner 진입점.
+
+action 값으로 두 기능을 분기한다:
+  - "plan-shots": 체크리스트 → 통합 촬영 가이드 (activities.generate_shot_guide)
+  - "inspect":    체크리스트 + 현장 사진들 → 자동 판정 (activities.run_inspection)
+
+사진은 operato-runner 파일 업로드(input_files) 또는 image_urls 로 전달한다.
+"""
+import io
+import json
+import os
+import urllib.request
+
+script_dir = os.path.dirname(os.path.abspath(__file__))
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv(os.path.join(script_dir, ".env"))
+except ImportError:
+    pass
+
+# HEIC/HEIF 지원 (아이폰·아이패드 기본 촬영 포맷)
+try:
+    from pillow_heif import register_heif_opener
+    register_heif_opener()
+except ImportError:
+    pass
+
+from PIL import Image
+
+from activities import generate_shot_guide, run_inspection
+from checklist import CHECKLIST_VERSION, validate_checklist
+
+MAX_IMAGES = int(os.environ.get("INSPECTION_API_MAX_IMAGES", "8"))
+MAX_BYTES = int(os.environ.get("INSPECTION_API_MAX_BYTES", str(15 * 1024 * 1024)))
+
+
+def _download(url: str, headers: dict = None) -> bytes:
+    # 사진을 URL에서 다운로드하여 바이트로 반환
+    req = urllib.request.Request(url, headers=headers or {"User-Agent": "inspection-ai/1.0"})
+    with urllib.request.urlopen(req, timeout=120) as resp:
+        return resp.read()
+
+
+def _load_images(input: dict) -> list:
+    """input_files(runner 파일 업로드) 또는 image_urls 에서 PIL 이미지를 로드한다."""
+    blobs: list[tuple[str, bytes]] = []
+
+    for f in input.get("input_files") or []:
+        path = (f.get("path") or "").strip()
+        if path:
+            with open(path, "rb") as fp:
+                blobs.append((f.get("filename") or os.path.basename(path), fp.read()))
+
+    headers = input.get("headers") or None
+    for url in input.get("image_urls") or []:
+        if url:
+            blobs.append((url, _download(url, headers=headers)))
+
+    if not blobs:
+        raise ValueError("사진이 없습니다 (input_files 또는 image_urls 필요).")
+    if len(blobs) > MAX_IMAGES:
+        raise ValueError(f"이미지 개수 초과 (최대 {MAX_IMAGES}장).")
+
+    images = []
+    for i, (name, data) in enumerate(blobs, 1):
+        if not data:
+            raise ValueError(f"빈 파일: image #{i} ({name})")
+        if len(data) > MAX_BYTES:
+            raise ValueError(f"파일 크기 초과 image #{i} ({len(data)} > {MAX_BYTES} bytes)")
+        try:
+            images.append(Image.open(io.BytesIO(data)).convert("RGB"))
+        except Exception as e:
+            raise ValueError(f"이미지 디코딩 실패 image #{i} ({name}): {e}")
+    return images
+
+
+def _parse_checklist(input: dict) -> list:
+    """checklist 를 파싱/검증한다. 배열 또는 JSON 문자열 모두 허용."""
+    checklist = input.get("checklist")
+    if isinstance(checklist, str):
+        checklist = json.loads(checklist)
+    if not checklist:
+        raise ValueError("checklist 가 필요합니다 (검측요청서 항목 배열).")
+    ok, err = validate_checklist(checklist)
+    if not ok:
+        raise ValueError(f"체크리스트 유효성 검증 실패: {err}")
+    return checklist
+
+
+def main(input):
+    """
+    operato-runner에서 호출되는 메인 함수.
+
+    Args:
+        input (dict):
+            - 'action' (str): "plan-shots" | "inspect" (기본: 사진 있으면 inspect, 없으면 plan-shots)
+            - 'checklist' (list|str): 검측요청서 [{item_id, text, category?, criteria?}] (필수)
+            - 'input_files': runner 파일 업로드 시 자동 주입 (inspect용 사진)
+            - 'image_urls' (list, 선택): 사진 URL 목록 (input_files 대신 사용 가능)
+            - 'headers' (dict, 선택): 사진 다운로드 시 HTTP 헤더
+
+    Returns:
+        dict: {"status": "success", "action": ..., "result": {...}}
+              plan-shots → {shots:[{shot_no,target,how}], total_shots, markdown}
+              inspect    → {items, items_sorted, groups, summary, summary_markdown, ...}
+    """
+    try:
+        raw_input = input
+        # input 키로 몇 겹 감싸져 들어와도 checklist 가 나올 때까지 벗김
+        while (
+            isinstance(input, dict)
+            and "checklist" not in input
+            and isinstance(input.get("input"), dict)
+        ):
+            input = input["input"]
+
+        if not isinstance(input, dict):
+            return {
+                "status": "error",
+                "error": "input 이 객체가 아닙니다.",
+                "received_type": type(raw_input).__name__,
+            }
+
+        # runner는 input_files를 최상위에 주입하므로, 벗겨낸 경우에도 유지
+        if isinstance(raw_input, dict) and raw_input is not input and raw_input.get("input_files"):
+            input.setdefault("input_files", raw_input["input_files"])
+
+        checklist = _parse_checklist(input)
+
+        has_images = bool(input.get("input_files") or input.get("image_urls"))
+        action = (input.get("action") or "").strip() or ("inspect" if has_images else "plan-shots")
+
+        if action == "plan-shots":
+            guide = generate_shot_guide(checklist)
+            return {
+                "status": "success",
+                "action": action,
+                "result": {"checklist_version": CHECKLIST_VERSION, **guide},
+            }
+
+        if action == "inspect":
+            images = _load_images(input)
+            result = run_inspection(checklist, images)
+            return {"status": "success", "action": action, "result": result}
+
+        return {"status": "error", "error": f"알 수 없는 action: {action} (plan-shots | inspect)"}
+
+    except Exception as e:
+        return {"status": "error", "error": f"처리 중 오류가 발생했습니다: {str(e)}"}
+
+
+if __name__ == "__main__":
+    import sys
+    if len(sys.argv) > 1:
+        # 명령행 인자로 JSON 입력 받기
+        input_data = json.loads(sys.argv[1])
+    else:
+        # 기본 테스트 입력 (plan-shots)
+        input_data = {
+            "action": "plan-shots",
+            "checklist": [
+                {"item_id": "C-01", "text": "청소상태는 양호한가?", "category": "수장공사 · 바닥 먹매김"},
+                {"item_id": "C-02", "text": "문틀/창틀의 수직, 수평 상태 확인", "category": "수장공사 · 바닥 먹매김"},
+            ],
+        }
+
+    result = main(input_data)
+    print(json.dumps(result, ensure_ascii=False, indent=2))

package/python/inspection_ai_engine_handoff/activities.py

@@ -0,0 +1,147 @@
+"""「AI 검측」 액티비티 진입점.
+
+시공감리 플랫폼의 단일 「AI 검측」 버튼이 돌리는 흐름을 함수로 모았습니다.
+화면(단계) ↔ 함수 ↔ 결과가 1:1 로 대응되어, 연동 시 이 파일만 보면 됩니다.
+(기존 로직 파일들은 '부품'이고, 이 파일이 '버튼이 호출하는 진입점' 입니다.)
+
+────────────────────────────────────────────────────────────
+[AI 검측] 흐름
+
+  1단계) 촬영 가이드 화면
+         "전체가 보이게 한 장 찍어주세요" + 촬영 가이드 + 진행바
+         → generate_shot_guide(checklist)
+
+  2단계) 사진 촬영 후 → 분석 결과 화면
+         · 자동 판정됨 / 추가 촬영 필요 / 수동 확인 으로 분류
+         · '추가 촬영 필요'(보류) 항목은 reason 에 어떤 사진이 더 필요한지 안내
+         → run_inspection(checklist, images)
+
+  (재촬영) 추가 사진을 더해 run_inspection 을 다시 호출하면 재판정.
+────────────────────────────────────────────────────────────
+"""
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+from PIL import Image
+
+from engine import (
+    _ROUTING_LABEL,
+    _VERDICT_SHORT,
+    build_summary_markdown,
+    inspect_all,
+)
+from shot_planner import build_plan_markdown, plan_shots, plan_to_dict
+
+
+def generate_shot_guide(checklist: Sequence[dict], *, client=None) -> dict:
+    """[AI 검측 · 1단계] 촬영 가이드 생성.
+
+    입력: 검측요청서 항목 [{item_id, text, category, criteria(선택)}]
+    처리: 항목별 처리방식(사진판독/측정) 분석 → 최소 매수 촬영지시 생성
+          (측정이 필요한 항목이 있으면 정면·수평 등 촬영 요구가 지시문에 반영됨)
+    출력: {
+        "shots": [{ "target": 찍을 대상, "how": 촬영 방법 }, ...],
+        "markdown": 화면에 그대로 띄울 수 있는 가이드 마크다운,
+    }
+    """
+    if client is None:
+        from openai import OpenAI
+        client = OpenAI()
+    plan = plan_shots(checklist, client=client)
+    shots = plan_to_dict(plan)["shots"]
+    return {
+        "shots": shots,                  # 각 항목에 shot_no(1-base) 포함 → 슬롯 UI 용
+        "total_shots": len(shots),       # "shot_no / total_shots" 진행바 표기
+        "markdown": build_plan_markdown(plan, list(checklist)),
+    }
+
+
+def _group_results(items: Sequence[dict]) -> dict:
+    """결과 화면용 분류 (시나리오의 '자동 판정 / 추가 촬영 필요' 그룹).
+
+    - auto_judged    : 적합/부적합 (AI가 판정 완료)
+    - needs_recapture: 보류 (사진 더 필요 — reason 에 안내)
+    - manual_check   : AI 미지원/오류 (감리자 수동 확인)
+    """
+    auto, recapture, manual = [], [], []
+    for it in items:
+        v = it.get("verdict")
+        if v in ("pass", "fail"):
+            auto.append(it["item_id"])
+        elif v == "hold":
+            recapture.append(it["item_id"])
+        else:  # pending(AI 미지원), error
+            manual.append(it["item_id"])
+    return {
+        "auto_judged":     auto,
+        "needs_recapture": recapture,
+        "manual_check":    manual,
+    }
+
+
+def _supervisor_mark(verdict: Optional[str]) -> Optional[str]:
+    """감리자 적합/부적합 칸 자동 채울 값. 보류·AI미지원·오류는 None(미체크)."""
+    return {"pass": "적합", "fail": "부적합"}.get(verdict or "")
+
+
+def _ai_report(item: dict) -> str:
+    """검측 체크리스트 '첨부자료'에 'AI판단' 문서로 붙일 텍스트."""
+    v = item.get("verdict")
+    lines = [
+        "[AI 판단]",
+        f"검사항목: {item.get('text', '')}",
+        f"판정: {_VERDICT_SHORT.get(v, v)}",
+    ]
+    method = _ROUTING_LABEL.get(item.get("routing", ""), "")
+    if method:
+        conf = item.get("confidence")
+        if conf is not None and item.get("routing") == "vlm":
+            method += f" (AI 확신도 {conf:.2f})"
+        lines.append(f"판정 방식: {method}")
+    if item.get("observation"):
+        lines.append(f"관찰 내용: {item['observation']}")
+    if item.get("reason"):
+        lines.append(f"판정 사유: {item['reason']}")
+    if item.get("used_images"):
+        lines.append(f"근거 사진: {item['used_images']}")
+    return "\n".join(lines)
+
+
+def run_inspection(
+    checklist: Sequence[dict],
+    images: Sequence[Image.Image],
+    *,
+    client=None,
+) -> dict:
+    """[AI 검측 · 2단계] 사진 분석 → 항목별 판정.
+
+    입력: 검측요청서 + 현장 사진(복수)
+    처리: 항목별 처리방식 분석(라우팅) → 사진판독(VLM)/측정(CV) 병렬 판정
+    출력: 검사 결과 dict
+          - items / items_sorted : 항목별 판정. 각 항목에 검사 등록용 필드 포함:
+              · verdict        : 기계값 (pass/fail/hold/pending/error)
+              · supervisor_mark: 감리자 칸 자동 채울 값 ("적합"/"부적합"/None=미체크)
+              · used_images    : 근거 사진 번호 (첨부용)
+              · ai_report      : '첨부자료'에 붙일 AI판단 문서 텍스트
+          - groups            : {auto_judged, needs_recapture, manual_check} (화면 그룹용)
+          - elapsed_total_sec : 전체 소요시간
+          - cost              : 추정 비용
+          - summary_markdown  : 감리자용 한글 결과(그대로 렌더 가능)
+    """
+    if client is None:
+        from openai import OpenAI
+        client = OpenAI()
+    result = inspect_all(checklist, images, client=client)
+
+    # 검사 등록(write-back)에 바로 쓸 필드를 항목마다 추가:
+    #   supervisor_mark : 감리자 칸 자동 채울 값 (적합/부적합/None)
+    #   ai_report       : '첨부자료'에 붙일 AI판단 문서 텍스트
+    #   used_images     : (이미 있음) 첨부할 근거 사진 번호
+    for it in result.get("items", []):
+        it["supervisor_mark"] = _supervisor_mark(it.get("verdict"))
+        it["ai_report"] = _ai_report(it)
+
+    result["groups"] = _group_results(result.get("items", []))
+    result["summary_markdown"] = build_summary_markdown(result)
+    return result

package/python/inspection_ai_engine_handoff/api.py

@@ -0,0 +1,273 @@
+"""시공감리 AI — HTTP API (FastAPI).
+
+엔드포인트:
+  GET  /health         서버 상태
+  GET  /cv-models      CV 모델 레지스트리 조회
+  POST /plan-shots     체크리스트 → 통합 촬영 가이드
+  POST /route          체크리스트 → 항목별 라우팅 결정 (선택)
+  POST /inspect        체크리스트 + 사진들 → 자동 판정
+
+실행:
+  python api.py
+  → http://localhost:8000  (Swagger: /docs)
+"""
+from __future__ import annotations
+
+import io
+import json
+import os
+import time
+from typing import List, Optional
+
+from fastapi import FastAPI, File, Form, HTTPException, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from PIL import Image
+from pydantic import BaseModel, Field
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
+
+# HEIC/HEIF 지원 (아이폰·아이패드 기본 촬영 포맷). pillow-heif 가 설치돼 있으면 등록.
+try:
+    from pillow_heif import register_heif_opener
+    register_heif_opener()
+except ImportError:
+    pass
+
+from activities import generate_shot_guide, run_inspection
+from checklist import CHECKLIST_VERSION, validate_checklist
+from cv_model_registry import list_models, summarize_for_router
+from router import decision_to_dict, route_all
+
+
+DEFAULT_PORT = int(os.environ.get("INSPECTION_API_PORT", "8000"))
+MAX_IMAGES   = int(os.environ.get("INSPECTION_API_MAX_IMAGES", "8"))
+MAX_BYTES    = int(os.environ.get("INSPECTION_API_MAX_BYTES", str(15 * 1024 * 1024)))
+ALLOWED_ORIGINS = os.environ.get("INSPECTION_API_ALLOWED_ORIGINS", "*").split(",")
+
+app = FastAPI(
+    title="시공감리 AI API",
+    version="1.0.0",
+    description=(
+        "시공감리 플랫폼 (아이패드/웹) 에서 동적 검측요청서 + 현장 사진을 받아\n"
+        "통합 촬영 가이드 → 항목별 라우팅 (VLM | CV 모델) → 자동 판정 결과를 반환합니다.\n\n"
+        "체크리스트가 매 요청마다 들어오므로 공종 무관 (목공사, 마감, 콘크리트, 방수 등).\n"
+        "CV 모델은 외부 cv_models.json 레지스트리에서 관리."
+    ),
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=ALLOWED_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ─── 응답/요청 모델 ──────────────────────────────────────────────────────
+
+class HealthResponse(BaseModel):
+    ok: bool
+    checklist_version: str
+    server_time: float
+    n_cv_models: int
+
+
+class ChecklistItemModel(BaseModel):
+    item_id:  str
+    text:     str
+    category: Optional[str] = ""
+
+
+class CVModelPublic(BaseModel):
+    model_id: str
+    name: str
+    description: str
+    applicable_to: list[str]
+    required_shots: list[str]
+    output_keys: list[str]
+    status: str
+
+
+class CVModelsResponse(BaseModel):
+    schema_version: str
+    n_models: int
+    models: list[CVModelPublic]
+
+
+class PlanShotsRequest(BaseModel):
+    checklist: list[ChecklistItemModel] = Field(
+        ...,
+        description="검측요청서 항목 리스트. {item_id, text, category?}.",
+    )
+
+
+# ─── 엔드포인트 ───────────────────────────────────────────────────────────
+
+@app.get("/health", response_model=HealthResponse)
+def health():
+    return HealthResponse(
+        ok=True,
+        checklist_version=CHECKLIST_VERSION,
+        server_time=time.time(),
+        n_cv_models=len(list_models()),
+    )
+
+
+@app.get("/cv-models", response_model=CVModelsResponse)
+def get_cv_models():
+    """등록된 CV 모델 레지스트리 조회.
+
+    플랫폼 측에서 "이 시스템이 어떤 측정 모델을 갖고 있나" 확인할 때 사용.
+    레지스트리 파일 자체 수정은 서버 운영자가 cv_models.json 을 직접 편집.
+    """
+    summaries = summarize_for_router()
+    return CVModelsResponse(
+        schema_version="1.0",
+        n_models=len(summaries),
+        models=[CVModelPublic(**s) for s in summaries],
+    )
+
+
+@app.post("/plan-shots")
+def post_plan_shots(payload: PlanShotsRequest):
+    """체크리스트 → 통합 촬영 가이드 (LLM 생성).
+
+    아이패드 앱: 감리자가 검측요청서를 받으면, 이 엔드포인트를 먼저 호출해서
+    "이렇게 N장 찍으세요" 가이드를 화면에 띄움. 그 다음 사진을 모아서 /inspect.
+    """
+    checklist = [it.model_dump() for it in payload.checklist]
+    ok, err = validate_checklist(checklist)
+    if not ok:
+        raise HTTPException(status_code=400, detail=f"체크리스트 유효성 검증 실패: {err}")
+
+    try:
+        from openai import OpenAI
+        client = OpenAI()
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"OpenAI 클라이언트 초기화 실패 (OPENAI_API_KEY 확인): {e}",
+        )
+
+    guide = generate_shot_guide(checklist, client=client)   # [AI 검측 1단계]
+    return JSONResponse({
+        "checklist_version": CHECKLIST_VERSION,
+        **guide,
+    })
+
+
+@app.post("/route")
+def post_route(payload: PlanShotsRequest):
+    """체크리스트 → 항목별 라우팅 결정 (LLM).
+
+    /inspect 가 내부적으로 자동 실행하지만, 플랫폼 측에서 '어떤 항목이 CV로 가는지'
+    미리 확인하고 싶을 때 사용 가능.
+    """
+    checklist = [it.model_dump() for it in payload.checklist]
+    ok, err = validate_checklist(checklist)
+    if not ok:
+        raise HTTPException(status_code=400, detail=f"체크리스트 유효성 검증 실패: {err}")
+
+    try:
+        from openai import OpenAI
+        client = OpenAI()
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"OpenAI 클라이언트 초기화 실패: {e}",
+        )
+
+    decisions = route_all(checklist, client=client)
+    return JSONResponse({
+        "checklist_version": CHECKLIST_VERSION,
+        "decisions": [decision_to_dict(d) for d in decisions],
+    })
+
+
+@app.post("/inspect")
+async def post_inspect(
+    images:    List[UploadFile] = File(..., description="현장 사진 1~N장. JPEG/PNG/WebP/HEIC."),
+    checklist: Optional[str]    = Form(
+        None,
+        description=(
+            "검측요청서 JSON 문자열 (필수). 배열 형식: "
+            '[{"item_id":"...", "text":"...", "category":"...", "criteria":"..."}, ...].'
+        ),
+    ),
+):
+    """현장 사진들 + 체크리스트 → 자동 판정.
+
+    multipart/form-data:
+      - images:    파일 (반복 가능). 1~MAX_IMAGES 장.
+      - checklist: 검측요청서 JSON 문자열 (필수).
+
+    응답 구조는 HANDOFF.md 참고.
+    """
+    if not checklist:
+        raise HTTPException(status_code=400, detail="checklist 가 필요합니다 (검측요청서 JSON).")
+    try:
+        checklist_items = json.loads(checklist)
+    except json.JSONDecodeError as e:
+        raise HTTPException(
+            status_code=400,
+            detail=f"checklist JSON 파싱 실패: {e}",
+        )
+
+    ok, err = validate_checklist(checklist_items)
+    if not ok:
+        raise HTTPException(status_code=400, detail=f"체크리스트 유효성 검증 실패: {err}")
+
+    if not images:
+        raise HTTPException(status_code=400, detail="이미지가 첨부되지 않았습니다.")
+    if len(images) > MAX_IMAGES:
+        raise HTTPException(
+            status_code=413,
+            detail=f"이미지 개수 초과 (최대 {MAX_IMAGES}장).",
+        )
+
+    pil_images: list[Image.Image] = []
+    for i, up in enumerate(images, 1):
+        data = await up.read()
+        if not data:
+            raise HTTPException(status_code=400, detail=f"빈 파일: image #{i}")
+        if len(data) > MAX_BYTES:
+            raise HTTPException(
+                status_code=413,
+                detail=f"파일 크기 초과 image #{i} ({len(data)} > {MAX_BYTES} bytes).",
+            )
+        try:
+            img = Image.open(io.BytesIO(data)).convert("RGB")
+        except Exception as e:
+            raise HTTPException(
+                status_code=400,
+                detail=f"이미지 디코딩 실패 image #{i}: {e}",
+            )
+        pil_images.append(img)
+
+    try:
+        from openai import OpenAI
+        client = OpenAI()
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"OpenAI 클라이언트 초기화 실패 (OPENAI_API_KEY 확인): {e}",
+        )
+
+    result = run_inspection(checklist_items, pil_images, client=client)   # [AI 검측 2단계]
+    return JSONResponse(result)
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "api:app",
+        host="0.0.0.0",
+        port=DEFAULT_PORT,
+        reload=False,
+    )

package/python/inspection_ai_engine_handoff/checklist.py

@@ -0,0 +1,53 @@
+"""체크리스트 스키마 검증 + 버전.
+
+운영에서는 시공감리 플랫폼이 매 요청마다 검측요청서를 HTTP body 로 전송합니다.
+이 파일은 그 입력의 **형식 검증(validate_checklist)** 과 **버전** 만 담당합니다.
+(샘플/데모용 체크리스트 데이터는 배포본에 포함하지 않습니다.)
+
+체크리스트 항목 스키마 (최소):
+    {
+      "item_id":  "고유 ID (문자열, 필수)",
+      "text":     "한국어 검사 항목 원문 (필수)",
+      "category": "상위 분류 (선택)",
+      "criteria": "검사 기준 (선택) — 있으면 판정에 반영"
+    }
+
+라우팅/CV 핸들러 정보는 보내지 마세요 — 엔진의 LLM 라우터가 그때그때 결정합니다.
+"""
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class ChecklistItem(TypedDict, total=False):
+    item_id:  str    # 필수
+    category: str    # 권장
+    text:     str    # 필수
+    criteria: str    # 선택 (검사 기준)
+
+
+CHECKLIST_VERSION = "inspection_engine_v1"
+
+
+def validate_checklist(items: list[dict]) -> tuple[bool, str]:
+    """플랫폼이 보낸 체크리스트가 최소 스키마를 만족하는지 확인.
+
+    Returns:
+        (ok, error_message). ok=True 면 error_message 는 빈 문자열.
+    """
+    if not isinstance(items, list):
+        return False, "체크리스트는 배열이어야 합니다."
+    if not items:
+        return False, "체크리스트가 비어있습니다."
+    seen_ids: set[str] = set()
+    for i, it in enumerate(items):
+        if not isinstance(it, dict):
+            return False, f"items[{i}] 는 객체여야 합니다."
+        if not it.get("item_id") or not isinstance(it["item_id"], str):
+            return False, f"items[{i}].item_id 가 비어있거나 문자열이 아닙니다."
+        if not it.get("text") or not isinstance(it["text"], str):
+            return False, f"items[{i}].text 가 비어있거나 문자열이 아닙니다."
+        if it["item_id"] in seen_ids:
+            return False, f"items[{i}].item_id 중복: {it['item_id']}"
+        seen_ids.add(it["item_id"])
+    return True, ""

package/python/inspection_ai_engine_handoff/cv_handlers.py

@@ -0,0 +1,46 @@
+"""CV 핸들러 공용 타입 — CVResult 정의.
+
+모든 CV 모델 폴더의 handler.py 는 이 CVResult 를 반환해야 합니다:
+
+    from cv_handlers import CVResult
+
+    def run(images):
+        ...
+        return CVResult(verdict="pass", reason="...", measurements={...})
+
+실제 모델 코드는 cv_models/<모델>/handler.py 에 두세요 (이 파일에 추가하지 않습니다).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, List, Literal, Optional, Sequence
+
+from PIL import Image
+
+Verdict = Literal["pass", "fail", "hold", "pending"]
+
+
+@dataclass
+class CVResult:
+    """CV 모델의 출력 표준 형식.
+
+    Attributes:
+        verdict: 판정 결과.
+            - "pass"   : 명확히 적합
+            - "fail"   : 명확히 부적합
+            - "hold"   : 모델이 판정 보류 (입력 조건 미달 등)
+            - "pending": 모델 미연결/미구현 (stub 단계)
+        reason: 판정 근거 (한국어 1~2문장).
+        measurements: 모델이 산출한 측정값/메타데이터 (JSON 직렬화 가능 타입만).
+        used_images: 실제 사용한 이미지 인덱스 (1-base) 리스트.
+        overlay_b64: 시각화 결과(검출선/마스크 등) PNG base64. 없으면 None.
+    """
+    verdict: Verdict
+    reason: str
+    measurements: dict = field(default_factory=dict)
+    used_images: List[int] = field(default_factory=list)
+    overlay_b64: Optional[str] = None
+
+
+# CV 핸들러 시그니처: (현장 사진 리스트) -> CVResult
+CVHandler = Callable[[Sequence[Image.Image]], CVResult]