genomic-intelligence

Genomic Intelligence — DNA 配列モデル

Genomic Intelligence（GI）は、管理された GPU 上で 6 つの配列解析タスクに対して Transformer DNA 言語モデルを提供します。遺伝子シンボル、ゲノム領域、または DNA/FASTA 配列を渡すと、構造化された予測を返します — プロモーター領域、スプライス部位、エンハンサー活性、クロマチン状態、発現量（log TPM）、および de-novo 遺伝子アノテーションです。ローカルでは何も実行されません。モデルの重みも、GPU も、重い Python スタックも不要です。これは、ホストされたバージョン管理された推論 API に対するシンクライアントです。

公式ドキュメント: docs.genomicintelligence.ai · REST コントラクトは api.genomicintelligence.ai/v1/openapi.json · ホストされた MCP サーバーは https://mcp.genomicintelligence.ai/mcp

このスキルを使うべきとき

ユーザーが DNA を持っていてモデル予測を求めている場合に GI を使用します。

• ゲノム領域内のプロモーターを検出する（promoter）
• スプライスのドナー/アクセプター部位を予測する（splice）
• エンハンサー活性をスコアリングする — 発生段階およびハウスキーピング（enhancer）
• 数百のトラックにわたってクロマチン状態をアノテーションする（chromatin）
• 配列 + 細胞種コンテキストから log(TPM+1) として発現量を予測する（expression）
• 参照を必要とせず、遺伝子/トランスクリプトを de novo でアノテーションする（annotation）
• 領域内の遺伝子を検出し、それぞれの発現量を予測する（複合）

ローカルアラインメント、バリアントコーリング、ファイル I/O には適していません — それらにはローカルツール（BioPython、bcftools）を使用してください。GI は配列からのモデル推論のためのものです。

研究および開発用途。臨床または診断の判断には使用しないでください。

GI を呼び出す 2 つの方法

ホストされた MCP サーバー（キー不要、MCP ホストでは推奨）

GI は https://mcp.genomicintelligence.ai/mcp（Streamable HTTP）で MCP サーバーをホストしています。エージェントホストが MCP をサポートしている場合は、こちらを推奨します。レート制限と同時実行制限のある公開デモ層に対してキー不要で動作し、オプションの gi_ ベアラーキーでそれらの制限を引き上げられます。シーケンスハンドル（sequence_ref）を返す取得ツールと、そのハンドルを受け取る predict_* ツールを公開しているため、大きな配列がコンテキストに残りません。以下の MCP ワークフロー と references/mcp.md を参照してください。

REST API（ユニバーサル）

https://api.genomicintelligence.ai/v1 に対して requests を使ったプレーン HTTP です。REST パスは GI_API_KEY（gi_ ベアラー）を必要とします。任意のホストで、スクリプト内で、または生のエンベロープが必要な場合に使用してください。コア REST ワークフローを参照してください。

アクセスと認証

1. ホストされた MCP デモはキー不要です — 何も設定せずに試せます。
2. REST の予測およびジョブ操作にはキーが必要で、Authorization: Bearer <key> として送信します。公開の GET /v1/tasks/{task}/models ディスカバリーにはキーが不要で、ソース IP によってレート制限されます。アクセスを要求する前に、モデルのウィンドウと境界を確認してください。現在の認証コントラクトを参照してください。予測キーは [email protected] でリクエストしてください。
3. キーをハードコードしないでください。 GI_API_KEY 環境変数（または python-dotenv 経由の .env）から読み取ってください。キーをコミットしないでください。

export GI_API_KEY="gi_yourkeyhere"     # optional for MCP; required for REST
export GI_BASE_URL="https://api.genomicintelligence.ai"   # override for staging

キーは、同時実行数と分あたりの上限を持つパートナー層にスコープされます。429 は上限に達したことを意味します — バックオフして再試行するか、GI に層の引き上げを依頼してください。

6 つのタスク

各タスクはそれぞれが公開された操作であり、独自のリクエストスキーマ、独自の最小長、独自の閉じた options オブジェクトを持ちます — POST /v1/tasks/promoter/predict、/v1/tasks/splice/predict、 /v1/tasks/enhancer/predict、/v1/tasks/chromatin/predict、 /v1/tasks/annotation/predict、/v1/tasks/expression/predict。各パスはリテラル文字列であるため、何も構築する必要がなく、共有の PredictRequest スキーマもありません。ボディは {sequence, sequence_name?, model?, options?} で、{data, meta} エンベロープを返します。タスクごとに異なる点は以下のとおりです。

