genomic-intelligence

Genomic Intelligence — DNA-Sequenzmodelle

Genomic Intelligence (GI) stellt Transformer-DNA-Sprachmodelle für sechs Sequenzanalyseaufgaben auf verwalteten GPUs bereit. Geben Sie ein Gensymbol, eine Genomregion oder eine DNA/FASTA-Sequenz an, und es gibt strukturierte Vorhersagen zurück — Promotorregionen, Spleißstellen, Enhancer-Aktivität, Chromatinzustand, Expression (log TPM) und De-novo-Genannotation. Nichts läuft lokal: keine Modellgewichte, keine GPU, kein schwerer Python-Stack. Es ist ein dünner Client über einer gehosteten, versionierten Inferenz-API.

Offizielle Dokumentation: docs.genomicintelligence.ai · REST-Vertrag unter api.genomicintelligence.ai/v1/openapi.json · gehosteter MCP-Server unter https://mcp.genomicintelligence.ai/mcp

Wann dieser Skill verwendet werden sollte

Verwenden Sie GI, wenn der Benutzer eine DNA-Sequenz hat und eine Modellvorhersage wünscht:

• Promotoren finden in einer Genomregion (promoter)
• Spleißstellen vorhersagen Donor/Akzeptor (splice)
• Enhancer-Aktivität bewerten — entwicklungsbezogen & housekeeping (enhancer)
• Chromatinzustand annotieren über Hunderte von Spuren (chromatin)
• Expression vorhersagen als log(TPM+1) aus einer Sequenz + Zelltyp-Kontext (expression)
• Gene/Transkripte de novo annotieren, ohne Referenz (annotation)
• Gene in einer Region finden und die Expression jedes einzelnen vorhersagen (zusammengesetzt)

Nicht für lokales Alignment, Variantenaufruf oder Datei-I/O — verwenden Sie dafür ein lokales Tool (BioPython, bcftools). GI ist für Modellinferenz aus Sequenz.

Forschung und Entwicklung. Nicht für klinische oder diagnostische Entscheidungen.

Zwei Möglichkeiten, GI aufzurufen

Gehosteter MCP-Server (schlüssellos; bevorzugt auf MCP-Hosts)

GI hostet einen MCP-Server unter https://mcp.genomicintelligence.ai/mcp (Streamable HTTP). Wenn Ihr Agenten-Host MCP unterstützt, bevorzugen Sie dies: Es funktioniert schlüssellos gegen einen raten- und nebenläufigkeitsbegrenzten öffentlichen Demo-Tier, und ein optionaler gi_Bearer-Token erhöht diese Grenzen. Es stellt Akquisitionswerkzeuge bereit, die einen Sequenz-Handle (sequence_ref) zurückgeben, und predict_*-Werkzeuge, die diesen Handle verwenden, sodass große Sequenzen außerhalb des Kontexts bleiben. Siehe MCP-Workflow (handle-basiert) unten und references/mcp.md.

REST-API (universal)

Einfaches HTTP mit requests gegen https://api.genomicintelligence.ai/v1. Der REST-Pfad erfordert einen GI_API_KEY (ein gi_-Bearer). Verwenden Sie es auf jedem Host, in Skripten oder wenn Sie den rohen Envelope benötigen. Siehe Kern-REST-Workflow.

Zugriff und Authentifizierung

1. Der gehostete MCP-Demo ist schlüssellos — versuchen Sie es ohne etwas.
2. Die REST /v1-API benötigt einen Schlüssel, gesendet als Authorization: Bearer <key>. Fordern Sie einen an unter [email protected].
3. Den Schlüssel niemals hartcodieren. Lesen Sie ihn aus der Umgebungsvariablen GI_API_KEY (oder einer .env-Datei über python-dotenv). Schlüssel niemals committen.

export GI_API_KEY="gi_yourkeyhere"     # optional für MCP; erforderlich für REST
export GI_BASE_URL="https://api.genomicintelligence.ai"   # Überschreibung für Staging

Schlüssel sind auf eine Partnerstufe mit Nebenläufigkeits- und Minutenlimits beschränkt. Ein 429 bedeutet, dass Sie ein Limit erreicht haben — zurückziehen und wiederholen, oder fragen Sie GI, Ihre Stufe zu erhöhen.

Die sechs Aufgaben

Jede Aufgabe ist ihre eigene veröffentlichte Operation mit eigenem Anfrageschema, eigener Mindestlänge und eigenem geschlossenen options-Objekt — 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. Jeder Pfad ist ein Literalstring, sodass nichts konstruiert werden muss, und es gibt kein gemeinsames PredictRequest-Schema. Der Body ist {sequence, sequence_name?, model?, options?}, der einen {data, meta}-Envelope zurückgibt. Was sich pro Aufgabe unterscheidet:

Aufgabe	Empfohlener Modus	Akzeptierte Länge	context_window_bp	Hinweise
promoter	synchron	300–500.000 bp	2.000 bp	Gleitfenster-Promotorregionen
splice	synchron	100–500.000 bp	15.000 bp	Donor/Akzeptor-Stellen (BigBird mit langem Kontext); strangabhängig — Transkriptorientierung angeben
enhancer	synchron	50–500.000 bp	249 bp	dev + housekeeping-Werte (DeepSTARR, Drosophila)
chromatin	synchron	200–500.000 bp	1.000 bp	Hunderte von Spuren (DeepSEA)
expression	synchron	9.198–500.000 bp	n/a (trained_window_bp 9.198)	log(TPM+1); benötigt tss_index, wenn nicht genau 9.198 bp, plus eine Zelltyp-description
annotation	asynchron	1.000–500.000 bp	n/a	De-novo-Transkripte; einreichen + abfragen; synchron über 200.000 bp ist 413 sync_too_large

Empfohlener Modus ist eine Empfehlung, keine Einschränkung — jede Aufgabe akzeptiert beide. Lassen Sie Prefer für eine synchrone 200 aus; senden Sie Prefer: respond-async für eine 202 plus GET /v1/tasks/jobs/{job_id}. Die einzige durchgesetzte Grenze ist pro Operation: Wo /v1/openapi.json ein x-sync-limit-bp auf einem POST veröffentlicht, führt eine synchrone Anfrage oberhalb dieser Länge zu 413 sync_too_large — 200.000 bp für annotation und 50.000 bp für den zusammengesetzten Workflow ab info.version 2026.09.10.1. Lesen Sie das Feld, anstatt sich die Zahlen zu merken; die anderen Vorhersageaufgaben haben heute keine Grenze.

Das Minimum ist Zugangskontrolle, kein Regime. Eine Anfrage oberhalb der Untergrenze, aber kürzer als das bio_spec.context_window_bp des ausgewählten Modells wird akzeptiert und bewertet — gegen ein auf das Kontextfenster aufgefülltes Fenster. Enhancer ist der scharfe Fall: Die Untergrenze beträgt 50 bp, aber das Kontextfenster 249 bp, sodass 50–248 bp hauptsächlich auf Padding bewertet werden. Vergleichen Sie Ihre Länge mit context_window_bp von GET /v1/tasks/{task}/models, um zu wissen, ob das Modell echte Sequenz gesehen hat. Längere als Kontexteingabe ist in Ordnung — der Scanner durchläuft ein Vorhersagefenster nach dem anderen und füllt nur das letzte partielle Fenster auf.

Unterhalb der Untergrenze und oberhalb des 500.000-bp-Limits sind beide 422 validation_failed bei loc ["body","sequence"]; Überlänge ist keine 413. Alle Längen werden gemessen, nachdem Leerzeichen entfernt wurden, sodass ein zeilenumgebrochener FASTA-Body wörtlich eingefügt werden kann (eine >-Kopfzeile schlägt jedoch die Alphabetprüfung fehl).

options ist typisiert und geschlossen (additionalProperties: false) pro Aufgabe — ein unbekannter Schlüssel führt zu einem harten 422 validation_failed mit type: "extra_forbidden", wird nie ignoriert:

Aufgabe	options-Schlüssel
promoter	threshold (0–1, Standard 0.5)
splice	threshold (0–1, Standard 0.5), site_types (Teilmenge von ["donor","acceptor"], Standard beide)
enhancer	(keine)
chromatin	threshold (0–1, Standard 0.5)
annotation	batch_size (1–128, Standard 8), shift_coordinates, reverse_complement (Standard true)
expression	description — erforderlich und der einzige Schlüssel

