@dssp/dcsp 1.0.2 → 1.0.6

package/python/inspection_ai_engine_handoff/cv_model_registry.py

@@ -0,0 +1,252 @@
+"""CV 모델 레지스트리 — 폴더 스캔 방식 (플러그인 구조).
+
+단일 cv_models.json 을 손으로 편집하던 방식의 문제(충돌·전체 파손 위험)를 없애기 위해,
+각 CV 모델을 **자기 폴더**에 담고 시스템이 그 폴더를 스캔해 레지스트리를 자동 조립합니다.
+
+폴더 구조:
+    cv_models/
+    ├── README.md
+    ├── _example_xxx/          ← 이름이 '_' 또는 '.' 로 시작하면 스캔 제외(비활성/예시)
+    │   ├── model.json
+    │   └── handler.py
+    ├── frame_alignment_v1/    ← 실제 모델 (폴더만 떨구면 자동 등록)
+    │   ├── model.json         ← 메타데이터 (handler 필드 없음 — 규칙으로 자동 연결)
+    │   └── handler.py         ← def run(images) -> CVResult
+    └── ...
+
+규칙:
+  - 핸들러는 <폴더>/handler.py 의 run() 함수로 자동 연결 (model.json 에 경로 안 적음).
+  - handler.py 가 없으면 status='stub' 로 간주하고 'pending' 을 반환하는 기본 핸들러 사용.
+    (메타만 먼저 등록 → 나중에 코드 추가 가능)
+  - 폴더 하나가 깨져도(json 오류 등) 그 폴더만 건너뛰고 경고. 나머지는 정상 동작.
+
+공개 API (engine/router/api 가 사용 — 시그니처 불변):
+  - load_registry() -> CVRegistry
+  - list_models() -> list[CVModelMeta]
+  - summarize_for_router() -> list[dict]
+  - resolve_handler(model_id) -> callable(images)->CVResult
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, List, Optional, Sequence
+
+from PIL import Image
+
+from cv_handlers import CVResult
+
+
+_REGISTRY_DIR = Path(
+    os.environ.get(
+        "CV_MODELS_DIR",
+        str(Path(__file__).with_name("cv_models")),
+    )
+)
+
+HANDLER_FUNC_NAME = "run"   # 각 모델 폴더 handler.py 가 노출해야 하는 함수 이름
+
+
+def _warn(msg: str) -> None:
+    print(f"[cv_model_registry] 경고: {msg}", file=sys.stderr)
+
+
+@dataclass
+class CVModelMeta:
+    """라우터/UI 에 노출하는 CV 모델 메타데이터."""
+    model_id: str
+    name: str
+    description: str
+    applicable_to: list[str]
+    input_spec: dict
+    output_schema: dict
+    verdict_rules: dict
+    status: str            # "stub" | "ready"
+    handler: str           # 자동 연결된 handler.py 경로 (없으면 "")
+    version: str
+
+    def is_ready(self) -> bool:
+        return self.status == "ready"
+
+
+@dataclass
+class CVRegistry:
+    schema_version: str
+    description: str
+    models: list[CVModelMeta]
+
+    def by_id(self, model_id: str) -> Optional[CVModelMeta]:
+        for m in self.models:
+            if m.model_id == model_id:
+                return m
+        return None
+
+
+# model.json 에서 반드시 있어야 하는 핵심 키 (나머지는 기본값으로 보완)
+_REQUIRED_KEYS = {"model_id", "name", "description", "applicable_to"}
+_VALID_STATUS = {"stub", "ready"}
+
+
+def _parse_model_json(data: dict, folder_name: str) -> dict:
+    """model.json dict 검증 + 기본값 보완. 실패 시 ValueError."""
+    missing = _REQUIRED_KEYS - set(data.keys())
+    if missing:
+        raise ValueError(f"필수 키 누락: {sorted(missing)}")
+    if not isinstance(data["model_id"], str) or not data["model_id"].strip():
+        raise ValueError("model_id 가 비어있거나 문자열이 아님")
+    if not isinstance(data["applicable_to"], list):
+        raise ValueError("applicable_to 는 배열이어야 함")
+    status = data.get("status", "ready")
+    if status not in _VALID_STATUS:
+        raise ValueError(f"status 는 {_VALID_STATUS} 중 하나여야 함 (현재: {status})")
+    return {
+        "model_id":      data["model_id"].strip(),
+        "name":          str(data["name"]),
+        "description":   str(data["description"]),
+        "applicable_to": [str(x) for x in data["applicable_to"]],
+        "input_spec":    dict(data.get("input_spec", {})),
+        "output_schema": dict(data.get("output_schema", {})),
+        "verdict_rules": dict(data.get("verdict_rules", {})),
+        "status":        status,
+        "version":       str(data.get("version", "0.0.0")),
+    }
+
+
+def _iter_model_dirs(root: Path):
+    """root 아래 모델 폴더들을 순회. '_' 또는 '.' 로 시작하는 폴더는 제외."""
+    if not root.exists() or not root.is_dir():
+        return
+    for child in sorted(root.iterdir(), key=lambda p: p.name):
+        if not child.is_dir():
+            continue
+        if child.name.startswith(("_", ".")):
+            continue
+        if (child / "model.json").exists():
+            yield child
+
+
+def load_registry(root: Optional[Path] = None) -> CVRegistry:
+    """cv_models/ 폴더를 스캔해 레지스트리를 조립. 깨진 폴더는 건너뜀(경고)."""
+    root = Path(root) if root is not None else _REGISTRY_DIR
+    models: list[CVModelMeta] = []
+    seen_ids: set[str] = set()
+
+    for folder in _iter_model_dirs(root):
+        try:
+            raw = json.loads((folder / "model.json").read_text(encoding="utf-8"))
+            parsed = _parse_model_json(raw, folder.name)
+        except Exception as e:
+            _warn(f"모델 폴더 '{folder.name}' 의 model.json 로드 실패 → 건너뜀: {e}")
+            continue
+
+        mid = parsed["model_id"]
+        if mid in seen_ids:
+            _warn(f"중복 model_id '{mid}' (폴더 '{folder.name}') → 건너뜀")
+            continue
+
+        handler_py = folder / "handler.py"
+        has_handler = handler_py.exists()
+        status = parsed["status"]
+        if not has_handler:
+            # 코드가 아직 없으면 무조건 stub 취급
+            status = "stub"
+
+        seen_ids.add(mid)
+        models.append(CVModelMeta(
+            model_id=mid,
+            name=parsed["name"],
+            description=parsed["description"],
+            applicable_to=parsed["applicable_to"],
+            input_spec=parsed["input_spec"],
+            output_schema=parsed["output_schema"],
+            verdict_rules=parsed["verdict_rules"],
+            status=status,
+            handler=str(handler_py) if has_handler else "",
+            version=parsed["version"],
+        ))
+
+    return CVRegistry(
+        schema_version="1.0",
+        description="cv_models/ 폴더에서 자동 조립된 CV 모델 레지스트리.",
+        models=models,
+    )
+
+
+def list_models() -> list[CVModelMeta]:
+    return load_registry().models
+
+
+def summarize_for_router(models: Optional[Sequence[CVModelMeta]] = None) -> list[dict]:
+    """LLM 라우터용 압축 뷰 (내부 필드 handler/version 제외)."""
+    if models is None:
+        models = list_models()
+    return [
+        {
+            "model_id": m.model_id,
+            "name": m.name,
+            "description": m.description,
+            "applicable_to": m.applicable_to,
+            "required_shots": m.input_spec.get("required_shots", []),
+            "output_keys": list(m.output_schema.keys()),
+            "status": m.status,
+        }
+        for m in models
+    ]
+
+
+CVHandlerFn = Callable[[Sequence[Image.Image]], CVResult]
+
+
+def _pending_handler(model_id: str) -> CVHandlerFn:
+    """handler.py 가 없거나 stub 인 모델용 기본 핸들러 — 항상 pending."""
+    def run(images: Sequence[Image.Image]) -> CVResult:
+        return CVResult(
+            verdict="pending",
+            reason=f"CV 모델 '{model_id}' 핸들러 미구현 (handler.py 없음 또는 stub 단계).",
+            measurements={"stub": True, "n_images_received": len(images)},
+            used_images=[],
+        )
+    return run
+
+
+def _import_run(handler_py: Path, model_id: str) -> CVHandlerFn:
+    """<폴더>/handler.py 를 동적 import 해서 run() 을 반환."""
+    spec = importlib.util.spec_from_file_location(f"_cvmodel_{model_id}", handler_py)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"{handler_py} import 스펙 생성 실패")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    fn = getattr(module, HANDLER_FUNC_NAME, None)
+    if fn is None:
+        raise AttributeError(f"{handler_py} 에 {HANDLER_FUNC_NAME}(images) 함수가 없습니다.")
+    return fn
+
+
+def resolve_handler(model_id: str) -> CVHandlerFn:
+    """model_id → 실제 핸들러 callable. 핸들러 없으면 pending 핸들러 반환.
+
+    Raises:
+        KeyError: 레지스트리에 model_id 없음.
+    """
+    meta = load_registry().by_id(model_id)
+    if meta is None:
+        raise KeyError(f"CV 모델 레지스트리에 model_id 없음: {model_id}")
+    if not meta.handler:
+        return _pending_handler(model_id)
+    try:
+        return _import_run(Path(meta.handler), model_id)
+    except Exception as e:
+        _warn(f"모델 '{model_id}' handler.py 로드 실패 → pending 처리: {e}")
+        return _pending_handler(model_id)
+
+
+if __name__ == "__main__":
+    reg = load_registry()
+    print(f"CV 모델 레지스트리: 활성 {len(reg.models)}개")
+    for m in reg.models:
+        mark = "READY" if m.is_ready() else "stub "
+        print(f"  [{mark}] {m.model_id}  {m.name}")

package/python/inspection_ai_engine_handoff/cv_models/README.md

@@ -0,0 +1,58 @@
+# CV 모델 레지스트리 (폴더 방식)
+
+이 폴더가 **CV 측정 모델 저장소**입니다. 모델마다 자기 폴더를 가지며, 시스템이
+시작할 때 이 폴더를 스캔해 레지스트리를 자동으로 조립합니다. **공유 파일(JSON 하나)을
+다 같이 편집하지 않으므로** 충돌·전체 파손 위험이 없습니다.
+
+## 구조
+
+```
+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` 의 값을 채웁니다 (아래 필드 설명).
+3. `handler.py` 의 `run()` 안에 실제 측정 코드를 작성합니다.
+4. `model.json` 의 `"status"` 를 `"ready"` 로 바꿉니다.
+5. 서버 재시작 — 끝. 라우터가 자동으로 인식합니다.
+
+> 코드가 아직 없으면 `model.json` 만 두어도 됩니다(`handler.py` 생략).
+> 이 경우 자동으로 `stub` 처리되어 결과는 항상 `pending` 입니다.
+> 메타만 먼저 등록하고 나중에 코드를 추가하는 흐름에 유용합니다.
+
+## model.json 필드
+
+| 필드 | 필수 | 설명 |
+|---|---|---|
+| `model_id` | ✅ | 고유 ID(문자열). 예: `"frame_alignment_v1"` |
+| `name` | ✅ | 사람이 읽는 이름 |
+| `description` | ✅ | 무엇을 측정/검출하는지 1~2문장. **라우터가 검사항목 매칭에 사용** |
+| `applicable_to` | ✅ | 적합한 검사 키워드 리스트. **라우터가 항목 텍스트와 비교** |
+| `input_spec` | | `{required_shots, min_images, max_images, notes}`. `notes` 의 촬영요구는 촬영지시에 반영됨 |
+| `output_schema` | | 산출 측정값 정의 `{ 이름: {type, desc} }` |
+| `verdict_rules` | | 판정 기준(`tolerance`, `logic`). `logic` 은 사람용 문서, 실제 판정은 코드에서 |
+| `status` | | `"stub"`(메타만/코드 미구현 → pending) 또는 `"ready"`(동작). 기본값 `ready` (단, handler.py 없으면 자동 stub) |
+| `version` | | 버전 문자열. 기본값 `"0.0.0"` |
+
+> `handler` 경로는 **적지 않습니다.** `<폴더>/handler.py:run` 으로 자동 연결됩니다.
+
+## handler.py 규칙
+
+- 함수 이름은 반드시 `run`.
+- 시그니처: `run(images: Sequence[PIL.Image]) -> CVResult`.
+- `CVResult` 는 `from cv_handlers import CVResult` 로 가져옵니다.
+
+## 견고성
+
+- 폴더 하나의 `model.json` 이 깨져도 그 폴더만 건너뛰고 경고를 출력합니다. 나머지 모델은 정상 동작.
+- `_` 또는 `.` 로 시작하는 폴더는 스캔에서 제외됩니다(예시·보관용).

package/python/inspection_ai_engine_handoff/cv_models/_example_frame_alignment/handler.py

@@ -0,0 +1,39 @@
+"""예시 CV 핸들러 (작성 템플릿).
+
+이 폴더는 이름이 '_' 로 시작하므로 레지스트리 스캔에서 제외됩니다(비활성).
+실제 모델을 만들 때 이 폴더를 통째로 복사해 'cv_models/내모델_v1/' 처럼
+'_' 없이 두고, 아래 run() 안을 채우세요.
+
+규칙:
+  - 함수 이름은 반드시 run.
+  - 시그니처: run(images: Sequence[PIL.Image]) -> CVResult.
+  - 어떤 사진을 쓸지는 모델이 알아서 고름 (예: 풀샷만 사용).
+"""
+from __future__ import annotations
+
+from typing import Sequence
+
+from PIL import Image
+
+from cv_handlers import CVResult
+
+
+def run(images: Sequence[Image.Image]) -> CVResult:
+    # --- 실제 구현 가이드 ---
+    # 1) images 중 풀샷 선택
+    # 2) 직선 성분 검출 (Hough/RANSAC/딥러닝 등)
+    # 3) 수직/수평축 대비 편차각 측정
+    # 4) 허용오차(예: ±1.0°) 기준으로 verdict 결정
+    #
+    # 예시 반환값 (실제 측정값으로 교체):
+    return CVResult(
+        verdict="pending",
+        reason="예시 스텁 — 실제 구현 대기. run() 안을 채우세요.",
+        measurements={
+            "stub": True,
+            "n_images_received": len(images),
+            "expected_keys": ["vertical_deviation_deg", "horizontal_deviation_deg"],
+        },
+        used_images=[],
+        overlay_b64=None,
+    )

package/python/inspection_ai_engine_handoff/cv_models/_example_frame_alignment/model.json

@@ -0,0 +1,22 @@
+{
+  "model_id": "frame_alignment_v1",
+  "name": "수직·수평 편차 측정 (작성 예시)",
+  "description": "풀샷에서 부재의 직선 성분을 검출해 수직축/수평축 대비 편차각을 측정. 시공 직선도/수직도 검사에 사용.",
+  "applicable_to": ["수직 상태", "수평 상태", "정렬", "기울기", "직선도"],
+  "input_spec": {
+    "required_shots": ["full_front"],
+    "min_images": 1,
+    "max_images": 3,
+    "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. 검출 선분이 너무 적으면 hold."
+  },
+  "status": "stub",
+  "version": "0.0.1"
+}