@dssp/dcsp 1.0.2 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dssp/dcsp",
-  "version": "1.0.2",
+  "version": "1.0.6",
   "main": "dist-server/index.js",
   "browser": "dist-client/index.js",
   "things-factory": true,
@@ -39,11 +39,11 @@
     "docker:push": "docker image push hatiolab/dcsp:latest && docker image push hatiolab/dcsp:$npm_package_version"
   },
   "dependencies": {
-    "@dssp/building-complex": "^1.0.1",
-    "@dssp/integration-allbaro": "^1.0.1",
-    "@dssp/integration-kiscon": "^1.0.1",
-    "@dssp/project": "^1.0.2",
-    "@dssp/supervision": "^1.0.1",
+    "@dssp/building-complex": "^1.0.6",
+    "@dssp/integration-allbaro": "^1.0.5",
+    "@dssp/integration-kiscon": "^1.0.5",
+    "@dssp/project": "^1.0.6",
+    "@dssp/supervision": "^1.0.6",
     "@material/web": "^2.4.0",
     "@operato/chart": "^10.0.0",
     "@operato/gantt": "^10.0.0",
@@ -81,6 +81,7 @@
     "@things-factory/i18n-base": "^10.0.0",
     "@things-factory/integration-base": "^10.0.0",
     "@things-factory/integration-ui": "^10.0.0",
+    "@things-factory/kpi": "^10.0.0",
     "@things-factory/lite-menu": "^10.0.0",
     "@things-factory/more-base": "^10.0.0",
     "@things-factory/more-ui": "^10.0.0",
@@ -95,5 +96,5 @@
   "devDependencies": {
     "@things-factory/builder": "^10.0.0"
   },
-  "gitHead": "73037725ffc0a7f33220490a54a5b9482a560b3f"
+  "gitHead": "f6b181b9e137f92aaf9e516f7c9f0b706fbd6035"
 }

package/python/RUNNER_CONVERSION_GUIDE.md

