[Feat] W4 Community stub + Routing Agent (#20 + #21) by TaskerJang · Pull Request #51 · TaskerJang/doc-graph-agent

TaskerJang · 2026-05-17T01:00:23Z

요약

W4 마무리. Layer C (Community Summary) stub + Layer A/B/C 통합 라우팅 에이전트 박제.

Closes #20, closes #21.

PR #49 (#19 Local Retriever) 머지 직후 진행 — 시나리오 A 의 5/18 일정을 하루 당겨 5/17 안에 W4 전체 완료.

변경 사항

신규 (4)

retrieval/community_summary.py — Layer C stub 진입점 (@track, 138 lines, LLM/Neo4j 호출 0회)
retrieval/prompts/community_summary_v1.md — W5+ 실제 구현 시 채울 placeholder
retrieval/router.py — Routing Agent (decide_route, route_and_answer, 424 lines)
retrieval/prompts/router_v1.md — LLM fallback system prompt + 5 few-shot

수정 (2)

retrieval/__init__.py — 신규 export 8개 (DEFAULT_ROUTE, Route, RouteDecision, RoutedResult, decide_route, route_and_answer, CommunitySummaryResult, community_summary)
scripts/run_w4_eval.py — expected_route 필드 + R1~R3 케이스 + --suite router + routing 결과 표

박제 (1)

docs/weekly-log/2026-05-17-community-router.md — 작업 컨텍스트 + 레퍼런스 표 + 설계 결정 + 평가 셋 + 발표 슬라이드 14 연결

설계 결정

#20 Community Summary — 순수 stub

Microsoft GraphRAG 의 Global Search 는 indexing time 에 community detection + community report 생성이 선행되어야 동작. 우리는 둘 다 없음.
LLM 만으로 글로벌 답변 흉내내면 "그래프 기반" 표현이 거짓 → 정직한 stub 만 제공.
응답: 글로벌 질의 분류 확인 + Layer C 미구현 명시 + 5/24+ ETA + 대안 (Layer A/B 활용).
인터페이스 박제: CommunitySummaryResult(answer, is_stub=True) — 미래 진짜 Layer C 와 시그니처 호환.

#21 Routing Agent — 키워드 분기 + LLM fallback

결정적 키워드 우선 — LangChain MultiRetrievalQAChain 의 LLM router 는 "the same query may route to different sources" (TDS 2025) 일관성 문제. 결정적 분기를 1단계로 두면 디버깅 / 평가 / 발표 시연 모두 명확.
LLM fallback 은 필요한 만큼만 — 키워드 매칭 0개 시에만 호출 → 단순 factual 질문은 LLM 호출 없이 t2c 로 즉시 라우팅.
graceful default = t2c — LLM 실패 / unknown route 시 (NeoConverse 의 "Intelligent fallback mechanism" 패턴).

키워드 매핑:

LOCAL_KEYWORDS (11개): 관계, 관련, 연관, 영향, 함께, 이웃, 어떻게, co-mention, 관계는, 관련된, 연관된
COMMUNITY_KEYWORDS (17개): 트렌드, 전체, 흐름, 주요 트렌드, 주제, 패턴, 주요 흐름, 전반, 글로벌, community, communities, topic, topics, themes, 전체적, 통합, 사전체
그 외 → t2c

평가 셋 R1~R3

ID	출처	질문	기대 라우트	검증 포인트
R1	Q2 동일	"미래에셋증권 4분기 보고서의 Table 은 몇 개?"	`t2c`	키워드 매칭 0개 → LLM fallback 트리거 검증 + t2c 답변 "6"
R2	L1 변형	"두산밥캣과 함께 언급된 리스크는 어떻게 관련되어 있나?"	`local`	"관련/어떻게/함께" 매칭 → local 즉시 분기
R3	L5 동일	"전체 8문서의 주요 트렌드와 흐름은?"	`community`	"전체/트렌드/흐름" 매칭 → community stub 응답 검증

검증 명령

git pull
uv run python -m scripts.run_w4_eval --suite router --json eval/w4_router_2026-05-17.json

DoD

#20 Community Summary stub

community_summary(question) 진입점
CommunitySummaryResult 시그니처 박제 (is_stub=True)
@track Opik trace
LLM/Neo4j 호출 0회
R3 케이스로 평가 통합

#21 Routing Agent

키워드 분기 1단계 (_classify_by_keywords)
LLM fallback 2단계 (_classify_by_llm) — JSON 응답 강제, tenacity 2 attempts
graceful default = t2c
통합 진입점 route_and_answer (@track)
R1~R3 평가 셋 + --suite router 옵션

발표 슬라이드 14 (Routing 명분) 강화

PR #49 까지: L5 PASS 만 있었음 (local_retriever 내부의 "Layer C 적합 안내" fallback).

본 PR 머지 후:

R3 시연 = 명시적 routing decision trace (matched_keywords, llm_used 필드) + Layer C stub 응답
R2 의 키워드 4중 매칭 trace = Opik nested span 으로 "라우팅 → entity 매칭 0개 → graceful fallback" 3단계 시각화

후속 (본 PR 스코프 외)

Issue #50 (Entity 추출 한계) — 5/24+ W5 영역, 발표 전 해결 불요
W5+ Layer C 실제 구현 (community detection → report 생성 → Global Search)
Semantic Router 확장 (EmbeddingRouterChain 패턴)

W4 세 번째 retrieval — Layer C 의 stub 구현. 실제 community detection / 요약은 W5+ 영역. 본 모듈은 Routing Agent (#21) 가 글로벌 질의를 Layer C 로 분기했을 때의 진입점 함수만 제공. 설계 결정: - Microsoft GraphRAG 의 Global Search 는 indexing time 사전 생성 community report 위에서 동작. 본 프로젝트는 community detection 자체가 미구현 → community 자료 없이 LLM 만 가지고 글로벌 답변 흉내내는 것은 정직하지 않음. - stub 응답: 글로벌 질의 분류 확인 + Layer C 미구현 명시 + 5/24+ ETA + 대안 안내 (Layer A/B 활용). - LLM / Neo4j 호출 없음 → 즉시 응답. @track 으로 Opik trace. DoD (#20): - Routing Agent (#21) 진입점 함수 제공 ✅ - 정직한 미구현 안내 ✅ - 즉시 응답 ✅ 후속: - 실제 Layer C 구현은 별도 이슈 (W5+) — Leiden detection + 사전 community summary + map-reduce 답변 합성. Reference: - Microsoft GraphRAG Global Search (map-reduce) - Sotaaz blog (2026-01) — hybrid_search() 의 elif is_global 분기 - graphrag.com/reference/global-community-summary-retriever

W5+ 실제 Layer C 구현 시 사용할 프롬프트 placeholder. 현재 stub 단계에서는 LLM 호출이 없어 본 프롬프트는 실제로 사용되지 않으나, 향후 활성화 시점에 바로 사용 가능하도록 구조 미리 정립. 내용: - Role 정의 (Community report 위 map-reduce 답변 합성기) - Input format (W5+ 시 community_reports 배열 입력) - Output format (자연어 답변) - Reference (Microsoft GraphRAG, Tomaz Bratanic) - 현재 stub 상태 명시

W4 통합 진입점 — 사용자 질문을 받아 Layer A/B/C 로 라우팅: - t2c (Text2Cypher) — factual / numerical / topN - local (Local Retriever) — 관계 / 연관 / co-mention - community (Community Summary stub) — 글로벌 / 트렌드 2단계 구조: 1. 키워드 매칭 (결정적, LLM 호출 없음) — 매칭 있으면 즉시 분기 2. LLM fallback — 키워드 매칭 0개 시에만, max_tokens=150 (짧음) 3. graceful default — LLM 실패 시 t2c 설계 결정: - LangChain MultiRetrievalQAChain 의 LLM router 는 "same query may route to different sources" (TDS, 2025) 일관성 문제. 결정적 1단계 우선. - 키워드 매칭은 토큰 비용 0 — 단순 factual 도 LLM 호출 없이 분기 - LLM fallback 은 어휘 한계 보완 — 키워드 못 잡는 변형 표현 처리 키워드 매핑: - 관계 / 관련 / 연관 / 영향 / 함께 / 이웃 / 어떻게 → local - 트렌드 / 전체 / 흐름 / 주제 / 패턴 / 글로벌 / community → community - 그 외 → t2c (default) Tie-break: 두 셋 동시 매칭 시 더 많은 쪽 (동률이면 community — 전체 의도 보통 글로벌). Reference: - LangChain MultiRetrievalQAChain (LLM router) - LangChain EmbeddingRouterChain (semantic router — 5/24+ 검토) - Neo4j ToolsRetriever (convert_to_tool 패턴) - NeoConverse (specialized 없으면 Text2Cypher fallback) - Sotaaz blog (2026-01) — hybrid_search() if/elif/else 패턴 - Memgraph Atomic GraphRAG (2026-03) — Analytical/Local/Global 3-way 향후 (5/24+): - Semantic Router (embedding) — 키워드 어휘 한계 보완 - LLM fallback 신뢰도 점수화 — dual-path 합성 - Conversation history 반영

키워드 매칭 0개 시 LLM 으로 라우팅 결정할 때 사용하는 system prompt. 구성: - 3가지 retriever 정의 + 예시 질문 - 분류 기준 (순서대로 판단) - Output format (JSON: route + reasoning) - 5개 few-shot 예시 (t2c x 2, local x 2, community x 1) 특징: - max_tokens=150 — 짧은 응답만 받음 - temperature=0.0 — 결정적 라우팅 - response_format={"type": "json_object"} 강제 - LLM 실패 / unknown route 시 caller 가 default (t2c) 로 fallback

, #21) 신규 export: - DEFAULT_ROUTE, Route (타입) - RouteDecision, RoutedResult (결과 객체) - decide_route, route_and_answer (진입점) - CommunitySummaryResult, community_summary (stub) 권장 진입점은 `route_and_answer(question)` — 일반 사용 시 라우팅 자동. 개별 retriever 함수도 그대로 export 유지 — 명시적 테스트 / 직접 호출 시 사용. sha 충돌 가능성 0 (dev branch 의 __init__.py 와 다른 파일).

R1~R3 평가 셋: - R1 (Q2 동일) — factual / 개수 → t2c 라우팅 기대. 키워드 매칭 0개라 LLM fallback 트리거의 검증 케이스도 겸함. - R2 (L1 변형) — "관계/관련/어떻게/함께" 키워드 4중 매칭 → local 기대. - R3 (L5 동일) — "전체/트렌드/흐름" 키워드 매칭 → community (stub) 기대. eval 스크립트 변경: - EvalCase 에 expected_route 필드 추가 (R* 케이스 전용) - _evaluate_router_case() 추가 — 라우팅 정확성 + answer 채워짐 + hint 검증 - CaseEvalResult 에 router 전용 필드 (actual_route, matched_keywords, llm_used, llm_reasoning) 추가 - _print_summary_table 에 Routing 결과 표 추가 (expected vs actual, match 표시, LLM 사용 여부, 매칭 키워드) - --suite router 옵션 추가 - 라우팅 평균 응답 시간 + 정확도 표시 새 케이스를 별도 만들지 않고 Q2/L1/L5 의 의도 재활용 — 발표 자료 일관성 + 빠른 검증. R1 은 키워드 0개라 LLM fallback / default(t2c) 경로 검증 겸함.

TaskerJang · 2026-05-17T01:04:53Z

정성 검증 결과 (5/17 10:02 KST 로컬 실행)

3/3 PASS · 라우팅 정확도 100% · 전체 12.8s · Routing 평균 4.3s

ID	category	verdict	expected	actual	match	llm?	matched_keywords	elapsed
R1	routing-factual	PASS	t2c	t2c	✅	✅	—	7.2s
R2	routing-relation	PASS	local	local	✅	—	관련, 함께, 어떻게	5.6s
R3	routing-global	PASS	community	community	✅	—	트렌드, 전체, 흐름, 주요 트렌드	0.0s

R1 — LLM fallback 트리거 ✅

키워드 0개 → LLM fallback 진입
Kimi reasoning: "특정 문서 내의 Table 개수를 묻는 명시적 사실 질문. Text2Cypher가 aggregation 쿼리를 통해 처리할 수 있다." → t2c
답변: "미래에셋증권 4분기 실적보고서에는 총 6개의 표(Table) 가 적재되어 있습니다." (Q2 답과 일치)

R2 — 키워드 3중 매칭 + graceful fallback ✅

"관련 / 함께 / 어떻게" 3개 매칭 → local 즉시 분기 (LLM 호출 없음, 결정적)
두산밥캣 entity 매칭 0개 → graceful fallback 응답
라우팅 + retriever 내부 fallback 양쪽 검증

R3 — Community stub 즉시 응답 ✅

"트렌드 / 전체 / 흐름 / 주요 트렌드" 4개 매칭 → community 즉시 분기
LLM/Neo4j 호출 0회 → elapsed 0.0s (의도대로)
Answer hint hits 5/5

Opik trace

프로젝트: hyunsang-doc-graph-agent
모든 R* 케이스의 라우팅 decision + 하위 retriever 호출이 nested span 으로 박제됨

박제 commit

6f6ec36a — weekly-log 정성 검증 결과 + R2/R3 매칭 개수 정확도 수정 (R2 4중→3중, R3 3중→4중)

PR 머지 준비 완료. 머지 시 #20, #21 자동 close.

TaskerJang added 8 commits May 17, 2026 09:42

docs(weekly-log): 5/17 W4 community stub + routing agent 박제 (#20 + #21)

9a1c2a3

docs(weekly-log): 정성 검증 결과 3/3 PASS 박제 + R2/R3 매칭 개수 정확도 수정

6f6ec36

TaskerJang merged commit 7cddcbe into dev May 17, 2026

This was referenced May 26, 2026

[Feat] P1 — Entity 추출 프롬프트 재설계 (Metric 라벨 + Few-shot + 후처리 검증) #56

Closed

[Feat] P4 — Layer C 핵심 로직 구현 (Leiden community detection + map-reduce 요약 합성) #59

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Feat] W4 Community stub + Routing Agent (#20 + #21)#51

[Feat] W4 Community stub + Routing Agent (#20 + #21)#51
TaskerJang merged 8 commits into
devfrom
feat/20-21-community-router

TaskerJang commented May 17, 2026

Uh oh!

TaskerJang commented May 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant