ncats-arax

NCATS ARAX

ARAX を制約付きナレッジグラフ検索サービスとして使用します。レビュー済みの CURIE と明示的な Biolink 型を送信し、TRAPI の交換内容をそのまま保持し、クエリエッジのバインディングと来歴を確認し、 返されたすべてのパスを後続の検証対象の候補として扱います。

クエリを構築する前に query-contract.md をお読みください。保存された 成果物、警告、来歴、または部分的な結果を解釈する場合は output-schema.md をお読みください。

安全境界

• 公開された機密性のない研究上の問いのみを使用してください。ARAX のステータス機能は、store=false を 要求した場合でも、クエリと呼び出し元のメタデータを公開する可能性があります。
• 患者情報、機密の研究上の問い、未公開の化合物プログラム、または独自の標的仮説を送信しないでください。
• 返されたパスを検証済みのメカニズムや臨床的推奨として提示しないでください。
• ゼロ件は「これらの制約下では返されなかった」と報告し、関係が存在しない証拠として決して扱わないでください。
• 位置はスコアリングされていない応答順序として説明し、決して順位として扱わないでください。
• 重要な候補は、文献と権威あるデータベースで別途検証してください。

ワークフロー

1. 自由テキストを別途正規化し、その後、提案された CURIE とカテゴリをレビューして報告します。
2. 型付きの 1 ホップクエリ、または両端点を固定した厳密に 2 ホップのクエリを選択します。
3. ユーザーが 2 ～ 5 個のプロバイダーを明示的に指定しない限り、デフォルトの RTX-KG2 検索を使用します。
4. その生物医学的クエリが公開されることを認識し、新規または空の出力ディレクトリを選択します。
5. クライアントを 1 回実行します。失敗または空の結果の後で、プロバイダーの選択や展開順序を暗黙に変更しないでください。
6. 制約付きバインディングと来歴については summary.json を、正確な TRAPI ペイロードについては response.json を確認します。
7. 科学的に重要なパスは ARAX の外部で検証します。

プリフライト

生物医学的クエリを実行せずに、本番環境の OpenAPI を確認します:

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

クライアントは、サービスが自身を ARAX として識別し、POST /query と GET /entity を公開し、 サポートされている TRAPI バージョンを報告することを検証します。info.x-trapi.version を読み取り、 古い OpenAPI ドキュメントの場合はタイトルにフォールバックします。非本番環境のエンドポイントまたは 未検証の TRAPI シリーズには明示的なオーバーライドが必要です。どちらのオーバーライドも、固定された クエリ形状や操作を変更しません。

エンティティの正規化

正規化はレビュー専用であり、グラフクエリを決してトリガーしません:

python skills/ncats-arax/scripts/arax_client.py normalize "ivacaftor" \
  --expected-category biolink:SmallMolecule \
  --max-synonyms 10 \
  --acknowledge-public-query \
  --output-dir outputs/normalize-ivacaftor

CURIE を使用する前に、正規の識別子、名前、カテゴリ、および同義語プレビューをレビューします。 クエリの結果にかかわらず、すべての CURIE とカテゴリを報告します。カテゴリの警告またはゼロ件の結果は、 識別子をキュレーションする理由であり、自動的に /query にチェーンする理由ではありません。

1 ホップ検索

少なくとも 1 つの端点を固定し、両方のノードに型を付けます:

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 がどちらのモードでもハード上限です。

端点固定の 2 ホップ検索

型付きで固定されていない中間ノードを厳密に 1 つ使用します:

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 を 指定して新しいクエリを明示的に実行し、実行を分けて保持します。

選択プロバイダーのフェデレーション

フェデレーションは明示的で、2 ～ 5 個の指定されたプロバイダーを受け付けます:

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 で終了し、部分的として マークされます。同じことは検索モードでのプロバイダーの失敗にも当てはまります。明示的な非成功の ARAX 応答ステータスは、生の応答を保持したまま終了コード 6 で終了します。これは成功したゼロ件のクエリとして 報告してはなりません。

保存された来歴の確認

ネットワークアクセスなしで制約付きサマリーを再構築します:

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 から返された物理的なエッジの主語、述語、目的語、および修飾子の値を保持してください。 返された述語やクエリの側面は、クエリ制約よりも具体的である場合があります。
• プライマリ、アグリゲーター、サポートデータ、上流リソース、 ソースレコード URL フィールドを含む、すべてのソースオブジェクトを検査してください。
• 裏付けを主張する前に、アグリゲーターエッジをそのプライマリ/上流ソースおよび出版物まで追跡してください。複数のプロバイダーが同じレコードを再配布する可能性があります。信頼度や独立した複製としてのプロバイダー数ではなく、プライマリエビデンスを報告してください。
• publication_availability: not_returned は、メタデータの欠落として扱い、出版物が存在しない証拠として扱わないでください。
• 補助グラフの参照の欠落およびプロバイダーの失敗は、明示的な警告として扱ってください。
• 制限付きサマリーが詳細を省略している場合、またはサービス応答が部分的、不慣れ、もしくは驚くべきものである場合は、常に生の応答を参照してください。

意図的な除外

このクライアントには、raw-query、ワークフロー、operation、overlay、ランキング、推論、リンク予測、 Pathfinder、ARS、バッチ、all-provider、three-hop、キャッシュ、デーモン、SDK、MCP、または natural-language-to-TRAPI サーフェスはありません。このスキルの下で直接 HTTP 呼び出しによってこれらの制限を回避しないでください。

公式リファレンス

2026-09-30 に、本番環境の ARAX 1.5.4 / TRAPI 1.5.0 に対してレビュー済みです（URL には依然として v1.4 が含まれています）。 事前チェック、正規化、修飾された 1 ホップおよびエンドポイント 2 ホップの検索、ならびに RTX-KG2/MolePro フェデレーションについて、公開のライブスモークテストに合格しました。結果およびプロバイダーの可用性は変更される可能性があります。 公式の入門ガイドには古い応答例が含まれています。フィールドおよび操作の契約については、デプロイされたスキーマと現在の ARAX ソースを使用してください。このクライアントでは Python は使用されていません。

• ARAX ドキュメント
• ARAX 本番 OpenAPI
• ARAXi 操作ドキュメント
• ARAX クエリ実行とスコアレス結果化
• Translator Reasoner API
• Biolink Model