Inteligência Genômica

Inteligência Genômica — Modelos de Sequência de DNA

A Inteligência Genômica (GI) serve modelos de linguagem de DNA baseados em transformers para seis tarefas de análise de sequência em GPUs gerenciadas. Forneça um símbolo de gene, uma região genômica ou uma sequência de DNA/FASTA; ela retorna previsões estruturadas — regiões promotoras, sítios de splicing, atividade de enhancers, estado da cromatina, expressão (log TPM) e anotação de genes de novo. Nada é executado localmente: sem pesos de modelo, sem GPU, sem pilha Python pesada. É um cliente leve sobre uma API de inferência hospedada e versionada.

Documentação oficial: docs.genomicintelligence.ai · Contrato REST em api.genomicintelligence.ai/v1/openapi.json · Servidor MCP hospedado em https://mcp.genomicintelligence.ai/mcp

Quando usar esta skill

Use GI quando o usuário tiver DNA e quiser uma previsão de modelo:

• Encontrar promotores em uma região genômica (promoter)
• Prever sítios de splicing doadores/aceitadores (splice)
• Pontuar atividade de enhancer — desenvolvimento e housekeeping (enhancer)
• Anotar estado da cromatina em centenas de tracks (chromatin)
• Prever expressão como log(TPM+1) a partir de uma sequência + contexto de tipo celular (expression)
• Anotar genes/transcritos de novo, sem referência (annotation)
• Encontrar os genes em uma região e prever a expressão de cada um (composto)

Não é para alinhamento local, chamada de variantes ou E/S de arquivo — use uma ferramenta local (BioPython, bcftools) para esses casos. GI é para inferência de modelo a partir de sequência.

Uso para pesquisa e desenvolvimento. Não é para decisões clínicas ou diagnósticas.

Duas maneiras de chamar GI

Servidor MCP hospedado (sem chave; preferido em hosts MCP)

O GI hospeda um servidor MCP em https://mcp.genomicintelligence.ai/mcp (HTTP Streamable). Quando seu host de agente suporta MCP, prefira-o: funciona sem chave contra um nível de demonstração pública com limite de taxa e concorrência, e uma chave de portador gi_ opcional aumenta esses limites. Ele expõe ferramentas de aquisição que retornam um handle de sequência (sequence_ref) e ferramentas predict_* que recebem esse handle, mantendo sequências grandes fora do contexto. Veja Fluxo de trabalho MCP abaixo e references/mcp.md.

API REST (universal)

HTTP simples com requests contra https://api.genomicintelligence.ai/v1. O caminho REST requer uma GI_API_KEY (um portador gi_). Use-a em qualquer host, em scripts ou quando precisar do envelope bruto. Veja Fluxo de trabalho REST principal.

Acesso e autenticação

1. A demonstração MCP hospedada é sem chave — teste-a sem configurar nada.
2. A API REST /v1 precisa de uma chave, enviada como Authorization: Bearer <chave>. Solicite uma em [email protected].
3. Nunca codifique a chave. Leia-a da variável de ambiente GI_API_KEY (ou um .env via python-dotenv). Nunca confirme chaves.

export GI_API_KEY="gi_yourkeyhere"     # opcional para MCP; obrigatório para REST
export GI_BASE_URL="https://api.genomicintelligence.ai"   # substituir para staging

As chaves são escopadas para um nível de parceiro com limites de concorrência e por minuto. Um 429 significa que você atingiu um limite — aguarde e tente novamente, ou peça ao GI para aumentar seu nível.

As seis tarefas

Cada tarefa é sua própria operação publicada com seu próprio esquema de solicitação, seu próprio comprimento mínimo e seu próprio objeto options fechado — 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. Cada caminho é uma string literal, então nada precisa ser construído, e não há esquema PredictRequest compartilhado. O corpo é {sequence, sequence_name?, model?, options?}, retornando um envelope {data, meta}. O que difere por tarefa:

Tarefa	Modo recomendado	Comprimento aceito	context_window_bp	Notas
promoter	síncrono	300–500.000 pb	2.000 pb	regiões promotoras de janela deslizante
splice	síncrono	100–500.000 pb	15.000 pb	sítios doador/aceitador (BigBird de contexto longo); específico da fita — forneça a orientação do transcrito
enhancer	síncrono	50–500.000 pb	249 pb	pontuações de desenvolvimento + housekeeping (DeepSTARR, Drosophila)
chromatin	síncrono	200–500.000 pb	1.000 pb	centenas de tracks (DeepSEA)
expression	síncrono	9.198–500.000 pb	n/a (trained_window_bp 9.198)	log(TPM+1); precisa de tss_index a menos que tenha exatamente 9.198 pb, mais uma description de tipo celular
annotation	assíncrono	1.000–500.000 pb	n/a	transcritos de novo; enviar + consultar; síncrono acima de 200.000 pb é 413 sync_too_large

