Intelligence Génomique

Intelligence Génomique — Modèles de séquence d'ADN

L'Intelligence Génomique (GI) sert des modèles de langage d'ADN de type transformeur pour six tâches d'analyse de séquence sur des GPU gérés. Donnez-lui un symbole de gène, une région génomique ou une séquence ADN/FASTA ; elle retourne des prédictions structurées — régions promotrices, sites d'épissage, activité enhancer, état de la chromatine, expression (log TPM) et annotation de novo de gènes. Rien ne s'exécute localement : pas de poids de modèle, pas de GPU, pas de lourde pile Python. C'est un client léger pour une API d'inférence hébergée et versionnée.

Documentation officielle : docs.genomicintelligence.ai · Contrat REST sur api.genomicintelligence.ai/v1/openapi.json · Serveur MCP hébergé sur https://mcp.genomicintelligence.ai/mcp

Quand utiliser cette compétence

Utilisez GI quand l'utilisateur a de l'ADN et souhaite une prédiction par modèle :

• Trouver des promoteurs dans une région génomique (promoter)
• Prédire les sites d'épissage donneurs/accepteurs (splice)
• Évaluer l'activité enhancer — développementale et de ménage (enhancer)
• Annoter l'état de la chromatine à travers des centaines de pistes (chromatin)
• Prédire l'expression sous forme de log(TPM+1) à partir d'une séquence + contexte cellulaire (expression)
• Annoter des gènes/transcrits de novo, sans référence (annotation)
• Trouver les gènes dans une région et prédire l'expression de chacun (composite)

Pas pour l'alignement local, l'appel de variants ou les entrées/sorties de fichiers — utilisez un outil local (BioPython, bcftools) pour cela. GI est pour l'inférence de modèle à partir de séquences.

Recherche et développement uniquement. Pas pour les décisions cliniques ou de diagnostic.

Deux façons d'appeler GI

Serveur MCP hébergé (sans clé ; préféré sur les hôtes MCP)

GI héberge un serveur MCP sur https://mcp.genomicintelligence.ai/mcp (HTTP Streamable). Lorsque votre hôte agent prend en charge MCP, préférez-le : il fonctionne sans clé sur un niveau démo public limité en débit et en concurrence, et une clé porteuse gi_ facultative augmente ces limites. Il expose des outils d'acquisition qui retournent une poignée de séquence (sequence_ref) et des outils predict_* qui prennent cette poignée, de sorte que les grandes séquences restent hors du contexte. Voir Flux de travail MCP ci-dessous et references/mcp.md.

API REST (universelle)

HTTP simple avec requests vers https://api.genomicintelligence.ai/v1. Le chemin REST nécessite une GI_API_KEY (une clé porteuse gi_). Utilisez-la sur n'importe quel hôte, dans des scripts, ou lorsque vous avez besoin de l'enveloppe brute. Voir Flux de travail REST de base.

Accès et authentification

1. La démo MCP hébergée est sans clé — essayez-la sans rien configurer.
2. L'API REST /v1 nécessite une clé, envoyée comme Authorization: Bearer <clé>. Demandez-en une à [email protected].
3. Ne codez jamais la clé en dur. Lisez-la depuis la variable d'environnement GI_API_KEY (ou un .env via python-dotenv). Ne commettez jamais de clés.

export GI_API_KEY="gi_votrecléici"     # facultatif pour MCP ; requis pour REST
export GI_BASE_URL="https://api.genomicintelligence.ai"   # substitution pour l'environnement de test

Les clés sont limitées à un niveau partenaire avec des limites de concurrence et par minute. Un 429 signifie que vous avez atteint une limite — reculez et réessayez, ou demandez à GI d'augmenter votre niveau.

Les six tâches

Chaque tâche est sa propre opération publiée avec son propre schéma de requête, sa propre longueur minimale et son propre objet options fermé — 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. Chaque chemin est une chaîne littérale, donc rien n'a besoin d'être construit, et il n'y a pas de schéma PredictRequest partagé. Le corps est {sequence, sequence_name?, model?, options?}, retournant une enveloppe {data, meta}. Ce qui diffère par tâche :

Tâche	Mode recommandé	Longueur acceptée	context_window_bp	Remarques
promoter	synchrone	300–500 000 pb	2 000 pb	régions promotrices par fenêtre glissante
splice	synchrone	100–500 000 pb	15 000 pb	sites donneurs/accepteurs (BigBird à long contexte) ; spécifique au brin — fournissez l'orientation du transcrit
enhancer	synchrone	50–500 000 pb	249 pb	scores développementaux + de ménage (DeepSTARR, Drosophila)
chromatin	synchrone	200–500 000 pb	1 000 pb	des centaines de pistes (DeepSEA)
expression	synchrone	9 198–500 000 pb	n/a (trained_window_bp 9 198)	log(TPM+1) ; nécessite tss_index sauf si exactement 9 198 pb, plus une description du type cellulaire
annotation	asynchrone	1 000–500 000 pb	n/a	transcrits de novo ; soumettre + interroger ; synchrone au-dessus de 200 000 pb est 413 sync_too_large

