inteligencia-genómica

Inteligencia Genómica — Modelos de Secuencia de ADN

La Inteligencia Genómica (IG) sirve modelos de lenguaje transformer de ADN en seis tareas de análisis de secuencias en GPU gestionadas. Proporciona un símbolo génico, una región genómica o una secuencia de ADN/FASTA; devuelve predicciones estructuradas: regiones promotoras, sitios de corte y empalme, actividad potenciadora, estado de la cromatina, expresión (log TPM) y anotación de genes de novo. No se ejecuta nada localmente: no hay pesos de modelo, ni GPU, ni una pesada pila de Python. Es un cliente ligero sobre una API de inferencia alojada y versionada.

Documentación oficial: docs.genomicintelligence.ai · Contrato REST en api.genomicintelligence.ai/v1/openapi.json · Servidor MCP alojado en https://mcp.genomicintelligence.ai/mcp

Cuándo usar esta habilidad

Usa IG cuando el usuario tenga ADN y quiera una predicción del modelo:

• Encontrar promotores en una región genómica (promotor)
• Predecir sitios de corte y empalme donante/aceptor (splice)
• Puntuar la actividad potenciadora — de desarrollo y de mantenimiento (potenciador)
• Anotar el estado de la cromatina en cientos de pistas (cromatina)
• Predecir la expresión como log(TPM+1) a partir de una secuencia + contexto de tipo celular (expresión)
• Anotar genes/transcripciones de novo, sin referencia necesaria (anotación)
• Encontrar los genes en una región y predecir la expresión de cada uno (compuesto)

No es para alineación local, llamada de variantes o E/S de archivos — usa una herramienta local (BioPython, bcftools) para eso. IG es para inferencia de modelo a partir de secuencia.

Investigación y desarrollo. No es para decisiones clínicas o de diagnóstico.

Dos formas de llamar a IG

Servidor MCP alojado (sin clave; preferido en hosts MCP)

IG aloja un servidor MCP en https://mcp.genomicintelligence.ai/mcp (HTTP Streamable). Cuando tu host agente soporte MCP, prefíerelo: funciona sin clave contra un nivel de demostración pública con límites de tasa y concurrencia, y una clave portadora gi_ opcional eleva esos límites. Expone herramientas de adquisición que devuelven un identificador de secuencia (sequence_ref) y herramientas predict_* que toman ese identificador, manteniendo las secuencias grandes fuera del contexto. Ver Flujo de trabajo MCP a continuación y references/mcp.md.

API REST (universal)

HTTP simple con requests contra https://api.genomicintelligence.ai/v1. La ruta REST requiere una GI_API_KEY (una gi_ portadora). Úsala en cualquier host, en scripts, o cuando necesites el envoltorio sin procesar. Ver Flujo de trabajo REST principal.

Acceso y autenticación

1. La demostración MCP alojada es sin clave — pruébala sin nada configurado.
2. La API REST /v1 necesita una clave, enviada como Authorization: Bearer <clave>. Solicita una en [email protected].
3. Nunca codifiques la clave. Lée de la variable de entorno GI_API_KEY (o un .env mediante python-dotenv). Nunca confirmes claves.

export GI_API_KEY="gi_tuclaveaqui"     # opcional para MCP; requerida para REST
export GI_BASE_URL="https://api.genomicintelligence.ai"   # anulación para staging

Las claves están limitadas a un nivel de socio con límites de concurrencia y por minuto. Un 429 significa que has alcanzado un límite — retrocede y reintenta, o pide a IG que aumente tu nivel.

Las seis tareas

Cada tarea es su propia operación publicada con su propio esquema de solicitud, su propia longitud mínima y su propio objeto options cerrado — 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 ruta es una cadena literal, por lo que no es necesario construir nada, y no hay un esquema PredictRequest compartido. El cuerpo es {sequence, sequence_name?, model?, options?}, devolviendo un envoltorio {data, meta}. Lo que difiere por tarea:

Tarea	Modo recomendado	Longitud aceptada	context_window_bp	Notas
promoter	síncrono	300–500.000 pb	2.000 pb	regiones promotoras de ventana deslizante
splice	síncrono	100–500.000 pb	15.000 pb	sitios donante/aceptor (BigBird de contexto largo); específico de hebra — alimentar orientación de transcripción
enhancer	síncrono	50–500.000 pb	249 pb	puntuaciones de desarrollo + mantenimiento (DeepSTARR, Drosophila)
chromatin	síncrono	200–500.000 pb	1.000 pb	cientos de pistas (DeepSEA)
expression	síncrono	9.198–500.000 pb	n/a (trained_window_bp 9.198)	log(TPM+1); necesita tss_index a menos que tenga exactamente 9.198 pb, más una description de tipo celular
annotation	asíncrono	1.000–500.000 pb	n/a	transcripciones de novo; enviar + sondear; síncrono por encima de 200.000 pb es 413 sync_too_large

