@dssp/dcsp 1.0.2 → 1.0.6

package/python/spec-matching-0.5.5/README.md

@@ -0,0 +1,113 @@
+# Spec Matching - Operato Runner Package
+
+건설공사 **검사항목**을 ① **KCS 표준 조항**(`kcs.csv`)과 ② **현장 시방서**(프로젝트별 PDF) 양쪽에서 의미적으로 가장 유사한 조항에 자동 매칭하는 시스템입니다. **SBERT(문장 임베딩)** 기반으로 외부 LLM API 없이 로컬에서 동작합니다.
+
+## 데이터 구조
+
+| 데이터 | 역할 | 출처 |
+| --- | --- | --- |
+| **검사항목 (query)** | 매칭할 질의 (공통 체크리스트 항목) | 호출 시 JSON으로 전달 |
+| **KCS 표준** | 표준 조항 6천여 건 | `kcs.csv` (패키지에 영구 보관) |
+| **현장 시방서** | 프로젝트별 실제 시공 기준 | PDF URL (호출 시 전달, 다운로드/파싱) |
+
+→ 검사항목 1건 입력 → `kcs_matches`(KCS 조항) + `site_spec_matches`(현장 시방서 조항)를 각각 반환.
+
+## 사용법
+
+### Operato Runner에서 실행
+
+```python
+input_data = {
+    "query": "합성수지제 창호의 보양 및 검사를 적합하게 시행하였는가",
+    "site_spec_pdf_url": "https://dcsp.hatiolab.com/attachment/xxxx.pdf",
+    "top_k": 5
+}
+
+result = main(input_data)
+```
+
+### 명령행(CLI) 실행
+
+```bash
+source .venv/bin/activate
+python __main__.py '{"query": "먹놓기는 적합하게 시공되었는가", "top_k": 3}'
+```
+
+인자 없이 실행하면 기본 테스트 입력(KCS 매칭만)으로 동작합니다.
+
+## 입력 파라미터
+
+| 키 | 타입 | 필수 | 설명 |
+| --- | --- | --- | --- |
+| `query` | str | ✅ | 매칭할 검사항목 텍스트 |
+| `site_spec_pdf_url` | str | ⬜ | 현장 시방서 PDF URL (없으면 KCS만 매칭) |
+| `headers` | dict | ⬜ | PDF 다운로드 시 HTTP 헤더 (인증 토큰/쿠키 등) |
+| `top_k` | int | ⬜ | 각 항목별 반환 후보 수 (기본 5) |
+
+## 응답 형식
+
+```json
+{
+  "status": "success",
+  "result": {
+    "query": "합성수지제 창호의 보양 및 검사를 적합하게 시행하였는가",
+    "kcs_matches": [
+      {
+        "file_label": "(개정) KCS 41 55 03 합성수지제 창호공사",
+        "clause_no": "3.3",
+        "clause_title": "보양 및 검사",
+        "text": "...",
+        "score": 0.72
+      }
+    ],
+    "site_spec_matches": [
+      { "text": "3.3 보양 및 검사 합성수지제 창호는 설치 후 ...", "score": 0.73 }
+    ]
+  }
+}
+```
+
+- `site_spec_pdf_url`을 안 주면 `site_spec_matches`는 빈 배열입니다.
+- PDF 처리 중 오류가 나도 KCS 결과는 그대로 반환되며, `result.site_spec_error`에 사유가 담깁니다.
+
+## 출력 필드
+
+- `kcs_matches`: KCS 표준 조항 후보 (유사도 내림차순)
+  - `file_label`: KCS 문서명(공사명), `clause_no`: 조항 번호, `clause_title`: 조항 제목, `text`: 조항 본문, `score`: 코사인 유사도
+- `site_spec_matches`: 현장 시방서 조항 후보 (`text`, `score`)
+
+## 에러 응답
+
+```json
+{ "status": "error", "error": "에러 메시지" }
+```
+
+주요 에러: `query` 누락, `kcs.csv` 없음.
+
+## 환경 설정
+
+Python 3.12 권장 (torch 호환).
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+> 최초 실행 시 SBERT 모델(약 수백 MB)을 Hugging Face Hub에서 자동 다운로드합니다.
+
+## 동작 메모
+
+- **KCS 임베딩 캐시**: 최초 1회 `kcs.csv` 전체(약 6천 건)를 임베딩해 `kcs_embeddings.npy`로 저장합니다(1~2분 소요). 이후 호출은 캐시를 재사용해 빠르게 동작합니다. `kcs.csv`가 바뀌면 자동으로 다시 계산합니다.
+- **현장 시방서 캐시**: 같은 PDF URL은 프로세스 동안 1회만 다운로드/파싱합니다.
+- **조항 분할**: PDF 텍스트는 조항 번호 헤더(예: `3.3`, `2.1.5`) 기준으로 우선 분할하고, 패턴이 없으면 길이 기준으로 분할합니다. 실제 현장 시방서 PDF의 추출 형식에 따라 분할 품질이 달라질 수 있어 필요 시 튜닝합니다.
+- 외부 LLM API를 사용하지 않으므로 API 키·과금이 없습니다.
+
+## 구성 파일
+
+| 파일명 | 설명 |
+| --- | --- |
+| `__main__.py` | operato-runner용 메인 처리 함수(`main(input)`) + CLI 진입점 |
+| `kcs.csv` | KCS 표준 조항 데이터 (영구 보관) |
+| `kcs_embeddings.npy` / `*.meta.json` | KCS 임베딩 디스크 캐시 (자동 생성) |
+| `requirements.txt` | 필요한 Python 패키지 |