Modo recomendado é orientação, não uma restrição — toda tarefa aceita ambos. Omita Prefer para um 200 síncrono; envie Prefer: respond-async para um 202 mais GET /v1/tasks/jobs/{job_id}. O único limite imposto é por operação: onde /v1/openapi.json publica x-sync-limit-bp em um POST, uma solicitação síncrona acima desse comprimento é 413 sync_too_large — 200.000 pb em annotation e 50.000 pb no fluxo de trabalho composto a partir de info.version 2026.09.10.1. Leia o campo em vez de memorizar os números; as outras tarefas de previsão não carregam limite hoje.

O mínimo é controle de admissão, não regime. Uma solicitação acima do piso, mas mais curta que o bio_spec.context_window_bp do modelo selecionado é aceita e pontuada — contra uma janela preenchida até a janela de contexto. Enhancer é o caso crítico: o piso é 50 pb, mas a janela de contexto é 249 pb, então 50–248 pb é pontuado principalmente em preenchimento. Compare seu comprimento com context_window_bp de GET /v1/tasks/{task}/models para saber se o modelo viu a sequência real. Entrada mais longa que o contexto é aceitável — o scanner avança uma janela de previsão por vez e preenche apenas a janela parcial final.

Abaixo do piso e acima do limite de 500.000 pb são ambos 422 validation_failed em loc ["body","sequence"]; comprimento excessivo não é um 413. Todos os comprimentos são medidos após a remoção de espaços em branco, então um corpo FASTA com quebra de linha pode ser colado literalmente (uma linha de cabeçalho > ainda falha na verificação do alfabeto).

options é tipado e fechado (additionalProperties: false) por tarefa — uma chave desconhecida é um erro 422 validation_failed com type: "extra_forbidden", nunca ignorado:

Tarefa	Chaves options
promoter	threshold (0–1, padrão 0.5)
splice	threshold (0–1, padrão 0.5), site_types (subconjunto de ["donor","acceptor"], padrão ambos)
enhancer	(nenhum)
chromatin	threshold (0–1, padrão 0.5)
annotation	batch_size (1–128, padrão 8), shift_coordinates, reverse_complement (padrão true)
expression	description — obrigatório, e a única chave

Prefer: respond-async é um cabeçalho declarado em todas as seis operações de previsão e no composto, não apenas em annotation — veja Assíncrono.

Omita model e a API usará o padrão da tarefa — essa é a chamada recomendada. Os IDs de modelo padrão são intencionalmente não documentados aqui: os padrões mudam e IDs obsoletos falham, então nunca codifique um. Para fixar um modelo, ou para escolher um não humano (modelos de Drosophila, levedura e Arabidopsis existem para várias tarefas), descubra IDs no momento da chamada com GET /v1/tasks/{task}/models (REST) ou list_models (MCP) — e nunca invente um. Formas completas de saída por tarefa estão em references/tasks.md.

expression é a mais restritiva das seis: sozinha entre elas seu esquema requer options assim como sequence. Três regras rígidas que impõe — toda violação é um 422, nada é preenchido ou fixado, e não há flag de exclusão, cabeçalho ou parâmetro de consulta:

• Sempre pontua exatamente uma janela de 9.198 pb centrada no TSS — sequence[tss_index-4599 : tss_index+4599]. O endpoint em si aceita 9.198–500.000 pb; qualquer coisa abaixo de 9.198 pb é rejeitada imediatamente.
• tss_index é obrigatório a menos que a sequência tenha exatamente 9.198 pb. É o deslocamento TSS baseado em 0 na sequência sem espaços em branco, limitado por 4599 ≤ tss_index ≤ len(sequence) − 4599. Com exatamente 9.198 pb, o padrão é 4.599, o único valor legal ali. Portanto, você pode enviar um locus inteiro (até 500 kb) e deixar o servidor cortar a janela — mas o servidor não descobre o TSS para você (essa é a função do fluxo de trabalho composto), e não faz complemento reverso: envie a sequência no sentido do gene.
• options.description — uma string de tipo celular/ensaio (por exemplo, "K562 cells") — é obrigatória, e é a única chave que expression aceita dentro de options. Campos de corpo de nível superior desconhecidos também são rejeitados.

Nota: o intervalo legal de tss_index é amplo, então um deslocamento que é meramente errado (contado sobre caracteres FASTA brutos incluindo quebras de linha, ou relativo a um início de locus em vez da fatia enviada) não gera erro — ele retorna um 200 confiante para a janela errada. Verifique meta.task_specific_counts.scored_window / .tss_index na resposta. O comprimento que você enviou é meta.sequence_length (também ecoado como data.input.submitted_sequence_length); a largura pontuada é sempre 9.198, ou seja, scored_window[1] - scored_window[0]. (data.input.sequence_length foi removido na revisão 13 do contrato.)

Ambas as violações de tss_index — "obrigatório a menos que exatamente 9.198 pb" e a verificação de intervalo — vêm de um validador de modelo inteiro, então elas aparecem no nível do corpo em vez de sob tss_index. Corresponda a error.code == "validation_failed" e use a mensagem apenas para exibição. Qualquer tupla loc citada nesta skill é ilustrativa dessa forma, não parte do contrato: não está publicada no esquema e não deve ser usada para ramificação.