Modo recomendado es una guía, no una restricción — cada tarea acepta ambos. Omite Prefer para un 200 síncrono; envía Prefer: respond-async para un 202 más GET /v1/tasks/jobs/{job_id}. El único límite impuesto es por operación: donde /v1/openapi.json publica x-sync-limit-bp en un POST, una solicitud síncrona por encima de esa longitud es 413 sync_too_large — 200.000 pb en annotation y 50.000 pb en el flujo de trabajo compuesto a partir de info.version 2026.09.10.1. Lee el campo en lugar de memorizar los números; las otras tareas de predicción no llevan límite hoy.

El mínimo es control de admisión, no un régimen. Una solicitud por encima del mínimo pero más corta que el bio_spec.context_window_bp del modelo seleccionado es aceptada y puntuada — contra una ventana rellenada hasta la ventana de contexto. El potenciador es el caso crítico: el mínimo es 50 pb pero la ventana de contexto es 249 pb, por lo que 50–248 pb se puntúa mayormente con relleno. Compara tu longitud con context_window_bp de GET /v1/tasks/{task}/models para saber si el modelo vio secuencia real. La entrada más larga que el contexto está bien — el escáner avanza una ventana de predicción a la vez y rellena solo la ventana parcial final.

Por debajo del mínimo y por encima del límite de 500.000 pb son ambos 422 validation_failed en loc ["body","sequence"]; la longitud excesiva no es un 413. Todas las longitudes se miden después de eliminar los espacios en blanco, por lo que un cuerpo FASTA con líneas ajustadas se puede pegar textualmente (una línea de encabezado > aún falla la comprobación del alfabeto).

options está tipado y cerrado (additionalProperties: false) por tarea — una clave desconocida es un 422 validation_failed duro con type: "extra_forbidden", nunca ignorado:

Tarea	Claves de options
promoter	threshold (0–1, predeterminado 0.5)
splice	threshold (0–1, predeterminado 0.5), site_types (subconjunto de ["donor","acceptor"], predeterminado ambos)
enhancer	(ninguno)
chromatin	threshold (0–1, predeterminado 0.5)
annotation	batch_size (1–128, predeterminado 8), shift_coordinates, reverse_complement (predeterminado true)
expression	description — requerido, y la única clave

Prefer: respond-async es un parámetro de encabezado declarado en las seis operaciones de predicción y en el compuesto, no solo en annotation — ver Asíncrono.

Omite model y la API usa el predeterminado de la tarea — esa es la llamada recomendada. Los IDs de modelo predeterminados intencionalmente no están documentados aquí: los predeterminados cambian y los IDs retirados fallan de forma dura, por lo que nunca codifiques uno. Para fijar un modelo, o para elegir uno no humano (existen modelos de Drosophila, levadura y Arabidopsis para varias tareas), descubre los IDs en tiempo de llamada con GET /v1/tasks/{task}/models (REST) o list_models (MCP) — y nunca inventes uno. Las formas de salida completas por tarea están en references/tasks.md.

expression es la más estricta de las seis: solo entre ellas su esquema requiere options además de sequence. Tres reglas estrictas que impone — cada violación es un 422, nada se rellena o sujeta, y no hay un indicador de exclusión, encabezado o parámetro de consulta:

• Siempre puntúa exactamente una ventana de 9.198 pb centrada en el TSS — sequence[tss_index-4599 : tss_index+4599]. El endpoint mismo acepta 9.198–500.000 pb; cualquier cosa por debajo de 9.198 pb se rechaza directamente.
• tss_index es requerido a menos que la secuencia tenga exactamente 9.198 pb. Es el desplazamiento TSS basado en 0 dentro de la secuencia sin espacios en blanco, limitado por 4599 ≤ tss_index ≤ len(sequence) − 4599. Con exactamente 9.198 pb, predetermina a 4.599, el único valor legal allí. Por lo tanto, puedes enviar un locus completo (hasta 500 kb) y dejar que el servidor corte la ventana — pero el servidor no descubre el TSS por ti (ese es el trabajo del flujo de trabajo compuesto), y no hace complemento inverso: envía la secuencia en sentido génico.
• options.description — una cadena de tipo celular/ensayo (por ejemplo, "células K562") — es requerida, y es la única clave que expression acepta dentro de options. Los campos desconocidos del cuerpo de nivel superior también se rechazan.