Prefer: respond-async ist ein deklarierter Header auf allen sechs Vorhersageoperationen und auf dem zusammengesetzten, nicht nur auf annotation — siehe Async.

model weglassen, und die API verwendet die Standardeinstellung der Aufgabe — das ist der empfohlene Aufruf. Standardmodell-IDs sind absichtlich nicht hier dokumentiert: Standards ändern sich, und eingestellte IDs schlagen hart fehl, also niemals eine hartcodieren. Um ein Modell festzulegen oder ein nicht-menschliches auszuwählen (es gibt Drosophila-, Hefe- und Arabidopsis-Modelle für mehrere Aufgaben), entdecken Sie IDs zur Laufzeit mit GET /v1/tasks/{task}/models (REST) oder list_models (MCP) — und erfinden Sie niemals eine. Vollständige Ausgabeformen pro Aufgabe finden Sie in references/tasks.md.

expression ist die strengste der sechs: Als einzige erfordert ihr Schema options sowie sequence. Drei harte Regeln werden durchgesetzt — jeder Verstoß führt zu einer 422, nichts wird aufgefüllt oder begrenzt, und es gibt kein Opt-out-Flag, keinen Header und keinen Abfrageparameter:

• Es bewertet immer genau ein 9.198 bp TSS-zentriertes Fenster — sequence[tss_index-4599 : tss_index+4599]. Der Endpunkt selbst akzeptiert 9.198–500.000 bp; alles unter 9.198 bp wird sofort abgelehnt.
• tss_index ist erforderlich, es sei denn, die Sequenz ist genau 9.198 bp. Es ist der 0-basierte TSS-Offset in die leerzeichenbereinigte Sequenz, begrenzt auf 4599 ≤ tss_index ≤ len(sequence) − 4599. Bei genau 9.198 bp wird standardmäßig 4.599 verwendet, der einzige zulässige Wert dort. Sie können also einen ganzen Locus (bis zu 500 kb) einreichen und den Server das Fenster zuschneiden lassen — aber der Server findet den TSS nicht für Sie (das ist Aufgabe des zusammengesetzten Workflows) und erzeugt kein Reverse-Complement: Reichen Sie die gensinnige Sequenz ein.
• options.description — eine Zelltyp-/Assay-Zeichenfolge (z. B. "K562 cells") — ist erforderlich und ist der einzige Schlüssel, den expression innerhalb von options akzeptiert. Unbekannte Body-Felder der obersten Ebene werden ebenfalls abgelehnt.

Hinweis: Der zulässige tss_index-Bereich ist breit, sodass ein Offset, der lediglich falsch ist (über rohe FASTA-Zeichen einschließlich Zeilenumbrüche gezählt oder relativ zu einem Locus-Start anstatt zum eingereichten Ausschnitt), keinen Fehler verursacht — er gibt eine zuversichtliche 200 für das falsche Fenster zurück. Überprüfen Sie meta.task_specific_counts.scored_window /.tss_index in der Antwort. Die von Ihnen eingereichte Länge ist meta.sequence_length (auch als data.input.submitted_sequence_length zurückgegeben); die bewertete Breite ist immer 9.198, d. h. scored_window[1] - scored_window[0]. (data.input.sequence_length wurde bei Vertragsrevision 13 entfernt.)

Beide tss_index-Verstöße — "erforderlich, es sei denn, genau 9.198 bp" und die Bereichsprüfung — kommen von einem gesamten Modell-Validator, sodass sie auf Body-Ebene statt unter tss_index erscheinen. Gleichen Sie auf error.code == "validation_failed" ab und verwenden Sie die Nachricht nur zur Anzeige. Jedes in diesem Skill angegebene loc-Tupel veranschaulicht diese Form, ist aber nicht Teil des Vertrags: Es wird nicht im Schema veröffentlicht und darf nicht für Verzweigungen verwendet werden.

Sequenzerwerb

Sie beginnen selten mit einem rohen 9.198 bp String. Erwerben Sie zuerst die Sequenz:

