structverify 0.3.0__py3-none-any.whl

structverify/retrieval/custom_db_source.py

@@ -0,0 +1,396 @@
+"""structverify.retrieval.custom_db_source — Custom DB DataSource.
+
+회사 자체 DB(테이블)를 정답 데이터로 사용. CustomCSV와 동일한 인터페이스로,
+행을 CSV 대신 **SQL 테이블에서 조회**한다.
+
+SQLAlchemy DSN 하나로 sqlite / postgresql / snowflake / mysql 등을 지원:
+    sqlite:///path.db
+    postgresql://user:pw@host:5432/db
+    snowflake://user:pw@account/DB/SCHEMA?warehouse=WH
+
+가정 테이블 형태: indicator, year, region, value, unit (CSV와 동일).
+컬럼명이 다르면 column_mapping 으로 매핑. (Snowflake는 컬럼이 대문자로 오므로 매핑 권장.)
+"""
+from __future__ import annotations
+
+import os
+import re
+from typing import Any
+
+from .base import CatalogCandidate, EvidenceData
+from .custom_csv_source import CustomCSVDataSource, _DEFAULT_COLUMN_MAPPING
+from .registry import register_datasource
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# ── 에이전틱(text-to-SQL) 모드 SQL 안전 가드 ──
+# 원장형 원시 테이블을 정답으로 쓸 때, LLM이 claim마다 집계 SQL을 생성한다.
+# 파괴적/부작용 SQL을 원천 차단 — SELECT/WITH 로 시작하는 단일문만 허용.
+_SQL_FORBIDDEN = re.compile(
+    r"\b(insert|update|delete|drop|alter|create|merge|truncate|grant|revoke|"
+    r"call|copy|use|set|comment|put|remove|unload)\b",
+    re.IGNORECASE,
+)
+
+
+def _is_safe_select(sql: str) -> bool:
+    """읽기 전용 단일 SELECT/WITH 문인지 검증. 아니면 실행 거부."""
+    s = (sql or "").strip().rstrip(";").strip()
+    if not s:
+        return False
+    if not re.match(r"(?is)^\s*(with|select)\b", s):
+        return False
+    if ";" in s:  # 다중문 차단
+        return False
+    if _SQL_FORBIDDEN.search(s):
+        return False
+    return True
+
+
+@register_datasource("custom_db")
+class CustomDBDataSource(CustomCSVDataSource):
+    """회사 DB 테이블 데이터소스 (CustomCSV 상속 — 조회만 DB로).
+
+    config 예 (data_sources.custom_db):
+        dsn: "sqlite:///company.db"          # 또는 dsn_env 로 환경변수 지정
+        dsn_env: "CUSTOM_DB_DSN"
+        table: "reference_values"            # 조회할 테이블 (스키마 포함 가능)
+        query: "SELECT ... FROM ..."         # (선택) 직접 SQL — table 대신
+        column_mapping: {value: "VAL", ...}  # 테이블 컬럼명 매핑 (선택)
+    """
+
+    name = "custom_db"
+
+    def __init__(self, **config: Any):
+        self.config = config
+        # DSN: 직접 주입 우선, 없으면 환경변수(dsn_env, 기본 CUSTOM_DB_DSN)
+        self.dsn = config.get("dsn") or os.getenv(
+            config.get("dsn_env") or "CUSTOM_DB_DSN", ""
+        )
+        self.table = config.get("table") or config.get("catalog_table") or ""
+        self.query = config.get("query")  # 직접 SQL (선택)
+        self.column_mapping = {
+            **_DEFAULT_COLUMN_MAPPING,
+            **(config.get("column_mapping") or {}),
+        }
+        self._cache: list[dict[str, str]] | None = None
+        # 임베딩 검색 필드 (부모 CustomCSVDataSource와 동일 — 지표 방대 시 의미검색).
+        # __init__을 완전히 오버라이드하므로 여기서 직접 세팅해야 한다.
+        self._embed_cfg = config.get("embedding") or {}
+        self._embed_threshold = int(config.get("embed_threshold", 200))
+        self._embed_client = None
+        self._ind_index: list[dict] | None = None
+        # ── 에이전틱(text-to-SQL) 모드 ──
+        # agentic=True면 '지표=값' 정돈 테이블을 가정하지 않고, 원시 테이블 스키마를
+        # 조사해 claim마다 집계 SQL을 LLM이 생성/실행한다("총 매출=SUM(...)"을 자동 정의).
+        self.agentic = bool(config.get("agentic"))
+        self.tables = list(config.get("tables") or [])   # (선택) 조사 대상 테이블 화이트리스트
+        self._schema_text: str | None = None
+        logger.info(
+            f"[CustomDBDataSource] 초기화: table={self.table!r}, "
+            f"dsn={'(set)' if self.dsn else '(none)'}, column_mapping={self.column_mapping}"
+        )
+
+    def _read_rows(self) -> list[dict[str, str]]:
+        """DB 테이블 전체 행을 dict 리스트로 (문자열 정규화). 1회 캐시."""
+        if self._cache is not None:
+            return self._cache
+        if not self.dsn:
+            logger.warning("[CustomDBDataSource] DSN 없음 (dsn 또는 CUSTOM_DB_DSN 설정 필요)")
+            return []
+        try:
+            import sqlalchemy as sa
+        except ImportError as e:  # pragma: no cover
+            raise ImportError(
+                "DB 커넥터는 SQLAlchemy가 필요합니다: pip install \"structverify[db]\" "
+                "(Snowflake는 추가로 snowflake-sqlalchemy)"
+            ) from e
+
+        sql = self.query or f"SELECT * FROM {self.table}"
+        try:
+            engine = sa.create_engine(self.dsn)
+            with engine.connect() as conn:
+                result = conn.execute(sa.text(sql))
+                raw = [dict(r._mapping) for r in result]
+        except Exception as e:  # noqa: BLE001 — 조회 실패는 빈 결과로(파이프라인 보호)
+            logger.warning(f"[CustomDBDataSource] DB 조회 실패: {e}")
+            return []
+
+        # 값 str 정규화(None→"") + 컬럼명 casing 정규화.
+        # DB/드라이버마다 결과 키 대소문자가 다르다(snowflake-sqlalchemy는 소문자,
+        # postgres는 소문자, 일부는 대문자). column_mapping이 어떤 casing이든 맞도록,
+        # 각 행에 매핑 대상 이름을 case-insensitive로 채워 넣는다.
+        targets = {v for v in self.column_mapping.values() if isinstance(v, str)}
+        rows: list[dict[str, str]] = []
+        for row in raw:
+            low = {
+                (k.lower() if isinstance(k, str) else k): ("" if v is None else str(v))
+                for k, v in row.items()
+            }
+            norm = dict(low)  # 소문자 키 접근 보존
+            for t in targets:  # 매핑이 요구하는 정확한 이름으로도 접근 가능하게
+                norm[t] = low.get(t.lower(), low.get(t, ""))
+            rows.append(norm)
+        self._cache = rows
+        logger.info(f"[CustomDBDataSource] {len(rows)}행 로드 (table={self.table!r})")
+        return rows
+
+    # ══════════════════════════════════════════════════════════════════
+    #  에이전틱(text-to-SQL) 모드 — 원시 테이블을 정답으로. 스키마 조사 후
+    #  claim마다 집계 SQL을 LLM이 생성/실행. ('총 매출=SUM(...)' 자동 정의)
+    # ══════════════════════════════════════════════════════════════════
+
+    def _engine(self):
+        import sqlalchemy as sa
+        return sa.create_engine(self.dsn)
+
+    def _list_tables(self) -> list[str]:
+        """조사 대상 테이블. tables 화이트리스트 우선, 없으면 스키마에서 자동 탐색."""
+        if self.tables:
+            return self.tables
+        try:
+            import sqlalchemy as sa
+            insp = sa.inspect(self._engine())
+            return list(insp.get_table_names())[:12]
+        except Exception as e:  # noqa: BLE001
+            logger.warning(f"[custom_db/agentic] 테이블 자동탐색 실패: {e}")
+            return []
+
+    @staticmethod
+    def _infer_relationships(table_cols: dict[str, list[str]]) -> str:
+        """FK 메타가 없을 때, 컬럼명으로 테이블 간 조인 관계를 추정.
+
+        분석용 DB는 FK 선언이 없는 경우가 많다. 대신 key/id 성격 컬럼을 테이블 접두어를
+        떼고(base) 묶어, 같은 base를 가진 서로 다른 테이블의 컬럼쌍을 조인 후보로 본다.
+        (예: ORDERS.o_custkey ↔ CUSTOMER.c_custkey — 둘 다 base='custkey')
+        """
+        from collections import defaultdict
+        groups: dict[str, list[tuple[str, str]]] = defaultdict(list)
+        for t, cols in table_cols.items():
+            for c in cols:
+                cl = str(c).lower()
+                base = re.sub(r"^[a-z]+_", "", cl)  # 테이블 접두어 제거
+                if base.endswith("key") or base.endswith("id"):
+                    groups[base].append((t, c))
+        lines: list[str] = []
+        for base, tc in groups.items():
+            if len(tc) < 2:
+                continue
+            for i in range(len(tc)):
+                for j in range(i + 1, len(tc)):
+                    lines.append(f"  {tc[i][0]}.{tc[i][1]} = {tc[j][0]}.{tc[j][1]}")
+        return "\n".join(lines)
+
+    def _introspect_schema(self) -> str:
+        """각 테이블을 LIMIT 조회해 (컬럼명 + 샘플값 + 조인관계)로 스키마 텍스트 구성. 1회 캐시.
+
+        DB 방언 무관하게 동작하도록 information_schema 대신 `SELECT * ... LIMIT`을 쓴다.
+        FK 메타가 없어도 컬럼명으로 조인 관계를 추정해 넣어(다중테이블 집계 신뢰도↑).
+        """
+        if self._schema_text is not None:
+            return self._schema_text
+        import sqlalchemy as sa
+        eng = self._engine()
+        parts: list[str] = []
+        table_cols: dict[str, list[str]] = {}
+        for t in self._list_tables():
+            try:
+                with eng.connect() as conn:
+                    res = conn.execute(sa.text(f"SELECT * FROM {t} LIMIT 3"))
+                    cols = list(res.keys())
+                    sample = [dict(r._mapping) for r in res]
+                table_cols[t] = [str(c) for c in cols]
+                col_line = ", ".join(str(c) for c in cols)
+                samp_line = ""
+                if sample:
+                    first = {k: sample[0][k] for k in list(sample[0])[:8]}
+                    samp_line = f"\n    예시행: {first}"
+                parts.append(f"- 테이블 {t} (컬럼: {col_line}){samp_line}")
+            except Exception as e:  # noqa: BLE001
+                logger.warning(f"[custom_db/agentic] 스키마 조사 실패({t}): {e}")
+        rels = self._infer_relationships(table_cols)
+        if rels:
+            parts.append(f"\n[테이블 간 조인 관계 (컬럼명 기반 추정 — JOIN에 사용)]\n{rels}")
+        self._schema_text = "\n".join(parts) if parts else "(스키마 조사 실패)"
+        logger.info(
+            f"[custom_db/agentic] 스키마 조사: {len(table_cols)}개 테이블"
+            f"{', 조인관계 ' + str(len(rels.splitlines())) + '쌍' if rels else ''}"
+        )
+        return self._schema_text
+
+    async def propose_metrics(self, config: dict | None = None) -> dict[str, Any]:
+        """스키마를 보고 이 데이터로 검증 가능한 지표 후보를 LLM이 제안(프로파일러용)."""
+        schema = self._introspect_schema()
+        from structverify.utils.llm_client import LLMClient
+        llm = LLMClient(config=(config or {}).get("llm", {}))
+        prompt = (
+            "아래는 회사 DB의 원시 테이블 스키마다. 이 데이터를 SQL 집계로 검증할 수 있는 "
+            "'지표(metric)' 후보를 제안하라. 트랜잭션 원장이면 합계/건수/평균 등으로 지표를 만든다.\n\n"
+            f"[스키마]\n{schema}\n\n"
+            "JSON만:\n"
+            '{"domain":"영문 스네이크 도메인","description":"이 데이터가 다루는 내용 한 문장",'
+            '"metrics":[{"indicator":"지표명(한글)","unit":"단위"}, ...]}'
+        )
+        try:
+            out = await llm.generate_json_light(prompt) or {}
+        except Exception as e:  # noqa: BLE001
+            logger.warning(f"[custom_db/agentic] 지표 제안 실패: {e}")
+            out = {}
+        metrics = out.get("metrics") or []
+        inds = [str(m.get("indicator", "")).strip() for m in metrics if m.get("indicator")]
+        units = [str(m.get("unit", "")).strip() for m in metrics if m.get("unit")]
+        return {
+            "domain": str(out.get("domain", "") or "").strip(),
+            "description": str(out.get("description", "") or "").strip(),
+            "indicators": inds,
+            "units": list(dict.fromkeys(units)),
+            "samples": [f"{i} ({u})" for i, u in zip(inds, units)][:6],
+        }
+
+    async def _agentic_fetch(
+        self, indicator: str, params: dict[str, Any]
+    ) -> EvidenceData | None:
+        """claim (지표/시점/대상)에 대해 LLM이 집계 SQL 생성 → 실행 → 단일 값 반환.
+
+        LLM SQL은 가끔 FROM 누락/오타가 있으므로, 에러를 피드백해 최대 2회 재시도한다.
+        """
+        schema = self._introspect_schema()
+        dialect = (self.dsn.split(":", 1)[0] if self.dsn else "sql").split("+")[0]
+        tp = str(params.get("time_period") or "").strip()
+        pop = str(params.get("population") or "").strip()
+        raw_claim = str(params.get("raw_claim") or params.get("claim_text") or "").strip()
+        # 목표 단위 — 파생계산 판단의 핵심 신호(%이면 비율/증감율). schema.unit에서 옴.
+        unit_hint = str(params.get("unit_hint") or params.get("unit") or "").strip()
+        _is_derived = ("%" in unit_hint) or any(
+            k in indicator for k in ("비율", "비중", "증감율", "증가율", "감소율", "변화율")
+        )
+        from structverify.utils.llm_client import LLMClient
+        llm = LLMClient(config=(self.config.get("llm") if isinstance(self.config, dict) else {}) or {})
+
+        base_prompt = (
+            f"너는 {dialect} SQL 분석가다. 아래 원시 테이블에서 주장 검증에 필요한 값을 "
+            "구하는 **완전히 실행 가능한 단일 SELECT** 집계 쿼리를 작성하라. 결과는 값 1개(스칼라).\n\n"
+            f"[스키마]\n{schema}\n\n"
+            f"[검증할 지표] {indicator}\n"
+            # ★ 절대값엔 스케일 단위(억/만 달러)를 목표로 주면 LLM이 raw값에 그 라벨을
+            #   붙여 스케일이 어긋난다. 파생(%)만 목표단위 명시, 절대값은 '원시 단위' 지시.
+            f"[목표 단위] {'%  ← 파생 계산(비율/증감율). 규칙 8 적용.' if _is_derived else '원시 단위 — 달러/명/건 등, 억·만·조 접두어 금지(값도 나누지 말 것)'}\n"
+            f"[시점] {tp or '(무관/전체)'}\n"
+            f"[대상/지역] {pop or '(전체)'}\n"
+            f"[주장 원문] {raw_claim or '(없음)'}\n\n"
+            "규칙(엄수):\n"
+            "1. SELECT/WITH로 시작하는 읽기전용 단일문. 반드시 **FROM 절**로 실제 테이블을 참조.\n"
+            "2. 결과 컬럼 1개(집계 원시값). 컬럼/테이블명은 위 스키마에 있는 것만.\n"
+            "3. **최소 테이블 원칙**: 필터/집계에 필요한 컬럼이 한 테이블에 다 있으면 그 테이블만 "
+            "사용(불필요한 JOIN 금지 — 예: 세그먼트별 고객수는 CUSTOMER만; ORDERS를 조인하면 "
+            "주문 없는 고객이 빠져 값이 왜곡됨). 다른 테이블 컬럼이 실제로 필요할 때만, 위 '조인 "
+            "관계'의 컬럼쌍으로 JOIN. FROM에 없는 테이블/별칭 참조 금지.\n"
+            "4. 지표에 '누적/총/전체'가 있으면 시점 필터 없이 전체 집계. "
+            "특정 연도가 명시된 경우에만 날짜 컬럼으로 필터.\n"
+            "5. unit은 **기본 단위만**(명/건/개/달러/원 등). 억·만·조 배수 접두어 금지 "
+            "(값을 나누지 말고 원시 집계값 그대로 — 스케일은 비교 단계가 처리).\n"
+            "6. 지역/세그먼트 등 대상이 있으면 해당 명칭 컬럼으로 필터(예: 지역명, 세그먼트명).\n"
+            "7. **지표 의미 일관성**: 지표에 '순'(순매출·순이익 등)이 있으면 할인/공제를 반영한 "
+            "*순액*으로 계산(할인 컬럼이 있으면 반드시 반영, 예: 가격×(1-할인율)). '총'만 있고 "
+            "'순'이 없으면 총액. 같은 문서 안에서 같은 지표는 항상 같은 공식으로.\n"
+            "8. 세미콜론·주석·여러 문장 금지.\n"
+            "9. **파생 계산 여부는 오직 [검증할 지표]로 판단**(문장의 비교 문맥에 반응하지 말 것):\n"
+            "   - [검증할 지표]가 '비율/비중/증감율/증감량' 등 *계산된 지표*이거나 단위가 %면 → "
+            "원시 데이터로 파생값을 SQL로 직접 계산(결과 1개, unit='%'):\n"
+            "       · 비율/비중 = 부분 / 전체 × 100  (서브쿼리 2개를 나눔)\n"
+            "       · 증감율 = (현재 시점 값 − 이전 시점 값) / 이전 시점 값 × 100\n"
+            "   - [검증할 지표]가 *절대값*(매출·고객수·건수·금액 등)이면 → 문장에 '대비/감소/증가/"
+            "비율' 같은 표현이 있어도 **무시하고 그 절대값만** 집계(규칙 2~6 적용).\n"
+            "   ※ 조건부 합계에 `FILTER (WHERE ...)` 금지(방언 비호환). 두 시점 비교는 "
+            "**서브쿼리 2개**(예5 형태)나 `CASE WHEN`/`IFF`로만.\n"
+            "예1(단일테이블): SELECT COUNT(DISTINCT c_custkey) FROM CUSTOMER WHERE c_mktsegment='MACHINERY'\n"
+            "예2(연도필터): SELECT SUM(o_totalprice) FROM ORDERS WHERE YEAR(o_orderdate)=1996\n"
+            "예3(조인): SELECT SUM(o_totalprice) FROM ORDERS "
+            "JOIN CUSTOMER ON o_custkey=c_custkey "
+            "JOIN NATION ON c_nationkey=n_nationkey "
+            "JOIN REGION ON n_regionkey=r_regionkey WHERE r_name='EUROPE'\n"
+            "예4(비율): SELECT (SELECT SUM(l_extendedprice*(1-l_discount)) FROM LINEITEM l "
+            "JOIN ORDERS o ON l.l_orderkey=o.o_orderkey JOIN CUSTOMER c ON o.o_custkey=c.c_custkey "
+            "JOIN NATION n ON c.c_nationkey=n.n_nationkey JOIN REGION r ON n.n_regionkey=r.r_regionkey "
+            "WHERE r_name='AMERICA') / (SELECT SUM(l_extendedprice*(1-l_discount)) FROM LINEITEM) * 100\n"
+            "예5(증감율): SELECT (a.v - b.v)/b.v*100 FROM "
+            "(SELECT SUM(l_extendedprice*(1-l_discount)) v FROM LINEITEM l JOIN ORDERS o ON l.l_orderkey=o.o_orderkey "
+            "WHERE YEAR(o.o_orderdate)=1998) a, "
+            "(SELECT SUM(l_extendedprice*(1-l_discount)) v FROM LINEITEM l JOIN ORDERS o ON l.l_orderkey=o.o_orderkey "
+            "WHERE YEAR(o.o_orderdate)=1997) b\n"
+            "JSON만:\n"
+            '{"sql":"SELECT ... FROM ...","unit":"기본단위 또는 %"}'
+        )
+
+        err_hint = ""
+        for attempt in range(3):  # 복합 JOIN은 실패 시 에러 피드백으로 2회까지 재시도
+            prompt = base_prompt + (
+                f"\n\n[직전 실패] 다음 오류를 고쳐 다시 작성: {err_hint}" if err_hint else ""
+            )
+            try:
+                out = await llm.generate_json_light(prompt) or {}
+            except Exception as e:  # noqa: BLE001
+                logger.warning(f"[custom_db/agentic] SQL 생성 실패: {e}")
+                return None
+            sql = str(out.get("sql", "") or "").strip().rstrip(";").strip()
+            unit = str(out.get("unit", "") or "").strip()
+            # ★ 결정적 단위 정규화: SQL 결과는 항상 원시값이므로, LLM이 억/만/조 접두어를
+            #   붙였어도 제거해 기본단위로 강제(값-단위 일관성). 파생(%)은 접두어 없어 무영향.
+            #   예: "억 달러" → "달러", "만 건" → "건". (스케일은 비교 단계가 처리)
+            _stripped = re.sub(r"^\s*(천|만|억|조)\s*", "", unit).strip()
+            if _stripped:
+                unit = _stripped
+            # 가드: 읽기전용 + FROM 절 필수(FROM 없는 COUNT(*)가 1을 반환하는 silent-wrong 방지)
+            if not _is_safe_select(sql) or not re.search(r"(?is)\bfrom\b", sql):
+                err_hint = f"안전하지 않거나 FROM 누락: {sql[:120]!r}"
+                logger.warning(f"[custom_db/agentic] SQL 거부(시도 {attempt+1}): {err_hint}")
+                continue
+            try:
+                import sqlalchemy as sa
+                with self._engine().connect() as conn:
+                    row = conn.execute(sa.text(sql)).fetchone()
+            except Exception as e:  # noqa: BLE001
+                err_hint = " ".join(str(e).split())[:300]   # 개행 제거·더 많은 detail 전달
+                logger.warning(f"[custom_db/agentic] SQL 실행 실패(시도 {attempt+1}): {err_hint} — sql={sql[:120]!r}")
+                continue
+            if row is None or row[0] is None:
+                err_hint = "결과가 비었음 — 필터/조인 확인"
+                logger.info(f"[custom_db/agentic] 결과 없음(시도 {attempt+1}) — sql={sql[:120]!r}")
+                continue
+            try:
+                value = float(row[0])
+            except (TypeError, ValueError):
+                logger.warning(f"[custom_db/agentic] 스칼라 아님: {row[0]!r}")
+                return None
+            logger.info(
+                f"[custom_db/agentic] '{indicator}'(시점 {tp or '전체'}) → {value:g}{unit} "
+                f"| SQL={sql[:100]}"
+            )
+            return EvidenceData({
+                "value": value, "unit": unit, "time_period": tp,
+                "operator": "", "source": self.name, "indicator": indicator,
+                "region": pop, "matched_row": {"sql": sql},
+            })
+        logger.warning(f"[custom_db/agentic] '{indicator}' SQL 3회 실패 — 포기")
+        return None
+
+    # ── BaseDataSource 오버라이드 (에이전틱이면 SQL 경로, 아니면 정돈-테이블 경로) ──
+
+    async def search_catalog(
+        self, query: str, category: list | None = None,
+        top_k: int = 10, context: dict | None = None,
+    ) -> list[CatalogCandidate]:
+        if not self.agentic:
+            return await super().search_catalog(query, category, top_k, context)
+        # 에이전틱: 후보 발견이 따로 없다(값은 fetch에서 SQL로 계산). query 자체를 후보로.
+        return [CatalogCandidate({"id": query, "name": query, "score": 1.0})]
+
+    async def fetch_evidence(
+        self, candidate_id: str, params: dict | None = None, workspace: Any = None,
+    ) -> EvidenceData | None:
+        if not self.agentic:
+            return await super().fetch_evidence(candidate_id, params, workspace)
+        params = params or {}
+        indicator = str(params.get("indicator") or candidate_id or "").strip()
+        return await self._agentic_fetch(indicator, params)

