[Feat] W4 Layer A: Text2Cypher 모듈 + 평가 셋 8/8 PASS (#18)

[TaskerJang]

🎯 Closes #18

W4 첫 retrieval 진입점 — 자연어 질의 → Cypher → 결과 → 자연어 답변.

5/16 박제된 평가 셋 (Q1Q5 + F1F3) 정성 검증 8/8 PASS 🎉🎉🎉🎉

변경 사항

신규 파일

• retrieval/__init__.py — 공개 인터페이스 (text2cypher, Text2CypherResult, Text2CypherError)
• retrieval/text2cypher.py (320 lines) — 2단계 LLM 흐름 + 안전장치
• retrieval/prompts/text2cypher_system_v1.md — 스키마 + few-shot 5개 + fallback 1개
• retrieval/prompts/text2cypher_answer_v1.md — 답변 가이드 (라벨 한계 정직 보고)
• retrieval/eval_set.md — 평가 셋 정답 Cypher (Q1Q5 + F1F3 + 작업 흐름)
• scripts/run_w4_eval.py (550 lines) — 자동 정성 검증 + markdown 표 + JSON 박제
• docs/weekly-log/2026-05-17-text2cypher.md — 8/8 PASS 결과 박제

Commits (4개)

• 142ff00 docs(eval): 평가 셋 사이퍼 쿼리 5종 박제
• ff03ba9 feat(retrieval): Text2Cypher 모듈 구현
• 98490c0 feat(scripts): W4 평가 셋 정성 검증 스크립트
• f26f70b docs(weekly-log): 🎉🎉🎉🎉 W4 Text2Cypher 정성 검증 8/8 PASS!

🏗️ 아키텍처

자연어 질의
   │
   ▼ _generate_cypher (LLM 1단계, JSON 강제, temp=0.1)
Cypher (또는 null — 스키마 외)
   │
   ▼ _enforce_safety (read-only + LIMIT 100 강제)
   ▼ Neo4jClient.read
결과 (list[dict])
   │
   ▼ _generate_answer (LLM 2단계, plain text, temp=0.3)
자연어 답변

안전장치 (#18 DoD)

1. read-only 강제: CREATE/DELETE/SET/MERGE/REMOVE/DROP/CALL/LOAD word boundary 정규식 검사
2. LIMIT 100 강제: 미명시 시 자동 부착 (Neo4jClient 도 강제하지만 본 모듈에서 사전 검증)
3. 2중 방어: LLM 자체 거부 (cypher=null) + 코드 차단 (Text2CypherError)
4. graceful fallback: 모든 경우 answer 필드 채워짐 (cypher=null / 실행 실패 / 빈 결과 / 보안 위반)

LLM 패턴 (kg/extractor.py 와 일치)

• JSON 응답 강제 (response_format={"type": "json_object"})
• tenacity 재시도 (3회, exponential backoff)
• JSON 파싱 방어 (코드펜스 strip + 따옴표 escape)
• 프롬프트 hot-reload (캐시 안 함)
• Opik @track 데코레이터

🎯 정성 검증 결과 (5/17 20:52, 44.8s)

ID	category	verdict	kw%	limit	safe	rows	elapsed
Q1	traversal	PASS	100%	✅	✅	68	8.1s
Q2	factual	PASS	100%	✅	✅	1	4.3s
Q3	filter	PASS	100%	✅	✅	100	9.0s
Q4	semantic	PASS	100%	✅	✅	0	6.2s
Q5	topN	PASS	100%	✅	✅	5	6.4s
F1	fallback	PASS	100%	✅	✅	0	5.1s
F2	fallback	PASS	0%	✅	✅	0	3.5s
F3	fallback	PASS	0%	❌	✅	0	2.3s

총 8/8 PASS · 평균 5.6초/케이스

⭐⭐⭐ Q5 진짜 발표 보석 정량 확정

5/16 발견된 Entity 라벨 품질 challenge 가 LLM 답변까지 정확히 보고:

Company 라벨 top 5 = 100% 금융 metric, 진짜 회사명 0개
1. 공모발행액 23조 7,050억원 (31 mentions)
2. 일반회사채 발행 규모 전월 대비 감소 (19)
3. 기업공개 발행액 524억원 (17)
4. 유상증자 발행액 415억원 (17)
5. AA등급 이상 회사채 발행 비중 73.0% (17)

LLM 자연어 답변:

"...'Company' 라벨임에도 실제 회사명이 아닌 금융 metric 으로 추출되어 있어,
entity 추출 단계의 라벨 품질을 production 환경에서 보강할 필요가 있습니다."

→ 발표 슬라이드 10 의 정직한 한계 분석 그대로.

✅ DoD 100% 충족

• retrieval/text2cypher.py — LLM 기반 자연어 → Cypher
• 스키마 프롬프트 (LLM 주입)
• read-only 강제 + LIMIT 100 강제
• 결과 → 자연어 답변 (LLM 2단계)
• 평가 셋 factual/numerical 5개 정성 검증
• "X 문서의 Y 섹션에 무엇이 있나" 답변 (Q1, Q3)
• graceful fallback (F1 / F2 / F3)

🚧 발견된 production 개선 포인트 (#18+ 후속)

1. LLM 이 가정한 property 가 스키마에 없는 경우 (F1: c.page 경고)
   → system prompt 에 actual property 목록 추가
2. 유용 property 활용 가이드 (Q5: e.member_count 미사용)
   → 답변 풍부도 개선
3. answer_hints 매칭률 낮음 (정상)
   → heuristic 한계, 박제만

의존 / 후속

• 의존: ✅ PR [Feat] #17 Layer A + MENTIONS + 8문서 일괄 적재 스크립트 (옵션 3 chunk_id prefix) #45 ([Feat] [5/14 보너스] 8문서 일괄 적재 #17 8문서 적재 완료, Aura 9b57188f)
• 후속:
  • [Feat] W4 Layer B: Local Retriever (Entity + Subgraph) #19 Local Retriever (entity 중심 traversal)
  • [Feat] W4 Layer C: Community stub (시나리오 A) #20 Community Summary (Louvain + 전체 트렌드)
  • [Feat] W4 Routing Agent (rule-based) #21 Routing Agent (Layer A/B/C 분기)
• 미래: #46 OpenAI 마이그 (5/24+), close #47 회사 발표 (6/1)

발표 슬라이드 (5/23) 연결

• 슬라이드 10: Entity 라벨 품질 challenge (5/16 + 5/17 Q5 정량 정밀)
• 슬라이드 11: VectorRAG ↔ GraphRAG 보완 (Q4 0 rows 증거)
• 슬라이드 12: Text2Cypher 데모 (NEW! Q2 5.7초 데모)