@@ -0,0 +1,81 @@
+# operato-runner 파이썬 모듈 변환 지침
+
+외부에서 받은 파이썬 소스(FastAPI 서버, CLI 스크립트 등)를 **operato-runner 모듈**로 변환할 때 따르는 규칙.
+이 폴더의 세 모듈이 레퍼런스다.
+
+| 폴더 | 기능 | 원본 형태 | 비고 |
+|---|---|---|---|
+| `doc_summary_engine_handoff` | 문서 요약 | FastAPI (`api.py`) | 가장 단순한 레퍼런스 |
+| `spec-matching-0.5.5` | KCS 시방서 매칭 | 단일 스크립트 | SBERT 임베딩 캐시 파일 동봉 |
+| `inspection_ai_engine_handoff` | 시공감리 AI 검측 | FastAPI (`api.py`) | action 분기(멀티 기능) 레퍼런스 |
+
+## 핵심 원칙
+
+1. **엔진 로직은 건드리지 않는다.** 원본의 비즈니스 로직 파일(`engine.py`, `activities.py` 등)은 그대로 두고,
+   `__main__.py` 진입점 파일 **하나만 새로 만든다**. 원본 `api.py`도 삭제하지 않고 참고용으로 남긴다.
+2. **보안**: OpenAI 등 API 키는 코드/클라이언트에 절대 넣지 않는다. runner 모듈의 **env-vars 설정**으로만 주입한다
+   (`os.environ.get(...)`, 로컬 개발용으로만 `.env` + dotenv 허용).
+3. 함수/어려운 로직에는 한국어 주석.
+
+## `__main__.py` 필수 구조
+
+```python
+def main(input):
+    """operato-runner가 호출하는 진입점. input은 dict."""
+    try:
+        # 1) input 언랩: 'input' 키로 몇 겹 감싸져 와도 필수 키가 나올 때까지 벗긴다.
+        #    단, runner가 최상위에 주입하는 input_files는 벗긴 뒤에도 유지(setdefault).
+        # 2) 파라미터 파싱/검증 (JSON 문자열로 온 배열도 json.loads 허용)
+        # 3) 기존 엔진 함수 호출
+        return {"status": "success", "result": {...}}
+    except Exception as e:
+        return {"status": "error", "error": f"처리 중 오류가 발생했습니다: {str(e)}"}
+
+if __name__ == "__main__":
+    # 로컬 테스트: python __main__.py '{"...": ...}' 또는 기본 테스트 입력
+    import sys, json
+    input_data = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {기본 테스트 입력}
+    print(json.dumps(main(input_data), ensure_ascii=False, indent=2))
+```
+
+### 반환 형식 (고정)
+
+- 성공: `{"status": "success", ..., "result": {엔진 결과}}`
+- 실패: `{"status": "error", "error": "메시지"}` — 예외를 밖으로 던지지 않는다.
+
+### 파일 입력 (사진/문서)
+
+runner가 multipart `files`로 업로드된 파일을 `input["input_files"]`로 주입한다:
+`[{file_id, path, filename, content_type, size}]` — `path`를 열어서 읽는다.
+URL 입력도 지원하려면 `image_urls`/`file_urls` + 선택적 `headers`(다운로드용 HTTP 헤더)를 함께 받는다.
+개수/크기 제한은 env로 조절 가능하게 (`..._MAX_IMAGES`, `..._MAX_BYTES` 패턴).
+
+### 멀티 기능(엔드포인트가 여러 개였던 경우)
+
+원본 FastAPI에 엔드포인트가 여러 개면 `input["action"]`으로 분기한다.
+예: inspection — `action: "plan-shots" | "inspect"`, 생략 시 사진 유무로 기본값 결정.
+
+### 기타 관례
+
+- `script_dir = os.path.dirname(os.path.abspath(__file__))` 기준으로 동봉 데이터 파일(csv, 캐시 등) 접근.
+- HEIC 등 특수 포맷 지원(`pillow_heif`)이나 dotenv는 `try/except ImportError`로 감싸서 선택 의존성으로.
+- 배포 전 `__pycache__` 삭제 후 폴더 전체를 zip.
+
+## 호출 방법 (WAS 클라이언트 쪽)
+
+```
+POST {runner-host}/api/run/{module-name}
+Content-Type: multipart/form-data
+  input: JSON 문자열 (파라미터)
+  files: 업로드 파일들 (선택)
+Authorization: Basic (runner 계정)
+```
+
+응답의 `result` 키(중첩돼 있으면 `raw?.result`)를 언랩해서 사용한다.
+
+## 배포 체크리스트
+
+1. `__pycache__` 삭제 → 폴더 zip
+2. runner에 모듈 업로드/활성화 (모듈명 예: `inspection-ai`, `doc-summary`)
+3. 모듈 env-vars에 `OPENAI_API_KEY` 등 비밀키 등록
+4. `python __main__.py`(기본 테스트 입력)로 로컬 스모크 테스트 먼저

package/python/doc_summary_engine_handoff/.env.example

@@ -0,0 +1,21 @@
+# 필수: OpenAI API 키
+OPENAI_API_KEY=sk-...
+
+# 사용할 모델
+OPENAI_MODEL=gpt-5.5
+
+# 브리핑 reasoning 강도 (none|low|medium|high|xhigh)
+# - 한 줄 브리핑은 충실한 압축이 목적 → low 권장 (속도·비용↓, 환각 여지↓).
+# - reasoning 미지원 모델이면 자동 무시.
+DOC_BRIEF_REASONING_EFFORT=low
+
+# ── HTTP API (api.py) ─────────────────────────────────────────────
+DOC_API_PORT=8100
+DOC_API_MAX_BYTES=31457280          # 파일 1개 최대 크기 (30MB)
+DOC_API_ALLOWED_ORIGINS=*           # 운영에선 플랫폼 도메인 명시 권장
+
+# ── 추출/요약 튜닝 (보통 기본값으로 충분) ─────────────────────────
+# DOC_MIN_TEXT_CHARS=20             # 이보다 본문이 짧으면 브리핑 빈칸
+# DOC_MAX_XLSX_ROWS=200             # 엑셀 시트당 읽을 최대 행
+# DOC_SINGLE_PASS_CHARS=12000       # 이보다 길면 map-reduce
+# DOC_CHUNK_CHARS=8000              # map 단계 청크 크기

