Skip to content

Commit 623a3b9

Browse files
SonAIengineclaude
SonAIengine
and
claude
committed
docs: 고도화 로드맵 추가 — 15개 후보 + 우선순위 매트릭스 + 마일스톤
## docs/roadmap.md 신규 작성 - 현재 gap 분석: README가 약속한 "round-trip 3-4회 → 1회"가 절반만 성립 (plan_workflow만 있고 execute_plan 부재) - 학술 차별화 9개 중 1개만 구현 (MCP Annotation-Aware Retrieval) - 코드 분석으로 발견한 실용 gap 7개 정리 (workflow 실행 / poisoning defense / score provider SPI / observability / incremental re-index / cross-spec federation / adapter layer) ## 15개 후보 → 거버넌스×효과 매트릭스 우선순위 1~9위 (전제 없음): 1. A. Workflow Execution [10] — README 약속 완성, 다른 5개 후보 전제 2. B. Tool Poisoning Defense [9] — 회사 도입 보안 장벽 제거 3. D. Score Provider SPI [8] — 학술 후보 8개 통합 인프라 4. C. Observability + Trace [7] 5. P6. Token-Budget Knapsack [7] — ICML/NeurIPS 타겟 6. P1. Cross-Server Dependency [6] — MCP-Bench 실패 50% 해결 7. F. Cross-Spec Federation [6] 8. G. Adapter Layer [6] 9. E. Incremental Re-indexing [6] ## 3개 마일스톤 (시나리오 C 기준) - M1 (~9주): v0.5 Release (D → A → C → B) - M2 (~16주): 논문 1 초안 (P1 → F → P2) — EMNLP/ACL Findings 타겟 - M3 (~32주): 논문 2 (P5 → P6) — ICML/NeurIPS 타겟 시간 제약 시 대안 시나리오 A(학술 우선, 4개월)/B(프로덕션, 2개월) 포함. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent eee5716 commit 623a3b9

2 files changed

Lines changed: 299 additions & 0 deletions

File tree

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ docs/
99
├── cli.md # CLI 레퍼런스 (모든 명령)
1010
├── api-reference.md # Python API 레퍼런스 (ToolGraph, helpers, middleware)
1111
├── benchmarks.md # 벤치마크 결과 (pipeline / retrieval / competitive / scale)
12+
├── roadmap.md # 고도화 후보 15개 + 우선순위 매트릭스 + 마일스톤
1213
│
1314
├── integrations/ # 통합 가이드 (사용 패턴별)
1415
│ ├── mcp-server.md # MCP server 모드

