Skip to content

Commit d304edc

Browse files
SonAIengineSonAIengine
committed
Release v0.8.0
1 parent 9c0844a commit d304edc

43 files changed

Lines changed: 2691 additions & 219 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/release-draft.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Draft Release Notes
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*"
7+
workflow_dispatch:
8+
inputs:
9+
tag:
10+
description: "Release tag (e.g. v0.8.0)"
11+
required: true
12+
type: string
13+
14+
jobs:
15+
draft-release:
16+
runs-on: ubuntu-latest
17+
permissions:
18+
contents: write
19+
steps:
20+
- uses: actions/checkout@v4
21+
- uses: actions/setup-python@v5
22+
with:
23+
python-version: "3.12"
24+
- name: Resolve version
25+
id: version
26+
run: |
27+
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
28+
TAG="${{ inputs.tag }}"
29+
else
30+
TAG="${GITHUB_REF_NAME}"
31+
fi
32+
echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
33+
echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
34+
- name: Generate release notes body
35+
run: |
36+
python scripts/release.py notes \
37+
--version "${{ steps.version.outputs.version }}" \
38+
--output release-notes.md \
39+
--format github
40+
- name: Create draft release
41+
uses: softprops/action-gh-release@v2
42+
with:
43+
tag_name: ${{ steps.version.outputs.tag }}
44+
name: ${{ steps.version.outputs.tag }}
45+
body_path: release-notes.md
46+
draft: true
47+
prerelease: false

‎AGENTS.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Codex Entry
2+
3+
이 저장소의 공통 에이전트 규칙은 [`docs/agent-guide.md`](docs/agent-guide.md)에 있다.
4+
Codex는 먼저 이 문서를 기준으로 작업한다.
5+
6+
## Codex 메모
7+
- 프로젝트 공통 규칙, 개발 명령, 테스트 기준은 공통 문서를 따른다.
8+
- Codex 전용 규칙이 추가로 생길 때만 이 파일에 최소한으로 적는다.

‎CHANGELOG.md‎

Lines changed: 42 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
## [0.8.0] - 2026-03-12
11+
1012
### Planned — Phase 4
11-
- Interactive Dashboard (Dash Cytoscape) — visualization + manual editing
13+
- Interactive dashboard manual editing and relation review workflow
1214
- LangChain community package
1315
- llama.cpp provider
1416

17+
### Added
18+
- **Interactive dashboard MVP**
19+
- `tg.dashboard_app()` to build a Dash Cytoscape app
20+
- `tg.dashboard()` to launch interactive graph inspection locally
21+
- relation/category filters, node detail panel, and query result highlighting
22+
- **Operational analyze report**
23+
- `tg.analyze()` summary with duplicates, conflicts, orphan tools, category coverage
24+
- CLI `analyze` now supports conflicts, orphans, categories, and JSON output
25+
- **Remote fetch hardening** for spec and workflow ingest
26+
- shared safe network helper for remote OpenAPI / Swagger UI / Arazzo loading
27+
- private / localhost hosts blocked by default
28+
- response size limits, redirect limits, and content-type checks
29+
- explicit opt-in via `allow_private_hosts=True`
30+
- **Execution policy layer** for tool calls
31+
- `ToolCallDecision` (`allow`, `confirm`, `deny`)
32+
- `ToolCallPolicy` and `ToolCallAssessment`
33+
- `tg.assess_tool_call()` API on top of `validate_tool_call()`
34+
- destructive auto-corrected calls denied by default
35+
- **MCP server ingest**
36+
- `fetch_mcp_tools()` — HTTP JSON-RPC `tools/list`
37+
- `tg.ingest_mcp_server()` — fetch + ingest MCP tool list from server URL
38+
- supports both `{"result": {"tools": [...]}}` and `{"tools": [...]}`
39+
- **Embedding persistence**
40+
- embedding vectors are now serialized with the graph
41+
- restorable embedding provider config is preserved when available
42+
- retrieval weights and diversity settings are restored on load
43+
44+
### Changed
45+
- **Serialization format** now stores optional `retrieval_state`
46+
- embedding index state
47+
- retrieval weights
48+
- diversity configuration
49+
- **Documentation sync**
50+
- WBS updated to match actual Phase 3 implementation status
51+
- `README.md`, `README-ko.md`, `README-ja.md`, `README-zh_CN.md` updated with
52+
MCP server ingest, execution policy, remote fetch safety, and embedding persistence
53+
1554
## [0.5.0] - 2026-03-07
1655