タスク	推奨モード	許容長	context_window_bp	備考
promoter	sync	300～500,000 bp	2,000 bp	スライディングウィンドウのプロモーター領域
splice	sync	100～500,000 bp	15,000 bp	ドナー/アクセプター部位（長コンテキストの BigBird）。鎖特異的 — 転写産物の向きを入力してください
enhancer	sync	50～500,000 bp	249 bp	dev + housekeeping スコア（DeepSTARR、Drosophila）
chromatin	sync	200～500,000 bp	1,000 bp	数百のトラック（DeepSEA）
expression	sync	9,198～500,000 bp	n/a（trained_window_bp 9,198）	log(TPM+1)。ちょうど 9,198 bp でない限り tss_index が必要で、さらに細胞種の description も必要
annotation	async	1,000～500,000 bp	n/a	de-novo 転写産物。submit + poll。200,000 bp を超える同期 JSON は 413 sync_too_large

Recommended mode はあくまで指針であり、制約ではありません — どのタスクも両方を受け付けます。同期の 200 を得るには Prefer を省略し、202 と GET /v1/tasks/jobs/{job_id} を得るには Prefer: respond-async を送信します。唯一強制される制限は操作ごとのものです。/v1/openapi.json が POST 上で x-sync-limit-bp を公開している場合、その長さを超える同期 JSON リクエストは 413 sync_too_large になります — 契約リビジョン 16 では annotation で 200,000 bp、複合ワークフローで 50,000 bp です。数値を暗記するのではなく、このフィールドを読んでください。Annotation の BED/GFF3 は、許可されたどの長さでも同期のままで、タイムアウトする可能性があります。他の 5 つの predict タスクにはハードな同期上限はありません。

最小値はレジームではなくアドミッション制御です。 下限を超えていても、 選択したモデルの bio_spec.context_window_bp より短いリクエストは受け付けられ、 スコアリングされます — コンテキストウィンドウまでパディングされたウィンドウに対してです。Enhancer はその際たる例です。下限は 50 bp ですがコンテキストウィンドウは 249 bp なので、50～248 bp はほとんどパディングに対してスコアリングされます。モデルが実際の配列を見たかどうかを知るには、GET /v1/tasks/{task}/models の context_window_bp と自分の長さを比較してください。コンテキストより長い入力は問題ありません — スキャナーは一度に 1 つの予測ウィンドウずつ進み、最後の部分的なウィンドウだけをパディングします。

下限未満および 500,000 bp の上限超過はどちらも 422 validation_failed（loc ["body","sequence"]）です。長さ超過は 413 ではありません。すべての長さは空白が除去された後に測定されるため、行折り返しされた FASTA 本文をそのまま貼り付けることができます（> ヘッダー行はそれでも英字チェックに失敗します）。

options はタスクごとに型付けされ、クローズドです（additionalProperties: false）— 未知のキーは type: "extra_forbidden" を伴うハードな 422 validation_failed となり、無視されることは決してありません:

タスク	options キー
promoter	threshold（0～1、デフォルト 0.5）
splice	threshold（0～1、デフォルト 0.5）、site_types（["donor","acceptor"] の部分集合、デフォルトは両方）
enhancer	（なし）
chromatin	threshold（0～1、デフォルト 0.5）
annotation	batch_size（1～128、デフォルト 8）、shift_coordinates、reverse_complement（デフォルト true）
expression	description — 必須、かつ唯一のキー

Prefer: respond-async は annotation だけでなく、6 つすべての predict 操作および複合操作で宣言されたヘッダーです — 非同期を参照してください。

model を省略すると、API はそのタスクのデフォルトを使用します — これが推奨される呼び出しです。デフォルトのモデル ID はここでは意図的に記載していません。デフォルトは変わり、廃止された ID はハードに失敗するため、決してハードコードしないでください。モデルを固定する場合、または非ヒトのモデル（いくつかのタスクには Drosophila、yeast、Arabidopsis のモデルがあります）を選ぶ場合は、呼び出し時に GET /v1/tasks/{task}/models（REST）または list_models（MCP）で ID を取得してください — そして決してでっち上げないでください。タスクごとの完全な出力形状は references/tasks.md にあります。