Mode recommandé est une indication, pas une contrainte — chaque tâche accepte les deux. Omettez Prefer pour un 200 synchrone ; envoyez Prefer: respond-async pour un 202 plus GET /v1/tasks/jobs/{job_id}. La seule limite imposée est par opération : là où /v1/openapi.json publie x-sync-limit-bp sur un POST, une requête synchrone au-dessus de cette longueur est 413 sync_too_large — 200 000 pb sur annotation et 50 000 pb sur le flux de travail composite en date de info.version 2026.09.10.1. Lisez le champ plutôt que de mémoriser les nombres ; les autres tâches de prédiction n'ont aujourd'hui aucune limite.

Le minimum est un contrôle d'admission, pas un régime. Une requête au-dessus du plancher mais plus courte que le bio_spec.context_window_bp du modèle sélectionné est acceptée et notée — contre une fenêtre étendue jusqu'à la fenêtre de contexte. Enhancer est le cas marquant : le plancher est de 50 pb mais la fenêtre de contexte est de 249 pb, donc 50–248 pb est noté principalement sur du remplissage. Comparez votre longueur à context_window_bp de GET /v1/tasks/{task}/models pour savoir si le modèle a vu une séquence réelle. Une entrée plus longue que le contexte est acceptable — le scanneur avance une fenêtre de prédiction à la fois et ne remplit que la dernière fenêtre partielle.

En dessous du plancher et au-dessus de la limite de 500 000 pb sont tous deux 422 validation_failed à loc ["body","sequence"] ; une longueur excessive n'est pas un 413. Toutes les longueurs sont mesurées après suppression des espaces, donc un corps FASTA avec des retours à la ligne peut être collé tel quel (une ligne d'en-tête > échoue toujours à la vérification de l'alphabet).

options est typé et fermé (additionalProperties: false) par tâche — une clé inconnue est un 422 validation_failed catégorique avec type: "extra_forbidden", jamais ignorée :

Tâche	Clés options
promoter	threshold (0–1, défaut 0.5)
splice	threshold (0–1, défaut 0.5), site_types (sous-ensemble de ["donor","acceptor"], défaut les deux)
enhancer	(aucune)
chromatin	threshold (0–1, défaut 0.5)
annotation	batch_size (1–128, défaut 8), shift_coordinates, reverse_complement (défaut true)
expression	description — requis, et la seule clé

Prefer: respond-async est un en-tête déclaré sur les six opérations de prédiction et sur le composite, pas seulement annotation — voir Asynchrone.

Omettez model et l'API utilise la valeur par défaut de la tâche — c'est l'appel recommandé. Les ID de modèle par défaut ne sont intentionnellement pas documentés ici : les valeurs par défaut changent et les ID retirés échouent durement, donc ne les codez jamais en dur. Pour épingler un modèle, ou pour choisir un modèle non humain (les modèles de drosophile, levure et Arabidopsis existent pour plusieurs tâches), découvrez les ID au moment de l'appel avec GET /v1/tasks/{task}/models (REST) ou list_models (MCP) — et n'en inventez jamais. Les formes de sortie complètes par tâche sont dans references/tasks.md.

expression est la plus stricte des six : seule parmi elles, son schéma exige options en plus de sequence. Trois règles strictes qu'elle applique — chaque violation est un 422, rien n'est rempli ou bloqué, et il n'y a pas de drapeau d'opt-out, d'en-tête ou de paramètre de requête :

