@dssp/dcsp 1.0.2 → 1.0.6

package/python/doc_summary_engine_handoff/summarize.py

@@ -0,0 +1,247 @@
+"""추출된 본문 → 한 줄 AI 브리핑 (OpenAI).
+
+설계 — 환각 최소화:
+  - 본문에 실제로 있는 내용만 사용하도록 강하게 지시.
+  - 긴 문서는 map-reduce: 파트별 '사실 추출' → 통합 → 최종 브리핑
+    (한 번에 욱여넣어 잘리는 것보다 사실 보존에 유리).
+  - 본문이 빈약/추출 실패면 애초에 이 모듈을 호출하지 않음 (api.py 가 거름).
+  - 모델이 판단 불가라고 보면 briefing=null 로 돌려주도록 허용.
+
+프롬프트 문구는 채팅에서 합의된 초안을 그대로 사용.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+_DEFAULT_MODEL    = os.environ.get("OPENAI_MODEL", "gpt-5.5")
+# 브리핑은 충실한 압축이 목적 → reasoning 은 낮게 (속도·비용↓, 환각 여지↓).
+_REASONING_EFFORT = os.environ.get("DOC_BRIEF_REASONING_EFFORT", "low").strip()
+
+# 한 번에 처리할 본문 길이(글자). 넘으면 map-reduce.
+_SINGLE_PASS_CHARS = int(os.environ.get("DOC_SINGLE_PASS_CHARS", "12000"))
+# map 단계 청크 크기(글자).
+_CHUNK_CHARS       = int(os.environ.get("DOC_CHUNK_CHARS", "8000"))
+
+
+@dataclass
+class BriefResult:
+    briefing: Optional[str]    # 한 줄 브리핑. 판단 불가 시 None.
+    doc_type: str              # 공문|보고서|회의록|계획서|기타 (본문 근거 시에만)
+    has_content: bool          # 모델이 요지를 잡았는지
+    model: str
+    elapsed_sec: float
+    note: str = ""             # briefing=None 일 때 사유
+    raw: str = ""              # 디버그용 원본 응답
+
+
+# ─── 합의된 브리핑 프롬프트 ────────────────────────────────────────────────
+
+_BRIEF_PROMPT = """당신은 건설 시공감리 문서를 정리하는 비서입니다.
+아래 [문서 본문]을 읽고, 감리자·시공자가 클릭 한 번에 내용을 파악할 수 있는
+한 줄 브리핑을 작성하세요.
+
+[작성 규칙]
+1. 본문에 실제로 적힌 내용만 사용. 본문에 없는 사실·배경·추측은 절대 쓰지 마라.
+2. 1~2문장, 한국어 명사형 종결("~건입니다", "~알림입니다", "~보고서입니다").
+3. 가능하면 다음 요소를 본문에 있는 한도에서 담아라:
+   - 누가(발신/수신 기관·부서), 무엇을(핵심 안건·조치), 언제(날짜), 문서 종류.
+4. 날짜·금액·수치·고유명사는 본문에 적힌 그대로만. 본문에 없으면 쓰지 마라.
+5. 본문이 비었거나 너무 짧아 요지를 알 수 없으면, 지어내지 말고
+   briefing 을 null 로 반환하라.
+6. 문서 분류(category)는 참고만. 분류 이름을 근거로 내용을 추측하지 마라.
+
+[문서 분류] {category}
+[파일명] {filename}
+[문서 본문]
+{text}
+
+아래 JSON 하나만 출력:
+{{
+  "briefing": "<한 줄 브리핑 또는 null>",
+  "doc_type": "<공문|보고서|회의록|계획서|기타 — 본문 근거 시에만>",
+  "has_content": true
+}}"""
+
+# map 단계: 긴 문서의 한 파트에서 '실제로 적힌 사실'만 뽑기 (브리핑은 reduce 에서).
+_FACTS_PROMPT = """당신은 건설 시공감리 문서를 정리하는 비서입니다.
+아래는 긴 문서의 일부(파트 {k}/{n})입니다.
+이 파트에 '실제로 적힌' 핵심 사실만 짧은 항목(-)으로 뽑으세요.
+본문에 없는 내용·추측은 절대 쓰지 마라. 날짜·숫자·고유명사는 적힌 그대로.
+이 파트에 의미 있는 내용이 없으면 빈 줄만 출력.
+
+[문서 본문 — 파트 {k}/{n}]
+{chunk}
+
+핵심 사실:"""
+
+
+# ─── 유틸 ──────────────────────────────────────────────────────────────────
+
+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_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:
+            t = item.get("text") if isinstance(item, dict) else getattr(item, "text", None)
+            if isinstance(t, str):
+                parts.append(t)
+        return "".join(parts)
+    return str(raw)
+
+
+def _call_text(client, prompt: str, *, model: str, max_completion_tokens: int,
+               reasoning_effort: Optional[str], retries: int = 1) -> str:
+    """텍스트 프롬프트 → 모델 응답 문자열. reasoning 미지원 모델은 자동 fallback."""
+    effort = reasoning_effort if reasoning_effort is not None else _REASONING_EFFORT
+    last = ""
+    for _ in range(retries + 1):
+        kwargs: Dict[str, Any] = {
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "max_completion_tokens": max_completion_tokens,
+        }
+        if effort and effort != "none":
+            kwargs["reasoning_effort"] = effort
+        try:
+            resp = client.chat.completions.create(**kwargs)
+            return _normalize_content(resp.choices[0].message.content)
+        except Exception as e:
+            msg = str(e)
+            last = msg
+            # reasoning_effort 미지원 모델이면 빼고 재시도 (temperature 는 안 건드림).
+            if "reasoning" in msg.lower() or "unsupported" in msg.lower():
+                kwargs.pop("reasoning_effort", None)
+                try:
+                    resp = client.chat.completions.create(**kwargs)
+                    return _normalize_content(resp.choices[0].message.content)
+                except Exception as e2:
+                    last = f"{msg} | retry: {e2}"
+    raise RuntimeError(last or "LLM 호출 실패")
+
+
+def _chunks(text: str, size: int) -> list[str]:
+    return [text[i : i + size] for i in range(0, len(text), size)] or [""]
+
+
+def _reduce_to_facts(client, text: str, *, model: str) -> str:
+    """긴 본문 → 파트별 사실 추출 후 합침 (map 단계)."""
+    parts = _chunks(text, _CHUNK_CHARS)
+    n = len(parts)
+    facts: list[str] = []
+    for k, chunk in enumerate(parts, 1):
+        prompt = _FACTS_PROMPT.format(k=k, n=n, chunk=chunk)
+        try:
+            out = _call_text(
+                client, prompt, model=model,
+                max_completion_tokens=800, reasoning_effort="low",
+            )
+            if out.strip():
+                facts.append(out.strip())
+        except Exception:
+            continue   # 한 파트 실패해도 나머지로 진행
+    return "\n".join(facts)
+
+
+# ─── 진입점 ────────────────────────────────────────────────────────────────
+
+def brief_document(
+    text: str,
+    *,
+    filename: str = "",
+    category: str = "",
+    client=None,
+    model: Optional[str] = None,
+    reasoning_effort: Optional[str] = None,
+) -> BriefResult:
+    """추출된 본문 → 한 줄 브리핑.
+
+    Args:
+        text: extract.extract_text() 가 뽑은 본문 (충분한 분량이라고 가정).
+        filename: 파일명 (근거 힌트).
+        category: 문서 분류 (대/중/소분류 문자열, 근거 힌트).
+        client: 기존 OpenAI 클라이언트 재사용. None 이면 새로 생성.
+        model: 모델 이름. None 이면 OPENAI_MODEL 환경변수.
+    """
+    t0 = time.time()
+    model = model or _DEFAULT_MODEL
+    if client is None:
+        from openai import OpenAI
+        client = OpenAI()
+
+    body = text or ""
+    # 긴 문서는 먼저 사실만 뽑아서 압축 (map-reduce).
+    if len(body) > _SINGLE_PASS_CHARS:
+        facts = _reduce_to_facts(client, body, model=model)
+        body = facts if facts.strip() else body[:_SINGLE_PASS_CHARS]
+
+    prompt = _BRIEF_PROMPT.format(
+        category=(category or "(미상)"),
+        filename=(filename or "(미상)"),
+        text=body,
+    )
+    try:
+        raw = _call_text(
+            client, prompt, model=model,
+            max_completion_tokens=1000, reasoning_effort=reasoning_effort,
+        )
+    except Exception as e:
+        return BriefResult(
+            briefing=None, doc_type="기타", has_content=False,
+            model=model, elapsed_sec=round(time.time() - t0, 2),
+            note=f"LLM 호출 실패: {str(e)[:160]}", raw="",
+        )
+
+    data = _extract_json(raw)
+    if not data:
+        return BriefResult(
+            briefing=None, doc_type="기타", has_content=False,
+            model=model, elapsed_sec=round(time.time() - t0, 2),
+            note=f"JSON 파싱 실패: {raw[:160]}", raw=raw,
+        )
+
+    briefing = data.get("briefing")
+    if isinstance(briefing, str):
+        briefing = briefing.strip() or None
+    else:
+        briefing = None   # null/누락/비문자열 → None
+
+    doc_type = str(data.get("doc_type") or "기타").strip() or "기타"
+    has_content = bool(data.get("has_content")) and briefing is not None
+
+    return BriefResult(
+        briefing=briefing,
+        doc_type=doc_type,
+        has_content=has_content,
+        model=model,
+        elapsed_sec=round(time.time() - t0, 2),
+        note="" if briefing else "모델이 본문에서 요지를 확정하지 못함",
+        raw=raw,
+    )

package/python/inspection_ai_engine_handoff/.env.example

@@ -0,0 +1,22 @@
+# 필수: OpenAI API 키
+OPENAI_API_KEY=sk-...
+
+# 사용할 모델 (VLM/라우터/샷플래너 공용)
+OPENAI_MODEL=gpt-5.5
+
+# reasoning 강도 (none|low|medium|high|xhigh)
+# - reasoning 모델일 때만 적용. 미지원 모델이면 자동으로 무시 + temperature=0 fallback.
+REASONING_EFFORT=high
+
+# ── HTTP API (api.py) ─────────────────────────────────────────────
+INSPECTION_API_PORT=8000
+INSPECTION_API_MAX_IMAGES=8
+INSPECTION_API_MAX_BYTES=15728640
+INSPECTION_API_ALLOWED_ORIGINS=*
+
+# ── CV 모델 레지스트리 ────────────────────────────────────────────
+# 경로 변경하고 싶을 때만 설정 (기본은 같은 폴더의 cv_models/ 디렉터리)
+# CV_MODELS_DIR=./cv_models
+
+# ── Gradio 데모 ──────────────────────────────────────────────────
+DEMO_UI_PORT=7870