package/python/doc_summary_engine_handoff/HANDOFF.md

@@ -0,0 +1,266 @@
+# 문서 AI 브리핑 엔진 — 인계 문서
+
+> 받는 분: 시공감리 플랫폼을 개발하시는 분께.
+> 「현장 문서 확인」 의 문서 상세에 **한 줄 "✨ AI 브리핑"** 을 채우기 위한 엔진입니다.
+> 이 문서 하나로 통합에 필요한 정보 다 들어 있습니다.
+
+---
+
+## 1. 이 엔진이 무엇을 하는가
+
+플랫폼에 등록된 문서(HWP/PDF/Excel 등) 파일 하나를 받아, 본문을 읽고
+**감리자·시공자가 클릭 한 번에 내용을 파악할 수 있는 한 줄 브리핑**을 돌려주는 HTTP API.
+
+```
+[현장 문서 확인]                                [이 엔진]
+  문서 업로드
+       │
+       └─ POST /brief-doc ───────────────▶  ① 파일 종류 판별 (hwp/hwpx/pdf/xlsx/docx/pptx)
+           (multipart)                        ② 본문 텍스트 추출
+           file: <문서파일>                   ③ LLM 으로 한 줄 브리핑 생성
+           category: "사업관리 · …"           ④ { briefing: "...", ... } 반환
+           ◀ { briefing, doc_type, ... }
+                                              → 플랫폼이 briefing 을 DB 에 저장
+                                              → 문서 클릭 시 "✨ AI 브리핑" 칸에 표시
+```
+
+핵심 특성:
+- **문서종류 무관** — 공문·보고서·일지·계획표·대장 등 분류 전체를 한 파이프라인으로.
+- **Stateless** — DB·세션 없음. 브리핑 저장은 플랫폼 측.
+- **환각 최소화가 1순위** — 본문에 있는 내용만 사용. 텍스트를 못 읽는 문서(스캔 PDF·도면·사진·DRM hwp)는 **억지로 지어내지 않고 `briefing: null`** 로 반환.
+
+---
+
+## 2. 빠른 시작 (10분)
+
+```bash
+cd doc_summary_engine
+pip install -r requirements.txt
+
+# .env 만들기 (.env.example 복사 후 OPENAI_API_KEY 채우기)
+cp .env.example .env
+
+python api.py
+#  → http://localhost:8100
+#  → Swagger UI: http://localhost:8100/docs
+```
+
+검증:
+```bash
+curl http://localhost:8100/health
+
+curl -X POST http://localhost:8100/brief-doc \
+  -F "file=@문서명 04.hwp" \
+  -F "category=사업관리 · 공사작업일보 · 민원처리보고"
+```
+
+> `pyhwp` 설치가 환경에 따라 까다로울 수 있습니다(§7 참고). PDF/XLSX 먼저 검증하셔도 됩니다.
+
+---
+
+## 3. 통합 지점 — 「현장 문서 확인」
+
+문서 상세 영역의 **"✨ AI 브리핑"** 칸(현재 빈칸)을 채우는 한 곳만 연결하면 됩니다.
+
+| 시점 | 동작 | API |
+|---|---|---|
+| **문서 업로드 시 (권장)** | 파일을 엔진에 1회 보내 `briefing` 을 받아 **문서 레코드에 저장** | `POST /brief-doc` |
+| 문서 클릭(상세 열기) | 저장된 `briefing` 을 "✨ AI 브리핑" 칸에 표시 (재호출 X) | — |
+| `briefing` 이 `null` 인 경우 | 칸을 비우거나 "본문을 읽을 수 없는 문서" 안내 (`note` 참고) | — |
+
+> **왜 업로드 시 1회인가:** 엔진은 stateless 라 클릭마다 호출하면 매번 LLM 비용·지연이
+> 발생합니다. 업로드 때 한 번 생성해 저장하면 클릭은 즉시·무료. 재생성이 필요하면
+> (문서 교체 등) 그때만 다시 호출.
+
+### 권장 배치 구조 (보안)
+
+```
+[브라우저/앱] ── HTTPS ──▶ [플랫폼 백엔드] ── HTTP(내부망) ──▶ [이 엔진] ── OpenAI
+                              │                                  │
+                              │ 인증/로깅/브리핑 DB 저장           │ OpenAI API 호출
+```
+
+**OpenAI 키를 프론트엔드에 넣지 마세요.** 반드시 플랫폼 백엔드에서 이 엔진으로 프록시.
+
+---
+
+## 4. HTTP API 상세
+
+서버 기본 `http://localhost:8100` (Swagger: `/docs`).
+
+### GET /health
+
+```json
+{
+  "ok": true,
+  "server_time": 1716700000.1,
+  "supported_formats": ["hwp", "hwpx", "pdf", "xlsx", "docx", "pptx"],
+  "model": "gpt-5.5"
+}
+```
+
+### POST /brief-doc
+
+문서 1개 → 한 줄 브리핑. **multipart/form-data**.
+
+| 필드 | 타입 | 필수 | 설명 |
+|---|---|---|---|
+| `file` | file | ✅ | 문서 파일 1개. HWP(5.x)/HWPX/PDF/XLSX/DOCX/PPTX. |
+| `category` | text | ❌ | 분류 문자열(대/중/소분류). 근거 힌트. 예: `"사업관리 · 공사작업일보 · 민원처리보고"`. |
+| `filename` | text | ❌ | 파일명 override. 없으면 업로드 파일명 사용. |
+
+**응답 (200):**
+```json
+{
+  "ok": true,
+  "filename": "문서명 04.hwp",
+  "kind": "hwp",
+  "char_count": 812,
+  "briefing": "OO 시행사의 PF 조달 및 분양가 갈등에 따른 공사 중지 지시(20.03.18)와 (주)OO건설의 현장 관리 계획 회신·사업 협의에 대한 공문입니다.",
+  "doc_type": "공문",
+  "has_content": true,
+  "note": "",
+  "model": "gpt-5.5",
+  "elapsed_sec": 2.1
+}
+```
+
+**필드 의미:**
+- `briefing`: 화면 "✨ AI 브리핑" 칸에 그대로 표시. **`null` 이면 본문을 읽지 못한 것** → 칸 비움.
+- `doc_type`: 본문 근거로 추정한 문서 종류(공문/보고서/회의록/계획서/기타). 표시는 선택.
+- `has_content`: 브리핑을 실제로 생성했는지 (`briefing != null` 과 동일 취지).
+- `note`: `briefing` 이 `null` 일 때 사유(사람용). 예: `"이미지 문서 (사진) — 텍스트 본문 없음"`, `"본문 텍스트가 거의 없음 (스캔 이미지/빈 문서 가능성)"`, `"지원하지 않는 형식(.hwp 3.x …)"`.
+- `kind`: 판별된 파일 종류. `char_count`: 추출된 본문 글자 수(공백 제외).
+
+> **항상 200 입니다.** 읽을 수 없는 문서도 에러가 아니라 `briefing: null` + `note` 로 정상 반환합니다 (UI 분기 단순화).
+
+**에러 응답:**
+- 400 — 빈 파일.
+- 413 — 파일 크기 초과(`DOC_API_MAX_BYTES`, 기본 30MB).
+- 500 — OpenAI 클라이언트 초기화 실패(`OPENAI_API_KEY` 누락 등).
+
+---
+
+## 5. 호출 예제
+
+### JavaScript (업로드 직후 브리핑 받아 저장)
+
+```js
+async function makeBriefing(fileBlob, fileName, categoryLabel) {
+  const fd = new FormData();
+  fd.append("file", fileBlob, fileName);
+  fd.append("category", categoryLabel ?? "");
+
+  const res = await fetch("http://engine:8100/brief-doc", { method: "POST", body: fd });
+  const data = await res.json();
+
+  // data.briefing 을 문서 레코드에 저장.
+  // null 이면 빈칸 (data.note 에 사유).
+  return data.briefing;   // 문서 클릭 시 "✨ AI 브리핑" 칸에 이 값 표시
+}
+```
+
+### Python (서버측 프록시)
+
+```python
+import requests
+
+with open(path, "rb") as f:
+    resp = requests.post(
+        "http://engine:8100/brief-doc",
+        files={"file": (file_name, f)},
+        data={"category": "사업관리 · 공사작업일보 · 민원처리보고"},
+        timeout=120,
+    )
+briefing = resp.json()["briefing"]   # None 이면 빈칸
+```
+
+### curl
+
+```bash
+curl -X POST http://localhost:8100/brief-doc \
+  -F "file=@report.pdf" \
+  -F "category=공정관리 · 공정관리계획 · 주간공정현황보고"
+```
+
+---
+
+## 6. 환각(없는 내용 지어내기) 방지 설계
+
+플랫폼 화면에 잘못된 한 줄이 뜨면 신뢰를 크게 해치므로, 다음 3중으로 막습니다:
+
+1. **추출 본문에만 근거** — 프롬프트가 "본문에 없는 사실·배경·추측은 절대 쓰지 마라" 를 명시. 분류명(category)을 근거로 내용을 지어내는 것도 금지(힌트로만).
+2. **못 읽으면 차라리 빈칸** — 텍스트가 빈약하거나(스캔·이미지) 형식을 못 읽으면(DRM hwp 등) **LLM 을 아예 호출하지 않고** `briefing: null` 반환. 비용도 0.
+3. **모델 자체 거부 허용** — 본문이 있어도 요지를 확정 못 하면 모델이 `briefing: null` 을 내도록 허용(억지 요약 금지).
+
+> 그래도 LLM 요약은 100% 정확을 보장하지 않습니다. 화면에 "AI 자동 생성 — 참고용"
+> 정도의 라벨을 같이 두는 것을 권장합니다.
+
+---
+
+## 7. 파일 구성 & HWP 관련 주의
+
+```
+doc_summary_engine/
+├── api.py            # HTTP API (FastAPI) — 진입점. POST /brief-doc
+├── extract.py        # 파일 → 본문 텍스트 (hwp/hwpx/pdf/xlsx/docx/pptx)
+├── summarize.py      # 본문 → 한 줄 브리핑 (OpenAI, 긴 문서 map-reduce)
+├── requirements.txt
+├── .env.example      # (실제 .env 는 키 포함 — 별도 전달, 커밋 금지)
+├── .gitignore
+├── HANDOFF.md        # 이 문서
+└── README.md
+```
+
+**`.hwp` (한글 5.x) 텍스트 추출 = `pyhwp`:**
+- 한컴 오피스 설치 없이 순수 파이썬으로 본문 추출. 공문·보고서처럼 글 위주 문서에 충분.
+- `pip install pyhwp` 가 환경에 따라 빌드 이슈가 있을 수 있음 → 설치 안 되면
+  엔진은 `hwp5txt` CLI 폴백도 시도. 둘 다 안 되면 그 문서만 `briefing: null`(다른 포맷은 정상).
+- **못 읽는 경우 (정상적으로 빈칸 처리):** HWPX 가 아닌 신형 일부, HWP 3.x, DRM/암호 hwp, 스캔 PDF, 사진·도면(jpg/png/dwg). → `note` 에 사유.
+- 표·그림 레이아웃은 손실되지만 한 줄 브리핑에는 영향 적음.
+
+---
+
+## 8. 환경변수
+
+| 변수 | 기본값 | 의미 |
+|---|---|---|
+| `OPENAI_API_KEY` | (필수) | OpenAI 키. |
+| `OPENAI_MODEL` | `gpt-5.5` | 요약 모델. |
+| `DOC_BRIEF_REASONING_EFFORT` | `low` | `none\|low\|medium\|high\|xhigh`. 브리핑은 low 권장. |
+| `DOC_API_PORT` | `8100` | HTTP 서버 포트. (검측 엔진 8000 과 분리) |
+| `DOC_API_MAX_BYTES` | `31457280` | 파일 1개 최대 크기(30MB). |
+| `DOC_API_ALLOWED_ORIGINS` | `*` | CORS. 운영에선 도메인 명시 권장. |
+| `DOC_MIN_TEXT_CHARS` | `20` | 본문이 이보다 짧으면 빈칸. |
+| `DOC_SINGLE_PASS_CHARS` | `12000` | 이보다 길면 map-reduce 요약. |
+
+---
+
+## 9. 성능/비용 메모
+
+- 한 문서 = LLM 호출 **1회**(짧은 문서) ~ **여러 회**(긴 문서 map-reduce). 보통 1~5초.
+- **업로드 시 1회 생성·저장** 구조면 클릭 시 추가 호출 0 → 사용자 체감 즉시.
+- 못 읽는 문서는 LLM 호출 0(비용 0).
+
+---
+
+## 10. 자주 받는 질문
+
+**Q: 여러 문서를 한 번에 보낼 수 있나요?**
+A: 현재는 1개씩(`/brief-doc`). 배치(`/brief-docs`)가 필요하면 추가 가능 — 요청 주세요.
+
+**Q: 브리핑을 더 길게/짧게, 또는 정해진 양식으로?**
+A: 문구·길이·항목은 `summarize.py` 의 프롬프트 한 곳에서 조정. 원하는 형태 알려주시면 맞춥니다.
+
+**Q: 이미지(사진)·도면도 브리핑 되나요?**
+A: 현재는 텍스트 문서만. 사진·도면은 `briefing: null`. 이미지 브리핑은 Vision 모델이 필요한 별개 작업 — 필요 시 검측 엔진(VLM)과 연계해 추가 가능.
+
+**Q: 파일을 base64 JSON 으로 보낼 수 있나요?**
+A: 현재 multipart 만. base64 JSON 도 받게 추가 가능 — 요청 주세요.
+
+**Q: 인증/권한은?**
+A: 엔진 자체엔 없음. 플랫폼 백엔드/게이트웨이에서 처리. CORS 만 주의.
+
+---
+
+문의: (보내실 분 정보)

