用途
NCATS ARAX 将 ARAX 作为受限的知识图谱查询服务使用。它面向生物医学研究场景，通过 NCATS Translator ARAX 生产 API 执行有界、带类型、富含溯源信息的查询，包括一跳查询和两端点固定的两跳查询。使用者需提交经过审核的 CURIE 和明确的 Biolink 类型，保留完整的 TRAPI 交换记录，检查查询边绑定与溯源，并将每条返回路径视为需要后续验证的候选。
主要能力
- 实体规范化：将自由文本单独规范化，并审核、报告建议的 CURIE 与类别。规范化仅用于审核，不会触发图谱查询。
- 一跳查询：固定至少一个端点，并为两个节点指定类型。默认使用 infores:rtx-kg2 查找模式，默认返回 20 条结果，可通过 --result-limit 请求 1 至 50 条结果，50 为硬上限。
- 两端点固定的两跳查询：使用恰好一个带类型、未固定的中间节点。默认采用右优先扩展；若空结果值得再次尝试，可显式使用 --expand-order left-first 运行新查询，并保持两次运行相互独立。
- 选定提供方联邦查询：联邦模式为显式操作，接受 2 至 5 个指定提供方，默认使用硬上限 50 条结果。提供方错误可能与有用结果并存，此类运行在保留产物后以退出码 7 结束并标记为部分结果。
- 溯源检查：无需网络访问即可重建有界摘要，检查 summary.json 中的有界绑定与溯源，以及 response.json 中的精确 TRAPI 载荷。
- 预检：在不发起生物医学查询的情况下检查生产 OpenAPI，验证服务标识为 ARAX、暴露 /query 并报告受支持的 TRAPI 版本。
使用方式
使用前需阅读 query-contract.md 以构建查询，阅读 output-schema.md 以解释保存的产物、警告、溯源或部分结果。
预检命令：
python skills/ncats-arax/scripts/arax_client.py preflight
实体规范化示例：
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
一跳查询示例：
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
两跳查询示例：
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
联邦查询示例：
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
摘要重建示例：
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
适用场景
适用于公开、非敏感的生物医学研究问题，例如查询化合物与基因、基因与疾病之间的有界关系路径，并在后续使用文献和权威数据库独立验证重要候选。
限制
- 仅使用公开、非敏感研究问题。ARAX 状态设施即使在请求 store=false 时也可能暴露查询和调用方元数据。
- 不得提交患者信息、机密研究问题、未公开化合物项目或专有靶点假设。
- 不得将返回路径呈现为已验证机制或临床建议。
- 零结果只能报告为“在这些约束下未返回”，绝不能作为不存在关系的证据。
- 位置只能描述为未评分的响应顺序，绝不能称为排名。
- 客户端没有原始查询、工作流、操作、覆盖、排名、推理、链接预测、Pathfinder、ARS、批处理、全提供方、三跳、缓存、守护进程、SDK、MCP 或自然语言到 TRAPI 的接口；不得在本技能下通过直接 HTTP 调用绕过这些限制。
- 失败或空结果后不得静默更改提供方选择或扩展顺序。
- 类别警告或零结果是整理标识符的理由，而不是自动链接到 /query 的理由。
- 非生产端点或未测试的 TRAPI 系列需要显式覆盖；覆盖不会改变固定的查询形态或操作。
- 遇到 HTTP 429 或 5xx 错误时，应遵守速率限制并退避、批量请求，并如实报告部分结果。
- 若安装版本中缺少某函数、标志或端点，应查阅该版本自身文档并告知用户，绝不虚构 API。
- 不得编造结果、参数、标识符、引用或统计；不得虚构登录号、ID 或记录，应报告“未找到”。
- 版本特定细节可能已过时，应针对已安装版本的官方文档进行确认。
- 涉及费用、共享 GPU 或云配额、个人或患者数据、不可撤销操作时，须先询问。
官方参考
ARAX 文档、ARAX 生产 OpenAPI、ARAXi 操作文档、Translator Reasoner API、Biolink Model。