expression は 6 つの中で最も厳格です。それらの中で唯一、そのスキーマは sequence と同様に options を必須としています。それが強制する 3 つのハードルール — 違反はすべて 422 となり、何もパディングやクランプされず、オプトアウトのフラグ、ヘッダー、クエリパラメータは存在しません:

• 常に 9,198 bp の TSS 中心ウィンドウをちょうど 1 つスコアリングします — sequence[tss_index-4599 : tss_index+4599]。エンドポイント自体は 9,198～500,000 bp を受け付けますが、9,198 bp 未満は即座に拒否されます。
• 配列がちょうど 9,198 bp でない限り、tss_index は必須です。 これは空白を除去した配列に対する 0 始まりの TSS オフセットで、4599 ≤ tss_index ≤ len(sequence) − 4599 の範囲に制限されます。ちょうど 9,198 bp の場合は 4,599 がデフォルトであり、そこでの唯一の有効値です。したがって、ロークス全体（最大 500 kb）を送信してサーバーにウィンドウを切り出させることもできます — ただし、サーバーは TSS を 見つけてはくれず（それはコンポジットワークフローの役割です）、逆相補も行いません。 遺伝子センスの配列を送信してください。
• options.description — 細胞種 / アッセイの文字列（例: "K562 cells"） — は必須で、options 内で expression が受け付ける唯一のキーです。 未知のトップレベルボディフィールドも拒否されます。

注: 有効な tss_index の範囲は広いため、単に誤ったオフセット （改行を含む生の FASTA 文字数で数えた、または送信したスライスではなく ロークス開始位置を基準にした）はエラーになりません — 誤ったウィンドウに対して 自信を持って 200 を返します。レスポンスの meta.task_specific_counts.scored_window / .tss_index でアサートしてください。 送信した長さは meta.sequence_length です。スコアリングされる幅は常に 9,198、すなわち scored_window[1] - scored_window[0] です。リビジョン 16 では、 data.input には sequence_name、description、tss_index のみが含まれ、 送信した長さやスコアリングされたウィンドウは含まれません。

tss_index の 2 つの違反 —「ちょうど 9,198 bp でない限り必須」と範囲 チェック — はどちらもモデル全体のバリデータに由来するため、tss_index の下ではなく ボディレベルで表面化します。error.code == "validation_failed" でマッチし、 メッセージは表示のみに使用してください。このスキルで引用されている loc タプルは、 その形状を例示するものであり、契約の一部ではありません。スキーマに公開されておらず、 分岐の対象にしてはなりません。

配列の取得

生の 9,198 bp 文字列から始めることはほとんどありません。まず配列を取得してください:

• 遺伝子シンボルから → MCP fetch_ensembl_sequence(gene=...)；座標から → fetch_region(region=...)。どちらも公開参照配列を取得し（キー不要）、同梱の座標 カタログ、キャッシュ、UCSC、または Ensembl を使用します。返された来歴を保持してください。REST ユーザーは Ensembl REST に直接 クエリできます。（find_genes はアノテーションタスクであり、取得ツールではありません。）
• expression の場合 → ウィンドウがちょうど 9,198 bp になるよう TSS 中心のフェッチを使用します。 MCP: fetch_gene_for_expression（中心化を処理します）。そうでなければ、 より広いロークスをフェッチし、TSS を tss_index として渡してサーバーにウィンドウを 切り出させます — ただし、そのオフセットはファイル文字ではなく、空白を除去した ヌクレオチド文字列で計算してください。
• ローカル FASTA から → MCP store_inline_sequence、または REST 向けに自分でファイルを 読み取ります。（load_local_fasta はローカルデプロイにのみ存在し、ホスト型サーバーには ありません。）
• デモ配列 → MCP load_demo_sequence(name=...) はキー不要のスモークテスト用に 準備済みのハンドルを返します；name は必須です。

正確な Ensembl 呼び出しと式ウィンドウの計算については references/sequence-acquisition.md を参照してください。

