🧪 gi-expression
You are gi-expression, a ClawBio agent that calls the Genomic Intelligence sequence-to-expression model. Given at least 9,198 bp around a TSS (--tss-index unless it is exactly 9,198 bp) and a cell-type description, it returns predicted expression (log TPM + TPM).
⚠️ Remote inference — opt-in required. Unlike most ClawBio skills, this skill uploads your FASTA sequence to the hosted Genomic Intelligence API at https://api.genomicintelligence.ai. The same models also run interactively at https://genomicintelligence.ai. Do not submit identifiable patient data without an appropriate data-use agreement. Key setup: see Authentication below.
Trigger
Fire this skill when the user says any of:
- "predict expression for this gene / sequence"
- "what's the expression of this region in [cell type]?"
- "sequence-to-expression prediction"
- "TPM prediction", "log TPM prediction"
- "gi-expression", "G0 expression"
Do NOT fire when:
- The user has counts / RNA-seq output and wants differential expression →
rnaseq-de
- The user wants tissue annotation / GTEx lookup → use external resources
Why This Exists
- Without it: Sequence-to-expression models (Enformer / Borzoi / G0 Expression) need GPU + private weights + careful TSS-centred windowing.
- With it: One CLI call → expression prediction conditioned on free-text cell-type description, in <1 s.
- Why ClawBio: Private weights, hosted. ClawBio's reproducibility bundle + chaining (
gi-promoter → gi-expression → rnaseq-de interpretation).
API Backed
POST https://api.genomicintelligence.ai/v1/tasks/expression/predict. Omit model and the API resolves the default; GET /v1/tasks/expression/models is the current list.
Contract note. The Genomic Intelligence API publishes one operation per task, each with its own request schema: per-task minLength/maxLength on sequence, and a typed, closed options object (an unknown option key is a 422 validation_failed, not a silent ignore). The bounds quoted in this file are the published ones, but the authority is always the served schema: GET https://api.genomicintelligence.ai/v1/openapi.json.
Workflow
- Parse: single-record FASTA, gene-sense, 9,198–500,000 bp with
--tss-index at least 4,599 bp from each end (an exact 9,198 bp TSS-centred sequence may omit it). Anything else is rejected locally before the request is sent. For a named gene, build the FASTA as in Building the input from a gene.
- Build options:
{"description": "assay term name is polyA plus RNA-seq. biosample summary is Homo sapiens K562."} by default; override via --description "...".
- POST to
/v1/tasks/expression/predict, which is its own operation with its own request schema — each of the six tasks has one, so there is no shared predict body.
- Render:
report.md (headline log TPM plus the scored window the API actually used) + result.json + reproducibility/.
CLI Reference
# Demo — HBB in K562
python skills/gi-expression/gi_expression.py --demo --output /tmp/gi-expression-demo
# Custom cell-type description
python skills/gi-expression/gi_expression.py \
--input my_tss_window.fa \
--description "assay term name is polyA plus RNA-seq. biosample summary is Homo sapiens liver." \
--output report_dir
# A gene fetched as in "Building the input from a gene": the TSS sits at
# offset F, so --tss-index is F (0-based, counted after whitespace is stripped)
python skills/gi-expression/gi_expression.py \
--input my_gene.fa --tss-index "$F" \
--output report_dir
# Via ClawBio runner
python clawbio.py run gi-expression --demo
Building the input from a gene
How much sequence to send is read from the model list at run time, never from this page: the API adds longer-context expression models and changes the default, and a too-short input is still scored, just with less context than the model reads.
- Read the list.
GET https://api.genomicintelligence.ai/v1/tasks/expression/models is public (no key). Use the model the user named, else default_model, and pass it as --model so every call in a run uses the same one.
- Pick F, the flank on each side of the TSS: the largest
bio_spec.recommended_flank_bp among the listed models, each capped so 2F fits that model's bio_spec.request_max_bp, and never below 4,599. One fetch then serves every listed model; a model ignores flank beyond what it reads.
- Find the TSS from the gene's canonical transcript (Ensembl
GET /lookup/symbol/homo_sapiens/<SYMBOL>?expand=1, then the transcript with is_canonical). Plus strand: TSS = transcript start. Minus strand: TSS = transcript end. Do not fall back to the gene's own start or end; refuse if there is no canonical transcript.
- Fetch gene-sense. Plus strand: genomic
[TSS - F, TSS + F), i.e. 1-based TSS-F .. TSS+F-1. Minus strand: (TSS - F, TSS + F], i.e. 1-based TSS-F+1 .. TSS+F, then reverse-complement it (Ensembl GET /sequence/region/human/<chr>:<start>..<end>:-1 does both). Either way the sequence is 2F long with the TSS at offset F.
- Run with
--tss-index F. Near a chromosome end, use the largest symmetric F that fits, down to 4,599, and say so.
import requests
listing = requests.get("https://api.genomicintelligence.ai/v1/tasks/expression/models", timeout=30).json()
F = 4599
for m in listing["models"]:
spec = m.get("bio_spec") or {}
f = spec.get("recommended_flank_bp")
if isinstance(f, int):
cap = spec.get("request_max_bp")
F = max(F, min(f, cap // 2) if isinstance(cap, int) else f)
model = listing["default_model"] # or the model the user named
Check the "Scored window" line in report.md afterwards: it is the part of your sequence the model actually read.
Authentication
The skill requires a Genomic Intelligence partner key in GI_API_KEY. Resolution order:
--api-key <value> CLI flag (explicit override).
GI_API_KEY environment variable.
- Otherwise: the skill raises a
RuntimeError pointing here.
Quick start — ClawBio hackathon key
A shared hackathon-tier key ships in .env.example at the repo root (opt-in only). Caps are per-key and are not published as a fixed number — read RateLimit-Limit / RateLimit-Remaining on any /v1/tasks/ response for the live allowance. The runner keeps them for you: they are in result.json under rate_limit, and a 429 names them on the error line. From wherever the ClawBio files live on your machine:
# Repo root (git clone) — or ~/.claude/plugins/cache/clawbio/clawbio/<version>/ for plugin installs
cp .env.example .env
set -a && source .env && set +a
Production / heavier use
Request an individual key at contact@genomicintelligence.ai, then:
export GI_API_KEY=gi_yourkeyhere
Demo
python clawbio.py run gi-expression --demo
Bundled fixture is HBB centred on its canonical TSS, RC'd to gene-sense, scored with the skill's default K562 description. It was built as in Building the input from a gene: F from the model list, the TSS at offset F. Its header records tss_index, and the skill sends that when --tss-index is not given. If the model list now recommends more flank than the fixture carries, fetch the gene again rather than trusting the bundled length.
Read the predicted value from your own run rather than from this page. Absolute predictions move when the model checkpoint changes, so any figure written here becomes a false claim. What is stable is the relative signal — gene-sense scores far above the genomic strand, and highly-expressed genes score above silent ones in the same cell context. Do not build assertions on an absolute value read from documentation.
Gotchas
- 9,198 bp is a floor, not a fixed size. The endpoint accepts 9,198–500,000 bp (
minLength / maxLength on ExpressionPredictRequest, counted after whitespace is stripped) with the TSS at least 4,599 bp from each end. How far a model reads is its own and can be far more than 9,198 bp: bio_spec.recommended_flank_bp on GET /v1/tasks/expression/models is how much each model wants on each side of the TSS, so size the input as in Building the input from a gene and pass --tss-index. The response reports the part it used as scored_window. An exact 9,198 bp TSS-centred sequence is still accepted without --tss-index, but a longer-context model then sees only that much. Anything shorter than 9,198 bp, longer than 500,000 bp, or missing --tss-index on a non-9,198 bp sequence is a 422 validation_failed — the skill catches all of those locally first. Over-max is a 422, not a 413; 413 is the separate 16 MiB raw-body cap. A TSS closer than 4,599 bp to either end is rejected rather than padded, and there is no opt-out flag.
- A
tss_index error reports at loc: ["body"], never body.tss_index. Both TSS checks are a whole-body validator, so any client branching on the error loc will silently never match. Match on error.code (validation_failed) and use message for display only — and read error.details defensively: for a validation failure it is the declared {errors: [{loc, msg, type}, …]} object.
- A wrong
--tss-index does not error — it lies. Any offset in [4599, len-4599] is legal, so an offset computed against file characters (line-wrapped FASTA newlines) or against a chromosome coordinate instead of an offset into this sequence returns a confident number for the wrong window. Always check the "Scored window" line in report.md. The response reports the applied window as meta.task_specific_counts.scored_window; older responses also echoed it as data.input.scored_window, and this skill falls back to that echo only for them. The submitted length is a separate field, not part of the window: it is meta.sequence_length. Offsets are counted on the whitespace-stripped nucleotide string, so compute the offset against that rather than against the raw file. The parser refuses any base outside ACGTN, so the two differ only by whitespace.
- Gene-sense is mandatory. Minus-strand genes need reverse-complementing. On the bundled HBB fixture the genomic strand scores about an order of magnitude below gene-sense, though the absolute values move with the checkpoint. The wrong strand returns a well-formed low number, not an error.
description wording changes the answer. It is a free-text conditioning input, not an enum, so paraphrases are not equivalent: on the same fixture and the same sequence, "K562", "K562 cells" and the canonical assay-format string give three different predictions, spanning roughly a factor of two in TPM. Pick one phrasing and keep it fixed across anything you intend to compare, and prefer the canonical "assay term name is … biosample summary is …" format the model was trained on.
description is required — in the published schema as well as at runtime, and it is the only key accepted inside expression options. The model is conditioned on it; "assay term name is polyA plus RNA-seq. biosample summary is Homo sapiens [tissue]." is the canonical format.
- TPM scale is not absolute across tissues — useful as a relative ranking within a cell type, not as a precise count prediction.
- Hackathon key is shared —
GI_API_KEY for heavier use.
Output Structure
output_dir/
├── report.md
├── result.json
└── reproducibility/
├── command.sh
└── environment.json
Integration with Bio Orchestrator
Routes here on: "predict expression", "sequence to expression", "TPM prediction", "cell-type expression".
Chains with: gi-promoter → gi-expression (validate predicted promoters by predicting downstream expression), rnaseq-de (compare predicted expression to measured DE results), variant-annotation (compare ref/alt sequence expression for promoter / 5'UTR variants).
Safety
Research and development use. Not for clinical or diagnostic decisions. Predictions are model outputs, not measurements.
1---2name: gi-expression3description: Predict tissue / cell-type expression (log TPM + TPM) from 9,198–500,000 bp of DNA around a TSS, at least 4,599 bp each side (anything but exactly 9,198 bp needs --tss-index) using the Genomic Intelligence G0 Expression model, via the hosted /v1/tasks/expression/predict4 API. The model is conditioned on a free-text cell-type / assay description.5license: MIT6metadata:7 source: https://skillmd.com/skills/clawbio/gi-expression8 openclaw:9 requires:10 bins:11 - python312 env: null13 config: null14 always: false15 emoji: 🧪16 homepage: https://docs.genomicintelligence.ai17 os:18 - darwin19 - linux20 install:21 - kind: pip22 package: requests23 bins: null24 trigger_keywords:25 - expression prediction26 - predict expression27 - sequence to expression28 - TPM prediction29 - cell type expression30 - tissue expression31 - RNA-seq prediction32 - gi expression33 - G0 expression34 - genomic intelligence expression35 author: ClawBio + Genomic Intelligence36 demo_data:37 - path: example_data/expression_hbb_k562.fa38 description: HBB (β-globin), TSS-centred with the flank the model list recommended when it was built, reverse-complemented to gene-sense; the header records tss_index, which the skill sends. K562 is the demo cell context — HBB is highly expressed in K562 erythroleukemia.39 dependencies:40 python: '>=3.10'41 packages:42 - requests>=2.3143 domain: genomics44 endpoints:45 cli: python skills/gi-expression/gi_expression.py --input {input_file} --output {output_dir}46 inputs:47 - name: input_file48 type: file49 format:50 - fa51 - fasta52 - fna53 description: Single-record FASTA, gene-sense (RC minus-strand genes), with --tss-index giving the 0-based TSS offset, at least 4,599 bp from each end (9,198 to 500,000 bp). Size it from the model list as in Building the input from a gene; only an exact 9,198 bp TSS-centred sequence may omit --tss-index.54 required: false55 outputs:56 - name: report57 type: file58 format: md59 description: Markdown report — predicted log(TPM+1), TPM, model + timing.60 - name: result61 type: file62 format: json63 description: Full `{data, meta}` response.64 - name: reproducibility65 type: directory66 description: command.sh + environment.json.67 tags:68 - genomics69 - expression70 - RNA-seq71 - TPM72 - sequence-to-expression73 - dna-lm74 - gi-api75 version: 0.1.076---7778# 🧪 gi-expression7980You are **gi-expression**, a ClawBio agent that calls the **Genomic Intelligence** sequence-to-expression model. Given at least 9,198 bp around a TSS (`--tss-index` unless it is exactly 9,198 bp) and a cell-type description, it returns predicted expression (log TPM + TPM).8182> ⚠️ **Remote inference — opt-in required.** Unlike most ClawBio skills, this skill uploads your FASTA sequence to the hosted Genomic Intelligence API at `https://api.genomicintelligence.ai`. The same models also run interactively at <https://genomicintelligence.ai>. **Do not submit identifiable patient data** without an appropriate data-use agreement. Key setup: see [Authentication](#authentication) below.8384## Trigger8586**Fire this skill when the user says any of:**87- "predict expression for this gene / sequence"88- "what's the expression of this region in [cell type]?"89- "sequence-to-expression prediction"90- "TPM prediction", "log TPM prediction"91- "gi-expression", "G0 expression"9293**Do NOT fire when:**94- The user has counts / RNA-seq output and wants differential expression → `rnaseq-de`95- The user wants tissue annotation / GTEx lookup → use external resources9697## Why This Exists9899- **Without it**: Sequence-to-expression models (Enformer / Borzoi / G0 Expression) need GPU + private weights + careful TSS-centred windowing.100- **With it**: One CLI call → expression prediction conditioned on free-text cell-type description, in <1 s.101- **Why ClawBio**: Private weights, hosted. ClawBio's reproducibility bundle + chaining (`gi-promoter` → `gi-expression` → `rnaseq-de` interpretation).102103## API Backed104105`POST https://api.genomicintelligence.ai/v1/tasks/expression/predict`. Omit `model` and the API resolves the default; `GET /v1/tasks/expression/models` is the current list.106107> **Contract note.** The Genomic Intelligence API publishes one operation per task, each with its own request schema: per-task `minLength`/`maxLength` on `sequence`, and a typed, closed `options` object (an unknown option key is a `422 validation_failed`, not a silent ignore). The bounds quoted in this file are the published ones, but the authority is always the served schema: `GET https://api.genomicintelligence.ai/v1/openapi.json`.108109## Workflow1101111. **Parse**: single-record FASTA, gene-sense, 9,198–500,000 bp with `--tss-index` at least 4,599 bp from each end (an exact 9,198 bp TSS-centred sequence may omit it). Anything else is rejected locally before the request is sent. For a named gene, build the FASTA as in [Building the input from a gene](#building-the-input-from-a-gene).1122. **Build options**: `{"description": "assay term name is polyA plus RNA-seq. biosample summary is Homo sapiens K562."}` by default; override via `--description "..."`.1133. **POST** to `/v1/tasks/expression/predict`, which is its own operation with its own request schema — each of the six tasks has one, so there is no shared predict body.1144. **Render**: `report.md` (headline log TPM plus the scored window the API actually used) + `result.json` + `reproducibility/`.115116## CLI Reference117118```bash119# Demo — HBB in K562120python skills/gi-expression/gi_expression.py --demo --output /tmp/gi-expression-demo121122# Custom cell-type description123python skills/gi-expression/gi_expression.py \124 --input my_tss_window.fa \125 --description "assay term name is polyA plus RNA-seq. biosample summary is Homo sapiens liver." \126 --output report_dir127128# A gene fetched as in "Building the input from a gene": the TSS sits at129# offset F, so --tss-index is F (0-based, counted after whitespace is stripped)130python skills/gi-expression/gi_expression.py \131 --input my_gene.fa --tss-index "$F" \132 --output report_dir133134# Via ClawBio runner135python clawbio.py run gi-expression --demo136```137138## Building the input from a gene139140How much sequence to send is read from the model list at run time, never from this page: the API adds longer-context expression models and changes the default, and a too-short input is still scored, just with less context than the model reads.1411421. **Read the list.** `GET https://api.genomicintelligence.ai/v1/tasks/expression/models` is public (no key). Use the model the user named, else `default_model`, and pass it as `--model` so every call in a run uses the same one.1432. **Pick F**, the flank on each side of the TSS: the largest `bio_spec.recommended_flank_bp` among the listed models, each capped so 2F fits that model's `bio_spec.request_max_bp`, and never below 4,599. One fetch then serves every listed model; a model ignores flank beyond what it reads.1443. **Find the TSS** from the gene's canonical transcript (Ensembl `GET /lookup/symbol/homo_sapiens/<SYMBOL>?expand=1`, then the transcript with `is_canonical`). Plus strand: TSS = transcript `start`. Minus strand: TSS = transcript `end`. Do not fall back to the gene's own start or end; refuse if there is no canonical transcript.1454. **Fetch gene-sense.** Plus strand: genomic `[TSS - F, TSS + F)`, i.e. 1-based `TSS-F .. TSS+F-1`. Minus strand: `(TSS - F, TSS + F]`, i.e. 1-based `TSS-F+1 .. TSS+F`, then reverse-complement it (Ensembl `GET /sequence/region/human/<chr>:<start>..<end>:-1` does both). Either way the sequence is 2F long with the TSS at offset F.1465. **Run** with `--tss-index F`. Near a chromosome end, use the largest symmetric F that fits, down to 4,599, and say so.147148```python149import requests150listing = requests.get("https://api.genomicintelligence.ai/v1/tasks/expression/models", timeout=30).json()151F = 4599152for m in listing["models"]:153 spec = m.get("bio_spec") or {}154 f = spec.get("recommended_flank_bp")155 if isinstance(f, int):156 cap = spec.get("request_max_bp")157 F = max(F, min(f, cap // 2) if isinstance(cap, int) else f)158model = listing["default_model"] # or the model the user named159```160161Check the "Scored window" line in `report.md` afterwards: it is the part of your sequence the model actually read.162163## Authentication164165The skill requires a Genomic Intelligence partner key in `GI_API_KEY`. Resolution order:1661671. `--api-key <value>` CLI flag (explicit override).1682. `GI_API_KEY` environment variable.1693. Otherwise: the skill raises a `RuntimeError` pointing here.170171### Quick start — ClawBio hackathon key172173A shared hackathon-tier key ships in `.env.example` at the repo root (opt-in only). Caps are per-key and are not published as a fixed number — read `RateLimit-Limit` / `RateLimit-Remaining` on any `/v1/tasks/` response for the live allowance. The runner keeps them for you: they are in `result.json` under `rate_limit`, and a `429` names them on the error line. From wherever the ClawBio files live on your machine:174175```bash176# Repo root (git clone) — or ~/.claude/plugins/cache/clawbio/clawbio/<version>/ for plugin installs177cp .env.example .env178set -a && source .env && set +a179```180181### Production / heavier use182183Request an individual key at **contact@genomicintelligence.ai**, then:184185```bash186export GI_API_KEY=gi_yourkeyhere187```188189## Demo190191```bash192python clawbio.py run gi-expression --demo193```194195Bundled fixture is HBB centred on its canonical TSS, RC'd to gene-sense, scored with the skill's default K562 description. It was built as in [Building the input from a gene](#building-the-input-from-a-gene): F from the model list, the TSS at offset F. Its header records `tss_index`, and the skill sends that when `--tss-index` is not given. If the model list now recommends more flank than the fixture carries, fetch the gene again rather than trusting the bundled length.196197> Read the predicted value from your own run rather than from this page. Absolute predictions move when the model checkpoint changes, so any figure written here becomes a false claim. What is stable is the *relative* signal — gene-sense scores far above the genomic strand, and highly-expressed genes score above silent ones in the same cell context. Do not build assertions on an absolute value read from documentation.198199## Gotchas200201- **9,198 bp is a floor, not a fixed size.** The endpoint accepts 9,198–500,000 bp (`minLength` / `maxLength` on `ExpressionPredictRequest`, counted after whitespace is stripped) with the TSS at least 4,599 bp from each end. How far a model reads is its own and can be far more than 9,198 bp: `bio_spec.recommended_flank_bp` on `GET /v1/tasks/expression/models` is how much each model wants on each side of the TSS, so size the input as in [Building the input from a gene](#building-the-input-from-a-gene) and pass `--tss-index`. The response reports the part it used as `scored_window`. An exact 9,198 bp TSS-centred sequence is still accepted without `--tss-index`, but a longer-context model then sees only that much. Anything shorter than 9,198 bp, longer than 500,000 bp, or missing `--tss-index` on a non-9,198 bp sequence is a `422 validation_failed` — the skill catches all of those locally first. Over-max is a 422, *not* a 413; 413 is the separate 16 MiB raw-body cap. A TSS closer than 4,599 bp to either end is rejected rather than padded, and there is no opt-out flag.202- **A `tss_index` error reports at `loc: ["body"]`, never `body.tss_index`.** Both TSS checks are a whole-body validator, so any client branching on the error `loc` will silently never match. Match on `error.code` (`validation_failed`) and use `message` for display only — and read `error.details` defensively: for a validation failure it is the declared `{errors: [{loc, msg, type}, …]}` object.203- **A wrong `--tss-index` does not error — it lies.** Any offset in `[4599, len-4599]` is legal, so an offset computed against file characters (line-wrapped FASTA newlines) or against a chromosome coordinate instead of an offset into *this* sequence returns a confident number for the wrong window. Always check the "Scored window" line in `report.md`. The response reports the applied window as `meta.task_specific_counts.scored_window`; older responses also echoed it as `data.input.scored_window`, and this skill falls back to that echo only for them. The submitted length is a separate field, not part of the window: it is `meta.sequence_length`. Offsets are counted on the whitespace-stripped nucleotide string, so compute the offset against that rather than against the raw file. The parser refuses any base outside `ACGTN`, so the two differ only by whitespace.204- **Gene-sense is mandatory.** Minus-strand genes need reverse-complementing. On the bundled HBB fixture the genomic strand scores about an order of magnitude below gene-sense, though the absolute values move with the checkpoint. The wrong strand returns a well-formed low number, not an error.205- **`description` wording changes the answer.** It is a free-text conditioning input, not an enum, so paraphrases are not equivalent: on the same fixture and the same sequence, `"K562"`, `"K562 cells"` and the canonical assay-format string give three different predictions, spanning roughly a factor of two in TPM. Pick one phrasing and keep it fixed across anything you intend to compare, and prefer the canonical `"assay term name is … biosample summary is …"` format the model was trained on.206- **`description` is required** — in the published schema as well as at runtime, and it is the *only* key accepted inside expression `options`. The model is conditioned on it; "assay term name is polyA plus RNA-seq. biosample summary is Homo sapiens [tissue]." is the canonical format.207- **TPM scale is not absolute** across tissues — useful as a relative ranking within a cell type, not as a precise count prediction.208- **Hackathon key is shared** — `GI_API_KEY` for heavier use.209210## Output Structure211212```213output_dir/214├── report.md215├── result.json216└── reproducibility/217 ├── command.sh218 └── environment.json219```220221## Integration with Bio Orchestrator222223Routes here on: "predict expression", "sequence to expression", "TPM prediction", "cell-type expression".224225Chains with: `gi-promoter` → `gi-expression` (validate predicted promoters by predicting downstream expression), `rnaseq-de` (compare predicted expression to measured DE results), `variant-annotation` (compare ref/alt sequence expression for promoter / 5'UTR variants).226227## Safety228229Research and development use. Not for clinical or diagnostic decisions. Predictions are model outputs, not measurements.