O que NCATS ARAX faz?
Use o ARAX como um serviço de consulta restrito a grafos de conhecimento. Submeta CURIEs revisadas e tipos explícitos do Biolink, preserve a troca TRAPI exata, inspecione as ligações das bordas da consulta e a proveniência, e trate cada caminho retornado como candidato para verificação posterior.
Leia query-contract.md antes de construir uma consulta. Leia output-schema.md ao interpretar artefatos salvos, avisos, proveniência ou resultados parciais.
Limite de segurança
- Use apenas perguntas de pesquisa públicas e não sensíveis. As instalações de status do ARAX podem expor metadados da consulta e do chamador mesmo quando
store=falseé solicitado. - Não submeta informações de pacientes, perguntas de pesquisa confidenciais, programas de compostos não publicados ou hipóteses de alvo proprietárias.
- Não apresente um caminho retornado como um mecanismo validado ou recomendação clínica.
- Relate um zero como "não retornado sob essas restrições", nunca como evidência de que nenhuma relação existe.
- Descreva a posição como ordem de resposta não pontuada, nunca como classificação.
- Verifique candidatos importantes com literatura e bancos de dados autoritativos separadamente.
Fluxo de trabalho
- Normalize o texto livre separadamente, depois revise e relate o CURIE e a categoria propostos.
- Escolha uma consulta tipada de um salto ou uma consulta exatamente de dois saltos com ambos os endpoints fixos.
- Use a consulta padrão RTX-KG2, a menos que o usuário nomeie explicitamente dois a cinco provedores.
- Reconheça que a consulta biomédica é pública e escolha um diretório de saída novo ou vazio.
- Execute o cliente uma vez. Não altere silenciosamente a seleção de provedores ou a ordem de expansão após uma falha ou resultado vazio.
- Inspecione
summary.jsonpara ligações limitadas e proveniência, eresponse.jsonpara o payload TRAPI exato. - Verifique caminhos cientificamente importantes fora do ARAX.
Pré-verificação
Verifique a OpenAPI de produção sem fazer uma consulta biomédica:
python skills/ncats-arax/scripts/arax_client.py preflight
O cliente verifica se o serviço se identifica como ARAX, expõe /query e relata uma versão TRAPI suportada. Um endpoint não produtivo ou série TRAPI não testada requer uma substituição explícita; nenhuma substituição altera as formas ou operações de consulta fixas.
Normalizar uma entidade
A normalização é apenas para revisão e nunca dispara uma consulta de grafo:
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
Revise o identificador canônico, nome, categoria e prévia de sinônimos antes de usar um CURIE. Relate todos os CURIEs e categorias independentemente do resultado da consulta. Um aviso de categoria ou resultado zero é um motivo para selecionar o identificador, não para encadear automaticamente para /query.
Consulta de um salto
Fixe pelo menos um endpoint e digite ambos os nós:
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
O modo de consulta é o padrão e fixa a expansão para infores:rtx-kg2. Ele usa como padrão 20 resultados. Use --result-limit N para solicitar de 1 a 50 resultados; 50 é o limite máximo em qualquer modo.
Consulta de dois saltos com endpoints fixos
Use exatamente um nó intermediário tipado e não fixo:
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
Expansão à direita primeiro é o padrão. Se um resultado vazio merecer outra tentativa, execute uma nova consulta explicitamente com --expand-order left-first e mantenha as execuções separadas.
Federação com provedores selecionados
A federação é explícita e aceita de dois a cinco provedores nomeados:
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
A federação usa como padrão o máximo de 50 resultados. Erros de provedor podem coexistir com resultados úteis; tal execução sai com código 7 após reter seus artefatos e é marcada como parcial.
Inspecionar proveniência salva
Reconstrua um resumo limitado sem acesso à rede:
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
O inspetor aceita apenas as mesmas formas de consulta restritas e operações fixas que os comandos ao vivo geram. Use --format json para a visualização normalizada na saída padrão.
Interpretar resultados
- Siga as ligações das bordas da consulta de cada análise; não resuma cada borda do grafo de conhecimento.
- Preserve o sujeito, predicado, objeto e valores de qualificador da borda física retornados pelo ARAX. Predicados ou aspectos de qualificador retornados podem ser mais específicos do que a restrição da consulta.
- Inspecione todos os objetos de fonte, incluindo campos de URL de fonte primária, agregadora, dados de suporte, recurso upstream e registro de fonte.
- Trate
publication_availability: not_returnedcomo metadados ausentes, não como evidência de que não existem publicações. - Trate referências de grafo auxiliar ausentes e falhas de provedor como avisos explícitos.
- Consulte a resposta bruta sempre que o resumo limitado omitir detalhes ou a resposta do serviço for parcial, desconhecida ou cientificamente surpreendente.
Exclusões deliberadas
O cliente não possui superfície de consulta bruta, workflow, operação, sobreposição, ranqueamento, inferência, previsão de links, Pathfinder, ARS, lote, todos os provedores, três saltos, cache, daemon, SDK, MCP ou linguagem natural para TRAPI. Não contorne esses limites com chamadas HTTP diretas sob esta skill.