@dssp/dcsp 1.0.2 → 1.0.6

package/python/doc_summary_engine_handoff/api.py

@@ -0,0 +1,165 @@
+"""문서 AI 브리핑 — HTTP API (FastAPI).
+
+엔드포인트:
+  GET  /health       서버 상태 + 지원 포맷
+  POST /brief-doc    문서 파일 1개 → 한 줄 AI 브리핑
+
+실행:
+  python api.py
+  → http://localhost:8100  (Swagger: /docs)
+
+설계:
+  - Stateless. 결과 저장은 플랫폼 측 DB.
+  - 권장 호출 시점: 문서 '업로드 시 1회' 호출해서 브리핑을 받아 저장 →
+    이후 문서 클릭 시엔 저장된 값을 표시 (재호출 없음 → 빠르고 저렴).
+  - 텍스트를 못 읽는 문서(스캔/도면/사진/DRM)는 briefing=null 로 반환
+    (환각 대신 빈칸).
+"""
+from __future__ import annotations
+
+import os
+import time
+from typing import Optional
+
+from fastapi import FastAPI, File, Form, HTTPException, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
+
+from extract import extract_text
+from summarize import brief_document
+
+DEFAULT_PORT    = int(os.environ.get("DOC_API_PORT", "8100"))
+MAX_BYTES       = int(os.environ.get("DOC_API_MAX_BYTES", str(30 * 1024 * 1024)))   # 30MB
+ALLOWED_ORIGINS = os.environ.get("DOC_API_ALLOWED_ORIGINS", "*").split(",")
+
+SUPPORTED = ["hwp", "hwpx", "pdf", "xlsx", "docx", "pptx"]
+
+app = FastAPI(
+    title="시공감리 문서 AI 브리핑 API",
+    version="1.0.0",
+    description=(
+        "시공감리 플랫폼의 「현장 문서 확인」 문서를 받아 한 줄 AI 브리핑을 반환합니다.\n\n"
+        "HWP(5.x)/HWPX/PDF/XLSX/DOCX/PPTX 의 본문 텍스트를 추출해 요약.\n"
+        "텍스트를 못 읽는 문서(스캔·도면·사진·DRM)는 briefing=null (환각 방지)."
+    ),
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=ALLOWED_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+class HealthResponse(BaseModel):
+    ok: bool
+    server_time: float
+    supported_formats: list[str]
+    model: str
+
+
+@app.get("/health", response_model=HealthResponse)
+def health():
+    return HealthResponse(
+        ok=True,
+        server_time=time.time(),
+        supported_formats=SUPPORTED,
+        model=os.environ.get("OPENAI_MODEL", "gpt-5.5"),
+    )
+
+
+@app.post("/brief-doc")
+async def post_brief_doc(
+    file:     UploadFile = File(..., description="문서 파일 1개. HWP/HWPX/PDF/XLSX/DOCX/PPTX."),
+    category: Optional[str] = Form("", description="문서 분류(대/중/소분류) 문자열. 근거 힌트, 선택."),
+    filename: Optional[str] = Form(None, description="파일명 override (없으면 업로드 파일명 사용)."),
+):
+    """문서 1개 → 한 줄 AI 브리핑.
+
+    multipart/form-data:
+      - file:     문서 파일 (필수)
+      - category: 분류 문자열 (선택, 예: "사업관리 · 공사작업일보 · 민원처리보고")
+      - filename: 파일명 override (선택)
+
+    응답:
+      {
+        "ok": true,
+        "filename": "문서명 04.hwp",
+        "kind": "hwp",
+        "char_count": 812,
+        "briefing": "...한 줄 브리핑...",   // 못 읽으면 null
+        "doc_type": "공문",
+        "has_content": true,
+        "note": "",                          // briefing=null 사유
+        "model": "gpt-5.5",
+        "elapsed_sec": 2.1
+      }
+    """
+    name = filename or file.filename or "(unknown)"
+    data = await file.read()
+
+    if not data:
+        raise HTTPException(status_code=400, detail="빈 파일입니다.")
+    if len(data) > MAX_BYTES:
+        raise HTTPException(
+            status_code=413,
+            detail=f"파일 크기 초과 ({len(data)} > {MAX_BYTES} bytes).",
+        )
+
+    # 1) 텍스트 추출 — 못 읽으면 LLM 호출 없이 빈칸 반환 (환각 방지 + 비용 0).
+    ex = extract_text(data, name)
+    if not ex.ok:
+        return JSONResponse({
+            "ok": True,
+            "filename": name,
+            "kind": ex.kind,
+            "char_count": ex.char_count,
+            "briefing": None,
+            "doc_type": "기타",
+            "has_content": False,
+            "note": ex.reason,
+            "model": os.environ.get("OPENAI_MODEL", "gpt-5.5"),
+            "elapsed_sec": 0.0,
+        })
+
+    # 2) OpenAI 클라이언트
+    try:
+        from openai import OpenAI
+        client = OpenAI()
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"OpenAI 클라이언트 초기화 실패 (OPENAI_API_KEY 확인): {e}",
+        )
+
+    # 3) 한 줄 브리핑
+    result = brief_document(
+        ex.text, filename=name, category=category or "", client=client,
+    )
+
+    return JSONResponse({
+        "ok": True,
+        "filename": name,
+        "kind": ex.kind,
+        "char_count": ex.char_count,
+        "briefing": result.briefing,
+        "doc_type": result.doc_type,
+        "has_content": result.has_content,
+        "note": result.note,
+        "model": result.model,
+        "elapsed_sec": result.elapsed_sec,
+    })
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("api:app", host="0.0.0.0", port=DEFAULT_PORT, reload=False)