1756
### Added
@@ -147,9 +186,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
147186
- **Tests**: 32 tests passing across all modules
148187
- **Example**: `quickstart.py` demonstrating full workflow
149188

150-
[Unreleased]: https://github.com/SonAIengine/graph-tool-call/compare/v0.5.0...HEAD
189+
[Unreleased]: https://github.com/SonAIengine/graph-tool-call/compare/v0.8.0...HEAD
151190
[0.5.0]: https://github.com/SonAIengine/graph-tool-call/compare/v0.4.0...v0.5.0
152191
[0.4.0]: https://github.com/SonAIengine/graph-tool-call/compare/v0.3.0...v0.4.0
153192
[0.3.0]: https://github.com/SonAIengine/graph-tool-call/compare/v0.2.0...v0.3.0
154193
[0.2.0]: https://github.com/SonAIengine/graph-tool-call/compare/v0.1.0...v0.2.0
155194
[0.1.0]: https://github.com/SonAIengine/graph-tool-call/releases/tag/v0.1.0
195+
[0.8.0]: https://github.com/SonAIengine/graph-tool-call/compare/v0.5.0...v0.8.0

‎CLAUDE.md‎

Lines changed: 6 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -1,119 +1,8 @@
1-
# graph-tool-call 개발 가이드
1+
# Claude Code Entry
22

3-
## 프로젝트 개요
4-
LLM 에이전트를 위한 그래프 기반 도구 검색 엔진. NetworkX DiGraph + BM25 + Embedding + MCP Annotation + wRRF 기반 하이브리드 검색.
3+
이 저장소의 공통 에이전트 규칙은 [`docs/agent-guide.md`](docs/agent-guide.md)에 있다.
4+
Claude Code에서는 먼저 이 문서를 기준으로 작업한다.
55