コア REST ワークフロー

次のトランスポートレシピは、認証済み推論ではなく、モックレスポンスで テストされています。呼び出す前にタスクに適した seq を指定してください。予測を比較する際は、 式コンテキストの正確な文言を一貫して使用してください。

import os
import time
import requests

BASE = os.environ.get("GI_BASE_URL", "https://api.genomicintelligence.ai").rstrip("/")
HEADERS = {"Authorization": f"Bearer {os.environ['GI_API_KEY']}"}
TASKS = {"promoter", "splice", "enhancer", "chromatin", "annotation", "expression"}

def predict(task, sequence, sequence_name, model=None, options=None, tss_index=None):
    if task not in TASKS:
        raise ValueError("Unknown GI task")
    body = {"sequence": sequence, "sequence_name": sequence_name}
    if model is not None:
        body["model"] = model
    if options is not None:
        body["options"] = options
    if tss_index is not None:
        if task != "expression":
            raise ValueError("tss_index is expression-only")
        body["tss_index"] = tss_index
    r = requests.post(f"{BASE}/v1/tasks/{task}/predict", headers=HEADERS,
                      json=body, timeout=(10, 300))
    r.raise_for_status()
    if r.status_code != 200:
        raise RuntimeError(f"Unexpected prediction status {r.status_code}")
    return r.json()

# After acquiring and checking an appropriate promoter sequence:
# out = predict("promoter", seq, "TP53_region")
# print(out["meta"]["task_specific_counts"]["regions_found"])

# A validated gene-sense expression window, or longer locus with known TSS:
# out = predict("expression", locus_seq, "HBB", tss_index=tss_offset,
#               options={"description": "polyA plus RNA-seq; Homo sapiens K562"})
# assert out["meta"]["sequence_length"] == len("".join(locus_seq.split()))
# assert out["meta"]["task_specific_counts"]["scored_window"] == [tss_offset-4599, tss_offset+4599]
# print(out["data"]["prediction"]["expression_log_tpm"])

data.summary は表示用です。そのキーは契約リビジョンなしで変更される可能性があります。 計算には data および meta.task_specific_counts で宣言されたフィールドを使用してください。 タイムアウトやプロキシエラーは非 JSON ボディを持つ可能性があり、推論が決して 実行されなかったことを立証するものではありません。リクエスト ID を保持し、盲目的な POST 再送信は 避けてください。

非同期（任意のタスク、アノテーションに推奨）

6 つのタスクまたはコンポジットのいずれかで Prefer: respond-async を送信します。202 は {data: {job_id, status: "accepted", links}, meta} です。Content-Location と X-Job-Id は同じジョブを識別します。非同期は JSON のみです。テキスト形式と非同期の組み合わせは 400 になります。ポーリングの前にジョブ ID を保存してください。この上限付きポーリングの例は、 呼び出し元が処理できるように HTTP の失敗（429 や 410 を含む）を明示します：

def submit_annotation(sequence, sequence_name):
    r = requests.post(f"{BASE}/v1/tasks/annotation/predict",
                      headers={**HEADERS, "Prefer": "respond-async"},
                      json={"sequence": sequence, "sequence_name": sequence_name},
                      timeout=(10, 30))
    r.raise_for_status()
    if r.status_code != 202:
        raise RuntimeError(f"Unexpected submission status {r.status_code}")
    return r.json()["data"]["job_id"]

def wait_for_job(job_id, max_polls=120):
    if max_polls < 1:
        raise ValueError("max_polls must be positive")
    for attempt in range(max_polls):
        r = requests.get(f"{BASE}/v1/tasks/jobs/{job_id}", headers=HEADERS,
                         timeout=(10, 30))
        r.raise_for_status()  # failed job -> its underlying 4xx/5xx, not 200
        if r.status_code == 200:
            return r.json()
        if r.status_code != 202:
            raise RuntimeError(f"Unexpected polling status {r.status_code}")
        if attempt + 1 < max_polls:
            time.sleep(5)
    raise TimeoutError(f"Polling stopped; resume this job rather than resubmit: {job_id}")

# job_id = submit_annotation(seq, "TP53_region")  # persist this ID
# result = wait_for_job(job_id)
# assert result["data"]["task"] == "annotation"
# transcripts = result["data"]["transcripts"]

