@dssp/dcsp 1.0.2 → 1.0.6

package/python/inspection_ai_engine_handoff/shot_planner.py

@@ -0,0 +1,278 @@
+"""LLM 기반 촬영지시 생성기.
+
+입력: 임의 체크리스트 (검측요청서) 항목 리스트.
+출력: 최소한의 사진으로 모든 검사항목을 커버하는 촬영지시 목록.
+      각 촬영지시 = { target(무엇: 찍을 대상), how(어떻게: 자연스러운 한 문장) }.
+
+설계:
+  - 촬영지시 전에 라우팅(router.route_all)을 먼저 돌려 각 항목이 VLM 정성판정인지
+    CV 측정모델인지 파악.
+  - CV 항목은 그 모델의 input_spec(정면·카메라 수평정렬 등 촬영요구)을 프롬프트에
+    함께 전달 → 측정 항목이 든 촬영지시의 'how' 문장에 그 요구가 녹아 들어감.
+  - 항목 배정(covers)·판정사유(왜)는 내부적으로만 쓰고 출력에는 노출하지 않음.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Sequence
+
+from vlm import _extract_json, _normalize_message_content
+
+# 비용 추적 (선택). 배포본에 cost_tracker.py 가 없어도 동작하도록 no-op 대체.
+try:
+    import cost_tracker
+except ImportError:
+    class _NoCost:
+        @staticmethod
+        def record(*a, **k): pass
+        @staticmethod
+        def reset(*a, **k): pass
+        @staticmethod
+        def drain(*a, **k): return []
+        @staticmethod
+        def snapshot(*a, **k): return None
+        @staticmethod
+        def snapshot_from(*a, **k): return None
+    cost_tracker = _NoCost()
+
+
+_DEFAULT_MODEL    = os.environ.get("OPENAI_MODEL", "gpt-5.5")
+_REASONING_EFFORT = os.environ.get("REASONING_EFFORT", "high").strip()
+
+
+@dataclass
+class PlannedShot:
+    target: str   # 무엇 — 찍을 대상/부위 (자유 명사구)
+    how: str      # 어떻게 — 자연스러운 한 문장 촬영 지시
+
+
+@dataclass
+class ShotPlan:
+    shots: list[PlannedShot]
+    raw: str = ""   # 디버그용 LLM 원본 응답
+
+
+_PROMPT_TEMPLATE = """당신은 건설현장 시공감리 AI 의 촬영지시 생성기입니다.
+감리자가 찍은 사진은 두 판정기에 입력됩니다.
+- VLM: 사진을 보고 양호/불량을 직접 판단 (일반 화질로 충분).
+- CV 측정모델: 각도·치수를 정량 측정 (정면·카메라 수평정렬·전체 프레임 등 촬영요구가 까다로움).
+
+목표: 아래 검사항목 전부를 **최소한의 사진**으로 빠짐없이 커버하는 촬영지시 목록을 만드세요.
+
+[검사항목 + 판정방식 ({n_items}개)]
+{checklist_block}
+
+촬영지시 생성 규칙:
+1) 누락 0 — 모든 검사항목이 어느 한 촬영지시에 반드시 배정되게 하되, **배정 결과(어느 항목인지)는 출력하지 마세요.**
+2) 최소 매수 — 한 장으로 커버되는 항목은 한 촬영지시로 묶어 사진 수를 최소화하세요. 보통 2~3장.
+3) 사방 쪼개기 금지 — "둘레"는 한 바퀴를 한 촬영지시로 통합하세요. 상·하·좌·우를 각각 따로 만들지 마세요.
+4) CV 촬영요구 강제 — CV 측정 항목이 포함된 촬영지시는 그 모델 요구(정면·카메라 수평정렬·전체 프레임)를
+   'how' 문장에 반드시 녹이세요. 단, 격자·수평계·줄자 같은 도구를 화면에 넣으라는 요구는 하지 마세요.
+5) 최대 4장 초과 금지.
+
+각 촬영지시 형식:
+- target: 찍을 대상/부위. 자유 명사구 (예: "창호 정면 전체", "프레임-벽체 접합부 둘레").
+- how: 자연스러운 **한 문장**의 촬영 지시. 거리 숫자(m, cm)는 쓰지 마세요. 토막 나열(·)도 금지.
+    문장에 자연스럽게 녹여야 할 것:
+      · 프레이밍 — 전체가 한 화면에 들어오게 / 디테일이 보이도록 가까이서
+      · 각도 — 정면 / 좌측면 / 우측면 / 상부 / 하부 중 해당하는 것
+      · CV 측정 항목이 포함되면 — "카메라를 수평·수직으로 맞춰 비스듬하지 않게"
+
+반드시 아래 JSON 객체 하나만 출력하세요. 다른 텍스트/주석/코드블록 금지.
+
+{{
+  "shots": [
+    {{
+      "target": "창호 정면 전체",
+      "how": "창호 전체가 한 화면에 들어오도록 정면에서 카메라를 수평·수직으로 맞춰 비스듬하지 않게 촬영하세요."
+    }},
+    {{
+      "target": "프레임-벽체 접합부 둘레",
+      "how": "창틀과 벽체가 만나는 둘레의 대표·의심 부위가 선명히 보이도록 가까이서 촬영하세요."
+    }}
+  ]
+}}"""
+
+
+# ── 판정방식 주석 (프롬프트 입력용 — 출력에는 노출 안 함) ──────────────────
+
+def _judge_info(item_id: str, decisions_by_id: dict, cv_by_id: dict) -> tuple[str, str]:
+    """item_id → (label, capture_req).
+
+    label: VLM / CV측정(모델) 라벨
+    capture_req: CV 모델의 촬영 요구사항 (CV 일 때만, 아니면 "")
+    """
+    d = decisions_by_id.get(item_id)
+    if d is None or d.mode == "vlm":
+        return ("VLM 정성판정", "")
+    if d.mode == "cv":
+        m = cv_by_id.get(d.model_id)
+        if m is not None:
+            notes = m.input_spec.get("notes", "")
+            req_shots = m.input_spec.get("required_shots", [])
+            cap = f"촬영요구: 샷={req_shots}"
+            if notes:
+                cap += f"; {notes}"
+            return (f"CV측정({m.model_id})", cap)
+        return (f"CV측정({d.model_id})", "")
+    return ("측정필요·적합모델없음(사람판단)", "")
+
+
+def _build_annotated_checklist(checklist: Sequence[dict], decisions_by_id: dict, cv_by_id: dict) -> str:
+    lines = []
+    for it in checklist:
+        cat = it.get("category", "")
+        cat_str = f" ({cat})" if cat else ""
+        label, cap = _judge_info(it["item_id"], decisions_by_id, cv_by_id)
+        line = f"- [{it['item_id']}]{cat_str} {it['text']}\n    → 판정: {label}"
+        if cap:
+            line += f" / {cap}"
+        lines.append(line)
+    return "\n".join(lines) if lines else "(없음)"
+
+
+def _call_text_json(
+    client,
+    prompt: str,
+    *,
+    model: str,
+    max_completion_tokens: int = 2500,
+    reasoning_effort: Optional[str] = None,
+    retries: int = 2,
+) -> tuple[Optional[dict], str]:
+    """텍스트 전용 JSON 응답 호출."""
+    effort = reasoning_effort if reasoning_effort is not None else _REASONING_EFFORT
+    messages = [{"role": "user", "content": prompt}]
+    last_raw = ""
+    for _ in range(retries + 1):
+        kwargs: Dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "max_completion_tokens": max_completion_tokens,
+        }
+        # reasoning 모델이면 reasoning_effort 전달 (chat.completions 정식 파라미터)
+        if effort and effort != "none":
+            kwargs["reasoning_effort"] = effort
+        try:
+            response = client.chat.completions.create(**kwargs)
+            cost_tracker.record(model, getattr(response, "usage", None))
+            raw = _normalize_message_content(response.choices[0].message.content)
+            last_raw = raw
+            parsed = _extract_json(raw)
+            if parsed is not None:
+                return parsed, raw
+        except Exception as e:
+            err_msg = str(e)
+            last_raw = err_msg
+            # reasoning_effort 미지원 모델이면 빼고 재시도. temperature 는 건드리지
+            # 않음 (reasoning 모델은 temperature=0 을 거부함).
+            if "reasoning" in err_msg.lower() or "unsupported" in err_msg.lower():
+                kwargs.pop("reasoning_effort", None)
+                try:
+                    response = client.chat.completions.create(**kwargs)
+                    cost_tracker.record(model, getattr(response, "usage", None))
+                    raw = _normalize_message_content(response.choices[0].message.content)
+                    last_raw = raw
+                    parsed = _extract_json(raw)
+                    if parsed is not None:
+                        return parsed, raw
+                except Exception as e2:
+                    last_raw = f"{err_msg} | retry: {e2}"
+    return None, last_raw
+
+
+def plan_shots(
+    checklist: Sequence[dict],
+    *,
+    client=None,
+    decisions=None,
+    registry=None,
+    model: Optional[str] = None,
+    max_completion_tokens: int = 6000,
+    reasoning_effort: Optional[str] = None,
+) -> ShotPlan:
+    """체크리스트 → 촬영지시 목록.
+
+    Args:
+        decisions: 항목별 라우팅 결정. None 이면 내부에서 router.route_all 로 먼저 라우팅.
+        registry: CV 모델 메타 리스트. None 이면 레지스트리에서 로드.
+    """
+    if not checklist:
+        return ShotPlan(shots=[], raw="체크리스트가 비어있음.")
+
+    if client is None:
+        from openai import OpenAI
+        client = OpenAI()
+    if registry is None:
+        from cv_model_registry import list_models
+        registry = list_models()
+    if decisions is None:
+        from router import route_all
+        decisions = route_all(checklist, client=client, registry=registry)
+    model = model or _DEFAULT_MODEL
+
+    decisions_by_id = {d.item_id: d for d in decisions}
+    cv_by_id = {m.model_id: m for m in registry}
+
+    prompt = _PROMPT_TEMPLATE.format(
+        n_items=len(checklist),
+        checklist_block=_build_annotated_checklist(checklist, decisions_by_id, cv_by_id),
+    )
+    data, raw = _call_text_json(
+        client=client,
+        prompt=prompt,
+        model=model,
+        max_completion_tokens=max_completion_tokens,
+        reasoning_effort=reasoning_effort,
+    )
+
+    if not data or "shots" not in data:
+        return ShotPlan(shots=[], raw=raw)
+
+    shots: list[PlannedShot] = []
+    for s in data.get("shots", []):
+        if not isinstance(s, dict):
+            continue
+        target = str(s.get("target") or "").strip()
+        how = str(s.get("how") or "").strip()
+        if not target and not how:
+            continue
+        shots.append(PlannedShot(
+            target=target or f"촬영지시 {len(shots) + 1}",
+            how=how,
+        ))
+
+    return ShotPlan(shots=shots, raw=raw)
+
+
+def build_plan_markdown(plan: ShotPlan, checklist: Sequence[dict]) -> str:
+    """ShotPlan → 사람용 마크다운 (촬영지시 목록)."""
+    if not plan.shots:
+        return "## 촬영 가이드\n\n_(촬영지시 생성 실패 — 다시 시도해 주세요.)_"
+
+    lines = [
+        "## 촬영 가이드",
+        "",
+        f"검사항목 {len(checklist)}개를 아래 **{len(plan.shots)}장**으로 촬영하세요.",
+        "",
+    ]
+    for i, s in enumerate(plan.shots, 1):
+        lines.append(f"**촬영지시 {i} — {s.target}**")
+        lines.append("")
+        lines.append(s.how)
+        lines.append("")
+    return "\n".join(lines)
+
+
+def plan_to_dict(plan: ShotPlan) -> dict:
+    """ShotPlan → JSON 직렬화 가능한 dict (API 응답용).
+
+    각 촬영지시에 1-base 순번(shot_no)을 부여 — UI 가 "1/N, 2/N" 슬롯을 돌릴 수 있게.
+    """
+    return {
+        "shots": [
+            {"shot_no": i, "target": s.target, "how": s.how}
+            for i, s in enumerate(plan.shots, 1)
+        ],
+    }

package/python/inspection_ai_engine_handoff/vlm.py

@@ -0,0 +1,335 @@
+"""GPT vision 기반 VQA 판정 핸들러 — 검사 항목 정성 판정.
+
+호출 패턴:
+  - max_completion_tokens (not max_tokens)
+  - reasoning={"effort": ...}  파라미터 — temperature 와 상호배타
+  - reasoning 미지원 모델일 경우 자동 fallback
+  - 이미지 URL 에 detail="high"
+  - JSON 파싱 실패 시 retries
+"""
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+from dataclasses import dataclass
+from io import BytesIO
+from typing import Any, Dict, List, Optional, Sequence
+
+from PIL import Image
+
+# 비용 추적 (선택). 플랫폼 배포본엔 cost_tracker.py 가 빠져 있어도 동작하도록 no-op 대체.
+try:
+    import cost_tracker
+except ImportError:
+    class _NoCost:
+        @staticmethod
+        def record(*a, **k): pass
+        @staticmethod
+        def reset(*a, **k): pass
+        @staticmethod
+        def drain(*a, **k): return []
+        @staticmethod
+        def snapshot(*a, **k): return None
+        @staticmethod
+        def snapshot_from(*a, **k): return None
+    cost_tracker = _NoCost()
+
+Verdict = str  # "pass" | "fail" | "hold"
+
+
+@dataclass
+class VLMResult:
+    verdict: Verdict          # 판정 결과
+    confidence: float         # 0.0 ~ 1.0
+    reason: str               # 판정 근거 (한국어)
+    observation: str          # 모델이 사진에서 본 것 (한국어)
+    used_images: List[int]    # 모델이 실제 활용한 이미지 인덱스 (1-base)
+    recapture_shots: list = None  # verdict=="hold" 일 때 재촬영할 샷 목록 [{target, how}]
+    raw: str = ""             # 디버그용 원본 응답
+
+    def __post_init__(self):
+        if self.recapture_shots is None:
+            self.recapture_shots = []
+
+
+_DEFAULT_MODEL    = os.environ.get("OPENAI_MODEL", "gpt-5.5")
+_REASONING_EFFORT = os.environ.get("REASONING_EFFORT", "high").strip()
+
+
+def _pil_to_b64_jpeg(img: Image.Image, max_side: int = 1600, quality: int = 88) -> str:
+    """PIL 이미지를 JPEG base64 로 직렬화. 큰 이미지는 축소."""
+    if img.mode != "RGB":
+        img = img.convert("RGB")
+    w, h = img.size
+    m = max(w, h)
+    if m > max_side:
+        scale = max_side / m
+        img = img.resize((int(w * scale), int(h * scale)), Image.LANCZOS)
+    buf = BytesIO()
+    img.save(buf, format="JPEG", quality=quality)
+    return base64.b64encode(buf.getvalue()).decode()
+
+
+def _extract_json(text: str) -> Optional[dict]:
+    """LLM 출력에서 첫 JSON 객체 추출. 실패 시 None."""
+    if not text:
+        return None
+    m = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.DOTALL)
+    candidate = m.group(1) if m else None
+    if candidate is None:
+        s, e = text.find("{"), text.rfind("}")
+        if s != -1 and e != -1 and e > s:
+            candidate = text[s : e + 1]
+    if not candidate:
+        return None
+    try:
+        return json.loads(candidate)
+    except json.JSONDecodeError:
+        return None
+
+
+def _normalize_message_content(raw: Any) -> str:
+    """OpenAI 응답 content 가 str/list 어떤 형식이든 평탄화."""
+    if raw is None:
+        return ""
+    if isinstance(raw, str):
+        return raw
+    if isinstance(raw, list):
+        parts = []
+        for item in raw:
+            if isinstance(item, dict):
+                t = item.get("text")
+                if isinstance(t, str):
+                    parts.append(t)
+                elif isinstance(t, dict) and isinstance(t.get("text"), str):
+                    parts.append(t["text"])
+            else:
+                t = getattr(item, "text", None)
+                if isinstance(t, str):
+                    parts.append(t)
+        return "".join(parts)
+    t = getattr(raw, "text", None)
+    return t if isinstance(t, str) else str(raw)
+
+
+# 시스템 프롬프트 — 공종 비종속. 항목 텍스트로만 판단.
+_PROMPT_TEMPLATE = """당신은 건설현장 시공감리 AI 입니다.
+여러 공종 (목공사, 마감공사, 콘크리트, 방수, 전기, 설비 등) 의 검사항목을 사진으로 판정합니다.
+
+검사항목 [{item_id}]: {item_text}
+판단 질문: {question}
+
+입력: 현장 사진 {n_images}장 (Image #1 ~ Image #{n_images}).
+여러 장이 주어진 경우 각 사진은 같은 부재/구간의 다른 구도/근접도 사진입니다.
+모든 사진을 종합해서 판정하세요. 단일 사진만으로는 단정할 수 없어도 다른
+사진에서 확인 가능하면 그 사진을 명시(예: "Image #2 좌측 모서리")해서 사용.
+
+[검측 맥락]
+이 사진들은 '시공 진행 중'에 수행되는 감리 검측이다. 완공·최종 인도 상태가 아니다.
+주어진 공종·부위·공정 정보를 보고, 이 검사항목이 '지금 시점에' 무엇을 확인하려는
+것인지 파악한 뒤 판단하라.
+단, '아직 시공 중이니 통과' 같은 식으로 판단을 건너뛰지 마라 —
+청소·보양 등도 그 자체가 검사 대상일 수 있다.
+
+[관찰 기술 원칙]
+observation 과 reason 에 '무엇을·어디서·왜' 를 명확히 하라.
+- 대상: 무엇을 보고 판단했는가 (예: 흰 점, 물자국, 긁힘, 보양필름, 이격)
+- 위치: Image #N 의 어느 부위인가 (예: "Image #1 유리 중앙")
+- 사유: 그것이 왜 적합/부적합 근거가 되는가
+- 확실성: 명확히 보이면 단정, 불확실하면 '추정' 이라고 표시
+정확한 개수·치수(mm)는 사진만으로 알 수 없으니 지어내지 마라.
+('여러 개', '일부', '전반' 같은 정성 표현은 가능하되 실제 본 것에 한정.)
+'오염 다수' 처럼 대상·위치 없이 뭉뚱그리는 것은 금지.
+
+다음 절차를 따르세요.
+1) observation: 위 '관찰 기술 원칙'에 따라, 사진에서 관찰되는 사실을 대상·위치와 함께 서술.
+2) verdict: "pass" / "fail" / "hold" 중 하나.
+   - pass : 명확히 양호/적합.
+   - fail : 명확히 불량/부적합 (구체 증거가 사진에 보일 때).
+   - hold : 사진만으로 단정 불가, 또는 경계선·맥락 불확실. (hold = 사람이 최종 확인)
+   [판정 신중] 명백한 적합/부적합만 pass/fail 로 단정하라. 경계선이거나(정도 판단이
+   갈릴 수 있음), 이 시점에 평가할 항목인지 맥락만으로 불확실하면 단정하지 말고 hold.
+3) confidence: 0.0 ~ 1.0 사이 (본인 판정의 확신도).
+4) reason: 위 판정의 한국어 근거 1~2문장. 대상·위치·사유를 명시하고, 불확실하면 그 이유도.
+5) used_images: 판정 근거로 실제 활용한 이미지 번호 리스트 (예: [1, 2]).
+6) recapture_shots: verdict 가 'hold' 인 경우에만, 판정을 내리려면 어떤 사진을 더
+   찍어야 하는지 목록으로 적어라. 각 원소는 {{"target": 찍을 대상, "how": 촬영 방법}}
+   (촬영 가이드와 같은 형식, 거리 숫자(mm·m)는 쓰지 말 것). hold 가 아니면 빈 배열 [] 로 둔다.
+
+반드시 아래 JSON 객체 하나만 출력하세요. 다른 문장/주석/코드블록 금지.
+
+{{
+  "observation": "<사진에서 본 것>",
+  "verdict": "pass" | "fail" | "hold",
+  "confidence": 0.0,
+  "reason": "<판정 근거>",
+  "used_images": [1],
+  "recapture_shots": [{{"target": "<찍을 대상>", "how": "<촬영 방법>"}}]
+}}"""
+
+
+def _call_vision_json(
+    client,
+    images: Sequence[Image.Image],
+    prompt: str,
+    *,
+    model: str,
+    max_completion_tokens: int = 1500,
+    reasoning_effort: Optional[str] = None,
+    retries: int = 2,
+) -> tuple[Optional[dict], str]:
+    """이미지들 + 프롬프트로 JSON 응답을 받아온다."""
+    effort = reasoning_effort if reasoning_effort is not None else _REASONING_EFFORT
+
+    content: list[Dict[str, Any]] = []
+    for idx, img in enumerate(images, 1):
+        b64 = _pil_to_b64_jpeg(img)
+        content.append({"type": "text", "text": f"[Image #{idx}]"})
+        content.append({
+            "type": "image_url",
+            "image_url": {
+                "url": f"data:image/jpeg;base64,{b64}",
+                "detail": "high",
+            },
+        })
+    content.append({"type": "text", "text": prompt})
+
+    last_raw = ""
+    for _ in range(retries + 1):
+        kwargs: Dict[str, Any] = {
+            "model": model,
+            "messages": [{"role": "user", "content": content}],
+            "max_completion_tokens": max_completion_tokens,
+        }
+        # reasoning 모델이면 reasoning_effort 전달 (chat.completions 정식 파라미터)
+        if effort and effort != "none":
+            kwargs["reasoning_effort"] = effort
+
+        try:
+            response = client.chat.completions.create(**kwargs)
+            cost_tracker.record(model, getattr(response, "usage", None))
+            raw = _normalize_message_content(response.choices[0].message.content)
+            last_raw = raw
+            parsed = _extract_json(raw)
+            if parsed is not None:
+                return parsed, raw
+        except Exception as e:
+            err_msg = str(e)
+            last_raw = err_msg
+            # reasoning_effort 미지원 모델이면 빼고 재시도. temperature 는 건드리지
+            # 않음 (reasoning 모델은 temperature=0 을 거부함).
+            if "reasoning" in err_msg.lower() or "unsupported" in err_msg.lower():
+                kwargs.pop("reasoning_effort", None)
+                try:
+                    response = client.chat.completions.create(**kwargs)
+                    cost_tracker.record(model, getattr(response, "usage", None))
+                    raw = _normalize_message_content(response.choices[0].message.content)
+                    last_raw = raw
+                    parsed = _extract_json(raw)
+                    if parsed is not None:
+                        return parsed, raw
+                except Exception as e2:
+                    last_raw = f"{err_msg} | retry: {e2}"
+
+    return None, last_raw
+
+
+def vqa_judge(
+    images: Sequence[Image.Image],
+    item_id: str,
+    item_text: str,
+    question: str,
+    *,
+    client=None,
+    model: Optional[str] = None,
+    max_completion_tokens: int = 6000,
+    reasoning_effort: Optional[str] = None,
+) -> VLMResult:
+    """단일 체크리스트 항목을 VLM 으로 판정 (멀티 이미지 지원).
+
+    Args:
+        images: 현장 사진 리스트 (최소 1장).
+        item_id: 항목 식별자.
+        item_text: 체크리스트 원문.
+        question: 항목별 VQA 질문 (엔진이 항목 텍스트로 합성).
+        client: 기존 OpenAI 클라이언트 재사용용. None 이면 새로 생성.
+        model: 모델 이름. None 이면 OPENAI_MODEL 환경변수.
+    """
+    if not images:
+        return VLMResult(
+            verdict="hold", confidence=0.0,
+            reason="이미지가 전달되지 않음.", observation="", used_images=[], raw="",
+        )
+    if client is None:
+        from openai import OpenAI
+        client = OpenAI()
+    model = model or _DEFAULT_MODEL
+
+    prompt = _PROMPT_TEMPLATE.format(
+        item_id=item_id, item_text=item_text, question=question,
+        n_images=len(images),
+    )
+    data, raw = _call_vision_json(
+        client=client,
+        images=images,
+        prompt=prompt,
+        model=model,
+        max_completion_tokens=max_completion_tokens,
+        reasoning_effort=reasoning_effort,
+    )
+
+    if not data:
+        return VLMResult(
+            verdict="hold",
+            confidence=0.0,
+            reason=f"JSON 파싱 실패: {raw[:200]}",
+            observation="",
+            used_images=[],
+            raw=raw,
+        )
+
+    verdict = data.get("verdict")
+    if verdict not in ("pass", "fail", "hold"):
+        verdict = "hold"
+
+    try:
+        confidence = float(data.get("confidence", 0.0))
+    except (TypeError, ValueError):
+        confidence = 0.0
+    confidence = max(0.0, min(1.0, confidence))
+
+    used: List[int] = []
+    raw_used = data.get("used_images")
+    if isinstance(raw_used, list):
+        for x in raw_used:
+            try:
+                ix = int(x)
+                if 1 <= ix <= len(images):
+                    used.append(ix)
+            except (TypeError, ValueError):
+                continue
+
+    # recapture_shots (hold 일 때만 의미 있음) — {target, how} 만 추려서 정규화
+    recapture: list = []
+    if verdict == "hold":
+        raw_rc = data.get("recapture_shots")
+        if isinstance(raw_rc, list):
+            for s in raw_rc:
+                if not isinstance(s, dict):
+                    continue
+                target = str(s.get("target") or "").strip()
+                how = str(s.get("how") or "").strip()
+                if target or how:
+                    recapture.append({"target": target, "how": how})
+
+    return VLMResult(
+        verdict=verdict,
+        confidence=confidence,
+        reason=str(data.get("reason") or "").strip() or raw.strip()[:200],
+        observation=str(data.get("observation") or "").strip(),
+        used_images=used,
+        recapture_shots=recapture,
+        raw=raw,
+    )