6-
## 개발 환경
7-
8-
### 필수 도구
9-
```bash
10-
poetry install --with dev # 기본 개발 환경
11-
poetry install --with dev --all-extras # 모든 optional dep 포함
12-
```
13-
14-
### Lint & Format
15-
```bash
16-
poetry run ruff check . # lint 검사
17-
poetry run ruff format --check . # format 검사
18-
poetry run ruff format . # 자동 format 적용
19-
```
20-
21-
**중요**: 반드시 `poetry run ruff`를 사용할 것. 시스템 ruff나 `pip install ruff`는 버전이 다를 수 있음.
22-
- pyproject.toml에 ruff 버전이 명시되어 있고, CI도 동일한 poetry 환경에서 실행함
23-
- 커밋 전 `poetry run ruff format .` + `poetry run ruff check .` 통과 확인 필수
24-
25-
### 테스트
26-
```bash
27-
poetry run pytest tests/ -v # 전체 테스트
28-
poetry run pytest tests/ -q # 간결 출력
29-
```
30-
31-
## CI/CD (GitHub Actions)
32-
- `.github/workflows/ci.yml`
33-
- lint job: `poetry install --only dev` → `poetry run ruff check/format`
34-
- test job: Python 3.10~3.14 매트릭스, `poetry install --with dev`
35-
- **lint와 test 모두 poetry 환경에서 실행** (버전 일관성 보장)
36-
37-
## 코드 규칙
38-
39-
### Optional Dependency 패턴
40-
```python
41-
try:
42-
import numpy as np
43-
except ImportError:
44-
np = None
45-
46-
def _require_numpy():
47-
if np is None:
48-
msg = "numpy required: pip install graph-tool-call[embedding]"
49-
raise ImportError(msg)
50-
```
51-
- extras별 그룹: `openapi`, `embedding`, `similarity`, `langchain`, `all`
52-
- 에러 메시지에 설치 명령어 포함
53-
54-
### HTTP 호출
55-
- `urllib.request` 사용 (requests/httpx 의존 안 함)
56-
- `# noqa: S310` 주석으로 bandit 경고 억제
57-
58-
### 테스트 작성
59-
- conftest.py 없음 — 각 테스트 파일에 헬퍼 함수 자체 정의
60-
- `pytest.importorskip("module")` 으로 optional dep 테스트 처리
61-
- mock 최소화, 실제 코드 실행 선호
62-
63-
### ruff 설정
64-
```toml
65-
[tool.ruff]
66-
target-version = "py310"
67-
line-length = 100
68-
69-
[tool.ruff.lint]
70-
select = ["E", "F", "I", "N", "W", "UP"]
71-
```
72-
73-
## 커밋 규칙
74-
- 한글 커밋 메시지, 구체적 내용 포함
75-
- `git -c user.name="SonAIengine" -c user.email="sonsj97@gmail.com" commit`
76-
- main 직접 push 가능 (개인 프로젝트)
77-
- 커밋 전 체크리스트:
78-
1. `poetry run ruff check .`
79-
2. `poetry run ruff format --check .`
80-
3. `poetry run pytest tests/ -q`
81-
82-
## 주요 파일 구조
83-
```
84-
graph_tool_call/
85-
__init__.py # public exports (MCPAnnotations, ToolSchema, ...), __version__
86-
tool_graph.py # ToolGraph facade (모든 public API, from_url(), ingest_mcp_tools())
87-
core/tool.py # MCPAnnotations, ToolSchema, parse_mcp_tool(), parse_tool()
88-
analyze/
89-
dependency.py # 자동 의존관계 탐지
90-
similarity.py # 5-Stage 중복 탐지 파이프라인 (annotation 보너스 포함)
91-
ingest/
92-
openapi.py # OpenAPI 3.x 파서 (description fallback, HTTP→annotation 추론)
93-
mcp.py # MCP tool list ingest (inputSchema + annotations 파싱)
94-
arazzo.py # Arazzo 1.0.0 워크플로우 파서
95-
ontology/
96-
auto.py # auto_organize (Auto + LLM-Auto 모드)
97-
builder.py # OntologyBuilder (node에 annotations 저장)
98-
llm_provider.py # OntologyLLM ABC + Ollama/OpenAI providers
99-
schema.py # NodeType, RelationType enums
100-
retrieval/
101-
engine.py # RetrievalEngine (4-source wRRF: BM25+Graph+Embedding+Annotation)
102-
intent.py # QueryIntent + classify_intent() — 한/영 키워드 기반 zero-LLM
103-
annotation_scorer.py # score_annotation_match() + compute_annotation_scores()
104-
embedding.py # EmbeddingIndex (sentence-transformers)
105-
search_llm.py # SearchLLM ABC + providers
106-
```
107-
108-
## 강건화 (Layered Resilience)
109-
110-
### Description Fallback
111-
`ingest/openapi.py`의 `_operation_to_tool()`에서 summary/description이 비어있으면 자동 생성:
112-
```
113-
{METHOD} {path} [{tags}] → 예: "GET /items [items]"
114-
```
115-
116-
### from_url()
117-
`ToolGraph.from_url(url)` — Swagger UI URL에서 swagger-config 자동 탐색 후 여러 spec 통합 ingest.
118-
- `/swagger-ui/` 포함 URL → swagger-config 파싱 → urls[].url 추출
119-
- 일반 spec URL → 직접 ingest
6+
## Claude 메모
7+
- 프로젝트 공통 규칙, 개발 명령, 테스트 기준은 공통 문서를 따른다.
8+
- Claude 전용 규칙이 추가로 생길 때만 이 파일에 최소한으로 적는다.

