用途
NCATS ARAX 将 ARAX 作为受约束的知识图谱查询服务使用。它面向生物医学研究场景，用于在公开知识图谱中查找有界、带类型、富含溯源信息的关系路径。查询前需阅读 query-contract.md，解释保存的产物、警告、溯源或部分结果时需阅读 output-schema.md。
安全边界
仅使用公开、非敏感的研究问题。即使请求 store=false，ARAX 状态设施仍可能暴露查询和调用方元数据。不得提交患者信息、机密研究问题、未公开化合物项目或专有靶点假设。不得将返回路径呈现为已验证机制或临床建议。零结果应报告为“在这些约束下未返回”，绝不能作为不存在关系的证据。位置应描述为未评分的响应顺序，而非排名。重要候选需另行通过文献和权威数据库验证。
工作流
- 单独规范化自由文本，然后审核并报告建议的 CURIE 和类别。
- 选择带类型的一跳查询，或两个端点均固定的恰好两跳查询。
- 除非用户明确指定两到五个提供者，否则使用默认 RTX-KG2 查找。
- 确认生物医学查询是公开的，并选择新的或空的输出目录。
- 运行客户端一次。失败或空结果后，不得静默更改提供者选择或扩展顺序。
- 检查 summary.json 中的有界绑定和溯源，以及 response.json 中的确切 TRAPI 负载。
- 在 ARAX 之外验证科学上重要的路径。
预检
在不进行生物医学查询的情况下检查生产 OpenAPI：
python skills/ncats-arax/scripts/arax_client.py preflight
客户端验证服务是否标识为 ARAX、是否暴露 POST /query 和 GET /entity，并报告支持的 TRAPI 版本。它读取 info.x-trapi.version，对于较旧的 OpenAPI 文档回退到标题。非生产端点或未测试的 TRAPI 系列需要显式覆盖；两种覆盖均不改变固定的查询形状或操作。
规范化实体
规范化仅用于审核，从不触发图查询：
python skills/ncats-arax/scripts/arax_client.py normalize "ivacaftor" \
--expected-category biolink:SmallMolecule \
--max-synonyms 10 \
--acknowledge-public-query \
--output-dir outputs/normalize-ivacaftor
在使用 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 运行新查询，并保持运行分开。
选定提供者联合
联合是显式的，接受两到五个命名提供者：
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，并标记为部分。查找模式中提供者失败同样如此。显式的非成功 ARAX 响应状态退出码为 6，保留原始响应；不得将其报告为成功的零结果查询。
检查保存的溯源
无需网络访问即可重建有界摘要：
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 调用绕过这些限制。
官方参考
2026-09-30 对照生产 ARAX 1.5.4 / TRAPI 1.5.0 审核（URL 仍包含 v1.4）。预检、规范化、限定一跳和端点固定两跳查找以及 RTX-KG2/MolePro 联合的实时公开冒烟测试通过。结果和提供者可用性可能变化。官方入门指南包含较旧的响应示例；使用部署的 schema 和当前 ARAX 源获取字段和操作契约。此客户端不使用 Python SDK。
ARAX 文档
ARAX 生产 OpenAPI
ARAXi 操作文档
ARAX 查询执行和无评分结果化
Translator Reasoner API
Biolink Model