AI导哈

联邦支出语义分析工具

gov-gpt是一个为USAspending API提供语义分析的工具，帮助开发者理解和使用联邦支出数据。

  • by saulrichardson
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 saulrichardson/gov-gpt

使用说明

政府gpt

gov-gpt 是美国支出API的证据支持语义MCP。

该项目为编码和分析代理提供了他们需要使用的上下文 联邦支出数据：发现正确的终点，了解业务 含义、构建或修复请求、检查证据、进行范围内的实时通话， 并解释结果。

产品目标

美国的支出有许多有用的终点，而最困难的部分是转向交通 将其转化为可靠的联邦支出分析。API表面混合请求 字段、嵌套过滤器、分页、导出、地理位置、时间段、奖项、， 账户和具有商业意义的应对措施。

gov-gpt 是美国支出端点和代理之间的语义层 试图对他们进行推理。它捕获了每个端点的含义 它支持的问题，如何安全地调用它，如何从可见的API中恢复 错误，以及在解释响应时哪些注意事项很重要。

当前状态

截至2026年5月20日，存储库已围绕“清理前进”进行了调整 架构：

  • 活跃的创作工作流程存在于 scripts/agents 并使用OpenAI 代理SDK。
  • 运行时MCP位于 scripts/mcp 并公开了通用语义工具 发现、检查、请求帮助、有界调用、证据和使用 指导。
  • 升级的MCP表面目前包含一个干净的语义配置文件V2 捆绑： v2__search__spending_by_transaction.
  • 推广的捆绑包通过文档、源代码、实时探测进行验证， 并得出检查证据。
  • MCP运行时包括 usaspending.callEndpoint，这使得实际 美国在基本请求飞行前花费API调用。
  • make verify 越过当前表面。
  • 横向扩展意味着通过当前的 制片人、评论、故事和推广循环。

功能架构

flowchart LR
    A["Evidence inputs<br/>docs, source, live probes,<br/>promoted semantic bundles"]
    B["Agents SDK authoring loop<br/>producer, reviewer,<br/>repairer, story gate"]
    C["Semantic profile<br/>callable shape, business meaning,<br/>evidence, usage guidance"]
    D{"Quality gates<br/>schema checks, evidence checks,<br/>MCP story tests"}
    E["Semantic MCP runtime<br/>discovery, understanding,<br/>request help, execution"]
    F["Downstream agents<br/>answer spending questions<br/>with scoped calls and receipts"]

    A --> B
    B --> C
    C --> D
    D -->|repair needed| B
    D -->|ready| E
    E --> F

运作原理

  1. 证据来自文档、源行为、提升的语义 捆绑包和美国实时支出调查。每个来源都提供了有用的上下文， 捆绑包明确记录了置信度和不确定性。
  2. 代理SDK驱动创作循环。生产商代理调查 终点，调和矛盾，探究生活行为，并撰写 语义概况。审查员和维修代理对结果提出质疑 证据质量和下游MCP可用性的角度。
  3. 语义概要文件捕获可调用的API形状和分析 含义：端点用于什么，它可以回答什么问题 请求字段的含义、响应度量表示什么、注意事项 问题，以及哪些证据支持这些说法。
  4. 通用门检查结构、证据链接、基本请求形状、MCP 在端点特定含义保持不变的情况下 代理编写了捆绑包。
  5. 故事代理将推广的MCP用作下游用户，并报告可重用 语义学习：切换脆弱性、度量解释、仪表板 安全性、响应形状、请求构造、工作流排序，以及 运行时启示需求。
  6. 一旦配置文件准备就绪，MCP运行时就会将其作为语义公开 界面：寻找合适的能力，检查意义和证据， 构造和预处理请求，进行范围化的实时调用，并返回语义 代理人提供的执行收据。

代理SDK是生产循环。产品是经过验证的语义 知道MCP为另一个代理服务。

MCP工具

运行时公开了一个语义工具界面：

  • usaspending.findEndpoints
  • usaspending.findConcepts
  • usaspending.findWorkflows
  • usaspending.getEndpointSchema
  • usaspending.getEndpointSemantics
  • usaspending.getAnalysisPacket
  • usaspending.getRequestTemplate
  • usaspending.listRequestFields
  • usaspending.validateRequest
  • usaspending.explainValidationError
  • usaspending.callEndpoint
  • usaspending.getEvidence
  • usaspending.getUsageGuide

usaspending.callEndpoint 通过 语义端点契约。它的响应包括原始API有效负载 规范化请求、语义验证输出、语义执行收据， 以及捆绑中已知的注意事项。

MCP给代理人什么

MCP经验让下游代理在 接地方式：

  • 发现与用户意图相匹配的端点或工作流
  • 了解端点的业务目的和分析粒度
  • 查看哪些请求字段是必需的、可选的、有风险的或支持不佳的
  • 将记录的事实与观察到的事实和已知的矛盾区分开来
  • 在作用域实时API调用之前或之后生成或修复有效请求
  • 检查重大索赔的证据
  • 执行作用域调用并在上下文中解释响应
  • 接收结构化切换值、测量警告和推荐 当bundle声明这些启示时进行后续调用

语义MCP应该告诉代理字段的含义、何时使用它、 有证据支持这一点，哪些警告对分析很重要。

语义配置文件V2

每个端点配置文件都保留了另一个代理需要使用的信息 负责端点：

  • 可调用的请求和响应形状
  • 商业目的
  • 分析粮食，如奖励、交易、地理、代理、账户、， 时间段或导出作业
  • 重要度量、维度、过滤器、排序行为、分页、连接和 工作流边界
  • 实时可用性和已知故障模式
  • 文档、源代码、升级的语义包和实时之间的矛盾 行为
  • 重要索赔的证据和置信状态
  • 适用和不适用分析用途的实用指南

持久包恰好有四个文件：

endpoint.json
semantics.json
evidence.jsonl
usage.md

不确定性是概况的一部分。该系统保留了记录的事实， 观察、反驳、不可用、推断或未知，然后让未来 代理人决定何时对特定故事进行额外的调查。

运营模式

该模型具有端点理解功能。它调查、调和、调查和 解释了端点的含义。

确定性代码拥有工件契约。它验证结构，检查 证据，执行基本请求安全，加载MCP表面，并报告 当配置文件与合同不符时，明确失败。

运行时使用引导优先姿势。基本飞行前捕获通用 形状、位置、必填字段、枚举、主机和超时问题。更丰富的端点 知识存在于使用指南、警告、例子、证据、语义中 收据和可恢复的实时API错误。

正向证据来源包括文档、源代码、实时探测、， 衍生检查、审查报告和MCP故事门。编排框架 可以进化，而证据支持的语义契约仍然是 真相。

设计原则

  • 为代理使用和真实分析而构建。
  • 将证据视为产品的一部分。
  • 明确地保留不确定性。
  • 在语义包中保留端点特定的含义。
  • 在系统扩展时，首选语义指导和API错误恢复。
  • 将成功的测试电话与有用的联邦支出故事联系起来。
  • 将明确的差距、矛盾和警告转化为持久的工件。

验证

make verify

验证门运行代理SDK类型检查/测试/冒烟、MCP 类型检查/测试、升级包验证、MCP服务器冒烟和MCP客户端 烟雾。

相关 MCP