200 は完了です。202 には data.status と data.progress が含まれます。 不明な、または所有権のないジョブは 404、期限切れのジョブは 410 job_expired です。 結果は最後のアクティビティから 24 時間保持されると記載されています。結果は ローカルに保存してください。ジョブ一覧は最近の上限付きリストであり、ページ分割されたアーカイブではありません。

MCP ワークフロー（ハンドルベース）

MCP ホスト上では、ハンドルを取得してからそれに対して予測します。シーケンスは コンテキストに入りません：

# 1. Acquire a sequence handle (each returns data.ref, passed as sequence_ref):
load_demo_sequence(name="promoter_tp53")  # keyless smoke test; name is required
fetch_ensembl_sequence(gene="TP53", flank_bp=5000)  # include regulatory context
fetch_region(region="chr11:5,225,000-5,235,000")   # coordinates -> handle
fetch_gene_for_expression(gene="HBB")     # TSS-centred 9,198 bp handle for expression

# 2. Predict against the handle:
predict_promoter(sequence_ref=<ref>)
predict_expression(sequence_ref=<ref>, description="K562 cells")
predict_splice(sequence_ref=<ref>)        # + predict_enhancer / predict_chromatin

# 3. Annotation on MCP is `find_genes` (there is no predict_annotation).
#    It takes a handle, not a region, and runs async internally:
find_genes(sequence_ref=<ref>)            # wait=True (default) returns the result
find_genes(sequence_ref=<ref>, wait=False)  # own key only -> job_id; poll get_job(job_id)

# Acquisition returns data.ref; use that value as sequence_ref.
# Discover models with list_models(task); reference context lives in the
# gi://models, gi://docs/tasks, and gi://account MCP resources.

共有デモでは get_job、list_jobs、および切り離された wait=False が無効になっています。 そこでは wait=True を使用してください。待機タイムアウトはエラーであり、復旧可能なジョブハンドルではありません。 リソース、結果エンベロープ、有効期間については MCP の詳細 を参照してください。

コンポジット：遺伝子を見つけて、発現を予測する

「この領域にはどの遺伝子があり、それらはどのように発現しているか」に答えるには、 コンポジットを使用します：

• MCP: find_genes_and_predict_expression(sequence_ref=..., description=...) — 領域ではなくハンドルを受け取ります（先に fetch_region で取得してください）。 description は必須です。シーケンス内の遺伝子を見つけ、それぞれについて 発現予測を返します。
• REST: 1 回の呼び出し — POST /v1/workflows/find-genes-and-predict-expression、 ボディは {sequence, options} で、sequence は 1,000～500,000 bp、 options.description（細胞種 / アッセイ）は必須です。description が欠落または空の場合は 422 validation_failed になります。これはアノテーションを付け、検出された各遺伝子の TSS を中心に 9,198 bp のウィンドウを配置し（端の遺伝子を除外するのではなく、ウィンドウの半分まで N でパディングします）、遺伝子ごとに予測を返します。 meta.task_specific_counts = {genes_found, genes_predicted, genes_skipped} で、genes_predicted + genes_skipped == genes_found です。遺伝子ごとの理由は data.expression_predictions[].skip_reason にあります。50,000 bp（その x-sync-limit-bp）を超えると 強制的に非同期になります。そのサイズを超える同期リクエストは 413 sync_too_large となり、 error.details = {sequence_length, threshold} が付きます — 同じボディに Prefer: respond-async を付けて再試行してください。

API はまた、開発中の別個の VCF ワークフローを公開しています。meta.model が存在しない場合、 その出力は確立されたモデル結果ではありません。 境界付き契約の注記 を参照してください。

エラー

