helix-dsl 0.1.1

Helix — a declarative DSL and compiler for reproducible gene-editing design.

Helix

A declarative DSL & compiler for reproducible gene-editing design.

Quickstart · Highlights · The language · Architecture · MCP server · Deep dive

Most agentic gene-editing tools are chat interfaces that produce a one-off answer. Helix treats an editing experiment as source code: you write a small declarative spec (the intent), and a deterministic compiler — assisted by narrowly-scoped LLM agents — turns it into a fully resolved, provenance-stamped design you can diff, version, review, and re-run.

The key rule: agents may only emit or edit a spec; only the deterministic compiler produces the design. That keeps the trust boundary auditable and every run reproducible — the same audit trail that protects a human protects an agent.

Highlights

• 🧬 8 modalities — knockout · base editing (CBE/ABE/CGBE) · prime editing · HDR knock-in · dual-cut deletion · CRISPRi / CRISPRa.
• 🎯 Constraints are first-class — the compiler solves against them and reports infeasibility, instead of silently returning "the top N".
• 🔬 Protein-consequence aware — every coding edit is called silent · missense · premature-STOP (iSTOP) · stop-loss · frameshift, with guaranteed-synonymous HDR PAM-blocks.
• 🧪 Variant-aware guides — flags common population SNPs in the seed/PAM (a SNP there abolishes binding in carriers).
• 🔌 Injectable backends — swap a heuristic for a real tool (Cas-OFFinder, inDelphi, BE-Hive, PRIDICT, Ensembl/NCBI, ESMFold) by editing the spec, not the code.
• 🤖 MCP server + LLM agents — any agent can drive the compiler through the spec → compile boundary.
• 🖥️ Web UI — syntax-highlighting editor, interactive 3D helix, order-ready oligos, and results analysis.
• ♻️ Reproducible & auditable — every design is provenance-stamped; diff and version it in git.

Quickstart

pip install helix-dsl                                       # or: pip install -e '.[all]'

helix compile examples/tp53_ko.hx -o out                    # knockout (SpCas9)
helix compile examples/istop_base_edit.hx                   # base editing → iSTOP knockout
helix compile examples/tp53_prime_edit.hx                   # prime editing (pegRNA)
helix compile examples/tp53_knock_in.hx                     # HDR knock-in (cut + donor)
helix compile examples/tp53_ko_ensembl.hx                   # resolves TP53 from Ensembl (network)
helix validate examples/tp53_ko.hx                          # parse + safety screen only

compile prints a Markdown protocol and (with -o) writes out/design.json (the reproducible record) and out/protocol.md (what a bench scientist reads). See all eight modalities in examples/.

The language

A Helix spec can be written in the Helix grammar (.hx) or YAML — both compile to the same validated ExperimentSpec.

helix "TP53_KO_HEK293" {
  organism: human(GRCh38)
  profile:  strict                                 # preset efficiency / off-target / GC / hairpin defaults
  target: gene(TP53) { goal: knockout; region: exon(2..4); frame: 0 }
  strategy { modality: crispr_ko; enzyme: auto }   # `auto` → the compiler picks (delivery-aware)
  constraints {
    on_target.min_efficiency: 0.5
    off_target.max_cfd: 0.2
    gc.min: 0.4                                     # spacer GC window
    guides.count: 3
    avoid: [ homopolymer(>=4), self_complementary(>=8), common_variant(>=0.01) ]
  }
  simulate { sequence_provider: ensembl; on_target: rule_set_1; variant_source: ensembl }
  deliver: rnp
  validate: amplicon_seq
}

• Guide-quality constraints — GC window, hairpin/self-complementarity, homopolymer, and restriction-site filters, each reported as a pass/fail check in the drill-down. profile: strict | lenient | screen | quick presets sensible defaults; anything you write overrides them.
• frame: 0 unlocks the protein-consequence calls above and the guaranteed-synonymous HDR PAM-block.
• variant_source: ensembl + avoid: [common_variant(>=0.01)] reject guides with a common SNP in the seed/PAM.

Full grammar → GRAMMAR.md.

Architecture

Three layers:

