feat: system prompt kind별 그룹화 + disambiguation 개선

[thrcle]

#️⃣ Issue Number

없음

📝 요약(Summary)

한 줄 요약: 등록된 비즈니스 용어를 종류별로 분류해 시스템 프롬프트에 주입함으로써, LLM이 각 용어를 SQL 어느 절에 써야 하는지 명확하게 판단할 수 있게 합니다.

해결하려는 문제

PR1에서 용어에 kind(metric/rule/dimension/table)를 추가했지만, 시스템 프롬프트에는 여전히 모든 용어가 한 덩어리로 나열됐습니다.

기존 프롬프트:

## Business Terminology
- **월매출** `metric` [전사]: SUM(orders.amount)
- **환불제외** `rule` [전사]: status != 'cancelled'
- **고객등급** `dimension` [전사]: users.tier

LLM이 metric은 SELECT에, rule은 WHERE에 쓴다는 판단을 스스로 해야 했습니다.

이번 변경으로 달라지는 것

변경 후 프롬프트:

## Business Terminology

### Metrics — 집계 지표: SELECT/HAVING 절의 집계식으로 사용
- **월매출** `metric` [전사]: SUM(orders.amount)

### Rules — 비즈니스 규칙: WHERE 절에 AND 조건으로 추가
- **환불제외** `rule` [전사]: status != 'cancelled'

### Dimensions — 분류 기준: GROUP BY 또는 SELECT 컬럼으로 활용
- **고객등급** `dimension` [전사]: users.tier

kind가 없는 용어는 ### 기타 그룹으로, 등록되지 않은 kind 그룹은 헤더 자체가 생략됩니다.

Ambiguous Term Policy 개선

미등록 용어를 처음 만났을 때 LLM이 사용자에게 묻는 방식도 개선했습니다.

기존: "이 정의를 어느 범위로 등록할까요?"
변경: "metric/rule/dimension/table 중 어느 종류이며, 어느 범위로 등록할까요?"

PR1에서 term_custom에 kind 파라미터를 추가했으므로, 이제 LLM이 등록 시 kind까지 함께 지정할 수 있습니다.

다음 PR과의 관계

PR1 (FedEntry kind 필드) → PR2 (OKF bundle) → PR3 (ingest 확인 루프) → PR4 (이 PR)

이 PR이 시리즈의 마지막입니다.

💬 To Reviewers

이 PR은 총 4개로 구성된 시리즈의 네 번째(마지막)입니다. PR3 머지 후 순차 머지 부탁드립니다.

• _resolve_term 내부 함수를 제거하고 _resolve_entry로 통합했습니다. bench/ecommerce_demo.py에서 미사용 import를 제거했습니다.
• kind 힌트 문구(_KIND_SQL_HINT)는 한국어로 작성했습니다. 영어 통일이 필요하다면 말씀해 주세요.

PR Checklist

• 변경 사항에 대한 테스트 또는 검증 완료 (신규 테스트 8개: 그룹핑, SQL 힌트, 기타 폴백, 빈 그룹 스킵, _resolve_entry 3케이스)
• 로컬에서 정상 동작 확인 (156 passed)
• 관련 문서 업데이트 완료

[seyoung4503]

#241 → #244 스택 통합 리뷰

