genomic-intelligence

Genomic Intelligence — DNA 序列模型

Genomic Intelligence (GI) 在托管 GPU 上通过六项序列分析任务提供 transformer DNA 语言模型服务。给它一个基因符号、一个基因组区域或一段 DNA/FASTA 序列；它会返回结构化预测结果——启动子区域、剪接位点、增强子活性、染色质状态、表达量（log TPM）以及从头基因注释。所有计算都不在本地运行：无需模型权重、无需 GPU、无需庞大的 Python 依赖栈。它是一个针对托管、带版本的推理 API 的轻量客户端。

官方文档： docs.genomicintelligence.ai · REST 契约见 api.genomicintelligence.ai/v1/openapi.json · 托管 MCP 服务位于 https://mcp.genomicintelligence.ai/mcp

何时使用此技能

当用户拥有 DNA 并希望获得模型预测时，请使用 GI：

• 查找启动子（在某个基因组区域内）（promoter）
• 预测剪接供体/受体位点（splice）
• 评估增强子活性——发育型与管家型（enhancer）
• 注释染色质状态，覆盖数百条 track（chromatin）
• 预测表达量，根据序列 + 细胞类型上下文给出 log(TPM+1)（expression）
• 从头注释基因/转录本，无需参考序列（annotation）
• 查找某个区域内的基因并预测每个基因的表达量（复合任务）

不适用于本地比对、变异检测或文件 I/O——这些请使用本地工具（BioPython、bcftools）。GI 用于基于序列的模型推理。

仅供研究与开发使用。不用于临床或诊断决策。

调用 GI 的两种方式

托管 MCP 服务（无需密钥；在 MCP 宿主上首选）

GI 在 https://mcp.genomicintelligence.ai/mcp 托管了一个 MCP 服务（Streamable HTTP）。当你的 Agent 宿主支持 MCP 时，优先使用它：它可以无需密钥访问一个受速率和并发限制的公共演示层级，可选的 gi_ bearer 密钥可提高这些限制。它提供获取类工具，返回一个序列句柄（sequence_ref），以及接收该句柄的 predict_* 工具，因此大序列不会进入上下文。请参阅下方的 MCP 工作流 和 references/mcp.md。

REST API（通用）

使用 requests 对 https://api.genomicintelligence.ai/v1 发起普通 HTTP 请求。REST 路径需要 GI_API_KEY（一个 gi_ bearer）。可在任何宿主机、脚本中使用，或在你需要原始响应封装时使用。请参阅 核心 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 提升你的层级。

六项任务

每项任务都是其自身独立发布的接口，拥有自己的请求 schema、自己的最小长度以及自己的封闭 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 schema。请求体为 {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	发育 + 管家评分（DeepSTARR，Drosophila）
chromatin	sync	200–500,000 bp	1,000 bp	数百条轨道（DeepSEA）
expression	sync	9,198–500,000 bp	不适用（trained_window_bp 9,198）	log(TPM+1)；除非恰好为 9,198 bp，否则需要 tss_index，另需细胞类型 description
annotation	async	1,000–500,000 bp	不适用	de-novo 转录本；提交 + 轮询；超过 200,000 bp 的同步 JSON 请求会返回 413 sync_too_large

Recommended mode 是建议，而非约束 —— 每个任务两种模式都接受。省略 Prefer 会得到同步 200；发送 Prefer: respond-async 会得到 202 以及 GET /v1/tasks/jobs/{job_id}。唯一强制执行的限制是按操作设定的：在 /v1/openapi.json 于某个 POST 上发布 x-sync-limit-bp 的地方，超过该长度的同步 JSON 请求会返回 413 sync_too_large —— 在 contract revision 16 中，annotation 为 200,000 bp，复合工作流为 50,000 bp。请读取该字段，而不是记住这些数字。Annotation BED/GFF3 在任何被接纳的长度下都保持同步，且可能超时；其他五个预测任务没有硬性同步上限。

最小值是准入控制，而非模式。 高于下限但短于所选模型 bio_spec.context_window_bp 的请求会被接受并评分 —— 评分时针对的是填充至上下文窗口的窗口。Enhancer 是最极端的情况：下限为 50 bp，但上下文窗口为 249 bp，因此 50–248 bp 的评分主要基于填充。请将你的长度与 GET /v1/tasks/{task}/models 返回的 context_window_bp 进行比较，以了解模型是否看到了真实序列。长于上下文的输入没有问题 —— 扫描器会一次推进一个预测窗口，仅对最后一个不完整窗口进行填充。

低于下限和超过 500,000 bp 上限的情况在 loc ["body","sequence"] 处均为 422 validation_failed；超长不是 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 —— 参见 异步。

省略 model，API 将使用该任务的默认值 —— 这是推荐的调用方式。默认模型 ID 有意不在此处记录：默认值会变化，而退役的 ID 会硬性失败，因此切勿硬编码。若要固定某个模型，或选择非人类模型（若干任务已有 Drosophila、yeast 和 Arabidopsis 模型），请在调用时通过 GET /v1/tasks/{task}/models（REST）或 list_models（MCP）发现 ID —— 并且绝不要凭空编造。每个任务的完整输出结构见 references/tasks.md。

expression 是六个中最严格的：它是其中唯一一个 schema 同时要求 options 和 sequence 的。它强制执行三条硬性规则 —— 任何违规都是 422，不会进行填充或截断，也没有退出标志、请求头或查询参数：

• 它总是恰好评分一个以 TSS 为中心的 9,198 bp 窗口 —— 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"）—— 是必填项，并且是 expression 在 options 内接受的 唯一 键。 未知的顶层请求体字段也会被拒绝。

注意：合法的 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 违规 ——“除非恰好为 9,198 bp，否则必填”和范围 检查 —— 都来自一个全模型校验器，因此它们出现在请求体层级， 而不是在 tss_index 之下。请匹配 error.code == "validation_failed"， 并仅将消息用于显示。本技能中引用的任何 loc 元组都是对该形态的 举例说明，而非契约的一部分：它未在 schema 中发布，不得据此分支。

序列获取

你很少会从原始的 9,198 bp 字符串开始。请先获取序列：

• 从基因符号 → MCP fetch_ensembl_sequence(gene=...)；从 坐标 → fetch_region(region=...)。两者都获取公共参考序列（无需密钥），使用内置的坐标 目录、缓存、UCSC 或 Ensembl；请保留返回的来源信息。REST 用户可以直接查询 Ensembl REST。（find_genes 是 注释任务，不是获取工具。）
• 对于 expression → 使用以 TSS 为中心的获取方式，使窗口恰好为 9,198 bp。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。

异步（适用于任何任务；推荐用于注释）

在六个任务中的任意一个或复合任务上发送 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： 单次调用 — 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）或未知作业	检查任务名称——无法识别的任务返回 404，而非 422
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，因此 持续每分钟配额是该头的六倍。代理失败可能省略 这些头和通常的 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} 封装、认证、base-URL 覆盖、层级。
• references/mcp.md — 托管的 MCP 工具列表、基于 handle 的流程以及 gi:// 资源。
• references/sequence-acquisition.md — Ensembl 获取调用和表达窗口（9,198 bp，以 TSS 为中心）的数学计算，包括 tss_index。