package/python/doc_summary_engine_handoff/README.md

@@ -0,0 +1,71 @@
+# 문서 AI 브리핑 엔진
+
+시공감리 플랫폼 「현장 문서 확인」 의 문서를 받아, 문서 상세의 **한 줄 "✨ AI 브리핑"** 을
+채워주는 HTTP API.
+
+```
+[현장 문서 확인]                 [엔진]
+  문서 업로드
+       │
+       └─ POST /brief-doc ──▶  hwp/hwpx/pdf/xlsx/docx/pptx 본문 추출
+                               → LLM 한 줄 브리핑
+                               → { briefing: "...", ... }
+                               → 플랫폼이 저장, 클릭 시 "✨ AI 브리핑" 칸에 표시
+```
+
+특징:
+- **문서종류 무관** — 공문·보고서·일지·계획표·대장 등 분류 전체를 한 파이프라인으로
+- **Stateless** — 저장은 플랫폼 측 (업로드 시 1회 생성·저장 권장)
+- **환각 최소화** — 본문에 있는 내용만. 못 읽는 문서(스캔·도면·사진·DRM)는 `briefing: null`
+
+상세 통합 가이드는 **[HANDOFF.md](HANDOFF.md)** 참고.
+
+---
+
+## 빠른 시작
+
+```bash
+pip install -r requirements.txt
+cp .env.example .env        # OPENAI_API_KEY 채우기
+python api.py
+#   → http://localhost:8100   (Swagger: /docs)
+```
+
+```bash
+curl -X POST http://localhost:8100/brief-doc \
+  -F "file=@report.pdf" \
+  -F "category=공정관리 · 공정관리계획 · 주간공정현황보고"
+```
+
+기본 모델 `gpt-5.5`. `.env` 의 `OPENAI_MODEL`/`DOC_BRIEF_REASONING_EFFORT` 로 변경.
+
+---
+
+## 파일 구성
+
+```
+doc_summary_engine/
+├── api.py            # HTTP API (FastAPI) — POST /brief-doc
+├── extract.py        # 파일 → 본문 텍스트 (hwp/hwpx/pdf/xlsx/docx/pptx)
+├── summarize.py      # 본문 → 한 줄 브리핑 (OpenAI, 긴 문서 map-reduce)
+├── requirements.txt
+├── .env / .env.example
+├── HANDOFF.md        # 통합 가이드 (이거 보세요)
+└── README.md         # 이 파일
+```
+
+---
+
+## 지원 포맷
+
+| 포맷 | 추출 방법 |
+|---|---|
+| `.hwp` (한글 5.x) | pyhwp (한컴 설치 불필요) |
+| `.hwpx` | zip + XML (표준 라이브러리) |
+| `.pdf` | PyMuPDF |
+| `.xlsx` | openpyxl (시트 → 표) |
+| `.docx` | python-docx |
+| `.pptx` | python-pptx (슬라이드 텍스트 + 노트) |
+
+스캔 PDF·사진(jpg/png)·도면(dwg/dxf)·DRM hwp 등 텍스트를 읽을 수 없는 문서는
+`briefing: null` + `note`(사유)로 정상 반환합니다.

