> ## Documentation Index
> Fetch the complete documentation index at: https://proto.evodesign.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Genomic Intelligence
> [Genomic Intelligence](https://genomicintelligence.ai) serves transformer DNA language models that score regulatory function directly from sequence. This toolkit exposes seven tools over its [`/v1` REST API](https://docs.genomicintelligence.ai): `gi-promoter` (promoter regions), `gi-splice` (donor and acceptor sites), `gi-enhancer` (enhancer activity), `gi-chromatin` (chromatin state), `gi-annotation` (de-novo transcripts), `gi-expression` (expression from a TSS window), and `gi-find-genes-and-predict-expression` (both, in one call). Inference runs on the vendor's service, so no weights are downloaded and no GPU is needed.
**License:** Genomic Intelligence is a client for the hosted Genomic Intelligence API; inference runs on the vendor's service under Genomic Intelligence Terms of Service. Submitted sequences are transmitted to Genomic Intelligence. Attribution to Genomic Intelligence is required when results are redistributed. The client wrapper code is MIT-licensed. Please refer to [the service terms](https://docs.genomicintelligence.ai) for full terms. Research and development use. Not for clinical or diagnostic decisions.
Proto is not affiliated with Genomic Intelligence. This toolkit is open source and builds on the implementation produced by this organization. Product names, logos, and trademarks are the property of their respective owners.
| Function | Description | |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_gi_annotation()` | Find genes and transcripts de novo in raw DNA via the hosted Genomic Intelligence API | Docs Source |
| `run_gi_chromatin()` | Predict chromatin accessibility, TF occupancy and histone marks via the hosted Genomic Intelligen... | Docs Source |
| `run_gi_enhancer()` | Predict developmental and housekeeping enhancer activity via the hosted Genomic Intelligence API | Docs Source |
| `run_gi_expression()` | Predict gene expression from a TSS-centred window via the hosted Genomic Intelligence API | Docs Source |
| `run_gi_find_genes_and_predict_expression()` | Annotate genes in a locus and predict expression for each, via the hosted Genomic Intelligence API | Docs Source |
| `run_gi_promoter()` | Predict promoter regions in DNA via the hosted Genomic Intelligence API | Docs Source |
| `run_gi_splice()` | Predict splice donor and acceptor sites via the hosted Genomic Intelligence API | Docs Source |
> This toolkit was developed by [Genomic Intelligence](https://genomicintelligence.ai/).
## Background
Sequence-to-function models predict regulatory readouts from DNA alone, without an assay. Genomic Intelligence hosts a family of them behind one API: promoter and enhancer classifiers, a splice-site model, a chromatin-state panel spanning accessibility, transcription-factor occupancy and histone marks, a structure-aware gene finder, and an expression model conditioned on experimental context. Each task is a separate published operation with its own request schema and its own minimum input length, so bounds are per task rather than global.
Every tool here is a thin HTTPS client. A request carries the sequence and the task's options; the service resolves which model version to run, so `model` is left unset by default and the alternatives are enumerable through `GET /v1/tasks/{task}/models`. Delivery is a per-request choice on every endpoint: omitting the `Prefer` header returns the result synchronously, while `respond_async` returns a job id to poll. Coordinates in tool outputs are 0-based with exclusive ends, following the genomics interval convention used elsewhere in `sequence_scoring` rather than the 1-based residue numbering used across the rest of proto-tools.
### Learning Resources
* [Genomic Intelligence API reference](https://docs.genomicintelligence.ai) (Genomic Intelligence) - endpoint documentation, worked examples, and the per-task input bounds.
* [OpenAPI document](https://api.genomicintelligence.ai/v1/openapi.json) (Genomic Intelligence) - the machine-readable contract: every field, bound, enum and status code.
## Tools
### GI Promoter (`gi-promoter`)
Slides a promoter classifier across the sequence and returns the windows called as promoters, the contiguous regions they form, and the per-window probabilities behind both.
#### API Reference
Source
Sequences to score. A bare DNA string is accepted and coerced. Each must be at least 300 bp, the endpoint's published floor.
DNA sequence. Length bounds are per task and are checked against the endpoint's published values before any request.
Label echoed back in the response, useful for correlating results in a batch.
Source
Probability above which a window is called a promoter. Applied server-side.
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run the tool on.
Maximum execution time in seconds. `None` waits indefinitely.
Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
Bearer key for the hosted API. Defaults to the `GI_API_KEY` environment variable.
Model identifier. Leave unset: the service resolves the current default for the task.
Request `202` + polling instead of a synchronous `200`. A per-request delivery choice available on every endpoint.
Wall-clock cap on the async wait.
Source
One result per submitted sequence, in the order submitted.
Label supplied with the sequence.
Length of the submitted sequence in base pairs.
Number of windows that cleared the threshold.
Number of windows scored.
Highest window probability, or None when no window was scored.
Regions called as promoters.
Every scored window.
Provenance for the call.
#### Applications
Use this to locate transcription start regions in unannotated sequence, or to score designed constructs for promoter strength inside an optimization loop. The per-window probabilities make it usable as a fitness signal rather than only a binary call.
#### Usage Tips
* **Minimum input is 300 bp.** This is a task floor published on the endpoint's request schema, so selecting a different `model` does not lower it.
* **Windows shorter than the model's context are padded.** A short sequence still scores, but the model sees padding; compare against the model's context window when interpreting a marginal call.
* **`threshold` is applied server-side.** Lowering it returns more regions without re-running inference.
### GI Splice Sites (`gi-splice`)
Predicts splice donor and acceptor sites, returning each site's span, class and score together with per-class counts.
#### API Reference
Source
Sequences to score, in transcript orientation. A bare DNA string is accepted and coerced. Each must be at least 100 bp, the endpoint's published floor.
DNA sequence. Length bounds are per task and are checked against the endpoint's published values before any request.
Label echoed back in the response, useful for correlating results in a batch.
Source
Score above which a position is reported as a site. Values at or near zero return every scored position and produce very large responses; the default is a good working value.
Restrict the reported site classes. Leave unset to report both.
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run the tool on.
Maximum execution time in seconds. `None` waits indefinitely.
Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
Bearer key for the hosted API. Defaults to the `GI_API_KEY` environment variable.
Model identifier. Leave unset: the service resolves the current default for the task.
Request `202` + polling instead of a synchronous `200`. A per-request delivery choice available on every endpoint.
Wall-clock cap on the async wait.
Source
One result per submitted sequence, in the order submitted.
Label supplied with the sequence.
Length of the submitted sequence in base pairs.
Number of sites reported.
Number of donor sites reported.
Number of acceptor sites reported.
The reported sites.
Provenance for the call.
#### Applications
Use this to locate exon boundaries in unannotated transcripts, to check whether a designed edit creates or destroys a splice site, or to screen variants for splice disruption.
#### Usage Tips
* **Submit transcript orientation.** The model is strand-specific, and the wrong strand does not fail loudly: it returns sites at different positions, frequently at high confidence. No score or count identifies a mis-oriented submission after the fact, so reverse-complement minus-strand genes before calling.
* **A site's `start`/`end` is a token span, not the junction base.** It bounds one variable-width tokenizer token — 4–10 bp across the sequences measured so far — and the exon/intron boundary lies somewhere inside it. Locate a boundary to within the span; do not reduce the pair to a single base position, and do not intersect it against reference annotation as though it were one.
* **Minimum input is 100 bp.**
* **Very low thresholds return every scored position.** The response grows accordingly; the default is a working value.
### GI Enhancer Activity (`gi-enhancer`)
Scores developmental and housekeeping enhancer activity per window, following the STARR-seq split between the two programmes.
#### API Reference
Source
Sequences to score. A bare DNA string is accepted and coerced. Each must be at least 50 bp, the endpoint's published floor.
DNA sequence. Length bounds are per task and are checked against the endpoint's published values before any request.
Label echoed back in the response, useful for correlating results in a batch.
Source
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run the tool on.
Maximum execution time in seconds. `None` waits indefinitely.
Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
Bearer key for the hosted API. Defaults to the `GI_API_KEY` environment variable.
Model identifier. Leave unset: the service resolves the current default for the task.
Request `202` + polling instead of a synchronous `200`. A per-request delivery choice available on every endpoint.
Wall-clock cap on the async wait.
Source
One result per submitted sequence, in the order submitted.
Label supplied with the sequence.
Length of the submitted sequence in base pairs.
Number of windows scored.
Highest developmental score.
Highest housekeeping score.
Every scored window.
Provenance for the call.
#### Applications
Use this to rank candidate enhancers, or as a dual-objective fitness function when designing regulatory elements that favour one programme over the other.
#### Usage Tips
* **Minimum input is 50 bp**, the lowest floor in the toolkit.
* **The developmental/housekeeping split is a *Drosophila* assay definition.** Read the two scores as relative activity within a comparison rather than as calibrated cross-species values.
* **The endpoint declares no task-specific options.** Only the shared configuration applies.
### GI Chromatin State (`gi-chromatin`)
Scores each window against a large panel of chromatin assays across many cell types, returning how many calls clear the threshold, per window and per assay category.
#### API Reference
Source
Sequences to score. A bare DNA string is accepted and coerced. Each must be at least 200 bp, the endpoint's published floor.
DNA sequence. Length bounds are per task and are checked against the endpoint's published values before any request.
Label echoed back in the response, useful for correlating results in a batch.
Source
Probability above which an assay call is reported. The panel is large, so lowering this materially increases response size.
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run the tool on.
Maximum execution time in seconds. `None` waits indefinitely.
Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
Bearer key for the hosted API. Defaults to the `GI_API_KEY` environment variable.
Model identifier. Leave unset: the service resolves the current default for the task.
Request `202` + polling instead of a synchronous `200`. A per-request delivery choice available on every endpoint.
Wall-clock cap on the async wait.
Source
One result per submitted sequence, in the order submitted.
Label supplied with the sequence.
Length of the submitted sequence in base pairs.
Number of windows scored.
Assay calls above the threshold, summed.
Calls per assay category.
Per-window call counts.
Provenance for the call.
#### Applications
Use this to ask whether a sequence looks accessible, bound, or marked in a given cellular context, and to compare designed variants against a natural reference across many assays at once.
#### Usage Tips
* **Minimum input is 200 bp.**
* **The panel is large.** Lowering `threshold` materially increases the size of the response the service returns.
* **Calls span many cell types and assays.** The tool reports totals and per-category counts rather than the individual calls, so a high count is not evidence about any one cellular context.
### GI Gene Annotation (`gi-annotation`)
Finds transcripts de novo in raw sequence with no reference, returning each transcript's bounds, strand, confidence score, and TSS and poly(A) positions.
#### API Reference
Source
Sequences to annotate. A bare DNA string is accepted and coerced. Each must be at least 1,000 bp, the endpoint's published floor.
DNA sequence. Length bounds are per task and are checked against the endpoint's published values before any request.
Label echoed back in the response, useful for correlating results in a batch.
Source
Server-side batching hint. Leave unset for the service default.
Also scan the reverse complement. Detection already finds genes on either strand, so this changes the reported orientation rather than whether genes are found.
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run the tool on.
Maximum execution time in seconds. `None` waits indefinitely.
Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
Bearer key for the hosted API. Defaults to the `GI_API_KEY` environment variable.
Model identifier. Leave unset: the service resolves the current default for the task.
Request `202` + polling instead of a synchronous `200`. A per-request delivery choice available on every endpoint.
Wall-clock cap on the async wait.
Source
One result per submitted sequence, in the order submitted.
Label supplied with the sequence.
Length of the submitted sequence in base pairs.
Number of transcripts found.
Transcripts on the submitted orientation.
Transcripts on the opposite orientation.
The transcripts found.
Provenance for the call.
#### Applications
Use this to annotate assembled contigs or synthetic constructs where no reference annotation exists, and to supply TSS positions to `gi-expression` when they are not known in advance.
#### Usage Tips
* **Minimum input is 1,000 bp**, the highest floor apart from expression.
* **Detection is strand-insensitive.** Genes on either strand are found from a single submission, and the reported `strand` is relative to the sequence as submitted.
* **This is the slowest task.** Setting `respond_async` returns a job id and polls it, which avoids holding a long request open. That is a latency preference, not a requirement.
### GI Gene Expression (`gi-expression`)
Predicts expression as log(TPM+1) from a single 9,198 bp window centred on a transcription start site, conditioned on a free-text description of the experimental context.
#### API Reference
Source
Loci to score, each carrying its own TSS offset where needed.
Either exactly 9,198 bp centred on the TSS, or a longer locus paired with `tss_index`.
Label echoed back in the response.
0-based TSS offset into the whitespace-stripped sequence. Required unless the sequence is exactly 9,198 bp, where it defaults to the midpoint. Must satisfy `4599 <= tss_index <= len(sequence) - 4599`.
Source
Experimental context the model is conditioned on — cell type, assay, conditions. Required. This is model input, not a
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run the tool on.
Maximum execution time in seconds. `None` waits indefinitely.
Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
Bearer key for the hosted API. Defaults to the `GI_API_KEY` environment variable.
Model identifier. Leave unset: the service resolves the current default for the task.
Request `202` + polling instead of a synchronous `200`. A per-request delivery choice available on every endpoint.
Wall-clock cap on the async wait.
Source
One result per submitted locus, in the order submitted.
Label supplied with the sequence.
Length of the submitted sequence in base pairs, whitespace-stripped. Read from `meta`, not from `data.input`: the echo carries a field of the same name holding the 9,198 bp window instead, and only `meta` is in the published schema.
Predicted log(TPM+1).
Predicted TPM.
TSS offset the service applied.
Window the service actually scored, as `[start, end)` in the submitted sequence.
Provenance for the call.
#### Applications
Use this to estimate the transcriptional output of a locus or a designed promoter under a stated cellular context, and as the objective in an expression-maximizing or expression-matching design loop.
#### Usage Tips
* **The window is exact.** Submit exactly 9,198 bp centred on the TSS, or a longer locus plus `tss_index` and let the service cut it. Under-length input is rejected rather than padded.
* **`description` is conditioning text, not a label.** It is fed to the model, so rewording it changes the prediction. Hold it fixed across runs you intend to compare.
* **An in-range but wrong `tss_index` still scores.** It simply scores a different window, so the tool reads the applied window back from the response rather than assuming the request's.
* **The sequence is never reverse-complemented.** Submit minus-strand genes in transcript orientation.
### GI Find Genes and Predict Expression (`gi-find-genes-and-predict-expression`)
Runs annotation over a locus and then predicts expression for every gene found, centring each window on that gene's own TSS.
#### API Reference
Source
Loci to process. A bare DNA string is accepted and coerced. Each must be at least 1,000 bp, the endpoint's published floor.
DNA sequence. Length bounds are per task and are checked against the endpoint's published values before any request.
Label echoed back in the response, useful for correlating results in a batch.
Source
Experimental context applied to every gene found. Conditioning text fed to the expression model, so its wording changes the predictions. The service requires it even though the published schema marks it optional.
Override the annotation stage's model. Leave unset.
Override the expression stage's model. Leave unset.
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Device to run the tool on.
Maximum execution time in seconds. `None` waits indefinitely.
Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
Bearer key for the hosted API. Defaults to the `GI_API_KEY` environment variable.
Model identifier. Leave unset: the service resolves the current default for the task.
Request `202` + polling instead of a synchronous `200`. A per-request delivery choice available on every endpoint.
Wall-clock cap on the async wait.
Source
One result per submitted locus, in the order submitted.
Label supplied with the sequence.
Length of the submitted sequence in base pairs.
Genes the annotation stage reported.
Genes expression was predicted for.
One record per gene found.
Provenance for the call.
#### Applications
Use this when the TSS positions are not known in advance — annotating and scoring a whole locus in one call — rather than chaining `gi-annotation` into `gi-expression` yourself.
#### Usage Tips
* **Minimum input is 1,000 bp**, and the ceiling is the endpoint's own 500,000 bp, which is not the expression model's window.
* **This is the only endpoint with a delivery rule.** A synchronous request above 50,000 bp is refused; the tool switches to polling automatically.
* **Genes too close to a sequence boundary are skipped**, with the reason reported, because there is not enough flanking sequence for a full window.
* **JSON only.** Unlike the predict endpoints, it declares no text output format.
## Toolkit Notes
These apply to every tool in this toolkit (`gi-promoter`, `gi-splice`, `gi-enhancer`, `gi-chromatin`, `gi-annotation`, `gi-expression`, `gi-find-genes-and-predict-expression`).
* **Requires network access and an API key.** Every tool calls the hosted Genomic Intelligence API. None runs offline, and no weights are downloaded. Set `GI_API_KEY`, or pass `gi_api_key` in the config; request a key at [genomicintelligence.ai](https://genomicintelligence.ai). The key is excluded from the cache key, so rotating it does not invalidate cached results.
* **No GPU is used.** Inference runs on the vendor's hardware, so these are CPU-local clients regardless of what is available on the host.
* **Every tool takes a list and returns one result per input, in order.** That is the shape a Constraint or Optimizer consumes when scoring a population. A bare DNA string is accepted in place of a list.
* **Length bounds are checked locally before any request.** Each task's floor comes from its own published request schema; every task caps at 500,000 bp.
* **Leave `model` unset.** The service resolves the current default per task, and pinning an identifier means a retired model fails hard. Enumerate the alternatives with `GET /v1/tasks/{task}/models`.
* **Errors carry a machine-readable code from a closed enum** plus a `request_id` for support. Branch on the code rather than the HTTP status.
* **A malformed 2xx is refused, not coerced.** A response that is well-formed HTTP but contradicts the published shape raises rather than parsing to zeros: a body that is not a `{data, meta}` envelope, or whose `data` is missing or empty, raises `GIAPIError` carrying the status and `request_id`; a field inside `data` that is documented as an object or an array and arrives as something else raises `GIResponseShapeError` naming that field. Absent and null members stay legitimate, since a task with nothing to report omits them.
**Example notebook:** See the [full working example](https://github.com/evo-design/proto-tools/blob/55339880a8d5da4f1c7677518bcf90974a6365b7/proto_tools/tools/sequence_scoring/genomic_intelligence/examples/example.ipynb) for a copy-paste-ready walkthrough.
## Infrastructure Guides
The following guides cover how to run tools efficiently and at scale.
Keep a tool's model warm across calls instead of reloading it every invocation.How GPUs are allocated to tools and how to target specific devices.Fan a batch of inputs out across multiple GPUs.
evo-design/proto-tools/proto\_tools/tools/sequence\_scoring/genomic\_intelligence
Genomic Intelligence