structverify/retrieval/custom_docs_source.py

@@ -0,0 +1,152 @@
+"""structverify.retrieval.custom_docs_source — 문서형(광범위) 회사 데이터.
+
+사규·규정·계약 등 긴 자연어 문서를 **청킹 → 임베딩 → 의미검색** 한다.
+표형(custom_csv, 키워드)과 달리, 동의어/의역까지 매칭.
+
+- 색인: 문서 로드 → chunk_text로 조각 → 각 조각을 EmbeddingClient(config.embedding)로 임베딩.
+- 저장: in-memory (프로세스 내). 대규모는 pgvector 백엔드로 확장(계획 P3).
+- 검색: 질의 임베딩 → 코사인 top-k 청크.
+- 임베딩 provider는 config.embedding(hcx/openai/upstage) — 색인·질의 동일 client라 차원 self-consistent.
+"""
+from __future__ import annotations
+
+import math
+import os
+from typing import Any
+
+from .base import BaseDataSource, CatalogCandidate, EvidenceData
+from .chunking import chunk_text, read_document
+from .registry import register_datasource
+from structverify.utils.embedding_client import EmbeddingClient
+from structverify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def _cosine(a: list[float], b: list[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    return dot / (na * nb) if na and nb else 0.0
+
+
+@register_datasource("custom_docs")
+class CustomDocsDataSource(BaseDataSource):
+    """문서형 회사 데이터 — 청킹 후 임베딩 → 의미검색 (in-memory).
+
+    config 예 (data_sources.custom_docs):
+        docs_path: "./uploads/regulations"   # .txt/.md 파일 또는 디렉토리
+        chunk_size: 400
+        chunk_overlap: 60
+        top_k: 5
+        embedding: { provider: "upstage" }    # 색인·질의 임베딩 provider
+    """
+
+    name = "custom_docs"
+
+    def __init__(self, **config: Any):
+        self.config = config
+        self.docs_path = (
+            config.get("docs_path") or config.get("csv_path")
+            or config.get("base_path") or ""
+        )
+        self.chunk_size = int(config.get("chunk_size", 400))
+        self.overlap = int(config.get("chunk_overlap", 60))
+        self.top_k_default = int(config.get("top_k", 5))
+        self._client = EmbeddingClient(config.get("embedding") or {})
+        self._index: list[dict[str, Any]] | None = None  # [{id, text, vec}]
+        logger.info(
+            f"[CustomDocsDataSource] docs_path={self.docs_path!r} "
+            f"chunk_size={self.chunk_size} provider={self._client.provider}"
+        )
+
+    def _load_text(self) -> str:
+        p = self.docs_path
+        if not p or not os.path.exists(p):
+            logger.warning(f"[CustomDocsDataSource] 경로 없음: {p!r}")
+            return ""
+        if os.path.isdir(p):
+            texts = [
+                read_document(os.path.join(p, fn))
+                for fn in sorted(os.listdir(p))
+                if fn.lower().endswith((".txt", ".md", ".pdf"))
+            ]
+            return "\n\n".join(t for t in texts if t)
+        return read_document(p)
+
+    async def _ensure_index(self) -> None:
+        """최초 검색 시 1회: 문서 로드 → 청킹 → 임베딩 (in-memory)."""
+        if self._index is not None:
+            return
+        chunks = chunk_text(
+            self._load_text(), chunk_size=self.chunk_size, overlap=self.overlap,
+        )
+        idx: list[dict[str, Any]] = []
+        for i, c in enumerate(chunks):
+            vec = await self._client.embed(c, role="passage")   # 문서 색인 → passage 모델
+            if vec is None:
+                logger.warning(f"[CustomDocsDataSource] 청크 {i} 임베딩 실패 — skip")
+                continue
+            idx.append({"id": f"chunk#{i}", "text": c, "vec": vec})
+        self._index = idx
+        logger.info(
+            f"[CustomDocsDataSource] 색인 완료: {len(idx)}/{len(chunks)} 청크 임베딩 "
+            f"(provider={self._client.provider}, dim={len(idx[0]['vec']) if idx else 0})"
+        )
+
+    async def build_index(self) -> int:
+        """색인을 즉시 빌드하고 청크 수 반환 (업로드 직후 호출용)."""
+        await self._ensure_index()
+        return len(self._index or [])
+
+    async def search_catalog(
+        self, query: str, category: list[str] | None = None,
+        top_k: int | None = None, context: dict[str, Any] | None = None,
+    ) -> list[CatalogCandidate]:
+        await self._ensure_index()
+        if not self._index:
+            return []
+        qv = await self._client.embed(query, role="query")   # 검색어 → query 모델
+        if qv is None:
+            logger.warning("[CustomDocsDataSource] 질의 임베딩 실패")
+            return []
+        scored = sorted(
+            ((_cosine(qv, it["vec"]), it) for it in self._index),
+            key=lambda x: x[0], reverse=True,
+        )
+        k = top_k or self.top_k_default
+        out: list[CatalogCandidate] = [
+            {
+                "id": it["id"],
+                "name": it["text"][:40].replace("\n", " "),
+                "score": round(float(sc), 4),
+            }
+            for sc, it in scored[:k]
+        ]
+        logger.info(
+            f"[CustomDocsDataSource] search(query={query!r}): "
+            f"{len(out)}개 (top={out[0]['score'] if out else None})"
+        )
+        return out
+
+    async def fetch_evidence(
+        self, candidate_id: str, params: dict[str, Any] | None = None,
+        workspace: Any = None,
+    ) -> EvidenceData | None:
+        """검색된 청크 텍스트를 근거로 반환. (문서형 — 수치 없음, 텍스트가 근거)
+
+        수치 규정(예: '한도는 10만원')이면 후속 단계에서 텍스트→값 추출/LLM 준수판정 필요.
+        """
+        if self._index is None:
+            await self._ensure_index()
+        it = next((x for x in (self._index or []) if x["id"] == candidate_id), None)
+        if it is None:
+            return None
+        return {
+            "value": None,
+            "unit": "",
+            "time_period": "",
+            "text": it["text"],       # 검색된 규정 조각 (근거)
+            "source": "custom_docs",
+            "indicator": candidate_id,
+        }