4개가 하나의 흐름이라 최종 상태(master..#244) 기준으로 봤습니다. 테스트 146개 통과, 회귀 없음.

잘 되는 것

• 기존 용어 그대로 읽히고 롤백도 안전
• 팀별 우선순위(개인 → 채널 → 서버) 보존 — kind 그룹화는 해석 이후에 적용됨
• 확인 루프 설계 견고 — 세션 압축 넘어 유지, ref별 분리, 이중 확정 안전
• 한글 왕복 정상, yaml.safe_load 사용

머지 전 수정 (전부 #243에서)

1. 전사(guild) 용어를 아무나 등록할 수 있습니다 — confirm_ingest.py:121

• 스펙에 "enum": ["guild","channel","member"]를 노출해두고(:59-61) 관리자 검사 없이 씁니다. 문서 올리고 "전사 용어로 등록해줘" 하면 그대로 통과합니다
• define은 semantic_federation.py:247에서 is_admin으로 막고 있습니다

2. 빈 channel_id 가드 누락 — confirm_ingest.py:159-161

• _entity_for가 effective_channel_id를 검사 없이 반환합니다. 값이 비면 키가 cterm:<term>:channel: 이 되어 모든 채널이 같은 키를 공유합니다
• 커밋 1adafd4에서 define 쪽에 넣으신 가드가 이 경로에는 없습니다

3. layer 값 검증 없음 — confirm_ingest.py:73

• 문자열을 그대로 받습니다. JSON 스키마 enum은 권고일 뿐이라 LLM이 "Guild"를 보낼 수 있고, 그러면 cterm:<term>:Guild: 로 저장됩니다
• 사용자에게는 "등록됨"이라고 알리지만 조회는 3개 레이어만 스캔하므로 영원히 안 잡힙니다. define은 :240에서 layer not in _LAYERS로 거부합니다

1·2·3은 define의 검증 블록(semantic_federation.py:240-270)을 공통 함수로 빼서 양쪽에서 부르면 한 번에 해결됩니다. 같은 키스페이스에 게이트가 다른 쓰기 경로가 둘이면 계속 어긋날 것 같습니다.

4. 번들 파일 경로 검증 없음 — okf_bundle.py:113-116

• 용어명을 파일명으로 바꿀 때 공백과 :만 치환하고 /, ..는 통과시킵니다. 재현했습니다:

  번들에 title: ../../../ESCAPED 인 항목 → import → export
  → 대상 폴더보다 두 단계 위에 파일 생성됨
  

• #242만 보면 호출자가 없어 무해하지만, confirm_ingest.py:133이 export를 호출하면서 사용자 문서로부터 도달 가능해집니다
• 수정: 안전한 문자만 남기고, 쓰기 직전 path.resolve().is_relative_to(self.base_dir.resolve()) 확인

5. 정의에 ---가 있으면 조용히 사라집니다 — okf_bundle.py:152

• text.index("---", 3)이 줄 단위가 아니라 글자 단위 검색입니다. 본문에 구분선이 있으면 frontmatter가 중간에서 잘려 safe_load가 실패하고, _md_to_entry가 None을 반환해 :96-98에서 건너뜁니다. 에러도 카운트도 없습니다
• 수정: 줄머리 \n--- 매칭 또는 text.split("\n---\n", 2)

후속 PR

• confirm_ingest에 감사 로그 없음 (define은 AuditEvent 남김)
• export가 KV 쓰기·pending 삭제 후에 실행돼 실패 시 상태 불일치 (:133)
• 후보 이름·정의 빈 값 검증 (:113)
• 깨진 파일 하나가 import 전체 중단 (okf_bundle.py:148, read_text가 try 밖)
• tags 파싱 허술 — 빈 값이 "None" 글자로 저장됨 (semantic_federation.py:278)
• org_setup.py:237 — 위저드 생성 용어는 kind가 계속 빈 값
• pending 키 만료 없음 / 슬러그 충돌 시 덮어쓰기

머지 순서

• feat: FedEntry에 kind/applies_to/tags 필드 추가 #241, feat: OKF bundle 어댑터 추가 (export/import, kind별 폴더 라우팅) #242 — 지금 머지 가능. 4번이 위험해지는 건 #243부터
• feat: ingest_doc 확인 루프 — confirm_ingest 툴 추가 및 OkfBundle 연동 #243 — 위 5건 수정 지점
• feat: system prompt kind별 그룹화 + disambiguation 개선 #244 — 코드 이상 없음. feat: ingest_doc 확인 루프 — confirm_ingest 툴 추가 및 OkfBundle 연동 #243 정리 후 리베이스만

테스트

• guild/관리자 경로와 빈 채널 경로에 테스트가 없어 1·2번이 안 걸렸습니다. 수정 시 함께 추가 부탁드립니다
• test_confirm_ingest.py 1건 실패는 로컬 PyYAML 미설치 문제로 CI는 정상입니다
• feat: system prompt kind별 그룹화 + disambiguation 개선 #244 제목이 "system prompt kind별 그룹화"인데 실제로는 harness/system_prompt.py가 아니라 tools/semantic_federation.py의 프롬프트 빌더를 고칩니다

[seyoung4503]

👍 좋습니다!!