Upload folder using huggingface_hub

src/cli/__init__.py

@@ -0,0 +1,3 @@
+"""GovOn CLI package."""
+
+__version__ = "1.0.1"

src/cli/approval_ui.py

@@ -0,0 +1,239 @@
+"""Approval / rejection UI for GovOn CLI.
+
+Renders a direction-key–driven prompt using `prompt_toolkit` when available.
+Falls back to a plain input() prompt if prompt_toolkit is not installed.
+"""
+
+from __future__ import annotations
+
+import unicodedata
+
+from src.cli.terminal import (
+    get_approval_box_width,
+    get_narrow_terminal_warning,
+    get_terminal_columns,
+    is_layout_supported,
+)
+
+_PT_AVAILABLE = False
+try:
+    from prompt_toolkit import Application
+    from prompt_toolkit.formatted_text import HTML
+    from prompt_toolkit.key_binding import KeyBindings
+    from prompt_toolkit.layout import Layout
+    from prompt_toolkit.layout.containers import HSplit, Window
+    from prompt_toolkit.layout.controls import FormattedTextControl
+
+    _PT_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    pass
+
+
+def _display_width(s: str) -> int:
+    """Return the display width of *s*, counting wide (CJK) chars as 2."""
+    w = 0
+    for ch in s:
+        eaw = unicodedata.east_asian_width(ch)
+        w += 2 if eaw in ("W", "F") else 1
+    return w
+
+
+def _box_line(content: str = "", *, width: int) -> str:
+    """Return a single box line padded to *width* display columns."""
+    pad = width - _display_width(content)
+    inner = content + " " * max(pad, 0)
+    return f"│ {inner} │"
+
+
+def _build_box_lines(
+    approval_request: dict, selected: int, box_width: int | None = None
+) -> list[str]:
+    """Build the raw text lines of the approval box (no ANSI needed here)."""
+    goal: str = approval_request.get("goal", "")
+    reason: str = approval_request.get("reason", "")
+    tool_summaries: list[str] = approval_request.get("tool_summaries") or []
+
+    w = get_approval_box_width(get_terminal_columns()) if box_width is None else box_width
+    _header = "─ 작업 승인 요청 "
+    top = "┌" + _header + "─" * max(w - _display_width(_header) + 2, 0) + "┐"
+    bot = "└" + "─" * (w + 2) + "┘"
+
+    lines: list[str] = [top, _box_line(width=w)]
+
+    def _wrap(label: str, value: str) -> None:
+        prefix = f"  {label}: "
+        available = max(w - _display_width(prefix), 1)
+        if _display_width(value) <= available:
+            lines.append(_box_line(f"{prefix}{value}", width=w))
+        else:
+            # Truncate value to fit within available display columns
+            chunk: list[str] = []
+            used = 0
+            for ch in value:
+                cw = 2 if unicodedata.east_asian_width(ch) in ("W", "F") else 1
+                if used + cw > available:
+                    break
+                chunk.append(ch)
+                used += cw
+            first = "".join(chunk)
+            lines.append(_box_line(f"{prefix}{first}", width=w))
+            rest = value[len(first) :]
+            while rest:
+                row: list[str] = []
+                used = 0
+                col_limit = w - 4
+                for ch in rest:
+                    cw = 2 if unicodedata.east_asian_width(ch) in ("W", "F") else 1
+                    if used + cw > col_limit:
+                        break
+                    row.append(ch)
+                    used += cw
+                seg = "".join(row)
+                lines.append(_box_line(f"    {seg}", width=w))
+                rest = rest[len(seg) :]
+
+    _wrap("목표", goal)
+    _wrap("이유", reason)
+
+    if tool_summaries:
+        lines.append(_box_line(width=w))
+        lines.append(_box_line("  수행할 작업:", width=w))
+        for idx, summary in enumerate(tool_summaries, 1):
+            prefix = f"    {idx}. "
+            avail = max(w - _display_width(prefix), 1)
+            if _display_width(summary) <= avail:
+                lines.append(_box_line(f"{prefix}{summary}", width=w))
+            else:
+                chunk2: list[str] = []
+                used2 = 0
+                for ch in summary:
+                    cw = 2 if unicodedata.east_asian_width(ch) in ("W", "F") else 1
+                    if used2 + cw > avail:
+                        break
+                    chunk2.append(ch)
+                    used2 += cw
+                first2 = "".join(chunk2)
+                lines.append(_box_line(f"{prefix}{first2}", width=w))
+                rest2 = summary[len(first2) :]
+                while rest2:
+                    row2: list[str] = []
+                    used2 = 0
+                    col_limit2 = max(w - 7, 1)
+                    for ch in rest2:
+                        cw = 2 if unicodedata.east_asian_width(ch) in ("W", "F") else 1
+                        if used2 + cw > col_limit2:
+                            break
+                        row2.append(ch)
+                        used2 += cw
+                    seg2 = "".join(row2)
+                    lines.append(_box_line(f"       {seg2}", width=w))
+                    rest2 = rest2[len(seg2) :]
+
+    lines.append(_box_line(width=w))
+    approve_bullet = "●" if selected == 0 else "○"
+    reject_bullet = "●" if selected == 1 else "○"
+    lines.append(_box_line(f"  {approve_bullet} 승인", width=w))
+    lines.append(_box_line(f"  {reject_bullet} 거절", width=w))
+    lines.append(bot)
+    return lines
+
+
+def show_approval_prompt(approval_request: dict) -> bool:
+    """Show an interactive approval / rejection prompt.
+
+    Returns True if approved, False if rejected.
+    """
+    terminal_columns = get_terminal_columns()
+    if not is_layout_supported(terminal_columns):
+        print(get_narrow_terminal_warning(terminal_columns))
+        return _fallback_prompt(approval_request, columns=terminal_columns)
+
+    if not _PT_AVAILABLE:
+        return _fallback_prompt(approval_request, columns=terminal_columns)
+
+    return _pt_prompt(approval_request, columns=terminal_columns)
+
+
+def _pt_prompt(approval_request: dict, *, columns: int) -> bool:
+    """prompt_toolkit–based arrow-key selection UI."""
+    state = {"selected": 0, "result": None}
+    box_width = get_approval_box_width(columns)
+
+    def get_text():
+        # Keep a stable width for a single prompt interaction.
+        lines = _build_box_lines(approval_request, state["selected"], box_width=box_width)
+        return "\n".join(lines) + "\n\n↑↓ 방향키로 선택, Enter로 확정"
+
+    kb = KeyBindings()
+
+    @kb.add("up")
+    @kb.add("k")
+    def _up(event):
+        state["selected"] = (state["selected"] - 1) % 2
+        _refresh_control()
+
+    @kb.add("down")
+    @kb.add("j")
+    def _down(event):
+        state["selected"] = (state["selected"] + 1) % 2
+        _refresh_control()
+
+    @kb.add("enter")
+    def _confirm(event):
+        state["result"] = state["selected"] == 0
+        event.app.exit()
+
+    @kb.add("q")
+    @kb.add("c-c")
+    def _cancel(event):
+        state["result"] = False
+        event.app.exit()
+
+    control = FormattedTextControl(text=get_text)
+    window = Window(content=control)
+    layout = Layout(HSplit([window]))
+
+    def _refresh_control():
+        control.text = get_text  # keep as callable
+        app.invalidate()
+
+    app: Application = Application(layout=layout, key_bindings=kb, full_screen=False)
+    app.run()
+
+    return bool(state["result"])
+
+
+def _fallback_prompt(approval_request: dict, columns: int | None = None) -> bool:
+    """Plain input() fallback when prompt_toolkit is unavailable."""
+    goal: str = approval_request.get("goal", "")
+    reason: str = approval_request.get("reason", "")
+    tool_summaries: list[str] = approval_request.get("tool_summaries") or []
+    terminal_columns = get_terminal_columns() if columns is None else columns
+    separator = "─" * max(terminal_columns - 2, 12)
+    title = " 작업 승인 요청 "
+    title_width = _display_width(title)
+    if terminal_columns > title_width:
+        fill_width = terminal_columns - title_width
+        left_fill = fill_width // 2
+        right_fill = fill_width - left_fill
+        title_line = f"{'─' * left_fill}{title}{'─' * right_fill}"
+    else:
+        title_line = title
+
+    print(f"\n{title_line}")
+    if goal:
+        print(f"  목표: {goal}")
+    if reason:
+        print(f"  이유: {reason}")
+    if tool_summaries:
+        print("\n  수행할 작업:")
+        for idx, s in enumerate(tool_summaries, 1):
+            print(f"    {idx}. {s}")
+    print(separator)
+
+    try:
+        answer = input("승인하시겠습니까? (y/n): ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        return False
+
+    return answer in ("y", "yes", "예", "네")

src/cli/commands.py

@@ -0,0 +1,49 @@
+"""Slash command parser and handler for GovOn CLI."""
+
+COMMANDS: dict[str, str] = {
+    "/help": "사용 가능한 명령과 도움말을 표시합니다.",
+    "/clear": "터미널 화면을 초기화합니다.",
+    "/exit": "셸을 종료합니다.",
+}
+
+_HELP_TEXT = """GovOn CLI 사용법
+────────────────────────────────────────
+  govon                       인터랙티브 REPL 모드
+  govon "질문"                단발 실행 모드
+  govon --session <id>        기존 세션 재개
+  govon --session <id> "질문" 기존 세션에서 단발 실행
+  govon --status              daemon 상태 확인
+  govon --stop                daemon 중지
+
+슬래시 명령
+────────────────────────────────────────"""
+
+for _cmd, _desc in COMMANDS.items():
+    _HELP_TEXT += f"\n  {_cmd:<10} {_desc}"
+
+_HELP_TEXT += "\n────────────────────────────────────────\n업무 요청은 자연어로 직접 입력하세요."
+
+
+def is_command(text: str) -> bool:
+    """Return True if text is a slash command."""
+    return text.strip().startswith("/")
+
+
+def handle_command(text: str) -> str | None:
+    """Execute a slash command and return a result string, or None.
+
+    Raises SystemExit for /exit.
+    """
+    cmd = text.strip().split()[0].lower()
+
+    if cmd == "/help":
+        return _HELP_TEXT
+
+    if cmd == "/clear":
+        print("\033[2J\033[H", end="", flush=True)
+        return None
+
+    if cmd == "/exit":
+        raise SystemExit(0)
+
+    return f"알 수 없는 명령입니다: {cmd}\n/help를 입력하세요."

src/cli/daemon.py

@@ -0,0 +1,222 @@
+"""GovOn daemon lifecycle 관리.
+
+Issue #144: CLI-daemon/LangGraph runtime 연동 및 session resume.
+
+uvicorn으로 백그라운드에서 GovOn API 서버를 기동하고,
+PID 파일로 프로세스 상태를 추적한다.
+
+.. note::
+   이 모듈은 **로컬 daemon 전용**입니다.
+   원격 서버에 연결할 때는 ``GOVON_RUNTIME_URL`` 환경변수를 설정하면
+   ``shell.py``의 ``main()``이 이 모듈을 완전히 건너뛰고 지정된 URL에
+   직접 연결합니다. Docker, 클라우드 배포, CI 환경에서는 해당 방식을
+   사용하는 것을 권장합니다.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+import httpx
+from loguru import logger
+
+
+class DaemonManager:
+    """GovOn API 서버 daemon lifecycle 관리자.
+
+    PID 파일과 /health 엔드포인트를 결합하여 daemon 상태를 확인하고,
+    필요 시 uvicorn으로 백그라운드 기동한다.
+
+    환경변수 ``GOVON_PORT``로 포트를 오버라이드할 수 있다 (기본: 8000).
+    """
+
+    GOVON_HOME = Path.home() / ".govon"
+    _HEALTH_CHECK_TIMEOUT = 120  # 최대 대기 초
+    _HEALTH_CHECK_INTERVAL = 1  # 재시도 간격 (초)
+
+    def __init__(self) -> None:
+        self.GOVON_HOME.mkdir(parents=True, exist_ok=True)
+        self.port: int = int(os.environ.get("GOVON_PORT", "8000"))
+        self.pid_path: Path = self.GOVON_HOME / "daemon.pid"
+        self.log_path: Path = self.GOVON_HOME / "daemon.log"
+
+    def get_base_url(self) -> str:
+        """daemon base URL을 반환한다."""
+        return f"http://127.0.0.1:{self.port}"
+
+    def is_running(self) -> bool:
+        """daemon이 실행 중인지 확인한다.
+
+        PID 파일이 존재하고 해당 프로세스가 살아 있으며,
+        /health 엔드포인트가 응답할 때 True를 반환한다.
+        """
+        pid = self._read_pid()
+        if pid is None:
+            return False
+
+        # PID 프로세스 생존 확인
+        if not self._pid_alive(pid):
+            logger.debug(f"[daemon] PID {pid} 프로세스가 없음. PID 파일 제거.")
+            self._remove_pid()
+            return False
+
+        # /health HTTP 확인
+        try:
+            with httpx.Client(timeout=5.0) as client:
+                resp = client.get(f"{self.get_base_url()}/health")
+                return resp.status_code == 200
+        except (httpx.ConnectError, httpx.TimeoutException, Exception):
+            return False
+
+    def start(self) -> bool:
+        """uvicorn을 백그라운드로 기동하고 PID를 기록한다.
+
+        Returns
+        -------
+        bool
+            기동 성공 여부 (health check 통과 시 True).
+        """
+        # 레이스 컨디션 방지: 기동 전 한 번 더 health check
+        if self.is_running():
+            logger.info("[daemon] 이미 실행 중입니다.")
+            return True
+
+        cmd = [
+            sys.executable,
+            "-m",
+            "uvicorn",
+            "src.inference.api_server:app",
+            "--host",
+            "127.0.0.1",
+            "--port",
+            str(self.port),
+        ]
+
+        logger.info(f"[daemon] 기동 명령: {' '.join(cmd)}")
+
+        with open(self.log_path, "a") as log_file:
+            proc = subprocess.Popen(
+                cmd,
+                stdout=log_file,
+                stderr=log_file,
+                start_new_session=True,
+            )
+
+        self._write_pid(proc.pid)
+        logger.info(f"[daemon] 프로세스 기동 완료. PID={proc.pid}")
+
+        # health check 대기
+        return self._wait_until_healthy()
+
+    def stop(self) -> None:
+        """daemon을 정상 종료한다 (SIGTERM → timeout 후 SIGKILL)."""
+        pid = self._read_pid()
+        if pid is None:
+            logger.info("[daemon] PID 파일이 없습니다. 실행 중이 아닌 것으로 간주합니다.")
+            return
+
+        if not self._pid_alive(pid):
+            logger.info(f"[daemon] PID {pid} 프로세스가 없습니다.")
+            self._remove_pid()
+            return
+
+        logger.info(f"[daemon] SIGTERM 전송: PID={pid}")
+        os.kill(pid, signal.SIGTERM)
+
+        # 최대 10초 대기
+        for _ in range(10):
+            time.sleep(1)
+            if not self._pid_alive(pid):
+                logger.info(f"[daemon] PID {pid} 정상 종료됨.")
+                self._remove_pid()
+                return
+
+        logger.warning(f"[daemon] SIGKILL 전송: PID={pid}")
+        try:
+            os.kill(pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        self._remove_pid()
+
+    def ensure_running(self) -> str:
+        """daemon이 실행 중임을 보장하고 base URL을 반환한다.
+
+        실행 중이 아니면 start()를 호출한다.
+
+        Returns
+        -------
+        str
+            daemon base URL (예: "http://127.0.0.1:8000").
+
+        Raises
+        ------
+        RuntimeError
+            daemon 기동에 실패한 경우.
+        """
+        if not self.is_running():
+            success = self.start()
+            if not success:
+                raise RuntimeError(
+                    "GovOn daemon 기동에 실패했습니다. " f"로그를 확인하세요: {self.log_path}"
+                )
+        return self.get_base_url()
+
+    # ------------------------------------------------------------------
+    # 내부 헬퍼
+    # ------------------------------------------------------------------
+
+    def _read_pid(self) -> Optional[int]:
+        """PID 파일에서 PID를 읽는다. 파일이 없으면 None."""
+        if not self.pid_path.exists():
+            return None
+        try:
+            first_line = self.pid_path.read_text().strip().splitlines()[0]
+            return int(first_line.split()[0])
+        except (ValueError, OSError, IndexError):
+            return None
+
+    def _write_pid(self, pid: int) -> None:
+        """PID와 기동 시각(epoch timestamp)을 파일에 기록한다."""
+        self.pid_path.write_text(f"{pid} {int(time.time())}")
+
+    def _remove_pid(self) -> None:
+        """PID 파일을 제거한다."""
+        try:
+            self.pid_path.unlink()
+        except FileNotFoundError:
+            pass
+
+    @staticmethod
+    def _pid_alive(pid: int) -> bool:
+        """프로세스가 살아 있는지 확인한다."""
+        try:
+            os.kill(pid, 0)
+            return True
+        except ProcessLookupError:
+            return False
+        except PermissionError:
+            # 프로세스가 존재하지만 권한이 없는 경우 → 살아 있음으로 간주
+            return True
+
+    def _wait_until_healthy(self) -> bool:
+        """health check가 통과할 때까지 최대 120초 대기한다."""
+        deadline = time.monotonic() + self._HEALTH_CHECK_TIMEOUT
+        while time.monotonic() < deadline:
+            try:
+                with httpx.Client(timeout=3.0) as client:
+                    resp = client.get(f"{self.get_base_url()}/health")
+                    if resp.status_code == 200:
+                        logger.info("[daemon] health check 통과.")
+                        return True
+            except (httpx.ConnectError, httpx.TimeoutException, Exception):
+                pass
+            time.sleep(self._HEALTH_CHECK_INTERVAL)
+
+        logger.error("[daemon] health check timeout (120초).")
+        return False

src/cli/http_client.py

@@ -0,0 +1,237 @@
+"""GovOn 로컬 daemon API HTTP 클라이언트.
+
+Issue #144: CLI-daemon/LangGraph runtime 연동 및 session resume.
+Issue #140: CLI 승인 UI 및 최소 명령 체계 (백엔드 부분).
+
+로컬 daemon(uvicorn)의 REST API를 래핑하는 클라이언트.
+run / approve / cancel 등 핵심 엔드포인트에 접근한다.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Generator, Iterator, Optional
+
+import httpx
+from loguru import logger
+
+
+class GovOnClient:
+    """GovOn 로컬 daemon HTTP 클라이언트.
+
+    Parameters
+    ----------
+    base_url : str
+        daemon base URL (예: "http://127.0.0.1:8000").
+    """
+
+    _RUN_TIMEOUT = 120.0
+    _DEFAULT_TIMEOUT = 30.0
+
+    def __init__(self, base_url: str) -> None:
+        self._base_url = base_url.rstrip("/")
+
+    # ------------------------------------------------------------------
+    # 공개 API
+    # ------------------------------------------------------------------
+
+    def health(self) -> Dict[str, Any]:
+        """GET /health — daemon 상태를 확인한다.
+
+        Returns
+        -------
+        dict
+            서버가 반환하는 health 응답.
+
+        Raises
+        ------
+        ConnectionError
+            daemon에 연결할 수 없을 때.
+        """
+        return self._get("/health", timeout=self._DEFAULT_TIMEOUT)
+
+    def run(
+        self,
+        query: str,
+        session_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """POST /v2/agent/run — 에이전트 실행 요청.
+
+        Parameters
+        ----------
+        query : str
+            사용자 입력 쿼리.
+        session_id : str | None
+            기존 세션을 이어받을 경우 session ID.
+
+        Returns
+        -------
+        dict
+            서버 응답 (thread_id, status 등 포함).
+        """
+        body: Dict[str, Any] = {"query": query}
+        if session_id is not None:
+            body["session_id"] = session_id
+
+        logger.debug(f"[http_client] run: session_id={session_id} query_len={len(query)}")
+        return self._post("/v2/agent/run", body=body, timeout=self._RUN_TIMEOUT)
+
+    def approve(self, thread_id: str, approved: bool) -> Dict[str, Any]:
+        """POST /v2/agent/approve — 승인 또는 거절.
+
+        Parameters
+        ----------
+        thread_id : str
+            승인/거절할 graph thread ID.
+        approved : bool
+            True이면 승인, False이면 거절.
+
+        Returns
+        -------
+        dict
+            서버 응답.
+        """
+        logger.debug(f"[http_client] approve: thread_id={thread_id} approved={approved}")
+        return self._post_params(
+            "/v2/agent/approve",
+            params={"thread_id": thread_id, "approved": str(approved).lower()},
+            timeout=self._DEFAULT_TIMEOUT,
+        )
+
+    def stream(
+        self,
+        query: str,
+        session_id: Optional[str] = None,
+    ) -> Generator[Dict[str, Any], None, None]:
+        """POST /v2/agent/stream — SSE 스트리밍으로 노드별 이벤트를 수신한다.
+
+        Parameters
+        ----------
+        query : str
+            사용자 입력 쿼리.
+        session_id : str | None
+            기존 세션을 이어받을 경우 session ID.
+
+        Yields
+        ------
+        dict
+            파싱된 SSE 이벤트 dict. 최소 ``node``와 ``status`` 키를 포함한다.
+
+        Raises
+        ------
+        ConnectionError
+            daemon에 연결할 수 없을 때.
+        httpx.HTTPStatusError
+            HTTP 오류 응답 시.
+        """
+        body: Dict[str, Any] = {"query": query}
+        if session_id is not None:
+            body["session_id"] = session_id
+
+        url = f"{self._base_url}/v2/agent/stream"
+        logger.debug(f"[http_client] stream: session_id={session_id} query_len={len(query)}")
+
+        try:
+            timeout = httpx.Timeout(connect=10.0, read=300.0, write=10.0, pool=10.0)
+            with httpx.Client(timeout=timeout) as client:
+                with client.stream("POST", url, json=body) as resp:
+                    resp.raise_for_status()
+                    for line in resp.iter_lines():
+                        line = line.strip()
+                        if not line:
+                            continue
+                        if line.startswith("data:"):
+                            data_str = line[len("data:") :].strip()
+                            if not data_str:
+                                continue
+                            try:
+                                event = json.loads(data_str)
+                                yield event
+                            except json.JSONDecodeError:
+                                logger.warning(f"[http_client] SSE JSON 파싱 실패: {data_str!r}")
+                                continue
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"daemon이 실행 중이 아닙니다. ({self._base_url})") from exc
+        except httpx.HTTPStatusError as exc:
+            logger.error(f"[http_client] HTTP {exc.response.status_code}: {url}")
+            raise
+
+    def cancel(self, thread_id: str) -> Dict[str, Any]:
+        """POST /v2/agent/cancel — 실행 중인 세션 취소.
+
+        Parameters
+        ----------
+        thread_id : str
+            취소할 graph thread ID.
+
+        Returns
+        -------
+        dict
+            서버 응답.
+        """
+        logger.debug(f"[http_client] cancel: thread_id={thread_id}")
+        return self._post_params(
+            "/v2/agent/cancel",
+            params={"thread_id": thread_id},
+            timeout=self._DEFAULT_TIMEOUT,
+        )
+
+    # ------------------------------------------------------------------
+    # 내부 헬퍼
+    # ------------------------------------------------------------------
+
+    def _get(self, path: str, *, timeout: float) -> Dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        try:
+            with httpx.Client(timeout=timeout) as client:
+                resp = client.get(url)
+                resp.raise_for_status()
+                return resp.json()
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"daemon이 실행 중이 아닙니다. ({self._base_url})") from exc
+        except httpx.HTTPStatusError as exc:
+            logger.error(f"[http_client] HTTP {exc.response.status_code}: {url}")
+            raise
+
+    def _post(
+        self,
+        path: str,
+        *,
+        body: Dict[str, Any],
+        timeout: float,
+    ) -> Dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        try:
+            with httpx.Client(timeout=timeout) as client:
+                resp = client.post(url, json=body)
+                resp.raise_for_status()
+                return resp.json()
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"daemon이 실행 중이 아닙니다. ({self._base_url})") from exc
+        except httpx.HTTPStatusError as exc:
+            logger.error(f"[http_client] HTTP {exc.response.status_code}: {url}")
+            raise
+
+    def _post_params(
+        self,
+        path: str,
+        *,
+        params: Dict[str, Any],
+        timeout: float,
+    ) -> Dict[str, Any]:
+        """쿼리 파라미터를 사용하는 POST 요청 헬퍼.
+
+        `/v2/agent/approve`, `/v2/agent/cancel` 등 FastAPI 엔드포인트가
+        쿼리 파라미터를 기대할 때 사용한다.
+        """
+        url = f"{self._base_url}{path}"
+        try:
+            with httpx.Client(timeout=timeout) as client:
+                resp = client.post(url, params=params)
+                resp.raise_for_status()
+                return resp.json()
+        except httpx.ConnectError as exc:
+            raise ConnectionError(f"daemon이 실행 중이 아닙니다. ({self._base_url})") from exc
+        except httpx.HTTPStatusError as exc:
+            logger.error(f"[http_client] HTTP {exc.response.status_code}: {url}")
+            raise

src/cli/renderer.py

@@ -0,0 +1,257 @@
+"""Result rendering for GovOn CLI.
+
+Uses `rich` when available; falls back to plain print() otherwise.
+"""
+
+from __future__ import annotations
+
+from threading import Lock
+
+from src.cli.terminal import (
+    get_narrow_terminal_warning,
+    get_panel_width,
+    get_terminal_columns,
+    is_layout_supported,
+)
+
+try:
+    from rich.console import Console
+    from rich.panel import Panel
+    from rich.status import Status
+    from rich.text import Text
+
+    _console = Console()
+    _RICH_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    _console = None  # type: ignore[assignment]
+    _RICH_AVAILABLE = False
+
+_HAS_WARNED_NARROW_TERMINAL = False
+_NARROW_WARNING_LOCK = Lock()
+
+# ---------------------------------------------------------------------------
+# Node status message mapping
+# ---------------------------------------------------------------------------
+
+NODE_STATUS_MESSAGES: dict[str, str] = {
+    "session_load": "세션 로드 중…",
+    "planner": "계획 수립 중…",
+    "approval_wait": "승인 대기 중…",
+    "tool_execute": "도구 실행 중…",
+    "synthesis": "답변 생성 중…",
+    "persist": "저장 중…",
+}
+
+
+def get_node_message(node_name: str) -> str:
+    """Return a human-readable status message for a given node name."""
+    return NODE_STATUS_MESSAGES.get(node_name, f"{node_name} 처리 중…")
+
+
+# ---------------------------------------------------------------------------
+# Spinner context manager
+# ---------------------------------------------------------------------------
+
+
+class StreamingStatusDisplay:
+    """Context manager that shows a spinner and updates the message per node.
+
+    Wraps rich.status.Status when rich is available; falls back to plain print().
+    """
+
+    def __init__(self, initial_message: str = "처리 중…") -> None:
+        self._initial_message = initial_message
+        self._status: Status | None = None  # type: ignore[name-defined]
+        self._use_rich = False
+
+    def __enter__(self) -> "StreamingStatusDisplay":
+        self._use_rich, _ = _resolve_render_mode()
+        if self._use_rich:
+            self._status = _console.status(self._initial_message, spinner="dots")
+            self._status.__enter__()
+        else:
+            print(f"→ {self._initial_message}", flush=True)
+        return self
+
+    def update(self, message: str) -> None:
+        """Update the displayed status message."""
+        if self._use_rich and self._status is not None:
+            self._status.update(message)
+        else:
+            print(f"→ {message}", flush=True)
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        if self._use_rich and self._status is not None:
+            self._status.__exit__(exc_type, exc_val, exc_tb)
+            self._status = None
+
+
+def _warn_narrow_terminal_once(columns: int) -> None:
+    """Emit the narrow-terminal fallback warning once per narrow-state entry."""
+    global _HAS_WARNED_NARROW_TERMINAL
+
+    with _NARROW_WARNING_LOCK:
+        if _HAS_WARNED_NARROW_TERMINAL:
+            return
+        _HAS_WARNED_NARROW_TERMINAL = True
+
+    print(get_narrow_terminal_warning(columns), flush=True)
+
+
+def _reset_narrow_warning() -> None:
+    """Reset narrow-terminal warning state for tests and wide-terminal recovery."""
+    global _HAS_WARNED_NARROW_TERMINAL
+
+    with _NARROW_WARNING_LOCK:
+        _HAS_WARNED_NARROW_TERMINAL = False
+
+
+def _resolve_render_mode() -> tuple[bool, int]:
+    """Return (use_rich, terminal_columns) for the current render call."""
+    columns = get_terminal_columns()
+    if not is_layout_supported(columns):
+        _warn_narrow_terminal_once(columns)
+        return False, columns
+    _reset_narrow_warning()
+    return _RICH_AVAILABLE, columns
+
+
+def _plain_rule(columns: int) -> str:
+    """Return a separator that fits within the current terminal."""
+    return "─" * max(columns - 2, 12)
+
+
+def render_evidence_section(evidence_items: list) -> str:
+    """EvidenceItem dict 리스트를 출처 섹션 텍스트로 변환한다.
+
+    source_type별로 그룹화하여 표시한다:
+      [로컬 문서] — rag 출처 (file_path, page, score 포함)
+      [외부 API]  — api 출처 (URL 포함)
+      [LLM 생성]  — llm_generated 출처
+
+    Parameters
+    ----------
+    evidence_items : list
+        EvidenceItem.to_dict() 형태의 dict 리스트.
+
+    Returns
+    -------
+    str
+        출처 섹션 텍스트. items가 없으면 빈 문자열.
+    """
+    if not evidence_items:
+        return ""
+
+    # source_type별 그룹화
+    rag_items = [i for i in evidence_items if i.get("source_type") == "rag"]
+    api_items = [i for i in evidence_items if i.get("source_type") == "api"]
+    llm_items = [i for i in evidence_items if i.get("source_type") == "llm_generated"]
+
+    lines: list[str] = ["── 참조 근거 ──"]
+    idx = 1
+
+    if rag_items:
+        lines.append("[로컬 문서]")
+        for item in rag_items:
+            title = item.get("title") or item.get("link_or_path", "")
+            page = item.get("page")
+            score = item.get("score", 0.0)
+            page_str = f" (p.{page})" if page is not None else ""
+            score_str = f" [{score:.2f}]" if score else ""
+            lines.append(f"  {idx}. {title}{page_str}{score_str}")
+            idx += 1
+
+    if api_items:
+        lines.append("[외부 API]")
+        for item in api_items:
+            title = item.get("title", "")
+            link = item.get("link_or_path", "")
+            link_str = f" — {link}" if link else ""
+            lines.append(f"  {idx}. {title}{link_str}")
+            idx += 1
+
+    if llm_items:
+        lines.append("[LLM 생성]")
+        for item in llm_items:
+            title = item.get("title", "")
+            excerpt = item.get("excerpt", "")[:80]
+            lines.append(f"  {idx}. {title}: {excerpt}" if title else f"  {idx}. {excerpt}")
+            idx += 1
+
+    return "\n".join(lines) if len(lines) > 1 else ""
+
+
+def render_result(result: dict) -> None:
+    """Render the final agent response to the terminal.
+
+    Expected keys (at least one required):
+      - result["text"] or result["response"]: main answer text
+      - result["evidence_items"]: EvidenceItem dict 리스트 (structured, 우선)
+      - result["citations"] or result["sources"]: list of source strings (fallback)
+    """
+    text_body: str = result.get("text") or result.get("response") or ""
+    evidence_items: list = result.get("evidence_items") or []
+    citations: list = result.get("citations") or result.get("sources") or []
+
+    use_rich, columns = _resolve_render_mode()
+
+    if use_rich:
+        content = Text(text_body)
+        if evidence_items:
+            evidence_text = render_evidence_section(evidence_items)
+            if evidence_text:
+                content.append(f"\n\n{evidence_text}\n", style="dim")
+        elif citations:
+            content.append("\n\n출처\n", style="bold")
+            for idx, src in enumerate(citations, 1):
+                content.append(f"  {idx}. {src}\n", style="dim")
+        _console.print(
+            Panel(
+                content,
+                title="[bold green]GovOn[/bold green]",
+                border_style="green",
+                width=get_panel_width(columns),
+            )
+        )
+    else:
+        rule = _plain_rule(columns)
+        print(f"\n{rule}")
+        print("GovOn")
+        print(text_body)
+        if evidence_items:
+            evidence_text = render_evidence_section(evidence_items)
+            if evidence_text:
+                print(f"\n{evidence_text}")
+        elif citations:
+            print("\n출처")
+            for idx, src in enumerate(citations, 1):
+                print(f"  {idx}. {src}")
+        print(f"{rule}\n")
+
+
+def render_status(message: str) -> None:
+    """Render a transient status / progress message."""
+    use_rich, _ = _resolve_render_mode()
+    if use_rich:
+        _console.print(f"[dim]→ {message}[/dim]")
+    else:
+        print(f"→ {message}")
+
+
+def render_error(message: str) -> None:
+    """Render an error message in red."""
+    use_rich, _ = _resolve_render_mode()
+    if use_rich:
+        _console.print(f"[bold red]오류:[/bold red] {message}")
+    else:
+        print(f"오류: {message}")
+
+
+def render_session_info(session_id: str) -> None:
+    """Render session resume hint at shell exit."""
+    hint = f"[session: {session_id}]  govon --session {session_id} 로 재개 가능"
+    use_rich, _ = _resolve_render_mode()
+    if use_rich:
+        _console.print(f"[dim]{hint}[/dim]")
+    else:
+        print(hint)

src/cli/shell.py

@@ -0,0 +1,420 @@
+"""GovOn CLI — main REPL loop and entry point.
+
+Entry point registered in pyproject.toml:
+  [project.scripts]
+  govon = "src.cli.shell:main"
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+import httpx
+
+# ---------------------------------------------------------------------------
+# Optional dependencies — graceful degradation
+# ---------------------------------------------------------------------------
+_PT_AVAILABLE = False
+try:
+    from prompt_toolkit import PromptSession
+    from prompt_toolkit.history import InMemoryHistory
+
+    _PT_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    pass
+
+# ---------------------------------------------------------------------------
+# Internal modules
+# ---------------------------------------------------------------------------
+from src.cli.approval_ui import show_approval_prompt
+from src.cli.commands import handle_command, is_command
+from src.cli.renderer import (
+    StreamingStatusDisplay,
+    get_node_message,
+    render_error,
+    render_result,
+    render_session_info,
+    render_status,
+)
+
+# ---------------------------------------------------------------------------
+# Stub imports for daemon / http_client (other agents implement these).
+# If the real modules exist they are used; otherwise lightweight stubs
+# are defined inline so the shell can be imported and tested standalone.
+# ---------------------------------------------------------------------------
+try:
+    from src.cli.daemon import DaemonManager  # type: ignore[import]
+except ImportError:  # pragma: no cover
+
+    class DaemonManager:  # type: ignore[no-redef]
+        """Stub: real implementation provided by daemon.py agent."""
+
+        def ensure_running(self) -> str:
+            raise RuntimeError("DaemonManager not available. Install the full GovOn package.")
+
+        def is_running(self) -> bool:
+            return False
+
+        def stop(self) -> None:
+            pass
+
+
+try:
+    from src.cli.http_client import GovOnClient  # type: ignore[import]
+except ImportError:  # pragma: no cover
+
+    class GovOnClient:  # type: ignore[no-redef]
+        """Stub: real implementation provided by http_client.py agent."""
+
+        def __init__(self, base_url: str) -> None:
+            self._base_url = base_url
+
+        def run(self, query: str, session_id: str | None = None) -> dict:
+            raise RuntimeError("GovOnClient not available. Install the full GovOn package.")
+
+        def stream(self, query: str, session_id: str | None = None):
+            raise RuntimeError("GovOnClient not available. Install the full GovOn package.")
+            yield  # make it a generator
+
+        def approve(self, thread_id: str, approved: bool) -> dict:
+            raise RuntimeError("GovOnClient not available. Install the full GovOn package.")
+
+        def cancel(self, thread_id: str) -> dict:
+            raise RuntimeError("GovOnClient not available. Install the full GovOn package.")
+
+        def health(self) -> dict:
+            raise RuntimeError("GovOnClient not available. Install the full GovOn package.")
+
+
+# ---------------------------------------------------------------------------
+# Core helpers
+# ---------------------------------------------------------------------------
+
+_PROMPT_TEXT = "govon> "
+
+
+def _get_input(session: "PromptSession | None") -> str:  # type: ignore[name-defined]
+    """Read one line of user input (prompt_toolkit or plain input())."""
+    if _PT_AVAILABLE and session is not None:
+        return session.prompt(_PROMPT_TEXT)
+    return input(_PROMPT_TEXT)
+
+
+def _process_query(
+    client: "GovOnClient",
+    query: str,
+    session_id: str | None,
+) -> tuple[str | None, bool]:
+    """Send *query* to the backend and handle approval flow.
+
+    Attempts to use the streaming endpoint (/v2/agent/stream) for per-node
+    progress display. Falls back to the blocking run() call when the streaming
+    endpoint is unavailable.
+
+    Returns (new_session_id, should_continue).
+    `should_continue` is False only when an unrecoverable error is returned
+    that suggests the daemon is down.
+    """
+    # --- Try streaming path first ---
+    try:
+        return _process_query_streaming(client, query, session_id)
+    except (AttributeError, NotImplementedError):
+        # client.stream() is not available (stub or older server)
+        pass
+    except (ConnectionError, httpx.HTTPStatusError, httpx.StreamError, OSError):
+        # Streaming endpoint unavailable — fall back silently
+        pass
+
+    # --- Fallback: blocking run() with simple spinner ---
+    return _process_query_blocking(client, query, session_id)
+
+
+def _process_query_streaming(
+    client: "GovOnClient",
+    query: str,
+    session_id: str | None,
+) -> tuple[str | None, bool]:
+    """Streaming path: calls client.stream() and shows per-node progress."""
+    final_response: dict = {}
+    approval_event: dict | None = None
+    new_session_id: str | None = None
+
+    with StreamingStatusDisplay("처리 중…") as status_display:
+        for event in client.stream(query, session_id):
+            node: str = event.get("node", "")
+            event_status: str = event.get("status", "")
+
+            if node == "error" or event_status == "error":
+                render_error(event.get("error", "알 수 없는 오류가 발생했습니다."))
+                return session_id, True
+
+            if event_status == "awaiting_approval":
+                approval_event = event
+                break
+
+            # Update spinner with node-specific message
+            if node:
+                msg = get_node_message(node)
+                status_display.update(msg)
+
+            # Collect session/thread id from any event
+            if not new_session_id:
+                new_session_id = event.get("session_id") or event.get("thread_id")
+
+            # Collect final result if present
+            if event_status == "completed" or event.get("final_text") or event.get("text"):
+                final_response = event
+
+    # Handle approval
+    if approval_event is not None:
+        if not new_session_id:
+            new_session_id = approval_event.get("session_id") or approval_event.get("thread_id")
+        approval_request: dict = approval_event.get("approval_request") or {}
+        approved = show_approval_prompt(approval_request)
+        thread_id: str = approval_event.get("thread_id") or ""
+
+        if not approved:
+            try:
+                client.approve(thread_id, approved=False)
+            except Exception:  # pragma: no cover
+                pass
+            return new_session_id or session_id, True
+
+        render_status("승인됨 — 계속 진행 중…")
+        try:
+            approved_response = client.approve(thread_id, approved=True)
+        except Exception as exc:  # pragma: no cover
+            render_error(f"승인 요청 실패: {exc}")
+            return new_session_id or session_id, True
+
+        render_result(approved_response)
+        return (
+            approved_response.get("session_id")
+            or approved_response.get("thread_id")
+            or new_session_id
+            or session_id,
+            True,
+        )
+
+    # Handle completed result from streaming events
+    if final_response:
+        _sid = final_response.get("session_id") or final_response.get("thread_id") or new_session_id
+        render_result(final_response)
+        return _sid or session_id, True
+
+    # No useful response received
+    render_result({"text": ""})
+    return new_session_id or session_id, True
+
+
+def _process_query_blocking(
+    client: "GovOnClient",
+    query: str,
+    session_id: str | None,
+) -> tuple[str | None, bool]:
+    """Blocking fallback path: calls client.run() with a simple spinner."""
+    render_status("처리 중…")
+
+    try:
+        response = client.run(query, session_id)
+    except Exception as exc:  # pragma: no cover
+        render_error(f"요청 실패: {exc}")
+        return session_id, True
+
+    new_session_id: str | None = response.get("session_id") or response.get("thread_id")
+    status: str = response.get("status", "")
+
+    if status == "awaiting_approval":
+        approval_request: dict = response.get("approval_request") or {}
+        approved = show_approval_prompt(approval_request)
+
+        if not approved:
+            # 거절: 서버에 통보 후 프롬프트 복귀
+            _thread_id: str = response.get("thread_id") or ""
+            try:
+                client.approve(_thread_id, approved=False)
+            except Exception:  # pragma: no cover
+                pass
+            return new_session_id or session_id, True
+
+        thread_id: str = response.get("thread_id") or ""
+        render_status("승인됨 — 계속 진행 중…")
+        try:
+            approved_response = client.approve(thread_id, approved=True)
+        except Exception as exc:  # pragma: no cover
+            render_error(f"승인 요청 실패: {exc}")
+            return new_session_id or session_id, True
+
+        render_result(approved_response)
+        return (
+            approved_response.get("session_id")
+            or approved_response.get("thread_id")
+            or new_session_id
+            or session_id,
+            True,
+        )
+
+    if status in ("completed", "done", "success") or "text" in response or "response" in response:
+        render_result(response)
+        return new_session_id or session_id, True
+
+    # Unknown status — render raw
+    render_result({"text": str(response)})
+    return new_session_id or session_id, True
+
+
+# ---------------------------------------------------------------------------
+# REPL loop
+# ---------------------------------------------------------------------------
+
+
+def _run_repl(client: "GovOnClient", initial_session_id: str | None = None) -> None:
+    """Run the interactive REPL until EOF or /exit."""
+    session_id: str | None = initial_session_id
+    pt_session = PromptSession(history=InMemoryHistory()) if _PT_AVAILABLE else None
+
+    while True:
+        try:
+            text = _get_input(pt_session).strip()
+        except EOFError:
+            # Ctrl+D
+            break
+        except KeyboardInterrupt:
+            # Ctrl+C while idle → exit
+            print()
+            break
+
+        if not text:
+            continue
+
+        if is_command(text):
+            try:
+                result = handle_command(text)
+            except SystemExit:
+                break
+            if result is not None:
+                print(result)
+            continue
+
+        # Normal query
+        try:
+            session_id, should_continue = _process_query(client, text, session_id)
+        except KeyboardInterrupt:
+            # Ctrl+C while processing → cancel and return to prompt
+            print("\n요청이 취소되었습니다.")
+            continue
+
+        if not should_continue:  # pragma: no cover
+            break
+
+    if session_id:
+        render_session_info(session_id)
+
+
+# ---------------------------------------------------------------------------
+# Single-shot mode
+# ---------------------------------------------------------------------------
+
+
+def _run_once(client: "GovOnClient", query: str, session_id: str | None) -> None:
+    """Run a single query and exit."""
+    new_session_id, _ = _process_query(client, query, session_id)
+    if new_session_id:
+        render_session_info(new_session_id)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    """CLI entry point for the `govon` command."""
+    parser = argparse.ArgumentParser(
+        prog="govon",
+        description="GovOn — shell-first local agentic runtime",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    parser.add_argument(
+        "query",
+        nargs="?",
+        default=None,
+        help="단발 실행할 질문 (생략 시 인터랙티브 REPL 모드)",
+    )
+    parser.add_argument(
+        "--session",
+        metavar="SESSION_ID",
+        default=None,
+        help="재개할 기존 세션 ID",
+    )
+    parser.add_argument(
+        "--status",
+        action="store_true",
+        help="daemon 상태 확인 후 종료",
+    )
+    parser.add_argument(
+        "--stop",
+        action="store_true",
+        help="daemon 중지 후 종료",
+    )
+
+    args = parser.parse_args()
+
+    # GOVON_RUNTIME_URL이 설정된 경우 원격 서버에 직접 연결하고 daemon을 관리하지 않는다.
+    runtime_url = os.environ.get("GOVON_RUNTIME_URL")
+
+    if runtime_url:
+        if not runtime_url.startswith(("http://", "https://")):
+            print(
+                f"오류: GOVON_RUNTIME_URL은 http:// 또는 https://로 시작해야 합니다: {runtime_url}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        # 원격 런타임 모드: daemon 관리 없이 지정된 URL에 직접 연결
+        if args.status:
+            print(f"GovOn daemon: 원격 모드 (GOVON_RUNTIME_URL={runtime_url})")
+            sys.exit(0)
+        if args.stop:
+            print("오류: 원격 런타임 모드에서는 --stop을 사용할 수 없습니다.", file=sys.stderr)
+            sys.exit(1)
+        base_url = runtime_url.rstrip("/")
+    else:
+        # 로컬 daemon 모드
+        daemon = DaemonManager()
+
+        # --status
+        if args.status:
+            if daemon.is_running():
+                print("GovOn daemon: 실행 중")
+            else:
+                print("GovOn daemon: 중지됨")
+            sys.exit(0)
+
+        # --stop
+        if args.stop:
+            daemon.stop()
+            print("GovOn daemon이 중지되었습니다.")
+            sys.exit(0)
+
+        # Ensure daemon is up and get base URL
+        try:
+            base_url = daemon.ensure_running()
+        except Exception as exc:
+            print(f"오류: daemon을 시작할 수 없습니다 — {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    client = GovOnClient(base_url)
+
+    if args.query:
+        # Single-shot mode
+        _run_once(client, args.query, args.session)
+    else:
+        # Interactive REPL mode
+        print("GovOn CLI  (종료: Ctrl+D 또는 /exit)")
+        _run_repl(client, initial_session_id=args.session)
+
+
+if __name__ == "__main__":
+    main()

src/cli/terminal.py

@@ -0,0 +1,56 @@
+"""Terminal layout helpers for the GovOn CLI."""
+
+from __future__ import annotations
+
+import shutil
+
+DEFAULT_TERMINAL_COLUMNS = 80
+MIN_TERMINAL_COLUMNS = 40
+MIN_CONTENT_WIDTH = 20
+APPROVAL_BOX_MAX_WIDTH = 55
+APPROVAL_BOX_MARGIN = 4
+PANEL_MARGIN = 2
+
+assert MIN_CONTENT_WIDTH < MIN_TERMINAL_COLUMNS
+
+
+def get_terminal_columns(default: int = DEFAULT_TERMINAL_COLUMNS) -> int:
+    """Return the current terminal width in columns."""
+    return max(shutil.get_terminal_size(fallback=(default, 24)).columns, 1)
+
+
+def _cols(columns: int | None) -> int:
+    """Resolve an explicit column override or read the current terminal width."""
+    return get_terminal_columns() if columns is None else columns
+
+
+def is_layout_supported(columns: int | None = None) -> bool:
+    """Return True when the terminal is wide enough for full rich layouts."""
+    return _cols(columns) >= MIN_TERMINAL_COLUMNS
+
+
+def get_approval_box_width(columns: int | None = None) -> int:
+    """Return the inner width for the approval box.
+
+    Callers should gate rich box rendering with `is_layout_supported()` first.
+    For very narrow terminals, plain fallback is the supported rendering path.
+    """
+    current_columns = _cols(columns)
+    return max(
+        MIN_CONTENT_WIDTH,
+        min(APPROVAL_BOX_MAX_WIDTH, current_columns - APPROVAL_BOX_MARGIN),
+    )
+
+
+def get_panel_width(columns: int | None = None) -> int:
+    """Return the rich panel width for result rendering."""
+    return max(MIN_CONTENT_WIDTH, _cols(columns) - PANEL_MARGIN)
+
+
+def get_narrow_terminal_warning(columns: int | None = None) -> str:
+    """Return the warning shown when the terminal is too narrow."""
+    current_columns = _cols(columns)
+    return (
+        f"터미널 너비가 {current_columns}열로 좁아 plain mode로 전환합니다. "
+        f"최소 {MIN_TERMINAL_COLUMNS}열 이상에서 전체 레이아웃이 보장됩니다."
+    )

src/data_collection_preprocessing/__init__.py

@@ -0,0 +1,13 @@
+"""민원답변 어댑터용 학습 데이터 수집 및 전처리 패키지."""
+
+from .config import DataConfig
+from .parsers import AdminLawParser, GovQAParser, GukripParser
+from .pipeline import CivilResponseDataPipeline
+
+__all__ = [
+    "DataConfig",
+    "GukripParser",
+    "GovQAParser",
+    "AdminLawParser",
+    "CivilResponseDataPipeline",
+]

src/data_collection_preprocessing/__main__.py

@@ -0,0 +1,5 @@
+"""python -m src.data_collection_preprocessing 진입점."""
+
+from .cli import main
+
+main()

src/data_collection_preprocessing/cli.py

@@ -0,0 +1,76 @@
+"""CLI entry point: python -m src.data_collection_preprocessing"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from .config import DataConfig
+from .pipeline import CivilResponseDataPipeline
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="민원답변 어댑터 학습 데이터 파이프라인")
+    parser.add_argument(
+        "--raw-dir",
+        default="data/raw/aihub",
+        help="AI Hub 원시 데이터 루트 디렉터리 (기본: data/raw/aihub)",
+    )
+    parser.add_argument(
+        "--output-dir",
+        default="data/processed",
+        help="출력 디렉터리 (기본: data/processed)",
+    )
+    parser.add_argument(
+        "--min-answer-length",
+        type=int,
+        default=30,
+        help="최소 답변 길이 (기본: 30자)",
+    )
+    parser.add_argument(
+        "--max-answer-length",
+        type=int,
+        default=4096,
+        help="최대 답변 길이 (기본: 4096자)",
+    )
+    parser.add_argument(
+        "--train-ratio",
+        type=float,
+        default=0.9,
+        help="train 비율 (기본: 0.9)",
+    )
+    parser.add_argument(
+        "--log-level",
+        default="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+    )
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        level=getattr(logging, args.log_level),
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        stream=sys.stdout,
+    )
+
+    config = DataConfig(
+        raw_dir=Path(args.raw_dir),
+        output_dir=Path(args.output_dir),
+        min_answer_length=args.min_answer_length,
+        max_answer_length=args.max_answer_length,
+        train_ratio=args.train_ratio,
+    )
+
+    pipeline = CivilResponseDataPipeline(config)
+    stats = pipeline.run()
+
+    print("\n파이프라인 완료")
+    print(f"  총 레코드: {stats['total']:,}")
+    print(f"  train:    {stats['train']:,}")
+    print(f"  val:      {stats['val']:,}")
+    print(f"  출력 경로: {args.output_dir}/")
+
+
+if __name__ == "__main__":
+    main()

src/data_collection_preprocessing/config.py

@@ -0,0 +1,14 @@
+"""데이터 파이프라인 설정."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class DataConfig:
+    raw_dir: Path = Path("data/raw/aihub")
+    output_dir: Path = Path("data/processed")
+    min_answer_length: int = 30
+    max_answer_length: int = 4096
+    min_question_length: int = 5
+    train_ratio: float = 0.9

src/data_collection_preprocessing/parsers.py

@@ -0,0 +1,235 @@
+"""AI Hub 데이터셋 파서 모듈.
+
+각 파서는 단일 JSON 파일을 파싱하여 학습 레코드 목록을 반환한다.
+반환 형식:
+    {
+        "question": str,
+        "answer": str,
+        "source": str,
+        "category": str,
+        "metadata": dict,
+    }
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+
+def _load_json(filepath: Path) -> Any:
+    with open(filepath, encoding="utf-8") as f:
+        return json.load(f)
+
+
+class GukripParser:
+    """71852 국립아시아문화전당 파서.
+
+    consulting_content의 '상담원:' 발화를 추출하여 답변으로 사용하고,
+    instructions[0].data[0].instruction을 질문으로 사용한다.
+    """
+
+    def parse(self, filepath: Path) -> list[dict]:
+        data = _load_json(filepath)
+        if isinstance(data, list):
+            records = []
+            for item in data:
+                records.extend(self._parse_item(item))
+            return records
+        return self._parse_item(data)
+
+    def _parse_item(self, item: dict) -> list[dict]:
+        content: str = item.get("consulting_content", "")
+        source_id: str = item.get("source_id", "")
+        consulting_date: str = item.get("consulting_date", "")
+        category: str = item.get("consulting_category", "")
+
+        # 상담원 발화 추출
+        agent_turns = []
+        for line in content.split("\n"):
+            line = line.strip()
+            if line.startswith("상담원:"):
+                turn_text = line[len("상담원:") :].strip()
+                if turn_text:
+                    agent_turns.append(turn_text)
+
+        if not agent_turns:
+            return []
+
+        answer = " ".join(agent_turns)
+
+        # instruction에서 질문 추출
+        instructions = item.get("instructions", [])
+        if not instructions:
+            return []
+
+        data_list = instructions[0].get("data", [])
+        if not data_list:
+            return []
+
+        question = data_list[0].get("instruction", "").strip()
+        if not question:
+            return []
+
+        return [
+            {
+                "question": question,
+                "answer": answer,
+                "source": "71852_국립아시아문화전당",
+                "category": category,
+                "metadata": {
+                    "source_id": source_id,
+                    "consulting_date": consulting_date,
+                },
+            }
+        ]
+
+
+class GovQAParser:
+    """71852 중앙/지방행정기관 파서.
+
+    consulting_content에서 Q/A 형식을 파싱하여 공식 정부 답변을 추출한다.
+    보조 질문(instructions.data[*].instruction)은 별도 레코드로 생성한다.
+    """
+
+    # A 구분자 패턴: "\nA :" 또는 "\nA:"
+    _A_SEP = re.compile(r"\nA\s*:")
+
+    def parse(self, filepath: Path) -> list[dict]:
+        data = _load_json(filepath)
+        if isinstance(data, list):
+            records = []
+            for item in data:
+                records.extend(self._parse_item(item))
+            return records
+        return self._parse_item(data)
+
+    def _parse_item(self, item: dict) -> list[dict]:
+        content: str = item.get("consulting_content", "")
+        source_str: str = item.get("source", "")
+        source_id: str = item.get("source_id", "")
+        consulting_date: str = item.get("consulting_date", "")
+        category: str = item.get("consulting_category", "")
+
+        # A 부분 분리
+        parts = self._A_SEP.split(content, maxsplit=1)
+        if len(parts) < 2:
+            return []
+
+        q_part, a_part = parts[0], parts[1].strip()
+        if not a_part:
+            return []
+
+        # Q 부분에서 질문 추출
+        question = self._extract_question(q_part)
+        if not question:
+            return []
+
+        records = [
+            {
+                "question": question,
+                "answer": a_part,
+                "source": "71852_중앙행정기관",
+                "category": category,
+                "metadata": {
+                    "source_id": source_id,
+                    "consulting_date": consulting_date,
+                    "org": source_str,
+                },
+            }
+        ]
+
+        # 보조 질문(instructions.data[*].instruction)으로 추가 레코드 생성
+        instructions = item.get("instructions", [])
+        if instructions:
+            for instr_item in instructions[0].get("data", []):
+                sub_q = instr_item.get("instruction", "").strip()
+                if sub_q and sub_q != question:
+                    records.append(
+                        {
+                            "question": sub_q,
+                            "answer": a_part,
+                            "source": "71852_중앙행정기관",
+                            "category": category,
+                            "metadata": {
+                                "source_id": source_id,
+                                "consulting_date": consulting_date,
+                                "org": source_str,
+                                "question_type": "auxiliary",
+                            },
+                        }
+                    )
+
+        return records
+
+    @staticmethod
+    def _extract_question(q_part: str) -> str:
+        """Q 블록에서 질문 텍스트를 추출한다."""
+        # "Q :" 또는 "Q:" 이후 텍스트 추출
+        q_match = re.search(r"\nQ\s*:(.*?)(?=\n\n|\Z)", q_part, re.DOTALL)
+        if q_match:
+            return q_match.group(1).strip()
+
+        # fallback: "제목 :" 이후 텍스트
+        title_match = re.search(r"제목\s*:\s*(.+)", q_part)
+        if title_match:
+            return title_match.group(1).strip()
+
+        return q_part.strip()
+
+
+class GovQALocalParser(GovQAParser):
+    """71852 지방행정기관 파서 — GovQAParser와 동일한 로직, source 레이블만 다름."""
+
+    def _parse_item(self, item: dict) -> list[dict]:
+        records = super()._parse_item(item)
+        for r in records:
+            r["source"] = "71852_지방행정기관"
+        return records
+
+
+class AdminLawParser:
+    """71847 행정법 파서.
+
+    label.input을 질문, label.output을 답변으로 사용한다.
+    결정례(TL_결정례_QA)와 법령(TL_법령_QA) 모두 동일 구조.
+    """
+
+    def __init__(self, source_label: str = "71847_결정례"):
+        self.source_label = source_label
+
+    def parse(self, filepath: Path) -> list[dict]:
+        data = _load_json(filepath)
+        if isinstance(data, list):
+            records = []
+            for item in data:
+                records.extend(self._parse_item(item))
+            return records
+        return self._parse_item(data)
+
+    def _parse_item(self, item: dict) -> list[dict]:
+        label = item.get("label", {})
+        question = label.get("input", "").strip()
+        answer = label.get("output", "").strip()
+
+        if not question or not answer:
+            return []
+
+        info = item.get("info", {})
+        case_name = info.get("caseName", info.get("title", ""))
+        category = info.get("ministry", info.get("caseCode", ""))
+
+        return [
+            {
+                "question": question,
+                "answer": answer,
+                "source": self.source_label,
+                "category": category,
+                "metadata": {
+                    "case_name": case_name,
+                    "law_class": info.get("lawClass", ""),
+                },
+            }
+        ]

src/data_collection_preprocessing/pipeline.py

@@ -0,0 +1,177 @@
+"""민원답변 학습 데이터 파이프라인."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import random
+from pathlib import Path
+from typing import Any
+
+from .config import DataConfig
+from .parsers import AdminLawParser, GovQALocalParser, GovQAParser, GukripParser
+
+logger = logging.getLogger(__name__)
+
+
+class CivilResponseDataPipeline:
+    """AI Hub 원시 데이터를 instruction-tuning JSONL로 변환하는 파이프라인."""
+
+    INSTRUCTION_TEXT = "다음 민원에 대한 답변을 작성해 주세요."
+
+    def __init__(self, config: DataConfig | None = None):
+        self.config = config or DataConfig()
+
+    def run(self) -> dict[str, int]:
+        """전체 파이프라인 실행. 결과 통계 반환."""
+        records: list[dict] = []
+
+        logger.info("71852 데이터 처리 시작")
+        records_71852 = self._process_71852()
+        logger.info("71852 데이터 %d개 수집", len(records_71852))
+        records.extend(records_71852)
+
+        logger.info("71847 데이터 처리 시작")
+        records_71847 = self._process_71847()
+        logger.info("71847 데이터 %d개 수집", len(records_71847))
+        records.extend(records_71847)
+
+        logger.info("중복 제거 전 총 %d개", len(records))
+        records = self._deduplicate(records)
+        logger.info("중복 제거 후 %d개", len(records))
+
+        records = self._filter(records)
+        logger.info("필터링 후 %d개", len(records))
+
+        train, val = self._split(records)
+        logger.info("train=%d, val=%d", len(train), len(val))
+
+        output_dir = Path(self.config.output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        self._save_jsonl(train, output_dir / "train.jsonl")
+        self._save_jsonl(val, output_dir / "val.jsonl")
+
+        return {
+            "total": len(records),
+            "train": len(train),
+            "val": len(val),
+        }
+
+    # ------------------------------------------------------------------
+    # 데이터셋별 처리
+    # ------------------------------------------------------------------
+
+    def _process_71852(self) -> list[dict]:
+        base = Path(self.config.raw_dir) / "71852"
+        records: list[dict] = []
+
+        # 국립아시아문화전당
+        gukrp = GukripParser()
+        for split in ("train", "val"):
+            dir_path = base / split / "국립"
+            if dir_path.exists():
+                records.extend(self._parse_dir(gukrp, dir_path))
+
+        # 중앙행정기관
+        gov_central = GovQAParser()
+        for split in ("train", "val"):
+            dir_path = base / split / "중앙"
+            if dir_path.exists():
+                records.extend(self._parse_dir(gov_central, dir_path))
+
+        # 지방행정기관
+        gov_local = GovQALocalParser()
+        for split in ("train", "val"):
+            dir_path = base / split / "지방"
+            if dir_path.exists():
+                records.extend(self._parse_dir(gov_local, dir_path))
+
+        return records
+
+    def _process_71847(self) -> list[dict]:
+        base = Path(self.config.raw_dir) / "71847"
+        records: list[dict] = []
+
+        # 결정례 QA
+        decision_parser = AdminLawParser(source_label="71847_결정례")
+        dir_path = base / "TL_결정례_QA"
+        if dir_path.exists():
+            records.extend(self._parse_dir(decision_parser, dir_path))
+
+        # 법령 QA
+        law_parser = AdminLawParser(source_label="71847_법령")
+        dir_path = base / "TL_법령_QA"
+        if dir_path.exists():
+            records.extend(self._parse_dir(law_parser, dir_path))
+
+        return records
+
+    # ------------------------------------------------------------------
+    # 유틸리티
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _parse_dir(parser: Any, dir_path: Path) -> list[dict]:
+        records: list[dict] = []
+        json_files = list(dir_path.glob("*.json"))
+        logger.debug("  %s: %d 파일", dir_path, len(json_files))
+        for filepath in json_files:
+            try:
+                records.extend(parser.parse(filepath))
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("파싱 실패 %s: %s", filepath, exc)
+        return records
+
+    def _deduplicate(self, records: list[dict]) -> list[dict]:
+        """질문+답변 해시 기반 중복 제거."""
+        seen: set[str] = set()
+        unique: list[dict] = []
+        for rec in records:
+            key = hashlib.md5(  # nosec B324
+                (rec["question"] + rec["answer"]).encode("utf-8"),
+                usedforsecurity=False,
+            ).hexdigest()
+            if key not in seen:
+                seen.add(key)
+                unique.append(rec)
+        return unique
+
+    def _filter(self, records: list[dict]) -> list[dict]:
+        """길이 필터링."""
+        filtered: list[dict] = []
+        for rec in records:
+            answer_len = len(rec["answer"])
+            question_len = len(rec["question"])
+            if answer_len < self.config.min_answer_length:
+                continue
+            if answer_len > self.config.max_answer_length:
+                continue
+            if question_len < self.config.min_question_length:
+                continue
+            filtered.append(rec)
+        return filtered
+
+    def _split(self, records: list[dict]) -> tuple[list[dict], list[dict]]:
+        """train/val 분리 (셔플 후 비율 분할)."""
+        shuffled = list(records)
+        random.seed(42)
+        random.shuffle(shuffled)
+        split_idx = int(len(shuffled) * self.config.train_ratio)
+        return shuffled[:split_idx], shuffled[split_idx:]
+
+    def _save_jsonl(self, records: list[dict], filepath: Path) -> None:
+        """Instruction-tuning 표준 JSONL 형식으로 저장."""
+        filepath = Path(filepath)
+        with open(filepath, "w", encoding="utf-8") as f:
+            for rec in records:
+                line = {
+                    "instruction": self.INSTRUCTION_TEXT,
+                    "input": rec["question"],
+                    "output": rec["answer"],
+                    "source": rec["source"],
+                    "category": rec.get("category", ""),
+                }
+                f.write(json.dumps(line, ensure_ascii=False) + "\n")
+        logger.info("저장 완료: %s (%d 레코드)", filepath, len(records))

src/inference/actions/__init__.py

@@ -0,0 +1,4 @@
+from .base import ActionResult, BaseAction, Citation
+from .data_go_kr import MinwonAnalysisAction
+
+__all__ = ["ActionResult", "BaseAction", "Citation", "MinwonAnalysisAction"]

src/inference/actions/base.py

@@ -0,0 +1,226 @@
+"""Action 추상 베이스 클래스 모듈.
+
+AgentLoop에서 외부 API나 서비스를 호출하는 Action의
+공통 인터페이스와 결과 타입을 정의한다.
+
+Issue: #394
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from loguru import logger
+
+from ..session_context import SessionContext
+
+
+@dataclass
+class Citation:
+    """출처 정보.
+
+    API 응답이나 검색 결과의 출처를 표현한다.
+
+    Parameters
+    ----------
+    title : str
+        출처 제목.
+    url : str
+        출처 URL. 없으면 빈 문자열.
+    date : str
+        작성/등록 날짜. 없으면 빈 문자열.
+    snippet : str
+        본문 요약(발췌). 없으면 빈 문자열.
+    metadata : Dict[str, Any]
+        추가 메타데이터.
+    """
+
+    title: str
+    url: str = ""
+    date: str = ""
+    snippet: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "title": self.title,
+            "url": self.url,
+            "date": self.date,
+            "snippet": self.snippet,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass
+class ActionResult:
+    """Action 실행 결과.
+
+    BaseAction.execute()의 반환값으로,
+    AgentLoop의 ToolFunction 반환 형식(dict)과 호환된다.
+
+    Parameters
+    ----------
+    success : bool
+        실행 성공 여부.
+    data : Dict[str, Any]
+        성공 시 페이로드.
+    error : Optional[str]
+        실패 시 오류 메시지.
+    source : str
+        결과 출처 식별자 (예: "data.go.kr").
+    citations : List[Citation]
+        참조된 출처 목록.
+    context_text : str
+        LLM 프롬프트에 삽입할 컨텍스트 텍스트.
+    """
+
+    success: bool
+    data: Dict[str, Any] = field(default_factory=dict)
+    error: Optional[str] = None
+    source: str = ""
+    citations: List[Citation] = field(default_factory=list)
+    context_text: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        """AgentLoop ToolFunction 반환 형식(dict)으로 변환."""
+        return {
+            "success": self.success,
+            "data": self.data,
+            "error": self.error,
+            "source": self.source,
+            "citations": [c.to_dict() for c in self.citations],
+            "context_text": self.context_text,
+        }
+
+
+class BaseAction(ABC):
+    """Action 추상 베이스 클래스.
+
+    AgentLoop의 ToolFunction 시그니처(query, context, session) -> dict와
+    호환되는 비동기 callable을 제공한다.
+
+    Parameters
+    ----------
+    action_name : str
+        Action 식별자. 로깅에 사용된다.
+    """
+
+    def __init__(self, action_name: str) -> None:
+        self._action_name = action_name
+
+    async def __call__(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: SessionContext,
+    ) -> Dict[str, Any]:
+        """AgentLoop ToolFunction 시그니처 호환 진입점.
+
+        1. validate()로 사전 검증.
+        2. 검증 통과 시 execute() 실행.
+        3. ActionResult를 dict로 변환해 반환.
+        4. 성공/실패를 로깅한다.
+
+        Parameters
+        ----------
+        query : str
+            사용자 요청 텍스트.
+        context : Dict[str, Any]
+            AgentLoop 누적 컨텍스트(이전 tool 결과 포함).
+        session : SessionContext
+            현재 세션 컨텍스트.
+
+        Returns
+        -------
+        Dict[str, Any]
+            ActionResult.to_dict() 결과.
+        """
+        # 1. 사전 검증
+        validation_error = self.validate(query, context, session)
+        if validation_error:
+            logger.warning(f"[{self._action_name}] 검증 실패: {validation_error}")
+            result = ActionResult(
+                success=False,
+                error=validation_error,
+                source=self._action_name,
+            )
+            return result.to_dict()
+
+        # 2. 실행
+        try:
+            result = await self.execute(query, context, session)
+        except Exception as exc:
+            logger.error(
+                f"[{self._action_name}] execute() 예외 발생: {exc}",
+                exc_info=True,
+            )
+            result = ActionResult(
+                success=False,
+                error=f"Action 실행 중 오류: {exc}",
+                source=self._action_name,
+            )
+
+        # 3. 로깅
+        if result.success:
+            logger.info(
+                f"[{self._action_name}] 성공 "
+                f"citations={len(result.citations)} "
+                f"context_text_len={len(result.context_text)}"
+            )
+        else:
+            logger.warning(f"[{self._action_name}] 실패: {result.error}")
+
+        return result.to_dict()
+
+    def validate(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: SessionContext,
+    ) -> Optional[str]:
+        """실행 전 사전 검증. 오류가 있으면 오류 메시지 문자열을 반환한다.
+
+        기본 구현: 빈 쿼리 검사. 서브클래스에서 super() 호출 후 추가 검증 가능.
+
+        Parameters
+        ----------
+        query : str
+            사용자 요청 텍스트.
+        context : Dict[str, Any]
+            AgentLoop 누적 컨텍스트.
+        session : SessionContext
+            현재 세션 컨텍스트.
+
+        Returns
+        -------
+        Optional[str]
+            검증 실패 메시지. None이면 검증 통과.
+        """
+        if not query or not query.strip():
+            return "쿼리가 비어 있습니다."
+        return None
+
+    @abstractmethod
+    async def execute(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: SessionContext,
+    ) -> ActionResult:
+        """Action 실제 실행 로직. 서브클래스에서 구현한다.
+
+        Parameters
+        ----------
+        query : str
+            사용자 요청 텍스트.
+        context : Dict[str, Any]
+            AgentLoop 누적 컨텍스트.
+        session : SessionContext
+            현재 세션 컨텍스트.
+
+        Returns
+        -------
+        ActionResult
+            실행 결과.
+        """
+        ...

src/inference/actions/data_go_kr.py

@@ -0,0 +1,952 @@
+"""data.go.kr 민원 분석 API Action 모듈.
+
+공공데이터포털(data.go.kr)의 민원분석정보조회 API를 호출하여
+유사 민원 사례를 검색하고 LLM 컨텍스트로 변환한다.
+
+API 문서: https://www.data.go.kr/data/15025759/openapi.do
+Issue: #394
+"""
+
+import os
+from typing import Any, Dict, List, Optional
+
+from loguru import logger
+
+from ..session_context import SessionContext
+from .base import ActionResult, BaseAction, Citation
+
+try:
+    import httpx
+
+    _HTTPX_AVAILABLE = True
+    _HttpxTimeoutError = httpx.TimeoutException
+    _HttpxStatusError = httpx.HTTPStatusError
+except ImportError:
+    httpx = None  # type: ignore
+    _HTTPX_AVAILABLE = False
+    _HttpxTimeoutError = type(None)  # 절대 매치되지 않는 타입
+    _HttpxStatusError = type(None)
+
+
+# ---------------------------------------------------------------------------
+# 상수
+# ---------------------------------------------------------------------------
+
+_BASE_URL = "http://apis.data.go.kr/1140100/minAnalsInfoView5"
+_ENDPOINT_SIMILAR = "/minSimilarInfo5"
+
+
+class MinwonAnalysisAction(BaseAction):
+    """공공데이터포털 민원분석정보조회 API Action.
+
+    data.go.kr의 민원분석정보조회 API를 호출하여
+    유사 민원 사례를 가져오고 AgentLoop 컨텍스트에 제공한다.
+
+    Parameters
+    ----------
+    api_key : Optional[str]
+        공공데이터포털 API 인증키. None이면 DATA_GO_KR_API_KEY 환경변수에서 로드.
+    ret_count : int
+        반환할 유사 사례 수. 기본값 5.
+    min_score : int
+        최소 유사도 점수. 기본값 2.
+    timeout : float
+        HTTP 요청 타임아웃(초). 기본값 10.0.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        ret_count: int = 5,
+        min_score: int = 2,
+        timeout: float = 10.0,
+    ) -> None:
+        super().__init__(action_name="minwon_analysis")
+        self._api_key = api_key or os.getenv("DATA_GO_KR_API_KEY", "")
+        self._ret_count = ret_count
+        self._min_score = min_score
+        self._timeout = timeout
+
+    def validate(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: SessionContext,
+    ) -> Optional[str]:
+        """API 키와 쿼리 길이를 검증한다.
+
+        Parameters
+        ----------
+        query : str
+            사용자 요청 텍스트.
+        context : Dict[str, Any]
+            AgentLoop 누적 컨텍스트.
+        session : SessionContext
+            현재 세션 컨텍스트.
+
+        Returns
+        -------
+        Optional[str]
+            검증 실패 메시지. None이면 통과.
+        """
+        base_error = super().validate(query, context, session)
+        if base_error:
+            return base_error
+
+        if not self._api_key:
+            return "DATA_GO_KR_API_KEY 환경변수가 설정되지 않았습니다."
+
+        if len(query.strip()) < 2:
+            return "쿼리가 너무 짧습니다 (최소 2자 이상)."
+
+        if not _HTTPX_AVAILABLE:
+            return "httpx 패키지가 설치되지 않았습니다. pip install httpx>=0.27.0"
+
+        return None
+
+    async def execute(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: SessionContext,
+    ) -> ActionResult:
+        """유사 민원 사례를 조회하고 ActionResult로 반환한다.
+
+        1. _enrich_query로 분류 카테고리를 반영한 검색어 생성.
+        2. _call_similar_api로 API 호출.
+        3. 결과를 파싱하여 ActionResult 생성.
+
+        Parameters
+        ----------
+        query : str
+            사용자 요청 텍스트.
+        context : Dict[str, Any]
+            AgentLoop 누적 컨텍스트.
+        session : SessionContext
+            현재 세션 컨텍스트.
+
+        Returns
+        -------
+        ActionResult
+            유사 민원 사례와 LLM 컨텍스트가 포함된 결과.
+        """
+        payload = await self.fetch_similar_cases(query, context)
+        items = payload["results"]
+
+        if items is None:
+            return ActionResult(
+                success=False,
+                error="민원 분석 API 호출에 실패했습니다.",
+                source="data.go.kr",
+            )
+
+        if not items:
+            return ActionResult(
+                success=True,
+                data={"results": [], "query": payload["query"], "count": 0},
+                source="data.go.kr",
+                context_text="",
+            )
+
+        return ActionResult(
+            success=True,
+            data={
+                "results": items,
+                "query": payload["query"],
+                "count": len(items),
+            },
+            source="data.go.kr",
+            citations=payload["citations"],
+            context_text=payload["context_text"],
+        )
+
+    async def fetch_similar_cases(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        ret_count: Optional[int] = None,
+        min_score: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """유사 민원 사례 검색에 필요한 payload를 구성한다.
+
+        api_lookup capability 내부에서 minSimilarInfo5 호출 경로를
+        공용으로 재사용할 수 있도록 공개 helper로 제공한다.
+
+        Parameters
+        ----------
+        ret_count : Optional[int]
+            반환 건수 오버라이드.
+        min_score : Optional[int]
+            최소 유사도 오버라이드.
+        """
+        search_query = self._enrich_query(query, context)
+        logger.debug(f"[minwon_analysis] 보강된 검색어: {search_query!r}")
+        items = await self._call_similar_api(search_query, ret_count=ret_count, min_score=min_score)
+
+        return {
+            "query": search_query,
+            "results": items,
+            "count": len(items or []),
+            "context_text": self._build_context_text(items or [], query) if items else "",
+            "citations": self._build_citations(items or []),
+        }
+
+    async def _call_similar_api(
+        self,
+        search_query: str,
+        ret_count: Optional[int] = None,
+        min_score: Optional[int] = None,
+    ) -> Optional[List[Dict[str, Any]]]:
+        """공공데이터포털 유사민원정보 API를 호출한다.
+
+        Parameters
+        ----------
+        search_query : str
+            API에 전달할 검색어.
+        ret_count : Optional[int]
+            반환 건수 오버라이드. None이면 인스턴스 기본값.
+        min_score : Optional[int]
+            최소 유사도 오버라이드. None이면 인스턴스 기본값.
+
+        Returns
+        -------
+        Optional[List[Dict[str, Any]]]
+            성공 시 아이템 목록, 실패 시 None.
+        """
+        url = _BASE_URL + _ENDPOINT_SIMILAR
+        params = {
+            "serviceKey": self._api_key,
+            "startPos": 1,
+            "retCount": ret_count if ret_count is not None else self._ret_count,
+            "target": "qna,qna_origin",
+            "minScore": min_score if min_score is not None else self._min_score,
+            "dataType": "json",
+            "searchword": search_query,
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout) as client:
+                response = await client.get(url, params=params)
+                response.raise_for_status()
+                body = response.json()
+        except _HttpxTimeoutError as exc:
+            logger.warning(f"[minwon_analysis] API 타임아웃: {exc}")
+            return None
+        except _HttpxStatusError as exc:
+            logger.warning(f"[minwon_analysis] HTTP 오류 {exc.response.status_code}: {exc}")
+            return None
+        except Exception as exc:
+            logger.error(f"[minwon_analysis] API 호출 오류: {exc}", exc_info=True)
+            return None
+
+        # 실제 API는 최상위 배열([]) 또는 returnObject 래핑으로 응답
+        if isinstance(body, list):
+            return body
+
+        if not isinstance(body, dict):
+            logger.warning(f"[minwon_analysis] 예상치 못한 응답 타입: {type(body)}")
+            return None
+
+        # returnObject 래핑
+        if "returnObject" in body:
+            obj = body["returnObject"]
+            return obj if isinstance(obj, list) else []
+
+        # 에러 응답 검사 — 성공 코드만 통과
+        _SUCCESS_CODES = {"00", "0", "200", ""}
+        code = str(body.get("code", body.get("resultCode", "00")))
+        if code not in _SUCCESS_CODES:
+            logger.warning(
+                f"[minwon_analysis] API 에러 (code={code}): {body.get('msg', body.get('resultMsg', ''))}"
+            )
+            return None
+
+        return self._parse_similar_items(body)
+
+    def _parse_similar_items(self, raw_body: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """API 응답에서 아이템 목록을 추출한다.
+
+        배열 형식과 단일 dict 래핑 형식을 모두 처리한다.
+
+        Parameters
+        ----------
+        raw_body : Dict[str, Any]
+            API 전체 응답 JSON.
+
+        Returns
+        -------
+        List[Dict[str, Any]]
+            파싱된 아이템 목록.
+        """
+        # 최상위 키 탐색: body → items → item 또는 직접 items
+        body = raw_body.get("body") or raw_body.get("response", {}).get("body") or raw_body
+        items_raw = body.get("items") if isinstance(body, dict) else None
+
+        if items_raw is None:
+            logger.debug("[minwon_analysis] 응답에 'items' 키 없음 — 빈 결과 반환")
+            return []
+
+        # 배열 vs dict 래핑 처리
+        if isinstance(items_raw, list):
+            return items_raw
+        if isinstance(items_raw, dict):
+            item = items_raw.get("item")
+            if item is None:
+                return []
+            if isinstance(item, list):
+                return item
+            if isinstance(item, dict):
+                return [item]
+
+        logger.warning(f"[minwon_analysis] 예상치 못한 items 형식: {type(items_raw)}")
+        return []
+
+    def _build_context_text(self, items: List[Dict[str, Any]], query: str) -> str:
+        """아이템 목록을 LLM 프롬프트용 컨텍스트 텍스트로 변환한다.
+
+        Parameters
+        ----------
+        items : List[Dict[str, Any]]
+            API에서 반환된 아이템 목록.
+        query : str
+            원본 사용자 쿼리.
+
+        Returns
+        -------
+        str
+            LLM 프롬프트에 삽입할 텍스트.
+        """
+        if not items:
+            return ""
+
+        lines = [f"### 공공데이터포털 유사 민원 사례 (검색어: {query})\n"]
+        for i, item in enumerate(items[:5], 1):
+            title = item.get("title") or item.get("qnaTitle") or ""
+            content = item.get("content") or item.get("qnaContent") or item.get("question") or ""
+            answer = item.get("answer") or item.get("qnaAnswer") or ""
+            category = (
+                item.get("category") or item.get("minCategory") or item.get("main_sub_name") or ""
+            )
+            date = item.get("regDate") or item.get("date") or item.get("create_date") or ""
+
+            lines.append(f"{i}. [{category}] {title}")
+            if date:
+                lines.append(f"   (등록일: {date})")
+            if content:
+                preview = content[:200] + "..." if len(content) > 200 else content
+                lines.append(f"   민원: {preview}")
+            if answer:
+                ans_preview = answer[:200] + "..." if len(answer) > 200 else answer
+                lines.append(f"   답변: {ans_preview}")
+            lines.append("")
+
+        return "\n".join(lines)
+
+    def _build_citations(self, items: List[Dict[str, Any]]) -> List[Citation]:
+        """아이템 목록에서 Citation 객체 목록을 생성한다.
+
+        Parameters
+        ----------
+        items : List[Dict[str, Any]]
+            API에서 반환된 아이템 목록.
+
+        Returns
+        -------
+        List[Citation]
+            Citation 객체 목록.
+        """
+        citations = []
+        for item in items:
+            title = item.get("title") or item.get("qnaTitle") or ""
+            url = item.get("url") or item.get("detailUrl") or ""
+            date = item.get("regDate") or item.get("date") or item.get("create_date") or ""
+            content = item.get("content") or item.get("qnaContent") or item.get("question") or ""
+            snippet = content[:150] + "..." if len(content) > 150 else content
+
+            # 제목 없는 항목은 스킵
+            if not title:
+                continue
+
+            citations.append(
+                Citation(
+                    title=title,
+                    url=url,
+                    date=date,
+                    snippet=snippet,
+                    metadata={k: v for k, v in item.items() if k not in ("content", "answer")},
+                )
+            )
+        return citations
+
+    def _enrich_query(self, query: str, context: Dict[str, Any]) -> str:
+        """세션 요약이나 최근 assistant 응답을 반영해 검색어를 보강한다.
+
+        Parameters
+        ----------
+        query : str
+            원본 사용자 쿼리.
+        context : Dict[str, Any]
+            AgentLoop 누적 컨텍스트.
+
+        Returns
+        -------
+        str
+            보강된 검색어.
+        """
+        query_variants = context.get("query_variants", {})
+        if isinstance(query_variants, dict):
+            prepared_query = str(query_variants.get("api_lookup", "")).strip()
+            if prepared_query:
+                return prepared_query
+
+        session_context = str(context.get("session_context", "")).strip()
+        if session_context:
+            recent_summary = " ".join(session_context.splitlines()[-2:]).strip()
+            if recent_summary and recent_summary not in query:
+                return f"{query} {recent_summary[:120]}".strip()
+        return query
+
+    # ---------------------------------------------------------------------------
+    # 공통 API 호출 헬퍼
+    # ---------------------------------------------------------------------------
+
+    async def _call_api(
+        self, endpoint: str, params: Dict[str, Any]
+    ) -> Optional[List[Dict[str, Any]]]:
+        """공통 API 호출 + 응답 파싱.
+
+        Parameters
+        ----------
+        endpoint : str
+            _BASE_URL 뒤에 붙는 엔드포인트 경로.
+        params : Dict[str, Any]
+            쿼리 파라미터 (serviceKey, dataType 자동 추가).
+
+        Returns
+        -------
+        Optional[List[Dict[str, Any]]]
+            성공 시 아이템 목록, 실패 시 None.
+        """
+        if not _HTTPX_AVAILABLE:
+            logger.warning("[minwon_analysis] httpx 미설치")
+            return None
+
+        url = _BASE_URL + endpoint
+        params["serviceKey"] = self._api_key
+        params["dataType"] = "json"
+
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout) as client:
+                response = await client.get(url, params=params)
+                response.raise_for_status()
+                body = response.json()
+        except httpx.TimeoutException as exc:
+            logger.warning(f"[minwon_analysis] API 타임아웃 ({endpoint}): {exc}")
+            return None
+        except httpx.HTTPStatusError as exc:
+            logger.warning(
+                f"[minwon_analysis] HTTP 오류 ({endpoint}) " f"{exc.response.status_code}: {exc}"
+            )
+            return None
+        except Exception as exc:
+            logger.error(
+                f"[minwon_analysis] API 호출 오류 ({endpoint}): {exc}",
+                exc_info=True,
+            )
+            return None
+
+        # 최상위 배열
+        if isinstance(body, list):
+            return body
+
+        # dict 래핑
+        if isinstance(body, dict):
+            if "returnObject" in body:
+                obj = body["returnObject"]
+                return obj if isinstance(obj, list) else []
+            # 에러 코드 화이트리스트 (기존 _call_similar_api와 동일)
+            code = str(body.get("code", body.get("resultCode", "00")))
+            if code not in ("00", "0", "200", ""):
+                logger.warning(
+                    f"[minwon_analysis] API 에러 ({endpoint}): code={code}, "
+                    f"msg={body.get('msg', body.get('resultMsg', ''))}"
+                )
+                return None
+            # body > items 경로 파싱 시도
+            return self._parse_similar_items(body)
+
+        return None
+
+    # ---------------------------------------------------------------------------
+    # 이슈 탐지 API (issue_detector)
+    # ---------------------------------------------------------------------------
+
+    async def get_rising_keywords(
+        self,
+        analysis_time: str,
+        max_result: int = 10,
+        target: str = "pttn,dfpt,saeol",
+        main_sub_code: str = "1140100",
+    ) -> Optional[List[Dict[str, Any]]]:
+        """급증키워드를 조회한다.
+
+        Parameters
+        ----------
+        analysis_time : str
+            분석 시점 (예: "2021050614").
+        max_result : int
+            최대 결과 수.
+        target : str
+            대상 채널.
+        main_sub_code : str
+            기관 코드.
+        """
+        return await self._call_api(
+            "/minRisingKeyword5",
+            {
+                "analysisTime": analysis_time,
+                "maxResult": max_result,
+                "target": target,
+                "mainSubCode": main_sub_code,
+            },
+        )
+
+    async def get_today_topics(
+        self,
+        search_date: str,
+        top_n: int = 5,
+        target: str = "pttn,dfpt,saeol",
+    ) -> Optional[List[Dict[str, Any]]]:
+        """오늘 이슈 토픽을 조회한다.
+
+        Parameters
+        ----------
+        search_date : str
+            검색 날짜 (예: "20210506").
+        top_n : int
+            상위 N개.
+        target : str
+            대상 채널.
+        """
+        return await self._call_api(
+            "/minTodayTopicInfo5",
+            {
+                "searchDate": search_date,
+                "todayTopicTopN": top_n,
+                "target": target,
+            },
+        )
+
+    async def get_top_keywords_by_period(
+        self,
+        analysis_time: str,
+        period: str = "MONTHLY",
+        range_count: int = 1,
+        max_result: int = 5,
+        target: str = "pttn,dfpt,saeol",
+        main_sub_code: str = "1140100",
+    ) -> Optional[List[Dict[str, Any]]]:
+        """기간별 최다 키워드를 조회한다.
+
+        Parameters
+        ----------
+        analysis_time : str
+            분석 시작 시점 (예: "20210301").
+        period : str
+            기간 단위 ("DAILY" | "WEEKLY" | "MONTHLY").
+        range_count : int
+            기간 범위 수.
+        max_result : int
+            최대 결과 수.
+        target : str
+            대상 채널.
+        main_sub_code : str
+            기관 코드.
+        """
+        return await self._call_api(
+            "/minDFTopNKeyword5",
+            {
+                "target": target,
+                "period": period,
+                "analysisTime": analysis_time,
+                "rangeCount": range_count,
+                "maxResult": max_result,
+                "mainSubCode": main_sub_code,
+            },
+        )
+
+    # ---------------------------------------------------------------------------
+    # 통계 API (stats_lookup)
+    # ---------------------------------------------------------------------------
+
+    async def get_statistics(
+        self,
+        date_from: str,
+        date_to: str,
+        period: str = "DAILY",
+        target: str = "pttn,dfpt,saeol",
+        sort_by: str = "NAME",
+        sort_order: str = "false",
+    ) -> Optional[List[Dict[str, Any]]]:
+        """맞춤형 통계를 조회한다.
+
+        Parameters
+        ----------
+        date_from : str
+            시작 날짜 (YYYYMMDD).
+        date_to : str
+            종료 날짜 (YYYYMMDD).
+        period : str
+            기간 단위.
+        target : str
+            대상 채널.
+        sort_by : str
+            정렬 기준.
+        sort_order : str
+            정렬 순서 ("true" 오름차순, "false" 내림차순).
+        """
+        return await self._call_api(
+            "/minStaticsInfo5",
+            {
+                "target": target,
+                "dateFrom": date_from,
+                "dateTo": date_to,
+                "period": period,
+                "sortBy": sort_by,
+                "sortOrder": sort_order,
+            },
+        )
+
+    async def get_trend(
+        self,
+        date_from: str,
+        date_to: str,
+        period: str = "DAILY",
+        target: str = "pttn,dfpt,saeol",
+        sort_by: str = "NAME",
+        sort_order: str = "false",
+    ) -> Optional[List[Dict[str, Any]]]:
+        """민원 트렌드(시계열)를 조회한다.
+
+        Parameters
+        ----------
+        date_from : str
+            시작 날짜시간 (YYYYMMDDHH).
+        date_to : str
+            종료 날짜시간 (YYYYMMDDHH).
+        period : str
+            기간 단위.
+        target : str
+            대상 채널.
+        sort_by : str
+            정렬 기준.
+        sort_order : str
+            정렬 순서.
+        """
+        return await self._call_api(
+            "/minTimeSeriseView5",
+            {
+                "target": target,
+                "dateFrom": date_from,
+                "dateTo": date_to,
+                "period": period,
+                "sortBy": sort_by,
+                "sortOrder": sort_order,
+            },
+        )
+
+    async def get_doc_count(
+        self,
+        date_from: str,
+        date_to: str,
+        searchword: str,
+        target: str = "pttn,dfpt,saeol",
+        min_score: int = 70,
+        omit_duplicate: bool = False,
+    ) -> Optional[List[Dict[str, Any]]]:
+        """민원 건수를 조회한다.
+
+        Parameters
+        ----------
+        date_from : str
+            시작 날짜 (YYYYMMDD).
+        date_to : str
+            종료 날짜 (YYYYMMDD).
+        searchword : str
+            검색어.
+        target : str
+            대상 채널.
+        min_score : int
+            최소 유사도 점수.
+        omit_duplicate : bool
+            중복 제거 여부.
+        """
+        return await self._call_api(
+            "/minSearchDocCnt5",
+            {
+                "dateFrom": date_from,
+                "dateTo": date_to,
+                "target": target,
+                "minScore": min_score,
+                "searchword": searchword,
+                "omitDuplicate": str(omit_duplicate).lower(),
+            },
+        )
+
+    async def get_org_ranking(
+        self,
+        date_from: str,
+        date_to: str,
+        top_n: int = 5,
+        target: str = "pttn,dfpt,saeol",
+        sort_by: str = "VALUE",
+        sort_order: str = "false",
+    ) -> Optional[List[Dict[str, Any]]]:
+        """기관별 민원 순위를 조회한다.
+
+        Parameters
+        ----------
+        date_from : str
+            시작 날짜 (YYYYMMDD).
+        date_to : str
+            종료 날짜 (YYYYMMDD).
+        top_n : int
+            상위 N개.
+        target : str
+            대상 채널.
+        sort_by : str
+            정렬 기준.
+        sort_order : str
+            정렬 순서.
+        """
+        return await self._call_api(
+            "/minMofacetInfo5",
+            {
+                "topN": top_n,
+                "sortBy": sort_by,
+                "sortOrder": sort_order,
+                "target": target,
+                "dateFrom": date_from,
+                "dateTo": date_to,
+            },
+        )
+
+    async def get_region_ranking(
+        self,
+        date_from: str,
+        date_to: str,
+        top_n: int = 5,
+        target: str = "pttn,dfpt,saeol",
+        sort_by: str = "VALUE",
+        sort_order: str = "false",
+    ) -> Optional[List[Dict[str, Any]]]:
+        """지역별 민원 순위를 조회한다.
+
+        Parameters
+        ----------
+        date_from : str
+            시작 날짜 (YYYYMMDD).
+        date_to : str
+            종료 날짜 (YYYYMMDD).
+        top_n : int
+            상위 N개.
+        target : str
+            대상 채널.
+        sort_by : str
+            정렬 기준.
+        sort_order : str
+            정렬 순서.
+        """
+        return await self._call_api(
+            "/minMrfacetInfo5",
+            {
+                "topN": top_n,
+                "sortBy": sort_by,
+                "sortOrder": sort_order,
+                "dateFrom": date_from,
+                "dateTo": date_to,
+                "target": target,
+            },
+        )
+
+    # ---------------------------------------------------------------------------
+    # 키워드 분석 API (keyword_analyzer)
+    # ---------------------------------------------------------------------------
+
+    async def get_core_keywords(
+        self,
+        date_from: str,
+        date_to: str,
+        result_count: int = 5,
+        target: str = "pttn,dfpt,saeol",
+    ) -> Optional[List[Dict[str, Any]]]:
+        """핵심 키워드를 조회한다.
+
+        Parameters
+        ----------
+        date_from : str
+            시작 날짜 (YYYYMMDD).
+        date_to : str
+            종료 날짜 (YYYYMMDD).
+        result_count : int
+            결과 수.
+        target : str
+            대상 채널.
+        """
+        return await self._call_api(
+            "/minTopNKeyword5",
+            {
+                "target": target,
+                "dateFrom": date_from,
+                "dateTo": date_to,
+                "resultCount": result_count,
+            },
+        )
+
+    async def get_related_words(
+        self,
+        date_from: str,
+        date_to: str,
+        searchword: str,
+        result_count: int = 5,
+        target: str = "pttn,dfpt,saeol",
+    ) -> Optional[List[Dict[str, Any]]]:
+        """연관어를 조회한다.
+
+        Parameters
+        ----------
+        date_from : str
+            시작 날짜 (YYYYMMDD).
+        date_to : str
+            종료 날짜 (YYYYMMDD).
+        searchword : str
+            검색어.
+        result_count : int
+            결과 수.
+        target : str
+            대상 채널.
+        """
+        return await self._call_api(
+            "/minWdcloudInfo5",
+            {
+                "target": target,
+                "searchword": searchword,
+                "dateFrom": date_from,
+                "dateTo": date_to,
+                "resultCount": result_count,
+            },
+        )
+
+    # ---------------------------------------------------------------------------
+    # 인구통계 API (demographics_lookup)
+    # ---------------------------------------------------------------------------
+
+    async def get_gender_stats(
+        self,
+        date_from: str,
+        date_to: str,
+        searchword: str,
+        target: str = "pttn",
+    ) -> Optional[List[Dict[str, Any]]]:
+        """성별 통계를 조회한다.
+
+        Parameters
+        ----------
+        date_from : str
+            시작 날짜 (YYYYMMDD).
+        date_to : str
+            종료 날짜 (YYYYMMDD).
+        searchword : str
+            검색어.
+        target : str
+            대상 채널.
+        """
+        return await self._call_api(
+            "/minPttnStstGndrInfo5",
+            {
+                "dateFrom": date_from,
+                "dateTo": date_to,
+                "target": target,
+                "searchword": searchword,
+            },
+        )
+
+    async def get_age_stats(
+        self,
+        date_from: str,
+        date_to: str,
+        searchword: str,
+        target: str = "pttn",
+    ) -> Optional[List[Dict[str, Any]]]:
+        """연령별 통계를 조회한다.
+
+        Parameters
+        ----------
+        date_from : str
+            시작 날짜 (YYYYMMDD).
+        date_to : str
+            종료 날짜 (YYYYMMDD).
+        searchword : str
+            검색어.
+        target : str
+            대상 채널.
+        """
+        return await self._call_api(
+            "/minPttnStstAgeInfo5",
+            {
+                "dateFrom": date_from,
+                "dateTo": date_to,
+                "target": target,
+                "searchword": searchword,
+            },
+        )
+
+    async def get_population_ratio(
+        self,
+        date_from: str,
+        date_to: str,
+        top_n: int = 5,
+        target: str = "pttn,saeol,dfpt",
+        period: str = "DAILY",
+        sort_by: str = "VALUE",
+        sort_order: str = "false",
+        date_type: str = "C",
+        search_type: str = "REGION",
+    ) -> Optional[List[Dict[str, Any]]]:
+        """인구대비 민원 비율을 조회한다.
+
+        Parameters
+        ----------
+        date_from : str
+            시작 날짜 (YYYYMMDD).
+        date_to : str
+            종료 날짜 (YYYYMMDD).
+        top_n : int
+            상위 N개.
+        target : str
+            대상 채널.
+        period : str
+            기간 단위.
+        sort_by : str
+            정렬 기준.
+        sort_order : str
+            정렬 순서.
+        date_type : str
+            날짜 유형 ("C" 접수일, "R" 등록일).
+        search_type : str
+            검색 유형 ("REGION" 지역별).
+        """
+        return await self._call_api(
+            "/minMrPopltnRtInfo5",
+            {
+                "target": target,
+                "dateFrom": date_from,
+                "dateTo": date_to,
+                "dateType": date_type,
+                "topN": top_n,
+                "period": period,
+                "sortBy": sort_by,
+                "sortOrder": sort_order,
+                "searchType": search_type,
+            },
+        )

src/inference/agent_loop.py

@@ -0,0 +1,360 @@
+"""세션 기반 task loop."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, AsyncGenerator, Callable, Dict, List, Optional
+
+from loguru import logger
+
+from .query_builder import build_query_variants, build_runtime_query_context, resolve_tool_query
+from .session_context import SessionContext
+from .tool_router import ExecutionPlan, ToolName, ToolRouter, ToolStep, ToolType, tool_name
+
+
+@dataclass
+class ToolResult:
+    tool: ToolName
+    success: bool
+    data: Dict[str, Any] = field(default_factory=dict)
+    error: Optional[str] = None
+    latency_ms: float = 0.0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "tool": tool_name(self.tool),
+            "success": self.success,
+            "data": self.data,
+            "error": self.error,
+            "latency_ms": round(self.latency_ms, 2),
+        }
+
+
+@dataclass
+class AgentTrace:
+    request_id: str
+    session_id: str
+    plan: Optional[ExecutionPlan] = None
+    tool_results: List[ToolResult] = field(default_factory=list)
+    total_latency_ms: float = 0.0
+    final_text: str = ""
+    error: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "request_id": self.request_id,
+            "session_id": self.session_id,
+            "plan": self.plan.tool_names if self.plan else [],
+            "plan_reason": self.plan.reason if self.plan else "",
+            "tool_results": [result.to_dict() for result in self.tool_results],
+            "total_latency_ms": round(self.total_latency_ms, 2),
+            "error": self.error,
+        }
+
+
+ToolFunction = Callable[..., Any]
+DEFAULT_TOOL_TIMEOUT = 30.0
+
+
+class AgentLoop:
+    """GovOn MVP capability loop."""
+
+    def __init__(
+        self,
+        tool_registry: Dict[ToolName, ToolFunction],
+        router: Optional[ToolRouter] = None,
+        tool_timeout: float = DEFAULT_TOOL_TIMEOUT,
+    ) -> None:
+        self._tools = {tool_name(name): runner for name, runner in tool_registry.items()}
+        self._router = router or ToolRouter()
+        self._tool_timeout = tool_timeout
+
+    async def run(
+        self,
+        query: str,
+        session: SessionContext,
+        request_id: Optional[str] = None,
+        force_tools: Optional[List[ToolName]] = None,
+    ) -> AgentTrace:
+        rid = request_id or str(uuid.uuid4())
+        trace = AgentTrace(request_id=rid, session_id=session.session_id)
+        loop_start = time.monotonic()
+        started_at = time.time()
+
+        try:
+            session.add_turn("user", query)
+
+            has_context = bool(session.tool_runs or session.conversations)
+            plan = self._router.plan(query, has_context=has_context, force_tools=force_tools)
+            trace.plan = plan
+
+            accumulated: Dict[str, Any] = build_runtime_query_context(session, query)
+            accumulated["conversation"] = [
+                {"role": turn.role, "content": turn.content} for turn in session.recent_history[-5:]
+            ]
+            accumulated["query_variants"] = build_query_variants(
+                query,
+                tool_names=plan.tool_names,
+                context=accumulated,
+            )
+
+            for step in plan.steps:
+                result = await self._execute_tool(step, accumulated, session)
+                trace.tool_results.append(result)
+                accumulated[step.step_id] = result.data if result.success else {}
+                session.add_tool_run(
+                    tool=step.step_id,
+                    graph_run_request_id=rid,
+                    success=result.success,
+                    latency_ms=result.latency_ms,
+                    error=result.error,
+                    metadata=self._build_tool_log_metadata(result.data),
+                )
+
+            trace.final_text = self._extract_final_text(accumulated, plan)
+            session.add_turn("assistant", trace.final_text)
+
+        except Exception as exc:
+            trace.error = str(exc)
+            logger.error(f"[AgentLoop] request_id={rid} 오류: {exc}", exc_info=True)
+        finally:
+            trace.total_latency_ms = (time.monotonic() - loop_start) * 1000
+            self._record_graph_run(
+                session=session,
+                trace=trace,
+                started_at=started_at,
+                completed_at=time.time(),
+            )
+
+        return trace
+
+    async def run_stream(
+        self,
+        query: str,
+        session: SessionContext,
+        request_id: Optional[str] = None,
+        force_tools: Optional[List[ToolName]] = None,
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        rid = request_id or str(uuid.uuid4())
+        loop_start = time.monotonic()
+        started_at = time.time()
+        trace = AgentTrace(request_id=rid, session_id=session.session_id)
+
+        try:
+            session.add_turn("user", query)
+            has_context = bool(session.tool_runs or session.conversations)
+            plan = self._router.plan(query, has_context=has_context, force_tools=force_tools)
+            trace.plan = plan
+
+            yield {
+                "type": "plan",
+                "request_id": rid,
+                "plan": plan.tool_names,
+                "reason": plan.reason,
+            }
+
+            accumulated: Dict[str, Any] = build_runtime_query_context(session, query)
+            accumulated["query_variants"] = build_query_variants(
+                query,
+                tool_names=plan.tool_names,
+                context=accumulated,
+            )
+
+            for step in plan.steps:
+                yield {"type": "tool_start", "request_id": rid, "tool": step.step_id}
+                result = await self._execute_tool(step, accumulated, session)
+                trace.tool_results.append(result)
+                accumulated[step.step_id] = result.data if result.success else {}
+                session.add_tool_run(
+                    tool=step.step_id,
+                    graph_run_request_id=rid,
+                    success=result.success,
+                    latency_ms=result.latency_ms,
+                    error=result.error,
+                    metadata=self._build_tool_log_metadata(result.data),
+                )
+                yield {
+                    "type": "tool_result",
+                    "request_id": rid,
+                    "tool": step.step_id,
+                    "success": result.success,
+                    "latency_ms": round(result.latency_ms, 2),
+                    "error": result.error,
+                }
+
+            trace.final_text = self._extract_final_text(accumulated, plan)
+            session.add_turn("assistant", trace.final_text)
+            trace.total_latency_ms = (time.monotonic() - loop_start) * 1000
+            yield {
+                "type": "final",
+                "request_id": rid,
+                "text": trace.final_text,
+                "trace": trace.to_dict(),
+                "finished": True,
+            }
+
+        except Exception as exc:
+            trace.error = str(exc)
+            trace.total_latency_ms = (time.monotonic() - loop_start) * 1000
+            logger.error(f"[AgentLoop] stream request_id={rid} 오류: {exc}", exc_info=True)
+            yield {
+                "type": "error",
+                "request_id": rid,
+                "error": "에이전트 처리 중 내부 오류가 발생했습니다.",
+                "finished": True,
+            }
+        finally:
+            if trace.total_latency_ms == 0.0:
+                trace.total_latency_ms = (time.monotonic() - loop_start) * 1000
+            self._record_graph_run(
+                session=session,
+                trace=trace,
+                started_at=started_at,
+                completed_at=time.time(),
+            )
+
+    async def _execute_tool(
+        self,
+        step: ToolStep,
+        accumulated: Dict[str, Any],
+        session: SessionContext,
+    ) -> ToolResult:
+        step_name = step.step_id
+        tool_fn = self._tools.get(step_name)
+        if tool_fn is None:
+            return ToolResult(
+                tool=step.tool, success=False, error=f"등록되지 않은 tool: {step_name}"
+            )
+
+        start = time.monotonic()
+        try:
+            execution_query = resolve_tool_query(step_name, accumulated)
+            result_data = await asyncio.wait_for(
+                tool_fn(
+                    query=execution_query,
+                    context=accumulated,
+                    session=session,
+                ),
+                timeout=self._tool_timeout,
+            )
+            return ToolResult(
+                tool=step.tool,
+                success=True,
+                data=result_data if isinstance(result_data, dict) else {"result": result_data},
+                latency_ms=(time.monotonic() - start) * 1000,
+            )
+        except asyncio.TimeoutError:
+            return ToolResult(
+                tool=step.tool,
+                success=False,
+                error=f"tool {step_name} 타임아웃 ({self._tool_timeout}초)",
+                latency_ms=(time.monotonic() - start) * 1000,
+            )
+        except Exception as exc:
+            logger.error(f"[AgentLoop] tool {step_name} 실행 오류: {exc}", exc_info=True)
+            return ToolResult(
+                tool=step.tool,
+                success=False,
+                error=str(exc),
+                latency_ms=(time.monotonic() - start) * 1000,
+            )
+
+    @staticmethod
+    def _build_tool_log_metadata(data: Dict[str, Any]) -> Dict[str, Any]:
+        """tool log에 남길 작은 preview만 보관한다."""
+        metadata: Dict[str, Any] = {}
+        if "count" in data:
+            metadata["count"] = data["count"]
+        if "query" in data:
+            metadata["query"] = data["query"]
+        if "results" in data and isinstance(data["results"], list):
+            metadata["result_count"] = len(data["results"])
+        if "text" in data:
+            metadata["text_preview"] = str(data["text"])[:200]
+        return metadata
+
+    @staticmethod
+    def _build_plan_summary(plan: Optional[ExecutionPlan]) -> str:
+        if not plan:
+            return ""
+
+        tools = " -> ".join(step.step_id for step in plan.steps)
+        if plan.reason:
+            return f"{plan.reason} | tools: {tools}"
+        return tools
+
+    @staticmethod
+    def _graph_run_status(trace: AgentTrace) -> str:
+        if trace.error:
+            return "failed"
+        if any(not result.success for result in trace.tool_results):
+            return "completed_with_errors"
+        return "completed"
+
+    @classmethod
+    def _record_graph_run(
+        cls,
+        session: SessionContext,
+        trace: AgentTrace,
+        started_at: float,
+        completed_at: float,
+    ) -> None:
+        success_count = sum(1 for result in trace.tool_results if result.success)
+        failure_count = len(trace.tool_results) - success_count
+        session.add_graph_run(
+            request_id=trace.request_id,
+            plan_summary=cls._build_plan_summary(trace.plan),
+            approval_status="not_requested",
+            executed_capabilities=[tool_name(result.tool) for result in trace.tool_results],
+            status=cls._graph_run_status(trace),
+            error=trace.error,
+            total_latency_ms=trace.total_latency_ms,
+            metadata={
+                "plan_reason": trace.plan.reason if trace.plan else "",
+                "tool_result_count": len(trace.tool_results),
+                "success_count": success_count,
+                "failure_count": failure_count,
+                "final_text_preview": trace.final_text[:200],
+            },
+            started_at=started_at,
+            completed_at=completed_at,
+        )
+
+    @staticmethod
+    def _extract_final_text(accumulated: Dict[str, Any], plan: ExecutionPlan) -> str:
+        for tool_type in (ToolType.APPEND_EVIDENCE, ToolType.DRAFT_CIVIL_RESPONSE):
+            payload = accumulated.get(tool_type.value, {})
+            if isinstance(payload, dict) and payload.get("text"):
+                return str(payload["text"])
+
+        for step in plan.steps:
+            payload = accumulated.get(step.step_id, {})
+            if isinstance(payload, dict) and payload.get("text"):
+                return str(payload["text"])
+
+        parts: List[str] = []
+
+        rag_data = accumulated.get(ToolType.RAG_SEARCH.value, {})
+        if rag_data.get("results"):
+            lines = ["[로컬 문서 근거]"]
+            for item in rag_data["results"][:3]:
+                title = item.get("title", "")
+                content = item.get("content", "")[:120]
+                lines.append(f"- {title}: {content}")
+            parts.append("\n".join(lines))
+
+        api_data = accumulated.get(ToolType.API_LOOKUP.value, {})
+        if api_data.get("context_text"):
+            parts.append(api_data["context_text"])
+        elif api_data.get("results"):
+            lines = ["[외부 조회 결과]"]
+            for item in api_data["results"][:3]:
+                title = item.get("title", item.get("qnaTitle", ""))
+                content = item.get("content", item.get("qnaContent", ""))[:120]
+                lines.append(f"- {title}: {content}")
+            parts.append("\n".join(lines))
+
+        return "\n\n".join(parts) if parts else "요청을 처리할 수 없습니다."

src/inference/agent_manager.py

@@ -0,0 +1,134 @@
+"""
+Agent Manager for multi-persona prompt construction.
+
+Loads agent persona definitions from Markdown files with YAML frontmatter,
+and builds EXAONE chat template prompts with the appropriate system message.
+
+Issue: #56
+"""
+
+import os
+import re
+from typing import Dict, List, Optional
+
+import yaml
+from loguru import logger
+
+
+class AgentPersona:
+    """Parsed agent persona from a Markdown file."""
+
+    def __init__(
+        self,
+        name: str,
+        role: str,
+        description: str,
+        system_prompt: str,
+        temperature: float = 0.7,
+        max_tokens: int = 512,
+    ):
+        self.name = name
+        self.role = role
+        self.description = description
+        self.system_prompt = system_prompt
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+
+    def __repr__(self) -> str:
+        return f"AgentPersona(name={self.name!r}, role={self.role!r})"
+
+
+class AgentManager:
+    """
+    Loads and manages agent personas from Markdown files.
+
+    Each agent file uses YAML frontmatter for configuration and Markdown body
+    for the system prompt content.
+
+    Usage:
+        manager = AgentManager("agents/")
+        persona = manager.get_agent("generator_civil_response")
+        prompt = manager.build_prompt("generator_civil_response", "민원 답변 초안을 작성해주세요.")
+    """
+
+    _FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n(.*)$", re.DOTALL)
+
+    def __init__(self, agents_dir: str = "agents"):
+        self.agents_dir = agents_dir
+        self._agents: Dict[str, AgentPersona] = {}
+        self._load_agents()
+
+    _DANGEROUS_TOKENS = ["[|user|]", "[|assistant|]", "[|system|]", "[|endofturn|]"]
+
+    def _load_agents(self) -> None:
+        base_dir = os.path.realpath(self.agents_dir)
+        if not os.path.isdir(base_dir):
+            logger.warning(f"Agents directory not found: {base_dir}")
+            return
+
+        for filename in os.listdir(base_dir):
+            if not filename.endswith(".md"):
+                continue
+            filepath = os.path.realpath(os.path.join(base_dir, filename))
+            if not filepath.startswith(base_dir + os.sep):
+                logger.warning(f"경로 순회 시도 감지, 무시됨: {filename}")
+                continue
+            try:
+                agent = self._parse_agent_file(filepath)
+                self._agents[agent.name] = agent
+                logger.info(f"Loaded agent: {agent.name} ({agent.role})")
+            except Exception as e:
+                logger.error(f"Failed to load agent from {filename}: {e}")
+
+    def _parse_agent_file(self, filepath: str) -> AgentPersona:
+        with open(filepath, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        match = self._FRONTMATTER_RE.match(content)
+        if not match:
+            raise ValueError(f"Invalid agent file format (missing YAML frontmatter): {filepath}")
+
+        frontmatter = yaml.safe_load(match.group(1))
+        body = match.group(2).strip()
+
+        name = (frontmatter.get("name") or "").strip()
+        if not name or not re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", name):
+            raise ValueError(f"유효하지 않은 에이전트 이름: {name!r} in {filepath}")
+
+        return AgentPersona(
+            name=name,
+            role=frontmatter.get("role", ""),
+            description=frontmatter.get("description", ""),
+            system_prompt=body,
+            temperature=float(frontmatter.get("temperature", 0.7)),
+            max_tokens=int(frontmatter.get("max_tokens", 512)),
+        )
+
+    def get_agent(self, name: str) -> Optional[AgentPersona]:
+        return self._agents.get(name)
+
+    def list_agents(self) -> List[str]:
+        return list(self._agents.keys())
+
+    def build_prompt(self, agent_name: str, user_message: str) -> str:
+        """
+        Build an EXAONE chat template prompt with the agent's system message.
+
+        Format:
+            [|system|]{system_prompt}[|endofturn|]
+            [|user|]{user_message}[|endofturn|]
+            [|assistant|]
+        """
+        agent = self._agents.get(agent_name)
+        if agent is None:
+            raise ValueError(f"Unknown agent: {agent_name}")
+
+        for token in self._DANGEROUS_TOKENS:
+            if token in user_message:
+                raise ValueError(f"이스케이프되지 않은 특수 토큰 감지: {token}")
+
+        return (
+            f"[|system|]{agent.system_prompt}[|endofturn|]"
+            f"\n[|user|]{user_message}[|endofturn|]"
+            f"\n[|assistant|]"
+        )

src/inference/api_server.py

@@ -0,0 +1,1899 @@
+import asyncio
+import json
+import os
+import re
+import time
+import uuid
+from contextlib import asynccontextmanager
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, AsyncGenerator, Dict, List, Optional
+
+from fastapi import Depends, FastAPI, HTTPException, Request, Security
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from fastapi.security import APIKeyHeader
+from loguru import logger
+
+try:
+    from vllm import AsyncLLM, SamplingParams
+except ImportError:
+    try:
+        from vllm.engine.async_llm_engine import AsyncLLMEngine as AsyncLLM
+        from vllm.sampling_params import SamplingParams
+    except ImportError:
+        AsyncLLM = None
+        SamplingParams = None
+
+try:
+    from vllm.lora.request import LoRARequest
+except ImportError:
+    LoRARequest = None
+
+# Multi-LoRA adapter name → numeric ID 매핑 (vLLM LoRARequest에 전달)
+_LORA_ID_MAP: Dict[str, int] = {"civil": 1, "legal": 2}
+
+from .agent_loop import AgentLoop, AgentTrace
+from .agent_manager import AgentManager
+from .bm25_indexer import BM25Indexer
+from .feature_flags import FeatureFlags
+from .hybrid_search import HybridSearchEngine, SearchMode
+from .index_manager import IndexType, MultiIndexManager
+from .retriever import CivilComplaintRetriever
+from .runtime_config import RuntimeConfig
+from .schemas import (
+    AgentRunRequest,
+    AgentRunResponse,
+    AgentTraceSchema,
+    GenerateCivilResponseRequest,
+    GenerateCivilResponseResponse,
+    GenerateRequest,
+    GenerateResponse,
+    RetrievedCase,
+    SearchRequest,
+    SearchResponse,
+    SearchResult,
+    ToolResultSchema,
+)
+from .session_context import SessionContext, SessionStore
+from .tool_router import ToolType, tool_name
+
+SessionLocal = None
+LocalDocumentIndexer = None
+SKIP_MODEL_LOAD = os.getenv("SKIP_MODEL_LOAD", "false").lower() in ("true", "1", "yes")
+
+
+async def _noop_tool(query: str, context: dict, session: Any) -> dict:
+    """build_mvp_registry fallback용 no-op tool."""
+    return {"success": False, "error": "tool이 초기화되지 않았습니다"}
+
+
+if not SKIP_MODEL_LOAD:
+    try:
+        from vllm.engine.arg_utils import AsyncEngineArgs
+
+        from .vllm_stabilizer import apply_transformers_patch
+    except ImportError:
+        logger.warning("vllm modules not found. Model loading will fail if attempted.")
+        AsyncEngineArgs = object
+        apply_transformers_patch = lambda: None
+
+try:
+    from slowapi import Limiter
+    from slowapi.middleware import SlowAPIMiddleware
+    from slowapi.util import get_remote_address
+
+    limiter = Limiter(key_func=get_remote_address)
+    _RATE_LIMIT_AVAILABLE = True
+except ImportError:
+    limiter = None
+    _RATE_LIMIT_AVAILABLE = False
+
+_API_KEY = os.getenv("API_KEY")
+_api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+
+
+async def verify_api_key(api_key: str = Security(_api_key_header)):
+    if _API_KEY is None:
+        return
+    if api_key != _API_KEY:
+        raise HTTPException(status_code=401, detail="유효하지 않은 API 키입니다.")
+
+
+runtime_config = RuntimeConfig.from_env()
+runtime_config.log_summary()
+
+MODEL_PATH = runtime_config.model.model_path
+DATA_PATH = runtime_config.paths.data_path
+INDEX_PATH = runtime_config.paths.index_path
+GPU_UTILIZATION = runtime_config.gpu_utilization
+MAX_MODEL_LEN = runtime_config.max_model_len
+TRUST_REMOTE_CODE = runtime_config.model.trust_remote_code
+_PROJECT_ROOT = str(Path(__file__).resolve().parent.parent.parent)
+AGENTS_DIR = runtime_config.paths.agents_dir
+
+
+@dataclass
+class PreparedGeneration:
+    prompt: str
+    sampling_params: SamplingParams
+    retrieved_cases: List[dict]
+    search_results: List[SearchResult]
+
+
+if not SKIP_MODEL_LOAD:
+    apply_transformers_patch()
+
+
+def _extract_content_by_type(result: dict, index_type: IndexType) -> str:
+    extras = result.get("extras", {})
+    if index_type == IndexType.CASE:
+        case_text = "\n".join(
+            part
+            for part in (extras.get("complaint_text", ""), extras.get("answer_text", ""))
+            if part
+        ).strip()
+        text = case_text or extras.get("content", "") or extras.get("chunk_text", "")
+    elif index_type == IndexType.LAW:
+        text = (
+            extras.get("law_text", "") or extras.get("content", "") or extras.get("chunk_text", "")
+        )
+    elif index_type == IndexType.MANUAL:
+        text = (
+            extras.get("manual_text", "")
+            or extras.get("content", "")
+            or extras.get("chunk_text", "")
+        )
+    elif index_type == IndexType.NOTICE:
+        text = (
+            extras.get("notice_text", "")
+            or extras.get("content", "")
+            or extras.get("chunk_text", "")
+        )
+    else:
+        text = ""
+    return text or result.get("title", "")
+
+
+def _extract_approval_request(graph_state: Any) -> Any:
+    """LangGraph interrupt state에서 approval payload를 ���출한다."""
+    if not graph_state or not getattr(graph_state, "tasks", None):
+        return None
+    task = graph_state.tasks[0]
+    if not getattr(task, "interrupts", None):
+        return None
+    return task.interrupts[0].value
+
+
+class vLLMEngineManager:
+    """GovOn Shell MVP용 로컬 런타임 매니저."""
+
+    def __init__(self):
+        self.engine: AsyncLLM = None
+        self.retriever: CivilComplaintRetriever = None
+        self.index_manager: Optional[MultiIndexManager] = None
+        self.hybrid_engine: Optional[HybridSearchEngine] = None
+        self.bm25_indexers: dict[IndexType, BM25Indexer] = {}
+        self.embed_model = None
+        self.feature_flags = FeatureFlags.from_env()
+        self.session_store = SessionStore()
+        self.agent_manager = AgentManager(AGENTS_DIR)
+        self.agent_loop: Optional[AgentLoop] = None
+        self.graph = None  # LangGraph CompiledGraph (v2 엔드포인트용)
+        self.local_document_indexer: Optional[Any] = None
+        self.local_document_sync_status: Optional[Dict[str, Any]] = None
+        self._local_document_sync_task: Optional[asyncio.Task] = None
+        self._checkpointer_ctx = None  # AsyncSqliteSaver 컨텍스트 매니저 (lifespan에서 관리)
+        self._sync_checkpointer_conn = None  # SqliteSaver용 sqlite3 connection (leak 방지)
+        self._init_agent_loop()
+        self._init_graph()
+
+    async def initialize(self):
+        if SKIP_MODEL_LOAD:
+            logger.info("SKIP_MODEL_LOAD=true: 모델 및 인덱스 로딩을 건너뜁니다.")
+            return
+
+        logger.info(f"Initializing vLLM runtime with model: {MODEL_PATH}")
+        # EXAONE 4.0-32B-AWQ 네이티브 tool calling 활성화:
+        #   --enable-auto-tool-choice --tool-call-parser hermes
+        # Multi-LoRA 서빙 시 --enable-lora --lora-modules 옵션 추가
+        # HuggingFace Spaces L4 (24GB VRAM) 기준 ~20GB 점유
+        try:
+            engine_kwargs = dict(
+                model=MODEL_PATH,
+                trust_remote_code=TRUST_REMOTE_CODE,
+                gpu_memory_utilization=GPU_UTILIZATION,
+                max_model_len=MAX_MODEL_LEN,
+                dtype=runtime_config.model.dtype,
+                enforce_eager=runtime_config.model.enforce_eager,
+            )
+            # Multi-LoRA 서빙: adapter_paths가 설정되어 있으면 활성화
+            lora_enabled = bool(runtime_config.model.adapter_paths)
+            if lora_enabled:
+                engine_kwargs.update(
+                    enable_lora=True,
+                    max_loras=4,
+                    max_lora_rank=64,
+                )
+                logger.info(
+                    f"Multi-LoRA 활성화: adapters={list(runtime_config.model.adapter_paths.keys())}"
+                )
+            engine_args = AsyncEngineArgs(**engine_kwargs)
+            if hasattr(AsyncLLM, "from_engine_args"):
+                self.engine = AsyncLLM.from_engine_args(engine_args)
+            else:
+                self.engine = AsyncLLM(engine_args)
+        except Exception as exc:
+            logger.error(f"vLLM 엔진 초기화 실패: {exc}")
+            raise
+
+        logger.info(f"Initializing retriever with index: {INDEX_PATH}")
+        self.retriever = CivilComplaintRetriever(
+            index_path=INDEX_PATH if os.path.exists(INDEX_PATH) else None,
+            data_path=DATA_PATH if not os.path.exists(INDEX_PATH) else None,
+        )
+        if self.retriever.index is not None and not os.path.exists(INDEX_PATH):
+            self.retriever.save_index(INDEX_PATH)
+
+        faiss_index_dir = runtime_config.paths.faiss_index_dir
+        local_docs_root = runtime_config.paths.local_docs_root
+        if os.path.isdir(faiss_index_dir) or local_docs_root:
+            self.index_manager = MultiIndexManager(base_dir=faiss_index_dir)
+            logger.info(f"MultiIndexManager 초기화 완료: {faiss_index_dir}")
+        else:
+            logger.warning(f"FAISS 인덱스 디렉터리 미존재: {faiss_index_dir}")
+
+        bm25_index_dir = os.getenv("BM25_INDEX_DIR", "models/bm25_index")
+        if os.path.isdir(bm25_index_dir):
+            for idx_type in IndexType:
+                bm25_path = os.path.join(bm25_index_dir, f"{idx_type.value}.pkl")
+                if not os.path.exists(bm25_path):
+                    continue
+                try:
+                    indexer = BM25Indexer()
+                    indexer.load(bm25_path)
+                    self.bm25_indexers[idx_type] = indexer
+                    logger.info(f"BM25 인덱스 로드 완료: {idx_type.value} ({indexer.doc_count}건)")
+                except Exception as exc:
+                    logger.warning(f"BM25 인덱스 로드 실패 ({idx_type.value}): {exc}")
+
+        if self.retriever and hasattr(self.retriever, "model"):
+            self.embed_model = self.retriever.model
+
+        if self.index_manager and self.embed_model:
+            self.hybrid_engine = HybridSearchEngine(
+                index_manager=self.index_manager,
+                bm25_indexers=self.bm25_indexers,
+                embed_model=self.embed_model,
+            )
+            logger.info("HybridSearchEngine 초기화 완료")
+            self._schedule_local_document_sync()
+        else:
+            logger.warning("HybridSearchEngine 미초기화: index_manager 또는 embed_model 없음")
+
+    def _schedule_local_document_sync(self) -> None:
+        indexer = self._build_local_document_indexer()
+        if indexer is None:
+            return
+        if self._local_document_sync_task and not self._local_document_sync_task.done():
+            return
+
+        self.local_document_sync_status = {
+            "status": "syncing",
+            "root_dir": str(indexer.root_dir),
+            "source_name": indexer.source_name,
+        }
+        self._local_document_sync_task = asyncio.create_task(self._sync_local_documents_async())
+
+    async def _sync_local_documents_async(self) -> Optional[Dict[str, Any]]:
+        try:
+            return await asyncio.to_thread(self.sync_local_documents)
+        except Exception as exc:
+            logger.error(f"백그라운드 로컬 문서 인덱싱 실패: {exc}", exc_info=True)
+            if self.local_document_indexer is None:
+                return None
+            self.local_document_sync_status = {
+                "status": "error",
+                "root_dir": str(self.local_document_indexer.root_dir),
+                "source_name": self.local_document_indexer.source_name,
+                "error": str(exc),
+            }
+            return self.local_document_sync_status
+
+    def _build_local_document_indexer(self) -> Optional[Any]:
+        global SessionLocal, LocalDocumentIndexer
+
+        root_dir = runtime_config.paths.local_docs_root
+        if not root_dir:
+            return None
+        if self.index_manager is None or self.embed_model is None:
+            logger.warning(
+                "LOCAL_DOCS_ROOT가 설정됐지만 index_manager 또는 embed_model이 없습니다."
+            )
+            return None
+        if self.local_document_indexer is None:
+            if SessionLocal is None:
+                from .db.database import SessionLocal as _SessionLocal
+
+                SessionLocal = _SessionLocal
+            if LocalDocumentIndexer is None:
+                from .local_document_indexer import LocalDocumentIndexer as _LocalDocumentIndexer
+
+                LocalDocumentIndexer = _LocalDocumentIndexer
+
+            self.local_document_indexer = LocalDocumentIndexer(
+                root_dir=root_dir,
+                index_manager=self.index_manager,
+                embed_model=self.embed_model,
+                session_factory=SessionLocal,
+            )
+        return self.local_document_indexer
+
+    def sync_local_documents(self) -> Optional[Dict[str, Any]]:
+        indexer = self._build_local_document_indexer()
+        if indexer is None:
+            return None
+
+        try:
+            summary = indexer.sync()
+        except Exception as exc:
+            logger.error(f"로컬 문서 인덱싱 실패: {exc}", exc_info=True)
+            self.local_document_sync_status = {
+                "status": "error",
+                "root_dir": str(indexer.root_dir),
+                "source_name": indexer.source_name,
+                "error": str(exc),
+            }
+            return self.local_document_sync_status
+
+        self.local_document_sync_status = {
+            "status": "ok",
+            "root_dir": str(indexer.root_dir),
+            "source_name": indexer.source_name,
+            **asdict(summary),
+        }
+        logger.info(
+            "로컬 문서 인덱싱 완료: "
+            f"root={indexer.root_dir}, scanned={summary.scanned_files}, "
+            f"indexed={summary.indexed_files}, unchanged={summary.unchanged_files}, "
+            f"removed={summary.removed_files}"
+        )
+        return self.local_document_sync_status
+
+    def _escape_special_tokens(self, text: str) -> str:
+        tokens = [
+            "[|user|]",
+            "[|assistant|]",
+            "[|system|]",
+            "[|endofturn|]",
+            "<thought>",
+            "</thought>",
+        ]
+        for token in tokens:
+            text = text.replace(
+                token,
+                token.replace("[", "\\[")
+                .replace("]", "\\]")
+                .replace("<", "\\<")
+                .replace(">", "\\>"),
+            )
+        return text
+
+    @staticmethod
+    def _strip_thought_blocks(text: str) -> str:
+        return re.sub(r"<thought>.*?</thought>\s*", "", text, flags=re.DOTALL).strip()
+
+    def _build_rag_context(self, retrieved_cases: List[dict]) -> str:
+        if not retrieved_cases:
+            return ""
+        rag_context = "### 참고 사례 (유사 민원 및 답변):\n"
+        for i, case in enumerate(retrieved_cases, start=1):
+            complaint = self._escape_special_tokens(case.get("complaint", ""))
+            answer = self._escape_special_tokens(case.get("answer", ""))
+            rag_context += f"{i}. [민원]: {complaint}\n   [답변]: {answer}\n\n"
+        return rag_context
+
+    def _augment_prompt(self, prompt: str, retrieved_cases: List[dict]) -> str:
+        rag_context = self._build_rag_context(retrieved_cases)
+        if not rag_context:
+            return prompt
+        user_tag = "[|user|]"
+        if user_tag in prompt:
+            return prompt.replace(user_tag, f"{user_tag}{rag_context}\n", 1)
+        return f"{rag_context}\n{prompt}"
+
+    def _build_search_result_context(self, search_results: List[SearchResult], heading: str) -> str:
+        if not search_results:
+            return ""
+
+        lines = [heading]
+        for index, result in enumerate(search_results, start=1):
+            safe_title = self._escape_special_tokens(result.title)
+            safe_content = self._escape_special_tokens(result.content[:300])
+            lines.append(f"{index}. [{result.source_type.value}] {safe_title}")
+            lines.append(f"   근거: {safe_content}")
+        return "\n".join(lines)
+
+    def _build_persona_prompt(self, agent_name: str, user_message: str) -> str:
+        if self.agent_manager and self.agent_manager.get_agent(agent_name):
+            return self.agent_manager.build_prompt(agent_name, user_message)
+        return user_message
+
+    def _extract_query(self, prompt: str) -> str:
+        user_match = re.search(r"\[\|user\|\](.*?)\[\|endofturn\|\]", prompt, re.DOTALL)
+        if user_match:
+            user_block = user_match.group(1)
+            complaint_match = re.search(r"민원\s*내용\s*:\s*(.+)", user_block, re.DOTALL)
+            if complaint_match:
+                return complaint_match.group(1).strip()
+            return user_block.strip()
+        return prompt
+
+    def _search_results_to_cases(self, search_results: List[SearchResult]) -> List[dict]:
+        retrieved_cases: List[dict] = []
+        for result in search_results:
+            if result.source_type != IndexType.CASE:
+                continue
+            metadata = result.metadata or {}
+            complaint = (
+                metadata.get("complaint_text") or metadata.get("complaint") or result.content
+            )
+            answer = metadata.get("answer_text") or metadata.get("answer") or result.content
+            retrieved_cases.append(
+                {
+                    "id": result.doc_id,
+                    "category": metadata.get("category", ""),
+                    "complaint": complaint,
+                    "answer": answer,
+                    "score": result.score,
+                }
+            )
+        return retrieved_cases
+
+    @staticmethod
+    def _is_evidence_request(query: str) -> bool:
+        return any(token in query for token in ("근거", "출처", "왜", "이유", "링크"))
+
+    @staticmethod
+    def _is_revision_request(query: str) -> bool:
+        return any(token in query for token in ("다시", "수정", "고쳐", "정중", "공손", "보강"))
+
+    def _latest_prior_turns(
+        self,
+        session: SessionContext,
+        current_query: str,
+    ) -> tuple[Optional[str], Optional[str]]:
+        turns = list(session.recent_history)
+        if turns and turns[-1].role == "user" and turns[-1].content == current_query:
+            turns = turns[:-1]
+
+        previous_user = next(
+            (turn.content for turn in reversed(turns) if turn.role == "user"), None
+        )
+        previous_assistant = next(
+            (turn.content for turn in reversed(turns) if turn.role == "assistant"),
+            None,
+        )
+        return previous_user, previous_assistant
+
+    def _build_working_query(self, query: str, session: SessionContext) -> str:
+        query = query.strip()
+        if not query:
+            return query
+
+        if not (self._is_evidence_request(query) or self._is_revision_request(query)):
+            return query
+
+        previous_user, previous_assistant = self._latest_prior_turns(session, query)
+        parts: List[str] = []
+        if previous_user:
+            parts.append(f"원래 요청: {previous_user}")
+        if previous_assistant:
+            parts.append(f"이전 답변: {previous_assistant[:600]}")
+
+        if self._is_revision_request(query):
+            parts.append(f"수정 요청: {query}")
+
+        return "\n\n".join(parts) if parts else query
+
+    async def _retrieve_search_results(
+        self,
+        query: str,
+        index_types: List[IndexType],
+        top_k_per_type: int = 2,
+    ) -> List[SearchResult]:
+        if not query.strip():
+            return []
+
+        collected: List[SearchResult] = []
+
+        if self.hybrid_engine:
+
+            async def _search_index(index_type: IndexType) -> List[SearchResult]:
+                results_raw, _ = await self.hybrid_engine.search(
+                    query=query,
+                    index_type=index_type,
+                    top_k=top_k_per_type,
+                    mode=SearchMode.HYBRID,
+                )
+                return [
+                    SearchResult(
+                        doc_id=item.get("doc_id", ""),
+                        source_type=IndexType(item.get("doc_type", index_type.value)),
+                        title=item.get("title", ""),
+                        content=_extract_content_by_type(item, index_type),
+                        score=item.get("score", 0.0),
+                        reliability_score=item.get("reliability_score", 1.0),
+                        metadata=item.get("extras", {}),
+                        chunk_index=item.get("chunk_index", 0),
+                        total_chunks=item.get("chunk_total", 1),
+                    )
+                    for item in results_raw
+                ]
+
+            grouped = await asyncio.gather(
+                *[_search_index(index_type) for index_type in index_types],
+                return_exceptions=True,
+            )
+            for result in grouped:
+                if isinstance(result, BaseException):
+                    logger.warning(f"로컬 검색 실패: {result}")
+                    continue
+                collected.extend(result)
+
+        elif self.retriever and IndexType.CASE in index_types:
+            for raw in self.retriever.search(query, top_k=max(3, top_k_per_type)):
+                collected.append(
+                    SearchResult(
+                        doc_id=raw.get("id", raw.get("doc_id", "")),
+                        source_type=IndexType.CASE,
+                        title=raw.get("category", "유사 민원 사례"),
+                        content=(raw.get("complaint", "") + "\n" + raw.get("answer", "")).strip(),
+                        score=raw.get("score", 0.0),
+                        reliability_score=raw.get("reliability_score", 1.0),
+                        metadata={
+                            "complaint": raw.get("complaint", ""),
+                            "answer": raw.get("answer", ""),
+                            "category": raw.get("category", ""),
+                        },
+                    )
+                )
+
+        return collected
+
+    @staticmethod
+    def _format_evidence_items(evidence_dict: Dict[str, Any]) -> str:
+        """EvidenceEnvelope dict를 소비하여 출처 목록 텍스트를 생성한다.
+
+        EvidenceItem이 있으면 source-specific branching 없이 단일 포매터로 처리한다.
+        """
+        items = evidence_dict.get("items", [])
+        if not items:
+            return ""
+
+        lines: list[str] = []
+        for idx, item in enumerate(items[:10], start=1):
+            source_type = item.get("source_type", "")
+            title = item.get("title", "")
+            link = item.get("link_or_path", "")
+            page = item.get("page")
+
+            if source_type == "rag":
+                loc = link or title or "로컬 문서"
+                if page:
+                    lines.append(f"[{idx}] {loc} (p.{page})")
+                else:
+                    lines.append(f"[{idx}] {loc}")
+            elif source_type == "api":
+                label = title or "외부 API 결과"
+                if link:
+                    lines.append(f"[{idx}] {label} - {link}")
+                else:
+                    lines.append(f"[{idx}] {label}")
+            else:
+                label = title or "생성 참조"
+                if link:
+                    lines.append(f"[{idx}] {label} - {link}")
+                else:
+                    lines.append(f"[{idx}] {label}")
+
+        return "\n".join(lines)
+
+    def _summarize_evidence(
+        self,
+        search_results: List[SearchResult],
+        api_lookup_data: Dict[str, Any],
+    ) -> str:
+        # EvidenceEnvelope가 있으면 우선 사용
+        evidence = api_lookup_data.get("evidence")
+        if isinstance(evidence, dict) and evidence.get("items"):
+            lines = ["근거 요약"]
+            rag_items = [i for i in evidence["items"] if i.get("source_type") == "rag"]
+            api_items = [i for i in evidence["items"] if i.get("source_type") == "api"]
+            if rag_items:
+                titles = ", ".join(i["title"] for i in rag_items[:3] if i.get("title"))
+                lines.append(
+                    f"- 로컬 문서 {len(rag_items)}건을 참고했습니다."
+                    + (f" 주요 문서: {titles}" if titles else "")
+                )
+            if api_items:
+                titles = ", ".join(i["title"] for i in api_items[:3] if i.get("title"))
+                lines.append(
+                    f"- 외부 민원분석 API에서 유사 사례 {len(api_items)}건을 확인했습니다."
+                    + (f" 대표 사례: {titles}" if titles else "")
+                )
+            if len(lines) == 1:
+                lines.append(
+                    "- 내부 검색 결과를 충분히 확보하지 못해 일반 행정 응대 원칙 기준으로 작성했습니다."
+                )
+            return "\n".join(lines)
+
+        # Legacy 포매터 (EvidenceItem 없을 때)
+        lines = ["근거 요약"]
+
+        if search_results:
+            titles = ", ".join(result.title for result in search_results[:3] if result.title)
+            lines.append(
+                f"- 로컬 문서 {len(search_results)}건을 참고했습니다."
+                + (f" 주요 문서: {titles}" if titles else "")
+            )
+
+        api_results = api_lookup_data.get("results", [])
+        if api_results:
+            titles = []
+            for item in api_results[:3]:
+                title = item.get("title") or item.get("qnaTitle") or item.get("question")
+                if title:
+                    titles.append(title)
+            lines.append(
+                f"- 외부 민원분석 API에서 유사 사례 {len(api_results)}건을 확인했습니다."
+                + (f" 대표 사례: {', '.join(titles)}" if titles else "")
+            )
+
+        if len(lines) == 1:
+            lines.append(
+                "- 내부 검색 결과를 충분히 확보하지 못해 일반 행정 응대 원칙 기준으로 작성했습니다."
+            )
+
+        return "\n".join(lines)
+
+    @staticmethod
+    def _rag_source_line(index: int, item: Dict[str, Any]) -> str:
+        metadata = item.get("metadata", {}) or {}
+        location = (
+            metadata.get("file_path")
+            or metadata.get("source_path")
+            or metadata.get("path")
+            or metadata.get("source")
+            or item.get("title")
+            or item.get("doc_id")
+            or "로컬 문서"
+        )
+        page = metadata.get("page") or metadata.get("page_number") or metadata.get("page_no")
+        if page:
+            return f"[{index}] {location} (p.{page})"
+        return f"[{index}] {location}"
+
+    @staticmethod
+    def _api_source_line(index: int, item: Dict[str, Any]) -> str:
+        title = item.get("title") or item.get("qnaTitle") or item.get("question") or "외부 API 결과"
+        url = item.get("url") or item.get("detailUrl") or ""
+        if url:
+            return f"[{index}] {title} - {url}"
+        return f"[{index}] {title}"
+
+    def _build_evidence_section(
+        self,
+        session: SessionContext,
+        current_query: str,
+        rag_data: Dict[str, Any],
+        api_data: Dict[str, Any],
+    ) -> str:
+        _, previous_answer = self._latest_prior_turns(session, current_query)
+        lines = ["근거/출처"]
+        cursor = 1
+
+        # EvidenceEnvelope가 있으면 단일 포매터로 우선 처리
+        rag_evidence = rag_data.get("evidence")
+        api_evidence = api_data.get("evidence")
+
+        if rag_evidence and isinstance(rag_evidence, dict) and rag_evidence.get("items"):
+            for item in rag_evidence["items"][:5]:
+                source_type = item.get("source_type", "rag")
+                if source_type == "rag":
+                    link = item.get("link_or_path", "")
+                    page = item.get("page")
+                    loc = link or item.get("title", "") or "로컬 문서"
+                    if page:
+                        lines.append(f"[{cursor}] {loc} (p.{page})")
+                    else:
+                        lines.append(f"[{cursor}] {loc}")
+                    cursor += 1
+        else:
+            # Legacy RAG 포매터
+            for item in rag_data.get("results", [])[:5]:
+                lines.append(self._rag_source_line(cursor, item))
+                cursor += 1
+
+        if api_evidence and isinstance(api_evidence, dict) and api_evidence.get("items"):
+            for item in api_evidence["items"][:5]:
+                title = item.get("title", "") or "외부 API 결과"
+                link = item.get("link_or_path", "")
+                if link:
+                    lines.append(f"[{cursor}] {title} - {link}")
+                else:
+                    lines.append(f"[{cursor}] {title}")
+                cursor += 1
+        else:
+            # Legacy API 포매터
+            api_items = api_data.get("citations") or api_data.get("results") or []
+            for item in api_items[:5]:
+                lines.append(self._api_source_line(cursor, item))
+                cursor += 1
+
+        if cursor == 1:
+            lines.append("- 검색 가능한 근거를 찾지 못했습니다.")
+
+        section = "\n".join(lines)
+        if previous_answer:
+            return f"{previous_answer}\n\n{section}"
+        return section
+
+    async def _prepare_civil_response_generation(
+        self,
+        request: GenerateCivilResponseRequest,
+        flags: Optional[FeatureFlags] = None,
+        external_cases: Optional[List[dict]] = None,
+    ) -> PreparedGeneration:
+        effective_flags = flags or self.feature_flags
+        query = self._escape_special_tokens(self._extract_query(request.prompt))
+        search_results: List[SearchResult] = []
+
+        if request.use_rag and effective_flags.use_rag_pipeline:
+            search_results = await self._retrieve_search_results(
+                query,
+                [IndexType.CASE, IndexType.LAW, IndexType.MANUAL, IndexType.NOTICE],
+            )
+
+        retrieved_cases = self._search_results_to_cases(search_results)
+        if external_cases:
+            retrieved_cases.extend(external_cases)
+
+        safe_message = self._escape_special_tokens(request.prompt)
+        sections = []
+        if search_results:
+            sections.append(
+                self._build_search_result_context(
+                    search_results,
+                    "### 민원 답변 참고 자료 (사례/법률/매뉴얼/공시정보):",
+                )
+            )
+        if retrieved_cases:
+            sections.append(self._build_rag_context(retrieved_cases[:5]))
+        sections.append(
+            "위 근거를 바탕으로 민원인의 불편에 공감하고, 현재 조치 상황과 처리 절차를 포함한 회신 초안을 작성하세요."
+        )
+        sections.append(safe_message)
+        augmented_prompt = self._build_persona_prompt(
+            "generator_civil_response",
+            "\n\n".join(section for section in sections if section),
+        )
+
+        gen_defaults = runtime_config.generation
+        sampling_params = SamplingParams(
+            temperature=request.temperature,
+            top_p=request.top_p,
+            max_tokens=request.max_tokens,
+            stop=request.stop or gen_defaults.stop_sequences,
+            repetition_penalty=gen_defaults.repetition_penalty,
+        )
+
+        return PreparedGeneration(
+            prompt=augmented_prompt,
+            sampling_params=sampling_params,
+            retrieved_cases=retrieved_cases[:5],
+            search_results=search_results,
+        )
+
+    async def _run_engine(
+        self,
+        prompt: str,
+        sampling_params: SamplingParams,
+        request_id: str,
+        lora_request=None,
+    ):
+        if self.engine is None:
+            return None
+
+        result = self.engine.generate(
+            prompt, sampling_params, request_id, lora_request=lora_request
+        )
+        if hasattr(result, "__aiter__"):
+            final_output = None
+            async for output in result:
+                final_output = output
+            return final_output
+        return await result
+
+    async def generate(
+        self,
+        request: GenerateRequest,
+        request_id: str,
+        flags: Optional[FeatureFlags] = None,
+    ) -> tuple[Any, List[dict]]:
+        output, retrieved_cases, _ = await self.generate_civil_response(request, request_id, flags)
+        return output, retrieved_cases
+
+    async def generate_civil_response(
+        self,
+        request: GenerateCivilResponseRequest,
+        request_id: str,
+        flags: Optional[FeatureFlags] = None,
+        external_cases: Optional[List[dict]] = None,
+        lora_request=None,
+    ) -> tuple[Any, List[dict], List[SearchResult]]:
+        prepared = await self._prepare_civil_response_generation(request, flags, external_cases)
+        output = await self._run_engine(
+            prepared.prompt, prepared.sampling_params, request_id, lora_request=lora_request
+        )
+        return output, prepared.retrieved_cases, prepared.search_results
+
+    async def generate_stream(
+        self,
+        request: GenerateRequest,
+        request_id: str,
+        flags: Optional[FeatureFlags] = None,
+    ) -> tuple[Any, List[dict], List[SearchResult]]:
+        prepared = await self._prepare_civil_response_generation(request, flags)
+        if self.engine is None:
+            raise RuntimeError("모델 엔진이 초기화되지 않았습니다.")
+        if hasattr(self.engine, "stream"):
+            stream = self.engine.stream(prepared.prompt, prepared.sampling_params, request_id)
+        else:
+            stream = self.engine.generate(prepared.prompt, prepared.sampling_params, request_id)
+        return stream, prepared.retrieved_cases, prepared.search_results
+
+    def _init_agent_loop(self) -> None:
+        from src.inference.actions.data_go_kr import MinwonAnalysisAction
+
+        engine_ref = self
+        minwon_action = MinwonAnalysisAction()
+
+        async def _rag_search_tool(query: str, context: dict, session: SessionContext) -> dict:
+            working_query = query.strip()
+            search_results = await engine_ref._retrieve_search_results(
+                working_query,
+                [IndexType.CASE, IndexType.LAW, IndexType.MANUAL, IndexType.NOTICE],
+            )
+            return {
+                "query": working_query,
+                "count": len(search_results),
+                "results": [result.model_dump() for result in search_results],
+                "context_text": engine_ref._build_search_result_context(
+                    search_results,
+                    "### 로컬 문서 검색 결과:",
+                ),
+            }
+
+        async def _api_lookup_tool(query: str, context: dict, session: SessionContext) -> dict:
+            working_query = query.strip()
+            payload = await minwon_action.fetch_similar_cases(
+                working_query,
+                {
+                    **context,
+                    "session_context": session.build_context_summary(),
+                },
+            )
+            results = payload["results"] or []
+            return {
+                "query": payload["query"],
+                "count": len(results),
+                "results": results,
+                "context_text": payload["context_text"],
+                "citations": [citation.to_dict() for citation in payload["citations"]],
+                "source": "data.go.kr",
+            }
+
+        async def _draft_civil_response_tool(
+            query: str,
+            context: dict,
+            session: SessionContext,
+        ) -> dict:
+            working_query = engine_ref._build_working_query(query, session)
+            api_lookup_data = context.get(ToolType.API_LOOKUP.value, {})
+
+            external_cases = []
+            for item in api_lookup_data.get("results", [])[:3]:
+                complaint = (
+                    item.get("content") or item.get("qnaContent") or item.get("question", "")
+                )
+                answer = item.get("answer") or item.get("qnaAnswer") or item.get("title", "")
+                if complaint or answer:
+                    external_cases.append(
+                        {
+                            "complaint": complaint,
+                            "answer": answer,
+                            "score": float(item.get("score", 0.0)),
+                        }
+                    )
+
+            # Multi-LoRA: civil 어댑터가 설정되어 있으면 LoRARequest 생성
+            civil_adapter_path = runtime_config.model.adapter_paths.get("civil")
+            lora_req = None
+            if civil_adapter_path and LoRARequest is not None:
+                lora_req = LoRARequest("civil", _LORA_ID_MAP["civil"], civil_adapter_path)
+
+            gen_request = GenerateCivilResponseRequest(
+                prompt=working_query,
+                max_tokens=512,
+                temperature=0.7,
+                use_rag=True,
+            )
+            request_id = str(uuid.uuid4())
+            final_output, retrieved_cases, search_results = (
+                await engine_ref.generate_civil_response(
+                    gen_request,
+                    request_id,
+                    external_cases=external_cases,
+                    lora_request=lora_req,
+                )
+            )
+            if final_output is None:
+                return {"text": "", "error": "민원 답변 생성 실패"}
+
+            draft_text = engine_ref._strip_thought_blocks(final_output.outputs[0].text)
+            text = (
+                engine_ref._summarize_evidence(search_results, api_lookup_data)
+                + "\n\n최종 초안\n"
+                + draft_text
+            )
+            return {
+                "text": text,
+                "draft_text": draft_text,
+                "retrieved_cases": retrieved_cases,
+                "search_results": [result.model_dump() for result in search_results],
+                "prompt_tokens": len(final_output.prompt_token_ids),
+                "completion_tokens": len(final_output.outputs[0].token_ids),
+            }
+
+        async def _append_evidence_tool(
+            query: str,
+            context: dict,
+            session: SessionContext,
+        ) -> dict:
+            rag_data = context.get(ToolType.RAG_SEARCH.value, {})
+            api_data = context.get(ToolType.API_LOOKUP.value, {})
+
+            # 기존 evidence 텍스트 (fallback용)
+            fallback_text = engine_ref._build_evidence_section(session, query, rag_data, api_data)
+
+            # LLM으로 evidence 보강 시도
+            enhanced_text = fallback_text
+            if engine_ref.engine is not None:
+                try:
+                    _, previous_answer = engine_ref._latest_prior_turns(session, query)
+                    existing_response = engine_ref._escape_special_tokens(previous_answer or "")
+                    rag_context = engine_ref._escape_special_tokens(
+                        rag_data.get("context_text", "")
+                    )
+                    api_context = ""
+                    for item in api_data.get("results", [])[:3]:
+                        title = item.get("title", "")
+                        content = item.get("content", "") or item.get("qnaContent", "")
+                        if title or content:
+                            api_context += (
+                                f"- {engine_ref._escape_special_tokens(title)}"
+                                f": {engine_ref._escape_special_tokens(content[:200])}\n"
+                            )
+
+                    evidence_prompt = (
+                        "[|system|]당신은 대한민국 공무원 민원 답변 보강 전문가입니다. "
+                        "법적 근거와 관련 규정을 정확하게 인용하여 evidence 섹션을 작성하세요."
+                        "[|endofturn|]\n"
+                        "[|user|]다음 민원 답변��� 대해 법적 근거와 관련 규정을 보강하여 "
+                        "evidence 섹션을 작성하세요.\n\n"
+                        f"[기존 답변]\n{existing_response[:800]}\n\n"
+                        f"[검색 결과]\n{rag_context[:800]}\n\n"
+                        f"[API 조회 결과]\n{api_context[:800]}"
+                        "[|endofturn|]\n[|assistant|]"
+                    )
+
+                    # legal 어댑터 LoRA 설정
+                    legal_adapter_path = runtime_config.model.adapter_paths.get("legal")
+                    lora_req = None
+                    if legal_adapter_path and LoRARequest is not None:
+                        lora_req = LoRARequest("legal", _LORA_ID_MAP["legal"], legal_adapter_path)
+
+                    if SamplingParams is not None:
+                        sp = SamplingParams(
+                            max_tokens=512,
+                            temperature=0.5,
+                            top_p=0.9,
+                            stop=["[|endofturn|]"],
+                        )
+                        request_id = str(uuid.uuid4())
+                        output = await engine_ref._run_engine(
+                            evidence_prompt, sp, request_id, lora_request=lora_req
+                        )
+                        if output is not None and output.outputs:
+                            enhanced_text = engine_ref._strip_thought_blocks(output.outputs[0].text)
+                except Exception as exc:
+                    logger.warning(f"Evidence LLM 보강 실패, fallback 사용: {exc}")
+                    enhanced_text = fallback_text
+
+            return {
+                "text": enhanced_text,
+                "rag_results": rag_data.get("results", []),
+                "api_citations": api_data.get("citations", []),
+            }
+
+        tool_registry = {
+            ToolType.RAG_SEARCH: _rag_search_tool,
+            ToolType.API_LOOKUP: _api_lookup_tool,
+            ToolType.DRAFT_CIVIL_RESPONSE: _draft_civil_response_tool,
+            ToolType.APPEND_EVIDENCE: _append_evidence_tool,
+        }
+        self.agent_loop = AgentLoop(tool_registry=tool_registry)
+
+    def _build_tool_registry(self) -> Dict[str, Any]:
+        """CapabilityBase 기반 MVP tool registry를 반환한다.
+
+        build_mvp_registry()를 사용하여 단일 소스에서 registry를 구성한다.
+        planner metadata와 executor binding이 동일한 CapabilityBase 인스턴스에서 나온다.
+        AgentLoop 하위호환: AgentLoop._tools에서 closure를 추출하여 wrapper로 래핑한다.
+        """
+        if self.agent_loop is None:
+            return {}
+
+        from src.inference.graph.capabilities.registry import build_mvp_registry
+
+        # AgentLoop의 tool_registry에서 기존 closure를 추출
+        raw_tools = {
+            str(k.value if hasattr(k, "value") else k): v for k, v in self.agent_loop._tools.items()
+        }
+
+        return build_mvp_registry(
+            rag_search_fn=raw_tools.get("rag_search", _noop_tool),
+            api_lookup_action=self._get_api_lookup_action(),
+            draft_civil_response_fn=raw_tools.get("draft_civil_response", _noop_tool),
+            append_evidence_fn=raw_tools.get("append_evidence", _noop_tool),
+        )
+
+    def _get_api_lookup_action(self) -> Any:
+        """AgentLoop에 등록된 api_lookup의 MinwonAnalysisAction을 추출한다."""
+        if self.agent_loop is None:
+            return None
+        tool_fn = self.agent_loop._tools.get(ToolType.API_LOOKUP)
+        # ApiLookupCapability인 경우 action을 직접 추출
+        if hasattr(tool_fn, "_action"):
+            return tool_fn._action
+        # closure인 경우 action을 추출할 수 없으므로 None 반환
+        # (MinwonAnalysisAction은 _init_agent_loop에서 새로 생성한다)
+        try:
+            from src.inference.actions.data_go_kr import MinwonAnalysisAction
+
+            return MinwonAnalysisAction()
+        except Exception:
+            return None
+
+    def _init_graph_with_async_checkpointer(self, checkpointer: object) -> None:
+        """lifespan에서 AsyncSqliteSaver가 준비된 후 graph를 재구성한다."""
+        self._init_graph(checkpointer=checkpointer)
+
+    def _init_graph(self, checkpointer: Optional[object] = None) -> None:
+        """LangGraph StateGraph를 초기화한다.
+
+        운영 환경에서는 LLMPlannerAdapter(vLLM OpenAI-compatible endpoint)를 사용한다.
+        SKIP_MODEL_LOAD=true 환경(CI/테스트)에서는 RegexPlannerAdapter가 CI fallback으로 동작한다.
+        RegistryExecutorAdapter는 기존 tool_registry를 재사용한다.
+
+        Parameters
+        ----------
+        checkpointer : optional
+            외부에서 주입할 LangGraph checkpointer.
+            None이면 SqliteSaver(동기 sqlite3)를 시도하고,
+            import 실패 시 MemorySaver로 fallback한다.
+            SqliteSaver DB 경로는 SessionStore DB와 같은 디렉터리에
+            ``langgraph_checkpoints.db``로 생성된다 (관심사 분리).
+        """
+        try:
+            from src.inference.graph.builder import build_govon_graph
+            from src.inference.graph.executor_adapter import RegistryExecutorAdapter
+            from src.inference.graph.planner_adapter import LLMPlannerAdapter
+        except ImportError as exc:
+            logger.warning(f"LangGraph graph 초기화 실패 (import 오류): {exc}")
+            return
+
+        tool_registry = self._build_tool_registry()
+
+        if SKIP_MODEL_LOAD:
+            # CI/테스트 환경: LLM이 없으므로 RegexPlannerAdapter를 CI fallback으로 사용
+            from src.inference.graph.planner_adapter import RegexPlannerAdapter
+
+            planner = RegexPlannerAdapter(registry=tool_registry)
+        else:
+            # 운영 환경: vLLM OpenAI-compatible endpoint를 LLMPlannerAdapter로 연결
+            # NOTE: ChatOpenAI는 lazy connection이므로 생성 시점에 vLLM이 미시작이어도 안전하다.
+            # 실제 LLM 호출은 graph invoke 시점에 발생하며,
+            # 그때는 lifespan에서 vLLM이 이미 시작된 상태다.
+            from langchain_openai import ChatOpenAI
+
+            planner_base_url = os.getenv(
+                "LANGGRAPH_MODEL_BASE_URL",
+                f"http://127.0.0.1:{runtime_config.port}/v1",
+            )
+            planner_api_key = os.getenv("LANGGRAPH_MODEL_API_KEY", "EMPTY")
+            planner_model = os.getenv("LANGGRAPH_PLANNER_MODEL", runtime_config.model.model_path)
+            llm = ChatOpenAI(
+                base_url=planner_base_url,
+                api_key=planner_api_key,
+                model=planner_model,
+                temperature=0.0,
+            )
+            planner = LLMPlannerAdapter(llm=llm, registry=tool_registry)
+        executor = RegistryExecutorAdapter(
+            tool_registry=tool_registry,
+            session_store=self.session_store,
+        )
+
+        # checkpointer가 외부에서 주입되지 않으면 SqliteSaver를 시도한다.
+        # SqliteSaver는 프로세스 재시작 후에도 interrupt 상태를 복원하므로
+        # MemorySaver와 달리 재시작-안전(restart-safe)하다.
+        if checkpointer is None:
+            checkpointer, conn = _build_sync_sqlite_checkpointer(self.session_store.db_path)
+            # 이전 동기 connection이 있으면 닫아 leak을 방지한다.
+            if self._sync_checkpointer_conn is not None:
+                try:
+                    self._sync_checkpointer_conn.close()
+                except Exception:
+                    pass
+            self._sync_checkpointer_conn = conn
+
+        self.graph = build_govon_graph(
+            planner_adapter=planner,
+            executor_adapter=executor,
+            session_store=self.session_store,
+            checkpointer=checkpointer,
+        )
+        logger.info("LangGraph graph 초기화 완료")
+
+
+def _build_sync_sqlite_checkpointer(
+    session_db_path: str,
+) -> tuple:
+    """SqliteSaver(동기) 또는 MemorySaver(fallback)를 반환한다.
+
+    LangGraph checkpointer용 SQLite DB는 SessionStore의 sessions.sqlite3와
+    같은 디렉터리에 별도 파일 ``langgraph_checkpoints.db``로 생성한다.
+    두 DB를 분리함으로써 관심사(세션 메타 vs. graph 체크포인트)를 명확히 구분한다.
+
+    SqliteSaver는 프로세스 재시작 후에도 interrupt 상태를 SQLite에서 복원하므로
+    MemorySaver와 달리 재시작-안전(restart-safe)하다.
+
+    Parameters
+    ----------
+    session_db_path : str
+        SessionStore가 사용 중인 sessions.sqlite3 파일 경로.
+        이 경로의 부모 디렉터리에 langgraph_checkpoints.db를 생성한다.
+
+    Returns
+    -------
+    tuple[SqliteSaver | MemorySaver, sqlite3.Connection | None]
+        (checkpointer, conn) 튜플.
+        SqliteSaver 사용 시 conn은 열린 sqlite3.Connection이며,
+        호출자가 적절한 시점에 close해야 한다.
+        MemorySaver fallback 시 conn은 None이다.
+    """
+    cp_db_path = str(Path(session_db_path).parent / "langgraph_checkpoints.db")
+    try:
+        from langgraph.checkpoint.sqlite import SqliteSaver
+
+        conn = __import__("sqlite3").connect(cp_db_path, check_same_thread=False)
+        saver = SqliteSaver(conn)
+        logger.info(f"LangGraph checkpointer: SqliteSaver ({cp_db_path})")
+        return saver, conn
+    except ImportError:
+        logger.warning(
+            "langgraph-checkpoint-sqlite 미설치 — MemorySaver로 fallback합니다. "
+            "프로세스 재시작 시 interrupt 상태가 소멸됩니다."
+        )
+        from langgraph.checkpoint.memory import MemorySaver
+
+        return MemorySaver(), None
+
+
+manager = vLLMEngineManager()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """FastAPI lifespan: 모델/인덱스 초기화 및 AsyncSqliteSaver 업그레이드.
+
+    startup 단계에서 AsyncSqliteSaver가 사용 가능하면 graph를 재구성한다.
+    AsyncSqliteSaver는 async 컨텍스트 매니저로 관리하며, shutdown 시 정리한다.
+    AsyncSqliteSaver import 실패 시 _init_graph에서 이미 설정된
+    SqliteSaver(또는 MemorySaver fallback)를 그대로 유지한다.
+    """
+    await manager.initialize()
+
+    # AsyncSqliteSaver로 graph 재구성 시도 (더 높은 async 성능)
+    async_cp_db = str(Path(manager.session_store.db_path).parent / "langgraph_checkpoints.db")
+    try:
+        from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+
+        async with AsyncSqliteSaver.from_conn_string(async_cp_db) as async_saver:
+            # 동기 SqliteSaver가 보유하던 connection을 닫아 leak을 방지한다.
+            if manager._sync_checkpointer_conn is not None:
+                try:
+                    manager._sync_checkpointer_conn.close()
+                except Exception:
+                    pass
+                manager._sync_checkpointer_conn = None
+            manager._checkpointer_ctx = async_saver
+            manager._init_graph_with_async_checkpointer(async_saver)
+            logger.info(f"LangGraph checkpointer: AsyncSqliteSaver ({async_cp_db})")
+            yield
+        manager._checkpointer_ctx = None
+    except ImportError:
+        logger.info("AsyncSqliteSaver 미설치 — SqliteSaver(동기) 또는 MemorySaver로 실행합니다.")
+        yield
+
+
+app = FastAPI(
+    title="GovOn Local Runtime",
+    description="Local FastAPI daemon for the GovOn Agentic Shell MVP.",
+    lifespan=lifespan,
+)
+
+ALLOWED_ORIGINS = os.getenv("CORS_ORIGINS", "").split(",")
+if ALLOWED_ORIGINS and ALLOWED_ORIGINS[0]:
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=ALLOWED_ORIGINS,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+if _RATE_LIMIT_AVAILABLE and limiter is not None:
+    app.state.limiter = limiter
+    app.add_middleware(SlowAPIMiddleware)
+
+
+@app.get("/health")
+async def health():
+    index_summary = None
+    if manager.index_manager:
+        stats = manager.index_manager.get_index_stats()
+        index_summary = {
+            idx_type: {
+                "loaded": info.get("loaded", False),
+                "doc_count": info.get("doc_count", 0),
+            }
+            for idx_type, info in stats.get("indexes", {}).items()
+        }
+
+    bm25_summary = {}
+    for idx_type in IndexType:
+        indexer = manager.bm25_indexers.get(idx_type)
+        if indexer and indexer.is_ready():
+            bm25_summary[idx_type.value] = {"loaded": True, "doc_count": indexer.doc_count}
+        else:
+            bm25_summary[idx_type.value] = {"loaded": False}
+
+    return {
+        "status": "healthy",
+        "profile": runtime_config.profile.value,
+        "model": runtime_config.model.model_path,
+        "rag_enabled": manager.index_manager is not None or manager.retriever is not None,
+        "agents_loaded": manager.agent_manager.list_agents() if manager.agent_manager else [],
+        "indexes": index_summary,
+        "bm25_indexes": bm25_summary,
+        "hybrid_search_enabled": manager.hybrid_engine is not None,
+        "local_documents": {
+            "enabled": bool(runtime_config.paths.local_docs_root),
+            "root_dir": runtime_config.paths.local_docs_root or None,
+            "last_sync": manager.local_document_sync_status,
+        },
+        "feature_flags": {
+            "use_rag_pipeline": manager.feature_flags.use_rag_pipeline,
+            "model_version": manager.feature_flags.model_version,
+        },
+        "session_store": {
+            "driver": "sqlite",
+            "path": manager.session_store.db_path,
+        },
+    }
+
+
+def _rate_limit(limit_string: str):
+    if _RATE_LIMIT_AVAILABLE and limiter is not None:
+        return limiter.limit(limit_string)
+
+    def _noop(func):
+        return func
+
+    return _noop
+
+
+def get_feature_flags(request: Request) -> FeatureFlags:
+    header = request.headers.get("X-Feature-Flag")
+    return manager.feature_flags.override_from_header(header)
+
+
+@app.post("/v1/generate-civil-response", response_model=GenerateCivilResponseResponse)
+@_rate_limit("30/minute")
+async def generate_civil_response(
+    request: GenerateCivilResponseRequest,
+    _: None = Depends(verify_api_key),
+    flags: FeatureFlags = Depends(get_feature_flags),
+):
+    if request.stream:
+        raise HTTPException(status_code=400, detail="민원 답변 스트리밍은 /v1/stream을 사용하세요.")
+
+    request_id = str(uuid.uuid4())
+    final_output, retrieved_cases, search_results = await manager.generate_civil_response(
+        request,
+        request_id,
+        flags,
+    )
+    if final_output is None:
+        raise HTTPException(status_code=500, detail="민원 답변 생성에 실패했습니다.")
+
+    return GenerateCivilResponseResponse(
+        request_id=request_id,
+        complaint_id=request.complaint_id,
+        text=manager._strip_thought_blocks(final_output.outputs[0].text),
+        prompt_tokens=len(final_output.prompt_token_ids),
+        completion_tokens=len(final_output.outputs[0].token_ids),
+        retrieved_cases=[RetrievedCase(**case) for case in retrieved_cases],
+        search_results=search_results,
+    )
+
+
+@app.post("/v1/generate", response_model=GenerateResponse)
+@_rate_limit("30/minute")
+async def generate(
+    request: GenerateRequest,
+    _: None = Depends(verify_api_key),
+    flags: FeatureFlags = Depends(get_feature_flags),
+):
+    if request.stream:
+        raise HTTPException(status_code=400, detail="Use /v1/stream for streaming.")
+
+    request_id = str(uuid.uuid4())
+    final_output, retrieved_cases = await manager.generate(request, request_id, flags)
+    if final_output is None:
+        raise HTTPException(status_code=500, detail="Generation failed.")
+
+    return GenerateResponse(
+        request_id=request_id,
+        complaint_id=request.complaint_id,
+        text=manager._strip_thought_blocks(final_output.outputs[0].text),
+        prompt_tokens=len(final_output.prompt_token_ids),
+        completion_tokens=len(final_output.outputs[0].token_ids),
+        retrieved_cases=[RetrievedCase(**case) for case in retrieved_cases],
+    )
+
+
+@app.post("/v1/stream")
+@_rate_limit("30/minute")
+async def stream_generate(
+    request: GenerateRequest,
+    _: None = Depends(verify_api_key),
+    flags: FeatureFlags = Depends(get_feature_flags),
+):
+    if not request.stream:
+        request.stream = True
+
+    request_id = str(uuid.uuid4())
+    results_stream, retrieved_cases, search_results = await manager.generate_stream(
+        request,
+        request_id,
+        flags,
+    )
+
+    async def stream_results() -> AsyncGenerator[str, None]:
+        cases_data = [RetrievedCase(**case).model_dump() for case in retrieved_cases]
+        search_data = [result.model_dump() for result in search_results]
+
+        async for request_output in results_stream:
+            text = request_output.outputs[0].text
+            finished = request_output.finished
+            if finished:
+                text = manager._strip_thought_blocks(text)
+
+            response_obj = {"request_id": request_id, "text": text, "finished": finished}
+            if finished:
+                response_obj["retrieved_cases"] = cases_data
+                response_obj["search_results"] = search_data
+
+            yield f"data: {json.dumps(response_obj, ensure_ascii=False)}\n\n"
+
+    return StreamingResponse(stream_results(), media_type="text/event-stream")
+
+
+@app.post("/v1/search", response_model=SearchResponse)
+@app.post("/search", response_model=SearchResponse)
+@_rate_limit("60/minute")
+async def search(request: SearchRequest, _: Request, __: None = Depends(verify_api_key)):
+    start_time = time.monotonic()
+    try:
+        if manager.hybrid_engine:
+            results_raw, actual_mode = await manager.hybrid_engine.search(
+                query=request.query,
+                index_type=request.doc_type,
+                top_k=request.top_k,
+                mode=request.search_mode,
+            )
+            results = [
+                SearchResult(
+                    doc_id=result.get("doc_id", ""),
+                    source_type=IndexType(result.get("doc_type", request.doc_type.value)),
+                    title=result.get("title", ""),
+                    content=_extract_content_by_type(result, request.doc_type),
+                    score=result.get("score", 0.0),
+                    reliability_score=result.get("reliability_score", 1.0),
+                    metadata=result.get("extras", {}),
+                    chunk_index=result.get("chunk_index", 0),
+                    total_chunks=result.get("chunk_total", 1),
+                )
+                for result in results_raw
+            ]
+        elif manager.retriever:
+            raw_results = manager.retriever.search(request.query, top_k=request.top_k)
+            results = [
+                SearchResult(
+                    doc_id=raw.get("id", raw.get("doc_id", "")),
+                    source_type=request.doc_type,
+                    title=raw.get("category", ""),
+                    content=raw.get("complaint", "") + "\n" + raw.get("answer", ""),
+                    score=raw.get("score", 0.0),
+                    reliability_score=raw.get("reliability_score", 1.0),
+                )
+                for raw in raw_results
+            ]
+            actual_mode = SearchMode.DENSE
+        else:
+            raise HTTPException(status_code=503, detail="검색 엔진이 아직 초기화되지 않았습니다.")
+
+        elapsed_ms = (time.monotonic() - start_time) * 1000
+        actual_search_mode = actual_mode if actual_mode != request.search_mode else None
+        return SearchResponse(
+            query=request.query,
+            doc_type=request.doc_type,
+            search_mode=request.search_mode,
+            actual_search_mode=actual_search_mode,
+            results=results,
+            total=len(results),
+            search_time_ms=round(elapsed_ms, 2),
+        )
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"검색 중 오류 발생: {exc}", exc_info=True)
+        raise HTTPException(status_code=500, detail="검색 처리 중 내부 오류가 발생했습니다.")
+
+
+def _trace_to_schema(trace: AgentTrace) -> AgentTraceSchema:
+    return AgentTraceSchema(
+        request_id=trace.request_id,
+        session_id=trace.session_id,
+        plan=trace.plan.tool_names if trace.plan else [],
+        plan_reason=trace.plan.reason if trace.plan else "",
+        tool_results=[
+            ToolResultSchema(
+                tool=tool_name(result.tool),
+                success=result.success,
+                latency_ms=round(result.latency_ms, 2),
+                data=result.data,
+                error=result.error,
+            )
+            for result in trace.tool_results
+        ],
+        total_latency_ms=round(trace.total_latency_ms, 2),
+        error=trace.error,
+    )
+
+
+@app.post("/v1/agent/run", response_model=AgentRunResponse)
+@_rate_limit("30/minute")
+async def agent_run(
+    request: AgentRunRequest,
+    _: None = Depends(verify_api_key),
+):
+    if not manager.agent_loop:
+        raise HTTPException(status_code=503, detail="에이전트 루프가 초기화되지 않았습니다.")
+    if request.stream:
+        raise HTTPException(status_code=400, detail="스트리밍은 /v1/agent/stream을 사용하세요.")
+
+    session = manager.session_store.get_or_create(session_id=request.session_id)
+    request_id = str(uuid.uuid4())
+    trace = await manager.agent_loop.run(
+        query=request.query,
+        session=session,
+        request_id=request_id,
+        force_tools=request.force_tools,
+    )
+
+    search_results = None
+    for result in trace.tool_results:
+        if tool_name(result.tool) == ToolType.RAG_SEARCH.value and result.success:
+            search_results = result.data.get("results")
+        elif (
+            tool_name(result.tool) == ToolType.API_LOOKUP.value
+            and result.success
+            and not search_results
+        ):
+            search_results = result.data.get("results")
+
+    return AgentRunResponse(
+        request_id=request_id,
+        session_id=session.session_id,
+        text=trace.final_text,
+        trace=_trace_to_schema(trace),
+        search_results=search_results,
+    )
+
+
+@app.post("/v1/agent/stream")
+@_rate_limit("30/minute")
+async def agent_stream(
+    request: AgentRunRequest,
+    _: None = Depends(verify_api_key),
+):
+    if not manager.agent_loop:
+        raise HTTPException(status_code=503, detail="에이전트 루프가 초기화되지 않았습니다.")
+
+    session = manager.session_store.get_or_create(session_id=request.session_id)
+    request_id = str(uuid.uuid4())
+
+    async def stream_events() -> AsyncGenerator[str, None]:
+        async for event in manager.agent_loop.run_stream(
+            query=request.query,
+            session=session,
+            request_id=request_id,
+            force_tools=request.force_tools,
+        ):
+            yield f"data: {json.dumps(event, ensure_ascii=False)}\n\n"
+
+    return StreamingResponse(stream_events(), media_type="text/event-stream")
+
+
+# ---------------------------------------------------------------------------
+# v2 엔드포인트: LangGraph 기반 agent 실행 (interrupt/approve 패턴)
+# ---------------------------------------------------------------------------
+
+
+@app.post("/v2/agent/stream")
+async def v2_agent_stream(
+    request: AgentRunRequest,
+    _: None = Depends(verify_api_key),
+):
+    """LangGraph 기반 agent SSE 스트리밍 실행.
+
+    graph.astream()을 사용해 노드별 완료 이벤트를 SSE로 전송한다.
+
+    이벤트 형식 (각 줄: ``data: <JSON>\\n\\n``):
+      - 노드 진행: ``{"node": "<name>", "status": "completed", ...}``
+      - approval_wait 도달:
+        ``{"node": "approval_wait", "status": "awaiting_approval",
+           "approval_request": {...}, "thread_id": "..."}``
+      - 오류: ``{"node": "error", "status": "error", "error": "..."}``
+
+    승인 흐름:
+    - 클라이언트는 ``awaiting_approval`` 이벤트 수신 후 스트림이 종료됨을 인지하고
+      ``/v2/agent/approve``로 승인/거절을 전달한다.
+    """
+    if not manager.graph:
+
+        async def _no_graph():
+            yield 'data: {"node": "error", "status": "error", "error": "LangGraph graph가 초기화되지 않았습니다."}\n\n'
+
+        return StreamingResponse(_no_graph(), media_type="text/event-stream")
+
+    from langchain_core.messages import HumanMessage
+
+    thread_id = request.session_id or str(uuid.uuid4())
+    session_id = thread_id
+    request_id = str(uuid.uuid4())
+    config = {"configurable": {"thread_id": thread_id}}
+    initial_state = {
+        "session_id": session_id,
+        "request_id": request_id,
+        "messages": [HumanMessage(content=request.query)],
+    }
+
+    async def _generate() -> AsyncGenerator[str, None]:
+        try:
+            async for chunk in manager.graph.astream(initial_state, config, stream_mode="updates"):
+                # chunk: {node_name: state_delta}
+                for node_name, state_delta in chunk.items():
+                    event: dict = {
+                        "node": node_name,
+                        "status": "completed",
+                    }
+                    # synthesis 완료 시 evidence_items와 task_type을 이벤트에 포함.
+                    # 전제: stream_mode="updates"에서 state_delta는 노드의 raw return dict다.
+                    # LangGraph 버전 업그레이드 시 이 구조가 변경될 수 있으므로 주의.
+                    # evidence_items 스키마: EvidenceItem.to_dict() 필드를 따른다.
+                    #   source_type: "rag" | "api" | "llm_generated"
+                    #   title, excerpt, link_or_path, page, score, provider_meta
+                    #   (웹 프론트엔드에서 직접 렌더링 시 XSS 방지를 위해 이스케이프 필요)
+                    if node_name == "synthesis" and isinstance(state_delta, dict):
+                        if state_delta.get("final_text"):
+                            event["final_text"] = state_delta["final_text"]
+                        if state_delta.get("evidence_items"):
+                            event["evidence_items"] = state_delta["evidence_items"]
+                        if state_delta.get("task_type"):
+                            event["task_type"] = state_delta["task_type"]
+                    if node_name == "approval_wait":
+                        try:
+                            graph_state = await manager.graph.aget_state(config)
+                            if graph_state.next:
+                                event = {
+                                    "node": "approval_wait",
+                                    "status": "awaiting_approval",
+                                    "approval_request": _extract_approval_request(graph_state),
+                                    "thread_id": thread_id,
+                                    "session_id": session_id,
+                                }
+                        except Exception as exc:
+                            logger.warning(f"[v2/agent/stream] aget_state 실패: {exc}")
+                            event["status"] = "awaiting_approval"
+                            event["approval_request"] = {
+                                "prompt": "승인 정보를 불러올 수 없습니다. /v2/agent/approve로 진행하세요."
+                            }
+
+                    yield f"data: {json.dumps(event, ensure_ascii=False)}\n\n"
+
+                    # Stop streaming after awaiting_approval (client must call /v2/agent/approve)
+                    if event.get("status") == "awaiting_approval":
+                        return
+        except Exception as exc:
+            logger.error(f"[v2/agent/stream] 스트림 예외: {exc}")
+            error_event = {"node": "error", "status": "error", "error": str(exc)}
+            yield f"data: {json.dumps(error_event, ensure_ascii=False)}\n\n"
+
+    return StreamingResponse(_generate(), media_type="text/event-stream")
+
+
+@app.post("/v2/agent/run")
+async def v2_agent_run(
+    request: AgentRunRequest,
+    _: None = Depends(verify_api_key),
+):
+    """LangGraph 기반 agent 실행 (1단계: interrupt까지).
+
+    graph를 실행하여 `approval_wait` 노드에서 interrupt되면
+    `status: awaiting_approval`과 함께 승인 요청 정보를 반환한다.
+
+    클라이언트는 반환된 `thread_id`를 저장해두고
+    `/v2/agent/approve`로 승인/거절을 전달해야 한다.
+
+    Session Resume Contract
+    -----------------------
+    동일 session_id로 재요청하는 경우 다음 규칙을 따른다:
+
+    1. **interrupt 대기 중**: graph가 approval_wait에서 interrupt 상태이면
+       현재 checkpoint에서 resume하지 않고 새 메시지를 *추가하여* 이어서 실행한다.
+       (재요청은 새 graph_run으로 처리한다.)
+       승인/거절은 반드시 `/v2/agent/approve`를 통해 처리해야 한다.
+
+    2. **완료된 graph**: graph가 END에 도달한 상태(state.next == [])이면
+       동일 thread_id에 새 graph_run을 시작한다. LangGraph checkpointer가
+       동일 thread_id에서 이전 상태를 누적하므로 대화 히스토리가 보존된다.
+
+    3. **프로세스 재시작 후**: SqliteSaver 사용 시 DB에서 checkpoint가 복원되므로
+       interrupt 상태가 유지된다. 클라이언트는 기존 thread_id로 `/v2/agent/approve`
+       를 다시 호출하면 중단된 지점에서 resume할 수 있다.
+
+    Note: session_id == thread_id. 두 값은 항상 동일하게 유지된다.
+    """
+    if not manager.graph:
+        raise HTTPException(status_code=503, detail="LangGraph graph가 초기화되지 않았습니다.")
+
+    from langchain_core.messages import HumanMessage
+
+    thread_id = request.session_id or str(uuid.uuid4())
+    session_id = thread_id  # thread_id를 session_id로 확정 (session_id == thread_id 불변)
+    request_id = str(uuid.uuid4())
+    config = {"configurable": {"thread_id": thread_id}}
+    initial_state = {
+        "session_id": session_id,
+        "request_id": request_id,
+        "messages": [HumanMessage(content=request.query)],
+    }
+
+    try:
+        await manager.graph.ainvoke(initial_state, config)
+
+        # interrupt 상태 확인
+        graph_state = await manager.graph.aget_state(config)
+        if graph_state.next:
+            # interrupt 대기 중: approval_request 정보를 클라이언트에 반환
+            return {
+                "status": "awaiting_approval",
+                "thread_id": thread_id,
+                "session_id": session_id,
+                "graph_run_id": request_id,
+                "approval_request": _extract_approval_request(graph_state),
+            }
+
+        # interrupt 없이 완료된 경우 (rejected 또는 오류)
+        final_state = graph_state.values
+        return {
+            "status": "completed",
+            "thread_id": thread_id,
+            "session_id": session_id,
+            "graph_run_id": request_id,
+            "text": final_state.get("final_text", ""),
+            "evidence_items": final_state.get("evidence_items", []),
+            "task_type": final_state.get("task_type", ""),
+        }
+    except Exception as exc:
+        logger.error(f"[v2/agent/run] 예외 발생: {exc}")
+        # graph_run을 "error" status로 기록 시도
+        try:
+            if manager.session_store:
+                session = manager.session_store.get_or_create(session_id)
+                session.add_graph_run(
+                    request_id=request_id,
+                    plan_summary=f"[error] {exc}",
+                    approval_status="",
+                    executed_capabilities=[],
+                    status="error",
+                    total_latency_ms=0.0,
+                )
+        except Exception as persist_exc:
+            logger.warning(f"[v2/agent/run] error persist 실패: {persist_exc}")
+        return {
+            "status": "error",
+            "thread_id": thread_id,
+            "session_id": session_id,
+            "graph_run_id": request_id,
+            "error": str(exc),
+        }
+
+
+@app.post("/v2/agent/approve")
+async def v2_agent_approve(
+    thread_id: str,
+    approved: bool,
+    _: None = Depends(verify_api_key),
+):
+    """interrupt된 graph를 resume한다 (2단계: 승인/거절).
+
+    Parameters
+    ----------
+    thread_id : str
+        `/v2/agent/run`에서 반환된 thread_id.
+    approved : bool
+        True면 tool_execute로 진행, False면 graph가 END로 종료.
+    """
+    if not manager.graph:
+        raise HTTPException(status_code=503, detail="LangGraph graph가 초기화되지 않았습니다.")
+
+    from langgraph.types import Command
+
+    config = {"configurable": {"thread_id": thread_id}}
+
+    try:
+        result = await manager.graph.ainvoke(
+            Command(resume={"approved": approved}),
+            config,
+        )
+
+        # 거절이면 "rejected", 승인 완료면 "completed"
+        approval_status = result.get("approval_status", "")
+        if not approved:
+            response_status = "rejected"
+        else:
+            response_status = "completed"
+
+        return {
+            "status": response_status,
+            "thread_id": thread_id,
+            "session_id": result.get("session_id", ""),
+            "graph_run_id": result.get("request_id", ""),
+            "text": result.get("final_text", ""),
+            "evidence_items": result.get("evidence_items", []),
+            "task_type": result.get("task_type", ""),
+            "tool_results": result.get("tool_results", {}),
+            "approval_status": approval_status,
+        }
+    except Exception as exc:
+        logger.error(f"[v2/agent/approve] 예외 발생: {exc}")
+        # graph_run을 "error" status로 기록 시도
+        session_id = ""
+        request_id = ""
+        try:
+            if manager.session_store:
+                graph_state = await manager.graph.aget_state(config)
+                state_values = graph_state.values if graph_state else {}
+                session_id = state_values.get("session_id", "")
+                request_id = state_values.get("request_id", "")
+                if session_id:
+                    session = manager.session_store.get_or_create(session_id)
+                    session.add_graph_run(
+                        request_id=request_id,
+                        plan_summary=f"[error] {exc}",
+                        approval_status="",
+                        executed_capabilities=[],
+                        status="error",
+                        total_latency_ms=0.0,
+                    )
+        except Exception as persist_exc:
+            logger.warning(f"[v2/agent/approve] error persist 실패: {persist_exc}")
+        return {
+            "status": "error",
+            "thread_id": thread_id,
+            "session_id": session_id,
+            "graph_run_id": request_id,
+            "error": str(exc),
+        }
+
+
+@app.post("/v2/agent/cancel")
+async def v2_agent_cancel(
+    thread_id: str,
+    _: None = Depends(verify_api_key),
+):
+    """interrupt 대기 중인 graph를 강제 취소한다.
+
+    interrupt 상태에서 거절 처리(Command(resume={"approved": False}))를 수행하되,
+    state에 interrupt_reason="user_cancel"을 전달하여
+    persist 노드가 graph_run status를 "interrupted"로 기록하게 한다.
+
+    Parameters
+    ----------
+    thread_id : str
+        `/v2/agent/run`에서 반환된 thread_id.
+    """
+    if not manager.graph:
+        raise HTTPException(status_code=503, detail="LangGraph graph가 초기화되지 않았습니다.")
+
+    from langgraph.types import Command
+
+    config = {"configurable": {"thread_id": thread_id}}
+
+    try:
+        # interrupt 상태 확인
+        graph_state = await manager.graph.aget_state(config)
+        if not graph_state or not graph_state.next:
+            raise HTTPException(
+                status_code=409,
+                detail="해당 thread는 현재 interrupt 대기 상태가 아닙니다.",
+            )
+
+        session_id = graph_state.values.get("session_id", "")
+
+        # 강제 거절 + interrupt_reason 전달로 resume
+        result = await manager.graph.ainvoke(
+            Command(resume={"approved": False, "cancel": True}),
+            config,
+        )
+
+        # persist 노드에서 "interrupted" 기록을 위해 state update
+        # (approval_wait_node가 cancel 신호를 interrupt_reason으로 변환)
+        return {
+            "status": "cancelled",
+            "thread_id": thread_id,
+            "session_id": session_id,
+            "graph_run_id": result.get("request_id", ""),
+        }
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[v2/agent/cancel] 예외 발생: {exc}")
+        return {
+            "status": "error",
+            "thread_id": thread_id,
+            "error": str(exc),
+        }
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, **runtime_config.to_uvicorn_kwargs())

src/inference/bm25_indexer.py

@@ -0,0 +1,446 @@
+"""
+BM25 Indexer for Korean civil complaint search.
+
+Provides sparse keyword-based retrieval using morpheme analysis (Okt/Mecab)
+and BM25Okapi ranking. Complements the dense FAISS retriever for hybrid search.
+
+Issue: #153
+
+Known limitation:
+    BM25Okapi assigns negative IDF when a term appears in every document
+    (df == N). search() returns only positive-scoring results, so a single-
+    document corpus may return empty results for exact-match queries.
+    In practice this does not occur at production scale (10k+ documents).
+
+Security:
+    Uses pickle for BM25Okapi serialization. Only load index files from
+    trusted sources within the closed-network environment. When the
+    BM25_INDEX_HMAC_KEY environment variable is set, save() signs the
+    payload and load() verifies the HMAC before deserialization.
+"""
+
+import hashlib
+import hmac
+import json
+import os
+import pickle
+from typing import List, Optional, Tuple
+
+import numpy as np
+from loguru import logger
+from rank_bm25 import BM25Okapi
+
+# Minimal Korean stopwords relevant to civil complaints
+# Defined before KoreanTokenizer to avoid forward-reference maintenance hazard.
+_STOPWORDS = frozenset(
+    {
+        "이다",
+        "있다",
+        "하다",
+        "되다",
+        "없다",
+        "않다",
+        "이런",
+        "저런",
+        "그런",
+        "합니다",
+        "입니다",
+        "습니다",
+        "됩니다",
+        "있습니다",
+        "없습니다",
+        "에서",
+        "으로",
+        "에게",
+        "까지",
+        "부터",
+        "에서는",
+        "으로는",
+        "그리고",
+        "하지만",
+        "그러나",
+        "따라서",
+        "그래서",
+    }
+)
+
+
+class KoreanTokenizer:
+    """
+    Korean morpheme tokenizer with Mecab (preferred) and Okt (fallback).
+    In closed-network environments where Mecab is not installed, Okt is used.
+    """
+
+    def __init__(self, tokenizer_type: str = "auto"):
+        """
+        Args:
+            tokenizer_type: "mecab", "okt", or "auto" (tries Mecab first, falls back to Okt)
+        """
+        self.tokenizer_type = tokenizer_type
+        self._tagger = None
+        self._init_tokenizer(tokenizer_type)
+
+    def _init_tokenizer(self, tokenizer_type: str) -> None:
+        if tokenizer_type in ("mecab", "auto"):
+            try:
+                from konlpy.tag import Mecab
+
+                self._tagger = Mecab()
+                self.tokenizer_type = "mecab"
+                logger.info("Tokenizer initialized: Mecab")
+                return
+            except Exception:
+                if tokenizer_type == "mecab":
+                    raise RuntimeError(
+                        "Mecab is not installed. Install it or use tokenizer_type='okt'."
+                    )
+                logger.warning("Mecab unavailable, falling back to Okt.")
+
+        # Okt path
+        try:
+            from konlpy.tag import Okt
+
+            self._tagger = Okt()
+            self.tokenizer_type = "okt"
+            logger.info("Tokenizer initialized: Okt")
+        except Exception as e:
+            raise RuntimeError(f"Failed to initialize any Korean tokenizer: {e}")
+
+    def morphs(self, text: str) -> List[str]:
+        """Tokenize text into morphemes, filtering stopwords and short tokens."""
+        if not text or not text.strip():
+            return []
+        try:
+            tokens = self._tagger.morphs(str(text))
+            # Filter single characters and common stopwords
+            return [t for t in tokens if len(t) > 1 and t not in _STOPWORDS]
+        except Exception as e:
+            logger.warning(
+                f"Tokenization error (len={len(text)}): {type(e).__name__}. "
+                "Falling back to whitespace split."
+            )
+            return [t for t in str(text).split() if len(t) > 1]
+
+
+class BM25Indexer:
+    """
+    BM25 keyword index for civil complaint documents.
+
+    Builds a sparse BM25Okapi index over tokenized Korean text,
+    enabling keyword-exact matching for terms like law article numbers,
+    department names, and specific complaint keywords.
+
+    Return type note:
+        search() returns List[Tuple[int, float]] — raw corpus indices and BM25
+        scores. This is intentionally lower-level than CivilComplaintRetriever
+        which returns List[Dict]. The HybridSearchEngine is responsible for
+        mapping indices to metadata and fusing scores across both retrievers.
+
+    Usage:
+        indexer = BM25Indexer()
+        indexer.build_index(documents)
+        results = indexer.search("도로 포장 균열 신고", top_k=10)
+        indexer.save("models/bm25_index/complaints.pkl")
+
+        # Later:
+        indexer2 = BM25Indexer()
+        indexer2.load("models/bm25_index/complaints.pkl")
+    """
+
+    _PAYLOAD_VERSION = 1
+    _HMAC_KEY_ENV = "BM25_INDEX_HMAC_KEY"
+
+    def __init__(self, tokenizer_type: str = "auto"):
+        self.tokenizer = KoreanTokenizer(tokenizer_type)
+        self.bm25: Optional[BM25Okapi] = None
+        self._tokenized_corpus: Optional[List[List[str]]] = None
+        self._doc_count: int = 0
+
+    def __repr__(self) -> str:
+        return (
+            f"BM25Indexer(docs={self._doc_count}, "
+            f"tokenizer={self.tokenizer.tokenizer_type}, "
+            f"ready={self.is_ready()})"
+        )
+
+    # ------------------------------------------------------------------
+    # Index construction
+    # ------------------------------------------------------------------
+
+    def build_index(self, documents: List[str]) -> None:
+        """
+        Build BM25 index from a list of document strings.
+
+        Args:
+            documents: Raw text documents (one per entry).
+
+        Raises:
+            ValueError: If documents list is empty or all documents tokenize
+                        to empty token lists (would cause ZeroDivisionError
+                        inside BM25Okapi).
+        """
+        if not documents:
+            raise ValueError("Document list is empty.")
+
+        if self.bm25 is not None:
+            logger.warning("Rebuilding BM25 index — existing index will be replaced.")
+
+        logger.info(f"Tokenizing {len(documents)} documents...")
+        tokenized = [self.tokenizer.morphs(doc) for doc in documents]
+
+        empty_count = sum(1 for t in tokenized if not t)
+        if empty_count:
+            logger.warning(f"{empty_count} documents produced empty token lists.")
+
+        # Guard against all-empty corpus which causes ZeroDivisionError in BM25Okapi
+        if all(len(t) == 0 for t in tokenized):
+            raise ValueError(
+                "All documents produced empty token lists. "
+                "Check that documents contain valid Korean text."
+            )
+
+        logger.info("Building BM25 index...")
+        self._tokenized_corpus = tokenized
+        self.bm25 = BM25Okapi(self._tokenized_corpus)
+        self._doc_count = len(documents)
+        logger.info(f"BM25 index built: {self._doc_count} documents.")
+
+    def build_index_from_jsonl(self, data_path: str, text_field: str = "text") -> None:
+        """
+        Build index by loading documents from a JSONL file.
+
+        Each line must be a JSON object with a field matching `text_field`.
+        For files using EXAONE chat template format, the complaint content
+        is extracted from the [|user|] section automatically.
+
+        Args:
+            data_path: Path to JSONL file.
+            text_field: JSON field containing the text ("text" or "complaint").
+        """
+        if not os.path.exists(data_path):
+            raise FileNotFoundError(f"Data file not found: {data_path}")
+
+        documents = []
+        with open(data_path, "r", encoding="utf-8") as f:
+            for line_no, line in enumerate(f, 1):
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    item = json.loads(line)
+                    if text_field in item:
+                        raw = item[text_field]
+                        # Auto-extract complaint from EXAONE chat template
+                        if isinstance(raw, str) and "[|user|]" in raw:
+                            text = self._extract_complaint_from_template(raw)
+                        else:
+                            text = raw
+                    elif "complaint" in item:
+                        text = item["complaint"]
+                    elif "input" in item:
+                        text = item["input"]
+                    else:
+                        text = self._extract_complaint_from_template(item.get("text", ""))
+                    # Ensure text is always a string
+                    if not isinstance(text, str):
+                        text = str(text) if text is not None else ""
+                    documents.append(text)
+                except (json.JSONDecodeError, KeyError) as e:
+                    logger.warning(f"Line {line_no}: skipping due to error: {e}")
+
+        logger.info(f"Loaded {len(documents)} documents from {data_path}")
+        self.build_index(documents)
+
+    @staticmethod
+    def _extract_complaint_from_template(text: str) -> str:
+        """Extract complaint content from EXAONE chat template format."""
+        if not text:
+            return text
+        try:
+            if "[|user|]" in text:
+                user_part = text.split("[|user|]")[1].split("[|endofturn|]")[0]
+                if "민원 내용:" in user_part:
+                    return user_part.split("민원 내용:")[1].strip()
+                return user_part.strip()
+        except Exception as e:
+            logger.debug(f"Template extraction fallback: {type(e).__name__}")
+        return text
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    def search(self, query: str, top_k: int = 10) -> List[Tuple[int, float]]:
+        """
+        Search the BM25 index and return top-k (index, score) pairs.
+
+        Only positive-scoring documents are returned. Scores are raw BM25
+        values and are not normalized — the HybridSearchEngine handles
+        score fusion (e.g., RRF) across dense and sparse retrievers.
+
+        Args:
+            query: Korean query string.
+            top_k: Number of results to return.
+
+        Returns:
+            List of (document_index, bm25_score) tuples, sorted by score desc.
+
+        Raises:
+            RuntimeError: If index has not been built or loaded.
+        """
+        if self.bm25 is None:
+            raise RuntimeError("Index not built. Call build_index() first.")
+        if not query or not query.strip():
+            return []
+
+        tokenized_query = self.tokenizer.morphs(query)
+        if not tokenized_query:
+            logger.warning("Query tokenized to empty list. Returning no results.")
+            return []
+
+        scores: np.ndarray = self.bm25.get_scores(tokenized_query)
+
+        # Use argpartition O(N) instead of argsort O(N log N) for top-k selection
+        actual_k = min(top_k, len(scores))
+        if actual_k == 0:
+            return []
+
+        top_indices = np.argpartition(scores, -actual_k)[-actual_k:]
+        top_indices = top_indices[np.argsort(scores[top_indices])[::-1]]
+
+        results = [(int(idx), float(scores[idx])) for idx in top_indices if scores[idx] > 0.0]
+        return results
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+
+    def save(self, path: str) -> None:
+        """
+        Serialize and save the BM25 index to disk.
+
+        Security: Uses pickle for BM25Okapi serialization. When the
+        ``BM25_INDEX_HMAC_KEY`` environment variable is set, the payload is
+        signed with HMAC-SHA256 and a ``.sig`` sidecar file is written. Only
+        load index files from trusted sources within the closed-network
+        environment.
+
+        Args:
+            path: Destination file path (e.g., "models/bm25_index/complaints.pkl").
+        """
+        if self.bm25 is None:
+            raise RuntimeError("Index not built. Call build_index() first.")
+
+        # Fix: use abspath to avoid makedirs("") crash on bare filenames
+        parent = os.path.dirname(os.path.abspath(path))
+        os.makedirs(parent, exist_ok=True)
+
+        payload = {
+            "version": self._PAYLOAD_VERSION,
+            "bm25": self.bm25,
+            "tokenized_corpus": self._tokenized_corpus,
+            "doc_count": self._doc_count,
+            "tokenizer_type": self.tokenizer.tokenizer_type,
+        }
+        data = pickle.dumps(payload, protocol=pickle.HIGHEST_PROTOCOL)
+
+        # HMAC signing (when key is configured)
+        hmac_key = os.getenv(self._HMAC_KEY_ENV)
+        if hmac_key:
+            sig = hmac.new(hmac_key.encode(), data, hashlib.sha256).hexdigest()
+            sig_path = path + ".sig"
+            with open(sig_path, "w", encoding="utf-8") as sf:
+                sf.write(sig)
+            logger.info(f"HMAC signature written to {sig_path}")
+
+        with open(path, "wb") as f:
+            f.write(data)
+        logger.info(f"BM25 index saved to {path} ({self._doc_count} documents).")
+
+    def load(self, path: str) -> None:
+        """
+        Load a previously saved BM25 index from disk.
+
+        Security: When the ``BM25_INDEX_HMAC_KEY`` environment variable is
+        set, the HMAC-SHA256 signature is verified before deserialization.
+        Pickle deserialization can execute arbitrary code — only load files
+        from trusted sources within the closed-network environment.
+
+        Args:
+            path: Path to the pickle file saved by `save()`.
+
+        Raises:
+            FileNotFoundError: If the index file does not exist.
+            ValueError: If the file is corrupt, has an incompatible schema,
+                        or fails HMAC verification.
+        """
+        if not os.path.exists(path):
+            raise FileNotFoundError(f"BM25 index file not found: {path}")
+
+        with open(path, "rb") as f:
+            data = f.read()
+
+        # HMAC verification (when key is configured)
+        hmac_key = os.getenv(self._HMAC_KEY_ENV)
+        if hmac_key:
+            sig_path = path + ".sig"
+            if not os.path.exists(sig_path):
+                raise ValueError(
+                    f"HMAC signature file missing: {sig_path}. "
+                    "Index file cannot be verified — rebuild the index."
+                )
+            with open(sig_path, "r", encoding="utf-8") as sf:
+                expected_sig = sf.read().strip()
+            actual_sig = hmac.new(hmac_key.encode(), data, hashlib.sha256).hexdigest()
+            if not hmac.compare_digest(actual_sig, expected_sig):
+                raise ValueError(
+                    "BM25 index HMAC verification failed — file may be tampered. "
+                    "Rebuild the index with a trusted data source."
+                )
+            logger.info("HMAC signature verified.")
+
+        try:
+            payload = pickle.loads(data)
+        except Exception as e:
+            raise ValueError(f"Failed to load BM25 index (corrupt or incompatible): {e}") from e
+
+        # Payload version check
+        saved_version = payload.get("version")
+        if saved_version != self._PAYLOAD_VERSION:
+            raise ValueError(
+                f"BM25 index version mismatch: file has v{saved_version}, "
+                f"expected v{self._PAYLOAD_VERSION}. Rebuild the index."
+            )
+
+        try:
+            self.bm25 = payload["bm25"]
+            self._tokenized_corpus = payload["tokenized_corpus"]
+            self._doc_count = payload["doc_count"]
+        except (KeyError, TypeError) as e:
+            raise ValueError(
+                f"BM25 index file has incompatible schema (missing key: {e}). " "Rebuild the index."
+            ) from e
+
+        saved_tokenizer = payload.get("tokenizer_type", "unknown")
+        if saved_tokenizer != self.tokenizer.tokenizer_type:
+            logger.warning(
+                f"Tokenizer mismatch: index was built with '{saved_tokenizer}' "
+                f"but current tokenizer is '{self.tokenizer.tokenizer_type}'. "
+                "Search recall may be degraded. Rebuild the index to resolve."
+            )
+
+        logger.info(
+            f"BM25 index loaded from {path} ({self._doc_count} documents, "
+            f"tokenizer: {saved_tokenizer})."
+        )
+
+    # ------------------------------------------------------------------
+    # Utilities
+    # ------------------------------------------------------------------
+
+    @property
+    def doc_count(self) -> int:
+        return self._doc_count
+
+    def is_ready(self) -> bool:
+        return self.bm25 is not None

src/inference/db/__init__.py

@@ -0,0 +1,67 @@
+"""
+GovOn RAG 데이터베이스 모듈.
+
+SQLAlchemy 2.0 기반 ORM 모델, CRUD 레이어, 변환 헬퍼를 제공한다.
+"""
+
+from src.inference.db.converters import (
+    dataclass_to_orm,
+    orm_to_dataclass,
+    orm_to_pydantic,
+)
+from src.inference.db.crud import (  # DocumentSource; IndexingQueue; IndexVersion
+    activate_version,
+    create_document_source,
+    create_index_version,
+    create_indexing_queue_item,
+    deactivate_versions,
+    delete_document_source,
+    get_active_version,
+    get_by_source_type_and_id,
+    get_document_source,
+    get_document_sources,
+    get_pending_items,
+    get_queue_stats,
+    update_document_source,
+    update_queue_status,
+)
+from src.inference.db.database import SessionLocal, engine, get_db
+from src.inference.db.models import (
+    Base,
+    DocumentSource,
+    IndexingQueue,
+    IndexVersion,
+)
+
+__all__ = [
+    # 데이터베이스 인프라
+    "engine",
+    "SessionLocal",
+    "get_db",
+    "Base",
+    # ORM 모델
+    "DocumentSource",
+    "IndexingQueue",
+    "IndexVersion",
+    # DocumentSource CRUD
+    "create_document_source",
+    "get_document_source",
+    "get_document_sources",
+    "update_document_source",
+    "delete_document_source",
+    "get_by_source_type_and_id",
+    # IndexingQueue CRUD
+    "create_indexing_queue_item",
+    "get_pending_items",
+    "update_queue_status",
+    "get_queue_stats",
+    # IndexVersion CRUD
+    "create_index_version",
+    "get_active_version",
+    "deactivate_versions",
+    "activate_version",
+    # 변환 헬퍼
+    "orm_to_dataclass",
+    "dataclass_to_orm",
+    "orm_to_pydantic",
+]

src/inference/db/alembic/env.py

@@ -0,0 +1,82 @@
+"""
+Alembic 환경 설정.
+
+DATABASE_URL 환경변수를 통해 연결 문자열을 주입받는다.
+기본값은 로컬 GovOn 홈 디렉터리 아래 SQLite 파일을 사용한다.
+"""
+
+# isort:skip_file
+import logging
+import os
+import sys
+from pathlib import Path
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+# 프로젝트 루트를 sys.path에 추가하여 모델 import 가능하게 함
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../../../../..")))
+
+from src.inference.db.models import Base  # noqa: E402
+
+# Alembic Config 객체
+config = context.config
+
+# 로깅 설정
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# 메타데이터 설정 (자동 마이그레이션 생성용)
+target_metadata = Base.metadata
+
+# 환경변수에서 DB URL 가져오기
+_DEFAULT_GOVON_HOME = Path(os.getenv("GOVON_HOME", Path.home() / ".govon"))
+_DEFAULT_DATABASE_URL = f"sqlite:///{_DEFAULT_GOVON_HOME / 'metadata.sqlite3'}"
+database_url = os.getenv("DATABASE_URL", _DEFAULT_DATABASE_URL)
+
+if database_url == _DEFAULT_DATABASE_URL:
+    logging.getLogger(__name__).warning(
+        "DATABASE_URL 환경변수가 설정되지 않아 로컬 SQLite 기본값을 사용합니다. "
+        "별도 RDBMS를 사용하려면 DATABASE_URL을 명시적으로 설정하세요."
+    )
+
+config.set_main_option("sqlalchemy.url", database_url)
+
+
+def run_migrations_offline() -> None:
+    """오프라인 모드: DB 연결 없이 SQL 스크립트만 생성."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """온라인 모드: DB에 직접 연결하여 마이그레이션 실행."""
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

src/inference/db/alembic/script.py.mako

@@ -0,0 +1,25 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

src/inference/db/alembic/versions/001_create_rag_tables.py

@@ -0,0 +1,346 @@
+"""RAG 핵심 테이블 생성: document_source, indexing_queue, index_version
+
+ADR-004 Section D 스키마와 Issue #152 요구사항을 병합한 초기 마이그레이션.
+ORM 모델(models.py)과 정합성을 유지한다.
+
+Revision ID: 001
+Revises: None
+Create Date: 2026-03-22
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+
+# revision identifiers, used by Alembic.
+revision: str = "001"
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ------------------------------------------------------------------
+    # 1. document_source 테이블
+    # ------------------------------------------------------------------
+    op.create_table(
+        "document_source",
+        # PK
+        sa.Column(
+            "id",
+            UUID(as_uuid=True),
+            server_default=sa.text("gen_random_uuid()"),
+            primary_key=True,
+            comment="문서 고유 식별자",
+        ),
+        # 공통 필드
+        sa.Column(
+            "source_type",
+            sa.String(20),
+            nullable=False,
+            comment="문서 타입: case, law, manual, notice",
+        ),
+        sa.Column(
+            "source_id",
+            sa.String(255),
+            nullable=False,
+            comment="원본 문서 식별자",
+        ),
+        sa.Column(
+            "source_name",
+            sa.String(200),
+            nullable=True,
+            comment="출처명 (AI Hub, 법제처 등)",
+        ),
+        sa.Column("title", sa.String(500), nullable=False, comment="문서 제목"),
+        sa.Column("content", sa.Text, nullable=False, comment="문서 본문"),
+        sa.Column("category", sa.String(50), nullable=True, comment="카테고리"),
+        sa.Column(
+            "chunk_index",
+            sa.Integer,
+            server_default="0",
+            comment="청크 인덱스",
+        ),
+        sa.Column(
+            "total_chunks",
+            sa.Integer,
+            server_default="1",
+            comment="전체 청크 수",
+        ),
+        sa.Column(
+            "reliability_score",
+            sa.Float,
+            server_default="0.6",
+            comment="신뢰도 점수 (0.0~1.0)",
+        ),
+        sa.Column("valid_from", sa.DateTime(timezone=True), nullable=True, comment="유효 시작일"),
+        sa.Column("valid_until", sa.DateTime(timezone=True), nullable=True, comment="유효 종료일"),
+        sa.Column(
+            "status",
+            sa.String(20),
+            server_default=sa.text("'active'"),
+            comment="문서 상태: active, expired, deprecated",
+        ),
+        sa.Column(
+            "version",
+            sa.String(20),
+            server_default=sa.text("'1.0'"),
+            comment="문서 버전",
+        ),
+        # 확장 메타데이터 (JSONB)
+        sa.Column(
+            "metadata",
+            JSONB,
+            server_default=sa.text("'{}'::jsonb"),
+            comment="추가 메타데이터 (JSONB)",
+        ),
+        # CASE 타입 전용
+        sa.Column("complaint_text", sa.Text, nullable=True, comment="민원 텍스트 (CASE 전용)"),
+        sa.Column("answer_text", sa.Text, nullable=True, comment="답변 텍스트 (CASE 전용)"),
+        # LAW 타입 전용
+        sa.Column("law_number", sa.String(100), nullable=True, comment="법률 번호 (LAW 전용)"),
+        sa.Column("article_number", sa.String(50), nullable=True, comment="조항 번호 (LAW 전용)"),
+        sa.Column("enforcement_date", sa.Date, nullable=True, comment="시행일 (LAW 전용)"),
+        # MANUAL 타입 전용
+        sa.Column("department", sa.String(100), nullable=True, comment="담당 부서 (MANUAL 전용)"),
+        # NOTICE 타입 전용
+        sa.Column(
+            "notice_number", sa.String(100), nullable=True, comment="공시 번호 (NOTICE 전용)"
+        ),
+        sa.Column("effective_date", sa.Date, nullable=True, comment="시행일 (NOTICE 전용)"),
+        # 인덱싱 관련
+        sa.Column("faiss_index_id", sa.Integer, nullable=True, comment="FAISS 인덱스 내 ID"),
+        sa.Column(
+            "embedding_version",
+            sa.String(50),
+            server_default=sa.text("'e5-large-v1'"),
+            comment="임베딩 모델 버전",
+        ),
+        # 타임스탬프
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            comment="생성 시각",
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            comment="수정 시각",
+        ),
+        # UNIQUE 제약조건
+        sa.UniqueConstraint(
+            "source_type",
+            "source_id",
+            "chunk_index",
+            name="uq_source_type_source_id_chunk",
+        ),
+        # CHECK 제약조건
+        sa.CheckConstraint(
+            "source_type IN ('case', 'law', 'manual', 'notice')",
+            name="ck_source_type_valid",
+        ),
+        sa.CheckConstraint(
+            "status IN ('active', 'expired', 'deprecated')",
+            name="ck_status_valid",
+        ),
+        sa.CheckConstraint(
+            "reliability_score >= 0.0 AND reliability_score <= 1.0",
+            name="ck_reliability_score_range",
+        ),
+    )
+
+    # document_source B-tree 인덱스
+    op.create_index("idx_docsource_source_type", "document_source", ["source_type"])
+    op.create_index("idx_docsource_status", "document_source", ["status"])
+    op.create_index("idx_docsource_category", "document_source", ["category"])
+    op.create_index("idx_docsource_valid_range", "document_source", ["valid_from", "valid_until"])
+
+    # document_source GIN 인덱스 - JSONB 검색용
+    op.create_index(
+        "idx_docsource_metadata",
+        "document_source",
+        ["metadata"],
+        postgresql_using="gin",
+    )
+
+    # ------------------------------------------------------------------
+    # 2. indexing_queue 테이블
+    # ------------------------------------------------------------------
+    op.create_table(
+        "indexing_queue",
+        # PK
+        sa.Column(
+            "id",
+            UUID(as_uuid=True),
+            server_default=sa.text("gen_random_uuid()"),
+            primary_key=True,
+            comment="큐 항목 고유 식별자",
+        ),
+        # document_source FK
+        sa.Column(
+            "document_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("document_source.id", ondelete="SET NULL"),
+            nullable=True,
+            comment="연결된 문서 원본 ID",
+        ),
+        # 참조 필드 (FK 없는 UUID - 참조 테이블 미존재)
+        sa.Column(
+            "session_id",
+            UUID(as_uuid=True),
+            nullable=True,
+            comment="상담 세션 ID (FK 없음)",
+        ),
+        sa.Column(
+            "message_id",
+            UUID(as_uuid=True),
+            nullable=True,
+            comment="메시지 ID (FK 없음)",
+        ),
+        # 큐 데이터
+        sa.Column(
+            "doc_type",
+            sa.String(20),
+            server_default=sa.text("'CASE'"),
+            comment="문서 타입",
+        ),
+        sa.Column("complaint_text", sa.Text, nullable=False, comment="민원 텍스트"),
+        sa.Column("answer_text", sa.Text, nullable=False, comment="답변 텍스트"),
+        sa.Column("category", sa.String(50), nullable=True, comment="카테고리"),
+        sa.Column(
+            "status",
+            sa.String(20),
+            server_default=sa.text("'pending'"),
+            comment="처리 상태: pending, processing, completed, skipped, failed",
+        ),
+        sa.Column(
+            "priority",
+            sa.Integer,
+            server_default="0",
+            comment="우선순위 (높을수록 먼저)",
+        ),
+        sa.Column("skip_reason", sa.String(200), nullable=True, comment="건너뛰기 사유"),
+        # 타임스탬프
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            comment="생성 시각",
+        ),
+        sa.Column(
+            "processed_at",
+            sa.DateTime(timezone=True),
+            nullable=True,
+            comment="처리 완료 시각",
+        ),
+        # CHECK 제약조건
+        sa.CheckConstraint(
+            "status IN ('pending', 'processing', 'completed', 'skipped', 'failed')",
+            name="ck_queue_status_valid",
+        ),
+    )
+
+    # indexing_queue 인덱스
+    op.create_index("idx_indexqueue_status", "indexing_queue", ["status"])
+    op.create_index("idx_indexqueue_priority", "indexing_queue", ["priority", "created_at"])
+    op.create_index("idx_indexqueue_document_id", "indexing_queue", ["document_id"])
+
+    # ------------------------------------------------------------------
+    # 3. index_version 테이블
+    # ------------------------------------------------------------------
+    op.create_table(
+        "index_version",
+        # PK
+        sa.Column(
+            "id",
+            UUID(as_uuid=True),
+            server_default=sa.text("gen_random_uuid()"),
+            primary_key=True,
+            comment="인덱스 버전 고유 식별자",
+        ),
+        # 인덱스 정보
+        sa.Column(
+            "index_type",
+            sa.String(20),
+            nullable=False,
+            comment="인덱스 타입 (case, law, manual, notice)",
+        ),
+        sa.Column("version", sa.String(50), nullable=False, comment="인덱스 버전"),
+        sa.Column("total_documents", sa.Integer, nullable=False, comment="포함 문서 수"),
+        sa.Column(
+            "index_file_path",
+            sa.String(500),
+            nullable=False,
+            comment="FAISS ���덱스 파일 경로",
+        ),
+        sa.Column(
+            "meta_file_path",
+            sa.String(500),
+            nullable=False,
+            comment="메타데이터 파일 경로",
+        ),
+        sa.Column(
+            "snapshot_path",
+            sa.Text,
+            nullable=True,
+            comment="스냅샷 경로",
+        ),
+        # 상태
+        sa.Column(
+            "built_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            comment="빌드 시각",
+        ),
+        sa.Column(
+            "is_active",
+            sa.Boolean,
+            server_default=sa.text("true"),
+            comment="활성 버전 여부",
+        ),
+        sa.Column(
+            "build_duration_seconds",
+            sa.Float,
+            nullable=True,
+            comment="빌드 소요 시간 (초)",
+        ),
+        sa.Column("notes", sa.Text, nullable=True, comment="비고"),
+    )
+
+    # index_version 인덱스
+    op.create_index("idx_indexversion_active", "index_version", ["index_type", "is_active"])
+
+    # ------------------------------------------------------------------
+    # 4. updated_at 자동 갱신 트리거 (document_source)
+    # ------------------------------------------------------------------
+    op.execute("""
+        CREATE OR REPLACE FUNCTION update_updated_at_column()
+        RETURNS TRIGGER AS $$
+        BEGIN
+            NEW.updated_at = NOW();
+            RETURN NEW;
+        END;
+        $$ LANGUAGE plpgsql;
+    """)
+
+    op.execute("""
+        CREATE TRIGGER trg_docsource_updated_at
+        BEFORE UPDATE ON document_source
+        FOR EACH ROW
+        EXECUTE FUNCTION update_updated_at_column();
+    """)
+
+
+def downgrade() -> None:
+    # 트리거 및 함수 제거
+    op.execute("DROP TRIGGER IF EXISTS trg_docsource_updated_at ON document_source;")
+    op.execute("DROP FUNCTION IF EXISTS update_updated_at_column();")
+
+    # 테이블 제거 (의존성 역순)
+    op.drop_table("index_version")
+    op.drop_table("indexing_queue")
+    op.drop_table("document_source")

src/inference/db/converters.py

@@ -0,0 +1,162 @@
+"""
+ORM <-> Dataclass / Pydantic 변환 헬퍼.
+
+DocumentSource ORM 인스턴스를 기존 DocumentMetadata(dataclass) 또는
+DocumentMetadataSchema(Pydantic) 모델로 상호 변환한다.
+"""
+
+from typing import Any, Dict
+
+from src.inference.db.models import DocumentSource
+from src.inference.index_manager import DocumentMetadata, IndexType
+from src.inference.schemas import DocumentMetadataSchema
+
+# 타입별 전용 필드 목록 (ORM <-> Dataclass/Pydantic 변환 시 공통 사용)
+_TYPE_SPECIFIC_FIELDS: tuple = (
+    "complaint_text",
+    "answer_text",  # CASE
+    "law_number",
+    "article_number",  # LAW
+    "enforcement_date",  # LAW
+    "department",  # MANUAL
+    "notice_number",
+    "effective_date",  # NOTICE
+)
+
+
+# ---------------------------------------------------------------------------
+# ORM -> Dataclass
+# ---------------------------------------------------------------------------
+
+
+def orm_to_dataclass(doc_source: DocumentSource) -> DocumentMetadata:
+    """DocumentSource ORM -> DocumentMetadata dataclass 변환.
+
+    ORM의 타입별 전용 필드(complaint_text, law_number 등)는
+    extras dict에 모아서 전달한다.
+    """
+    # 타입별 추가 필드를 extras로 수집
+    extras: Dict[str, Any] = {}
+    if doc_source.metadata_:
+        extras.update(doc_source.metadata_)
+
+    for field_name in _TYPE_SPECIFIC_FIELDS:
+        value = getattr(doc_source, field_name, None)
+        if value is not None:
+            # date/datetime 객체는 ISO 문자열로 직렬화
+            extras[field_name] = value.isoformat() if hasattr(value, "isoformat") else value
+
+    return DocumentMetadata(
+        doc_id=str(doc_source.id),
+        doc_type=doc_source.source_type,
+        source=doc_source.source_name or "",
+        title=doc_source.title,
+        category=doc_source.category or "",
+        reliability_score=doc_source.reliability_score,
+        created_at=doc_source.created_at.isoformat(),
+        updated_at=doc_source.updated_at.isoformat(),
+        valid_from=(doc_source.valid_from.isoformat() if doc_source.valid_from else None),
+        valid_until=(doc_source.valid_until.isoformat() if doc_source.valid_until else None),
+        chunk_index=doc_source.chunk_index,
+        chunk_total=doc_source.total_chunks,
+        extras=extras,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Dataclass -> ORM create kwargs
+# ---------------------------------------------------------------------------
+
+
+def dataclass_to_orm(meta: DocumentMetadata, content: str) -> Dict[str, Any]:
+    """DocumentMetadata dataclass -> DocumentSource 생성용 kwargs 딕셔너리.
+
+    Parameters
+    ----------
+    meta : DocumentMetadata
+        내부 dataclass 인스턴스.
+    content : str
+        문서 본문 텍스트 (dataclass에는 content가 없음).
+
+    Returns
+    -------
+    dict
+        crud.create_document_source()에 전달할 kwargs.
+    """
+    extras = dict(meta.extras) if meta.extras else {}
+
+    kwargs: Dict[str, Any] = {
+        "source_type": meta.doc_type,
+        "source_id": meta.doc_id,
+        "source_name": meta.source,
+        "title": meta.title,
+        "content": content,
+        "category": meta.category,
+        "chunk_index": meta.chunk_index,
+        "total_chunks": meta.chunk_total,
+        "reliability_score": meta.reliability_score,
+        "metadata_": {},
+    }
+
+    # ISO 문자열 -> datetime 변환 (valid_from/valid_until)
+    from datetime import datetime
+
+    if meta.valid_from:
+        kwargs["valid_from"] = datetime.fromisoformat(meta.valid_from)
+    if meta.valid_until:
+        kwargs["valid_until"] = datetime.fromisoformat(meta.valid_until)
+
+    # extras에서 타입별 전용 필드 추출
+    _type_field_map = {
+        "complaint_text": str,
+        "answer_text": str,
+        "law_number": str,
+        "article_number": str,
+        "enforcement_date": str,  # DATE 컬럼이므로 문자열 그대로 전달
+        "department": str,
+        "notice_number": str,
+        "effective_date": str,
+    }
+    remaining_extras: Dict[str, Any] = {}
+    for key, value in extras.items():
+        if key in _type_field_map:
+            kwargs[key] = value
+        else:
+            remaining_extras[key] = value
+
+    kwargs["metadata_"] = remaining_extras
+    return kwargs
+
+
+# ---------------------------------------------------------------------------
+# ORM -> Pydantic
+# ---------------------------------------------------------------------------
+
+
+def orm_to_pydantic(doc_source: DocumentSource) -> DocumentMetadataSchema:
+    """DocumentSource ORM -> DocumentMetadataSchema Pydantic 모델 변환."""
+    # 타입별 추가 필드 + JSONB metadata를 합산
+    extra_meta: Dict[str, Any] = {}
+    if doc_source.metadata_:
+        extra_meta.update(doc_source.metadata_)
+
+    for field_name in _TYPE_SPECIFIC_FIELDS:
+        value = getattr(doc_source, field_name, None)
+        if value is not None:
+            extra_meta[field_name] = value.isoformat() if hasattr(value, "isoformat") else value
+
+    return DocumentMetadataSchema(
+        doc_id=str(doc_source.id),
+        source_type=IndexType(doc_source.source_type),
+        source_id=doc_source.source_id,
+        title=doc_source.title,
+        content=doc_source.content,
+        chunk_index=doc_source.chunk_index,
+        total_chunks=doc_source.total_chunks,
+        created_at=doc_source.created_at,
+        updated_at=doc_source.updated_at,
+        valid_from=doc_source.valid_from,
+        valid_until=doc_source.valid_until,
+        reliability_score=doc_source.reliability_score,
+        metadata=extra_meta,
+    )

src/inference/db/crud.py

@@ -0,0 +1,306 @@
+"""
+CRUD 레이어 (Unit of Work 패턴).
+
+DocumentSource, IndexingQueue, IndexVersion 테이블에 대한
+생성/조회/수정/삭제 함수를 제공한다.
+모든 함수는 동기 Session을 인자로 받는다.
+
+이 모듈의 함수들은 내부에서 commit을 수행하지 않는다.
+트랜잭션의 commit/rollback 제어는 caller(서비스 계층)의 책임이다.
+복합 작업의 원자성을 보장하기 위해 flush만 수행하여 DB에 SQL을 전송하되,
+최종 확정은 caller가 결정한다.
+"""
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from sqlalchemy import func, select, update
+from sqlalchemy.orm import Session
+
+from src.inference.db.models import DocumentSource, IndexingQueue, IndexVersion
+
+# ---------------------------------------------------------------------------
+# 상수 정의
+# ---------------------------------------------------------------------------
+
+MAX_LIMIT = 1000
+
+_ALLOWED_FILTER_COLUMNS = frozenset(
+    {
+        "source_type",
+        "source_id",
+        "status",
+        "category",
+        "source_name",
+        "embedding_version",
+        "version",
+    }
+)
+
+_IMMUTABLE_FIELDS = frozenset({"id", "created_at"})
+
+_VALID_QUEUE_STATUSES = frozenset(
+    {
+        "pending",
+        "processing",
+        "completed",
+        "skipped",
+        "failed",
+    }
+)
+
+
+# ============================================================================
+# DocumentSource CRUD
+# ============================================================================
+
+
+def create_document_source(db: Session, **kwargs: Any) -> DocumentSource:
+    """새 문서 원본 레코드를 생성한다."""
+    doc = DocumentSource(**kwargs)
+    db.add(doc)
+    db.flush()
+    db.refresh(doc)
+    return doc
+
+
+def get_document_source(db: Session, doc_id: uuid.UUID) -> Optional[DocumentSource]:
+    """ID로 문서 원본을 조회한다."""
+    return db.get(DocumentSource, doc_id)
+
+
+def get_document_sources(
+    db: Session,
+    filters: Optional[Dict[str, Any]] = None,
+    skip: int = 0,
+    limit: int = 100,
+) -> List[DocumentSource]:
+    """필터 조건에 맞는 문서 원본 목록을 조회한다.
+
+    Parameters
+    ----------
+    filters : dict, optional
+        컬럼명-값 쌍의 필터 딕셔너리.
+        예: {"source_type": "case", "status": "active"}
+    skip : int
+        건너뛸 행 수 (페이지네이션 오프셋).
+    limit : int
+        최대 반환 행 수.
+    """
+    limit = min(limit, MAX_LIMIT)
+    stmt = select(DocumentSource)
+
+    if filters:
+        for col_name, value in filters.items():
+            if col_name in _ALLOWED_FILTER_COLUMNS:
+                stmt = stmt.where(getattr(DocumentSource, col_name) == value)
+
+    stmt = stmt.offset(skip).limit(limit).order_by(DocumentSource.created_at.desc())
+    return list(db.scalars(stmt).all())
+
+
+def update_document_source(
+    db: Session, doc_id: uuid.UUID, **kwargs: Any
+) -> Optional[DocumentSource]:
+    """문서 원본 레코드를 수정한다.
+
+    변경할 컬럼-값을 kwargs로 전달한다.
+    """
+    doc = db.get(DocumentSource, doc_id)
+    if doc is None:
+        return None
+
+    for key, value in kwargs.items():
+        if key in _IMMUTABLE_FIELDS:
+            continue
+        if hasattr(doc, key):
+            setattr(doc, key, value)
+
+    db.flush()
+    db.refresh(doc)
+    return doc
+
+
+def delete_document_source(db: Session, doc_id: uuid.UUID) -> bool:
+    """문서 원본 레코드를 삭제한다. 성공 시 True 반환."""
+    doc = db.get(DocumentSource, doc_id)
+    if doc is None:
+        return False
+
+    db.delete(doc)
+    db.flush()
+    return True
+
+
+def get_by_source_type_and_id(
+    db: Session, source_type: str, source_id: str
+) -> List[DocumentSource]:
+    """source_type + source_id 조합으로 문서를 조회한다.
+
+    동일 문서의 여러 청크가 반환될 수 있으므로 리스트를 반환한다.
+    """
+    stmt = (
+        select(DocumentSource)
+        .where(
+            DocumentSource.source_type == source_type,
+            DocumentSource.source_id == source_id,
+        )
+        .order_by(DocumentSource.chunk_index)
+    )
+    return list(db.scalars(stmt).all())
+
+
+# ============================================================================
+# IndexingQueue CRUD
+# ============================================================================
+
+
+def create_indexing_queue_item(db: Session, **kwargs: Any) -> IndexingQueue:
+    """인덱싱 대기열에 새 항목을 추가한다."""
+    item = IndexingQueue(**kwargs)
+    db.add(item)
+    db.flush()
+    db.refresh(item)
+    return item
+
+
+def get_pending_items(db: Session, limit: int = 50) -> List[IndexingQueue]:
+    """pending 상태의 대기열 항목을 우선순위 내림차순으로 조회한다."""
+    limit = min(limit, MAX_LIMIT)
+    stmt = (
+        select(IndexingQueue)
+        .where(IndexingQueue.status == "pending")
+        .order_by(IndexingQueue.priority.desc(), IndexingQueue.created_at)
+        .limit(limit)
+    )
+    return list(db.scalars(stmt).all())
+
+
+def update_queue_status(
+    db: Session,
+    item_id: uuid.UUID,
+    status: str,
+    skip_reason: Optional[str] = None,
+) -> Optional[IndexingQueue]:
+    """대기열 항목의 상태를 변경한다.
+
+    completed/failed 상태로 변경 시 processed_at을 자동 설정한다.
+    """
+    if status not in _VALID_QUEUE_STATUSES:
+        raise ValueError(
+            f"유효하지 않은 상태: {status!r}. "
+            f"허용 값: {', '.join(sorted(_VALID_QUEUE_STATUSES))}"
+        )
+
+    item = db.get(IndexingQueue, item_id)
+    if item is None:
+        return None
+
+    item.status = status
+    if skip_reason is not None:
+        item.skip_reason = skip_reason
+
+    if status in ("completed", "failed", "skipped"):
+        item.processed_at = datetime.now(timezone.utc)
+
+    db.flush()
+    db.refresh(item)
+    return item
+
+
+def get_queue_stats(db: Session) -> Dict[str, int]:
+    """대기열 상태별 건수를 집계한다.
+
+    Returns
+    -------
+    dict
+        {"pending": 10, "processing": 2, "completed": 50, ...}
+    """
+    stmt = select(IndexingQueue.status, func.count()).group_by(IndexingQueue.status)
+    rows = db.execute(stmt).all()
+    return {status: count for status, count in rows}
+
+
+# ============================================================================
+# IndexVersion CRUD
+# ============================================================================
+
+
+def create_index_version(db: Session, **kwargs: Any) -> IndexVersion:
+    """새 인덱스 버전 레코드를 생성한다."""
+    ver = IndexVersion(**kwargs)
+    db.add(ver)
+    db.flush()
+    db.refresh(ver)
+    return ver
+
+
+def get_active_version(db: Session, index_type: str) -> Optional[IndexVersion]:
+    """특정 index_type의 활성 버전을 조회한다.
+
+    index_type별로 active 버전은 최대 1개여야 한다.
+    """
+    stmt = (
+        select(IndexVersion)
+        .where(
+            IndexVersion.index_type == index_type,
+            IndexVersion.is_active.is_(True),
+        )
+        .order_by(IndexVersion.built_at.desc())
+        .limit(1)
+    )
+    return db.scalars(stmt).first()
+
+
+def deactivate_versions(db: Session, index_type: str) -> int:
+    """특정 index_type의 모든 활성 버전을 비활성화한다.
+
+    새 인덱스를 활성화하기 전에 호출하여 단일 활성 버전을 보장한다.
+
+    Returns
+    -------
+    int
+        비활성화된 레코드 수.
+    """
+    stmt = (
+        update(IndexVersion)
+        .where(
+            IndexVersion.index_type == index_type,
+            IndexVersion.is_active.is_(True),
+        )
+        .values(is_active=False)
+    )
+    result = db.execute(stmt)
+    db.flush()
+    return result.rowcount  # type: ignore[return-value]
+
+
+def activate_version(db: Session, version_id: uuid.UUID) -> Optional[IndexVersion]:
+    """특정 인덱스 버전을 활성화한다.
+
+    동일 index_type의 기존 활성 버전을 먼저 비활성화한 뒤 대상을 활성화한다.
+
+    Race Condition 방지:
+        SELECT ... FOR UPDATE로 동일 index_type의 모든 버전에 행 레벨 잠금을
+        획득한 뒤 deactivate/activate를 수행한다. 동시 호출 시 후발 트랜잭션은
+        잠금 해제까지 대기하므로 다중 active 버전이 생기는 문제를 방지한다.
+        (PostgreSQL 전용 — SQLite는 FOR UPDATE를 지원하지 않는다.)
+    """
+    ver = db.get(IndexVersion, version_id)
+    if ver is None:
+        return None
+
+    # 동일 index_type의 모든 버전에 대해 행 레벨 잠금 획득 (PostgreSQL 전용)
+    lock_stmt = (
+        select(IndexVersion).where(IndexVersion.index_type == ver.index_type).with_for_update()
+    )
+    db.execute(lock_stmt)
+
+    # 잠금 획득 후 동일 타입의 기존 활성 버전 비활성화
+    deactivate_versions(db, ver.index_type)
+
+    ver.is_active = True
+    db.flush()
+    db.refresh(ver)
+    return ver

src/inference/db/database.py

@@ -0,0 +1,77 @@
+"""
+SQLAlchemy 2.0 데이터베이스 엔진/세션 설정.
+
+동기 세션 기반으로 구성하며, FastAPI 의존성 주입(get_db)을 제공한다.
+기본값은 로컬 단일 사용자 MVP에 맞춰 GovOn 홈 디렉터리 아래 SQLite 파일을 사용한다.
+"""
+
+import logging
+import os
+from pathlib import Path
+from typing import Generator
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session, sessionmaker
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# 엔진 & 세션 팩토리
+# ---------------------------------------------------------------------------
+
+_DEFAULT_GOVON_HOME = Path(os.getenv("GOVON_HOME", Path.home() / ".govon"))
+_DEFAULT_DATABASE_URL = f"sqlite:///{_DEFAULT_GOVON_HOME / 'metadata.sqlite3'}"
+
+DATABASE_URL: str = os.getenv("DATABASE_URL", _DEFAULT_DATABASE_URL)
+
+if DATABASE_URL == _DEFAULT_DATABASE_URL:
+    logger.warning(
+        "DATABASE_URL 환경변수가 설정되지 않아 로컬 SQLite 기본값을 사용합니다. "
+        "별도 RDBMS를 사용하려면 DATABASE_URL을 명시적으로 설정하세요."
+    )
+
+engine_kwargs = {
+    "echo": os.getenv("SQL_ECHO", "").lower() in ("1", "true"),
+}
+if DATABASE_URL.startswith("sqlite:///"):
+    _DEFAULT_GOVON_HOME.mkdir(parents=True, exist_ok=True)
+    engine_kwargs["connect_args"] = {"check_same_thread": False}
+else:
+    engine_kwargs.update(
+        {
+            "pool_size": 10,
+            "max_overflow": 20,
+            "pool_pre_ping": True,
+            "pool_recycle": 3600,
+        }
+    )
+
+engine = create_engine(DATABASE_URL, **engine_kwargs)
+
+SessionLocal = sessionmaker(
+    bind=engine,
+    autocommit=False,
+    autoflush=False,
+)
+
+
+# ---------------------------------------------------------------------------
+# FastAPI 의존성 주입
+# ---------------------------------------------------------------------------
+
+
+def get_db() -> Generator[Session, None, None]:
+    """FastAPI Depends()용 세션 제너레이터.
+
+    사용 예시::
+
+        @router.get("/docs")
+        def list_docs(db: Session = Depends(get_db)):
+            ...
+    """
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.rollback()
+        db.close()

src/inference/db/models.py

@@ -0,0 +1,448 @@
+"""
+SQLAlchemy 2.0 ORM 모델.
+
+ADR-004 + Issue #152 병합 스키마 기반 3개 테이블:
+- DocumentSource  : 문서 원본 메타데이터
+- IndexingQueue   : 인덱싱 대기열
+- IndexVersion    : FAISS 인덱스 버전 관리
+
+모든 모델은 SQLAlchemy 2.0 Mapped 스타일(mapped_column, Mapped)을 사용하며,
+server_default로 DB 레벨 기본값을 지정한다.
+"""
+
+import uuid
+from datetime import date, datetime
+from typing import Any, Dict, List, Optional
+
+from sqlalchemy import (
+    Boolean,
+    CheckConstraint,
+    Date,
+    DateTime,
+    Float,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+    func,
+    text,
+)
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import (
+    DeclarativeBase,
+    Mapped,
+    mapped_column,
+    relationship,
+)
+
+# ---------------------------------------------------------------------------
+# Base 클래스
+# ---------------------------------------------------------------------------
+
+
+class Base(DeclarativeBase):
+    """모든 ORM 모델의 공통 기반 클래스."""
+
+    pass
+
+
+# ---------------------------------------------------------------------------
+# DocumentSource
+# ---------------------------------------------------------------------------
+
+
+class DocumentSource(Base):
+    """document_source 테이블 ORM 모델.
+
+    모든 문서 타입(case, law, manual, notice)의 메타데이터를 통합 관리한다.
+    타입별 전용 컬럼은 nullable로 처리하며, 해당하지 않는 타입에서는 NULL이다.
+    """
+
+    __tablename__ = "document_source"
+    __table_args__ = (
+        UniqueConstraint(
+            "source_type",
+            "source_id",
+            "chunk_index",
+            name="uq_source_type_source_id_chunk",
+        ),
+        CheckConstraint(
+            "source_type IN ('case', 'law', 'manual', 'notice')",
+            name="ck_source_type_valid",
+        ),
+        CheckConstraint(
+            "status IN ('active', 'expired', 'deprecated')",
+            name="ck_status_valid",
+        ),
+        CheckConstraint(
+            "reliability_score >= 0.0 AND reliability_score <= 1.0",
+            name="ck_reliability_score_range",
+        ),
+        # 성능 인덱스
+        Index("idx_docsource_source_type", "source_type"),
+        Index("idx_docsource_status", "status"),
+        Index("idx_docsource_category", "category"),
+        Index("idx_docsource_valid_range", "valid_from", "valid_until"),
+        Index("idx_docsource_metadata", "metadata", postgresql_using="gin"),
+    )
+
+    # -- 기본 키 --
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+        comment="문서 고유 식별자",
+    )
+
+    # -- 공통 필드 --
+    source_type: Mapped[str] = mapped_column(
+        String(20),
+        nullable=False,
+        comment="문서 타입: case, law, manual, notice",
+    )
+    source_id: Mapped[str] = mapped_column(
+        String(255),
+        nullable=False,
+        comment="원본 문서 식별자",
+    )
+    source_name: Mapped[Optional[str]] = mapped_column(
+        String(200),
+        nullable=True,
+        comment="출처명 (AI Hub, 법제처 등)",
+    )
+    title: Mapped[str] = mapped_column(
+        String(500),
+        nullable=False,
+        comment="문서 제목",
+    )
+    content: Mapped[str] = mapped_column(
+        Text,
+        nullable=False,
+        comment="문서 본문",
+    )
+    category: Mapped[Optional[str]] = mapped_column(
+        String(50),
+        nullable=True,
+        comment="카테고리 (도로/교통, 환경/위생 등)",
+    )
+    chunk_index: Mapped[int] = mapped_column(
+        Integer,
+        server_default=text("0"),
+        comment="청크 인덱스",
+    )
+    total_chunks: Mapped[int] = mapped_column(
+        Integer,
+        server_default=text("1"),
+        comment="전체 청크 수",
+    )
+    reliability_score: Mapped[float] = mapped_column(
+        Float,
+        server_default=text("0.6"),
+        comment="신뢰도 점수 (0.0~1.0)",
+    )
+    valid_from: Mapped[Optional[datetime]] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+        comment="유효 시작일",
+    )
+    valid_until: Mapped[Optional[datetime]] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+        comment="유효 종료일",
+    )
+    status: Mapped[str] = mapped_column(
+        String(20),
+        server_default=text("'active'"),
+        comment="문서 상태: active, expired, deprecated",
+    )
+    version: Mapped[str] = mapped_column(
+        String(20),
+        server_default=text("'1.0'"),
+        comment="문서 버전",
+    )
+    # 'metadata'는 SQLAlchemy 내부 예약어이므로 Python 속성은 metadata_로 매핑
+    metadata_: Mapped[Dict[str, Any]] = mapped_column(
+        "metadata",
+        JSONB,
+        server_default=text("'{}'::jsonb"),
+        comment="추가 메타데이터 (JSONB)",
+    )
+
+    # -- CASE 전용 --
+    complaint_text: Mapped[Optional[str]] = mapped_column(
+        Text,
+        nullable=True,
+        comment="민원 텍스트 (CASE 전용)",
+    )
+    answer_text: Mapped[Optional[str]] = mapped_column(
+        Text,
+        nullable=True,
+        comment="답변 텍스트 (CASE 전용)",
+    )
+
+    # -- LAW 전용 --
+    law_number: Mapped[Optional[str]] = mapped_column(
+        String(100),
+        nullable=True,
+        comment="법률 번호 (LAW 전용)",
+    )
+    article_number: Mapped[Optional[str]] = mapped_column(
+        String(50),
+        nullable=True,
+        comment="조항 번호 (LAW 전용)",
+    )
+    enforcement_date: Mapped[Optional[date]] = mapped_column(
+        Date,
+        nullable=True,
+        comment="시행일 (LAW 전용)",
+    )
+
+    # -- MANUAL 전용 --
+    department: Mapped[Optional[str]] = mapped_column(
+        String(100),
+        nullable=True,
+        comment="담당 부서 (MANUAL 전용)",
+    )
+
+    # -- NOTICE 전용 --
+    notice_number: Mapped[Optional[str]] = mapped_column(
+        String(100),
+        nullable=True,
+        comment="공시 번호 (NOTICE 전용)",
+    )
+    effective_date: Mapped[Optional[date]] = mapped_column(
+        Date,
+        nullable=True,
+        comment="시행일 (NOTICE 전용)",
+    )
+
+    # -- 인덱싱 관련 --
+    faiss_index_id: Mapped[Optional[int]] = mapped_column(
+        Integer,
+        nullable=True,
+        comment="FAISS 인덱스 내 ID",
+    )
+    embedding_version: Mapped[str] = mapped_column(
+        String(50),
+        server_default=text("'e5-large-v1'"),
+        comment="임베딩 모델 버전",
+    )
+
+    # -- 타임스탬프 --
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        comment="생성 시각",
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+        comment="수정 시각",
+    )
+
+    # -- 관계 --
+    queue_items: Mapped[List["IndexingQueue"]] = relationship(
+        back_populates="document",
+        cascade="all, delete-orphan",
+        lazy="select",
+    )
+
+    def __repr__(self) -> str:
+        return f"<DocumentSource(id={self.id}, " f"type={self.source_type}, title={self.title!r})>"
+
+
+# ---------------------------------------------------------------------------
+# IndexingQueue
+# ---------------------------------------------------------------------------
+
+
+class IndexingQueue(Base):
+    """indexing_queue 테이블 ORM 모델.
+
+    새로운 민원 상담이 들어오면 인덱싱 대기열에 추가되며,
+    배치 프로세스가 주기적으로 pending 항목을 소비한다.
+    """
+
+    __tablename__ = "indexing_queue"
+    __table_args__ = (
+        CheckConstraint(
+            "status IN ('pending', 'processing', 'completed', 'skipped', 'failed')",
+            name="ck_queue_status_valid",
+        ),
+        # 성능 인덱스
+        Index("idx_indexqueue_status", "status"),
+        Index("idx_indexqueue_priority", "priority", "created_at"),
+        Index("idx_indexqueue_document_id", "document_id"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+        comment="큐 항목 고유 식별자",
+    )
+    document_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("document_source.id", ondelete="SET NULL"),
+        nullable=True,
+        comment="연결된 문서 원본 ID",
+    )
+    session_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        nullable=True,
+        comment="상담 세션 ID (FK 없음)",
+    )
+    message_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        nullable=True,
+        comment="메시지 ID (FK 없음)",
+    )
+    doc_type: Mapped[str] = mapped_column(
+        String(20),
+        server_default=text("'CASE'"),
+        comment="문서 타입",
+    )
+    complaint_text: Mapped[str] = mapped_column(
+        Text,
+        nullable=False,
+        comment="민원 텍스트",
+    )
+    answer_text: Mapped[str] = mapped_column(
+        Text,
+        nullable=False,
+        comment="답변 텍스트",
+    )
+    category: Mapped[Optional[str]] = mapped_column(
+        String(50),
+        nullable=True,
+        comment="카테고리",
+    )
+    status: Mapped[str] = mapped_column(
+        String(20),
+        server_default=text("'pending'"),
+        comment="처리 상태: pending, processing, completed, skipped, failed",
+    )
+    priority: Mapped[int] = mapped_column(
+        Integer,
+        server_default=text("0"),
+        comment="우선순위 (높을수록 먼저)",
+    )
+    skip_reason: Mapped[Optional[str]] = mapped_column(
+        String(200),
+        nullable=True,
+        comment="건너뛰기 사유",
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        comment="생성 시각",
+    )
+    processed_at: Mapped[Optional[datetime]] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+        comment="처리 완료 시각",
+    )
+
+    # -- 관계 --
+    document: Mapped[Optional["DocumentSource"]] = relationship(
+        back_populates="queue_items",
+        lazy="select",
+    )
+
+    def __repr__(self) -> str:
+        return f"<IndexingQueue(id={self.id}, " f"status={self.status}, doc_type={self.doc_type})>"
+
+
+# ---------------------------------------------------------------------------
+# IndexVersion
+# ---------------------------------------------------------------------------
+
+
+class IndexVersion(Base):
+    """index_version 테이블 ORM 모델.
+
+    FAISS 인덱스 빌드 이력을 관리하며,
+    index_type별로 하나의 active 버전만 유지한다.
+    """
+
+    __tablename__ = "index_version"
+    __table_args__ = (
+        CheckConstraint(
+            "index_type IN ('case', 'law', 'manual', 'notice')",
+            name="ck_index_type_valid",
+        ),
+        Index("idx_indexversion_active", "index_type", "is_active"),
+        Index(
+            "uq_indexversion_one_active_per_type",
+            "index_type",
+            unique=True,
+            postgresql_where=text("is_active = true"),
+        ),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+        comment="인덱스 버전 고유 식별자",
+    )
+    index_type: Mapped[str] = mapped_column(
+        String(20),
+        nullable=False,
+        comment="인덱스 타입 (case, law, manual, notice)",
+    )
+    version: Mapped[str] = mapped_column(
+        String(50),
+        nullable=False,
+        comment="인덱스 버전 (예: v1.0.0)",
+    )
+    total_documents: Mapped[int] = mapped_column(
+        Integer,
+        nullable=False,
+        comment="포함 문서 수",
+    )
+    index_file_path: Mapped[str] = mapped_column(
+        String(500),
+        nullable=False,
+        comment="FAISS 인덱스 파일 경로",
+    )
+    meta_file_path: Mapped[str] = mapped_column(
+        String(500),
+        nullable=False,
+        comment="메타데이터 파일 경로",
+    )
+    snapshot_path: Mapped[Optional[str]] = mapped_column(
+        Text,
+        nullable=True,
+        comment="스냅샷 경로",
+    )
+    built_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        comment="빌드 시각",
+    )
+    is_active: Mapped[bool] = mapped_column(
+        Boolean,
+        server_default=text("true"),
+        comment="활성 버전 여부",
+    )
+    build_duration_seconds: Mapped[Optional[float]] = mapped_column(
+        Float,
+        nullable=True,
+        comment="빌드 소요 시간 (초)",
+    )
+    notes: Mapped[Optional[str]] = mapped_column(
+        Text,
+        nullable=True,
+        comment="비고",
+    )
+
+    def __repr__(self) -> str:
+        return (
+            f"<IndexVersion(id={self.id}, "
+            f"type={self.index_type}, version={self.version}, "
+            f"active={self.is_active})>"
+        )

src/inference/document_processor.py

@@ -0,0 +1,545 @@
+"""
+DocumentProcessor: 다형식 문서 파싱 및 하이브리드 청킹 모듈.
+
+이슈 #156 — PDF(PyMuPDF), HWP, TXT 파서를 통합하고,
+의미 단위(조/항/호, 문단) + 고정 크기(512토큰, 128토큰 오버랩) 하이브리드 청킹을 수행한다.
+
+ADR-004 Section B.3 참조.
+"""
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from loguru import logger
+
+from src.inference.index_manager import DocumentMetadata, IndexType
+
+# ---------------------------------------------------------------------------
+# 토크나이저 (토큰 기반 청킹용)
+# ---------------------------------------------------------------------------
+
+_LOAD_FAILED = object()  # 센티널: 로드 실패 확정
+_tokenizer = None  # None=미시도, _LOAD_FAILED=실패확정
+
+
+def _get_tokenizer():
+    """transformers 토크나이저를 lazy-load한다.
+
+    EXAONE 토크나이저가 없으면 단순 문자 기반 근사로 폴백.
+    로드 실패 시 센티널을 설정하여 재시도를 방지한다.
+    """
+    global _tokenizer
+    if _tokenizer is _LOAD_FAILED:
+        return None
+    if _tokenizer is not None:
+        return _tokenizer
+    try:
+        from transformers import AutoTokenizer
+
+        _tokenizer = AutoTokenizer.from_pretrained(
+            "LGAI-EXAONE/EXAONE-Deep-7.8B",
+            trust_remote_code=True,
+        )
+        logger.info("EXAONE 토크나이저 로드 완료")
+    except Exception:
+        logger.warning("EXAONE 토크나이저 로드 실패 — 문자 기반 폴백 사용")
+        _tokenizer = _LOAD_FAILED
+    return None if _tokenizer is _LOAD_FAILED else _tokenizer
+
+
+def _count_tokens(text: str) -> int:
+    """텍스트의 토큰 수를 반환한다."""
+    tok = _get_tokenizer()
+    if tok is not None:
+        return len(tok.encode(text, add_special_tokens=False))
+    # 폴백: 한국어 평균 1.5자 ≈ 1토큰 근사
+    return max(1, len(text) // 2)
+
+
+# ---------------------------------------------------------------------------
+# 파서 (PDF / HWP / TXT)
+# ---------------------------------------------------------------------------
+
+
+def _parse_pdf_pages(file_path: str) -> List[Tuple[int, str]]:
+    """PyMuPDF로 PDF의 페이지별 텍스트를 추출한다."""
+    try:
+        import fitz  # PyMuPDF
+    except ImportError as e:
+        raise ImportError("PyMuPDF가 설치되지 않았습니다: pip install PyMuPDF") from e
+
+    pages: List[Tuple[int, str]] = []
+    with fitz.open(file_path) as doc:
+        for page_number, page in enumerate(doc, start=1):
+            text = page.get_text("text")
+            if text.strip():
+                pages.append((page_number, text))
+    return pages
+
+
+def _parse_pdf(file_path: str) -> str:
+    """PyMuPDF로 PDF 텍스트를 추출한다."""
+    pages = _parse_pdf_pages(file_path)
+    return "\n\n".join(text for _, text in pages)
+
+
+def _parse_hwp(file_path: str) -> str:
+    """HWP 텍스트를 추출한다.
+
+    pyhwp 또는 호환 라이브러리가 필요하다. PyPI에 안정적인 HWP 파서가
+    없으므로 런타임 ImportError로 안내한다.
+    """
+    try:
+        import hwp
+    except ImportError as e:
+        raise ImportError(
+            "HWP 파서가 설치되지 않았습니다. " "pyhwp 또는 호환 라이브러리를 설치해 주세요."
+        ) from e
+
+    doc = hwp.open(file_path)
+    try:
+        paragraphs: List[str] = []
+        for paragraph in doc.paragraphs:
+            text = paragraph.text.strip()
+            if text:
+                paragraphs.append(text)
+        return "\n\n".join(paragraphs)
+    finally:
+        if hasattr(doc, "close"):
+            doc.close()
+
+
+def _parse_txt(file_path: str) -> str:
+    """TXT 파일을 UTF-8로 읽는다. 실패 시 cp949 폴백."""
+    path = Path(file_path)
+    for encoding in ("utf-8", "cp949", "euc-kr"):
+        try:
+            return path.read_text(encoding=encoding)
+        except (UnicodeDecodeError, LookupError):
+            continue
+    raise ValueError(f"텍스트 파일 인코딩을 식별할 수 없습니다: {file_path}")
+
+
+_PARSERS = {
+    ".pdf": _parse_pdf,
+    ".hwp": _parse_hwp,
+    ".txt": _parse_txt,
+}
+
+_PAGE_PARSERS = {
+    ".pdf": _parse_pdf_pages,
+}
+
+
+# ---------------------------------------------------------------------------
+# 텍스트 정제
+# ---------------------------------------------------------------------------
+
+# 페이지 번호, 머리글/바닥글 패턴
+_HEADER_FOOTER_RE = re.compile(
+    r"^[\s]*[-–—]?\s*\d+\s*[-–—]?\s*$",  # 페이지 번호만 있는 줄
+    re.MULTILINE,
+)
+_MULTI_NEWLINE_RE = re.compile(r"\n{3,}")
+_MULTI_SPACE_RE = re.compile(r"[ \t]{2,}")
+
+
+def _clean_text(text: str) -> str:
+    """추출된 원시 텍스트를 정제한다."""
+    text = _HEADER_FOOTER_RE.sub("", text)
+    text = _MULTI_NEWLINE_RE.sub("\n\n", text)
+    text = _MULTI_SPACE_RE.sub(" ", text)
+    return text.strip()
+
+
+# ---------------------------------------------------------------------------
+# 의미 단위 분할
+# ---------------------------------------------------------------------------
+
+# 법령: 제N조, 제N항, 제N호
+_LAW_ARTICLE_RE = re.compile(r"(?=\n\s*제\s*\d+\s*조(?:의\d+)?\s*[\(（])")
+# 문단 분할 (빈 줄 기준)
+_PARAGRAPH_RE = re.compile(r"\n\s*\n")
+
+
+def _split_semantic(text: str, doc_type: IndexType) -> List[str]:
+    """문서 타입에 따라 의미 단위로 분할한다.
+
+    - LAW: 조/항 단위
+    - MANUAL/NOTICE: 문단(빈 줄) 단위
+    - CASE: 문단 단위
+    """
+    if doc_type == IndexType.LAW:
+        segments = _LAW_ARTICLE_RE.split(text)
+    else:
+        segments = _PARAGRAPH_RE.split(text)
+
+    return [s.strip() for s in segments if s.strip()]
+
+
+# ---------------------------------------------------------------------------
+# 고정 크기 청킹 (토큰 기반)
+# ---------------------------------------------------------------------------
+
+
+def _chunk_fixed(
+    text: str,
+    chunk_size: int = 512,
+    chunk_overlap: int = 128,
+) -> List[str]:
+    """토큰 기반 고정 크기 청킹.
+
+    토크나이저가 로드된 경우 정확한 토큰 분할,
+    그렇지 않으면 문자 기반 근사 분할을 수행한다.
+    """
+    # overlap이 chunk_size 이상이면 보정 (무한루프 방지)
+    if chunk_overlap >= chunk_size:
+        chunk_overlap = chunk_size // 4
+
+    tok = _get_tokenizer()
+
+    if tok is not None:
+        token_ids = tok.encode(text, add_special_tokens=False)
+        if len(token_ids) <= chunk_size:
+            return [text]
+
+        chunks: List[str] = []
+        start = 0
+        step = max(1, chunk_size - chunk_overlap)
+        while start < len(token_ids):
+            end = min(start + chunk_size, len(token_ids))
+            chunk_text = tok.decode(token_ids[start:end], skip_special_tokens=True)
+            if chunk_text.strip():
+                chunks.append(chunk_text.strip())
+            if end >= len(token_ids):
+                break
+            start += step
+        return chunks
+
+    # 폴백: 문자 기반 근사 (한국어 ~2자 ≈ 1토큰)
+    char_size = chunk_size * 2
+    char_overlap = chunk_overlap * 2
+    if len(text) <= char_size:
+        return [text]
+
+    chunks = []
+    start = 0
+    step = max(1, char_size - char_overlap)
+    while start < len(text):
+        end = min(start + char_size, len(text))
+        chunk_text = text[start:end].strip()
+        if chunk_text:
+            chunks.append(chunk_text)
+        if end >= len(text):
+            break
+        start += step
+    return chunks
+
+
+# ---------------------------------------------------------------------------
+# 하이브리드 청킹
+# ---------------------------------------------------------------------------
+
+
+def _hybrid_chunk(
+    text: str,
+    doc_type: IndexType,
+    chunk_size: int = 512,
+    chunk_overlap: int = 128,
+    min_chunk_tokens: int = 50,
+) -> List[str]:
+    """의미 단위 + 고정 크기 하이브리드 청킹.
+
+    1단계: 의미 단위 분할 (조/항, 문단)
+    2단계: 큰 세그먼트는 고정 크기로 재분할
+    3단계: 작은 세그먼트는 인접 세그먼트와 병합
+    """
+    if not text.strip():
+        return []
+
+    segments = _split_semantic(text, doc_type)
+
+    if not segments:
+        return _chunk_fixed(text, chunk_size, chunk_overlap)
+
+    chunks: List[str] = []
+    buffer = ""
+
+    for segment in segments:
+        seg_tokens = _count_tokens(segment)
+
+        if seg_tokens > chunk_size:
+            # 버퍼에 쌓인 것 먼저 처리
+            if buffer.strip():
+                if _count_tokens(buffer) > chunk_size:
+                    chunks.extend(_chunk_fixed(buffer, chunk_size, chunk_overlap))
+                else:
+                    chunks.append(buffer.strip())
+                buffer = ""
+            # 큰 세그먼트는 고정 크기로 분할
+            chunks.extend(_chunk_fixed(segment, chunk_size, chunk_overlap))
+        elif _count_tokens(buffer + "\n\n" + segment if buffer else segment) > chunk_size:
+            # 버퍼 + 현재 세그먼트가 chunk_size를 초과하면 버퍼 flush
+            if buffer.strip():
+                chunks.append(buffer.strip())
+            buffer = segment
+        else:
+            # 버퍼에 추가
+            buffer = buffer + "\n\n" + segment if buffer else segment
+
+    # 남은 버퍼 처리
+    if buffer.strip():
+        if _count_tokens(buffer) > chunk_size:
+            chunks.extend(_chunk_fixed(buffer, chunk_size, chunk_overlap))
+        else:
+            chunks.append(buffer.strip())
+
+    # 최소 토큰 미만 청크 병합
+    merged: List[str] = []
+    for chunk in chunks:
+        if merged and _count_tokens(chunk) < min_chunk_tokens:
+            candidate = merged[-1] + "\n\n" + chunk
+            if _count_tokens(candidate) <= chunk_size:
+                merged[-1] = candidate
+                continue
+        merged.append(chunk)
+
+    return merged if merged else []
+
+
+# ---------------------------------------------------------------------------
+# BatchResult
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class BatchResult:
+    """process_batch 반환 타입. 성공/실패 정보를 모두 포함한다."""
+
+    succeeded: List[DocumentMetadata] = field(default_factory=list)
+    failed: List[Tuple[str, str]] = field(default_factory=list)  # [(file_path, error)]
+
+    @property
+    def total_chunks(self) -> int:
+        return len(self.succeeded)
+
+    @property
+    def success_count(self) -> int:
+        return self.total_chunks - len(self.failed) if not self.failed else self._count_files()
+
+    def _count_files(self) -> int:
+        seen = set()
+        for m in self.succeeded:
+            seen.add(m.extras.get("file_path", ""))
+        return len(seen)
+
+
+# ---------------------------------------------------------------------------
+# DocumentProcessor
+# ---------------------------------------------------------------------------
+
+# 문서 타입별 기본 신뢰도 (ADR-004 Table)
+_DEFAULT_RELIABILITY: Dict[IndexType, float] = {
+    IndexType.CASE: 0.6,
+    IndexType.LAW: 1.0,
+    IndexType.MANUAL: 0.9,
+    IndexType.NOTICE: 0.7,
+}
+
+
+class DocumentProcessor:
+    """다형식 문서를 파싱하고 청크 분할하여 DocumentMetadata 리스트를 반환한다.
+
+    Parameters
+    ----------
+    chunk_size : int
+        청크당 최대 토큰 수 (기본 512).
+    chunk_overlap : int
+        청크 간 오버랩 토큰 수 (기본 128, ADR-004).
+    min_chunk_tokens : int
+        최소 청크 크기. 이보다 작으면 인접 청크와 병합 (기본 50).
+    """
+
+    SUPPORTED_EXTENSIONS = frozenset(_PARSERS.keys())
+
+    def __init__(
+        self,
+        chunk_size: int = 512,
+        chunk_overlap: int = 128,
+        min_chunk_tokens: int = 50,
+    ) -> None:
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+        self.min_chunk_tokens = min_chunk_tokens
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def process(
+        self,
+        file_path: str,
+        doc_type: IndexType,
+        *,
+        source: str = "",
+        title: Optional[str] = None,
+        category: str = "",
+        reliability_score: Optional[float] = None,
+        valid_from: Optional[str] = None,
+        valid_until: Optional[str] = None,
+        extras: Optional[Dict[str, Any]] = None,
+        document_id: Optional[str] = None,
+    ) -> List[DocumentMetadata]:
+        """파일을 파싱 → 정제 → 청킹하여 DocumentMetadata 리스트를 반환한다.
+
+        Parameters
+        ----------
+        file_path : str
+            파싱할 원본 문서 경로.
+        doc_type : IndexType
+            문서의 semantic type.
+        document_id : Optional[str]
+            원본 문서 단위의 안정 ID. 지정되면 생성되는 모든 chunk가 같은 doc_id를 공유한다.
+
+        Returns
+        -------
+        List[DocumentMetadata]
+            청크별 메타데이터 리스트. doc_id는 원본 문서 단위로 동일하며,
+            청크는 chunk_index로 구분한다.
+        """
+        path = Path(file_path)
+        ext = path.suffix.lower()
+
+        if ext not in _PARSERS:
+            raise ValueError(
+                f"지원하지 않는 파일 형식: {ext} "
+                f"(지원: {', '.join(sorted(self.SUPPORTED_EXTENSIONS))})"
+            )
+
+        logger.info(f"문서 파싱 시작: {file_path} (type={doc_type.value})")
+
+        units: List[Tuple[Optional[int], str]] = []
+        page_parser = _PAGE_PARSERS.get(ext)
+        if page_parser is not None:
+            for page_number, page_text in page_parser(file_path):
+                cleaned_page = _clean_text(page_text)
+                if cleaned_page:
+                    units.append((page_number, cleaned_page))
+        else:
+            raw_text = _PARSERS[ext](file_path)
+            if not raw_text.strip():
+                logger.warning(f"빈 문서: {file_path}")
+                return []
+
+            cleaned = _clean_text(raw_text)
+            if not cleaned:
+                logger.warning(f"정제 후 빈 문서: {file_path}")
+                return []
+            units.append((None, cleaned))
+
+        if not units:
+            logger.warning(f"정제 후 빈 문서: {file_path}")
+            return []
+
+        chunk_entries: List[Tuple[str, Optional[int]]] = []
+        for page_number, cleaned_text in units:
+            chunks = _hybrid_chunk(
+                cleaned_text,
+                doc_type,
+                chunk_size=self.chunk_size,
+                chunk_overlap=self.chunk_overlap,
+                min_chunk_tokens=self.min_chunk_tokens,
+            )
+            for chunk in chunks:
+                chunk_entries.append((chunk, page_number))
+
+        if not chunk_entries:
+            logger.warning(f"청킹 결과 없음: {file_path}")
+            return []
+
+        logger.info(f"청킹 완료: {len(chunk_entries)}개 청크 생성 ({file_path})")
+
+        # 4. 메타데이터 생성
+        now_iso = datetime.now(timezone.utc).isoformat()
+        doc_title = title or path.stem
+        score = (
+            reliability_score
+            if reliability_score is not None
+            else _DEFAULT_RELIABILITY.get(doc_type, 0.5)
+        )
+        # doc_id: 원본 문서 단위 안정 ID (모든 청크가 동일)
+        doc_id = (
+            document_id or hashlib.sha256(f"{file_path}:{doc_type.value}".encode()).hexdigest()[:12]
+        )
+
+        results: List[DocumentMetadata] = []
+        for idx, (chunk, page_number) in enumerate(chunk_entries):
+            chunk_extras = dict(extras or {})
+            chunk_extras.update(
+                {
+                    "chunk_text": chunk,
+                    "file_path": str(path),
+                    "file_extension": ext,
+                    "chunk_id": f"{doc_id}:{idx}",
+                }
+            )
+            if page_number is not None:
+                chunk_extras["page"] = page_number
+
+            meta = DocumentMetadata(
+                doc_id=doc_id,
+                doc_type=doc_type.value,
+                source=source,
+                title=doc_title,
+                category=category,
+                reliability_score=score,
+                created_at=now_iso,
+                updated_at=now_iso,
+                valid_from=valid_from,
+                valid_until=valid_until,
+                chunk_index=idx,
+                chunk_total=len(chunk_entries),
+                extras=chunk_extras,
+            )
+            results.append(meta)
+
+        return results
+
+    def process_batch(
+        self,
+        file_paths: List[str],
+        doc_type: IndexType,
+        **kwargs: Any,
+    ) -> BatchResult:
+        """여러 파일을 일괄 처리한다.
+
+        Returns
+        -------
+        BatchResult
+            성공한 청크 리스트와 실패한 파일 정보를 모두 포함.
+        """
+        result = BatchResult()
+        for fp in file_paths:
+            try:
+                chunks = self.process(fp, doc_type, **kwargs)
+                result.succeeded.extend(chunks)
+            except Exception as e:
+                logger.error(f"문서 처리 실패: {fp} — {e}")
+                result.failed.append((fp, str(e)))
+        logger.info(
+            f"배치 처리 완료: {len(file_paths)}개 파일 → "
+            f"{result.total_chunks}개 청크, {len(result.failed)}개 실패"
+        )
+        return result
+
+    def parse_only(self, file_path: str) -> str:
+        """파싱 + 정제만 수행하고 텍스트를 반환한다 (청킹 없음)."""
+        ext = Path(file_path).suffix.lower()
+        if ext not in _PARSERS:
+            raise ValueError(f"지원하지 않는 파일 형식: {ext}")
+        raw = _PARSERS[ext](file_path)
+        return _clean_text(raw)

src/inference/feature_flags.py

@@ -0,0 +1,58 @@
+"""Feature Flag 관리 모듈.
+
+환경변수 기반 Feature Flag와 X-Feature-Flag 헤더를 통한 요청별 오버라이드를 지원한다.
+"""
+
+import os
+from dataclasses import asdict, dataclass
+from typing import Optional
+
+from loguru import logger
+
+
+@dataclass(frozen=True)
+class FeatureFlags:
+    """런타임 Feature Flag 설정."""
+
+    use_rag_pipeline: bool = True
+    model_version: str = "v2_lora"  # v1_lora | v2_lora
+
+    @classmethod
+    def from_env(cls) -> "FeatureFlags":
+        """환경변수에서 Feature Flag를 로드한다."""
+        flags = cls(
+            use_rag_pipeline=os.getenv("USE_RAG_PIPELINE", "true").lower() in ("true", "1", "yes"),
+            model_version=os.getenv("MODEL_VERSION", "v2_lora"),
+        )
+        logger.info(f"Feature Flags 로드: {flags}")
+        return flags
+
+    def override_from_header(self, header_value: Optional[str]) -> "FeatureFlags":
+        """X-Feature-Flag 헤더에서 런타임 오버라이드.
+
+        형식: 'USE_RAG_PIPELINE=false,MODEL_VERSION=v1_lora'
+        원본 인스턴스는 변경되지 않으며 새 인스턴스를 반환한다.
+        """
+        if not header_value:
+            return self
+
+        overrides: dict = {}
+        for pair in header_value.split(","):
+            pair = pair.strip()
+            if "=" not in pair:
+                continue
+            key, value = pair.split("=", 1)
+            key = key.strip().upper()
+            value = value.strip()
+
+            if key == "USE_RAG_PIPELINE":
+                overrides["use_rag_pipeline"] = value.lower() in ("true", "1", "yes")
+            elif key == "MODEL_VERSION":
+                if value in ("v1_lora", "v2_lora"):
+                    overrides["model_version"] = value
+
+        if overrides:
+            current = asdict(self)
+            current.update(overrides)
+            return FeatureFlags(**current)
+        return self

src/inference/graph/__init__.py

@@ -0,0 +1,30 @@
+"""GovOn LangGraph runtime 패키지.
+
+Issue #415: LangGraph runtime 기반 및 planner/executor adapter 구성.
+
+주요 public API:
+- `build_govon_graph`: StateGraph 빌더 함수
+- `GovOnGraphState`: graph state TypedDict
+- `ApprovalStatus`, `TaskType`, `ToolPlan`: state 관련 타입
+- `PlannerAdapter`, `LLMPlannerAdapter`: planner 추상화 (LLMPlannerAdapter가 기본)
+- `RegexPlannerAdapter`: CI fallback planner (SKIP_MODEL_LOAD=true 환경 전용)
+- `ExecutorAdapter`, `RegistryExecutorAdapter`: executor 추상화
+"""
+
+from .builder import build_govon_graph
+from .executor_adapter import ExecutorAdapter, RegistryExecutorAdapter
+from .planner_adapter import LLMPlannerAdapter, PlannerAdapter, RegexPlannerAdapter
+from .state import ApprovalStatus, GovOnGraphState, TaskType, ToolPlan
+
+__all__ = [
+    "build_govon_graph",
+    "GovOnGraphState",
+    "ApprovalStatus",
+    "TaskType",
+    "ToolPlan",
+    "PlannerAdapter",
+    "RegexPlannerAdapter",
+    "LLMPlannerAdapter",
+    "ExecutorAdapter",
+    "RegistryExecutorAdapter",
+]

src/inference/graph/builder.py

@@ -0,0 +1,142 @@
+"""GovOn LangGraph StateGraph 빌더.
+
+Issue #415: LangGraph runtime 기반 및 planner/executor adapter 구성.
+
+`build_govon_graph()` 함수가 6-node StateGraph를 조립하고
+컴파일된 graph를 반환한다.
+
+Graph topology:
+  START -> session_load -> planner -> approval_wait
+               -> [approved] tool_execute -> synthesis -> persist -> END
+               -> [rejected] persist -> END
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+from langgraph.graph import END, START, StateGraph
+from langgraph.utils.runnable import RunnableCallable
+
+from .executor_adapter import ExecutorAdapter
+from .nodes import (
+    approval_wait_node,
+    persist_node,
+    planner_node,
+    session_load_node,
+    synthesis_node,
+    tool_execute_node,
+)
+from .planner_adapter import PlannerAdapter
+from .state import ApprovalStatus, GovOnGraphState
+
+if TYPE_CHECKING:
+    from src.inference.session_context import SessionStore
+
+
+def route_after_approval(state: GovOnGraphState) -> str:
+    """approval_wait 이후 분기 조건.
+
+    `approval_status` 값에 따라 다음 노드를 결정한다.
+
+    Parameters
+    ----------
+    state : GovOnGraphState
+        현재 graph state.
+
+    Returns
+    -------
+    str
+        "tool_execute" (승인) 또는 "persist" (거절).
+    """
+    if state.get("approval_status") == ApprovalStatus.APPROVED.value:
+        return "tool_execute"
+    return "persist"
+
+
+def build_govon_graph(
+    planner_adapter: PlannerAdapter,
+    executor_adapter: ExecutorAdapter,
+    session_store: "SessionStore",
+    checkpointer: Optional[object] = None,
+) -> object:
+    """GovOn MVP StateGraph를 구성하고 컴파일한다.
+
+    6개 노드를 조립하고 conditional edge로 approval gate를 연결한다.
+    checkpointer가 None이면 `MemorySaver`를 사용한다.
+
+    Parameters
+    ----------
+    planner_adapter : PlannerAdapter
+        planner 어댑터 인스턴스.
+        운영 환경에서는 `LLMPlannerAdapter`를 사용한다.
+        CI 환경에서는 `RegexPlannerAdapter`가 fallback으로 동작한다.
+    executor_adapter : ExecutorAdapter
+        tool executor 어댑터 인스턴스.
+    session_store : SessionStore
+        GovOn 세션 저장소. session_load와 persist 노드에서 사용한다.
+    checkpointer : optional
+        LangGraph checkpoint 저장소.
+        None이면 MemorySaver를 사용한다 (메모리에만 저장, 재시작 시 소멸).
+        프로덕션에서는 `AsyncSqliteSaver`를 주입한다.
+
+    Returns
+    -------
+    CompiledGraph
+        컴파일된 LangGraph. `ainvoke()`, `aget_state()` 등을 사용할 수 있다.
+    """
+    from langgraph.checkpoint.memory import MemorySaver
+
+    graph = StateGraph(GovOnGraphState)
+
+    # --- 노드 등록 (closure로 adapter와 session_store 주입) ---
+
+    async def _session_load(state: GovOnGraphState) -> dict:
+        return await session_load_node(state, session_store=session_store)
+
+    async def _planner(state: GovOnGraphState) -> dict:
+        return await planner_node(state, planner_adapter=planner_adapter)
+
+    async def _tool_execute(state: GovOnGraphState) -> dict:
+        return await tool_execute_node(state, executor_adapter=executor_adapter)
+
+    async def _synthesis(state: GovOnGraphState) -> dict:
+        return await synthesis_node(state)
+
+    async def _persist(state: GovOnGraphState) -> dict:
+        return await persist_node(state, session_store=session_store)
+
+    graph.add_node("session_load", _session_load)
+    graph.add_node("planner", _planner)
+    # Preserve sync execution for interrupt() on Python 3.10.
+    # The default add_node(sync_fn) path auto-generates an async executor wrapper,
+    # which breaks LangGraph interrupt context under ainvoke().
+    graph.add_node(
+        "approval_wait",
+        RunnableCallable(approval_wait_node, name="approval_wait"),
+    )
+    graph.add_node("tool_execute", _tool_execute)
+    graph.add_node("synthesis", _synthesis)
+    graph.add_node("persist", _persist)
+
+    # --- 엣지 ---
+    graph.add_edge(START, "session_load")
+    graph.add_edge("session_load", "planner")
+    graph.add_edge("planner", "approval_wait")
+    graph.add_conditional_edges(
+        "approval_wait",
+        route_after_approval,
+        {
+            "tool_execute": "tool_execute",
+            "persist": "persist",
+        },
+    )
+    graph.add_edge("tool_execute", "synthesis")
+    graph.add_edge("synthesis", "persist")
+    graph.add_edge("persist", END)
+
+    # --- 컴파일 ---
+    saver = checkpointer if checkpointer is not None else MemorySaver()
+    compiled = graph.compile(checkpointer=saver)
+
+    return compiled

src/inference/graph/capabilities/__init__.py

@@ -0,0 +1,35 @@
+"""LangGraph capabilities 패키지 — 표준화된 tool capability 인터페이스."""
+
+from .api_lookup import ApiLookupCapability, ApiLookupParams
+from .append_evidence import AppendEvidenceCapability
+from .base import CapabilityBase, CapabilityMetadata, LookupResult
+from .defaults import get_all_defaults, get_max_retries, get_timeout
+from .draft_civil_response import DraftCivilResponseCapability
+from .rag_search import RagSearchCapability, RagSearchParams
+from .registry import (
+    MVP_CAPABILITY_IDS,
+    build_mvp_registry,
+    get_all_metadata,
+    get_mvp_capability_ids,
+    is_mvp_capability,
+)
+
+__all__ = [
+    "CapabilityBase",
+    "CapabilityMetadata",
+    "LookupResult",
+    "ApiLookupCapability",
+    "ApiLookupParams",
+    "RagSearchCapability",
+    "RagSearchParams",
+    "DraftCivilResponseCapability",
+    "AppendEvidenceCapability",
+    "MVP_CAPABILITY_IDS",
+    "build_mvp_registry",
+    "get_all_metadata",
+    "get_mvp_capability_ids",
+    "is_mvp_capability",
+    "get_timeout",
+    "get_max_retries",
+    "get_all_defaults",
+]

src/inference/graph/capabilities/api_lookup.py

@@ -0,0 +1,268 @@
+"""unified api_lookup capability — MinwonAnalysisAction 래핑."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from loguru import logger
+
+from .base import CapabilityBase, CapabilityMetadata, EvidenceEnvelope, EvidenceItem, LookupResult
+from .defaults import get_timeout
+
+try:
+    import httpx
+
+    _HTTPX_AVAILABLE = True
+except ImportError:
+    httpx = None  # type: ignore
+    _HTTPX_AVAILABLE = False
+
+
+# ---------------------------------------------------------------------------
+# 파라미터 validator
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ApiLookupParams:
+    """api_lookup 호출 파라미터 — context에서 추출·정규화·검증."""
+
+    query: str
+    ret_count: int = 5
+    min_score: int = 2
+
+    @classmethod
+    def from_context(cls, query: str, context: Dict[str, Any]) -> "ApiLookupParams":
+        """context에서 파라미터를 추출하고 alias를 정규화한다."""
+
+        def _first_not_none(*values, default):
+            for v in values:
+                if v is not None:
+                    return v
+            return default
+
+        ret_count = int(
+            _first_not_none(
+                context.get("api_lookup_count"),
+                context.get("ret_count"),
+                context.get("count"),
+                default=5,
+            )
+        )
+        min_score = int(
+            _first_not_none(
+                context.get("api_lookup_min_score"),
+                context.get("min_score"),
+                context.get("score_threshold"),
+                default=2,
+            )
+        )
+        return cls(
+            query=query.strip(),
+            ret_count=max(1, min(20, ret_count)),
+            min_score=max(0, min(10, min_score)),
+        )
+
+    def validate(self) -> Optional[str]:
+        """검증 실패 시 오류 메시지, 통과 시 None."""
+        if not self.query:
+            return "query가 비어있습니다"
+        if len(self.query) > 500:
+            return f"query가 너무 깁니다 ({len(self.query)}자, 최대 500자)"
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Capability
+# ---------------------------------------------------------------------------
+
+
+class ApiLookupCapability(CapabilityBase):
+    """공공데이터포털 민원분석정보조회 API를 LangGraph capability로 래핑.
+
+    Parameters
+    ----------
+    action : Optional[MinwonAnalysisAction]
+        래핑할 기존 Action 인스턴스. None이면 빈 결과를 반환한다
+        (SKIP_MODEL_LOAD 등 경량 환경 지원).
+    """
+
+    def __init__(self, action: Optional[Any] = None) -> None:
+        self._action = action
+
+    @property
+    def metadata(self) -> CapabilityMetadata:
+        return CapabilityMetadata(
+            name="api_lookup",
+            description="공공데이터포털 민원분석정보조회 API를 호출하여 유사 민원 사례를 검색합니다.",
+            approval_summary="외부 API(data.go.kr)에서 유사 민원 사례를 조회합니다.",
+            provider="data.go.kr",
+            timeout_sec=get_timeout("api_lookup"),
+        )
+
+    async def execute(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: Any,
+    ) -> LookupResult:
+        """MinwonAnalysisAction.fetch_similar_cases를 래핑하여 LookupResult로 반환."""
+        provider = self.metadata.provider
+
+        # 파라미터 추출 및 검증 (action 유무와 무관하게 항상 수행)
+        params = ApiLookupParams.from_context(query, context)
+        validation_error = params.validate()
+        if validation_error:
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error=validation_error,
+                empty_reason="validation_error",
+                evidence=EvidenceEnvelope(
+                    status="error",
+                    errors=[validation_error],
+                ),
+            )
+
+        # action이 없으면 빈 결과 (경량 환경)
+        if self._action is None:
+            logger.debug("[api_lookup] action이 None — 빈 결과 반환")
+            return LookupResult(
+                success=True,
+                query=params.query,
+                provider=provider,
+                empty_reason="no_match",
+                evidence=EvidenceEnvelope(status="empty"),
+            )
+
+        # 파라미터를 인자로 전달 (shared state 변경 없이 thread-safe)
+        try:
+            payload = await asyncio.wait_for(
+                self._action.fetch_similar_cases(
+                    params.query,
+                    context,
+                    ret_count=params.ret_count,
+                    min_score=params.min_score,
+                ),
+                timeout=self.metadata.timeout_sec,
+            )
+        except asyncio.TimeoutError:
+            timeout_msg = f"API 호출 타임아웃 ({self.metadata.timeout_sec}초 초과)"
+            logger.warning(f"[api_lookup] 타임아웃 ({self.metadata.timeout_sec}s 초과)")
+            return LookupResult(
+                success=False,
+                query=params.query,
+                provider=provider,
+                error=timeout_msg,
+                empty_reason="provider_error",
+                evidence=EvidenceEnvelope(
+                    status="error",
+                    errors=[timeout_msg],
+                ),
+            )
+        except Exception as exc:
+            if _HTTPX_AVAILABLE and isinstance(exc, httpx.HTTPError):
+                logger.warning(f"[api_lookup] httpx 오류: {exc}")
+            else:
+                logger.error(f"[api_lookup] API 호출 오류: {exc}", exc_info=True)
+            return LookupResult(
+                success=False,
+                query=params.query,
+                provider=provider,
+                error=str(exc),
+                empty_reason="provider_error",
+                evidence=EvidenceEnvelope(
+                    status="error",
+                    errors=[str(exc)],
+                ),
+            )
+
+        # 결과 변환
+        results = payload.get("results")
+        if results is None:
+            error_msg = "민원 분석 API 호출에 실패했습니다."
+            return LookupResult(
+                success=False,
+                query=payload.get("query", params.query),
+                provider=provider,
+                error=error_msg,
+                empty_reason="provider_error",
+                evidence=EvidenceEnvelope(
+                    status="error",
+                    errors=[error_msg],
+                ),
+            )
+
+        # citations를 dict 목록으로 정규화
+        raw_citations = payload.get("citations", [])
+        citations: list[Dict[str, Any]] = []
+        for c in raw_citations:
+            if isinstance(c, dict):
+                citations.append(c)
+            elif hasattr(c, "__dict__"):
+                citations.append({k: v for k, v in c.__dict__.items() if not k.startswith("_")})
+
+        if not results:
+            return LookupResult(
+                success=True,
+                query=payload.get("query", params.query),
+                provider=provider,
+                empty_reason="no_match",
+                evidence=EvidenceEnvelope(status="empty"),
+            )
+
+        # EvidenceItem으로 정규화
+        evidence_items = []
+        for item in results:
+            if not isinstance(item, dict):
+                continue
+            title = item.get("title") or item.get("qnaTitle") or item.get("question", "")
+            excerpt = item.get("content") or item.get("qnaContent") or item.get("qnaAnswer", "")
+            link = item.get("url") or item.get("detailUrl", "")
+            evidence_items.append(
+                EvidenceItem(
+                    source_type="api",
+                    title=str(title),
+                    excerpt=str(excerpt)[:500],
+                    link_or_path=str(link),
+                    score=float(item.get("score", 0)),
+                    provider_meta={"provider": provider},
+                )
+            )
+        # citations도 EvidenceItem으로 변환 (중복 제거를 위해 link_or_path 기반 dedup)
+        seen_links: set[str] = {item.link_or_path for item in evidence_items}
+        for c in citations:
+            link = c.get("url") or c.get("detailUrl", "")
+            if link in seen_links:
+                continue
+            seen_links.add(str(link))
+            title = c.get("title") or c.get("qnaTitle") or c.get("question", "")
+            excerpt = c.get("content") or c.get("qnaContent") or c.get("qnaAnswer", "")
+            evidence_items.append(
+                EvidenceItem(
+                    source_type="api",
+                    title=str(title),
+                    excerpt=str(excerpt)[:500],
+                    link_or_path=str(link),
+                    score=float(c.get("score", 0)),
+                    provider_meta={"provider": provider},
+                )
+            )
+
+        envelope = EvidenceEnvelope(
+            items=evidence_items,
+            status="ok" if evidence_items else "empty",
+        )
+
+        return LookupResult(
+            success=True,
+            query=payload.get("query", params.query),
+            results=results,
+            context_text=payload.get("context_text", ""),
+            citations=citations,
+            provider=provider,
+            evidence=envelope,
+        )

src/inference/graph/capabilities/append_evidence.py

@@ -0,0 +1,133 @@
+"""append_evidence capability — 기존 closure를 CapabilityBase로 래핑."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict
+
+from .base import CapabilityBase, CapabilityMetadata, EvidenceEnvelope, EvidenceItem, LookupResult
+from .defaults import get_timeout
+
+
+class AppendEvidenceCapability(CapabilityBase):
+    """근거/출처 보강 capability.
+
+    기존 api_server의 _append_evidence_tool closure를 주입받아
+    CapabilityBase 인터페이스로 래핑한다.
+
+    Parameters
+    ----------
+    execute_fn : Callable
+        ``async (query, context, session) -> dict`` 시그니처의 실행 함수.
+    """
+
+    def __init__(self, execute_fn: Callable[..., Any]) -> None:
+        self._execute_fn = execute_fn
+
+    @property
+    def metadata(self) -> CapabilityMetadata:
+        return CapabilityMetadata(
+            name="append_evidence",
+            description=(
+                "기존 답변에 법령 근거, 유사 사례, 외부 통계 등 " "추가 출처를 보강합니다."
+            ),
+            approval_summary="기존 답변에 법적 근거와 출처를 추가합니다.",
+            provider="local_vectordb+data.go.kr",
+            timeout_sec=get_timeout("append_evidence"),
+        )
+
+    async def execute(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: Any,
+    ) -> LookupResult:
+        """주입받은 함수에 위임하고 결과를 LookupResult로 변환한다."""
+        raw = await self._execute_fn(query=query, context=context, session=session)
+
+        if isinstance(raw, dict) and raw.get("error"):
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=self.metadata.provider,
+                error=raw["error"],
+                empty_reason="provider_error",
+                evidence=EvidenceEnvelope(
+                    status="error",
+                    errors=[raw["error"]],
+                ),
+            )
+
+        text = raw.get("text", "") if isinstance(raw, dict) else str(raw)
+        citations = raw.get("api_citations", []) if isinstance(raw, dict) else []
+        rag_results = raw.get("rag_results", []) if isinstance(raw, dict) else []
+
+        # 이전 단계의 evidence를 합산하여 EvidenceEnvelope 구성
+        evidence_items: list[EvidenceItem] = []
+        errors: list[str] = []
+
+        # rag_results -> EvidenceItem 변환
+        for item in rag_results:
+            if not isinstance(item, dict):
+                continue
+            metadata = item.get("metadata", {}) or {}
+            evidence_items.append(
+                EvidenceItem(
+                    source_type="rag",
+                    title=item.get("title", ""),
+                    excerpt=str(item.get("content", ""))[:500],
+                    link_or_path=metadata.get("file_path", ""),
+                    page=metadata.get("page"),
+                    score=float(item.get("score", 0.0)),
+                    provider_meta={"provider": "local_vectordb"},
+                )
+            )
+
+        # api_citations -> EvidenceItem 변환
+        for c in citations:
+            if not isinstance(c, dict):
+                continue
+            title = c.get("title") or c.get("qnaTitle") or c.get("question", "")
+            excerpt = c.get("content") or c.get("qnaContent") or c.get("qnaAnswer", "")
+            link = c.get("url") or c.get("detailUrl", "")
+            evidence_items.append(
+                EvidenceItem(
+                    source_type="api",
+                    title=str(title),
+                    excerpt=str(excerpt)[:500],
+                    link_or_path=str(link),
+                    score=float(c.get("score", 0)),
+                    provider_meta={"provider": "data.go.kr"},
+                )
+            )
+
+        if isinstance(raw, dict):
+            raw_errors = raw.get("errors", [])
+            if isinstance(raw_errors, list):
+                errors = [str(e) for e in raw_errors]
+
+        status: str
+        if not evidence_items and errors:
+            status = "error"
+        elif not evidence_items:
+            status = "empty"
+        elif errors:
+            status = "partial"
+        else:
+            status = "ok"
+
+        envelope = EvidenceEnvelope(
+            items=evidence_items,
+            summary_text=text,
+            status=status,
+            errors=errors,
+        )
+
+        return LookupResult(
+            success=True,
+            query=query,
+            context_text=text,
+            citations=citations,
+            results=rag_results,
+            provider=self.metadata.provider,
+            evidence=envelope,
+        )

src/inference/graph/capabilities/base.py

@@ -0,0 +1,129 @@
+"""LangGraph capability 공통 추상화."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class EvidenceItem:
+    """RAG/API 출처 무관하게 동일한 구조로 evidence를 표현.
+
+    source_type: "rag" | "api" | "llm_generated"
+    """
+
+    source_type: str  # "rag" | "api" | "llm_generated"
+    title: str
+    excerpt: str  # 본문 발췌 (최대 500자)
+    link_or_path: str = ""  # URL(API) 또는 file_path(RAG)
+    page: Optional[int] = None
+    score: float = 0.0
+    provider_meta: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "source_type": self.source_type,
+            "title": self.title,
+            "excerpt": self.excerpt,
+            "link_or_path": self.link_or_path,
+            "page": self.page,
+            "score": self.score,
+            "provider_meta": self.provider_meta,
+        }
+
+
+@dataclass
+class EvidenceEnvelope:
+    """mixed evidence 결과 컨테이너."""
+
+    items: List[EvidenceItem] = field(default_factory=list)
+    summary_text: str = ""
+    status: str = "ok"  # "ok" | "empty" | "partial" | "error"
+    errors: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "items": [item.to_dict() for item in self.items],
+            "summary_text": self.summary_text,
+            "status": self.status,
+            "errors": self.errors,
+        }
+
+
+@dataclass
+class CapabilityMetadata:
+    """planner·executor·session trace에서 공통으로 사용하는 capability 메타데이터."""
+
+    name: str  # tool registry key (예: "api_lookup")
+    description: str  # LLM planner가 읽는 한국어 설명 (1-2문장)
+    approval_summary: str  # approval_wait 프롬프트에 표시되는 요약
+    provider: str  # 데이터 제공자 식별자 (예: "data.go.kr")
+    timeout_sec: float = 10.0  # 기본 타임아웃
+
+
+@dataclass
+class LookupResult:
+    """api_lookup 공통 응답 스키마."""
+
+    success: bool
+    query: str
+    results: List[Dict[str, Any]] = field(default_factory=list)
+    context_text: str = ""
+    citations: List[Dict[str, Any]] = field(default_factory=list)
+    provider: str = ""
+    error: Optional[str] = None
+    empty_reason: Optional[str] = None  # "quota", "no_match", "provider_error"
+    latency_ms: float = 0.0
+    evidence: Optional[EvidenceEnvelope] = None  # 정규화된 evidence (새 필드)
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {
+            "success": self.success,
+            "query": self.query,
+            "count": len(self.results),
+            "results": self.results,
+            "context_text": self.context_text,
+            "citations": self.citations,
+            "provider": self.provider,
+            "error": self.error,
+            "empty_reason": self.empty_reason,
+            "latency_ms": round(self.latency_ms, 2),
+        }
+        if self.evidence is not None:
+            d["evidence"] = self.evidence.to_dict()
+        return d
+
+
+class CapabilityBase(ABC):
+    """LangGraph tool capability 추상 베이스.
+
+    RegistryExecutorAdapter의 tool_registry에 등록 가능한 async callable 인터페이스.
+    """
+
+    @property
+    @abstractmethod
+    def metadata(self) -> CapabilityMetadata: ...
+
+    @abstractmethod
+    async def execute(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: Any,  # SessionContext (순환 import 방지)
+    ) -> LookupResult: ...
+
+    async def __call__(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: Any,
+    ) -> Dict[str, Any]:
+        """RegistryExecutorAdapter 호환 진입점."""
+        import time
+
+        start = time.monotonic()
+        result = await self.execute(query, context, session)
+        result.latency_ms = (time.monotonic() - start) * 1000
+        return result.to_dict()

src/inference/graph/capabilities/defaults.py

@@ -0,0 +1,94 @@
+"""Capability timeout/retry 기본값 모듈.
+
+Issue #163: capability별 timeout과 retry 기본값을 중앙 집중 관리.
+환경변수 GOVON_TOOL_TIMEOUT_{CAPABILITY_NAME} 으로 오버라이드 가능.
+
+예: GOVON_TOOL_TIMEOUT_RAG_SEARCH=20  -> rag_search timeout을 20초로 변경
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Dict
+
+from loguru import logger
+
+
+@dataclass(frozen=True)
+class CapabilityDefaults:
+    """capability별 timeout/retry 기본값."""
+
+    timeout_sec: float
+    max_retries: int
+
+
+# -----------------------------------------------------------------------
+# 기본값 정의 (코드베이스 capability metadata에서 추출)
+# -----------------------------------------------------------------------
+
+_DEFAULTS: Dict[str, CapabilityDefaults] = {
+    "rag_search": CapabilityDefaults(timeout_sec=15.0, max_retries=0),
+    "api_lookup": CapabilityDefaults(timeout_sec=10.0, max_retries=1),
+    "draft_civil_response": CapabilityDefaults(timeout_sec=30.0, max_retries=0),
+    "append_evidence": CapabilityDefaults(timeout_sec=30.0, max_retries=0),
+    "issue_detector": CapabilityDefaults(timeout_sec=15.0, max_retries=0),
+    "stats_lookup": CapabilityDefaults(timeout_sec=15.0, max_retries=0),
+    "keyword_analyzer": CapabilityDefaults(timeout_sec=10.0, max_retries=0),
+    "demographics_lookup": CapabilityDefaults(timeout_sec=15.0, max_retries=0),
+}
+
+
+def get_timeout(capability_name: str) -> float:
+    """capability의 timeout(초)을 반환한다.
+
+    환경변수 ``GOVON_TOOL_TIMEOUT_{CAPABILITY_NAME_UPPER}`` 가 설정되어 있으면
+    해당 값을 사용하고, 없으면 기본값을 반환한다.
+
+    Parameters
+    ----------
+    capability_name : str
+        capability 이름 (예: "rag_search").
+
+    Returns
+    -------
+    float
+        timeout 초. 알 수 없는 capability는 10.0초.
+    """
+    env_key = f"GOVON_TOOL_TIMEOUT_{capability_name.upper()}"
+    env_val = os.environ.get(env_key)
+    if env_val is not None:
+        try:
+            val = float(env_val)
+            if val > 0:
+                return val
+            logger.warning(
+                f"GOVON_TOOL_TIMEOUT_{capability_name.upper()} 값이 양수가 아닙니다: {env_val}"
+            )
+        except ValueError:
+            logger.warning(f"{env_key} 값을 숫자로 파싱할 수 없습니다: {env_val!r}")
+
+    defaults = _DEFAULTS.get(capability_name)
+    return defaults.timeout_sec if defaults else 10.0
+
+
+def get_max_retries(capability_name: str) -> int:
+    """capability의 최대 재시도 횟수를 반환한다.
+
+    Parameters
+    ----------
+    capability_name : str
+        capability 이름.
+
+    Returns
+    -------
+    int
+        최대 재시도 횟수. 알 수 없는 capability는 0.
+    """
+    defaults = _DEFAULTS.get(capability_name)
+    return defaults.max_retries if defaults else 0
+
+
+def get_all_defaults() -> Dict[str, CapabilityDefaults]:
+    """등록된 모든 capability 기본값을 반환한다."""
+    return dict(_DEFAULTS)

src/inference/graph/capabilities/demographics_lookup.py

@@ -0,0 +1,283 @@
+"""demographics_lookup capability — 성별+연령+인구대비 조합.
+
+Issue #489: 민원 인구통계 분석 도구.
+3개 API(성별통계, 연령통계, 인구대비비율)를 조합하여
+민원 인구통계 분석 결과를 제공한다.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional
+
+from loguru import logger
+
+from .base import (
+    CapabilityBase,
+    CapabilityMetadata,
+    EvidenceEnvelope,
+    EvidenceItem,
+    LookupResult,
+)
+from .defaults import get_timeout
+
+
+class DemographicsLookupCapability(CapabilityBase):
+    """민원 인구통계 분석 capability.
+
+    성별, 연령, 인구대비 비율을 조합하여 인구통계 분석 결과를 제공한다.
+
+    Parameters
+    ----------
+    action : Optional[MinwonAnalysisAction]
+        API 호출용 Action 인스턴스. None이면 빈 결과 반환.
+    """
+
+    def __init__(self, action: Optional[Any] = None) -> None:
+        self._action = action
+
+    @property
+    def metadata(self) -> CapabilityMetadata:
+        return CapabilityMetadata(
+            name="demographics_lookup",
+            description=(
+                "성별, 연령, 인구대비 비율을 조합하여 " "민원 인구통계 분석 결과를 제공합니다."
+            ),
+            approval_summary="공공데이터포털에서 민원 인구통계를 분석합니다.",
+            provider="data.go.kr",
+            timeout_sec=get_timeout("demographics_lookup"),
+        )
+
+    async def execute(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: Any,
+    ) -> LookupResult:
+        """성별+연령+인구대비 API를 병렬 호출하고 결과를 조합한다."""
+        provider = self.metadata.provider
+
+        if not query or not query.strip():
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error="query가 비어있습니다",
+                empty_reason="validation_error",
+                evidence=EvidenceEnvelope(status="error", errors=["query가 비어있습니다"]),
+            )
+
+        if self._action is None:
+            logger.debug("[demographics_lookup] action이 None - 빈 결과 반환")
+            return LookupResult(
+                success=True,
+                query=query,
+                provider=provider,
+                empty_reason="no_match",
+                evidence=EvidenceEnvelope(status="empty"),
+            )
+
+        date_from = context.get("date_from", "")
+        date_to = context.get("date_to", "")
+        searchword = context.get("searchword", "")
+        top_n = int(context.get("top_n", 5))
+
+        if not searchword:
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error="인구통계 분석에는 searchword가 필요합니다",
+                empty_reason="validation_error",
+                evidence=EvidenceEnvelope(
+                    status="error",
+                    errors=["인구통계 분석에는 searchword가 필요합니다"],
+                ),
+            )
+
+        try:
+            gender, age, population = await asyncio.wait_for(
+                self._fetch_all(date_from, date_to, searchword, top_n),
+                timeout=self.metadata.timeout_sec,
+            )
+        except asyncio.TimeoutError:
+            msg = f"API 호출 타임아웃 ({self.metadata.timeout_sec}초 초과)"
+            logger.warning(f"[demographics_lookup] {msg}")
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error=msg,
+                empty_reason="provider_error",
+                evidence=EvidenceEnvelope(status="error", errors=[msg]),
+            )
+        except Exception as exc:
+            logger.error(f"[demographics_lookup] API 호출 오류: {exc}", exc_info=True)
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error=str(exc),
+                empty_reason="provider_error",
+                evidence=EvidenceEnvelope(status="error", errors=[str(exc)]),
+            )
+
+        all_results: List[Dict[str, Any]] = []
+        evidence_items: List[EvidenceItem] = []
+        errors: List[str] = []
+
+        if gender is not None:
+            for item in gender:
+                item["_source_api"] = "gender"
+                all_results.append(item)
+                evidence_items.append(
+                    EvidenceItem(
+                        source_type="api",
+                        title=item.get("label", ""),
+                        excerpt=f"성별: {item.get('label', '')}, " f"건수={item.get('hits', 0)}",
+                        provider_meta={"provider": provider, "api": "gender"},
+                    )
+                )
+        else:
+            errors.append("성별통계 API 실패")
+
+        if age is not None:
+            for item in age:
+                item["_source_api"] = "age"
+                all_results.append(item)
+                evidence_items.append(
+                    EvidenceItem(
+                        source_type="api",
+                        title=f"{item.get('label', '')}대",
+                        excerpt=f"연령: {item.get('label', '')}대, " f"건수={item.get('hits', 0)}",
+                        provider_meta={"provider": provider, "api": "age"},
+                    )
+                )
+        else:
+            errors.append("연령통계 API 실패")
+
+        if population is not None:
+            for item in population:
+                item["_source_api"] = "population"
+                all_results.append(item)
+                evidence_items.append(
+                    EvidenceItem(
+                        source_type="api",
+                        title=item.get("label", ""),
+                        excerpt=f"인구대비: {item.get('label', '')}, "
+                        f"비율={item.get('ratio', '')}",
+                        provider_meta={"provider": provider, "api": "population"},
+                    )
+                )
+        else:
+            errors.append("인구대비 API 실패")
+
+        if not all_results:
+            status = "error" if len(errors) == 3 else "empty"
+            return LookupResult(
+                success=len(errors) < 3,
+                query=query,
+                provider=provider,
+                empty_reason="no_match" if len(errors) < 3 else "provider_error",
+                error="; ".join(errors) if errors else None,
+                evidence=EvidenceEnvelope(items=[], status=status, errors=errors),
+            )
+
+        context_text = self._build_context_text(gender, age, population)
+        status = "ok" if not errors else "partial"
+
+        return LookupResult(
+            success=True,
+            query=query,
+            results=all_results,
+            context_text=context_text,
+            provider=provider,
+            evidence=EvidenceEnvelope(
+                items=evidence_items,
+                summary_text=context_text,
+                status=status,
+                errors=errors,
+            ),
+        )
+
+    async def _fetch_all(
+        self,
+        date_from: str,
+        date_to: str,
+        searchword: str,
+        top_n: int,
+    ) -> tuple:
+        """3개 API를 병렬 호출한다."""
+        tasks = [
+            self._safe_call(
+                self._action.get_gender_stats,
+                date_from=date_from,
+                date_to=date_to,
+                searchword=searchword,
+            ),
+            self._safe_call(
+                self._action.get_age_stats,
+                date_from=date_from,
+                date_to=date_to,
+                searchword=searchword,
+            ),
+            self._safe_call(
+                self._action.get_population_ratio,
+                date_from=date_from,
+                date_to=date_to,
+                top_n=top_n,
+            ),
+        ]
+        return tuple(await asyncio.gather(*tasks))
+
+    @staticmethod
+    async def _safe_call(fn, **kwargs) -> Optional[List[Dict[str, Any]]]:
+        """개별 API 호출을 안전하게 래핑한다."""
+        try:
+            return await fn(**kwargs)
+        except Exception as exc:
+            logger.warning(f"[demographics_lookup] 개별 API 실패: {exc}")
+            return None
+
+    @staticmethod
+    def _build_context_text(
+        gender: Optional[List],
+        age: Optional[List],
+        population: Optional[List],
+    ) -> str:
+        """조합 결과에서 자연어 요약을 생성한다."""
+        parts: List[str] = []
+
+        if gender:
+            total = sum(int(g.get("hits", 0)) for g in gender)
+            if total > 0:
+                items = []
+                for g in gender:
+                    label = g.get("label", "")
+                    hits = int(g.get("hits", 0))
+                    pct = (hits / total * 100) if total else 0
+                    items.append(f"{label} {pct:.1f}%")
+                parts.append(", ".join(items))
+
+        if age:
+            # 가장 높은 건수의 연령대
+            sorted_age = sorted(age, key=lambda x: int(x.get("hits", 0)), reverse=True)
+            if sorted_age:
+                top = sorted_age[0]
+                total = sum(int(a.get("hits", 0)) for a in age)
+                hits = int(top.get("hits", 0))
+                pct = (hits / total * 100) if total else 0
+                parts.append(f"{top.get('label', '')}대 최다({pct:.1f}%)")
+
+        if population:
+            if len(population) > 0:
+                top = population[0]
+                ratio = top.get("ratio", "")
+                label = top.get("label", "")
+                try:
+                    ratio_pct = float(ratio) * 100 if ratio else 0
+                    parts.append(f"{label} 인구대비 {ratio_pct:.2f}%")
+                except (ValueError, TypeError):
+                    parts.append(f"{label} 인구대비 {ratio}")
+
+        return ", ".join(parts) if parts else ""

src/inference/graph/capabilities/draft_civil_response.py

@@ -0,0 +1,96 @@
+"""draft_civil_response capability — 기존 closure를 CapabilityBase로 래핑."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict
+
+from .base import CapabilityBase, CapabilityMetadata, EvidenceEnvelope, EvidenceItem, LookupResult
+from .defaults import get_timeout
+
+
+class DraftCivilResponseCapability(CapabilityBase):
+    """민원 답변 초안 생성 capability.
+
+    기존 api_server의 _draft_civil_response_tool closure를 주입받아
+    CapabilityBase 인터페이스로 래핑한다.
+
+    Parameters
+    ----------
+    execute_fn : Callable
+        ``async (query, context, session) -> dict`` 시그니처의 실행 함수.
+    """
+
+    def __init__(self, execute_fn: Callable[..., Any]) -> None:
+        self._execute_fn = execute_fn
+
+    @property
+    def metadata(self) -> CapabilityMetadata:
+        return CapabilityMetadata(
+            name="draft_civil_response",
+            description=(
+                "검색된 법령/사례와 외부 민원분석 결과를 종합하여 " "민원 답변 초안을 생성합니다."
+            ),
+            approval_summary="AI 모델이 검색 결과를 종합하여 민원 답변 초안을 생성합니다.",
+            provider="local_llm",
+            timeout_sec=get_timeout("draft_civil_response"),
+        )
+
+    async def execute(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: Any,
+    ) -> LookupResult:
+        """주입받은 함수에 위임하고 결과를 LookupResult로 변환한다."""
+        raw = await self._execute_fn(query=query, context=context, session=session)
+
+        if isinstance(raw, dict) and raw.get("error"):
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=self.metadata.provider,
+                error=raw["error"],
+                empty_reason="provider_error",
+                evidence=EvidenceEnvelope(
+                    status="error",
+                    errors=[raw["error"]],
+                ),
+            )
+
+        text = raw.get("text", "") if isinstance(raw, dict) else str(raw)
+
+        # draft에서 참조된 사례를 EvidenceItem으로 변환
+        evidence_items: list[EvidenceItem] = []
+        if isinstance(raw, dict):
+            # raw에 포함된 citations/references를 EvidenceItem으로 변환
+            for ref in raw.get("citations", []):
+                if not isinstance(ref, dict):
+                    continue
+                title = ref.get("title") or ref.get("qnaTitle") or ref.get("question", "")
+                excerpt = ref.get("content") or ref.get("qnaContent") or ref.get("qnaAnswer", "")
+                link = ref.get("url") or ref.get("detailUrl", "")
+                evidence_items.append(
+                    EvidenceItem(
+                        source_type="llm_generated",
+                        title=str(title),
+                        excerpt=str(excerpt)[:500],
+                        link_or_path=str(link),
+                        provider_meta={"provider": self.metadata.provider},
+                    )
+                )
+
+        envelope = EvidenceEnvelope(
+            items=evidence_items,
+            summary_text=text,
+            status="ok",
+        )
+
+        return LookupResult(
+            success=True,
+            query=query,
+            context_text=text,
+            provider=self.metadata.provider,
+            # draft 결과는 results 대신 context_text에 담긴다
+            results=[raw] if isinstance(raw, dict) else [],
+            evidence=envelope,
+        )

src/inference/graph/capabilities/issue_detector.py

@@ -0,0 +1,292 @@
+"""issue_detector capability — 급증키워드+오늘이슈+최다키워드 조합.
+
+Issue #486: 민원 이슈 탐지 도구.
+3개 API(급증키워드, 오늘이슈, 최다키워드)를 조합하여
+현재 주요 이슈를 탐지하고 자연어 요약을 생성한다.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional
+
+from loguru import logger
+
+from .base import (
+    CapabilityBase,
+    CapabilityMetadata,
+    EvidenceEnvelope,
+    EvidenceItem,
+    LookupResult,
+)
+from .defaults import get_timeout
+
+
+class IssueDetectorCapability(CapabilityBase):
+    """민원 이슈 탐지 capability.
+
+    급증키워드, 오늘 이슈 토픽, 최다 키워드를 조합하여
+    현재 주요 민원 이슈를 파악한다.
+
+    Parameters
+    ----------
+    action : Optional[MinwonAnalysisAction]
+        API 호출용 Action 인스턴스. None이면 빈 결과 반환.
+    """
+
+    def __init__(self, action: Optional[Any] = None) -> None:
+        self._action = action
+
+    @property
+    def metadata(self) -> CapabilityMetadata:
+        return CapabilityMetadata(
+            name="issue_detector",
+            description=(
+                "급증키워드, 오늘이슈, 최다키워드를 조합하여 " "현재 주요 민원 이슈를 탐지합니다."
+            ),
+            approval_summary="공공데이터포털에서 민원 이슈 현황을 조회합니다.",
+            provider="data.go.kr",
+            timeout_sec=get_timeout("issue_detector"),
+        )
+
+    async def execute(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: Any,
+    ) -> LookupResult:
+        """3개 API를 병렬 호출하고 결과를 조합한다."""
+        provider = self.metadata.provider
+
+        if not query or not query.strip():
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error="query가 비어있습니다",
+                empty_reason="validation_error",
+                evidence=EvidenceEnvelope(status="error", errors=["query가 비어있습니다"]),
+            )
+
+        if self._action is None:
+            logger.debug("[issue_detector] action이 None - 빈 결과 반환")
+            return LookupResult(
+                success=True,
+                query=query,
+                provider=provider,
+                empty_reason="no_match",
+                evidence=EvidenceEnvelope(status="empty"),
+            )
+
+        # 날짜 파라미터 추출 및 검증
+        analysis_time = context.get("analysis_time", "")
+        search_date = context.get("search_date", "")
+        max_result = int(context.get("max_result", 5))
+
+        if not analysis_time and not search_date:
+            err = "analysis_time 또는 search_date 파라미터가 필요합니다"
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error=err,
+                empty_reason="validation_error",
+                evidence=EvidenceEnvelope(status="error", errors=[err]),
+            )
+
+        try:
+            rising, topics, top_kw = await asyncio.wait_for(
+                self._fetch_all(analysis_time, search_date, max_result),
+                timeout=self.metadata.timeout_sec,
+            )
+        except asyncio.TimeoutError:
+            msg = f"API 호출 타임아웃 ({self.metadata.timeout_sec}초 초과)"
+            logger.warning(f"[issue_detector] {msg}")
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error=msg,
+                empty_reason="provider_error",
+                evidence=EvidenceEnvelope(status="error", errors=[msg]),
+            )
+        except Exception as exc:
+            logger.error(f"[issue_detector] API 호출 오류: {exc}", exc_info=True)
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error=str(exc),
+                empty_reason="provider_error",
+                evidence=EvidenceEnvelope(status="error", errors=[str(exc)]),
+            )
+
+        # 결과 조합
+        all_results: List[Dict[str, Any]] = []
+        evidence_items: List[EvidenceItem] = []
+        errors: List[str] = []
+
+        if rising is not None:
+            for item in rising:
+                item["_source_api"] = "rising_keyword"
+                all_results.append(item)
+                evidence_items.append(
+                    EvidenceItem(
+                        source_type="api",
+                        title=item.get("keyword", ""),
+                        excerpt=f"급증키워드: {item.get('keyword', '')}, "
+                        f"빈도={item.get('df', 0)}, 전일대비={item.get('prevRatio', '')}%",
+                        provider_meta={"provider": provider, "api": "rising_keyword"},
+                    )
+                )
+        else:
+            errors.append("급증키워드 API 실패")
+
+        if topics is not None:
+            for item in topics:
+                item["_source_api"] = "today_topic"
+                all_results.append(item)
+                evidence_items.append(
+                    EvidenceItem(
+                        source_type="api",
+                        title=item.get("topic", ""),
+                        excerpt=f"오늘이슈: {item.get('topic', '')}, "
+                        f"건수={item.get('count', 0)}",
+                        provider_meta={"provider": provider, "api": "today_topic"},
+                    )
+                )
+        else:
+            errors.append("오늘이슈 API 실패")
+
+        if top_kw is not None:
+            for item in top_kw:
+                item["_source_api"] = "top_keyword"
+                all_results.append(item)
+                evidence_items.append(
+                    EvidenceItem(
+                        source_type="api",
+                        title=item.get("term", ""),
+                        excerpt=f"최다키워드: {item.get('term', '')}, " f"빈도={item.get('df', 0)}",
+                        provider_meta={"provider": provider, "api": "top_keyword"},
+                    )
+                )
+        else:
+            errors.append("최다키워드 API 실패")
+
+        if not all_results:
+            status = "error" if len(errors) == 3 else "empty"
+            return LookupResult(
+                success=len(errors) < 3,
+                query=query,
+                provider=provider,
+                empty_reason="no_match" if len(errors) < 3 else "provider_error",
+                error="; ".join(errors) if errors else None,
+                evidence=EvidenceEnvelope(items=[], status=status, errors=errors),
+            )
+
+        context_text = self._build_context_text(rising, topics, top_kw)
+        status = "ok" if not errors else "partial"
+
+        return LookupResult(
+            success=True,
+            query=query,
+            results=all_results,
+            context_text=context_text,
+            provider=provider,
+            evidence=EvidenceEnvelope(
+                items=evidence_items,
+                summary_text=context_text,
+                status=status,
+                errors=errors,
+            ),
+        )
+
+    async def _fetch_all(
+        self,
+        analysis_time: str,
+        search_date: str,
+        max_result: int,
+    ) -> tuple:
+        """3개 API를 병렬 호출한다."""
+        tasks = [
+            (
+                self._safe_call(
+                    self._action.get_rising_keywords,
+                    analysis_time=analysis_time,
+                    max_result=max_result,
+                )
+                if analysis_time
+                else self._noop()
+            ),
+            (
+                self._safe_call(
+                    self._action.get_today_topics,
+                    search_date=search_date,
+                    top_n=max_result,
+                )
+                if search_date
+                else self._noop()
+            ),
+            (
+                self._safe_call(
+                    self._action.get_top_keywords_by_period,
+                    analysis_time=analysis_time or search_date,
+                    max_result=max_result,
+                )
+                if (analysis_time or search_date)
+                else self._noop()
+            ),
+        ]
+        return await asyncio.gather(*tasks)
+
+    @staticmethod
+    async def _noop() -> None:
+        """빈 결과를 반환하는 no-op 코루틴."""
+        return None
+
+    @staticmethod
+    async def _safe_call(fn, **kwargs) -> Optional[List[Dict[str, Any]]]:
+        """개별 API 호출을 안전하게 래핑한다."""
+        try:
+            return await fn(**kwargs)
+        except Exception as exc:
+            logger.warning(f"[issue_detector] 개별 API 실패: {exc}")
+            return None
+
+    @staticmethod
+    def _build_context_text(
+        rising: Optional[List],
+        topics: Optional[List],
+        top_kw: Optional[List],
+    ) -> str:
+        """조합 결과에서 자연어 요약을 생성한다."""
+        parts: List[str] = []
+
+        if rising:
+            items = []
+            for r in rising[:3]:
+                kw = r.get("keyword", "")
+                ratio = r.get("prevRatio", "")
+                items.append(f"{kw}(+{ratio}%)" if ratio else kw)
+            if items:
+                parts.append(f"급증 이슈: {', '.join(items)}")
+
+        if topics:
+            items = []
+            for t in topics[:3]:
+                topic = t.get("topic", "")
+                count = t.get("count", 0)
+                items.append(f"{topic}({count:,}건)")
+            if items:
+                parts.append(f"오늘 핵심: {', '.join(items)}")
+
+        if top_kw:
+            items = []
+            for k in top_kw[:3]:
+                term = k.get("term", "")
+                df = k.get("df", 0)
+                items.append(f"{term}({df}건)")
+            if items:
+                parts.append(f"최다: {', '.join(items)}")
+
+        return "; ".join(parts) if parts else ""

src/inference/graph/capabilities/keyword_analyzer.py

@@ -0,0 +1,261 @@
+"""keyword_analyzer capability — 핵심키워드+연관어 조합.
+
+Issue #488: 민원 키워드 분석 도구.
+2개 API(핵심키워드, 연관어)를 조합하여
+키워드 분석 결과를 제공한다.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional
+
+from loguru import logger
+
+from .base import (
+    CapabilityBase,
+    CapabilityMetadata,
+    EvidenceEnvelope,
+    EvidenceItem,
+    LookupResult,
+)
+from .defaults import get_timeout
+
+
+class KeywordAnalyzerCapability(CapabilityBase):
+    """민원 키워드 분석 capability.
+
+    핵심키워드와 연관어를 조합하여 키워드 분석 결과를 제공한다.
+
+    Parameters
+    ----------
+    action : Optional[MinwonAnalysisAction]
+        API 호출용 Action 인스턴스. None이면 빈 결과 반환.
+    """
+
+    def __init__(self, action: Optional[Any] = None) -> None:
+        self._action = action
+
+    @property
+    def metadata(self) -> CapabilityMetadata:
+        return CapabilityMetadata(
+            name="keyword_analyzer",
+            description=("핵심키워드와 연관어를 조합하여 " "민원 키워드 분석 결과를 제공합니다."),
+            approval_summary="공공데이터포털에서 민원 키워드를 분석합니다.",
+            provider="data.go.kr",
+            timeout_sec=get_timeout("keyword_analyzer"),
+        )
+
+    async def execute(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: Any,
+    ) -> LookupResult:
+        """핵심키워드 + 연관어 API를 병렬 호출하고 결과를 조합한다."""
+        provider = self.metadata.provider
+
+        if not query or not query.strip():
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error="query가 비어있습니다",
+                empty_reason="validation_error",
+                evidence=EvidenceEnvelope(status="error", errors=["query가 비어있습니다"]),
+            )
+
+        if self._action is None:
+            logger.debug("[keyword_analyzer] action이 None - 빈 결과 반환")
+            return LookupResult(
+                success=True,
+                query=query,
+                provider=provider,
+                empty_reason="no_match",
+                evidence=EvidenceEnvelope(status="empty"),
+            )
+
+        date_from = context.get("date_from", "")
+        date_to = context.get("date_to", "")
+        searchword = context.get("searchword", "")
+        result_count = int(context.get("result_count", 5))
+
+        try:
+            core_kw, related = await asyncio.wait_for(
+                self._fetch_all(date_from, date_to, searchword, result_count),
+                timeout=self.metadata.timeout_sec,
+            )
+        except asyncio.TimeoutError:
+            msg = f"API 호출 타임아웃 ({self.metadata.timeout_sec}초 초과)"
+            logger.warning(f"[keyword_analyzer] {msg}")
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error=msg,
+                empty_reason="provider_error",
+                evidence=EvidenceEnvelope(status="error", errors=[msg]),
+            )
+        except Exception as exc:
+            logger.error(f"[keyword_analyzer] API 호출 오류: {exc}", exc_info=True)
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error=str(exc),
+                empty_reason="provider_error",
+                evidence=EvidenceEnvelope(status="error", errors=[str(exc)]),
+            )
+
+        all_results: List[Dict[str, Any]] = []
+        evidence_items: List[EvidenceItem] = []
+        errors: List[str] = []
+
+        if core_kw is not None:
+            for item in core_kw:
+                item["_source_api"] = "core_keyword"
+                all_results.append(item)
+                evidence_items.append(
+                    EvidenceItem(
+                        source_type="api",
+                        title=item.get("label", ""),
+                        excerpt=f"핵심키워드: {item.get('label', '')}, "
+                        f"점수={item.get('value', 0)}",
+                        provider_meta={"provider": provider, "api": "core_keyword"},
+                    )
+                )
+        else:
+            errors.append("핵심키워드 API 실패")
+
+        if related is not None:
+            for item in related:
+                item["_source_api"] = "related_word"
+                all_results.append(item)
+                evidence_items.append(
+                    EvidenceItem(
+                        source_type="api",
+                        title=item.get("label", ""),
+                        excerpt=f"연관어: {item.get('label', '')}, " f"점수={item.get('value', 0)}",
+                        provider_meta={"provider": provider, "api": "related_word"},
+                    )
+                )
+        else:
+            if searchword:
+                errors.append("연관어 API 실패")
+
+        if not all_results:
+            status = "error" if errors else "empty"
+            return LookupResult(
+                success=not errors,
+                query=query,
+                provider=provider,
+                empty_reason="no_match" if not errors else "provider_error",
+                error="; ".join(errors) if errors else None,
+                evidence=EvidenceEnvelope(items=[], status=status, errors=errors),
+            )
+
+        context_text = self._build_context_text(core_kw, related)
+        status = "ok" if not errors else "partial"
+
+        return LookupResult(
+            success=True,
+            query=query,
+            results=all_results,
+            context_text=context_text,
+            provider=provider,
+            evidence=EvidenceEnvelope(
+                items=evidence_items,
+                summary_text=context_text,
+                status=status,
+                errors=errors,
+            ),
+        )
+
+    async def _fetch_all(
+        self,
+        date_from: str,
+        date_to: str,
+        searchword: str,
+        result_count: int,
+    ) -> tuple:
+        """핵심키워드 + 연관어를 병렬 호출한다."""
+        tasks = []
+
+        # 핵심키워드는 date_from/date_to가 있으면 항상 호출
+        if date_from and date_to:
+            tasks.append(
+                self._safe_call(
+                    self._action.get_core_keywords,
+                    date_from=date_from,
+                    date_to=date_to,
+                    result_count=result_count,
+                )
+            )
+        else:
+            tasks.append(self._noop())
+
+        # 연관어는 searchword가 있을 때만 호출
+        if date_from and date_to and searchword:
+            tasks.append(
+                self._safe_call(
+                    self._action.get_related_words,
+                    date_from=date_from,
+                    date_to=date_to,
+                    searchword=searchword,
+                    result_count=result_count,
+                )
+            )
+        else:
+            tasks.append(self._noop())
+
+        return tuple(await asyncio.gather(*tasks))
+
+    @staticmethod
+    async def _safe_call(fn, **kwargs) -> Optional[List[Dict[str, Any]]]:
+        """개별 API 호출을 안전하게 래핑한다."""
+        try:
+            return await fn(**kwargs)
+        except Exception as exc:
+            logger.warning(f"[keyword_analyzer] 개별 API 실패: {exc}")
+            return None
+
+    @staticmethod
+    async def _noop() -> None:
+        """빈 결과를 반환하는 no-op 코루틴."""
+        return None
+
+    @staticmethod
+    def _build_context_text(
+        core_kw: Optional[List],
+        related: Optional[List],
+    ) -> str:
+        """조합 결과에서 자연어 요약을 생성한다."""
+        parts: List[str] = []
+
+        if core_kw:
+            items = []
+            for k in core_kw[:5]:
+                label = k.get("label", "")
+                value = k.get("value", 0)
+                try:
+                    value_f = float(value)
+                    items.append(f"{label}({value_f:,.0f}건)")
+                except (ValueError, TypeError):
+                    items.append(f"{label}({value})")
+            if items:
+                parts.append(f"핵심 키워드: {', '.join(items)}")
+
+        if related:
+            items = []
+            for r in related[:5]:
+                label = r.get("label", "")
+                value = r.get("value", 0)
+                try:
+                    value_f = float(value)
+                    items.append(f"{label}({value_f:,.1f}점)")
+                except (ValueError, TypeError):
+                    items.append(f"{label}({value})")
+            if items:
+                parts.append(f"연관어: {', '.join(items)}")
+
+        return ", ".join(parts) if parts else ""

src/inference/graph/capabilities/rag_search.py

@@ -0,0 +1,287 @@
+"""rag_search capability — 로컬 문서 하이브리드 검색을 LangGraph capability로 표준화.
+
+Issue #395: local RAG 검색을 LangGraph tool capability로 표준화.
+
+ApiLookupCapability 패턴을 따라 파라미터 검증, 타임아웃, 결과 정규화,
+fallback 정책(empty/low-confidence)을 구현한다.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+from loguru import logger
+
+from src.inference.index_manager import IndexType
+
+from .base import CapabilityBase, CapabilityMetadata, EvidenceEnvelope, EvidenceItem, LookupResult
+from .defaults import get_timeout
+
+# ---------------------------------------------------------------------------
+# 상수
+# ---------------------------------------------------------------------------
+
+LOW_CONFIDENCE_THRESHOLD: float = 0.3
+"""저신뢰도 기본 임계값. 모든 결과 score가 이 값 미만이면 low_confidence로 분류."""
+
+_VALID_SOURCE_TYPES: frozenset[str] = frozenset(t.value for t in IndexType)
+_DEFAULT_SOURCE_TYPES: list[str] = [t.value for t in IndexType]
+
+
+# ---------------------------------------------------------------------------
+# 파라미터 validator
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RagSearchParams:
+    """rag_search 호출 파라미터 — context에서 추출·정규화·검증."""
+
+    query: str
+    top_k: int = 5
+    source_types: List[str] = field(default_factory=lambda: list(_DEFAULT_SOURCE_TYPES))
+    min_confidence: float = LOW_CONFIDENCE_THRESHOLD
+
+    @classmethod
+    def from_context(
+        cls,
+        query: str,
+        context: Dict[str, Any],
+        default_min_confidence: float = LOW_CONFIDENCE_THRESHOLD,
+    ) -> "RagSearchParams":
+        """context에서 파라미터를 추출하고 alias를 정규화한다."""
+        top_k = int(context.get("rag_top_k") or context.get("top_k") or context.get("count") or 5)
+
+        raw_filters = context.get("filters") or context.get("source_types")
+        if isinstance(raw_filters, list):
+            source_types = [str(f).lower() for f in raw_filters]
+        else:
+            source_types = list(_DEFAULT_SOURCE_TYPES)
+
+        raw = context.get("rag_min_confidence")
+        if raw is None:
+            raw = context.get("min_confidence")
+        if raw is None:
+            raw = context.get("score_threshold")
+        if raw is None:
+            raw = default_min_confidence
+        min_confidence = float(raw)
+
+        return cls(
+            query=query.strip(),
+            top_k=max(1, min(50, top_k)),
+            source_types=source_types,
+            min_confidence=max(0.0, min(1.0, min_confidence)),
+        )
+
+    def validate(self) -> Optional[str]:
+        """검증 실패 시 오류 메시지, 통과 시 None."""
+        if not self.query:
+            return "query가 비어있습니다"
+        if len(self.query) > 2000:
+            return f"query가 너무 깁니다 ({len(self.query)}자, 최대 2000자)"
+        invalid = [t for t in self.source_types if t not in _VALID_SOURCE_TYPES]
+        if invalid:
+            return f"유효하지 않은 source_type: {invalid}"
+        return None
+
+
+# ---------------------------------------------------------------------------
+# 결과 정규화 헬퍼
+# ---------------------------------------------------------------------------
+
+
+def _normalize_result(raw: Dict[str, Any]) -> Dict[str, Any]:
+    """raw SearchResult dict에 공통 스키마 필드를 보강한다.
+
+    추가 필드: excerpt, file_path, page, score, source_type, doc_id, title.
+    기존 필드는 그대로 유지.
+    """
+    content = raw.get("content", "")
+    metadata = raw.get("metadata", {})
+    result = dict(raw)
+    result["excerpt"] = content[:500] if content else ""
+    result["file_path"] = metadata.get("file_path", "")
+    result["page"] = metadata.get("page", raw.get("chunk_index", 0))
+    result["score"] = raw.get("score", 0.0)
+    result["source_type"] = raw.get("source_type", "")
+    result["doc_id"] = raw.get("doc_id", "")
+    result["title"] = raw.get("title", "")
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Capability
+# ---------------------------------------------------------------------------
+
+
+class RagSearchCapability(CapabilityBase):
+    """로컬 문서(법령/매뉴얼/사례/공지) 하이브리드 검색 capability.
+
+    기존 api_server의 _rag_search_tool closure를 주입받아
+    CapabilityBase 인터페이스로 래핑하고, 파라미터 검증·타임아웃·
+    결과 정규화·fallback 정책을 적용한다.
+
+    Parameters
+    ----------
+    execute_fn : Callable
+        ``async (query, context, session) -> dict`` 시그니처의 실행 함수.
+    low_confidence_threshold : float
+        저신뢰도 임계값. 모든 결과가 이 값 미만이면 ``low_confidence``로 분류.
+    """
+
+    def __init__(
+        self,
+        execute_fn: Callable[..., Any],
+        low_confidence_threshold: float = LOW_CONFIDENCE_THRESHOLD,
+    ) -> None:
+        self._execute_fn = execute_fn
+        self._low_confidence_threshold = low_confidence_threshold
+
+    @property
+    def metadata(self) -> CapabilityMetadata:
+        return CapabilityMetadata(
+            name="rag_search",
+            description=(
+                "내부 법령, 매뉴얼, 민원 사례, 공지사항 등 로컬 문서를 "
+                "하이브리드 검색(BM25 + 벡터)으로 조회합니다."
+            ),
+            approval_summary="로컬 문서 DB에서 관련 법령/사례를 검색합니다.",
+            provider="local_vectordb",
+            timeout_sec=get_timeout("rag_search"),
+        )
+
+    async def execute(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: Any,
+    ) -> LookupResult:
+        """검색 실행 — 파라미터 검증, 타임아웃, 정규화, fallback 적용."""
+        provider = self.metadata.provider
+
+        params = RagSearchParams.from_context(
+            query, context, default_min_confidence=self._low_confidence_threshold
+        )
+        validation_error = params.validate()
+        if validation_error:
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error=validation_error,
+                empty_reason="validation_error",
+            )
+
+        try:
+            raw = await asyncio.wait_for(
+                self._execute_fn(query=params.query, context=context, session=session),
+                timeout=self.metadata.timeout_sec,
+            )
+        except asyncio.TimeoutError:
+            logger.warning(f"[rag_search] 타임아웃 ({self.metadata.timeout_sec}s 초과)")
+            return LookupResult(
+                success=False,
+                query=params.query,
+                provider=provider,
+                error=f"검색 타임아웃 ({self.metadata.timeout_sec}초 초과)",
+                empty_reason="provider_error",
+            )
+        except Exception as exc:
+            logger.error(f"[rag_search] 검색 오류: {exc}", exc_info=True)
+            return LookupResult(
+                success=False,
+                query=params.query,
+                provider=provider,
+                error=str(exc),
+                empty_reason="provider_error",
+            )
+
+        if not isinstance(raw, dict):
+            raw = {}
+
+        if raw.get("error"):
+            return LookupResult(
+                success=False,
+                query=raw.get("query", params.query),
+                provider=provider,
+                error=raw["error"],
+                empty_reason="provider_error",
+                evidence=EvidenceEnvelope(
+                    status="error",
+                    errors=[raw["error"]],
+                ),
+            )
+
+        raw_query = raw.get("query", params.query)
+        raw_context_text = raw.get("context_text", "")
+        raw_results = raw.get("results", [])
+        normalized = [_normalize_result(r) for r in raw_results]
+
+        # EvidenceItem으로 정규화
+        evidence_items = []
+        for r in normalized:
+            evidence_items.append(
+                EvidenceItem(
+                    source_type="rag",
+                    title=r.get("title", ""),
+                    excerpt=r.get("excerpt", "")[:500],
+                    link_or_path=r.get("file_path", ""),
+                    page=r.get("page"),
+                    score=float(r.get("score", 0.0)),
+                    provider_meta={"provider": provider},
+                )
+            )
+
+        if not normalized:
+            return LookupResult(
+                success=True,
+                query=raw_query,
+                provider=provider,
+                empty_reason="no_match",
+                context_text=raw_context_text,
+                evidence=EvidenceEnvelope(items=[], status="empty"),
+            )
+
+        confident = [r for r in normalized if r["score"] >= params.min_confidence]
+        if not confident:
+            logger.info(f"[rag_search] 모든 결과가 저신뢰도 (threshold={params.min_confidence})")
+            return LookupResult(
+                success=True,
+                query=raw_query,
+                results=normalized,
+                context_text=raw_context_text,
+                provider=provider,
+                empty_reason="low_confidence",
+                evidence=EvidenceEnvelope(
+                    items=evidence_items,
+                    status="partial",
+                ),
+            )
+
+        confident_evidence = [ei for ei in evidence_items if ei.score >= params.min_confidence]
+        citations = [
+            {
+                "source_type": r["source_type"],
+                "doc_id": r["doc_id"],
+                "title": r["title"],
+                "score": r["score"],
+                "excerpt": r["excerpt"][:200],
+            }
+            for r in confident
+        ]
+
+        return LookupResult(
+            success=True,
+            query=raw_query,
+            results=confident,
+            context_text=raw_context_text,
+            citations=citations,
+            provider=provider,
+            evidence=EvidenceEnvelope(
+                items=confident_evidence,
+                status="ok",
+            ),
+        )

src/inference/graph/capabilities/registry.py

@@ -0,0 +1,125 @@
+"""tool metadata registry — MVP capability의 단일 소스.
+
+Issue #416: tool metadata registry 및 LangGraph executor binding 정리.
+
+이 모듈은 다음을 보장한다:
+- planner가 읽는 metadata와 executor binding이 같은 소스에서 나온다
+- approval prompt와 session log가 동일한 capability identifier를 사용한다
+- 비MVP capability가 registry 수준에서 차단된다
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List
+
+from src.inference.tool_router import ToolType
+
+from .api_lookup import ApiLookupCapability
+from .append_evidence import AppendEvidenceCapability
+from .base import CapabilityBase, CapabilityMetadata
+from .demographics_lookup import DemographicsLookupCapability
+from .draft_civil_response import DraftCivilResponseCapability
+from .issue_detector import IssueDetectorCapability
+from .keyword_analyzer import KeywordAnalyzerCapability
+from .rag_search import RagSearchCapability
+from .stats_lookup import StatsLookupCapability
+
+# ---------------------------------------------------------------------------
+# MVP capability stable identifiers (session log, approval prompt에서 사용)
+# ToolType enum에서 파생하여 단일 소스를 유지한다.
+# ---------------------------------------------------------------------------
+
+MVP_CAPABILITY_IDS: frozenset[str] = frozenset(t.value for t in ToolType)
+
+
+def get_mvp_capability_ids() -> frozenset[str]:
+    """MVP capability stable identifier 집합을 반환한다.
+
+    plan_validator, planner_adapter 등에서 화이트리스트로 사용한다.
+    """
+    return MVP_CAPABILITY_IDS
+
+
+def build_mvp_registry(
+    *,
+    rag_search_fn: Callable[..., Any],
+    api_lookup_action: Any = None,
+    draft_civil_response_fn: Callable[..., Any],
+    append_evidence_fn: Callable[..., Any],
+    rag_low_confidence_threshold: float = 0.3,
+) -> Dict[str, CapabilityBase]:
+    """MVP 4개 capability를 CapabilityBase 인스턴스로 구성한 registry를 반환한다.
+
+    모든 capability가 CapabilityBase를 구현하므로,
+    RegistryExecutorAdapter.get_tool_metadata()가 일관된 metadata를 반환한다.
+
+    Parameters
+    ----------
+    rag_search_fn : Callable
+        ``async (query, context, session) -> dict`` 형태의 RAG 검색 함수.
+    api_lookup_action : Any, optional
+        ``MinwonAnalysisAction`` 인스턴스. None이면 빈 결과 반환.
+    draft_civil_response_fn : Callable
+        ``async (query, context, session) -> dict`` 형태의 민원 답변 생성 함수.
+    append_evidence_fn : Callable
+        ``async (query, context, session) -> dict`` 형태의 근거 보강 함수.
+    rag_low_confidence_threshold : float
+        RAG 검색 저신뢰도 임계값. 기본값 0.3.
+
+    Returns
+    -------
+    Dict[str, CapabilityBase]
+        capability name -> CapabilityBase 인스턴스 매핑.
+    """
+    return {
+        "rag_search": RagSearchCapability(
+            execute_fn=rag_search_fn,
+            low_confidence_threshold=rag_low_confidence_threshold,
+        ),
+        "api_lookup": ApiLookupCapability(action=api_lookup_action),
+        "draft_civil_response": DraftCivilResponseCapability(
+            execute_fn=draft_civil_response_fn,
+        ),
+        "append_evidence": AppendEvidenceCapability(execute_fn=append_evidence_fn),
+        "issue_detector": IssueDetectorCapability(action=api_lookup_action),
+        "stats_lookup": StatsLookupCapability(action=api_lookup_action),
+        "keyword_analyzer": KeywordAnalyzerCapability(action=api_lookup_action),
+        "demographics_lookup": DemographicsLookupCapability(action=api_lookup_action),
+    }
+
+
+def get_all_metadata(
+    registry: Dict[str, CapabilityBase],
+) -> List[Dict[str, Any]]:
+    """registry에 등록된 모든 capability의 metadata를 dict 목록으로 반환한다.
+
+    planner가 tool 목록을 구성할 때 사용한다.
+
+    Parameters
+    ----------
+    registry : Dict[str, CapabilityBase]
+        build_mvp_registry()가 반환한 registry.
+
+    Returns
+    -------
+    List[Dict[str, Any]]
+        각 capability의 metadata dict 목록.
+    """
+    result: List[Dict[str, Any]] = []
+    for name, cap in registry.items():
+        meta = cap.metadata
+        result.append(
+            {
+                "name": meta.name,
+                "description": meta.description,
+                "approval_summary": meta.approval_summary,
+                "provider": meta.provider,
+                "timeout_sec": meta.timeout_sec,
+            }
+        )
+    return result
+
+
+def is_mvp_capability(name: str) -> bool:
+    """주어진 이름이 MVP capability인지 확인한다."""
+    return name in MVP_CAPABILITY_IDS

src/inference/graph/capabilities/stats_lookup.py

@@ -0,0 +1,287 @@
+"""stats_lookup capability — 맞춤형통계+트렌드+건수+기관순위+지역순위 조합.
+
+Issue #487: 민원 통계 조회 도구.
+5개 API를 조합하여 민원 통계 현황을 제공한다.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional
+
+from loguru import logger
+
+from .base import (
+    CapabilityBase,
+    CapabilityMetadata,
+    EvidenceEnvelope,
+    EvidenceItem,
+    LookupResult,
+)
+from .defaults import get_timeout
+
+
+class StatsLookupCapability(CapabilityBase):
+    """민원 통계 조회 capability.
+
+    키워드가 있으면 건수+트렌드, 없으면 통계+기관순위+지역순위를 조합한다.
+
+    Parameters
+    ----------
+    action : Optional[MinwonAnalysisAction]
+        API 호출용 Action 인스턴스. None이면 빈 결과 반환.
+    """
+
+    def __init__(self, action: Optional[Any] = None) -> None:
+        self._action = action
+
+    @property
+    def metadata(self) -> CapabilityMetadata:
+        return CapabilityMetadata(
+            name="stats_lookup",
+            description=(
+                "민원 통계, 트렌드, 건수, 기관/지역 순위를 조합하여 " "민원 현황 통계를 제공합니다."
+            ),
+            approval_summary="공공데이터포털에서 민원 통계 현황을 조회합니다.",
+            provider="data.go.kr",
+            timeout_sec=get_timeout("stats_lookup"),
+        )
+
+    async def execute(
+        self,
+        query: str,
+        context: Dict[str, Any],
+        session: Any,
+    ) -> LookupResult:
+        """조건에 따라 API를 조합 호출하고 결과를 반환한다."""
+        provider = self.metadata.provider
+
+        if not query or not query.strip():
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error="query가 비어있습니다",
+                empty_reason="validation_error",
+                evidence=EvidenceEnvelope(status="error", errors=["query가 비어있습니다"]),
+            )
+
+        if self._action is None:
+            logger.debug("[stats_lookup] action이 None - 빈 결과 반환")
+            return LookupResult(
+                success=True,
+                query=query,
+                provider=provider,
+                empty_reason="no_match",
+                evidence=EvidenceEnvelope(status="empty"),
+            )
+
+        date_from = context.get("date_from", "")
+        date_to = context.get("date_to", "")
+        searchword = context.get("searchword", "")
+        period = context.get("period", "DAILY")
+        top_n = int(context.get("top_n", 5))
+
+        try:
+            results_map = await asyncio.wait_for(
+                self._fetch_all(date_from, date_to, searchword, period, top_n),
+                timeout=self.metadata.timeout_sec,
+            )
+        except asyncio.TimeoutError:
+            msg = f"API 호출 타임아웃 ({self.metadata.timeout_sec}초 초과)"
+            logger.warning(f"[stats_lookup] {msg}")
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error=msg,
+                empty_reason="provider_error",
+                evidence=EvidenceEnvelope(status="error", errors=[msg]),
+            )
+        except Exception as exc:
+            logger.error(f"[stats_lookup] API 호출 오류: {exc}", exc_info=True)
+            return LookupResult(
+                success=False,
+                query=query,
+                provider=provider,
+                error=str(exc),
+                empty_reason="provider_error",
+                evidence=EvidenceEnvelope(status="error", errors=[str(exc)]),
+            )
+
+        all_results: List[Dict[str, Any]] = []
+        evidence_items: List[EvidenceItem] = []
+        errors: List[str] = []
+
+        for api_name, items in results_map.items():
+            if items is None:
+                errors.append(f"{api_name} API 실패")
+                continue
+            for item in items:
+                item["_source_api"] = api_name
+                all_results.append(item)
+                evidence_items.append(
+                    EvidenceItem(
+                        source_type="api",
+                        title=item.get("label", item.get("term", "")),
+                        excerpt=self._format_item(api_name, item),
+                        provider_meta={"provider": provider, "api": api_name},
+                    )
+                )
+
+        if not all_results:
+            status = "error" if len(errors) == len(results_map) else "empty"
+            return LookupResult(
+                success=len(errors) < len(results_map),
+                query=query,
+                provider=provider,
+                empty_reason="no_match" if len(errors) < len(results_map) else "provider_error",
+                error="; ".join(errors) if errors else None,
+                evidence=EvidenceEnvelope(items=[], status=status, errors=errors),
+            )
+
+        context_text = self._build_context_text(results_map, date_from, date_to)
+        status = "ok" if not errors else "partial"
+
+        return LookupResult(
+            success=True,
+            query=query,
+            results=all_results,
+            context_text=context_text,
+            provider=provider,
+            evidence=EvidenceEnvelope(
+                items=evidence_items,
+                summary_text=context_text,
+                status=status,
+                errors=errors,
+            ),
+        )
+
+    async def _fetch_all(
+        self,
+        date_from: str,
+        date_to: str,
+        searchword: str,
+        period: str,
+        top_n: int,
+    ) -> Dict[str, Optional[List]]:
+        """조건에 따라 적절한 API를 병렬 호출한다."""
+        tasks: Dict[str, Any] = {}
+
+        if searchword:
+            # 키워드 기반: 건수 + 트렌드
+            tasks["doc_count"] = self._safe_call(
+                self._action.get_doc_count,
+                date_from=date_from,
+                date_to=date_to,
+                searchword=searchword,
+            )
+            if date_from and date_to:
+                tasks["trend"] = self._safe_call(
+                    self._action.get_trend,
+                    date_from=date_from + "00",
+                    date_to=date_to + "23",
+                    period=period,
+                )
+        else:
+            # 일반 통계: 통계 + 기관순위 + 지역순위
+            if date_from and date_to:
+                tasks["statistics"] = self._safe_call(
+                    self._action.get_statistics,
+                    date_from=date_from,
+                    date_to=date_to,
+                    period=period,
+                )
+                tasks["org_ranking"] = self._safe_call(
+                    self._action.get_org_ranking,
+                    date_from=date_from,
+                    date_to=date_to,
+                    top_n=top_n,
+                )
+                tasks["region_ranking"] = self._safe_call(
+                    self._action.get_region_ranking,
+                    date_from=date_from,
+                    date_to=date_to,
+                    top_n=top_n,
+                )
+
+        if not tasks:
+            return {}
+
+        keys = list(tasks.keys())
+        values = await asyncio.gather(*tasks.values())
+        return dict(zip(keys, values))
+
+    @staticmethod
+    async def _safe_call(fn, **kwargs) -> Optional[List[Dict[str, Any]]]:
+        """개별 API 호출을 안전하게 래핑한다."""
+        try:
+            return await fn(**kwargs)
+        except Exception as exc:
+            logger.warning(f"[stats_lookup] 개별 API 실패: {exc}")
+            return None
+
+    @staticmethod
+    def _format_item(api_name: str, item: Dict[str, Any]) -> str:
+        """개별 아이템의 요약 문자열을 생성한다."""
+        label = item.get("label", "")
+        hits = item.get("hits", "")
+        if api_name == "doc_count":
+            pttn = item.get("pttn", 0)
+            dfpt = item.get("dfpt", 0)
+            saeol = item.get("saeol", 0)
+            return f"국민신문고={pttn}, 민원24={dfpt}, 새올={saeol}"
+        if api_name == "trend":
+            ratio = item.get("prebRatio", "")
+            return f"{label}: {hits}건, 전일대비 {ratio}%"
+        return f"{label}: {hits}건"
+
+    @staticmethod
+    def _build_context_text(
+        results_map: Dict[str, Optional[List]],
+        date_from: str,
+        date_to: str,
+    ) -> str:
+        """조합 결과에서 자연어 요약을 생성한다."""
+        parts: List[str] = []
+        period_str = ""
+        if date_from and date_to:
+            period_str = (
+                f"{date_from[:4]}/{date_from[4:6]}/{date_from[6:8]}~{date_to[4:6]}/{date_to[6:8]}"
+            )
+
+        doc_count = results_map.get("doc_count")
+        if doc_count and len(doc_count) > 0:
+            item = doc_count[0]
+            try:
+                pttn = int(item.get("pttn") or 0)
+                dfpt = int(item.get("dfpt") or 0)
+                saeol = int(item.get("saeol") or 0)
+            except (ValueError, TypeError):
+                pttn, dfpt, saeol = 0, 0, 0
+            total = pttn + dfpt + saeol
+            parts.append(f"{period_str} 총 {total:,}건" if period_str else f"총 {total:,}건")
+
+        stats = results_map.get("statistics")
+        if stats:
+            total = sum(int(s.get("hits", 0)) for s in stats)
+            parts.append(f"{period_str} 총 {total:,}건" if period_str else f"총 {total:,}건")
+
+        trend = results_map.get("trend")
+        if trend and len(trend) > 0:
+            last = trend[-1]
+            ratio = last.get("prebRatio", "")
+            if ratio:
+                parts.append(f"전일대비 {'+' if not ratio.startswith('-') else ''}{ratio}%")
+
+        region = results_map.get("region_ranking")
+        if region and len(region) > 0:
+            top = region[0]
+            parts.append(f"{top.get('label', '')} 최다({int(top.get('hits', 0)):,}건)")
+
+        org = results_map.get("org_ranking")
+        if org and len(org) > 0:
+            top = org[0]
+            parts.append(f"기관 최다: {top.get('label', '')}({int(top.get('hits', 0)):,}건)")
+
+        return ", ".join(parts) if parts else ""

src/inference/graph/executor_adapter.py

@@ -0,0 +1,190 @@
+"""Executor adapter: tool registry에서 tool을 조회하고 실행.
+
+Issue #415: LangGraph runtime 기반 및 planner/executor adapter 구성.
+Issue #416: tool metadata registry 및 LangGraph executor binding 정리.
+
+두 가지 구현체를 제공한다:
+- `ExecutorAdapter` (ABC): 추상 인터페이스
+- `RegistryExecutorAdapter`: CapabilityBase 기반 registry를 사용하는 구현체
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Dict, List, Optional
+
+from loguru import logger
+
+
+class ExecutorAdapter(ABC):
+    """Tool executor 추상 인터페이스.
+
+    LangGraph graph의 `tool_execute` 노드에서 호출된다.
+    """
+
+    @abstractmethod
+    async def execute(
+        self,
+        tool_name: str,
+        query: str,
+        context: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """tool을 실행하고 결과를 반환한다.
+
+        Parameters
+        ----------
+        tool_name : str
+            실행할 tool 이름.
+        query : str
+            사용자 요청 텍스트.
+        context : Dict[str, Any]
+            누적 컨텍스트 (이전 tool 결과 포함).
+
+        Returns
+        -------
+        Dict[str, Any]
+            tool 실행 결과. 최소 {"success": bool, ...} 형태.
+            실패 시 {"success": False, "error": str}.
+        """
+        ...
+
+    @abstractmethod
+    def list_tools(self) -> list[str]:
+        """등록된 tool 이름 목록을 반환한다."""
+        ...
+
+
+class RegistryExecutorAdapter(ExecutorAdapter):
+    """기존 tool_registry를 재사용하는 executor.
+
+    `tool_registry`는 `Dict[str, Callable]` 형태로 주입받는다.
+    각 callable은 `async (query, context, session) -> dict` 시그니처여야 한다.
+    기존 `AgentLoop._execute_tool()` 로직을 계승한다.
+
+    Parameters
+    ----------
+    tool_registry : Dict[str, Callable]
+        tool 이름 -> async callable 매핑.
+    session_store : SessionStore
+        GovOn 세션 저장소. executor가 tool 호출 시 세션을 주입한다.
+    default_timeout : float
+        tool 실행 제한 시간 (초). 기본값 30.0.
+    """
+
+    def __init__(
+        self,
+        tool_registry: Dict[str, Callable],
+        session_store: Any,  # SessionStore (순환 import 방지를 위해 Any 사용)
+        default_timeout: float = 30.0,
+    ) -> None:
+        self._tools = tool_registry
+        self._session_store = session_store
+        self._default_timeout = default_timeout
+
+    async def execute(
+        self,
+        tool_name: str,
+        query: str,
+        context: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """tool을 조회하고 타임아웃 포함하여 실행한다.
+
+        registry에 등록되지 않은 tool은 비MVP capability로 차단한다.
+        """
+        from src.inference.graph.capabilities.registry import is_mvp_capability
+
+        # 비MVP capability 차단
+        if not is_mvp_capability(tool_name):
+            logger.warning(f"[RegistryExecutorAdapter] 비MVP capability 차단: {tool_name}")
+            return {"success": False, "error": f"비MVP capability: {tool_name}"}
+
+        tool_fn = self._tools.get(tool_name)
+        if tool_fn is None:
+            return {"success": False, "error": f"등록되지 않은 tool: {tool_name}"}
+
+        session = self._session_store.get_or_create(context.get("session_id"))
+        start = time.monotonic()
+        try:
+            result = await asyncio.wait_for(
+                tool_fn(query=query, context=context, session=session),
+                timeout=self._default_timeout,
+            )
+            latency = (time.monotonic() - start) * 1000
+            if isinstance(result, dict):
+                if "latency_ms" not in result:
+                    result["latency_ms"] = latency
+                result.setdefault("success", True)
+                return result
+            return {"success": True, "result": result, "latency_ms": latency}
+        except asyncio.TimeoutError:
+            latency = (time.monotonic() - start) * 1000
+            return {
+                "success": False,
+                "error": f"tool {tool_name} 타임아웃 ({self._default_timeout}초)",
+                "latency_ms": latency,
+            }
+        except Exception as exc:
+            latency = (time.monotonic() - start) * 1000
+            logger.error(f"[RegistryExecutorAdapter] tool {tool_name} 오류: {exc}", exc_info=True)
+            return {"success": False, "error": str(exc), "latency_ms": latency}
+
+    def list_tools(self) -> list[str]:
+        """등록된 tool 이름 목록을 반환한다."""
+        return list(self._tools.keys())
+
+    def get_tool_metadata(self, tool_name: str) -> Optional[dict]:
+        """capability의 planner metadata를 반환한다.
+
+        CapabilityBase 인스턴스가 등록된 경우 metadata 프로퍼티에서 정보를 추출하고,
+        일반 callable인 경우 이름만 포함된 기본 dict를 반환한다.
+        등록되지 않은 tool이면 None을 반환한다.
+
+        Parameters
+        ----------
+        tool_name : str
+            조회할 tool 이름.
+
+        Returns
+        -------
+        Optional[dict]
+            tool metadata dict 또는 None.
+        """
+        tool = self._tools.get(tool_name)
+        if tool is None:
+            return None
+        # CapabilityBase 인터페이스 지원
+        if hasattr(tool, "metadata"):
+            meta = tool.metadata
+            return {
+                "name": meta.name,
+                "description": meta.description,
+                "approval_summary": meta.approval_summary,
+                "provider": getattr(meta, "provider", ""),
+            }
+        return {
+            "name": tool_name,
+            "description": "",
+            "approval_summary": "",
+            "provider": "",
+        }
+
+    def get_tool_descriptions_for_planner(self) -> List[dict]:
+        """planner가 읽을 tool 목록을 단일 메서드로 노출한다.
+
+        등록된 모든 tool의 metadata를 dict 목록으로 반환한다.
+        CapabilityBase 인스턴스는 풍부한 metadata를, 일반 callable은
+        이름만 포함된 기본 dict를 반환한다.
+
+        Returns
+        -------
+        List[dict]
+            각 tool의 metadata dict 목록.
+        """
+        descriptions: List[dict] = []
+        for name in self._tools:
+            meta = self.get_tool_metadata(name)
+            if meta is not None:
+                descriptions.append(meta)
+        return descriptions

src/inference/graph/nodes.py

@@ -0,0 +1,752 @@
+"""GovOn LangGraph 노드 함수 모음.
+
+Issue #415: LangGraph runtime 기반 및 planner/executor adapter 구성.
+
+6개 노드를 정의한다:
+  session_load -> planner -> approval_wait -> tool_execute -> synthesis -> persist
+
+각 노드는 `GovOnGraphState`를 입력으로 받고 상태 업데이트 dict를 반환한다.
+I/O가 필요한 노드는 async 함수이며, `approval_wait` 노드는 `interrupt()`를
+사용하는 human-in-the-loop 승인 게이트이므로 sync 함수로 유지한다.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import TYPE_CHECKING, Any, Dict, List
+
+from langchain_core.messages import AIMessage
+from langgraph.types import interrupt
+from loguru import logger
+
+from src.inference.query_builder import (
+    build_query_variants,
+    build_runtime_query_context,
+    resolve_tool_query,
+)
+
+from .plan_validator import PlanValidationError, ToolPlanValidator
+from .state import ApprovalStatus, GovOnGraphState
+
+if TYPE_CHECKING:
+    from src.inference.session_context import SessionStore
+
+    from .executor_adapter import ExecutorAdapter
+    from .planner_adapter import PlannerAdapter
+
+
+async def session_load_node(
+    state: GovOnGraphState,
+    *,
+    session_store: "SessionStore",
+) -> dict:
+    """세션 로드 노드.
+
+    SessionStore에서 기존 세션을 불러오거나 새 세션을 생성한다.
+    대화 히스토리와 tool 사용 기록을 accumulated_context에 주입한다.
+
+    Parameters
+    ----------
+    state : GovOnGraphState
+        현재 graph state. `session_id`와 `messages`를 읽는다.
+    session_store : SessionStore
+        graph config에서 closure로 주입되는 세션 저장소.
+
+    Returns
+    -------
+    dict
+        `session_id`와 `accumulated_context`를 갱신한다.
+    """
+    _start = time.monotonic()
+
+    session_id: str | None = state.get("session_id")
+    session = session_store.get_or_create(session_id)
+
+    messages = state.get("messages", [])
+    query = messages[-1].content if messages else ""
+    accumulated_context = build_runtime_query_context(session, query)
+
+    _latency_ms = round((time.monotonic() - _start) * 1000, 2)
+    logger.debug(
+        f"[session_load] session_id={session.session_id} "
+        f"query_len={len(query)} latency_ms={_latency_ms}"
+    )
+
+    return {
+        "session_id": session.session_id,
+        "accumulated_context": accumulated_context,
+        "node_latencies": {"session_load": _latency_ms},
+    }
+
+
+async def planner_node(
+    state: GovOnGraphState,
+    *,
+    planner_adapter: "PlannerAdapter",
+) -> dict:
+    """Planner 노드.
+
+    PlannerAdapter를 호출하여 구조화된 실행 계획을 생성한다.
+    LLMPlannerAdapter가 기본으로 사용된다. SKIP_MODEL_LOAD=true 환경에서는
+    RegexPlannerAdapter가 CI fallback으로 동작한다.
+
+    Parameters
+    ----------
+    state : GovOnGraphState
+        현재 graph state. `messages`와 `accumulated_context`를 읽는다.
+    planner_adapter : PlannerAdapter
+        graph config에서 closure로 주입되는 planner 어댑터.
+
+    Returns
+    -------
+    dict
+        `task_type`, `goal`, `reason`, `planned_tools`를 갱신한다.
+    """
+    _start = time.monotonic()
+
+    messages = state.get("messages", [])
+    context = state.get("accumulated_context", {})
+
+    plan = await planner_adapter.plan(messages=messages, context=context)
+
+    validator = ToolPlanValidator()
+    try:
+        validator.validate(plan)
+    except PlanValidationError as e:
+        _latency_ms = round((time.monotonic() - _start) * 1000, 2)
+        logger.warning(f"[planner] validation 실패: {e} latency_ms={_latency_ms}")
+        return {
+            **validator.make_fallback_plan(e),
+            "task_type": "",
+            "node_latencies": {"planner": _latency_ms},
+        }
+
+    logger.info(
+        f"[planner] task_type={plan.task_type.value} "
+        f"tools={plan.tools} reason={plan.reason} adapter_mode={plan.adapter_mode}"
+    )
+
+    query_variants = build_query_variants(
+        context.get("query", ""),
+        tool_names=plan.tools,
+        context=context,
+    )
+
+    _latency_ms = round((time.monotonic() - _start) * 1000, 2)
+    logger.debug(f"[planner] latency_ms={_latency_ms}")
+
+    return {
+        "task_type": plan.task_type.value,
+        "goal": plan.goal,
+        "reason": plan.reason,
+        "planned_tools": plan.tools,
+        "tool_summaries": plan.tool_summaries,
+        "adapter_mode": plan.adapter_mode,
+        "accumulated_context": {
+            **context,
+            "query_variants": query_variants,
+        },
+        "node_latencies": {"planner": _latency_ms},
+    }
+
+
+def approval_wait_node(state: GovOnGraphState) -> dict:
+    """Human-in-the-loop 승인 게이트.
+
+    `interrupt()`를 호출하여 graph 실행을 일시 정지한다.
+    FastAPI `/v2/agent/approve` 엔드포인트가 사용자 응답을 받아 graph를 resume한다.
+
+    `interrupt()`는 LangGraph가 지원하는 human-in-the-loop 메커니즘이다.
+    graph 실행이 멈추고, `Command(resume=...)` 호출로 재개될 때
+    `interrupt()`의 반환값으로 사용자 입력이 전달된다.
+
+    Parameters
+    ----------
+    state : GovOnGraphState
+        현재 graph state. `goal`, `reason`, `planned_tools`를 읽는다.
+
+    Returns
+    -------
+    dict
+        `approval_status`를 갱신한다.
+    """
+    tool_summaries: List[str] = state.get("tool_summaries") or []
+    planned_tools: List[str] = state.get("planned_tools", [])
+
+    # CLI 표시용 도구 설명: tool_summaries가 있으면 사용, 없으면 tool 이름 그대로
+    display_tools = tool_summaries if tool_summaries else planned_tools
+
+    approval_request = {
+        "type": "approval_request",
+        "goal": state.get("goal", ""),
+        "reason": state.get("reason", ""),
+        "planned_tools": planned_tools,
+        "tool_summaries": display_tools,
+        "prompt": (
+            f"다음 작업을 수행하겠습니다:\n\n"
+            f"  {state.get('goal', '')}\n\n"
+            f"  이유: {state.get('reason', '')}\n"
+            f"  사용할 도구:\n"
+            + "".join(f"    - {s}\n" for s in display_tools)
+            + "\n승인하시겠습니까? (승인/거절)"
+        ),
+    }
+
+    logger.info(f"[approval_wait] interrupt 호출: tools={planned_tools}")
+
+    # interrupt()는 graph 실행을 멈추고, resume 시 반환값이 된다.
+    # 예: {"approved": True} 또는 {"approved": False}
+    user_response = interrupt(approval_request)
+
+    if isinstance(user_response, dict) and user_response.get("approved"):
+        logger.info("[approval_wait] 승인됨")
+        return {"approval_status": ApprovalStatus.APPROVED.value}
+
+    # cancel 신호가 있으면 interrupt_reason을 "user_cancel"로 설정
+    interrupt_reason = None
+    if isinstance(user_response, dict) and user_response.get("cancel"):
+        logger.info("[approval_wait] 사용자 취소 (cancel)")
+        interrupt_reason = "user_cancel"
+    else:
+        logger.info("[approval_wait] 거절됨")
+
+    return {
+        "approval_status": ApprovalStatus.REJECTED.value,
+        "interrupt_reason": interrupt_reason,
+    }
+
+
+async def tool_execute_node(
+    state: GovOnGraphState,
+    *,
+    executor_adapter: "ExecutorAdapter",
+) -> dict:
+    """Tool executor 노드.
+
+    ExecutorAdapter를 통해 `planned_tools`를 두 단계로 실행하고
+    결과를 `accumulated_context`에 누적한다.
+
+    실행 전략:
+    - Phase 1 (병렬): `rag_search`, `api_lookup` 등 INDEPENDENT_TOOLS는
+      `asyncio.gather()`로 동시에 실행한다.
+    - Phase 2 (순차): 나머지 의존 도구(draft_civil_response 등)는 Phase 1
+      결과가 누적된 accumulated_context를 사용하여 순서대로 실행한다.
+
+    Parameters
+    ----------
+    state : GovOnGraphState
+        현재 graph state. `planned_tools`, `accumulated_context`를 읽는다.
+    executor_adapter : ExecutorAdapter
+        graph config에서 closure로 주입되는 executor 어댑터.
+
+    Returns
+    -------
+    dict
+        `tool_results`, `accumulated_context`, `node_latencies`를 갱신한다.
+        `node_latencies`에는 `"tool_execute"` 키로 노드 전체 레이턴시,
+        `"tool:<tool_name>"` 키로 개별 도구 레이턴시가 포함된다.
+    """
+    _start = time.monotonic()
+
+    # approval guard: 승인 없이 tool 실행 차단
+    approval_status = state.get("approval_status", "")
+    if approval_status != ApprovalStatus.APPROVED.value:
+        _latency_ms = round((time.monotonic() - _start) * 1000, 2)
+        logger.warning(
+            f"[tool_execute] 승인되지 않은 상태에서 실행 시도 차단: approval_status={approval_status!r}"
+        )
+        return {
+            "tool_results": {},
+            "accumulated_context": dict(state.get("accumulated_context", {})),
+            "error": f"tool 실행 차단: 승인 필요 (현재 상태: {approval_status!r})",
+            "node_latencies": {"tool_execute": _latency_ms},
+        }
+
+    planned_tools: list[str] = state.get("planned_tools", [])
+    accumulated: Dict[str, Any] = dict(state.get("accumulated_context", {}))
+
+    # planned_tools가 비어있는 경우 (validation 실패 fallback 등)
+    if not planned_tools:
+        logger.warning("[tool_execute] planned_tools가 비어있어 실행 건너뜀")
+        return {
+            "tool_results": {},
+            "accumulated_context": accumulated,
+            "node_latencies": {"tool_execute": round((time.monotonic() - _start) * 1000, 2)},
+        }
+
+    tool_results: Dict[str, Any] = {}
+    tool_latencies: Dict[str, float] = {}
+
+    # --- 독립 도구와 의존 도구를 분리하여 병렬/순차 실행 ---
+    # 새로운 독립 capability를 추가할 때는 이 집합에도 등록해야 한다.
+    # 독립 도구란 다른 도구의 실행 결과(accumulated_context)에 의존하지 않아
+    # 병렬 실행이 안전한 capability를 의미한다.
+    INDEPENDENT_TOOLS = {"rag_search", "api_lookup"}
+
+    independent = [t for t in planned_tools if t in INDEPENDENT_TOOLS]
+    dependent = [t for t in planned_tools if t not in INDEPENDENT_TOOLS]
+
+    # Phase 1: 독립 도구 병렬 실행
+    # 주의: _run_tool 클로저 내에서 accumulated는 읽기 전용으로 취급해야 한다.
+    # 병렬 실행 중 accumulated를 변경하면 race condition이 발생할 수 있다.
+    # accumulated 갱신은 gather() 완료 후 메인 루프에서 순서대로 수행한다.
+    if independent:
+
+        async def _run_tool(name: str) -> tuple[str, Dict[str, Any], float]:
+            t0 = time.monotonic()
+            execution_query = resolve_tool_query(name, accumulated)
+            logger.info(f"[tool_execute] 병렬 실행: {name}")
+            result = await executor_adapter.execute(
+                tool_name=name,
+                query=execution_query,
+                context=dict(accumulated),
+            )
+            latency = round((time.monotonic() - t0) * 1000, 2)
+            return name, result, latency
+
+        results = await asyncio.gather(
+            *[_run_tool(name) for name in independent],
+            return_exceptions=True,
+        )
+        for i, item in enumerate(results):
+            if isinstance(item, Exception):
+                failed_tool = independent[i]
+                logger.opt(exception=item).error(
+                    f"[tool_execute] 병렬 실행 실패: tool={failed_tool}"
+                )
+                continue
+            name, result, latency = item
+            tool_results[name] = result
+            tool_latencies[name] = latency
+            if result.get("success", True):
+                accumulated[name] = result
+
+    # Phase 2: 의존 도구 순차 실행 (accumulated context 필요)
+    for name in dependent:
+        t0 = time.monotonic()
+        execution_query = resolve_tool_query(name, accumulated)
+        logger.info(f"[tool_execute] 순차 실행: {name}")
+        try:
+            result = await executor_adapter.execute(
+                tool_name=name,
+                query=execution_query,
+                context=accumulated,
+            )
+        except Exception as exc:
+            latency = round((time.monotonic() - t0) * 1000, 2)
+            logger.opt(exception=exc).error(f"[tool_execute] 순차 실행 실패: tool={name}")
+            tool_results[name] = {
+                "success": False,
+                "error": f"{type(exc).__name__}: {exc}",
+            }
+            tool_latencies[name] = latency
+            continue
+        latency = round((time.monotonic() - t0) * 1000, 2)
+        tool_results[name] = result
+        tool_latencies[name] = latency
+        if result.get("success", True):
+            accumulated[name] = result
+
+    _latency_ms = round((time.monotonic() - _start) * 1000, 2)
+    logger.info(
+        f"[tool_execute] 완료: {list(tool_results.keys())} "
+        f"latency_ms={_latency_ms} per_tool={tool_latencies}"
+    )
+
+    # node_latencies에 노드 전체 레이턴시와 개별 tool 레이턴시를 함께 기록한다.
+    # tool 레이턴시는 "tool:<tool_name>" 접두사로 구분한다.
+    merged_latencies: Dict[str, float] = {"tool_execute": _latency_ms}
+    for tool_name, tool_lat in tool_latencies.items():
+        merged_latencies[f"tool:{tool_name}"] = tool_lat
+
+    return {
+        "tool_results": tool_results,
+        "accumulated_context": accumulated,
+        "node_latencies": merged_latencies,
+    }
+
+
+async def synthesis_node(state: GovOnGraphState) -> dict:
+    """결과 종합 노드.
+
+    tool_results와 accumulated_context를 종합하여 최종 응답 텍스트를 생성한다.
+    기존 AgentLoop._extract_final_text() 로직을 계승한다.
+
+    Parameters
+    ----------
+    state : GovOnGraphState
+        현재 graph state. `tool_results`, `accumulated_context`, `task_type`을 읽는다.
+
+    Returns
+    -------
+    dict
+        `final_text`, `evidence_items`, `messages`(AIMessage 추가)를 갱신한다.
+    """
+    _start = time.monotonic()
+
+    accumulated = state.get("accumulated_context", {})
+    task_type = state.get("task_type", "")
+
+    final_text = _extract_final_text(accumulated, task_type)
+    evidence_items = _collect_evidence_items(accumulated)
+
+    _latency_ms = round((time.monotonic() - _start) * 1000, 2)
+    logger.info(
+        f"[synthesis] final_text_len={len(final_text)} evidence_items={len(evidence_items)} latency_ms={_latency_ms}"
+    )
+
+    return {
+        "final_text": final_text,
+        "evidence_items": evidence_items,
+        "messages": [AIMessage(content=final_text)],
+        "node_latencies": {"synthesis": _latency_ms},
+    }
+
+
+async def persist_node(
+    state: GovOnGraphState,
+    *,
+    session_store: "SessionStore",
+) -> dict:
+    """영속화 노드.
+
+    SessionStore에 대화 턴과 tool 실행 기록을 저장한다.
+    기존 SessionContext.add_turn / add_tool_run 로직을 계승한다.
+
+    Parameters
+    ----------
+    state : GovOnGraphState
+        현재 graph state. 전체 state를 읽어 저장한다.
+    session_store : SessionStore
+        graph config에서 closure로 주입되는 세션 저장소.
+
+    Returns
+    -------
+    dict
+        side effect로 DB에 저장하고, `node_latencies` 업데이트를 반환한다.
+    """
+    _start = time.monotonic()
+
+    session_id: str | None = state.get("session_id")
+    session = session_store.get_or_create(session_id)
+
+    # 사용자 입력 저장 (messages[0]이 최초 사용자 메시지)
+    messages = state.get("messages", [])
+    if messages:
+        user_msg = messages[0]
+        session.add_turn("user", user_msg.content)
+
+    # --- graph_run 기록 (plan + approval + executed capabilities) ---
+    request_id: str = state.get("request_id", "")
+    approval_status: str = state.get("approval_status", "")
+    planned_tools: List[str] = state.get("planned_tools", [])
+    tool_results: Dict[str, Any] = state.get("tool_results", {})
+
+    # 승인된 경우에만 실행된 도구 목록을 기록, 거절 시 빈 리스트
+    executed_capabilities: List[str] = (
+        [name for name in planned_tools if name in tool_results]
+        if approval_status == ApprovalStatus.APPROVED.value
+        else []
+    )
+
+    plan_summary = (
+        f"[{state.get('task_type', '')}] {state.get('goal', '')} "
+        f"| 이유: {state.get('reason', '')} | tools: {planned_tools}"
+    )
+
+    total_latency_ms = sum(r.get("latency_ms", 0.0) for r in tool_results.values())
+
+    # interrupt_reason이 있으면 "interrupted", 거절이면 "rejected", 그 외 "completed"
+    interrupt_reason: str | None = state.get("interrupt_reason")
+    if interrupt_reason:
+        graph_status = "interrupted"
+    elif approval_status == ApprovalStatus.REJECTED.value:
+        graph_status = "rejected"
+    else:
+        graph_status = "completed"
+
+    session.add_graph_run(
+        request_id=request_id,
+        plan_summary=plan_summary,
+        approval_status=approval_status,
+        executed_capabilities=executed_capabilities,
+        status=graph_status,
+        total_latency_ms=total_latency_ms,
+    )
+
+    # tool 실행 기록 저장 (graph_run_request_id로 연결)
+    for name, result in tool_results.items():
+        session.add_tool_run(
+            tool=name,
+            success=result.get("success", True),
+            graph_run_request_id=request_id,
+            latency_ms=result.get("latency_ms", 0.0),
+            error=result.get("error"),
+        )
+
+    # 어시스턴트 응답 저장
+    final_text = state.get("final_text", "")
+    if final_text:
+        session.add_turn("assistant", final_text)
+
+    _latency_ms = round((time.monotonic() - _start) * 1000, 2)
+    logger.debug(
+        f"[persist] session_id={session.session_id} "
+        f"graph_run={request_id} saved latency_ms={_latency_ms}"
+    )
+
+    return {"node_latencies": {"persist": _latency_ms}}
+
+
+def _safe_score(item: dict) -> float:
+    """evidence item의 score를 안전하게 float으로 변환한다.
+
+    외부 API 결과의 score가 문자열이거나 None일 수 있으므로
+    변환 실패 시 0.0을 반환한다.
+    """
+    try:
+        return float(item.get("score", 0.0))
+    except (ValueError, TypeError):
+        return 0.0
+
+
+# accumulated 컨텍스트 탐색 시 스킵할 메타 키 목록 (모듈 레벨 상수)
+_CONTEXT_META_KEYS: frozenset[str] = frozenset(
+    {
+        "session_context",
+        "query",
+        "query_variants",
+        "previous_user_query",
+        "previous_assistant_response",
+        "recent_tool_summary",
+    }
+)
+
+
+def _collect_evidence_items(accumulated: Dict[str, Any]) -> list[dict]:
+    """accumulated 컨텍스트에서 모든 EvidenceItem dict를 수집한다.
+
+    각 tool 결과의 evidence.items 필드를 탐색하여 하나의 리스트로 합산한다.
+    최대 10개까지 반환하며, score 내림차순으로 정렬한다.
+
+    Parameters
+    ----------
+    accumulated : Dict[str, Any]
+        tool 결과가 누적된 컨텍스트 dict.
+
+    Returns
+    -------
+    list[dict]
+        EvidenceItem.to_dict() 형태의 dict 리스트.
+    """
+    items: list[dict] = []
+    for key, payload in accumulated.items():
+        if key in _CONTEXT_META_KEYS:
+            continue
+        if not isinstance(payload, dict):
+            continue
+        ev = payload.get("evidence")
+        if isinstance(ev, dict) and ev.get("items"):
+            for item in ev["items"]:
+                if isinstance(item, dict):
+                    items.append(item)
+    # score 내림차순, 최대 10개 — 외부 값이므로 _safe_score로 방어적 변환
+    items.sort(key=_safe_score, reverse=True)
+    return items[:10]
+
+
+def _safe_score(item: dict) -> float:
+    """evidence item의 score를 안전하게 float으로 변환한다.
+
+    외부 API 결과의 score가 문자열이거나 None일 수 있으��로
+    변환 실패 시 0.0을 반환한다.
+    """
+    try:
+        return float(item.get("score", 0.0))
+    except (ValueError, TypeError):
+        return 0.0
+
+
+# accumulated 컨텍스트 탐색 시 스킵할 메타 키 목록 (모듈 레벨 상수)
+_CONTEXT_META_KEYS: frozenset[str] = frozenset(
+    {
+        "session_context",
+        "query",
+        "query_variants",
+        "previous_user_query",
+        "previous_assistant_response",
+        "recent_tool_summary",
+    }
+)
+
+
+def _collect_evidence_items(accumulated: Dict[str, Any]) -> list[dict]:
+    """accumulated 컨텍스트에서 모든 EvidenceItem dict를 수집한다.
+
+    각 tool 결과의 evidence.items 필드를 탐색하여 하나의 리스트로 합산한다.
+    최대 10개까지 반환하며, score 내림차순으로 정렬한다.
+
+    Parameters
+    ----------
+    accumulated : Dict[str, Any]
+        tool 결과가 누적된 컨텍스트 dict.
+
+    Returns
+    -------
+    list[dict]
+        EvidenceItem.to_dict() 형태의 dict 리스트.
+    """
+    items: list[dict] = []
+    for key, payload in accumulated.items():
+        if key in _CONTEXT_META_KEYS:
+            continue
+        if not isinstance(payload, dict):
+            continue
+        ev = payload.get("evidence")
+        if isinstance(ev, dict) and ev.get("items"):
+            for item in ev["items"]:
+                if isinstance(item, dict):
+                    items.append(item)
+    # score 내림차순, 최대 10개 — 외부 값이므로 _safe_score로 방어적 변환
+    items.sort(key=_safe_score, reverse=True)
+    return items[:10]
+
+
+def _extract_final_text(accumulated: Dict[str, Any], task_type: str) -> str:
+    """tool 결과를 종합하여 최종 텍스트를 생성한다.
+
+    기존 AgentLoop._extract_final_text()를 계승하되,
+    task_type을 기반으로 분기한다.
+
+    append_evidence 타입일 때는 기존 답변(previous_assistant_response)을
+    evidence 섹션 앞에 prepend하여 답변을 보강한다.
+
+    Parameters
+    ----------
+    accumulated : Dict[str, Any]
+        tool 결과가 누적된 컨텍스트 dict.
+    task_type : str
+        TaskType.value (예: "draft_response").
+
+    Returns
+    -------
+    str
+        최종 응답 텍스트.
+    """
+    # append_evidence: 기존 답변 위에 근거 섹션을 추가한다
+    if task_type == "append_evidence":
+        previous_draft = str(accumulated.get("previous_assistant_response", "")).strip()
+        evidence_section = _build_evidence_section(accumulated)
+        if previous_draft and evidence_section:
+            return f"{previous_draft}\n\n{evidence_section}"
+        if evidence_section:
+            return evidence_section
+        if previous_draft:
+            return previous_draft
+
+    # 1. append_evidence 또는 draft_civil_response의 직접 텍스트가 있으면 사용
+    for key in ("append_evidence", "draft_civil_response"):
+        payload = accumulated.get(key, {})
+        if isinstance(payload, dict) and payload.get("text"):
+            return str(payload["text"])
+
+    # 2. 모든 accumulated 결과에서 텍스트 탐색
+    for key, payload in accumulated.items():
+        if key in ("session_context", "query"):
+            continue
+        if isinstance(payload, dict) and payload.get("text"):
+            return str(payload["text"])
+
+    # 3. 개별 결과 조합 — evidence 필드가 있으면 우선 사용
+    parts: list[str] = []
+
+    # evidence 필드 기반 출처 목록 생성 (source-specific branching 없이)
+    all_evidence_items: list[dict] = []
+    for key, payload in accumulated.items():
+        if key in ("session_context", "query"):
+            continue
+        if isinstance(payload, dict):
+            ev = payload.get("evidence")
+            if isinstance(ev, dict) and ev.get("items"):
+                all_evidence_items.extend(ev["items"])
+
+    if all_evidence_items:
+        lines = ["[참조 근거]"]
+        for item in all_evidence_items[:5]:
+            source_type = item.get("source_type", "")
+            title = item.get("title", "")
+            excerpt = item.get("excerpt", "")[:120]
+            label = (
+                "[로컬]" if source_type == "rag" else "[외부]" if source_type == "api" else "[생성]"
+            )
+            if title:
+                lines.append(f"- {label} {title}: {excerpt}")
+            elif excerpt:
+                lines.append(f"- {label} {excerpt}")
+        if len(lines) > 1:
+            parts.append("\n".join(lines))
+
+    # evidence가 없는 경우 legacy fallback
+    if not parts:
+        rag_data = accumulated.get("rag_search", {})
+        if isinstance(rag_data, dict) and rag_data.get("results"):
+            lines = ["[로컬 문서 근거]"]
+            for item in rag_data["results"][:3]:
+                title = item.get("title", "")
+                content = str(item.get("content", ""))[:120]
+                lines.append(f"- {title}: {content}")
+            parts.append("\n".join(lines))
+
+        api_data = accumulated.get("api_lookup", {})
+        if isinstance(api_data, dict) and api_data.get("context_text"):
+            parts.append(api_data["context_text"])
+
+    return "\n\n".join(parts) if parts else "요청을 처리할 수 없습니다."
+
+
+def _build_evidence_section(accumulated: Dict[str, Any]) -> str:
+    """accumulated에서 근거 섹션 텍스트를 구성한다.
+
+    append_evidence capability의 직접 텍스트가 있으면 우선 사용하고,
+    없으면 evidence items에서 구조화된 텍스트를 생성한다.
+
+    계약(contract):
+      - 이 함수는 **근거 섹션만** 반환한다. 기존 답변(previous_draft)은 포함하지 않는다.
+      - 호출자(_extract_final_text)가 previous_draft와 병합하여 반환한다.
+      - AppendEvidenceCapability.execute()의 text 필드도 근거 섹션만 담아야 한다.
+        (기존 답변을 포함한 완전 응답을 text에 넣으면 _extract_final_text에서 중복된다.)
+
+    Parameters
+    ----------
+    accumulated : Dict[str, Any]
+        tool 결과가 누적된 컨텍스트 dict.
+
+    Returns
+    -------
+    str
+        근거 섹션 텍스트. 근거가 없으면 빈 문자열.
+    """
+    # append_evidence capability의 직접 생성 텍스트 우선 사용
+    # 이 텍스트는 근거 섹션만 담아야 한다 (기존 답변 포함 금지).
+    ae_payload = accumulated.get("append_evidence", {})
+    if isinstance(ae_payload, dict) and ae_payload.get("text"):
+        return str(ae_payload["text"])
+
+    # evidence items에서 구조화 텍스트 생성
+    items = _collect_evidence_items(accumulated)
+    if not items:
+        return ""
+
+    lines = ["[참조 근거]"]
+    for item in items[:5]:
+        source_type = item.get("source_type", "")
+        title = item.get("title", "")
+        excerpt = item.get("excerpt", "")[:120]
+        label = "[로컬]" if source_type == "rag" else "[외부]" if source_type == "api" else "[생성]"
+        if title:
+            lines.append(f"- {label} {title}: {excerpt}")
+        elif excerpt:
+            lines.append(f"- {label} {excerpt}")
+
+    return "\n".join(lines) if len(lines) > 1 else ""