package/python/spec-matching-0.5.5/__main__.py

@@ -0,0 +1,331 @@
+import os
+import re
+import json
+import csv
+import tempfile
+import urllib.request
+import numpy as np
+from sentence_transformers import SentenceTransformer
+from sklearn.metrics.pairwise import cosine_similarity
+from pypdf import PdfReader
+
+
+# =========================
+# Config
+# =========================
+SBERT_MODEL_NAME = "snunlp/KR-SBERT-V40K-klueNLI-augSTS"
+script_dir = os.path.dirname(os.path.abspath(__file__))
+
+KCS_CSV_PATH = os.path.join(script_dir, "kcs.csv")           # 영구 보관되는 KCS 표준 데이터
+KCS_EMB_CACHE = os.path.join(script_dir, "kcs_embeddings.npy")  # KCS 임베딩 디스크 캐시
+KCS_META_CACHE = os.path.join(script_dir, "kcs_embeddings.meta.json")
+EMBED_SCHEME = "file_label+clause_title+text/v2"  # 임베딩 텍스트 구성 방식 (바뀌면 캐시 무효화)
+
+
+# =========================
+# Utilities
+# =========================
+def normalize_name(s: str) -> str:
+    # 공백 정리 등 텍스트 정규화
+    s = str(s or "").strip()
+    s = re.sub(r"\s+", " ", s)
+    return s
+
+
+def _size_chunks(text: str, target_size: int, min_size: int):
+    # 라인 단위로 나눈 뒤 target_size 근처까지 그리디하게 병합 (폴백용)
+    lines = [ln.strip() for ln in re.split(r"[\n\r]+", text) if ln.strip()]
+    chunks = []
+    buf = ""
+    for ln in lines:
+        if not buf:
+            buf = ln
+        elif len(buf) + 1 + len(ln) <= target_size:
+            buf += " " + ln
+        else:
+            chunks.append(buf)
+            buf = ln
+    if buf:
+        chunks.append(buf)
+    return [c for c in chunks if len(c) >= min_size]
+
+
+def chunk_text(full_text: str, target_size: int = 500, min_size: int = 15):
+    """
+    PDF 전체 텍스트를 조항 단위에 가까운 청크로 분할.
+    1) 조항 번호 헤더(예: '3.3 보양', '2.1.5 일반') 앞에서 우선 분할
+    2) 조항 분할이 안 되면 size 기반 병합으로 폴백
+    """
+    text = re.sub(r"[ \t]+", " ", full_text)
+    # 조항 번호 헤더 앞에 분할점 삽입 (번호 뒤에 한글 제목이 오는 패턴)
+    parts = re.split(r"(?=(?<![\d.])\d+(?:\.\d+){0,3}\s+[가-힣])", text)
+    parts = [re.sub(r"\s+", " ", p).strip() for p in parts]
+    parts = [p for p in parts if len(p) >= min_size]
+
+    if len(parts) >= 2:
+        chunks = []
+        for p in parts:
+            # 한 조항이 너무 길면 size 기준으로 추가 분할
+            if len(p) <= target_size * 2:
+                chunks.append(p)
+            else:
+                chunks.extend(_size_chunks(p, target_size, min_size))
+        return chunks
+
+    # 폴백: 조항 패턴이 없을 때
+    return _size_chunks(text, target_size, min_size)
+
+
+# =========================
+# SBERT Matching Engine
+# =========================
+class SBERTIndex:
+    """텍스트 임베딩 인덱스. meta로 각 텍스트의 부가정보를 함께 보관."""
+
+    def __init__(self, model: SentenceTransformer):
+        self.model = model
+        self.texts = []
+        self.meta = []
+        self.emb = None
+
+    def build(self, texts, meta=None, batch_size=64, precomputed_emb=None):
+        # 텍스트 리스트를 정규화 후 임베딩 (precomputed_emb 있으면 재사용)
+        self.texts = [normalize_name(t) for t in texts]
+        self.meta = meta if meta is not None else [{} for _ in self.texts]
+        if precomputed_emb is not None:
+            self.emb = precomputed_emb
+        else:
+            self.emb = self.model.encode(
+                self.texts,
+                normalize_embeddings=True,
+                batch_size=batch_size,
+                show_progress_bar=False
+            )
+
+    def search(self, query: str, top_k=5):
+        # 쿼리와 코사인 유사도가 높은 top_k 의 (text, meta, score) 반환
+        if self.emb is None or len(self.texts) == 0:
+            return []
+        q = normalize_name(query)
+        q_emb = self.model.encode([q], normalize_embeddings=True, batch_size=1)
+        sims = cosine_similarity(q_emb, self.emb)[0]
+        idx = sims.argsort()[::-1][:top_k]
+        return [(self.texts[i], self.meta[i], float(sims[i])) for i in idx]
+
+
+# 모델 로딩은 비싸므로 프로세스 단위로 1회만 (lazy 싱글톤)
+_MODEL = None
+_KCS_INDEX = None
+_SITE_SPEC_CACHE = {}  # url -> SBERTIndex
+
+
+def get_model() -> SentenceTransformer:
+    # SBERT 모델 싱글톤
+    global _MODEL
+    if _MODEL is None:
+        _MODEL = SentenceTransformer(SBERT_MODEL_NAME, device="cpu")  # CUDA OOM 방지
+    return _MODEL
+
+
+def _load_kcs_rows():
+    # KCS 표준 CSV 로드 (BOM 처리)
+    rows = []
+    with open(KCS_CSV_PATH, "r", encoding="utf-8-sig", newline="") as f:
+        reader = csv.DictReader(f)
+        for r in reader:
+            text = (r.get("text") or "").strip()
+            clause_title = (r.get("clause_title") or "").strip()
+            if not text and not clause_title:
+                continue
+            rows.append({
+                "file_label": (r.get("file_label") or "").strip(),
+                "section_no": (r.get("section_no") or "").strip(),
+                "clause_no": (r.get("clause_no") or "").strip(),
+                "clause_title": clause_title,
+                "text": text,
+            })
+    return rows
+
+
+def _kcs_cache_valid(rows_count: int) -> bool:
+    # 캐시 메타가 현재 CSV/스킴과 일치하는지 검증
+    if not (os.path.exists(KCS_EMB_CACHE) and os.path.exists(KCS_META_CACHE)):
+        return False
+    try:
+        with open(KCS_META_CACHE, "r", encoding="utf-8") as f:
+            meta = json.load(f)
+    except Exception:
+        return False
+    st = os.stat(KCS_CSV_PATH)
+    return (
+        meta.get("scheme") == EMBED_SCHEME
+        and meta.get("model") == SBERT_MODEL_NAME
+        and meta.get("csv_size") == st.st_size
+        and meta.get("rows") == rows_count
+    )
+
+
+def get_kcs_index() -> SBERTIndex:
+    # KCS 인덱스 싱글톤 (임베딩은 디스크 캐시 재사용, 없으면 계산 후 저장)
+    global _KCS_INDEX
+    if _KCS_INDEX is not None:
+        return _KCS_INDEX
+
+    rows = _load_kcs_rows()
+    # 매칭에 사용할 텍스트: 공사명(file_label) + 조항제목 + 본문
+    # (공사 도메인이 검색에 반영되도록 file_label 포함)
+    embed_texts = [
+        normalize_name(f"{r['file_label']} {r['clause_title']} {r['text']}") for r in rows
+    ]
+
+    model = get_model()
+    idx = SBERTIndex(model)
+
+    if _kcs_cache_valid(len(rows)):
+        emb = np.load(KCS_EMB_CACHE)
+        idx.build(embed_texts, meta=rows, precomputed_emb=emb)
+    else:
+        idx.build(embed_texts, meta=rows, batch_size=64)
+        np.save(KCS_EMB_CACHE, idx.emb)
+        st = os.stat(KCS_CSV_PATH)
+        with open(KCS_META_CACHE, "w", encoding="utf-8") as f:
+            json.dump({
+                "scheme": EMBED_SCHEME,
+                "model": SBERT_MODEL_NAME,
+                "csv_size": st.st_size,
+                "rows": len(rows),
+            }, f, ensure_ascii=False)
+
+    _KCS_INDEX = idx
+    return idx
+
+
+def _download_pdf(url: str, headers: dict = None) -> str:
+    # PDF를 URL에서 임시파일로 다운로드하고 경로 반환
+    req = urllib.request.Request(url, headers=headers or {"User-Agent": "spec-matching/1.0"})
+    fd, path = tempfile.mkstemp(suffix=".pdf")
+    os.close(fd)
+    with urllib.request.urlopen(req, timeout=60) as resp, open(path, "wb") as out:
+        out.write(resp.read())
+    return path
+
+
+def get_site_spec_index(pdf_url: str, headers: dict = None) -> SBERTIndex:
+    # 현장 시방서 PDF 인덱스 (URL별 프로세스 캐시)
+    if pdf_url in _SITE_SPEC_CACHE:
+        return _SITE_SPEC_CACHE[pdf_url]
+
+    pdf_path = _download_pdf(pdf_url, headers=headers)
+    try:
+        reader = PdfReader(pdf_path)
+        full_text = "\n".join([p.extract_text() or "" for p in reader.pages])
+    finally:
+        try:
+            os.remove(pdf_path)
+        except OSError:
+            pass
+
+    chunks = chunk_text(full_text)
+    idx = SBERTIndex(get_model())
+    idx.build(chunks, meta=[{"chunk_index": i} for i in range(len(chunks))], batch_size=64)
+    _SITE_SPEC_CACHE[pdf_url] = idx
+    return idx
+
+
+def match_kcs(query: str, top_k=5):
+    # 검사항목 → KCS 표준 조항 매칭
+    hits = get_kcs_index().search(query, top_k=top_k)
+    out = []
+    for _text, meta, score in hits:
+        out.append({
+            "file_label": meta.get("file_label", ""),
+            "clause_no": meta.get("clause_no", ""),
+            "clause_title": meta.get("clause_title", ""),
+            "text": meta.get("text", ""),
+            "score": score,
+        })
+    return out
+
+
+def match_site_spec(query: str, pdf_url: str, top_k=5, headers: dict = None):
+    # 검사항목 → 현장 시방서(PDF) 조항 매칭
+    hits = get_site_spec_index(pdf_url, headers=headers).search(query, top_k=top_k)
+    return [{"text": text, "score": score} for text, _meta, score in hits]
+
+
+def main(input):
+    """
+    operato-runner에서 호출되는 메인 함수.
+
+    검사항목(query) 1건을 받아, KCS 표준 조항(kcs.csv)과 현장 시방서(PDF URL)
+    양쪽에서 의미적으로 가장 유사한 조항을 각각 반환한다. 외부 LLM API 미사용.
+
+    Args:
+        input (dict):
+            - 'query' (str, 필수): 검사항목 텍스트
+            - 'site_spec_pdf_url' (str, 선택): 현장 시방서 PDF URL (없으면 KCS만)
+            - 'headers' (dict, 선택): PDF 다운로드 시 사용할 HTTP 헤더(인증 등)
+            - 'top_k' (int, 선택, 기본 5): 각 항목별 반환 후보 수
+
+    Returns:
+        dict: 실행 결과
+    """
+    try:
+        raw_input = input  # 원본(감싸진 형태 포함) 보존
+        # input 키로 몇 겹 감싸져 들어와도 query가 나올 때까지 벗김
+        while isinstance(input, dict) and "query" not in input and isinstance(input.get("input"), dict):
+            input = input["input"]
+        query = normalize_name(input.get("query", ""))
+        pdf_url = (input.get("site_spec_pdf_url") or "").strip()
+        headers = input.get("headers") or None
+        top_k = int(input.get("top_k", 5))
+
+        if not query:
+            return {
+                "status": "error",
+                "error": "query가 제공되지 않았습니다.",
+                "received_type": type(raw_input).__name__,
+                "received_keys": list(raw_input.keys()) if isinstance(raw_input, dict) else None,
+                "received": raw_input,
+            }
+        if not os.path.exists(KCS_CSV_PATH):
+            return {"status": "error", "error": f"KCS 표준 데이터를 찾을 수 없습니다: {KCS_CSV_PATH}"}
+
+        result = {
+            "query": query,
+            "kcs_matches": match_kcs(query, top_k=top_k),
+            "site_spec_matches": [],
+        }
+
+        # 현장 시방서 PDF가 주어지면 매칭, 실패해도 KCS 결과는 유지
+        if pdf_url:
+            try:
+                result["site_spec_matches"] = match_site_spec(
+                    query, pdf_url, top_k=top_k, headers=headers
+                )
+            except Exception as e:
+                result["site_spec_error"] = f"현장 시방서 처리 실패: {str(e)}"
+
+        return {"status": "success", "result": result}
+
+    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:
+        # 기본 테스트 입력 (PDF 없이 KCS 매칭만)
+        input_data = {
+            "query": "합성수지제 창호의 보양 및 검사를 적합하게 시행하였는가",
+            "top_k": 3
+        }
+
+    result = main(input_data)
+    print(json.dumps(result, ensure_ascii=False, indent=2))