helix-governance 1.1.5
Friendly, reproducible bioinformatics toolkit with schema-verified viz
Requires Python: >=3.10
Keywords: bioinformatics, genomics, rna, alignment, visualization

# Helix — Deterministic, auditable genome-editing simulation (CRISPR/Prime/PCR)
[![PyPI](https://img.shields.io/pypi/v/helix-governance.svg)](https://pypi.org/project/helix-governance/)
[![Scientific Contract CI](https://github.com/omniscoder/Helix/actions/workflows/ci.yaml/badge.svg)](https://github.com/omniscoder/Helix/actions/workflows/ci.yaml?query=branch:main)
[![VeriBiota CI](https://github.com/omniscoder/Helix/actions/workflows/veribiota.yml/badge.svg)](https://github.com/omniscoder/Helix/actions/workflows/veribiota.yml)
[![Verified by VeriBiota](https://img.shields.io/badge/verified%20by-VeriBiota-10b981?logo=lean&logoColor=white)](docs/veribiota.md)
[![Reproducible Viz (spec v1.0)](https://img.shields.io/badge/reproducible%20viz-spec%201.0-6f42c1)](docs/schema.md)

Helix is a deterministic, auditable genome editing simulator and reporting system for **pre-clinical, in-silico** CRISPR, Prime, and PCR workflows — a computational system of record for genome editing design decisions.

Helix does **not** claim biological truth. It guarantees **computational reproducibility**, explicit modeling boundaries, and verifiable decision artifacts (reports, manifests, schema-versioned evidence bundles).

Pre-clinical, in-silico simulation only. See [docs/positioning.md](docs/positioning.md).

## Migration note (veri-helix → helix-governance)

Helix is now published on PyPI as `helix-governance` (Python module namespace and CLI entrypoints are unchanged).

```bash
python -m pip uninstall -y veri-helix
python -m pip install -U helix-governance
```

![Helix Studio Outcome Explorer overlay](docs/img/helix_studio_evs_overlay_1920x1080.png)

## Choose your path

- Try Helix quickly → [First Run](#first-run) or [docs/getting-started.md](docs/getting-started.md)
- Evaluate auditability/reproducibility → [docs/audit_walkthrough.md](docs/audit_walkthrough.md) and [docs/scientific_contract_v1.md](docs/scientific_contract_v1.md)
- Run the Public Validation Pack v1 → [docs/validation/README.md](docs/validation/README.md)
- Verify release receipts (trust model + receipts) → [docs/reference_validation_bundle.md](docs/reference_validation_bundle.md)
- Enterprise proof dossier (security, threat model, signing, receipts) → [docs/enterprise_proof/index.md](docs/enterprise_proof/index.md)
- Teams v0 blueprint (artifact store + run registry + RBAC) → [docs/teams_v0.md](docs/teams_v0.md)
- Use CRISPR/Prime decision modeling → [docs/edit_dag_overview.md](docs/edit_dag_overview.md) (limitations: [docs/model_limitations/crispr_edit_dag_limitations.md](docs/model_limitations/crispr_edit_dag_limitations.md))
- Integrate in CI/headless lanes → [docs/cli_headless.md](docs/cli_headless.md) and [docs/trust_kit.md](docs/trust_kit.md)
- Hack on internals → [docs/contributing.md](docs/contributing.md) (tests: `tools/test.sh` / `tools/test.ps1`)

## First Run

Install, run a deterministic demo, and open the exported report:

```bash
python -m venv .venv
source .venv/bin/activate
pip install "helix-governance"

helix demo run --demo-id crispr --outdir out/demo_crispr --zip
python -m http.server --directory out/demo_crispr/reports 8000
```

Prime demo:

```bash
helix demo run --demo-id prime --outdir out/demo_prime --zip
```

## Governance licensing (principle: authority, not bits)

- Helix is free to install/run (simulate + explore).
- Decision-grade assertions and signed bundles require an **offline** license file.
- Verification is always free + offline: `helix verify <bundle_dir_or_zip>` validates signatures and lineage, and never reads your local license.

## Dynamic CRISPR simulation (resource-aware)

Copy/paste quickstart (Python API):

```python
from helix.crispr.dynamic import CrisprDynamicSimConfig, simulate_crispr_dynamic

# Key mental model: `delivery` shapes Cas(t) (availability over time), not a static cut probability.
# `population.seed` makes the stochastic simulation reproducible.
cfg = CrisprDynamicSimConfig.from_yaml("""
time: {dt_h: 0.25, t_end_h: 48.0}
population: {n_cells: 2000, seed: 1}
delivery: {mode: RNP, params: {C0: 1.0}}
cas_kinetics: {k_deg: 0.35, k_dil: 0.0}
engagement: {k_eff: 0.55}
grnas: [{id: g1, abundance: 1.0, load_efficiency: 1.0}, {id: g2, abundance: 1.0, load_efficiency: 1.0}]
targets: [{id: t1, grna_id: g1, chr: chr1, pos: 1000, accessibility: 1.0}, {id: t2, grna_id: g2, chr: chr1, pos: 2000, accessibility: 1.0}]
ploidy: {loci: [{locus_id: t1, copies: 2, allele_accessibility: [1.0, 0.5]}, {locus_id: t2, copies: 2, allele_accessibility: [1.0, 1.0]}]}
measurement: {amplicons: [{id: amp1, chr: chr1, start: 900, end: 1100, locus_id: t1}]}
""")
result = simulate_crispr_dynamic(cfg)

print("edited_fraction(t1) =", result.edited_fraction("t1"))
print("edited_fraction(t2) =", result.edited_fraction("t2"))
print("amp1 truth =", result.measurement.amplicons[0].truth_counts)
print("amp1 observed =", result.measurement.amplicons[0].observed_counts)
```

Want the GUI? `pip install "helix-governance[studio]"` then run `helix-studio`.

## Who this is for

- Genome editing researchers who need reproducible CRISPR/Prime outcome enumeration and comparisons
- Auditors/reviewers who need deterministic replays and verifiable artifacts
- Contributors building policies, verifiers, and visualization/reporting pipelines

## Docs

- Docs & Playground: https://omniscoder.github.io/Helix/
- Studio strategy: [docs/helix_studio_strategy.md](docs/helix_studio_strategy.md)
- Snapshot spec v1: [docs/snapshot_spec_v1.md](docs/snapshot_spec_v1.md)
- Full manual / product cookbook (legacy README): [docs/product_manual.md](docs/product_manual.md)