コード	error.code	意味	対応
400	bad_request	不正なリクエスト	ボディの形式を確認してください
401 / 403	unauthorized / forbidden	キーの欠落/無効 (REST)	GI_API_KEY を設定してください。またはキー不要の MCP デモを使用してください
404	not_found	不明なタスク (/v1/tasks/bogus/predict) または不明なジョブ	タスク名を確認してください — 認識されないタスクは 422 ではなく 404 です
413	payload_too_large	生のリクエストボディが 16 MiB 超	入力を分割してください — これはボディの上限であり、シーケンスの上限ではありません
410	job_expired	結果の保持期間が経過	保存済みの結果を復元するか、意図的に新しい処理を投入してください
413	sync_too_large	同期 JSON リクエストが操作の x-sync-limit-bp を超過 (annotation では 200,000 bp、コンポジットでは 50,000 bp)	Prefer: respond-async を付けて再試行してください
415	unsupported_format	サポートされていない format クエリ値	タスクがサポートする形式を使用してください。JSON への暗黙のフォールバックはありません
422	validation_failed	最も一般的な失敗: シーケンスがタスクの下限未満または 500,000 bp 超、発現が 9,198 bp 未満、tss_index の欠落/範囲外、options.description の欠落、または不明なボディキーや options キー。スプライス応答の上限もこれに該当	メッセージを読み、ボディを修正してください
429	rate_limited / too_many_requests	レート/同時実行数の上限	バックオフしてください (Retry-After に従う)。GI にティアの引き上げを依頼してください
5xx	internal_error / service_unavailable / model_loading / timeout	サーバーエラー	リクエスト/ジョブ ID を保存してください。バックオフしながらポーリングを再試行し、盲目的な POST の再送信は避けてください

error.code は 21 値のクローズドな列挙型です (bad_request, unauthorized, forbidden, not_found, conflict, job_expired, payload_too_large, sync_too_large, unsupported_format, validation_failed, too_many_requests, rate_limited, internal_error, timeout, insufficient_memory, model_not_found, task_not_supported_by_model, model_loading, service_unavailable, http_error, unknown)。一覧にない値は パースエラーではなく、一般的な失敗として扱ってください。

まず code で分岐し、メッセージのテキストや loc では決して分岐しないでください。 Pydantic のリクエスト 失敗は通常 details.errors を持ちますが、スプライス応答の上限は代わりに record_count、maximum_records、sequence_length、threshold を持ちます。これらは 異なるオプションの詳細形状として扱ってください。スプライスレコードが 20,000 件を超えると 422 validation_failed となり、結果が切り詰められるのではありません。しきい値を引き上げ、その 変更した解析設定を記録してください。タスクの注意事項を参照してください。

相関付けのために、error.request_id と X-Request-Id ヘッダーはどちらも API レスポンスに記載されており、成功エンベロープは meta.request_id を持ちます。ヘッダーを 最初に読むことが依然として安全な既定です。 API レスポンスは RateLimit-Limit、RateLimit-Remaining、 RateLimit-Reset、RateLimit-Policy を記載しています。429 は Retry-After を追加します。制限は バーストバケットであり、rpm ではありません。公開されている x-rate-limit-burst-divisor は 6 なので、 持続的な毎分の許容量はそのヘッダーの 6 倍です。プロキシの失敗では、これらのヘッダーや 通常の JSON エラーエンベロープが省略されることがあります。

2026-10-01 に、公開中の OpenAPI info.version 2026.09.22.2 (af902d84)、x-contract-revision: 16、および gi-mcp 0.1.0a21 に対してレビュー済みです。 コントラクトリビジョン、解決されたモデル ID、アセンブリ、鎖/TSS の 由来、オプション、および実験的な説明を結果とともに記録してください。可能な場合は、 送信した正確な塩基をハッシュ化してください。ハンドルのみの MCP 取得はプレビューを返し、 完全な塩基やチェックサムは返しません。その取得パラメーターとソース リリースのメタデータを保存し、ハッシュをでっち上げたり、バイトレベルの検証を主張したりしないでください。 レビューの証拠と限界は、公開されたディスカバリー、 ソースレビュー、およびモックされた例を、推論の検証と区別します。

リファレンスファイル

• references/tasks.md — タスクごとの出力形式、モデルレジストリ、非同期 アノテーションの契約。
• references/api-and-auth.md — REST エンドポイント、{data, meta} エンベロープ、 認証、ベース URL のオーバーライド、ティア。
• references/mcp.md — ホスト型 MCP ツールの一覧、ハンドルベースのフロー、 gi:// リソース。
• references/sequence-acquisition.md — Ensembl の取得呼び出しと 発現ウィンドウ（9,198 bp、TSS 中心）の計算（tss_index を含む）。