genomic-intelligence

# Genomic Intelligence — DNA Sequence Models Genomic Intelligence (GI) serves transformer DNA language models over six sequence-analysis tasks on managed GPUs. Give it a **gene symbol**, a **genomic region**, or a **DNA/FASTA sequence**; it returns structured predictions — promoter regions, splice sites, enhancer activity, chromatin state, expression (log TPM), and de-novo gene annotation. Nothing runs locally: no model weights, no GPU, no heavy Python stack. It is a thin client over a hosted, versioned inference API. **Official docs:** [docs.genomicintelligence.ai](https://docs.genomicintelligence.ai) · REST contract at [api.genomicintelligence.ai/v1/openapi.json](https://api.genomicintelligence.ai/v1/openapi.json) · hosted MCP server at `https://mcp.genomicintelligence.ai/mcp` ## When to use this skill Use GI when the user has DNA and wants a model prediction: - **Find promoters** in a genomic region (`promoter`) - **Predict splice** donor/acceptor sites (`splice`) - **Score enhancer activity** — developmental & housekeeping (`enhancer`) - **Annotate chromatin state** across hundreds of tracks (`chromatin`) - **Predict expression** as log(TPM+1) from a sequence + cell-type context (`expression`) - **Annotate genes/transcripts** de novo, no reference needed (`annotation`) - **Find the genes in a region and predict each one's expression** (composite) Not for local alignment, variant calling, or file I/O — use a local tool (BioPython, bcftools) for those. GI is for **model inference from sequence**. > Research and development use. Not for clinical or diagnostic decisions. ## Two ways to call GI ### Hosted MCP server (keyless; preferred on MCP hosts) GI hosts an MCP server at `https://mcp.genomicintelligence.ai/mcp` (Streamable HTTP). When your agent host supports MCP, prefer it: it works **keyless** against a rate- and concurrency-limited public demo tier, and an optional `gi_` bearer key raises those limits. It exposes acquisition tools that return a **sequence handle** (`sequence_ref`) and `predict_*` tools that take that handle, so large sequences stay out of the context. See [MCP workflow](#mcp-workflow-handle-based) below and `references/mcp.md`. ### REST API (universal) Plain HTTP with `requests` against `https://api.genomicintelligence.ai/v1`. The REST path **requires** a `GI_API_KEY` (a `gi_` bearer). Use it on any host, in scripts, or when you need the raw envelope. See [Core REST workflow](#core-rest-workflow). ## Access and authentication 1. The **hosted MCP demo is keyless** — try it with nothing set. 2. The **REST `/v1` API needs a key**, sent as `Authorization: Bearer <key>`. Request one at [contact@genomicintelligence.ai](mailto:contact@genomicintelligence.ai). 3. **Never hardcode the key.** Read it from the `GI_API_KEY` environment variable (or a `.env` via `python-dotenv`). Never commit keys. ```bash export GI_API_KEY="gi_yourkeyhere" # optional for MCP; required for REST export GI_BASE_URL="https://api.genomicintelligence.ai" # override for staging ``` Keys are scoped to a partner tier with concurrency and per-minute caps. A `429` means you hit a cap — back off and retry, or ask GI to raise your tier. ## The six tasks Each task is **its own published operation** with its own request schema, its own minimum length, and its own closed `options` object — `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`. Each path is a literal string, so nothing needs to be constructed, and there is no shared `PredictRequest` schema. Body is `{sequence, sequence_name?, model?, options?}`, returning a `{data, meta}` envelope. What differs per task: | Task | Recommended mode | Accepted length | `context_window_bp` | Notes | |---|---|---|---|---| | `promoter` | sync | 300–500,000 bp | 2,000 bp | sliding-window promoter regions | | `splice` | sync | 100–500,000 bp | 15,000 bp | donor/acceptor sites (long-context BigBird); strand-specific — feed transcript orientation | | `enhancer` | sync | 50–500,000 bp | 249 bp | dev + housekeeping scores (DeepSTARR, *Drosophila*) | | `chromatin` | sync | 200–500,000 bp | 1,000 bp | hundreds of tracks (DeepSEA) | | `expression` | sync | **9,198–500,000 bp** | n/a (`trained_window_bp` 9,198) | log(TPM+1); needs `tss_index` unless exactly 9,198 bp, plus a cell-type `description` | | `annotation` | async | 1,000–500,000 bp | n/a | de-novo transcripts; submit + poll; sync above 200,000 bp is `413 sync_too_large` | `Recommended mode` is guidance, not a constraint — every task accepts both. Omit `Prefer` for a synchronous `200`; send `Prefer: respond-async` for a `202` plus `GET /v1/tasks/jobs/{job_id}`. The one enforced limit is per operation: where `/v1/openapi.json` publishes `x-sync-limit-bp` on a `POST`, a synchronous request above that length is `413 sync_too_large` — 200,000 bp on `annotation` and 50,000 bp on the composite workflow as of `info.version` 2026.09.10.1. Read the field rather than memorising the numbers; the other predict tasks carry no limit today. **The minimum is admission control, not regime.** A request above the floor but shorter than the selected model's `bio_spec.context_window_bp` is *accepted and scored* — against a window padded out to the context window. Enhancer is the sharp case: the floor is 50 bp but the context window is 249 bp, so 50–248 bp is scored mostly on padding. Compare your length against `context_window_bp` from `GET /v1/tasks/{task}/models` to know whether the model saw real sequence. Longer-than-context input is fine — the scanner steps a prediction window at a time and pads only the final partial window. Under the floor and over the 500,000 bp cap are **both `422 validation_failed`** at `loc ["body","sequence"]`; over-length is *not* a `413`. All lengths are measured after whitespace is stripped, so a line-wrapped FASTA body can be pasted verbatim (a `>` header line still fails the alphabet check). `options` is typed and **closed** (`additionalProperties: false`) per task — an unknown key is a hard `422 validation_failed` with `type: "extra_forbidden"`, never ignored: | Task | `options` keys | |---|---| | promoter | `threshold` (0–1, default 0.5) | | splice | `threshold` (0–1, default 0.5), `site_types` (subset of `["donor","acceptor"]`, default both) | | enhancer | *(none)* | | chromatin | `threshold` (0–1, default 0.5) | | annotation | `batch_size` (1–128, default 8), `shift_coordinates`, `reverse_complement` (default true) | | expression | `description` — **required**, and the only key | `Prefer: respond-async` is a declared header on **all six** predict operations and on the composite, not just `annotation` — see [Async](#async-any-task-recommended-for-annotation). **Omit `model` and the API uses the task's default** — that is the recommended call. Default model IDs are intentionally **not** documented here: defaults change and retired IDs fail hard, so never hardcode one. To pin a model, or to pick a non-human one (Drosophila, yeast, and Arabidopsis models exist for several tasks), discover IDs at call time with `GET /v1/tasks/{task}/models` (REST) or `list_models` (MCP) — and **never invent one**. Full per-task output shapes are in `references/tasks.md`. `expression` is the strictest of the six: alone among them its schema requires `options` as well as `sequence`. Three hard rules it enforces — every violation is a `422`, nothing is padded or clamped, and there is no opt-out flag, header, or query parameter: - **It always scores exactly one 9,198 bp TSS-centred window** — `sequence[tss_index-4599 : tss_index+4599]`. The endpoint itself accepts **9,198–500,000 bp**; anything below 9,198 bp is rejected outright. - **`tss_index` is required unless the sequence is exactly 9,198 bp.** It is the 0-based TSS offset into the **whitespace-stripped** sequence, bounded by `4599 ≤ tss_index ≤ len(sequence) − 4599`. At exactly 9,198 bp it defaults to 4,599, the only legal value there. So you may submit a whole locus (up to 500 kb) and let the server cut the window — but the server does **not** discover the TSS for you (that is the composite workflow's job), and does **not** reverse-complement: submit gene-sense sequence. - **`options.description`** — a cell-type / assay string (e.g. `"K562 cells"`) — is required, and is the **only** key `expression` accepts inside `options`. Unknown top-level body fields are rejected too. > Note: the legal `tss_index` range is wide, so an offset that is merely > *wrong* (counted over raw FASTA characters including newlines, or relative to > a locus start rather than the submitted slice) does not error — it returns a > confident `200` for the wrong window. Assert on > `meta.task_specific_counts.scored_window` / `.tss_index` in the response. > The length you submitted is `meta.sequence_length` (also echoed as > `data.input.submitted_sequence_length`); the scored width is always 9,198, > i.e. `scored_window[1] - scored_window[0]`. (`data.input.sequence_length` > was removed at contract revision 13.) > > Both `tss_index` violations — "required unless exactly 9,198 bp" and the range > check — come from a whole-model validator, so they surface at the body level > rather than under `tss_index`. Match on `error.code == "validation_failed"` > and use the message for display only. Any `loc` tuple quoted in this skill is > illustrative of that shape, not part of the contract: it is not published in > the schema and must not be branched on. ## Sequence acquisition You rarely start from a raw 9,198 bp string. Acquire sequence first: - **From a gene symbol** → MCP `fetch_ensembl_sequence(gene=...)`; **from coordinates** → `fetch_region(region=...)`. Both fetch public Ensembl reference sequence (no key). REST users can query Ensembl REST directly. (`find_genes` is the annotation task, not an acquisition tool.) - **For `expression`** → use the TSS-centred fetch so the window is exactly 9,198 bp. MCP: `fetch_gene_for_expression` (handles the centring). Otherwise fetch a wider locus and pass the TSS as `tss_index` so the server cuts the window — but compute that offset on the stripped nucleotide string, not on file characters. - **From a local FASTA** → MCP `store_inline_sequence`, or read the file yourself for REST. (`load_local_fasta` exists only in local deployments, not on the hosted server.) - **A demo sequence** → MCP `load_demo_sequence(name=...)` returns a ready handle for a keyless smoke test; `name` is required. See `references/sequence-acquisition.md` for the exact Ensembl calls and the expression-window math. ## Core REST workflow Called synchronously — the default for every task — a prediction is one call: ```python 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 # Each task is its own published operation, but the URL string is unchanged. r = requests.post(f"{BASE}/v1/tasks/{task}/predict", headers=HEADERS, json=body) # 422 validation_failed — sequence under the task floor OR over 500,000 bp, # bad tss_index, missing options.description, # or ANY unknown body/options key (options is closed) # 401 no/bad key · 404 unknown task · 413 body over 16 MiB · 429 rate limit r.raise_for_status() return r.json() # {"data": {...}, "meta": {...}} # Promoter: out = predict("promoter", seq, "TP53_region") print(out["data"]["summary"]) # Expression — a pre-cut 9,198 bp TSS-centred window (tss_index defaults to 4,599): out = predict("expression", tss_window_9198bp, "HBB", options={"description": "K562 cells"}) print(out["data"]["prediction"]["expression_log_tpm"]) # Expression — a whole locus; the server slices ±4,599 bp around the TSS you name. # tss_index is 0-based into the whitespace-stripped sequence. out = predict("expression", locus_seq, "HBB", options={"description": "K562 cells"}, tss_index=tss_offset_in_locus) print(out["meta"]["task_specific_counts"]["scored_window"]) # confirm the window scored ``` ### Async (any task; recommended for annotation) `Prefer: respond-async` is a declared header parameter on all six predict operations and on the composite. A `202` carries the same `{data, meta}` envelope as a sync `200`, with `data = {job_id, status: "accepted", links}`; the job id is also in the `Content-Location` and `X-Job-Id` response headers. Async is JSON-only — combining it with a text `format` is rejected. `annotation` is the task that needs it: ```python 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 is the final {data, meta} break j.raise_for_status() # 202 = still running (2xx, won't raise) time.sleep(5) # ~20 s typical for ~20 kb transcripts = j.json()["data"]["transcripts"] ``` ## MCP workflow (handle-based) On an MCP host, acquire a handle, then predict against it — sequences stay out of the context: ``` # 1. Acquire a sequence handle (each returns a sequence_ref): load_demo_sequence(name="promoter_tp53") # keyless smoke test; name is required fetch_ensembl_sequence(gene="TP53") # gene symbol or Ensembl ID -> handle 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>)