package/python/doc_summary_engine_handoff/__main__.py

@@ -0,0 +1,159 @@
+"""문서 AI 브리핑 — operato-runner 진입점.
+
+문서 파일 1개(URL 또는 로컬 경로)를 받아 본문을 추출하고 한 줄 AI 브리핑을 반환한다.
+텍스트를 못 읽는 문서(스캔·도면·사진·DRM·미지원 형식)는 briefing=null 로 정상 응답 (환각 방지).
+
+지원 포맷: HWP(5.x) / HWPX / PDF / XLSX / DOCX / PPTX
+"""
+import os
+import json
+import urllib.request
+from urllib.parse import urlparse, unquote
+
+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
+
+from extract import extract_text
+from summarize import brief_document
+
+MAX_BYTES = int(os.environ.get("DOC_API_MAX_BYTES", str(30 * 1024 * 1024)))  # 30MB
+
+
+def _download(url: str, headers: dict = None) -> bytes:
+    # 문서 파일을 URL에서 다운로드하여 바이트로 반환
+    req = urllib.request.Request(url, headers=headers or {"User-Agent": "doc-summary/1.0"})
+    with urllib.request.urlopen(req, timeout=120) as resp:
+        return resp.read()
+
+
+def _filename_from_url(url: str) -> str:
+    # URL 경로의 마지막 세그먼트를 파일명으로 사용 (확장자 판별용)
+    return unquote(os.path.basename(urlparse(url).path))
+
+
+def main(input):
+    """
+    operato-runner에서 호출되는 메인 함수.
+
+    문서 1건을 받아 본문 텍스트를 추출하고 OpenAI로 한 줄 브리핑을 생성한다.
+    본문을 읽을 수 없는 문서는 briefing=null 로 정상 응답한다 (내용을 지어내지 않음).
+
+    Args:
+        input (dict):
+            - 'file_url' (str): 문서 파일 URL (file_path 없으면 필수)
+            - 'file_path' (str, 선택): 로컬 파일 경로 (테스트/공유 볼륨용, file_url보다 우선)
+            - 'filename' (str, 선택): 파일명 — 확장자 판별용. 없으면 URL/경로에서 유추
+            - 'category' (str, 선택): 문서 분류(대/중/소분류) 문자열. LLM 근거 힌트
+            - 'headers' (dict, 선택): 파일 다운로드 시 HTTP 헤더(인증 등)
+
+    Returns:
+        dict: {"status": "success", "result": {filename, kind, char_count,
+               briefing, doc_type, has_content, note, model, elapsed_sec}}
+    """
+    try:
+        raw_input = input  # 원본(감싸진 형태 포함) 보존
+        # input 키로 몇 겹 감싸져 들어와도 파일 정보가 나올 때까지 벗김
+        while (
+            isinstance(input, dict)
+            and not any(k in input for k in ("file_url", "file_path", "documentPath", "input_files"))
+            and isinstance(input.get("input"), dict)
+        ):
+            input = input["input"]
+
+        file_path = (input.get("file_path") or "").strip()
+        file_url = (input.get("file_url") or input.get("documentPath") or "").strip()
+        filename = (input.get("filename") or input.get("documentName") or "").strip()
+        category = (input.get("category") or "").strip()
+        headers = input.get("headers") or None
+
+        # operato-runner 파일 업로드 실행 지원: 업로드 파일은 input_files로 주입됨
+        # [{"file_id", "path", "filename", "content_type", "size"}, ...] — 첫 번째 파일 사용
+        input_files = input.get("input_files") or []
+        if not file_path and input_files:
+            file_path = (input_files[0].get("path") or "").strip()
+            filename = filename or (input_files[0].get("filename") or "").strip()
+
+        # 1) 파일 바이트 확보 (로컬 경로 우선, 없으면 URL 다운로드)
+        if file_path:
+            filename = filename or os.path.basename(file_path)
+            with open(file_path, "rb") as f:
+                data = f.read()
+        elif file_url.lower().startswith(("http://", "https://")):
+            filename = filename or _filename_from_url(file_url)
+            data = _download(file_url, headers=headers)
+        else:
+            return {
+                "status": "error",
+                "error": "file_url(또는 file_path)이 제공되지 않았습니다.",
+                "received_type": type(raw_input).__name__,
+                "received_keys": list(raw_input.keys()) if isinstance(raw_input, dict) else None,
+            }
+
+        if not data:
+            return {"status": "error", "error": "빈 파일입니다."}
+        if len(data) > MAX_BYTES:
+            return {"status": "error", "error": f"파일 크기 초과 ({len(data)} > {MAX_BYTES} bytes)."}
+
+        model = os.environ.get("OPENAI_MODEL", "gpt-5.5")
+
+        # 2) 본문 추출 — 못 읽으면 LLM 호출 없이 브리핑 빈칸으로 정상 응답 (환각 방지 + 비용 0)
+        ex = extract_text(data, filename)
+        if not ex.ok:
+            return {
+                "status": "success",
+                "result": {
+                    "filename": filename,
+                    "kind": ex.kind,
+                    "char_count": ex.char_count,
+                    "briefing": None,
+                    "doc_type": "기타",
+                    "has_content": False,
+                    "note": ex.reason,
+                    "model": model,
+                    "elapsed_sec": 0.0,
+                },
+            }
+
+        # 3) 한 줄 브리핑 (OpenAI)
+        r = brief_document(ex.text, filename=filename, category=category)
+        return {
+            "status": "success",
+            "result": {
+                "filename": filename,
+                "kind": ex.kind,
+                "char_count": ex.char_count,
+                "briefing": r.briefing,
+                "doc_type": r.doc_type,
+                "has_content": r.has_content,
+                "note": r.note,
+                "model": r.model,
+                "elapsed_sec": r.elapsed_sec,
+            },
+        }
+
+    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:
+        # 기본 테스트 입력 (file_url을 지정해야 동작)
+        input_data = {
+            "file_url": "",
+            "category": "사업관리 · 공사작업일보 · 민원처리보고",
+        }
+
+    result = main(input_data)
+    print(json.dumps(result, ensure_ascii=False, indent=2))