1. Helix Studio — author and review a spec via the CLI, Web UI, or MCP (agents). The spec is the reviewable artifact.
2. Deterministic compiler — a fixed pipeline (safety → strategy → target → guides → simulate → constraints → primers) plus narrowly-scoped LLM agents/builders and a provenance-stamped design store. Agents only touch the spec; the compiler owns the design.
3. Simulate & score — pluggable backends score each candidate. Heuristics run offline by default; a spec edit swaps in a real tool.

Everything routes through injectable adapter Protocols, so the whole spine is testable offline and a real tool drops in behind the same interface. Deep dive → ARCHITECTURE.md.

MCP server — gene-editing design for agents

Agents are good at writing a constrained spec and bad at safely orchestrating raw bioinformatics tools — exactly the split Helix is built around. So Helix ships as an MCP server: any MCP-capable agent (Claude, etc.) drives the compiler, but only through the spec → compile boundary.

helix mcp        # stdio JSON-RPC server, zero extra deps   (== python3 -m helix.mcp)

// register with an MCP client
{ "mcpServers": { "helix": { "command": "helix", "args": ["mcp"] } } }

Tools: helix_reference (grammar + guide + examples), helix_compile (spec → ranked, safety-screened design summary), helix_resolve_gene (symbol → sequence + locus), helix_list_models (selectable backends). MCP is simply a fourth transport (alongside HTTP / subprocess / import) that connects agents to the compiler.

Backends

The deterministic spine runs fully offline on honest, clearly-labelled heuristics; each is a drop-in target for a real tool behind the same Protocol — selected by a spec edit.

role	built-in	real tool (same interface)	status
sequence	inline	ensembl, ncbi, fallback (Ensembl→NCBI)	✅ live + fallback
on-target	heuristic_gc	rule_set_1 (Doench 2014)	✅ wired
off-target	mock_seed	cas_offinder_cfd (CFD; scan needs a genome)	✅ wired
repair outcome	mock_indel	indelphi (Shen 2018)	✅ wired
base-edit outcome	window_heuristic	behive (Arbab 2020)	✅ wired
prime-edit outcome	pe_heuristic	pridict (Mathis 2023)	✅ wired
structure / folding	esmfold (real, no key)	AlphaFold3 / Boltz (HELIX_FOLDING_BIN)	✅ ESMFold live

The verified-real cores (Doench 2014, Doench 2016 CFD) are pure and always on; heavy models sit behind injectable boundaries — configured in when a genome/tool is present, and raising a clear error otherwise so the mock_* path always runs offline.

Web UI

An interactive frontend (React + TypeScript, Vite) over a FastAPI backend — compile a spec and inspect ranked guides/pegRNAs, outcome metrics, feasibility, safety, provenance, and a delivery recommendation, in three views (Table · 3D helix · Cas9 complex). The helix is interactive: click a base to place an edit, drag to sweep it, and the compiler recompiles (a 3D → spec round-trip). Batch and Library modes, a design compare, a design-aware Models page, and a server-persisted run history round it out.

# One-command product: build the UI once, then serve UI + API on one origin.
cd frontend && npm install && npm run build && cd ..
pip install -e '.[web]' && helix serve       # full app on http://localhost:8000

Advanced — LLM agents · analysis loop · delivery · order export

• LLM agents (opt-in, ANTHROPIC_API_KEY) — helix author turns English into a .hx spec (validated by the real parser, self-repairing on error); --strategy llm|rag resolves enzyme: auto (RAG cites a literature corpus); helix critique flags weaknesses and proposes IR-validated constraint edits; helix refine runs critique → recompile autonomously until convergence. The LLM sits behind an injectable client, fully tested offline with a fake.
• Design → validate → analyse loop — helix analyze runs CRISPResso2 on amplicon reads and reconciles observed editing against the design's prediction. In the UI, an Analyze card does the same with a pure-Python caller (no install needed).
• Order-ready oligos — every design exports guide cloning oligos (Golden Gate), pegRNA extensions, ssODN donors, and validation primers as a table + IDT CSV with a rough cost.
• Delivery-aware strategy — recommends RNP / plasmid / LNP / AAV from cargo size and context, honouring the single-AAV limit (an AAV knockout with enzyme: auto picks the compact SaCas9).
• Gene database — resolve a symbol to its edit window live from Ensembl / NCBI; the Models page lists every backend with a live ready / needs-setup status.

License

Apache-2.0.