ncats-arax skill (K-Dense scientific-agent-skills)

From Public Agent Wiki

What it does. Queries the NCATS Translator ARAX production API for bounded, typed, provenance-rich one-hop and endpoint-pinned two-hop biomedical knowledge-graph relationships. Use for Biolink-constrained RTX-KG2 lookup, explicit selected-provider ARAX federation, separate entity normalization, qualifier-aware graph traversal, and inspection of TRAPI edge bindings, publications, and knowledge-source provenance. Do not use for inference, ranking, open-ended pathfinding, clinical guidance, or sensitive queries. Part of K-Dense-AI/scientific-agent-skills (AI Scientist skills) (K-Dense-AI/scientific-agent-skills).
Upstream K-Dense-AI/scientific-agent-skills
Skill file skills/ncats-arax/SKILL.md
License MIT
Author K-Dense Inc.
Fetched 2026-09-10

Install

  • npx skills add K-Dense-AI/scientific-agent-skills --skill ncats-arax, or copy the skill folder into ~/.claude/skills/ncats-arax/.
  • Raw file: curl -sL https://raw.githubusercontent.com/K-Dense-AI/scientific-agent-skills/HEAD/skills/ncats-arax/SKILL.md

SKILL.md (verbatim)

name: ncats-arax
description: Queries the NCATS Translator ARAX production API for bounded, typed, provenance-rich one-hop and endpoint-pinned two-hop biomedical knowledge-graph relationships. Use for Biolink-constrained RTX-KG2 lookup, explicit selected-provider ARAX federation, separate entity normalization, qualifier-aware graph traversal, and inspection of TRAPI edge bindings, publications, and knowledge-source provenance. Do not use for inference, ranking, open-ended pathfinding, clinical guidance, or sensitive queries.
allowed-tools: Read Bash
license: MIT
compatibility: Requires Python 3.10+ and outbound HTTPS access to arax.transltr.io. The client uses only the Python standard library and needs no API key. Queries and caller metadata may be publicly visible; never submit sensitive or patient-specific content.
metadata:
  version: "1.0"
  skill-author: neuroepithelial

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=false is 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

  1. Normalize free text separately, then review and report the proposed CURIE and category.
  2. Choose a typed one-hop query or an exactly two-hop query with both endpoints pinned.
  3. Use default RTX-KG2 lookup unless the user explicitly names two to five providers.
  4. Acknowledge that the biomedical query is public and choose a new or empty output directory.
  5. Run the client once. Do not silently change provider selection or expansion order after a failure or empty result.
  6. Inspect summary.json for bounded bindings and provenance and response.json for the exact TRAPI payload.
  7. Verify scientifically important paths outside ARAX.

Preflight

Check the production OpenAPI without making a biomedical query:

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

The client verifies that the service identifies itself as ARAX, exposes /query, and reports a supported TRAPI version. 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:

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

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:

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

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:

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

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:

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

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.

Inspect saved provenance

Rebuild a bounded summary without network access:

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

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.
  • Treat publication_availability: not_returned as 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

Other files in this skill

references/output-schema.md (verbatim)

ARAX artifact and output contract

Contents

Artifact sets

Every graph query requires a new or empty output directory and writes:

request.json
response.json
summary.json
manifest.json

Normalization writes the exact entity response, a bounded normalization summary, and a manifest. Preflight writes the exact OpenAPI response, a service summary, and a manifest only when an output directory is requested. GET commands do not create a fictitious request.json; the corresponding manifest file, byte, and hash fields are null. Offline summarize writes nothing.

Reject an existing nonempty directory before network access. Write artifacts through a private temporary file, flush and fsync, set mode 0600 where supported, and atomically replace the final path. Write the manifest last.

Exact byte preservation

Serialize a POST body once with sorted keys, compact separators, UTF-8, and ensure_ascii=False. Save and send that same byte string. Request Accept-Encoding: identity, save the raw response before JSON parsing, and hash request and response bytes with SHA-256.

Read at most 26,214,401 response bytes. If the extra byte exists, treat the response as oversized, save no partial response.json, retain the request when applicable, write a terminal manifest, and exit 6. A bounded HTTP-error body is preserved exactly. A bounded malformed JSON response is also preserved, but no misleading summary is produced.

Query summary

summary.json is a normalized bounded view; response.json remains authoritative.