package/python/doc_summary_engine_handoff/extract.py

@@ -0,0 +1,290 @@
+"""문서 파일 → 본문 텍스트 추출.
+
+지원 포맷:
+  - .hwp  (한글 5.x 바이너리)   → olefile + zlib (BodyText 레코드 직접 파싱)
+  - .hwpx (한글 신포맷, OWPML)  → zip + XML 파싱 (표준 라이브러리)
+  - .pdf                        → PyMuPDF (fitz)
+  - .xlsx                       → openpyxl (시트 → 마크다운 표)
+  - .docx                       → python-docx
+  - .pptx                       → python-pptx (슬라이드 텍스트 + 노트)
+
+설계 원칙 — 환각 방지의 1차 방어선:
+  텍스트를 못 읽거나(스캔 PDF, DRM hwp, 도면·사진) 본문이 너무 빈약하면
+  '추측해서 채우지' 않고 ok=False 로 돌려준다. 그러면 상위(summarize/api)는
+  LLM 을 호출하지 않고 브리핑을 빈칸(null)으로 둔다.
+"""
+from __future__ import annotations
+
+import io
+import os
+import re
+import struct
+import zipfile
+import zlib
+from dataclasses import dataclass
+from typing import Optional
+
+# 본문으로 인정할 최소 글자 수 (공백 제외). 이보다 적으면 '본문 없음' 처리.
+MIN_TEXT_CHARS = int(os.environ.get("DOC_MIN_TEXT_CHARS", "20"))
+# 엑셀 시트당 읽을 최대 행 수 (한 줄 브리핑엔 앞부분이면 충분).
+MAX_XLSX_ROWS = int(os.environ.get("DOC_MAX_XLSX_ROWS", "200"))
+
+
+@dataclass
+class ExtractResult:
+    ok: bool                       # 본문 추출 성공 + 충분한 분량 여부
+    text: str                      # 추출된 본문 (실패 시 "")
+    kind: str                      # 파일 종류 ("hwp"|"hwpx"|"pdf"|"xlsx"|"docx"|"unknown"|...)
+    char_count: int                # 공백 제외 글자 수
+    reason: str = ""               # ok=False 일 때 사유 (사람용)
+
+
+# ─── 포맷별 추출기 ─────────────────────────────────────────────────────────
+
+# HWP 5.x 본문 텍스트 레코드 태그 (HWPTAG_PARA_TEXT)
+_HWP_PARA_TEXT_TAG = 67
+# 부가 데이터를 포함해 8 WCHAR를 차지하는 인라인/확장 컨트롤 문자 코드
+_HWP_EXTENDED_CTRL = frozenset(range(1, 10)) | {11, 12} | frozenset(range(14, 24))
+
+
+def _hwp_records(stream: bytes):
+    """HWP 레코드 스트림 순회 → (tag, payload) 생성.
+    레코드 헤더 4바이트: tag(10bit) | level(10bit) | size(12bit). size=0xFFF면 뒤 4바이트가 실제 크기."""
+    i, n = 0, len(stream)
+    while i + 4 <= n:
+        (hdr,) = struct.unpack_from("<I", stream, i)
+        i += 4
+        tag = hdr & 0x3FF
+        size = (hdr >> 20) & 0xFFF
+        if size == 0xFFF:
+            if i + 4 > n:
+                break
+            (size,) = struct.unpack_from("<I", stream, i)
+            i += 4
+        yield tag, stream[i : i + size]
+        i += size
+
+
+def _hwp_para_text(payload: bytes) -> str:
+    """PARA_TEXT 페이로드(WCHAR 배열) → 텍스트. 컨트롤 문자는 건너뛰거나 줄바꿈으로 치환."""
+    u = payload.decode("utf-16-le", errors="ignore")
+    out: list[str] = []
+    i = 0
+    while i < len(u):
+        c = ord(u[i])
+        if c in (10, 13):
+            out.append("\n")
+            i += 1
+        elif c in _HWP_EXTENDED_CTRL:
+            i += 8  # 컨트롤 + 부가데이터 7 WCHAR
+        elif c < 32:
+            i += 1
+        else:
+            out.append(u[i])
+            i += 1
+    return "".join(out)
+
+
+def _extract_hwp(data: bytes) -> str:
+    """한글 5.x (.hwp, OLE 복합문서) → 텍스트. BodyText 섹션 레코드에서 본문을 직접 파싱.
+    (pyhwp/hwp5txt 의존 제거 — 실행 환경에 CLI가 없어도 동작)"""
+    import olefile
+
+    ole = olefile.OleFileIO(io.BytesIO(data))
+    try:
+        if not ole.exists("FileHeader"):
+            raise RuntimeError("한글 5.x 형식이 아님 (구형식/손상 파일)")
+        header = ole.openstream("FileHeader").read()
+        (flags,) = struct.unpack_from("<I", header, 36)
+        if flags & 0x2:
+            raise RuntimeError("암호화된 문서")
+        compressed = bool(flags & 0x1)
+
+        # BodyText/Section0, Section1, ... 순서대로 (배포용 문서는 ViewText라 본문 없음 → 빈칸 처리)
+        sections = sorted(
+            (e for e in ole.listdir() if e[0] == "BodyText"),
+            key=lambda e: int(re.sub(r"\D", "", e[-1]) or 0),
+        )
+        parts: list[str] = []
+        for entry in sections:
+            raw = ole.openstream(entry).read()
+            if compressed:
+                raw = zlib.decompress(raw, -15)
+            for tag, payload in _hwp_records(raw):
+                if tag == _HWP_PARA_TEXT_TAG:
+                    t = _hwp_para_text(payload)
+                    if t.strip():
+                        parts.append(t)
+        return "\n".join(parts)
+    finally:
+        ole.close()
+
+
+def _extract_hwpx(data: bytes) -> str:
+    """한글 신포맷 (.hwpx, OWPML) → 텍스트. zip 안 section XML 의 텍스트 런(t) 추출."""
+    import xml.etree.ElementTree as ET
+
+    parts: list[str] = []
+    with zipfile.ZipFile(io.BytesIO(data)) as z:
+        names = sorted(
+            n for n in z.namelist()
+            if n.startswith("Contents/") and n.lower().endswith(".xml") and "section" in n.lower()
+        )
+        for n in names:
+            try:
+                root = ET.fromstring(z.read(n))
+            except ET.ParseError:
+                continue
+            for el in root.iter():
+                tag = el.tag.split("}")[-1]   # 네임스페이스 제거 (hp:t → t)
+                if tag == "p":                # 문단 경계 → 줄바꿈
+                    parts.append("\n")
+                elif tag == "t" and el.text:  # 텍스트 런
+                    parts.append(el.text)
+    return "".join(parts)
+
+
+def _extract_pdf(data: bytes) -> str:
+    """PDF → 텍스트. (스캔 PDF 는 텍스트가 거의 안 나옴 → 상위에서 빈칸 처리)"""
+    import fitz  # PyMuPDF
+
+    pages: list[str] = []
+    with fitz.open(stream=data, filetype="pdf") as doc:
+        for page in doc:
+            pages.append(page.get_text())
+    return "\n".join(pages)
+
+
+def _extract_xlsx(data: bytes) -> str:
+    """XLSX → 시트별 마크다운 표. 표 구조를 모델이 보게 해서 브리핑 정확도↑."""
+    from openpyxl import load_workbook
+
+    wb = load_workbook(io.BytesIO(data), read_only=True, data_only=True)
+    try:
+        blocks: list[str] = []
+        for ws in wb.worksheets:
+            rows: list[str] = []
+            for i, row in enumerate(ws.iter_rows(values_only=True)):
+                if i >= MAX_XLSX_ROWS:
+                    rows.append("… (이하 행 생략)")
+                    break
+                cells = ["" if c is None else str(c) for c in row]
+                if any(c.strip() for c in cells):
+                    rows.append(" | ".join(cells))
+            if rows:
+                blocks.append(f"## 시트: {ws.title}\n" + "\n".join(rows))
+        return "\n\n".join(blocks)
+    finally:
+        wb.close()
+
+
+def _extract_docx(data: bytes) -> str:
+    """DOCX → 문단 + 표 텍스트."""
+    from docx import Document
+
+    doc = Document(io.BytesIO(data))
+    parts: list[str] = [p.text for p in doc.paragraphs if p.text.strip()]
+    for table in doc.tables:
+        for row in table.rows:
+            line = " | ".join(c.text for c in row.cells)
+            if line.strip():
+                parts.append(line)
+    return "\n".join(parts)
+
+
+def _extract_pptx(data: bytes) -> str:
+    """PPTX → 슬라이드별 텍스트(도형·표) + 발표자 노트."""
+    from pptx import Presentation
+
+    prs = Presentation(io.BytesIO(data))
+    parts: list[str] = []
+    for i, slide in enumerate(prs.slides, 1):
+        slide_lines: list[str] = []
+        for shape in slide.shapes:
+            if shape.has_text_frame and shape.text_frame.text.strip():
+                slide_lines.append(shape.text_frame.text.strip())
+            if shape.has_table:
+                for row in shape.table.rows:
+                    cells = [c.text for c in row.cells]
+                    if any(c.strip() for c in cells):
+                        slide_lines.append(" | ".join(cells))
+        # 발표자 노트 (있으면)
+        if slide.has_notes_slide:
+            notes = slide.notes_slide.notes_text_frame.text
+            if notes and notes.strip():
+                slide_lines.append(f"(노트) {notes.strip()}")
+        if slide_lines:
+            parts.append(f"## 슬라이드 {i}\n" + "\n".join(slide_lines))
+    return "\n\n".join(parts)
+
+
+# ─── 디스패치 ──────────────────────────────────────────────────────────────
+
+# 텍스트 추출이 되는 포맷.
+_EXTRACTORS = {
+    "hwp":  _extract_hwp,
+    "hwpx": _extract_hwpx,
+    "pdf":  _extract_pdf,
+    "xlsx": _extract_xlsx,
+    "docx": _extract_docx,
+    "pptx": _extract_pptx,
+}
+
+# 텍스트 본문이 없는 게 정상인 포맷 → 브리핑 빈칸 (사유 명시).
+_NO_TEXT_KINDS = {
+    "jpg": "이미지 문서 (사진) — 텍스트 본문 없음",
+    "jpeg": "이미지 문서 (사진) — 텍스트 본문 없음",
+    "png": "이미지 문서 — 텍스트 본문 없음",
+    "gif": "이미지 문서 — 텍스트 본문 없음",
+    "tif": "이미지 문서 — 텍스트 본문 없음",
+    "tiff": "이미지 문서 — 텍스트 본문 없음",
+    "bmp": "이미지 문서 — 텍스트 본문 없음",
+    "heic": "이미지 문서 — 텍스트 본문 없음",
+    "dwg": "도면(CAD) — 텍스트 본문 없음",
+    "dxf": "도면(CAD) — 텍스트 본문 없음",
+}
+
+
+def _ext_of(filename: str) -> str:
+    m = re.search(r"\.([A-Za-z0-9]+)\s*$", filename or "")
+    return m.group(1).lower() if m else ""
+
+
+def _count_chars(text: str) -> int:
+    return len(re.sub(r"\s+", "", text or ""))
+
+
+def extract_text(data: bytes, filename: str) -> ExtractResult:
+    """파일 바이트 + 파일명 → ExtractResult. 확장자로 포맷 판별."""
+    ext = _ext_of(filename)
+
+    if not data:
+        return ExtractResult(ok=False, text="", kind="unknown", char_count=0,
+                             reason="빈 파일")
+
+    # 텍스트 본문이 없는 포맷 (사진·도면) — 추출 시도 없이 빈칸.
+    if ext in _NO_TEXT_KINDS:
+        return ExtractResult(ok=False, text="", kind=ext, char_count=0,
+                             reason=_NO_TEXT_KINDS[ext])
+
+    extractor = _EXTRACTORS.get(ext)
+    if extractor is None:
+        # .hwp 3.x, .xls/.ppt(구버전), 기타 미지원 → 빈칸 (환각 대신 정직)
+        return ExtractResult(ok=False, text="", kind=ext or "unknown", char_count=0,
+                             reason=f"지원하지 않는 형식(.{ext or '?'}) — PDF/HWP(5.x)/HWPX/XLSX/DOCX/PPTX 만 지원")
+
+    try:
+        text = extractor(data) or ""
+    except Exception as e:
+        # DRM 걸린 hwp, 손상 파일 등 → 빈칸 (사유 기록)
+        return ExtractResult(ok=False, text="", kind=ext, char_count=0,
+                             reason=f"본문 추출 실패: {str(e)[:160]}")
+
+    n = _count_chars(text)
+    if n < MIN_TEXT_CHARS:
+        return ExtractResult(
+            ok=False, text=text, kind=ext, char_count=n,
+            reason="본문 텍스트가 거의 없음 (스캔 이미지/빈 문서 가능성)",
+        )
+
+    return ExtractResult(ok=True, text=text, kind=ext, char_count=n, reason="")

package/python/doc_summary_engine_handoff/requirements.txt

@@ -0,0 +1,15 @@
+openai>=1.30
+python-dotenv>=1.0
+
+# HTTP API 서버
+fastapi>=0.110
+uvicorn[standard]>=0.27
+python-multipart>=0.0.9
+
+# 문서 텍스트 추출
+olefile>=0.46          # .hwp (한글 5.x, OLE 복합문서) → 텍스트
+PyMuPDF>=1.23          # .pdf → 텍스트 (import 명은 fitz)
+openpyxl>=3.1          # .xlsx → 시트 텍스트
+python-docx>=1.1       # .docx → 텍스트
+python-pptx>=0.6       # .pptx → 슬라이드 텍스트 + 노트
+# .hwpx 는 표준 라이브러리(zipfile + xml.etree)로 처리 — 추가 의존성 없음