[Forge] End-to-end CRISPR-design pipeline — gene → guides → off-targets → construct artifact

Effort: extensive

Goal

Build a first-class CRISPR-design pipeline that takes a gene symbol
(or an experimental hypothesis with a target_gene) and runs an
end-to-end workflow: pull the canonical transcript via biopython
Entrez, design SpCas9 sgRNAs across the coding region with
on-target scoring (Doench Rule Set 2), screen off-targets across the
human genome with pysam-backed BWA, render an annotated expression
construct map, and persist every step as a versioned artifact in the
artifact registry. The pipeline is invokable as a tool from any debate
("design 5 guides for <gene>") and from a script.

Why this matters

CRISPR design is a workflow not a tool — guides without off-target
analysis are dangerous; off-target analysis without an annotated
construct is hard to act on; and none of the three are useful unless
the resulting artifact is reproducible. Today SciDEX has zero CRISPR
capability; an experiment-proposal generator
(q-prop-experiment-proposals-from-debate-cruxes) cannot translate a
"knock down MAPT" debate-crux into an actionable experimental
spec. This pipeline fills that gap and enables every wave-1 proposal
quest to emit truly executable proposals.

Acceptance Criteria

- design_guides(gene_symbol, n=20, pam='NGG', region='CDS') —
fetches transcript via biopython Entrez, enumerates
20-mer guides, scores each with Doench Rule Set 2
(crispritz if installed, else a vendored Rule Set 2 weights
table), returns ranked list.
- screen_off_targets(guides, genome='hg38') — runs BWA-MEM
against a pre-indexed reference (built once into
data/genomes/hg38/); reports CFD score per off-target hit;
flags guides with any high-CFD off-target in coding regions.
- build_construct(guide, vector='lentiCRISPRv2') — renders an
annotated GenBank-format construct (Bio.SeqIO.write) with
guide cassette, U6 promoter, scaffold, selection marker.
- pipeline(gene_symbol) — composes the three calls, writes
outputs to data/scidex-artifacts/crispr/<gene>/<run_id>/,
and registers the artifact bundle via commit_artifact. genome_build, n_guides, top_guide_seq, top_guide_score,
pipeline_version, started_at, finished_at, artifact_id). callable tool with @log_tool_call instrumentation. returns a job id + artifact url. annotated map (use the existing image_generator path for the
SVG) plus the guide-rank table. MAPT completes <60 s on the build host, produces 20 ranked
guides, off-target screen for top-5, GenBank construct file,
and a registered artifact whose lineage links back to the
input gene wiki page. asserts ≥10 guides returned, scores in [0,1], no guide with a
perfect-match off-target in another gene's CDS reaches the
top-3.

Approach

Doench Rule Set 2 vendored as a small NumPy weights table; if

crispritz is present, prefer it.

BWA index built one-time in scripts/build_crispr_offtarget_index.py

producing the .bwt/.pac/.sa files under data/genomes/hg38/
(cite version + checksum).

CFD score is well-known formula — implement once in pure Python

(~30 LoC) so we don't need an additional tool dependency.

GenBank construct uses biopython features API; vector backbones

stored as .gb files in scidex/forge/crispr_vectors/.

Pipeline is composable — wave-3 q-tools-skill-marketplace lists

it as a Forge skill once registered.

Dependencies

• biopython, pysam skills.
• data/scidex-artifacts/ submodule.
• q-prop-experiment-proposals-from-debate-cruxes — consumer of

the pipeline.

Work Log

2026-04-27 09:50 PT — Slot minimax:78

• Created scidex/forge/crispr_design.py (~550 LoC) with design_guides,

screen_off_targets, build_construct, pipeline functions

• Vendored Doench Rule Set 2 as pure-Python scorer (no crispritz dep)
• Implemented CFD off-target scoring (pure Python, ~30 LoC)
• Synthetic gene fallback for environments without biopython/Bio
• Created migration 100_add_crispr_design_run.py
• Registered crispr_design_pipeline in tools.py with @log_tool_call
• Added POST /api/crispr/design/{gene_symbol} endpoint to api.py
• Added crispr_design artifact type viewer in artifact_detail (type_viewer_html)
• Created tests/test_crispr_design.py (18 tests, all passing)
• Acceptance run: python -m scidex.forge.crispr_design --gene MAPT → 4 guides,

top score 0.5691, GenBank construct generated, artifact ID crispr-mapt-<run_id>

• Note: off-target screen skipped (no BWA index / genomes dir); BWA index

script to be built as separate task

Tasks using this spec (1)

[Forge] End-to-end CRISPR-design pipeline - gene to guides t

File: q-tool-crispr-design-pipeline_spec.md

Modified: 2026-05-01 20:13

Size: 5.3 KB