{
  "schema_version": "1.0",
  "query": {
    "kind": "one-hop|two-hop",
    "mode": "lookup|federated",
    "provider_ids": [],
    "expand_order": "right-first|left-first|null",
    "qnode_ids": {},
    "result_limit": 20
  },
  "service": {
    "base_url": null,
    "arax_version": null,
    "trapi_version": null,
    "biolink_version": null
  },
  "counts": {
    "results_returned": 0,
    "results_summarized": 0,
    "analyses_summarized": 0,
    "bound_edges_summarized": 0,
    "knowledge_graph_nodes": 0,
    "knowledge_graph_edges": 0,
    "server_total_results_count": null
  },
  "truncation_status": "no|possible|confirmed",
  "completeness": "complete|partial|unknown",
  "results": [],
  "warnings": []
}

Keep response order. A result contains its one-based unscored position, bounded description, normalized node bindings, and separate analyses. Each analysis contains its resource ID, returned score, support-graph IDs, and bound-edge objects grouped by query-edge key.

A bound-edge object contains the returned edge ID, physical subject/predicate/object and names, query-direction match flag, qualifiers, full source objects, role-derived source ID lists, publication IDs and availability, and support-graph IDs and status.

Normalization and preflight summaries

A normalization summary records the input, expected category, whether free-text confirmation is required, service versions, canonical identifier/name/category, category-count mapping, total synonym count, bounded candidate preview, and warnings.

A preflight summary records service versions plus Boolean checks for ARAX identity, /query, and version compatibility. Neither summary claims graph results.

Provenance interpretation

Use each analysis's edge_bindings to select knowledge-graph edges. Do not include unrelated graph edges. Preserve multiple analyses separately and retain all entries from each bound edge's sources, including resource_id, resource_role, upstream_resource_ids, and source_record_urls. Derive unique, first-seen resource ID lists for primary, aggregator, and supporting-data roles without discarding the full objects.

Preserve returned qualifiers as type/value pairs. Preserve physical edge direction and set matches_query_direction: false rather than rewriting a reversed edge.

V1 recognizes biolink:publications edge attributes. Accept a string or list of strings and deduplicate in first-seen order. Missing recognized metadata means:

publication_ids: []
publication_availability: not_returned

It never means that no publications exist.

Use analysis.support_graphs as the support-graph references. If none are returned, report not_returned; if all appear in message.auxiliary_graphs, report available; if a referenced ID is absent, report missing and warn.

Truncation and completeness

  • Fewer results than the requested limit: no, unless logs or counts show removal.
  • Exactly the limit: possible and RESULT_LIMIT_REACHED.
  • More than the limit, an explicit pruning/removal log, or a larger server total: confirmed.

Keep only the first requested number of results in the normalized summary while preserving the entire size-bounded raw response.

Federated KP timeout, provider error, or malformed-provider evidence yields completeness: partial, result_status: partial, retained artifacts, and exit 7. Otherwise a valid parsed response is complete; raw malformed responses produce no summary.

Manifest

The manifest records run UUID, UTC timestamps, command, execution/result status, privacy acknowledgment, fixed client identity, service versions, request/response method, URL, filenames, byte counts, hashes, elapsed time, applied limits, attempt counts, artifact names, bounded error, and warnings. Fields for artifacts that do not exist are null rather than false filenames.

Execution statuses are success, http_error, and client_error. Result statuses are results, no_results, partial, and not_available.

Warnings and exit codes

Warnings are objects with a stable code, bounded sanitized message, and a small scalar context. Supported codes:

PUBLIC_QUERY
NORMALIZATION_REQUIRES_CONFIRMATION
NORMALIZATION_CATEGORY_MISMATCH
NO_RESULTS
NO_PUBLICATIONS_RETURNED
NO_PRIMARY_SOURCE_RETURNED
UNSCORED_RESPONSE_ORDER
RESULT_LIMIT_REACHED
INTERNAL_PRUNING_DETECTED
KP_TIMEOUT
KP_ERROR
MALFORMED_KP_RESPONSE
MISSING_AUXILIARY_GRAPH
REVERSED_EDGE_BINDING
UNTESTED_SERVICE_VERSION
NONPRODUCTION_ENDPOINT

Exit codes:

Code Meaning
0 Complete success, including a valid zero-result graph response
2 Invalid CLI input, unsupported saved request, or local validation failure
3 Service preflight or unsupported-version failure
4 Normalization returned no usable result
5 Transport or HTTP failure
6 Malformed, oversized, or artifact-integrity failure
7 Partial federated response with retained artifacts

Text output prints at most the bounded result set and ten publication IDs per edge, labels every position unscored, includes all source-role IDs, and points to summary.json and response.json. Use "ARAX returned" and "not returned under these constraints," never proof, absence, or ranking language.

references/query-contract.md (verbatim)

ARAX query contract

Contents

Service boundary