• Von einem Gensymbol → MCP fetch_ensembl_sequence(gene=...); von Koordinaten → fetch_region(region=...). Beide rufen öffentliche Ensembl-Referenzsequenz ab (kein Schlüssel). REST-Benutzer können Ensembl REST direkt abfragen. (find_genes ist die Annotationaufgabe, kein Akquisitionswerkzeug.)
• Für expression → verwenden Sie den TSS-zentrierten Abruf, sodass das Fenster genau 9.198 bp beträgt. MCP: fetch_gene_for_expression (handhabt die Zentrierung). Andernfalls rufen Sie einen breiteren Locus ab und übergeben den TSS als tss_index, sodass der Server das Fenster zuschneidet — aber berechnen Sie diesen Offset auf dem bereinigten Nukleotid-String, nicht auf Dateizeichen.
• Von einer lokalen FASTA → MCP store_inline_sequence, oder lesen Sie die Datei selbst für REST. (load_local_fasta existiert nur in lokalen Bereitstellungen, nicht auf dem gehosteten Server.)
• Eine Demosequenz → MCP load_demo_sequence(name=...) gibt einen fertigen Handle für einen schlüssellosen Smoke-Test zurück; name ist erforderlich.

Siehe references/sequence-acquisition.md für die genauen Ensembl-Aufrufe und die Expressionsfenster-Berechnung.

Kern-REST-Workflow

Synchron aufgerufen — der Standard für jede Aufgabe — ist eine Vorhersage ein einzelner Aufruf:

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   # nur expression
    # Jede Aufgabe ist ihre eigene veröffentlichte Operation, aber die URL-Zeichenfolge ist unverändert.
    r = requests.post(f"{BASE}/v1/tasks/{task}/predict", headers=HEADERS, json=body)
    # 422 validation_failed  — Sequenz unterhalb der Aufgabenuntergrenze ODER über 500.000 bp,
    #                          schlechter tss_index, fehlende options.description,
    #                          oder JEDER unbekannte Body/Options-Schlüssel (options ist geschlossen)
    # 401 kein/schlechter Schlüssel · 404 unbekannte Aufgabe · 413 Body über 16 MiB · 429 Ratenlimit
    r.raise_for_status()
    return r.json()               # {"data": {...}, "meta": {...}}

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

# Expression — ein vorgeschnittenes 9.198 bp TSS-zentriertes Fenster (tss_index standardmäßig 4.599):
out = predict("expression", tss_window_9198bp, "HBB",
              options={"description": "K562 cells"})
print(out["data"]["prediction"]["expression_log_tpm"])

# Expression — ein ganzer Locus; der Server schneidet ±4.599 bp um den von Ihnen genannten TSS.
# tss_index ist 0-basiert in der leerzeichenbereinigten Sequenz.
out = predict("expression", locus_seq, "HBB",
              options={"description": "K562 cells"}, tss_index=tss_offset_in_locus)
print(out["meta"]["task_specific_counts"]["scored_window"])   # bestätigen Sie das bewertete Fenster

Async (beliebige Aufgabe; empfohlen für Annotation)

Prefer: respond-async ist ein deklarierter Header-Parameter auf allen sechs Vorhersageoperationen und auf dem zusammengesetzten. Eine 202 trägt denselben {data, meta}-Envelope wie eine synchrone 200, mit data = {job_id, status: "accepted", links}; die Job-ID befindet sich auch in den Content-Location- und X-Job-Id-Antwort-Headern. Async ist nur JSON — eine Kombination mit einem Text-format wird abgelehnt. annotation ist die Aufgabe, die es benötigt:

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: Body ist der finale {data, meta}
        break
    j.raise_for_status()          # 202 = läuft noch (2xx, löst keinen Fehler aus)
    time.sleep(5)                 # ~20 s typisch für ~20 kb
transcripts = j.json()["data"]["transcripts"]

MCP-Workflow (handle-basiert)

Auf einem MCP-Host einen Handle erwerben, dann dagegen vorhersagen — Sequenzen bleiben außerhalb des Kontexts:

# 1. Sequenz-Handle erwerben (jeder gibt einen sequence_ref zurück):
load_demo_sequence(name="promoter_tp53")  # schlüsselloser Smoke-Test

…

[gekürzt für Übersetzung]