‎docs/roadmap.md‎

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
# graph-tool-call Roadmap
2+
3+
> 작성일: 2026-04-09
4+
> 상태: Phase 0~4.5 완료 (255+ tests). 다음 6~9개월 고도화 방향.
5+
>
6+
> 관련 문서:
7+
> - [memo/differentiation-analysis.md](../memo/differentiation-analysis.md) — 학술 차별화 9개 분석
8+
> - [docs/wbs/README.md](wbs/README.md) — Phase 0~4.5 WBS
9+
> - [docs/benchmarks.md](benchmarks.md) — 현재 벤치마크 결과
10+
11+
---
12+
13+
## 요약
14+
15+
현재 graph-tool-call은 **"도구 검색 라이브러리"**로 완성도 높음. 다음 단계는 **"도구 검색 + 실행 + 거버넌스 레이어"**로 카테고리 확장.
16+
17+
고도화 후보 15개를 2축 — **거버넌스**(다른 작업의 전제 + 안정성/보안/관측성)와 **효과**(사용자 체감 + 학술 임팩트) — 로 평가해 우선순위를 매겼다. 1번과 2번 우선순위는 의존성이 명확하므로 순서 고정, 3번 이후는 시간/리소스 제약에 따라 3가지 시나리오로 분기.
18+
19+
---
20+
21+
## 1. 배경 — 현재 gap
22+
23+
### 1.1 README가 약속한 것 vs 실제 구현
24+
25+
README Quick Start는 `plan_workflow()`에 대해 이렇게 쓰여 있다:
26+
27+
> `plan_workflow()` returns ordered execution chains with prerequisites — **reducing agent round-trips from 3-4 to 1**.
28+
29+
하지만 현재 `graph_tool_call/workflow.py`에는 **계획 작성/편집 메서드만 있고 실행 메서드가 없다** (`execute` / `run` / `invoke` 키워드 0개). 단일 tool 실행은 `ToolGraph.execute()`(tool_graph.py:629)에 있지만, 이를 chain으로 묶는 orchestration 레이어가 부재. 즉 "round-trip 1회" 약속은 **절반만 지켜진 상태**.
30+
31+
### 1.2 학술 차별화 9개 중 1개만 구현
32+
33+
[memo/differentiation-analysis.md](../memo/differentiation-analysis.md)는 9개의 학술 차별화 후보를 정리해두었다:
34+
35+
| # | 후보 | Tier | 구현 상태 |
36+
|---|---|:---:|:---:|
37+
| 3.1 | MCP Annotation-Aware Retrieval | 1 | ✅ (Phase 2.5) |
38+
| 3.2 | Execution Trace → Causal Tool Graph | 1 | ❌ |
39+
| 3.3 | Token-Budget Constrained Graph Selection | 1 | ❌ |
40+
| 3.4 | Dynamic Tool Graph | 2 | 부분 |
41+
| 3.5 | Cross-Server Tool Dependency | 2 | ❌ |
42+
| 3.6 | Tool Name Disambiguation | 2 | ❌ (prefix 회피만) |
43+
| 3.7 | Cross-Primitive Retrieval | 3 | ❌ |
44+
| 3.8 | Failure-Aware Closed-Loop Retrieval | 3 | ❌ |
45+
| 3.9 | Stateful Session-Aware Retrieval | 3 | 부분 (history 파라미터만) |
46+
47+
### 1.3 코드 베이스 분석으로 발견한 추가 gap
48+
49+
학술 차별화 분석에 **없는** 실용 gap 7개:
50+
51+
| 코드 | 위치 | gap |
52+
|---|---|---|
53+
| `graph_tool_call/workflow.py` | `WorkflowPlan` | `execute_plan()` 부재 |
54+
| `graph_tool_call/mcp_proxy.py:164-211` | backend tool 수집 | schema 검증/provenance/ACL 부재 |
55+
| `graph_tool_call/retrieval/engine.py:111-188` | 5개 scorer | Score Provider 플러그인 인터페이스 부재 |
56+
| `graph_tool_call/__init__.py` | public API | trace export / debug API 부재 |
57+
| `graph_tool_call/retrieval/graph_search.py:38-100` | `_get_category_index()` | 매 query마다 재구축 |
58+
| `graph_tool_call/ingest/` | 단일 spec | spec 경계를 넘는 federation 부재 |
59+
| `graph_tool_call/ingest/` | 6종 format | 새 format 추가 시 adapter interface 부재 |
60+
61+
---
62+
63+
## 2. 후보 15개 간략 설명
64+
65+
후보는 **그룹 1 (사용자 즉시 체감)**, **그룹 2 (시스템 견고성)**, **그룹 3 (검색 품질 / 학술)** 으로 분류.
66+
67+
### 그룹 1 — 사용자 즉시 체감
68+
69+
#### A. Workflow Execution Engine
70+
**현상**: `plan_workflow()`는 계획만 생성, 실행은 사용자/LLM 책임.
71+
**작업**: `execute_plan(goal, initial_args)` 추가. `params_from` path expression parser로 step 간 데이터 자동 전달. 실패 시 skip / rollback / abort 정책. dry-run 모드.
72+
**효과**: README 약속("round-trip 3-4회 → 1회") 완성. LLM agent가 `execute_plan` 1번 호출로 multi-step workflow 처리. 다른 학술 후보 5개(P4, P5, B enforcement, C trace, end-to-end 벤치마크)의 전제.
73+
**Effort**: 1.5~2주 (HTTP 실행 인프라는 이미 존재, chain orchestration만 추가)
74+
75+
#### B. Tool Poisoning Defense
76+
**현상**: MCP backend tool schema를 그대로 신뢰. 악성 서버가 description에 prompt injection 삽입 가능 (Invariant Labs 보고).
77+
**작업**: Schema 해시 기반 mutation detection / tool provenance 추적 / annotation 기반 ACL (`readOnlyHint=true`만 unprivileged 노출) / prompt injection 패턴 탐지.
78+
**효과**: 회사 도입 시 보안팀 차단 사유 제거. USENIX Security / IEEE S&P 같은 보안 학회 논문 타겟 가능 (Tool Poisoning을 retrieval layer에서 막는 first work).
79+
**Effort**: 2~3주
80+
81+
#### C. Observability + Trace Export
82+
**현상**: 기본 logging만. "왜 이 도구가 검색되지 않았지?" 디버그 불가.
83+
**작업**: `RetrievalEngine`에 `TraceContext` 추가 — 단계별 점수 + 최종 순위 캡처. OpenTelemetry span export. CLI `--trace-out trace.json`.
84+
**효과**: 사용자가 자기 데이터로 튜닝 가능. P4/P5의 데이터 소스 겸용. 도입 전 검증 가능성 ↑.
85+
**Effort**: 1주
86+
87+
#### F. Cross-Spec Federation
88+
**현상**: 여러 OpenAPI spec ingest 시 단순 union. spec A의 `getUser` 출력과 spec B의 `userId` 파라미터가 연결되지 않음.
89+
**작업**: spec 경계를 넘는 parameter schema 매칭. provenance metadata.
90+
**효과**: 회사 internal API 여러 개 통합 케이스 — 실제 도입 시나리오에서 가장 흔한 요구.
91+
**Effort**: 2주 (P1과 인프라 공유)
92+
93+
### 그룹 2 — 시스템 견고성 (인프라)
94+
95+
#### D. Pluggable Score Provider SPI
96+
**현상**: `retrieval/engine.py`에 5개 scorer가 hardcoded. 새 score 추가하려면 engine 직접 수정.
97+
**작업**: `ScoreProvider` Protocol + `register_score_provider()` API. 기존 5개를 SPI에 맞춰 refactor.
98+
**효과**: 학술 후보 P3/P4/P5의 score 통합이 모두 plug-in. 외부 기여자가 새 score (popularity, latency, user feedback 등)를 추가 가능.
99+
**Effort**: 1주
100+
101+
#### E. Incremental Re-indexing
102+
**현상**: tool 추가 시 BM25 index와 embedding을 처음부터 재구축. `_get_category_index()`는 매 query마다 재구축 (1068 tools × tokenization = O(n)).
103+
**작업**: BM25/embedding add-remove API. category index lazy invalidation.
104+
**효과**: 1068+ tools 환경에서 latency 급감. MCP server를 동적으로 추가/제거하는 환경(Cursor, Claude Code)에서 직접 이득.
105+
**Effort**: 1주
106+
107+
#### G. Anti-Corruption Adapter Layer
108+
**현상**: ingest format 6종(OpenAPI/MCP tools/MCP server/Python fn/manual/Arazzo). 새 format 추가 시 ingest 모듈에 산발적 코드.
109+
**작업**: `IngestAdapter` 추상 interface. 기존 6종 refactor. gRPC + GraphQL adapter PoC.
110+
**효과**: 외부 기여 진입 장벽 ↓. 신규 format 200~300 LOC로 추가 가능.
111+
**Effort**: 2주
112+
113+
### 그룹 3 — 검색 품질 / 학술 차별화
114+
115+
#### P1. Cross-Server Tool Dependency
116+
**현상**: 같은 spec 내 의존성만 감지. cross-server 흐름(Slack → Jira → GitHub)은 별개로 취급.
117+
**작업**: `mcp_proxy.py` cross-backend ingest 시 parameter schema 매칭. 새 edge type 불필요 (`REQUIRES`로 충분), backend metadata만 추가.
118+
**효과**: MCP-Bench retrieval 오류의 50%를 차지하는 cross-server 문제 직접 해결. 논문 1편 핵심 contribution.
119+
**Effort**: 2~3주
120+
121+
#### P2. Tool Name Disambiguation
122+
**현상**: MCP 생태계 59% 이름 충돌("search" 32개 서버). 현재는 `serverName__toolName` prefix로 회피.
123+
**작업**: 동일 이름 도구를 (signature + ontology context)로 자동 구분. disambiguation key 생성.
124+
**효과**: LLM이 prefix 신경 쓰지 않아도 됨. 논문 1편의 sub-contribution으로 포함 가능.
125+
**Effort**: 2주
126+
127+
#### P3. Stateful Session-Aware Retrieval
128+
**현상**: history 파라미터로 "이미 호출한 도구"를 demote만 함. 다음 도구 예측 없음.
129+
**작업**: Markov chain on tool graph로 다음 도구 확률 계산. `RetrievalEngine`에 새 score source.
130+
**효과**: multi-turn 대화 retrieval 정확도 ↑. 짧은 후속 질문("이제 그거 취소해") 처리력 강화.
131+
**Effort**: 3~4주 (평가 인프라 포함)
132+
133+
#### P4. Failure-Aware Closed-Loop Retrieval
134+
**현상**: 도구 실패해도 retrieval 순위에 영향 없음.
135+
**작업**: 실행 trace → edge weight online learning. 최근 실패율 높은 도구 자동 강등. `SIMILAR_TO` fallback 제안.
136+
**효과**: self-healing. 운영 중 안 쓰이는 도구 자동 정리.
137+
**전제**: **A 필요** (실행 trace가 있어야 학습 가능)
138+
**Effort**: 3주
139+
140+
#### P5. Execution Trace → Causal Tool Graph
141+
**현상**: 의존성 그래프가 정적 metadata(OpenAPI/CRUD)에만 의존.
142+
**작업**: 실행 trace에서 interventional causal discovery로 인과적 의존성 자동 발견.
143+
**효과**: Tier 1 단독 contribution (causal discovery + tool learning 교차점, 미개척). 사용할수록 똑똑해지는 시스템.
144+
**전제**: **A 필요**
145+
**Effort**: 6~8주 (이론 + 평가)
146+
147+
#### P6. Token-Budget Constrained Graph Selection
148+
**현상**: top-k=5 고정. 도구 토큰 비용 예측 불가.
149+
**작업**: dependency-constrained knapsack ILP formulation. DAG 활용 근사 알고리즘. approximation ratio 증명.
150+
**효과**: Cursor 40 한도, OpenAI 권장 20개 제약 해결. 비용 예측 가능. ICML/NeurIPS 타겟.
151+
**Effort**: 8주 (이론 작업 중심)
152+
153+
#### P7. Cross-Primitive Retrieval
154+
**현상**: MCP의 3대 primitive 중 Tools만 검색.
155+
**작업**: Resources/Prompts 노드 추가. 새 edge type(`PROVIDES_CONTEXT`, `TEMPLATES`). heterogeneous graph 검색.
156+
**효과**: MCP 잠재력 100% 활용.
157+
**블로커**: Resources/Prompts 사용하는 실제 MCP 서버가 적어 평가 데이터셋 부족
158+
**Effort**: 6주 (+ 평가 데이터 수집)
159+
160+
---
161+
162+
## 3. 우선순위 매트릭스
163+
164+
거버넌스 = 다른 작업의 전제 + 안정성/보안/관측성
165+
효과 = 사용자 체감 + 잠금 해제 + 학술/시장 임팩트
166+
167+
| 순위 | 후보 | 거버넌스 | 효과 | 합계 | 전제 |
168+
|:---:|---|:---:|:---:|:---:|---|
169+
| 1 | **A. Workflow Execution** | ★★★★★ | ★★★★★ | 10 | 없음 |
170+
| 2 | **B. Tool Poisoning Defense** | ★★★★★ | ★★★★ | 9 | 없음 |
171+
| 3 | **D. Score Provider SPI** | ★★★★★ | ★★★ | 8 | 없음 |
172+
| 4 | **C. Observability + Trace** | ★★★★ | ★★★ | 7 | 없음 |
173+
| 5 | **P6. Token-Budget Knapsack** | ★★★ | ★★★★ | 7 | 없음 |
174+
| 6 | **P1. Cross-Server Dependency** | ★★ | ★★★★ | 6 | 없음 |
175+
| 7 | **F. Cross-Spec Federation** | ★★ | ★★★★ | 6 | P1 인프라 공유 |
176+
| 8 | **G. Adapter Layer** | ★★★★ | ★★ | 6 | 없음 |
177+
| 9 | **E. Incremental Re-indexing** | ★★★ | ★★★ | 6 | 없음 |
178+
| 10 | P5. Causal Tool Graph | ★★★ | ★★★★★ | 8* | **A 필요** |
179+
| 11 | P4. Failure-Aware | ★★★ | ★★★ | 6* | **A 필요** |
180+
| 12 | P2. Name Disambiguation | ★★ | ★★★ | 5 | 없음 |
181+
| 13 | P7. Cross-Primitive | ★★ | ★★★ | 5 | 없음 |
182+
| 14 | P3. Stateful Session | ★ | ★★★ | 4 | 없음 |
183+
184+
`*` 전제 작업(A) 미완료 시 진입 불가
185+
186+
---
187+
188+
## 4. 마일스톤
189+
190+
### 권장 진행 (6~8개월, 시나리오 C)
191+
192+
```
193+
┌─────────────────────────────────────────────────────────┐
194+
│ Week 1 D. Score Provider SPI [1w] │
195+
│ Week 2-4 A. Workflow Execution [3w] │
196+
│ Week 5-6 C. Observability + Trace [2w] │
197+
│ Week 7-9 B. Tool Poisoning Defense [3w] │
198+
├─────────────────────────────────────────────────────────┤
199+
│ 마일스톤 1 (~9주) — v0.5 Release │
200+
│ ✓ Workflow 완성 (README 약속 성립) │
201+
│ ✓ Security defense │
202+
│ ✓ Observability + debug │
203+
│ ✓ Score provider plugin SPI │
204+
└─────────────────────────────────────────────────────────┘
205+
206+
┌─────────────────────────────────────────────────────────┐
207+
│ Week 10-12 P1. Cross-Server Dependency [3w] │
208+
│ Week 13-14 F. Cross-Spec Federation [2w] │
209+
│ Week 15-16 P2. Name Disambiguation [2w] │
210+
├─────────────────────────────────────────────────────────┤
211+
│ 마일스톤 2 (~16주) — 논문 1 초안 │
212+
│ "MCP-Native Graph Tool Retrieval: │
213+
│ Cross-Server Dependency + Name Disambiguation + │
214+
│ Annotation-Aware Defense" │
215+
│ 타겟: EMNLP Workshop / ACL Findings │
216+
└─────────────────────────────────────────────────────────┘
217+
218+
┌─────────────────────────────────────────────────────────┐
219+
│ Week 17-24 P5. Causal Tool Graph [8w] │
220+
│ Week 25-32 P6. Token-Budget Knapsack [8w] │
221+
├─────────────────────────────────────────────────────────┤
222+
│ 마일스톤 3 (~32주) — 논문 2 │
223+
│ "Token-Constrained Tool Selection as │
224+
│ Graph Optimization" │
225+
│ 타겟: ICML / NeurIPS │
226+
└─────────────────────────────────────────────────────────┘
227+
```
228+
229+
### 대안 시나리오
230+
231+
#### 시나리오 A — 학술 우선 (4개월, 논문 1편)
232+
233+
시간이 제한적이고 논문 1편을 빨리 받고 싶은 경우.
234+
235+
```
236+
Week 1 D. Score Provider SPI [1w]
237+
Week 2-4 P1. Cross-Server Dependency [3w]
238+
Week 5-6 P2. Name Disambiguation [2w]
239+
Week 7-9 B. Tool Poisoning Defense [3w]
240+
Week 10-16 논문 1 작성 (LiveMCPBench + ToolBench 평가)
241+
```
242+
243+
**리스크**: A가 뒤로 밀려서 P4/P5가 영구적으로 막힘. 논문 2 불가능.
244+
245+
#### 시나리오 B — 프로덕션 우선 (2개월, 사용자 확보)
246+
247+
학술 의도 없이 실사용자 확보가 목표인 경우.
248+
249+
```
250+
Week 1-3 A. Workflow Execution [3w]
251+
Week 4 C. Observability + Trace [1w]
252+
Week 5 E. Incremental Re-indexing [1w]
253+
Week 6-7 F. Cross-Spec Federation [2w]
254+
Week 8 블로그 + LangChain community 등록 (Phase 4 잔여)
255+
```
256+
257+
**산출물**: PyPI 다운로드 ↑, real-world adopter case 1~2개, blog 기반 유입.
258+
259+
---
260+
261+
## 5. Phase 4 잔여 작업
262+
263+
시나리오와 무관하게 마무리할 가치 있음. 마일스톤 사이사이에 끼워 진행.
264+
265+
- [ ] 4-1d. 관계 검증 UI (confirm/reject)
266+
- [ ] 4-2. LangChain community package 등록
267+
- [ ] 4-3. 블로그: "Why Graph > Vector for Tool Retrieval"
268+
- [ ] 4-4. (선택) LAPIS 포맷 출력
269+
- [ ] 4-5. (선택) Rust (PyO3+petgraph) 최적화
270+
271+
---
272+
273+
## 6. 의사결정 포인트
274+
275+
다음 작업에 들어가기 전 확정해야 할 것:
276+
277+
1. **시나리오 선택** (A/B/C)
278+
- 논문 마감 있음 → A
279+
- 학술 의도 없음 → B
280+
- 시간 여유 있음 → C (권장)
281+
282+
2. **첫 작업 확정**
283+
- 시나리오 C → D (1주) 후 A (3주)
284+
- 시나리오 A → D (1주) 후 P1 (3주)
285+
- 시나리오 B → A (3주)
286+
287+
3. **Phase 4 잔여 끼워넣기 여부**
288+
- 4-2, 4-3은 시나리오 B 마지막에 통합
289+
- 4-1d는 Workflow Editor와 함께 A 작업 시 처리 가능
290+
291+
---
292+
293+
## 참고
294+
295+
- [memo/differentiation-analysis.md](../memo/differentiation-analysis.md) — 학술 차별화 9개 후보 상세
296+
- [docs/wbs/README.md](wbs/README.md) — Phase 0~4.5 완료 내역
297+
- [docs/benchmarks.md](benchmarks.md) — 현재 벤치마크 (Petstore 19 / GitHub 50 / MCP 38 / k8s 248 / GitHub full 1068)
298+
- [docs/design/benchmark.md](design/benchmark.md) — 벤치마크 설계 근거

0 commit comments

Comments
 (0)