‎README-ja.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,7 @@ pip install graph-tool-call[all] # すべて
140140
pip install graph-tool-call[lint] # + ai-api-lint spec自動修正
141141
pip install graph-tool-call[similarity] # + rapidfuzz 重複検出
142142
pip install graph-tool-call[visualization] # + pyvis HTMLグラフエクスポート
143+
pip install graph-tool-call[dashboard] # + Dash Cytoscape ダッシュボード
143144
pip install graph-tool-call[langchain] # + LangChain toolアダプター
144145
```
145146

@@ -385,6 +386,32 @@ tools = tg.retrieve("一時ファイルを削除", top_k=5)
385386
MCPアノテーション（`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`）は検索シグナルとして活用されます。
386387
参照クエリはread-onlyツールを、削除クエリはdestructiveツールをより優先的にランク付けできます。
387388

389+
### MCPサーバーURLから直接収集
390+
391+
```python
392+
from graph_tool_call import ToolGraph
393+
394+
tg = ToolGraph()
395+
396+
# Public MCP endpoint
397+
tg.ingest_mcp_server("https://mcp.example.com/mcp")
398+
399+
# ローカル/プライベートMCP endpointは明示的な許可が必要
400+
tg.ingest_mcp_server(
401+
"http://127.0.0.1:3000/mcp",
402+
allow_private_hosts=True,
403+
)
404+
```
405+
406+
`ingest_mcp_server()` は HTTP JSON-RPC `tools/list` を呼び出してツール一覧を取得し、
407+
MCPアノテーションを保持したまま graph に登録します。
408+
409+
リモート収集の既定セーフティ:
410+
- private / localhost host は既定でブロック
411+
- リモート応答サイズを制限
412+
- redirect 回数を制限
413+
- 想定外の content-type を拒否
414+
388415
### Python関数から生成
389416

390417
```python
@@ -482,6 +509,15 @@ tg = ToolGraph.from_url(url, cache="my_graph.json")
482509

483510
グラフ構造全体（ノード、エッジ、関係タイプ、ウェイト）が保持されます。
484511

512+
エンベディング検索を有効化した状態で保存すると、次も一緒に保持されます。
513+
- embedding vector
514+
- 復元可能な embedding provider 設定
515+
- retrieval weights
516+
- diversity 設定
517+
518+
つまり `ToolGraph.load()` 後に embedding を再構築しなくても、
519+
hybrid retrieval 状態をそのまま復元できます。
520+
485521
---
486522

487523
## 高度な機能
@@ -621,24 +657,29 @@ tg = ToolGraph.from_url(url, lint=True)
621657
| `add_tools(tools)` | 複数ツール追加 |
622658
| `ingest_openapi(source)` | OpenAPI / Swagger specから収集 |
623659
| `ingest_mcp_tools(tools)` | MCPツールリストから収集 |
660+
| `ingest_mcp_server(url)` | MCP HTTPサーバーから直接収集 |
624661
| `ingest_functions(fns)` | Python callableから収集 |
625662
| `ingest_arazzo(source)` | Arazzo 1.0.0ワークフロー spec収集 |
626663
| `from_url(url, cache=...)` | Swagger UIまたはspec URLからビルド |
627664
| `add_relation(src, tgt, type)` | 手動関係追加 |
628665
| `auto_organize(llm=...)` | ツール自動分類 |
629666
| `build_ontology(llm=...)` | 完全オントロジービルド |
630667
| `retrieve(query, top_k=10)` | ツール検索 |
668+
| `validate_tool_call(call)` | ツール呼び出しの検証と自動補正 |
669+
| `assess_tool_call(call)` | 実行ポリシーに基づく `allow/confirm/deny` 判定 |
631670
| `enable_embedding(provider)` | ハイブリッドエンベディング検索を有効化 |
632671
| `enable_reranker(model)` | cross-encoderリランキングを有効化 |
633672
| `enable_diversity(lambda_)` | MMR多様性を有効化 |
634673
| `set_weights(...)` | wRRF融合ウェイトチューニング |
635674
| `find_duplicates(threshold)` | 重複ツール検出 |
636675
| `merge_duplicates(pairs)` | 検出された重複を統合 |
637676
| `apply_conflicts()` | CONFLICTS_WITHエッジ検出/追加 |
677+
| `analyze()` | 運用分析レポートを生成 |
638678
| `save(path)` / `load(path)` | シリアライズ / デシリアライズ |
639679
| `export_html(path)` | インタラクティブHTML可視化エクスポート |
640680
| `export_graphml(path)` | GraphMLフォーマットエクスポート |
641681
| `export_cypher(path)` | Neo4j Cypher文エクスポート |
682+
| `dashboard_app()` / `dashboard()` | ダッシュボードを生成 / 起動 |
642683

643684
</details>
644685

0 commit comments

Comments
 (0)