SonAIengine/graph-tool-call

**Graph-structured retrieval for large LLM tool catalogs.**
Find the target tool, the prerequisite tools that produce its inputs, and the
smallest schema bundle that fits the planner's token budget.
Documentation ·
Quickstart ·
PyPI ·
Benchmarks
English · 한국어
---
The Problem
A semantic search for "refund an order" can find refundOrder. That is not
enough when the operation requires an order_id that the user does not have.
A usable candidate set also needs the operation that produces that field:
Large catalogs create a second problem: sending every schema to the model wastes
context and can lower selection quality. graph-tool-call treats retrieval as a
contract-aware graph problem instead of flat similarity search.
It provides:
- deterministic ingestion from OpenAPI, GraphQL introspection, MCP tools,
Python functions, and structured tool catalogs;
- hybrid target retrieval with keyword, graph, optional embedding, and MCP
annotation signals;
- evidence-backed target selection and typed prerequisite expansion;
- token-budgeted, contract-projected schemas for the model-facing catalog;
- readiness, failure, and trace metadata for application-side diagnostics;
- adapters for OpenAI, Anthropic, LangChain v1, MCP, Docker, and Kubernetes.
Authentication, tenant policy, approval, and product-specific execution remain
in the host application.
See It in 30 Seconds
No model, API key, or network call is required:
This demo runs the real retriever, deterministic target selector, typed
dependency closure, and schema admission pipeline.
Installation
The core search and graph package uses only the Python standard library.
Optional integrations are installed explicitly:
Python 3.10 through 3.14 are tested in CI.
Build and Search
OpenAPI
OpenAPI ingestion preserves request and response schemas, parameter locations,
content types, security requirements, links, examples, response envelopes, and
typed consumes/produces contracts. Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1
are supported.
Inspect a collection before exposing it to an agent:
The report contains stable readiness issue codes, semantic coverage, and edge
quality rather than a single opaque score.
Other sources
Every adapter returns normalized ToolSchema objects, capability metadata, and
structured unsupported-feature diagnostics.
Choose an Integration
| Environment | Recommended surface | What graph-tool-call owns |
| --- | --- | --- |
| Python application | ToolGraph / graphify APIs | ingest, search, evidence, dependency closure |
| OpenAI Responses or Chat Completions | patch_openai | per-request function-tool filtering |
| Anthropic Messages | patch_anthropic | per-request tool filtering |
| LangChain v1 | create_tool_selection_middleware | model-call tool selection |
| Claude Code, Cursor, Windsurf | MCP proxy | many MCP backends behind 3 gateway tools |
| OpenAI Agents, PydanticAI, Google ADK | remote MCP server | protocol-neutral search service |
| Docker or Kubernetes | Streamable HTTP MCP | private deployable service |
See the compatibility matrix
for validation boundaries. Protocol compatibility does not imply that every
framework or cloud release is tested by this repository.
OpenAI Responses