@pikaa-ai/pikaa 0.2.4 → 0.3.0

package/skills/genomic-coordinates/scripts/normalize_variant.py

@@ -0,0 +1,290 @@
+#!/usr/bin/env python3
+"""Normalise VCF-style variants: check REF, trim, and left-align.
+
+Two variant records can describe exactly the same change to the genome and share
+no field values at all. Comparing, joining, or deduplicating variants without
+normalising first silently loses real matches. This implements the parsimony +
+left-alignment procedure of Tan, Abecasis & Kang (2015), which is what
+``bcftools norm`` and ``vt normalize`` implement.
+
+    python3 normalize_variant.py --fasta ref.fa chr1 7 CAC C
+    python3 normalize_variant.py --fasta ref.fa --input variants.vcf
+    python3 normalize_variant.py --fasta ref.fa --compare chr1:7:CAC:C chr1:3:CAC:C
+
+Exit codes: 0 all records verified against the reference, 1 at least one REF
+mismatch or invalid record, 2 usage or reference error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _common import Reference, ReferenceError, emit, iter_data_lines  # noqa: E402
+
+COLUMNS = [
+    "input",
+    "normalized",
+    "type",
+    "pos_shift",
+    "ref_check",
+    "changed",
+    "detail",
+]
+
+SYMBOLIC_PREFIXES = ("<", "*", ".")
+DEFAULT_WINDOW = 1000
+
+
+class VariantError(ValueError):
+    """The record cannot be normalised as written."""
+
+
+def classify(ref: str, alt: str) -> str:
+    if len(ref) == len(alt) == 1:
+        return "snv"
+    if len(ref) == len(alt):
+        return "mnv"
+    if len(ref) == 1 and len(alt) > 1 and alt.startswith(ref):
+        return "insertion"
+    if len(alt) == 1 and len(ref) > 1 and ref.startswith(alt):
+        return "deletion"
+    return "complex"
+
+
+def normalize(
+    reference: Reference,
+    contig: str,
+    pos: int,
+    ref: str,
+    alt: str,
+    window: int = DEFAULT_WINDOW,
+) -> dict:
+    """Normalise a single bi-allelic record. ``pos`` is 1-based, as in VCF.
+
+    Returns the normalised record plus how far it moved and whether the stated
+    REF actually matched the reference sequence. ``shifted`` is positive when
+    left-alignment walked the anchor left through a repeat, and negative when
+    trimming redundant flanking bases moved it right onto a parsimonious
+    representation (``3 CA>CT`` is really the SNV ``4 A>T``).
+    """
+    if pos < 1:
+        raise VariantError(f"POS {pos} is not 1-based; VCF positions start at 1")
+    if not ref:
+        raise VariantError("REF is empty; VCF requires at least the anchor base")
+    if alt.startswith(SYMBOLIC_PREFIXES):
+        return {
+            "pos": pos,
+            "ref": ref,
+            "alt": alt,
+            "shifted": 0,
+            "ref_check": "skipped",
+            "type": "symbolic",
+            "detail": "symbolic, missing, or spanning-deletion ALT: left as written",
+        }
+
+    ref, alt = ref.upper(), alt.upper()
+    observed = reference.fetch(contig, pos - 1, pos - 1 + len(ref))
+    if observed != ref:
+        return {
+            "pos": pos,
+            "ref": ref,
+            "alt": alt,
+            "shifted": 0,
+            "ref_check": "MISMATCH",
+            "type": classify(ref, alt),
+            "detail": (
+                f"REF says {ref} but the reference has {observed or '(past contig end)'} "
+                f"at {contig}:{pos}. Do not normalise this record -- the variants and "
+                "the FASTA are different assemblies, or the coordinates are off by one"
+            ),
+        }
+    if ref == alt:
+        raise VariantError(f"REF and ALT are both {ref}; this record asserts no change")
+
+    start_pos = pos
+    limit = max(0, pos - 1 - window)
+
+    # Right-trim and left-extend until the alleles no longer share a final base.
+    while ref[-1] == alt[-1]:
+        if len(ref) == 1 or len(alt) == 1:
+            if pos - 1 <= limit:
+                break
+            base = reference.fetch(contig, pos - 2, pos - 1)
+            if not base:
+                break
+            pos -= 1
+            ref, alt = base + ref, base + alt
+        ref, alt = ref[:-1], alt[:-1]
+
+    # Left-trim any shared leading bases, keeping one anchor base for indels.
+    while len(ref) > 1 and len(alt) > 1 and ref[0] == alt[0]:
+        ref, alt = ref[1:], alt[1:]
+        pos += 1
+
+    shifted = start_pos - pos
+    detail = ""
+    if shifted and pos - 1 <= limit:
+        detail = (
+            f"left-alignment stopped at the {window} bp window; the repeat may extend "
+            "further. Re-run with a larger --window to confirm"
+        )
+    return {
+        "pos": pos,
+        "ref": ref,
+        "alt": alt,
+        "shifted": shifted,
+        "ref_check": "ok",
+        "type": classify(ref, alt),
+        "detail": detail,
+    }
+
+
+def parse_spec(text: str) -> tuple[str, int, str, str]:
+    """Parse ``contig:pos:ref:alt``."""
+    parts = text.split(":")
+    if len(parts) != 4:
+        raise VariantError(f"expected contig:pos:ref:alt, got {text!r}")
+    contig, pos, ref, alt = parts
+    if not pos.isdigit():
+        raise VariantError(f"POS {pos!r} in {text!r} is not a number")
+    return contig, int(pos), ref, alt
+
+
+def read_records(path: str, split: bool) -> list[tuple[str, int, str, str]]:
+    """Read CHROM/POS/REF/ALT from a VCF, or from a bare 4-column TSV.
+
+    Five or more columns are read as VCF (CHROM POS ID REF ALT); exactly four as
+    CHROM POS REF ALT.
+    """
+    records: list[tuple[str, int, str, str]] = []
+    for lineno, line in iter_data_lines(path):
+        fields = line.split("\t")
+        if len(fields) >= 5:
+            contig, pos, ref, alt = fields[0], fields[1], fields[3], fields[4]
+        elif len(fields) == 4:
+            contig, pos, ref, alt = fields[0], fields[1], fields[2], fields[3]
+        else:
+            raise SystemExit(f"{path}:{lineno}: need CHROM, POS, REF, ALT columns")
+        if not pos.isdigit():
+            raise SystemExit(f"{path}:{lineno}: POS {pos!r} is not a number")
+        for one in alt.split(",") if split else [alt]:
+            records.append((contig, int(pos), ref, one))
+    return records
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Check, trim, and left-align VCF-style variants."
+    )
+    parser.add_argument("contig", nargs="?")
+    parser.add_argument("pos", nargs="?", type=int)
+    parser.add_argument("ref", nargs="?")
+    parser.add_argument("alt", nargs="?")
+    parser.add_argument("--fasta", required=True, help="reference FASTA (.fai used if present)")
+    parser.add_argument("--input", help="VCF, or a TSV of contig/pos/ref/alt")
+    parser.add_argument(
+        "--compare",
+        nargs="+",
+        metavar="CONTIG:POS:REF:ALT",
+        help="normalise two or more records and report whether they are the same variant",
+    )
+    parser.add_argument(
+        "--split",
+        action="store_true",
+        help="split comma-separated ALTs into one record each before normalising",
+    )
+    parser.add_argument("--window", type=int, default=DEFAULT_WINDOW)
+    parser.add_argument("--format", choices=("tsv", "json"), default="tsv")
+    parser.add_argument("-o", "--output")
+    return parser
+
+
+def run(records, reference, window) -> list[dict]:
+    rows = []
+    for contig, pos, ref, alt in records:
+        label = f"{contig}:{pos}:{ref}:{alt}"
+        try:
+            result = normalize(reference, contig, pos, ref, alt, window)
+        except (VariantError, ReferenceError) as exc:
+            rows.append(
+                {
+                    "input": label,
+                    "normalized": "",
+                    "type": "",
+                    "pos_shift": "",
+                    "ref_check": "error",
+                    "changed": "",
+                    "detail": str(exc),
+                }
+            )
+            continue
+        norm = f"{contig}:{result['pos']}:{result['ref']}:{result['alt']}"
+        rows.append(
+            {
+                "input": label,
+                "normalized": norm,
+                "type": result["type"],
+                "pos_shift": result["shifted"],
+                "ref_check": result["ref_check"],
+                "changed": "yes" if norm != label else "no",
+                "detail": result["detail"],
+            }
+        )
+    return rows
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        reference = Reference(args.fasta)
+    except ReferenceError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    records: list[tuple[str, int, str, str]] = []
+    if args.compare:
+        try:
+            records = [parse_spec(spec) for spec in args.compare]
+        except VariantError as exc:
+            parser.error(str(exc))
+    elif args.input:
+        records = read_records(args.input, args.split)
+    elif args.contig and args.pos is not None and args.ref and args.alt:
+        alts = args.alt.split(",") if args.split else [args.alt]
+        records = [(args.contig, args.pos, args.ref, a) for a in alts]
+    else:
+        parser.error("give contig pos ref alt, or --input, or --compare")
+
+    rows = run(records, reference, args.window)
+    emit(rows, COLUMNS, args.format, args.output)
+    sys.stdout.flush()
+
+    if args.compare:
+        if any(row["ref_check"] != "ok" for row in rows):
+            print("\nverdict: cannot compare -- at least one record failed", file=sys.stderr)
+            return 1
+        keys = {row["normalized"] for row in rows}
+        if len(keys) == 1:
+            print(
+                f"\nverdict: identical -- all {len(rows)} records normalise to "
+                f"{keys.pop()}",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                f"\nverdict: distinct -- {len(keys)} different variants after "
+                "normalisation",
+                file=sys.stderr,
+            )
+
+    return 1 if any(row["ref_check"] in {"MISMATCH", "error"} for row in rows) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/genomic-intelligence/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: genomic-intelligence
+description: "Predict regulatory features, gene structure, and expression directly from DNA sequence using Genomic Intelligence's hosted transformer DNA language models — no local GPU or model weights. Six tasks over a REST API and a hosted MCP server (keyless public demo): promoter regions, splice donor/acceptor sites, enhancer activity, chromatin state, sequence-to-expression (log TPM), and de-novo gene annotation, plus a composite find-genes-then-predict-expression workflow. Use when the user has a gene symbol, a genomic region, or a DNA/FASTA sequence and wants any of these predictions, mentions Genomic Intelligence, genomicintelligence.ai, api.genomicintelligence.ai, or mcp.genomicintelligence.ai."
+license: MIT
+compatibility: Python 3.10+ with the `requests` library for the REST path (no dedicated SDK). Network access required. The REST `/v1` API needs a `GI_API_KEY` (a `gi_` bearer); the hosted MCP server at mcp.genomicintelligence.ai/mcp works keyless against a capped public demo quota, key optional.
+metadata:
+  version: "1.0"
+  skill-author: Genomic Intelligence
+  trigger-keywords: DNA sequence prediction, regulatory genomics, promoter prediction, splice site prediction, enhancer activity, chromatin state, gene expression prediction, sequence to expression, log TPM, gene annotation, transcript prediction, DNA language model, genomic intelligence, hosted inference, Ensembl sequence, FASTA prediction, cis-regulatory, TSS window, DeepSEA, DeepSTARR, BigBird splice, MCP genomics
+  openclaw:
+    primaryEnv: GI_API_KEY
+    envVars:
+    - name: GI_API_KEY
+      required: false
+      description: Optional gi_ bearer key for the REST /v1 API and a higher MCP quota. The hosted MCP demo runs keyless; request a key at contact@genomicintelligence.ai.
+---
+
+# 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**.
+
+> For research and development use, **not clinical or diagnostic decisions**.
+
+## Two ways to call GI
+
+### Hosted MCP server (best for AI agents — keyless)
+
+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 capped public demo quota (zero setup), and an optional `gi_` bearer key raises
+the quota. It exposes acquisition tools that return a **sequence handle**
+(`sequence_ref`) and `predict_*` tools that take that handle — so large sequences
+never bloat 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
+
+All REST tasks share one shape: `POST /v1/tasks/{task}/predict` with body
+`{sequence, sequence_name, model?, options?}`, returning a `{data, meta}`
+envelope. What differs per task:
+
+| Task | Mode | Length bound | Notes |
+|---|---|---|---|
+| `promoter` | sync | 1–500,000 bp | sliding-window promoter regions |
+| `splice` | sync | 1–500,000 bp | donor/acceptor sites (long-context BigBird) |
+| `enhancer` | sync | 1–500,000 bp | dev + housekeeping scores (DeepSTARR, *Drosophila*) |
+| `chromatin` | sync | 1–500,000 bp | hundreds of tracks (DeepSEA) |
+| `expression` | sync | **exactly 9,198 bp** | log(TPM+1); needs a cell-type `description` |
+| `annotation` | **async** | 1–500,000 bp | de-novo transcripts; submit + poll |
+
+**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`.
+
+Two hard rules the model enforces:
+
+- **`expression` needs exactly 9,198 bp**, a window **centred on the TSS**
+  (4,599 upstream + TSS + 4,598 downstream). Any other length is rejected. Use the acquisition helpers below to
+  build it — do not truncate by hand.
+- **`expression` needs a `description`** — a cell-type / assay string (e.g.
+  `"K562 cells"`), passed as `options.description`.
+
+## 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). Do not
+  build the window by hand.
+- **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
+  (great 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
+
+Sync tasks (promoter, splice, enhancer, chromatin, expression) are 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):
+    body = {"sequence": sequence, "sequence_name": sequence_name}
+    if model:   body["model"] = model
+    if options: body["options"] = options
+    r = requests.post(f"{BASE}/v1/tasks/{task}/predict", headers=HEADERS, json=body)
+    r.raise_for_status()          # 400 invalid; 401 no/bad key; 413 too long; 429 rate limit
+    return r.json()               # {"data": {...}, "meta": {...}}
+
+# Promoter:
+out = predict("promoter", seq, "TP53_region")
+print(out["data"]["summary"])
+
+# Expression — exactly 9,198 bp + a cell-type description:
+out = predict("expression", tss_window_9198bp, "HBB",
+              options={"description": "K562 cells"})
+print(out["data"]["prediction"]["expression_log_tpm"])
+```
+
+### Async: annotation
+
+`annotation` is submit-then-poll. Send `Prefer: respond-async`, get a `job_id`,
+poll until terminal:
+
+```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>)
+predict_expression(sequence_ref=<ref>, description="K562 cells")
+predict_splice(sequence_ref=<ref>)        # + predict_enhancer / predict_chromatin
+
+# 3. Annotation on MCP is `find_genes` (there is no predict_annotation).
+#    It takes a handle, not a region, and runs async internally:
+find_genes(sequence_ref=<ref>)            # wait=True (default) returns the result
+find_genes(sequence_ref=<ref>, wait=False)  # -> job_id; poll get_job(job_id)
+
+# Discover models with list_models(task); reference context lives in the
+# gi://models, gi://docs/tasks, and gi://account MCP resources.
+```
+
+## Composite: find genes, then predict expression
+
+To answer "what genes are in this region and how are they expressed?", use the
+composite:
+
+- **MCP:** `find_genes_and_predict_expression(sequence_ref=..., description=...)`
+  — takes a **handle, not a region** (acquire one with `fetch_region` first);
+  `description` is required. Finds genes in the sequence and returns an
+  expression prediction for each.
+- **REST:** call gene discovery, then loop `expression` per gene (build each
+  TSS-centred 9,198 bp window via the acquisition helpers).
+
+## Errors
+
+| Code | Meaning | Action |
+|---|---|---|
+| 400 | Invalid request / bad sequence | Check the body; expression must be exactly 9,198 bp and carry `description` |
+| 401 | Missing/invalid key (REST) | Set `GI_API_KEY`; or use the keyless MCP demo |
+| 413 | Sequence too long | Stay within the task's length bound (≤500,000 bp) |
+| 429 | Rate / concurrency cap | Back off and retry; ask GI to raise your tier |
+| 422 | Validation failed (`validation_failed`) | The most common failure: expression not exactly 9,198 bp, or a sequence below the model's minimum length |
+| 5xx | Server error | Retry; if persistent, contact support |
+
+## Reference files
+
+- `references/tasks.md` — per-task output shapes, model registries, the async
+  annotation contract.
+- `references/api-and-auth.md` — REST endpoints, the `{data, meta}` envelope,
+  auth, base-URL override, tiers.
+- `references/mcp.md` — the hosted MCP tool list, the handle-based flow, and the
+  `gi://` resources.
+- `references/sequence-acquisition.md` — Ensembl fetch calls and the
+  expression-window (9,198 bp, TSS-centred) math.

package/skills/genomic-intelligence/references/api-and-auth.md

@@ -0,0 +1,45 @@
+# REST API & Authentication
+
+Base URL: `https://api.genomicintelligence.ai` (override with `GI_BASE_URL` for
+staging). Live contract: <https://api.genomicintelligence.ai/v1/openapi.json>.
+
+## Authentication
+
+Every `/v1/*` REST call needs a partner bearer key, sent as
+`Authorization: Bearer <key>`. Public routes needing no key: `/health`, `/docs`,
+`/redoc`, `/v1/openapi.json`.
+
+```bash
+export GI_API_KEY="gi_yourkeyhere"
+```
+
+Keys begin with `gi_`. Request one at contact@genomicintelligence.ai. Read the
+key from the environment (or a `.env` via `python-dotenv`); never hardcode or
+commit it.
+
+> The hosted **MCP** server (`mcp.genomicintelligence.ai/mcp`) is different: it
+> runs **keyless** against a capped public demo quota, with the key optional for
+> a higher quota. Only the **REST** path strictly requires a key. See `mcp.md`.
+
+## Endpoints
+
+| Method | Path | Purpose |
+|---|---|---|
+| POST | `/v1/tasks/{task}/predict` | Run a task (sync, or async for `annotation` with `Prefer: respond-async`) |
+| GET | `/v1/tasks/jobs/{job_id}` | Poll an async job (202 running → 200 terminal) |
+| GET | `/v1/tasks/{task}/models` | List available model IDs for a task |
+
+## Request / response
+
+Request body: `{sequence, sequence_name, model?, options?}`. `options` is
+task-specific — most notably `options.description` (required for `expression`).
+
+Success is a `{data, meta}` envelope; `data` is task-specific (see `tasks.md`),
+`meta` carries model + request info. Errors use an `{error}` envelope carrying
+`code`, `message`, `status` and `request_id`; the most common is `422`
+`validation_failed` (wrong sequence length).
+
+## Partner tiers
+
+Keys are scoped to a tier with concurrency and per-minute caps. A `429` means a
+cap was hit — back off and retry, or ask GI to raise the tier.

package/skills/genomic-intelligence/references/mcp.md

@@ -0,0 +1,94 @@
+# Hosted MCP Server
+
+GI hosts a Model Context Protocol server (Streamable HTTP) at:
+
+```
+https://mcp.genomicintelligence.ai/mcp
+```
+
+It works **keyless** against a capped public demo quota, with no setup. An
+optional `gi_` bearer key (`GI_API_KEY`) raises the quota. Prefer MCP on agent
+hosts that support it: the tools use agent-friendly, handle-based schemas so large
+sequences never enter the context.
+
+The hosted server exposes **15 tools**. Verify with `tools/list` rather than
+assuming; the list below is a point-in-time snapshot.
+
+## The handle-based flow
+
+Acquire a **sequence handle** (`sequence_ref`), then predict against it.
+
+### 1. Acquire (each returns a handle)
+
+| Tool | Required | Notes |
+|---|---|---|
+| `fetch_ensembl_sequence` | `gene` | Gene **symbol or Ensembl ID** (e.g. `"TP53"`). Also `species`, `flank_bp`. Not for coordinates. |
+| `fetch_region` | `region` | Coordinate range, e.g. `"chr8:127,680,000-127,800,000"`. Also `species`, `strand`, `flank_bp`. Plus strand by default, which is what gene finding expects. |
+| `fetch_gene_for_expression` | `gene` | Builds the **TSS-centred 9,198 bp** window `expression` needs. Also `species`. |
+| `load_demo_sequence` | `name` | **`name` is required.** Valid names: `promoter_tp53`, `splice_hbb`, `enhancer_eve`, `chromatin_active_promoter_chr19`, `expression_hbb_k562`, `annotation_hbb_chr11`. |
+| `store_inline_sequence` | `sequence` | Store an inline string; optional `name`. |
+
+There is **no `load_local_fasta` on the hosted server** — it only exists in local
+deployments. Over REST, read the file yourself.
+
+### 2. Predict (pass the handle)
+
+`predict_promoter`, `predict_splice`, `predict_enhancer`, `predict_chromatin`,
+`predict_expression`. Each takes `sequence_ref` **or** `sequence` (mutually
+exclusive), plus optional `model` and `sequence_name`.
+
+`predict_expression` additionally needs `description` (cell type / assay, e.g.
+`"K562 cells"`).
+
+### 3. Gene finding (the annotation task on MCP)
+
+**There is no `predict_annotation` tool.** The annotation task is surfaced as
+**`find_genes`**, which takes `sequence_ref` or `sequence` — **not** a `region`.
+Acquire a region handle with `fetch_region` first, then pass the handle.
+
+`find_genes` runs async internally (~8-25 s). With `wait=True` (the default) it
+blocks and returns the result directly, never a job id. With `wait=False` it
+returns `{data: {job_id, status}}` to poll with `get_job(job_id)`.
+
+## Composite
+
+`find_genes_and_predict_expression` takes `sequence_ref` or `sequence` plus a
+**required** `description`. It has **no `region` parameter** — acquire a handle
+with `fetch_region` first. It finds genes in the sequence, then predicts
+expression off each discovered TSS. Use it whenever you want expression for a
+whole region: `predict_expression` cannot run on one, because it needs a single
+per-gene 9,198 bp window.
+
+## Jobs and discovery
+
+- `get_job(job_id)` (required `job_id`) and `list_jobs` — poll detached work.
+- `list_models(task)` — the model registry for a task. Do not invent model IDs,
+  and do not hardcode a default; omit `model` and the server resolves it.
+
+## Resources
+
+Reference context lives in MCP resources: `gi://models`, `gi://docs/tasks`,
+`gi://sequences`, `gi://account`. Read these instead of hardcoding model lists or
+bounds.
+
+## Small sequences
+
+Small sequences may be passed inline via `sequence` on the `predict_*` tools, but
+the handle flow above is preferred to keep context small.
+
+## Worked example
+
+```
+# region -> handle -> genes -> expression per gene
+h = fetch_region(region="chr11:5,225,000-5,235,000")
+find_genes(sequence_ref=h.ref)
+find_genes_and_predict_expression(sequence_ref=h.ref, description="K562 cells")
+
+# gene -> handle -> promoter
+g = fetch_ensembl_sequence(gene="TP53")
+predict_promoter(sequence_ref=g.ref)
+
+# keyless smoke test
+d = load_demo_sequence(name="promoter_tp53")
+predict_promoter(sequence_ref=d.ref)
+```