NCATS ARAX
Usa ARAX como un servicio de consulta de grafos de conocimiento acotado. Envía CURIEs revisadas y tipos Biolink explícitos, preserva el intercambio TRAPI exacto, inspecciona los enlaces de aristas de consulta y la procedencia, y trata cada ruta devuelta como un candidato para verificación posterior.
Lee query-contract.md antes de construir una consulta. Lee output-schema.md al interpretar artefactos guardados, advertencias, procedencia o resultados parciales.
Límite de seguridad
- Usa solo preguntas de investigación públicas y no sensibles. Las instalaciones de estado de ARAX pueden exponer metadatos de consulta y de la persona que llama incluso cuando se solicita
store=false. - No envíes información de pacientes, preguntas de investigación confidenciales, programas de compuestos no publicados ni hipótesis de dianas propietarias.
- No presentes una ruta devuelta como un mecanismo validado o recomendación clínica.
- Informa un cero como "no devuelto bajo estas restricciones", nunca como evidencia de que no existe ninguna relación.
- Describe la posición como orden de respuesta sin puntuación, nunca como rango.
- Verifica candidatos importantes con literatura y bases de datos autorizadas por separado.
Flujo de trabajo
- Normaliza el texto libre por separado, luego revisa e informa el CURIE y la categoría propuestos.
- Elige una consulta tipada de un salto o una consulta exactamente de dos saltos con ambos extremos fijos.
- Usa la búsqueda predeterminada RTX-KG2 a menos que el usuario nombre explícitamente de dos a cinco proveedores.
- Reconoce que la consulta biomédica es pública y elige un directorio de salida nuevo o vacío.
- Ejecuta el cliente una vez. No cambies silenciosamente la selección de proveedores o el orden de expansión después de un fallo o resultado vacío.
- Inspecciona
summary.jsonpara enlaces acotados y procedencia, yresponse.jsonpara la carga útil TRAPI exacta. - Verifica rutas científicamente importantes fuera de ARAX.
Verificación previa
Comprueba la OpenAPI de producción sin realizar una consulta biomédica:
python skills/ncats-arax/scripts/arax_client.py preflight
El cliente verifica que el servicio se identifica como ARAX, expone /query e informa una versión TRAPI compatible. Un endpoint que no sea de producción o una serie TRAPI no probada requiere una anulación explícita; ninguna anulación cambia las formas de consulta u operaciones fijas.
Normalizar una entidad
La normalización es solo de revisión y nunca desencadena una 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
Revisa el identificador canónico, nombre, categoría y vista previa de sinónimos antes de usar un CURIE. Informa todos los CURIEs y categorías independientemente del resultado de la consulta. Una advertencia de categoría o un resultado cero es motivo para depurar el identificador, no para encadenar automáticamente a /query.
Consulta de un salto
Fija al menos un extremo y tipa ambos nodos:
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
El modo de búsqueda es el predeterminado y fija la expansión a infores:rtx-kg2. Por defecto devuelve 20 resultados. Usa --result-limit N para solicitar de 1 a 50 resultados; 50 es el límite máximo en ambos modos.
Consulta de dos saltos con extremos fijos
Usa exactamente un nodo intermedio tipado y no fijo:
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
La expansión derecha-primero es la predeterminada. Si un resultado vacío merece otro intento, ejecuta una nueva consulta explícitamente con --expand-order left-first y mantén las ejecuciones separadas.
Federación de proveedores seleccionados
La federación es explícita y acepta de dos a cinco proveedores nombrados:
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
La federación usa por defecto el máximo de 50 resultados. Los errores de proveedor pueden coexistir con resultados útiles; dicha ejecución termina con código 7 después de conservar sus artefactos y se marca como parcial.
Inspeccionar la procedencia guardada
Reconstruye un resumen acotado sin acceso a la red:
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
El inspector solo acepta las mismas formas de consulta restringidas y operaciones fijas que generan los comandos en vivo. Usa --format json para la vista normalizada en la salida estándar.
Interpretar resultados
- Sigue los enlaces de aristas de cada análisis; no resumas cada arista del grafo de conocimiento.
- Preserva los valores de sujeto, predicado, objeto y calificador de la arista física devueltos por ARAX. Los predicados o aspectos de calificador devueltos pueden ser más específicos que la restricción de la consulta.
- Inspecciona todos los objetos de origen, incluidos los campos de URL de fuente primaria, agregador, datos de apoyo, recurso ascendente y registro fuente.
- Trata
publication_availability: not_returnedcomo metadatos faltantes, no como evidencia de que no existen publicaciones. - Trata las referencias faltantes de gráfico auxiliar y los fallos de proveedor como advertencias explícitas.
- Consulta la respuesta sin procesar siempre que el resumen acotado omita detalles o la respuesta del servicio sea parcial, desconocida o científicamente sorprendente.
Exclusiones deliberadas
El cliente no tiene superficie de consulta sin procesar, flujo de trabajo, operación, superposición, clasificación, inferencia, predicción de enlaces, Pathfinder, ARS, lote, todos los proveedores, tres saltos, caché, daemon, SDK, MCP o lenguaje natural a TRAPI. No evites estos límites con llamadas HTTP directas bajo esta habilidad.