Nota: el rango legal de tss_index es amplio, por lo que un desplazamiento que es meramente incorrecto (contado sobre caracteres FASTA sin procesar incluyendo nuevas líneas, o relativo a un inicio de locus en lugar del fragmento enviado) no genera error — devuelve un 200 seguro para la ventana incorrecta. Afirmar en meta.task_specific_counts.scored_window / .tss_index en la respuesta. La longitud que enviaste es meta.sequence_length (también reflejada como data.input.submitted_sequence_length); el ancho puntuado es siempre 9.198, es decir, scored_window[1] - scored_window[0]. (data.input.sequence_length se eliminó en la revisión 13 del contrato).

Ambas violaciones de tss_index — "requerido a menos que tenga exactamente 9.198 pb" y la comprobación de rango — provienen de un validador de modelo completo, por lo que aparecen a nivel del cuerpo en lugar de bajo tss_index. Coincide con error.code == "validation_failed" y usa el mensaje solo para mostrar. Cualquier tupla loc citada en esta habilidad es ilustrativa de esa forma, no parte del contrato: no está publicada en el esquema y no se debe bifurcar en ella.

Adquisición de secuencias

Raramente empiezas con una cadena sin procesar de 9.198 pb. Adquiere primero la secuencia:

• Desde un símbolo génico → MCP fetch_ensembl_sequence(gene=...); desde coordenadas → fetch_region(region=...). Ambos obtienen secuencia de referencia pública de Ensembl (sin clave). Los usuarios de REST pueden consultar Ensembl REST directamente. (find_genes es la tarea de anotación, no una herramienta de adquisición).
• Para expression → usa la búsqueda centrada en TSS para que la ventana tenga exactamente 9.198 pb. MCP: fetch_gene_for_expression (maneja el centrado). De lo contrario, obtén un locus más amplio y pasa el TSS como tss_index para que el servidor corte la ventana — pero calcula ese desplazamiento en la cadena de nucleótidos sin espacios, no en los caracteres del archivo.
• Desde un FASTA local → MCP store_inline_sequence, o lee el archivo tú mismo para REST. (load_local_fasta existe solo en implementaciones locales, no en el servidor alojado).
• Una secuencia de demostración → MCP load_demo_sequence(name=...) devuelve un identificador listo para una prueba sin clave; name es requerido.

Ver references/sequence-acquisition.md para las llamadas exactas de Ensembl y las matemáticas de la ventana de expresión.

Flujo de trabajo REST principal

Llamado de forma síncrona — el predeterminado para cada tarea — una predicción es una llamada:

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   # expression only
    # Cada tarea es su propia operación publicada, pero la cadena URL no cambia.
    r = requests.post(f"{BASE}/v1/tasks/{task}/predict", headers=HEADERS, json=body)
    # 422 validation_failed  — secuencia por debajo del mínimo de la tarea O por encima de 500.000 pb,
    #                          tss_index incorrecto, falta options.description,
    #                          o CUALQUIER clave desconocida del cuerpo/options (options está cerrado)
    # 401 sin clave/clave incorrecta · 404 tarea desconocida · 413 cuerpo superior a 16 MiB · 429 límite de tasa
    r.raise_for_status()
    return r.json()               # {"data": {...}, "meta": {...}}

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

# Expresión — una ventana de 9.198 pb pre-cortada centrada en TSS (tss_index predetermina a 4.599):
out = predict("expression", tss_window_9198bp, "HBB",
              options={"description": "células K562"})
print(out["data"]["prediction"]["expression_log_tpm"])

# Expresión — un locus completo; el servidor corta ±4.599 pb alrededor del TSS que nombras.
# tss_index está basado en 0 dentro de la secuencia sin espacios en blanco.
out = predict("expression", locus_seq, "HBB",
              options={"description": "células K562"}, tss_index=tss_offset_in_locus)
print(out["meta"]["task_specific_counts"]["scored_window"])   # confirmar la ventana puntuada

Asíncrono (cualquier tarea; recomendado para anotación)

Prefer: respond-async es un parámetro de encabezado declarado en las seis operaciones de predicción y en el compuesto. Un 202 lleva el mismo envoltorio {data, meta} que un 200 síncrono, con data = {job_id, status: "accepted", links}; el id del trabajo también está en los encabezados de respuesta Content-Location y X-Job-Id. Asíncrono es solo JSON — combinarlo con un formato de texto format es rechazado. annotation es la tarea que lo necesita:

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 Aceptado
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: el cuerpo es el {data, meta} final
        break
    j.raise_for_status()          # 202 = aún ejecutándose (2xx, no generará excepción)
    time.sleep(5)                 # ~20 segundos típico para ~20 kb
transcripts = j.json()["data"]["transcripts"]

Flujo de trabajo MCP (basado en identificadores)

En un host MCP, adquiere un identificador, luego predice contra él — las secuencias permanecen fuera del contexto:

# 1. Adquirir un identificador de secuencia (cada uno devuelve un sequence_ref):
load_demo_sequence(name="promoter_tp53")  # prueba sin clave
...

[truncado para traducción]