NCATS ARAX
Use ARAX as a constrained knowledge-graph lookup service. Submit reviewed CURIEs and explicit Biolink types, preserve the exact TRAPI exchange, inspect query-edge bindings and provenance, and treat every returned path as a candidate for subsequent verification.
Read query-contract.md before constructing a query. Read output-schema.md when interpreting saved artifacts, warnings, provenance, or partial results.
Safety boundary
- Use only public, nonsensitive research questions. ARAX status facilities may expose query and
caller metadata even when
store=falseis requested. - Do not submit patient information, confidential research questions, unpublished compound programs, or proprietary target hypotheses.
- Do not present a returned path as a validated mechanism or clinical recommendation.
- Report a zero as "not returned under these constraints," never as evidence that no relationship exists.
- Describe position as unscored response order, never rank.
- Verify important candidates with literature and authoritative databases separately.
Workflow
- Normalize free text separately, then review and report the proposed CURIE and category.
- Choose a typed one-hop query or an exactly two-hop query with both endpoints pinned.
- Use default RTX-KG2 lookup unless the user explicitly names two to five providers.
- Acknowledge that the biomedical query is public and choose a new or empty output directory.
- Run the client once. Do not silently change provider selection or expansion order after a failure or empty result.
- Inspect
summary.jsonfor bounded bindings and provenance andresponse.jsonfor the exact TRAPI payload. - Verify scientifically important paths outside ARAX.
Preflight
Check the production OpenAPI without making a biomedical query:
bashpython skills/ncats-arax/scripts/arax_client.py preflight
The client verifies that the service identifies itself as ARAX, exposes POST /query and
GET /entity, and reports a supported TRAPI version. It reads info.x-trapi.version, falling back
to the title for older OpenAPI documents. A nonproduction endpoint or untested TRAPI series
requires an explicit override; neither override changes the fixed query shapes or operations.
Normalize an entity
Normalization is review-only and never triggers a graph query:
bashpython skills/ncats-arax/scripts/arax_client.py normalize "ivacaftor" \ --expected-category biolink:SmallMolecule \ --max-synonyms 10 \ --acknowledge-public-query \ --output-dir outputs/normalize-ivacaftor
Review the canonical identifier, name, category, and synonym preview before using a CURIE. Report
all CURIEs and categories regardless of query outcome. A category warning or zero result is a
reason to curate the identifier, not to chain automatically to /query.
One-hop lookup
Pin at least one endpoint and type both nodes:
bashpython 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
Lookup mode is the default and fixes expansion to infores:rtx-kg2. It defaults to 20 results.
Use --result-limit N to request 1-50 results; 50 is the hard cap in either mode.
Endpoint-pinned two-hop lookup
Use exactly one typed, unpinned intermediate node:
bashpython 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
Right-first expansion is the default. If an empty result merits another attempt, run a new query
explicitly with --expand-order left-first and keep the runs separate.
Selected-provider federation
Federation is explicit and accepts two to five named providers:
bashpython 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
Federation defaults to the hard maximum of 50 results. Provider errors may coexist with useful results; such a run exits 7 after retaining its artifacts and is marked partial. The same applies to a failed provider in lookup mode. An explicit non-success ARAX response status exits 6 with the raw response retained; it must not be reported as a successful zero-result query.
Inspect saved provenance
Rebuild a bounded summary without network access:
bashpython skills/ncats-arax/scripts/arax_client.py summarize \ --request outputs/ivacaftor-cystic-fibrosis/request.json \ --response outputs/ivacaftor-cystic-fibrosis/response.json \ --format text
The inspector accepts only the same constrained request shapes and fixed operations that the live
commands generate. Use --format json for the normalized view on standard output.
Interpret results
- Follow each analysis's query-edge bindings; do not summarize every knowledge-graph edge.
- Preserve the physical edge subject, predicate, object, and qualifier values returned by ARAX. Returned predicates or qualifier aspects may be more specific than the query constraint.
- Inspect all source objects, including primary, aggregator, supporting-data, upstream-resource, and source-record URL fields.
- Trace aggregator edges to their primary/upstream sources and publications before claiming corroboration. Multiple providers can redistribute the same record; report distinct primary evidence, not provider count as confidence or independent replication.
- Treat
publication_availability: not_returnedas missing metadata, not evidence that no publications exist. - Treat missing auxiliary-graph references and provider failures as explicit warnings.
- Consult the raw response whenever the bounded summary omits detail or the service response is partial, unfamiliar, or scientifically surprising.
Deliberate exclusions
The client has no raw-query, workflow, operation, overlay, ranking, inference, link-prediction, Pathfinder, ARS, batch, all-provider, three-hop, cache, daemon, SDK, MCP, or natural-language-to-TRAPI surface. Do not work around those limits with direct HTTP calls under this skill.
Official references
Reviewed on 2026-09-30 against production ARAX 1.5.4 / TRAPI 1.5.0 (the URL still contains v1.4).
Live public smoke tests passed for preflight, normalization, qualified one-hop and endpoint-pinned
two-hop lookups, and RTX-KG2/MolePro federation. Results and provider availability can change.
The official introductory guide contains older response examples; use the deployed schema and
current ARAX source for field and operation contracts. No Python SDK is used by this client.
