feat: 기존 ContextFlow에 연결 즉시 의미 준비형 질의 추가

[o2mandoo]

요약

이미 병합된 ContextFlow의 의미 발견·축적 철학을 그대로 유지합니다. Discord →
tenancy → agent loop와 Enrich·Federation·Memory·Ingestion 위에서, catalog가
활성화된 연결의 실행 경계에만 연결 즉시 의미 준비형 질의를 덧댑니다. 자동
보강은 검색 후보만 늘리며 승인이나 실행 권한을 만들지 않습니다.

• catalog 없음: 기존 run_sql·schema 탐색/Enrich 유지
• catalog 있음: 질문별 후보를 제한하고 서버가 SQL 컴파일
• 사람은 매 SQL이 아니라, 현재 질문에 필요한 미확정 의미·공개 범위만 확인

작은 모델이 가능한 이유

“규칙”은 매출 → orders.amount 같은 도메인별 if 문이나 SQL template이
아닙니다. 첫 연결에서 DB별 사실(허용 ID·타입·PK/FK·확인된 의미)을 catalog로
만들고, 지원 범위 안에서 DB와 무관한 집계·타입·join·parameter·공개 규칙으로
컴파일합니다.

질문마다 관련 table은 최대 6개, metric·dimension 후보는 각각 최대 12개로
줄입니다. 아래는 필요한 공개·표현 검토가 끝난 연결의 간단한 예입니다.

flowchart LR
    A["질문: ordered_on이 2025-01-01 이상<br/>2025-02-01 미만이고 status=paid인 amount 합계"] --> B["서버: 관련 metric·filter·기간 후보만 제공"]
    B --> C["작은 모델: SQL 대신 허용 ID·값 조립"]
    C --> D["서버: catalog·공통 규칙으로 SQL 컴파일"]
    D --> E{"의미·공개 범위 확정?"}
    E -- "예" --> F["기존 Safety → 읽기 전용 실행"]
    E -- "아니오/미지원" --> G["사람 검토·추가 질문·명시적 차단"]

Loading

후보  metric:orders.amount · dimension:orders.status
      dimension:orders.ordered_on · SUM
출력  metric_id=metric:orders.amount
      filter.dimension_id=dimension:orders.status
      operator=EQ · value="paid"
      time_window.dimension_id=dimension:orders.ordered_on
      start=2025-01-01 · end=2025-02-01

모델은 table·join·dialect를 추측하지 않고 소수 후보에서 정해진 칸만 채웁니다.
자연어의 숨은 조건을 놓치는 문제까지 자동 해결한다고 주장하지 않으며, 미확정
의미는 실행하지 않습니다.

핵심 변경

1. /setup 직후 물리명·DB comment를 후보로 사용하고, 같은 source·물리
   fingerprint의 재연결이면 기존 /enrich 설명 캐시도 재사용합니다. auto
   모드에서 실제 LLM provider가 있으면 raw row 없이 metadata-only 보강도 한 번
   수행합니다.
2. 자동 보강은 검색 후보만 늘립니다. 승인 alias·집계·join·공개 권한은 바꾸지 않습니다.
3. LLM은 SQL이나 임의 table/join 대신 허용된 지표·분류·집계·필터·기간만 조립합니다.
4. SQLite/DuckDB 밖의 미검증 실행은 run_sql로 우회하지 않고 명시적으로 차단합니다.

상세 계약: docs/REVIEWED_SEMANTIC_QUERY.md

검증

• 전체 회귀: 357 passed
• DB row 조회 0회, 자동 후보 후에도 사람 검토 유지, LLM 실패 상태 노출
• Ruff·mypy 통과

권장 리뷰 순서: 문서 → tools/__init__.py → semantic/ → 공개 API·Discord