• Elle évalue toujours exactement une fenêtre de 9 198 pb centrée sur le TSS — sequence[tss_index-4599 : tss_index+4599]. Le point de terminaison lui-même accepte 9 198–500 000 pb ; toute séquence en dessous de 9 198 pb est rejetée purement et simplement.
• tss_index est requis sauf si la séquence fait exactement 9 198 pb. C'est le décalage TSS basé sur 0 dans la séquence sans espaces, borné par 4599 ≤ tss_index ≤ len(sequence) − 4599. À exactement 9 198 pb, il prend par défaut la valeur 4 599, la seule valeur légale là. Vous pouvez donc soumettre un locus entier (jusqu'à 500 kb) et laisser le serveur couper la fenêtre — mais le serveur ne découvre pas le TSS pour vous (c'est le travail du flux de travail composite) et ne fait pas de complément inverse : soumettez la séquence dans le sens du gène.
• options.description — une chaîne de type cellulaire / test (par exemple "cellules K562") — est requise et est la seule clé que expression accepte dans options. Les champs de corps de premier niveau inconnus sont également rejetés.

Remarque : la plage légale de tss_index est large, donc un décalage qui est simplement faux (compté sur les caractères FASTA bruts incluant les sauts de ligne, ou relatif à un début de locus plutôt qu'à la tranche soumise) ne génère pas d'erreur — il retourne un 200 confiant pour la mauvaise fenêtre. Vérifiez meta.task_specific_counts.scored_window / .tss_index dans la réponse. La longueur que vous avez soumise est meta.sequence_length (également reflétée comme data.input.submitted_sequence_length) ; la largeur évaluée est toujours 9 198, c'est-à-dire scored_window[1] - scored_window[0]. (data.input.sequence_length a été supprimé à la révision 13 du contrat.)

Les deux violations de tss_index — "requis sauf si exactement 9 198 pb" et la vérification de plage — proviennent d'un validateur au niveau du modèle, donc elles apparaissent au niveau du corps plutôt que sous tss_index. Cherchez error.code == "validation_failed" et utilisez le message pour l'affichage uniquement. Tout tuple loc cité dans cette compétence est illustratif de cette forme, pas une partie du contrat : il n'est pas publié dans le schéma et ne doit pas être utilisé pour des branchements.

Acquisition de séquence

Vous partez rarement d'une chaîne brute de 9 198 pb. Acquérez d'abord la séquence :

• À partir d'un symbole de gène → MCP fetch_ensembl_sequence(gene=...) ; à partir de coordonnées → fetch_region(region=...). Les deux récupèrent la séquence de référence Ensembl publique (pas de clé). Les utilisateurs REST peuvent interroger l'API REST Ensembl directement. (find_genes est la tâche d'annotation, pas un outil d'acquisition.)
• Pour expression → utilisez la récupération centrée sur le TSS pour que la fenêtre soit exactement 9 198 pb. MCP : fetch_gene_for_expression (gère le centrage). Sinon, récupérez un locus plus large et passez le TSS comme tss_index pour que le serveur coupe la fenêtre — mais calculez ce décalage sur la chaîne nucléotidique sans espaces, pas sur les caractères du fichier.
• À partir d'un fichier FASTA local → MCP store_inline_sequence, ou lisez le fichier vous-même pour REST. (load_local_fasta n'existe que dans les déploiements locaux, pas sur le serveur hébergé.)
• Une séquence de démonstration → MCP load_demo_sequence(name=...) retourne une poignée prête pour un test sans clé ; name est requis.

Voir references/sequence-acquisition.md pour les appels Ensembl exacts et le calcul de la fenêtre d'expression.

Flux de travail REST de base

Appelée de manière synchrone — la valeur par défaut pour chaque tâche — une prédiction est un appel :

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 uniquement
    # Chaque tâche est sa propre opération publiée, mais la chaîne URL est inchangée.
    r = requests.post(f"{BASE}/v1/tasks/{task}/predict", headers=HEADERS, json=body)
    # 422 validation_failed  — séquence sous le plancher de la tâche OU au-dessus de 500 000 pb,
    #                          mauvais tss_index, options.description manquant,
    #                          ou TOUTE clé corps/options inconnue (options est fermé)
    # 401 clé absente/mauvaise · 404 tâche inconnue · 413 corps > 16 Mio · 429 limite de taux
    r.raise_for_status()
    return r.json()               # {"data": {...}, "meta": {...}}

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

# Expression — une fenêtre pré-découpée de 9 198 pb centrée sur le TSS (tss_index par défaut à 4 599) :
out = predict("expression", fenetre_tss_9198pb, "HBB",
              options={"description": "cellules K562"})
print(out["data"]["prediction"]["expression_log_tpm"])

# Expression — un locus entier ; le serveur découpe ±4 599 pb autour du TSS que vous nommez.
# tss_index est basé sur 0 dans la séquence sans espaces.
out = predict("expression", seq_locus, "HBB",
              options={"description": "cellules K562"}, tss_index=decalage_tss_dans_locus)
print(out["meta"]["task_specific_counts"]["scored_window"])   # confirmez la fenêtre évaluée

Asynchrone (toute tâche ; recommandé pour l'annotation)

Prefer: respond-async est un paramètre d'en-tête déclaré sur toutes les six opérations de prédiction et sur le composite. Un 202 contient la même enveloppe {data, meta} qu'un 200 synchrone, avec data = {job_id, status: "accepted", links} ; l'ID du travail est également dans les en-têtes de réponse Content-Location et X-Job-Id. L'asynchrone est uniquement JSON — le combiner avec un format texte est rejeté. annotation est la tâche qui en a besoin :

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 Accepté
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 : le corps est le {data, meta} final
        break
    j.raise_for_status()          # 202 = toujours en cours (2xx, ne lèvera pas)
    time.sleep(5)                 # ~20 s typique pour ~20 kb
transcrits = j.json()["data"]["transcripts"]

Flux de travail MCP (à base de poignées)

Sur un hôte MCP, acquérez une poignée, puis prédisez contre elle — les séquences restent hors du contexte :

# 1. Acquérir une poignée de séquence (chacune retourne un sequence_ref) :
load_demo_sequence(name="promoter_tp53")  # test sans clé

… [tronqué pour la traduction]