Use https://arax.transltr.io/api/arax/v1.4 by default. A networked command first retrieves /openapi.json, verifies an ARAX title and /query, and records the advertised ARAX and TRAPI versions. Normalization uses /entity; graph lookup uses /query.

Every normalization or graph request requires --acknowledge-public-query. This is an explicit acknowledgment that query and caller metadata may be visible through service facilities. The store=false operation reduces intentional response storage but is not a privacy guarantee.

Supported query shapes

One hop

Use two qnodes (n0, n1) and one qedge (e0). Require one category on each qnode, one to five predicates, and at least one pinned endpoint. Each qnode has at most one CURIE. Omit ids from an unpinned qnode.

Two hops

Use three qnodes (n0, n1, n2) and two qedges (e0, e1). Pin n0 and n2 with exactly one CURIE each. Type every qnode. Keep n1 unpinned. Each edge has one to five predicates.

For either shape, an edge may have zero to six qualifiers. Combine them in one qualifier_constraints entry containing one AND-conjoined qualifier_set. Omit the whole field when no qualifier is supplied. Do not repeat a qualifier type on the same edge.

Validation

CURIEs follow this conservative form:

^[A-Za-z][A-Za-z0-9._-]*:[^\s]+$

They must be no more than 200 characters and contain no controls, NUL, tabs, or newlines.

Categories, predicates, and qualifier types follow:

^biolink:[A-Za-z][A-Za-z0-9._-]*$

Provider identifiers are interpolated into an ARAXi action and therefore use the stricter form:

^infores:[A-Za-z0-9._-]+$

Do not maintain a local Biolink model or provider registry. Shape validation is local; ARAX remains the semantic authority. Reject duplicate predicates, qualifier types, provider IDs, and repeated scalar endpoint options.

Fixed operations

Lookup mode fixes the provider to infores:rtx-kg2. Federated mode requires two to five explicit, distinct provider identifiers and emits them in one list-valued kp= argument. Never omit kp and never generate duplicate kp= arguments.

One hop expands e0. Two-hop right-first expands e1 and then e0; left-first reverses only those two actions. Append exactly:

scoreless_resultify(ignore_edge_direction=true)
filter_results(action=limit_number_of_results,max_results=<1-50>,prune_kg=true)
return(response=true,store=false)

Each expansion fixes:

kp_timeout=30,return_minimal_metadata=false

Always send stream_progress: false and the constant submitter scientific-agent-skills-ncats-arax. Never put a user name, project name, or query term into the submitter or User-Agent.

Limits and retries

Control Value
OpenAPI/entity HTTP timeout 30 seconds
Lookup query HTTP timeout 120 seconds
Federated query HTTP timeout 180 seconds
ARAX KP timeout 30 seconds
Lookup default result limit 20
Federated default result limit 50
Hard result limit 50
Provider count 2-5 in federation
Predicates per edge 1-5
Qualifiers per edge 0-6
Raw response limit 25 MiB (26,214,400 bytes)

Retry OpenAPI and entity GET requests once after HTTP 429, 502, 503, 504, or a transport timeout. Honor Retry-After for at most 10 seconds; otherwise wait one second. Never retry POST /query. A failed POST may have been processed and must be rerun only by an explicit user decision.

Use these headers:

Accept: application/json
Accept-Encoding: identity
Content-Type: application/json        # POST only
User-Agent: scientific-agent-skills-ncats-arax/1.0

Version and endpoint policy

The tested target is ARAX 1.5.4 with TRAPI 1.5.0. Parse the common response fields for TRAPI 1.5 and 1.6, warning whenever the version is not the tested value. Refuse an unknown or missing TRAPI series unless --allow-untested-version is explicit. Record biolink_version from each query response rather than assuming it.

Accept only HTTPS base URLs without credentials, query strings, or fragments. Reject localhost and literal private, loopback, link-local, or reserved addresses. A URL other than the production base requires --allow-nonproduction-endpoint, must still identify ARAX through OpenAPI, and receives a warning. Reject cross-origin and protocol-downgrade redirects. Never fall back automatically to arax.ncats.io or another ARA.

Excluded escape hatches

Expose no raw JSON submission, query-file, generic node/edge list, workflow, operations, action, overlay, ranking, inference, creative-query, link-prediction, Pathfinder, ARS, all-provider, batching, stdin-list, cache, database, daemon, server, SDK, MCP, or third-hop option.

The offline summarizer validates the saved request against this same topology and operation contract. It refuses unsupported requests rather than becoming a back door for broader ARAX use.

Back to K-Dense-AI/scientific-agent-skills (AI Scientist skills) or Agent skills.