ncats-arax

NCATS ARAX

将 ARAX 用作受约束的知识图谱查询服务。提交经过审核的 CURIE 和明确的 Biolink 类型，保留精确的 TRAPI 交换内容，检查查询边绑定和来源，并将返回的每条路径视为有待进一步验证的候选项。

构造查询前，请阅读 query-contract.md。解读已保存的产物、警告、来源或部分结果时，请阅读 output-schema.md。

安全边界

• 仅使用公开且不敏感的研究问题。即使请求设置了 store=false，ARAX 状态设施也可能公开查询和调用方元数据。
• 请勿提交患者信息、机密研究问题、未发表的化合物项目或专有靶点假设。
• 请勿将返回的路径描述为已验证的机制或临床建议。
• 将零结果表述为“在这些约束下未返回”，绝不可将其视为不存在关联的证据。
• 将位置描述为未经评分的响应顺序，切勿称为排名。
• 另行通过文献和权威数据库验证重要候选项。

工作流

1. 单独规范化自由文本，然后审核并报告建议的 CURIE 和类别。
2. 选择带类型的单跳查询，或端点均固定的精确双跳查询。
3. 除非用户明确指定 2 至 5 个提供方，否则使用默认的 RTX-KG2 查询。
4. 确认该生物医学查询是公开的，并选择新的或空的输出目录。
5. 运行客户端一次。发生失败或结果为空后，不要悄悄更改提供方选择或扩展顺序。
6. 检查 summary.json 中有界限的绑定和来源，并检查 response.json 中精确的 TRAPI 负载。
7. 在 ARAX 之外验证具有科学重要性的路径。

预检

检查生产环境的 OpenAPI，不发起生物医学查询：

python skills/ncats-arax/scripts/arax_client.py preflight

客户端会验证服务是否标识为 ARAX、是否提供 /query，以及是否报告受支持的 TRAPI 版本。非生产环境端点或未经测试的 TRAPI 系列需要显式覆盖；这两种覆盖都不会更改固定的查询形状或操作。

规范化实体

规范化仅用于审核，不会触发图查询：

python skills/ncats-arax/scripts/arax_client.py normalize "primary myelofibrosis" \
  --expected-category biolink:Disease \
  --max-synonyms 10 \
  --acknowledge-public-query \
  --output-dir outputs/normalize-myelofibrosis

使用 CURIE 前，请审核规范标识符、名称、类别和同义词预览。无论查询结果如何，都要报告所有 CURIE 和类别。类别警告或零结果意味着应整理标识符，而不是自动继续调用 /query。

单跳查询

至少固定一个端点，并为两个节点指定类型：

python skills/ncats-arax/scripts/arax_client.py one-hop \
  --subject-id CHEBI:31690 \
  --subject-category biolink:SmallMolecule \
  --predicate biolink:affects \
  --object-id NCBIGene:25 \
  --object-category biolink:Gene \
  --qualifier biolink:object_aspect_qualifier=activity_or_abundance \
  --qualifier biolink:object_direction_qualifier=decreased \
  --acknowledge-public-query \
  --output-dir outputs/imatinib-abl1

查询模式为默认模式，并将扩展固定为 infores:rtx-kg2。默认返回 20 条结果。使用 --result-limit N 可请求 1-50 条结果；两种模式的硬性上限均为 50。

端点固定的双跳查询

使用一个且仅一个带类型、未固定的中间节点：

python skills/ncats-arax/scripts/arax_client.py two-hop \
  --subject-id CHEBI:66901 \
  --subject-category biolink:SmallMolecule \
  --predicate-1 biolink:affects \
  --intermediate-category biolink:Gene \
  --predicate-2 biolink:associated_with \
  --object-id MONDO:0009061 \
  --object-category biolink:Disease \
  --qualifier-1 biolink:object_aspect_qualifier=activity_or_abundance \
  --qualifier-1 biolink:object_direction_qualifier=increased \
  --expand-order right-first \
  --acknowledge-public-query \
  --output-dir outputs/ivacaftor-cystic-fibrosis

默认采用从右向左的扩展顺序。如果空结果值得再次尝试，请明确使用 --expand-order left-first 运行新查询，并将两次运行分开。

指定提供方的联合查询

联合查询需显式启用，并接受 2 至 5 个指定的提供方：

python skills/ncats-arax/scripts/arax_client.py one-hop \
  --subject-id CHEBI:31690 \
  --subject-category biolink:SmallMolecule \
  --predicate biolink:affects \
  --object-id NCBIGene:25 \
  --object-category biolink:Gene \
  --mode federated \
  --kp infores:rtx-kg2 \
  --kp infores:molepro \
  --acknowledge-public-query \
  --output-dir outputs/federated-imatinib-abl1

联合查询默认返回硬性上限 50 条结果。提供方报错可能与有用结果并存；此类运行会在保留产物后以退出码 7 结束，并标记为部分结果。

检查已保存的来源信息

无需联网即可重建有界限的摘要：

python skills/ncats-arax/scripts/arax_client.py summarize \
  --request outputs/ivacaftor-cystic-fibrosis/request.json \
  --response outputs/ivacaftor-cystic-fibrosis/response.json \
  --format text

检查器仅接受与实时命令生成的请求形状和固定操作相同的内容。使用 --format json 可在标准输出中获取规范化视图。

解读结果

• 遵循每项分析的查询边绑定；不要概述知识图谱中的所有边。
• 保留 ARAX 返回的物理边的主语、谓语、宾语和限定值。 返回的谓语或限定方面可能比查询约束更具体。
• 检查所有来源对象，包括主要来源、聚合来源、支持数据、上游资源 以及来源记录 URL 字段。
• 将 publication_availability: not_returned 视为元数据缺失，而非不存在 出版物的证据。
• 将缺失的辅助图引用和提供方故障视为明确警告。
• 当有限摘要省略细节，或服务响应不完整、陌生或在科学上令人惊讶时， 请查阅原始响应。

明确排除项

客户端不提供原始查询、工作流、操作、叠加、排序、推理、链接预测、 Pathfinder、ARS、批处理、所有提供方、三跳、缓存、守护进程、SDK、MCP 或 自然语言转 TRAPI 功能。请勿在此技能下通过直接 HTTP 调用绕过这些限制。

官方参考资料

• ARAX 文档
• ARAX 生产环境 OpenAPI
• ARAXi 操作文档
• Translator Reasoner API
• Biolink Model

Agent 操作流程

1. 检查环境。 确认网络访问、API 密钥（如有需要）、数据库当前的 API 文档和速率限制。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问，不要猜测。
3. 先运行小规模版本。 获取一条已知记录，并在批量查询前检查响应格式。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 确认标识符可解析、记录数量已报告，并记录数据库版本或访问日期。
6. 报告。 说明运行了哪些内容（版本、命令、参数）、检查了哪些内容，以及仍有哪些不确定之处。

如果发生这种情况	请这样做
HTTP 429 或 5xx 错误	通过退避、批量请求遵守速率限制，并如实报告部分结果。
这些说明中提到的函数、标志或端点在已安装版本中不存在	查阅已安装版本自己的文档（help()、--help、官方文档），进行调整并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明假设。

诚信规则

• 切勿伪造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请直言说明。
• 切勿编造登录号、ID 或记录；报告“未找到”。
• 将此处与版本相关的细节视为可能已过时：请根据已安装版本的官方文档确认。
• 对于需要付费、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先征求同意。