ncats-arax

NCATS ARAX

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

クエリを作成する前に、query-contract.md をお読みください。保存されたアーティファクト、警告、来歴、部分的な結果を解釈する際は、output-schema.md をお読みください。

安全上の境界

• 公開されている、機密性のない研究上の質問のみを使用してください。store=false を指定しても、ARAX のステータス機能にクエリや呼び出し元のメタデータが公開される場合があります。
• 患者情報、機密性のある研究上の質問、未公開の化合物プログラム、専有の標的仮説は送信しないでください。
• 返されたパスを、検証済みのメカニズムや臨床上の推奨事項として提示しないでください。
• 結果がゼロの場合は、関係が存在しない証拠とせず、「これらの制約下では返されなかった」と報告してください。
• 順序はスコア付けされていない応答順として説明し、ランキングとは表現しないでください。
• 重要な候補は、文献や信頼できるデータベースを使って別途検証してください。

ワークフロー

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 として識別されること、/query が公開されていること、サポート対象の TRAPI バージョンが報告されることを確認します。本番環境以外のエンドポイントや、未テストの TRAPI 系列を使用するには明示的なオーバーライドが必要です。いずれのオーバーライドも、固定されたクエリ形状や操作は変更しません。

エンティティの正規化

正規化は確認のみを行い、グラフクエリは実行しません。

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

CURIE を使用する前に、正規識別子、名前、カテゴリ、同義語のプレビューを確認してください。クエリの結果にかかわらず、すべての CURIE とカテゴリを報告してください。カテゴリの警告や結果がゼロの場合は、識別子を精査する理由であり、自動的に /query に連続して送信する理由ではありません。

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 となり、部分的な結果としてマークされます。

保存された来歴の確認

ネットワークに接続せず、範囲が限定されたサマリーを再構築します。

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 はメタデータの欠落として扱い、出版物が存在しないことの証拠とは見なさないでください。
• 補助グラフ参照の欠落やプロバイダーの障害は、明示的な警告として扱ってください。
• 要約で詳細が省略されている場合、またはサービスの応答が不完全、見慣れない、もしくは科学的に意外な場合は、必ず生の応答を確認してください。

意図的な対象外

このクライアントには、生クエリ、ワークフロー、操作、オーバーレイ、ランキング、推論、リンク予測、Pathfinder、ARS、バッチ、全プロバイダー、3 ホップ、キャッシュ、デーモン、SDK、MCP、または自然言語から TRAPI への変換のインターフェースはありません。このスキルのもとで直接 HTTP 呼び出しを行い、これらの制限を回避しないでください。

公式リファレンス

• ARAX のドキュメント
• ARAX 本番環境の OpenAPI
• ARAXi 操作のドキュメント
• Translator Reasoner API
• Biolink Model

エージェントの操作手順

1. 環境を確認します。 ネットワークアクセス、API キー（必要な場合）、データベースの最新の API ドキュメントとレート制限を確認します。
2. 入力を特定します。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果を左右する値は推測せず、質問してください。
3. まず小規模に実行します。 既知のレコードを 1 件取得し、一括クエリの前に応答形式を確認します。
4. 上記の手順とリファレンスを使用して、タスク全体を実行します。
5. 結果を検証します。 識別子が解決できること、レコード数が報告されていること、データベースのバージョンまたはアクセス日が記録されていることを確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を明記します。

次の状況が発生した場合	次の対応を行います
HTTP 429 または 5xx エラー	バックオフを行ってレート制限を守り、リクエストをバッチ処理し、部分的な結果は正直に報告します。
この手順に記載された関数、フラグ、またはエンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、ユーザーに伝えます。API をでっち上げてはいけません。
必須の入力、識別子、またはパラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

整合性に関するルール

• 結果、パラメーター、識別子、引用、統計を決して捏造しないでください。実行または検証できないことがあれば、率直に伝えてください。
• アクセッション番号、ID、レコードを決して捏造せず、「見つかりません」と報告してください。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認してください。
• 金銭がかかる、共有 GPU やクラウドのクォータを消費する、個人データや患者データに触れる、または取り消せない操作を行う前に、必ず確認してください。