alleleforge

## What it is AlleleForge is a research-oriented design framework for CRISPR genome editing that starts from a broken allele rather than from a guide. You supply a variant — ClinVar entry, rsID, HGVS, VCF or raw coordinates — and the pipeline resolves it, routes it to the eligible editing chemistries, enumerates candidate guides/pegRNAs, scores them, and returns a ranked menu of candidate edits. Three chemistries are covered: SpCas9 nuclease, base editors (ABE/CBE) and prime editing, which the project treats as its flagship modality. Each candidate carries a predicted edit outcome, an uncertainty interval, and an off-target report. Everything is exposed through three shells over one core: a Python library, an `aforge` command-line interface, and a web UI (FastAPI backend with a Next.js frontend). ## Uncertainty and safety reporting Predictions are never bare floats. Each numeric result ships with an interval, the method that produced it, and a `calibrated` flag indicating whether the interval was fitted against held-out coverage. Out-of-the-box, weight-free defaults are heuristics and report `calibrated=False`. Interval recalibration uses split-conformal methods and probability calibration uses isotonic regression, with `empirical_coverage`/ECE surfacing when either is needed. Off-target analysis is population- and haplotype-aware, but explicitly opt-in: the project vendors no gnomAD data, so an ancestry-stratified scan requires the user to supply a frequency source (`--gnomad`, `--haplotypes`, `--patient-vcf`). Without one, the scan is reference-only and the output states so. Ancestry risk is reported as the worst-affected population rather than an average, with a carrying threshold applied identically on population and haplotype paths. Nomination combines two specificity models (CFD and MIT), recording both scores per site. A cross-run off-target cache is safety-gated to reference-only, default-scorer searches. ## Reproducibility and engineering posture Design decisions documented in the README emphasize reproducibility: content-addressed results, splits and caches (with integrity re-verification), pinned environments, deterministic seeds, and content-hashed checkpoints. A `null` artifact hash blocks a download by design. Models are loaded through a consent/license/checksum gate; the default backbone (Nucleotide Transformer v2 500M) is CC-BY-NC-SA-4.0 and is refused for commercial use at load time, with no real weights vendored. An ONNX export path exists for the backbone. A Rust/PyO3 crate (`aforge_native`) provides optional acceleration kernels — FM-index BWT search, k-mer seeding, haplotype walking and bulged alignment — each with a byte-identical pure-Python fallback and parity tests; the library installs and passes without the crate. Notably, benchmarking led the project to leave the FM-index and k-mer seed prefilter as opt-in rather than default, since both were measured as a net scan-level cost. ## Benchmark and status A public benchmark, CRISPR-Bench, provides tasks, frozen splits, metrics, a runner and a leaderboard; a calibration/generalization study script regenerates per-task ECE, cross-cell-type generalization gap and recalibration reports. Reproducible SVG figures are generated by a dependency-free renderer. All fifteen phases of the v0.1.0 roadmap are marked complete (core types, genome access, data registry, variant resolver, off-target engine, scoring/model zoo, the three chemistries, designer, reporting, CLI, web, benchmark, docs). Post-v0.1.0 tracks toward v1.0 are listed as in progress or not started, including pinning real artifact hashes and a validation/calibration study. ## Installation shape The core install is deliberately light (typed models, config, model-card parsing) with optional extras for `core`, `genome`, `variant`, `cli`, `web`, `ml`, `cas9-rs3`, `docs` and `dev`. Python ≥ 3.11 is required. The `variant` extra needs PostgreSQL client headers because `hgvs` depends on `psycopg2`; the README notes this previously made a documented install command impossible to run. The project states plainly that it is a research tool, not a medical device, and that off-target nominations are computational and must be experimentally validated.