用途
graph-tool-call 是面向 LLM Agent 的工具检索与契约层。当工具目录规模很大时，仅靠语义相似度搜索可能找到目标工具（例如 refundOrder），却无法满足该操作对输入字段（例如 order_id）的依赖，而用户并未持有这些字段。此时可用的候选集还需要包含能产出该字段的操作。同时，把每个工具的 schema 都发给模型既浪费上下文，也可能降低选择质量。graph-tool-call 将检索建模为考虑调用契约的图问题，而不是扁平的相似度搜索。
主要能力
- 从 OpenAPI、GraphQL introspection、MCP tools、Python 函数和结构化工具目录进行确定性摄入。
- 混合式目标检索，结合关键词、图关系、可选嵌入以及 MCP 注解信号。
- 有证据支持的目标选择与类型化前置依赖展开。
- 面向模型的目录采用受 token 预算约束、遵循契约投影的 schema。
- 提供就绪状态、失败信息与 trace 元数据，供应用侧诊断使用。
- 适配 OpenAI、Anthropic、LangChain v1、MCP、Docker 与 Kubernetes。
- 认证、租户策略、审批与产品特定的执行逻辑仍归属于宿主应用。
使用方式
项目提供“30 秒体验”演示，无需模型、API key 或网络调用即可运行真实的检索器、确定性目标选择器、类型化依赖闭包与 schema 准入流水线。
核心搜索与图包仅使用 Python 标准库，可选集成需显式安装；CI 中测试的 Python 版本为 3.10 至 3.14。
摄入 OpenAPI 时会保留请求与响应 schema、参数位置、内容类型、安全要求、links、examples、响应封装以及类型化的 consumes / produces 契约，支持 Swagger 2.0、OpenAPI 3.0 与 OpenAPI 3.1。
在把工具集合暴露给 agent 之前，可先检查其就绪状态；报告提供稳定的就绪问题代码、语义覆盖情况与边质量，而不是单一的不透明评分。每个适配器都返回归一化的 ToolSchema 对象、能力元数据以及结构化“不支持特性”诊断。
OpenAI Responses 中托管工具（例如 web search）会原样透传，同一补丁保留对旧版 Chat Completions 的支持。中间件会与更早的权限或功能开关中间件所允许的工具取交集，不会重新引入已被过滤的工具。MCP 端点为 /mcp，HTTP 部署还暴露 /healthz 与 /readyz，远程端点应保持私有或置于带认证的网关之后。代理接受本地 stdio、SSE 与 Streamable HTTP 后端；在网关模式下暴露 search_tools、get_tool_schema、call_backend_tool，并在匹配的后端工具变为可见时通知具备相应能力的客户端。
可复现证据
版本发布的核心指标刻意不依赖模型，且小到足以在 CI 中重放。在七个精心挑选的电商案例上，对同一已选目标增加类型化生产者展开后产生了相应效果；v0.47.0 的案例级产物记录了 fixture 哈希、每个预期目标与生产者以及重放命令。另有可观测性产物用于检查：追踪不会改变引擎输入、可确定性重放、会清洗密钥、解释每项决策，并且保持在文档所述 5ms/span 的 p95 采集成本门槛之下。项目说明该结果属于引擎回归套件，并非对 LLM 工具调用准确率的总体估计，也不构成 state-of-the-art 声明；更大规模的外部对比、模型循环实验、置信区间与已知弱例在 Benchmark Results 与论文协议中报告。
适用场景
适合需要让 LLM Agent 在大型工具目录（OpenAPI、MCP、GraphQL、Python 函数等来源）中稳定找到目标工具及其依赖工具，并希望控制发送给模型的 schema 体积与 token 成本的场景。
限制
graph-tool-call 只负责检索与契约层，生产适配器仍需自行负责用户与服务认证、租户授权与审批策略、下游密钥与 cookie 处理、副作用确认、清理与审计留存、提供商与模型生命周期以及最终响应策略。不应在 graph 产物、工具描述、trace 记录或模型可见参数中存储原始凭据。