Aquisição de sequência

Raramente você começa com uma string bruta de 9.198 pb. Adquira a sequência primeiro:

• De um símbolo de gene → MCP fetch_ensembl_sequence(gene=...); de coordenadas → fetch_region(region=...). Ambos buscam sequência de referência Ensembl pública (sem chave). Usuários REST podem consultar o Ensembl REST diretamente. (find_genes é a tarefa de anotação, não uma ferramenta de aquisição.)
• Para expression → use a busca centrada no TSS para que a janela tenha exatamente 9.198 pb. MCP: fetch_gene_for_expression (lida com a centralização). Caso contrário, busque um locus mais amplo e passe o TSS como tss_index para que o servidor corte a janela — mas calcule esse deslocamento na string de nucleotídeos sem espaços, não nos caracteres do arquivo.
• De um FASTA local → MCP store_inline_sequence, ou leia o arquivo você mesmo para REST. (load_local_fasta existe apenas em implantações locais, não no servidor hospedado.)
• Uma sequência de demonstração → MCP load_demo_sequence(name=...) retorna um handle pronto para um teste sem chave; name é obrigatório.

Veja references/sequence-acquisition.md para as chamadas exatas do Ensembl e a matemática da janela de expressão.

Fluxo de trabalho REST principal

Chamado de forma síncrona — o padrão para toda tarefa — uma previsão é uma chamada:

import os, requests

BASE = os.environ.get("GI_BASE_URL", "https://api.genomicintelligence.ai")
HEADERS = {"Authorization": f"Bearer {os.environ['GI_API_KEY']}"}

def predict(task, sequence, sequence_name, model=None, options=None, tss_index=None):
    body = {"sequence": sequence, "sequence_name": sequence_name}
    if model:   body["model"] = model
    if options: body["options"] = options
    if tss_index is not None: body["tss_index"] = tss_index   # apenas expression
    # Cada tarefa é sua própria operação publicada, mas a string URL não muda.
    r = requests.post(f"{BASE}/v1/tasks/{task}/predict", headers=HEADERS, json=body)
    # 422 validation_failed  — sequência abaixo do piso da tarefa OU acima de 500.000 pb,
    #                          tss_index inválido, options.description ausente,
    #                          ou QUALQUER chave de corpo/options desconhecida (options é fechado)
    # 401 sem chave/chave inválida · 404 tarefa desconhecida · 413 corpo acima de 16 MiB · 429 limite de taxa
    r.raise_for_status()
    return r.json()               # {"data": {...}, "meta": {...}}

# Promotor:
out = predict("promoter", seq, "TP53_region")
print(out["data"]["summary"])

# Expressão — uma janela pré-cortada de 9.198 pb centrada no TSS (tss_index padrão 4.599):
out = predict("expression", tss_window_9198bp, "HBB",
              options={"description": "K562 cells"})
print(out["data"]["prediction"]["expression_log_tpm"])

# Expressão — um locus inteiro; o servidor corta ±4.599 pb ao redor do TSS que você nomeia.
# tss_index é baseado em 0 na sequência sem espaços em branco.
out = predict("expression", locus_seq, "HBB",
              options={"description": "K562 cells"}, tss_index=tss_offset_in_locus)
print(out["meta"]["task_specific_counts"]["scored_window"])   # confirme a janela pontuada

Assíncrono (qualquer tarefa; recomendado para annotation)

Prefer: respond-async é um parâmetro de cabeçalho declarado em todas as seis operações de previsão e no composto. Um 202 carrega o mesmo envelope {data, meta} que um 200 síncrono, com data = {job_id, status: "accepted", links}; o ID do trabalho também está nos cabeçalhos de resposta Content-Location e X-Job-Id. Assíncrono é apenas JSON — combiná-lo com um formato de texto é rejeitado. annotation é a tarefa que precisa disso:

import time

r = requests.post(f"{BASE}/v1/tasks/annotation/predict",
                  headers={**HEADERS, "Prefer": "respond-async"},
                  json={"sequence": seq, "sequence_name": "TP53"})
r.raise_for_status()              # 202 Accepted
job_id = r.json()["data"]["job_id"]

while True:
    j = requests.get(f"{BASE}/v1/tasks/jobs/{job_id}", headers=HEADERS)
    if j.status_code == 200:      # terminal: corpo é o {data, meta} final
        break
    j.raise_for_status()          # 202 = ainda executando (2xx, não gerará exceção)
    time.sleep(5)                 # ~20 s típico para ~20 kb
transcripts = j.json()["data"]["transcripts"]

Fluxo de trabalho MCP (baseado em handle)

Em um host MCP, adquira um handle e preveja contra ele — as sequências ficam fora do contexto:

# 1. Adquira um handle de sequência (cada um retorna um sequence_ref):
load_demo_sequence(name="promoter_tp53")  # teste sem chave

[truncado para tradução]