NCATS ARAX
将ARAX用作受约束的知识图谱查找服务。提交经过审核的CURIE和明确的Biolink类型，保留精确的TRAPI交换，检查查询边绑定和溯源，并将每个返回的路径视为后续验证的候选者。
在构建查询之前，请阅读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，公开 /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 显式运行新查询，并保持各次运行分离。
选定提供者联合查询
联合查询是显式的，接受两到五个命名提供者：
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返回的物理边主语、谓语、宾语和限定符值。返回的谓语或限定符方面可能比查询约束更具体。
- 检查所有源对象，包括primary、aggregator、supporting-data、upstream-resource和source-record URL字段。
- 将
publication_availability: not_returned视为缺失元数据，而非不存在出版物的证据。 - 将缺失的辅助图引用和提供者失败视为显式警告。
- 当有界摘要遗漏细节或服务响应部分、不熟悉或科学上令人惊讶时，查阅原始响应。
有意排除的功能
客户端没有原始查询、工作流、操作、叠加、排名、推断、链接预测、Pathfinder、ARS、批处理、全提供者、三跳、缓存、守护进程、SDK、MCP或自然语言到TRAPI的接口。不要在此技能下通过直接HTTP调用绕过这些限制。