gene-edit-check 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- gene_edit_check-0.3.0/.env.example +1 -0
- gene_edit_check-0.3.0/.github/workflows/ci.yml +39 -0
- gene_edit_check-0.3.0/.github/workflows/release.yml +48 -0
- gene_edit_check-0.3.0/.gitignore +37 -0
- gene_edit_check-0.3.0/CHANGELOG.md +44 -0
- gene_edit_check-0.3.0/CITATION.cff +33 -0
- gene_edit_check-0.3.0/LICENSE +21 -0
- gene_edit_check-0.3.0/PKG-INFO +237 -0
- gene_edit_check-0.3.0/PROJECT_PLAN.md +128 -0
- gene_edit_check-0.3.0/README.md +203 -0
- gene_edit_check-0.3.0/SKILL.md +113 -0
- gene_edit_check-0.3.0/docs/HOW_IT_WORKS.md +86 -0
- gene_edit_check-0.3.0/docs/RELATED_WORK.md +40 -0
- gene_edit_check-0.3.0/docs/RELEASING.md +47 -0
- gene_edit_check-0.3.0/docs/RESULTS.md +145 -0
- gene_edit_check-0.3.0/docs/examples/crc_pd1_real_run.md +111 -0
- gene_edit_check-0.3.0/outputs/fig_coupling.png +0 -0
- gene_edit_check-0.3.0/outputs/fig_forest.png +0 -0
- gene_edit_check-0.3.0/outputs/fig_loci.png +0 -0
- gene_edit_check-0.3.0/outputs/fig_pipeline.png +0 -0
- gene_edit_check-0.3.0/outputs/fig_scorecard.png +0 -0
- gene_edit_check-0.3.0/outputs/figure_crc-pd1-exhaustion.png +0 -0
- gene_edit_check-0.3.0/outputs/report_crc-pd1-exhaustion.json +1077 -0
- gene_edit_check-0.3.0/outputs/sweep_coupling_seed42.json +128 -0
- gene_edit_check-0.3.0/outputs/universality_report.json +269 -0
- gene_edit_check-0.3.0/plugin.json +10 -0
- gene_edit_check-0.3.0/pyproject.toml +60 -0
- gene_edit_check-0.3.0/references/citation.bib +18 -0
- gene_edit_check-0.3.0/scripts/make_figures.py +19 -0
- gene_edit_check-0.3.0/scripts/probe_ag2_api.py +199 -0
- gene_edit_check-0.3.0/skills/alphagenome_v2_single_cell_crispr/SKILL.md +113 -0
- gene_edit_check-0.3.0/src/gene_edit_check/__init__.py +7 -0
- gene_edit_check-0.3.0/src/gene_edit_check/adata_utils.py +42 -0
- gene_edit_check-0.3.0/src/gene_edit_check/ag_backend/__init__.py +4 -0
- gene_edit_check-0.3.0/src/gene_edit_check/ag_backend/live_client.py +339 -0
- gene_edit_check-0.3.0/src/gene_edit_check/ag_backend/protocol.py +102 -0
- gene_edit_check-0.3.0/src/gene_edit_check/ag_backend/simulator.py +173 -0
- gene_edit_check-0.3.0/src/gene_edit_check/agent/__init__.py +1 -0
- gene_edit_check-0.3.0/src/gene_edit_check/agent/reflexion_loop.py +429 -0
- gene_edit_check-0.3.0/src/gene_edit_check/benchmarks/__init__.py +1 -0
- gene_edit_check-0.3.0/src/gene_edit_check/benchmarks/hazard_coupling.py +319 -0
- gene_edit_check-0.3.0/src/gene_edit_check/benchmarks/state_fidelity.py +81 -0
- gene_edit_check-0.3.0/src/gene_edit_check/benchmarks/universality.py +341 -0
- gene_edit_check-0.3.0/src/gene_edit_check/budget.py +93 -0
- gene_edit_check-0.3.0/src/gene_edit_check/cache.py +79 -0
- gene_edit_check-0.3.0/src/gene_edit_check/cli.py +629 -0
- gene_edit_check-0.3.0/src/gene_edit_check/conditions.py +232 -0
- gene_edit_check-0.3.0/src/gene_edit_check/crispr/__init__.py +1 -0
- gene_edit_check-0.3.0/src/gene_edit_check/crispr/constraints.py +175 -0
- gene_edit_check-0.3.0/src/gene_edit_check/crispr/motifs.py +50 -0
- gene_edit_check-0.3.0/src/gene_edit_check/data/ag2_supported_conditions.tsv.gz +0 -0
- gene_edit_check-0.3.0/src/gene_edit_check/datasets/__init__.py +0 -0
- gene_edit_check-0.3.0/src/gene_edit_check/datasets/crc_pelka.py +166 -0
- gene_edit_check-0.3.0/src/gene_edit_check/datasets/generic_h5ad.py +364 -0
- gene_edit_check-0.3.0/src/gene_edit_check/mcp_server/server.py +88 -0
- gene_edit_check-0.3.0/src/gene_edit_check/models.py +288 -0
- gene_edit_check-0.3.0/src/gene_edit_check/paths.py +51 -0
- gene_edit_check-0.3.0/src/gene_edit_check/pipeline.py +130 -0
- gene_edit_check-0.3.0/src/gene_edit_check/provenance.py +29 -0
- gene_edit_check-0.3.0/src/gene_edit_check/sc_sketch/__init__.py +1 -0
- gene_edit_check-0.3.0/src/gene_edit_check/sc_sketch/coreset.py +101 -0
- gene_edit_check-0.3.0/src/gene_edit_check/sc_sketch/sketch_variance.py +152 -0
- gene_edit_check-0.3.0/src/gene_edit_check/scenarios/__init__.py +1 -0
- gene_edit_check-0.3.0/src/gene_edit_check/scenarios/registry.py +344 -0
- gene_edit_check-0.3.0/src/gene_edit_check/ui/__init__.py +1 -0
- gene_edit_check-0.3.0/src/gene_edit_check/ui/plots.py +409 -0
- gene_edit_check-0.3.0/src/gene_edit_check/ui/terminal_hud.py +239 -0
- gene_edit_check-0.3.0/src/gene_edit_check/verifier/__init__.py +1 -0
- gene_edit_check-0.3.0/src/gene_edit_check/verifier/off_tissue.py +80 -0
- gene_edit_check-0.3.0/src/gene_edit_check/verifier/two_tier.py +292 -0
- gene_edit_check-0.3.0/tests/test_agnostic_h5ad_and_universality.py +286 -0
- gene_edit_check-0.3.0/tests/test_budget_guardrails.py +42 -0
- gene_edit_check-0.3.0/tests/test_conditions_and_offtarget.py +174 -0
- gene_edit_check-0.3.0/tests/test_coreset_stratified.py +34 -0
- gene_edit_check-0.3.0/tests/test_crispr_constraints.py +37 -0
- gene_edit_check-0.3.0/tests/test_determinism_and_cache.py +34 -0
- gene_edit_check-0.3.0/tests/test_hazard_coupling.py +143 -0
- gene_edit_check-0.3.0/tests/test_ism_prescreen.py +122 -0
- gene_edit_check-0.3.0/tests/test_real_data_and_verifier_rules.py +214 -0
- gene_edit_check-0.3.0/tests/test_report_rendering.py +54 -0
- gene_edit_check-0.3.0/tests/test_two_tier_loop.py +55 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
ALPHAGENOME_API_KEY=your_alphagenome_api_key_here
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: ["main", "master"]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
steps:
|
|
12
|
+
- uses: actions/checkout@v4
|
|
13
|
+
- name: Install uv
|
|
14
|
+
uses: astral-sh/setup-uv@v4
|
|
15
|
+
- name: Set up Python 3.12
|
|
16
|
+
run: uv python install 3.12
|
|
17
|
+
- name: Install dependencies
|
|
18
|
+
run: |
|
|
19
|
+
uv venv --python 3.12 .venv
|
|
20
|
+
uv pip install --python .venv/bin/python -e ".[scverse,dev]"
|
|
21
|
+
- name: Run unit & determinism test suite (offline simulator backend)
|
|
22
|
+
run: .venv/bin/pytest -v
|
|
23
|
+
- name: Smoke test CLI plumbing (SYNTHETIC data + scripted simulator; never a result)
|
|
24
|
+
run: |
|
|
25
|
+
.venv/bin/gene-edit-check ablate-sketch --scenario pd1-exhaustion --simulator --sketch-size 16 --pool-size 96
|
|
26
|
+
.venv/bin/gene-edit-check optimize --scenario pd1-exhaustion --simulator --sketch-size 16 --pool-size 96 --max-iterations 4
|
|
27
|
+
- name: Reference-condition table is shipped and queryable (offline, no API key)
|
|
28
|
+
run: .venv/bin/gene-edit-check conditions "CD8-positive" --modality methylation --limit 5
|
|
29
|
+
- name: Setup check runs without an API key
|
|
30
|
+
run: .venv/bin/gene-edit-check doctor
|
|
31
|
+
- name: Build the package and confirm the reference table ships inside it
|
|
32
|
+
run: |
|
|
33
|
+
uv build
|
|
34
|
+
unzip -l dist/*.whl | grep ag2_supported_conditions.tsv.gz
|
|
35
|
+
- name: A fresh install of the wheel works with no extras
|
|
36
|
+
run: |
|
|
37
|
+
uv venv --python 3.12 /tmp/fresh
|
|
38
|
+
uv pip install --python /tmp/fresh/bin/python dist/*.whl
|
|
39
|
+
/tmp/fresh/bin/gene-edit-check conditions "CD8-positive" --limit 3
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
# Publishes to PyPI when you push a version tag such as v0.3.0.
|
|
4
|
+
# One-time setup (see docs/RELEASING.md): add this repository as a "trusted publisher" on PyPI,
|
|
5
|
+
# using workflow file release.yml and environment name pypi. No API token is stored anywhere.
|
|
6
|
+
|
|
7
|
+
on:
|
|
8
|
+
push:
|
|
9
|
+
tags: ["v*"]
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
build:
|
|
13
|
+
runs-on: ubuntu-latest
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v4
|
|
16
|
+
- name: Install uv
|
|
17
|
+
uses: astral-sh/setup-uv@v4
|
|
18
|
+
- name: Refuse to publish with unreplaced placeholders
|
|
19
|
+
run: |
|
|
20
|
+
if grep -rIl "YOUR_GITHUB_USERNAME" README.md pyproject.toml CITATION.cff plugin.json; then
|
|
21
|
+
echo "Replace YOUR_GITHUB_USERNAME with your GitHub username before releasing."; exit 1
|
|
22
|
+
fi
|
|
23
|
+
- name: Tag matches the package version
|
|
24
|
+
run: |
|
|
25
|
+
v=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
|
|
26
|
+
[ "v$v" = "${GITHUB_REF_NAME}" ] || { echo "Tag ${GITHUB_REF_NAME} does not match pyproject version v$v"; exit 1; }
|
|
27
|
+
- name: Build sdist and wheel
|
|
28
|
+
run: uv build
|
|
29
|
+
- name: The reference-condition table must be inside the wheel
|
|
30
|
+
run: unzip -l dist/*.whl | grep -q ag2_supported_conditions.tsv.gz
|
|
31
|
+
- uses: actions/upload-artifact@v4
|
|
32
|
+
with:
|
|
33
|
+
name: dist
|
|
34
|
+
path: dist/
|
|
35
|
+
|
|
36
|
+
publish:
|
|
37
|
+
needs: build
|
|
38
|
+
runs-on: ubuntu-latest
|
|
39
|
+
environment: pypi
|
|
40
|
+
permissions:
|
|
41
|
+
id-token: write # trusted publishing
|
|
42
|
+
steps:
|
|
43
|
+
- uses: actions/download-artifact@v4
|
|
44
|
+
with:
|
|
45
|
+
name: dist
|
|
46
|
+
path: dist/
|
|
47
|
+
- name: Publish to PyPI
|
|
48
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Environment & Secrets
|
|
2
|
+
.env
|
|
3
|
+
.env.*
|
|
4
|
+
!.env.example
|
|
5
|
+
|
|
6
|
+
# Python & Virtualenvs
|
|
7
|
+
.venv/
|
|
8
|
+
venv/
|
|
9
|
+
__pycache__/
|
|
10
|
+
*.py[cod]
|
|
11
|
+
*.egg-info/
|
|
12
|
+
dist/
|
|
13
|
+
build/
|
|
14
|
+
.pytest_cache/
|
|
15
|
+
.ruff_cache/
|
|
16
|
+
|
|
17
|
+
# Local caches
|
|
18
|
+
.ag2_cache/
|
|
19
|
+
*.sqlite
|
|
20
|
+
*.db
|
|
21
|
+
|
|
22
|
+
# Raw single-cell data (396 MB; re-downloaded automatically on first run)
|
|
23
|
+
/data/
|
|
24
|
+
|
|
25
|
+
# Scratch and superseded runs
|
|
26
|
+
outputs/_old_synthetic_run/
|
|
27
|
+
outputs/report_pd1-exhaustion.json
|
|
28
|
+
outputs/figure_pd1-exhaustion.png
|
|
29
|
+
phase0_probe_results.json
|
|
30
|
+
|
|
31
|
+
# Committed on purpose: the published run's figure, report and sweep, so the results in
|
|
32
|
+
# README.md are reproducible and visible without an API key.
|
|
33
|
+
!outputs/figure_crc-pd1-exhaustion.png
|
|
34
|
+
!outputs/fig_*.png
|
|
35
|
+
!outputs/report_crc-pd1-exhaustion.json
|
|
36
|
+
!outputs/sweep_coupling_seed42.json
|
|
37
|
+
!outputs/universality_report.json
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
- Renamed the project to `gene-edit-check`.
|
|
6
|
+
- Efficacy-hazard correlations now carry 95% bootstrap intervals, and the methylation-versus-splice label comes
|
|
7
|
+
from a paired bootstrap of the gap instead of a fixed cutoff. For the main PDCD1 run: rho +0.57
|
|
8
|
+
(CI +0.28 to +0.77); the gap to splicing is +0.41 (CI -0.02 to +0.82), so specificity to methylation is not
|
|
9
|
+
established.
|
|
10
|
+
- New optional dose ceiling `optimize --max-effect`, which rejects edits that silence the target more than a
|
|
11
|
+
given |LFC|. Off by default.
|
|
12
|
+
- `optimize` and `run-h5ad` now default to a 40-edit random null, matching the sweeps.
|
|
13
|
+
- New `docs/RELATED_WORK.md` listing prior art and what this project does and does not add.
|
|
14
|
+
|
|
15
|
+
## 0.3.0
|
|
16
|
+
|
|
17
|
+
First public release.
|
|
18
|
+
|
|
19
|
+
**Pipeline**
|
|
20
|
+
- Real-data pipeline on the Pelka et al. 2021 colorectal atlas, with sketches split by patient so the
|
|
21
|
+
verification sketch never shares a patient with the proposal sketch.
|
|
22
|
+
- Edit direction is measured by an in-silico mutagenesis pre-screen instead of inferred from gradient sign,
|
|
23
|
+
which agreed with the measured sign only about 70% of the time.
|
|
24
|
+
- Efficacy must beat a 40-edit random null; neighbouring genes in the scored window are checked; finalists are
|
|
25
|
+
scored against six non-immune tissues.
|
|
26
|
+
- Tier 2 hazard references are chosen by the model's own evidence tier (observed, imputed-supported,
|
|
27
|
+
imputed-exploratory), with a tissue-matched cross-check reported alongside rather than averaged in.
|
|
28
|
+
- `run-h5ad` runs the pipeline on any single-cell `.h5ad` file.
|
|
29
|
+
|
|
30
|
+
**Commands**: `optimize`, `run-h5ad`, `conditions`, `doctor`, `validate-fidelity`, `ablate-sketch`,
|
|
31
|
+
`sweep-coupling`, `sweep-universality`, and `gene-edit-check-mcp` for AI agents.
|
|
32
|
+
|
|
33
|
+
**Install behaviour**
|
|
34
|
+
- Downloaded atlases and cached API responses go to a per-user cache folder, never the Python install
|
|
35
|
+
directory. Override with `GENE_EDIT_CHECK_HOME`.
|
|
36
|
+
- A real-data run without an API key stops with instructions instead of falling back to the simulator.
|
|
37
|
+
- `.env` is found in the folder you run from.
|
|
38
|
+
- `gene-edit-check doctor` reports your setup.
|
|
39
|
+
|
|
40
|
+
**Corrections made before release**
|
|
41
|
+
- An earlier draft reported a CpG-methylation vs efficacy correlation of +0.94 at *PDCD1*. With a 40-edit random
|
|
42
|
+
null it is about +0.5, the random-edit control is not significant, and splicing also correlates. The claim was
|
|
43
|
+
retracted; see `docs/RESULTS.md`.
|
|
44
|
+
- The shipped reference-condition table had been excluded from the package by an over-broad ignore rule.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
cff-version: 1.2.0
|
|
2
|
+
title: "gene-edit-check: a computational-biology toolkit for cell-state-selective CRISPR base edits"
|
|
3
|
+
message: "If you use this software, please cite it as below."
|
|
4
|
+
type: software
|
|
5
|
+
authors:
|
|
6
|
+
- family-names: Mendiratta
|
|
7
|
+
given-names: Arav
|
|
8
|
+
repository-code: "https://github.com/aravmendiratta/gene-edit-check"
|
|
9
|
+
license: MIT
|
|
10
|
+
version: 0.3.0
|
|
11
|
+
date-released: "2026-11-16"
|
|
12
|
+
keywords:
|
|
13
|
+
- AlphaGenome
|
|
14
|
+
- CRISPR base editing
|
|
15
|
+
- single-cell genomics
|
|
16
|
+
- T-cell exhaustion
|
|
17
|
+
- regulatory genomics
|
|
18
|
+
abstract: >-
|
|
19
|
+
A verifier-guided search for cell-state-selective CRISPR base edits that uses Google DeepMind's
|
|
20
|
+
AlphaGenome 2 as the judge. Applied to PDCD1 (PD-1) silencing in exhausted tumour-infiltrating
|
|
21
|
+
CD8 T cells from colorectal cancer (Pelka et al., Cell 2021), no candidate edit passes every safety check;
|
|
22
|
+
CpG methylation is the binding constraint. Edit efficacy and predicted CpG methylation shift are positively
|
|
23
|
+
associated (Spearman rho about +0.5 to +0.6 across seeds, cohorts and six checkpoint loci), a moderate
|
|
24
|
+
association whose specificity to methylation is not established. Model predictions only; no wet-lab validation.
|
|
25
|
+
references:
|
|
26
|
+
- type: article
|
|
27
|
+
authors:
|
|
28
|
+
- family-names: Pelka
|
|
29
|
+
given-names: Karin
|
|
30
|
+
title: "Spatially organized multicellular immune hubs in human colorectal cancer"
|
|
31
|
+
journal: Cell
|
|
32
|
+
year: 2021
|
|
33
|
+
doi: 10.1016/j.cell.2021.08.003
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Arav Mendiratta
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: gene-edit-check
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Computational-biology toolkit that checks whether a CRISPR base edit works only in the cells you want, using AlphaGenome 2 as the judge.
|
|
5
|
+
Project-URL: Homepage, https://github.com/aravmendiratta/gene-edit-check
|
|
6
|
+
Project-URL: Issues, https://github.com/aravmendiratta/gene-edit-check/issues
|
|
7
|
+
Project-URL: Changelog, https://github.com/aravmendiratta/gene-edit-check/blob/main/CHANGELOG.md
|
|
8
|
+
Author: Arav Mendiratta
|
|
9
|
+
License: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: alphagenome,base-editing,bioinformatics,computational-biology,crispr,gene-editing,regulatory-genomics,single-cell
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
17
|
+
Requires-Python: >=3.11
|
|
18
|
+
Requires-Dist: alphagenome>=0.1.0
|
|
19
|
+
Requires-Dist: matplotlib>=3.8.0
|
|
20
|
+
Requires-Dist: numpy>=1.26.0
|
|
21
|
+
Requires-Dist: pandas>=2.0.0
|
|
22
|
+
Requires-Dist: pydantic>=2.7.0
|
|
23
|
+
Requires-Dist: python-dotenv>=1.0.1
|
|
24
|
+
Requires-Dist: rich>=13.7.0
|
|
25
|
+
Requires-Dist: scipy>=1.12.0
|
|
26
|
+
Requires-Dist: typer>=0.12.0
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: pytest>=8.0.0; extra == 'dev'
|
|
29
|
+
Provides-Extra: mcp
|
|
30
|
+
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
|
|
31
|
+
Provides-Extra: scverse
|
|
32
|
+
Requires-Dist: anndata>=0.10.0; extra == 'scverse'
|
|
33
|
+
Description-Content-Type: text/markdown
|
|
34
|
+
|
|
35
|
+
# gene-edit-check
|
|
36
|
+
|
|
37
|
+
**Checks, on a computer, whether a gene edit works only in the cells you want, before anyone spends weeks testing it in a lab.**
|
|
38
|
+
|
|
39
|
+
[](https://github.com/aravmendiratta/gene-edit-check/actions/workflows/ci.yml)
|
|
40
|
+
[](https://pypi.org/project/gene-edit-check/)
|
|
41
|
+

|
|
42
|
+

|
|
43
|
+

|
|
44
|
+
|
|
45
|
+
A computational-biology toolkit built on Google DeepMind's AlphaGenome 2.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## The problem
|
|
50
|
+
|
|
51
|
+
Gene-editing tools can now change a single letter of DNA. That makes a precise kind of treatment possible: turn
|
|
52
|
+
one gene down in the cells that cause trouble, and leave every other cell alone.
|
|
53
|
+
|
|
54
|
+
The hard part is knowing, in advance, whether a given edit will do that. Testing each candidate in a lab takes
|
|
55
|
+
weeks. And an edit can look good where you aimed it while quietly doing damage elsewhere: in healthy cells, in
|
|
56
|
+
the genes next door, or in the chemical tags that keep DNA working properly.
|
|
57
|
+
|
|
58
|
+
**gene-edit-check does that homework on a computer first.** You give it a gene and two kinds of cell, the ones
|
|
59
|
+
you want to change and the ones you want to leave alone. It proposes single-letter edits, predicts what each
|
|
60
|
+
one would do in both, and runs the survivors through a set of safety checks. What comes out is a short list of
|
|
61
|
+
edits worth taking to a lab, or a clear reason why there isn't one.
|
|
62
|
+
|
|
63
|
+

|
|
64
|
+
|
|
65
|
+
The part that keeps it honest: the patients' cells used to *propose* an edit are never the ones used to *judge*
|
|
66
|
+
it, and every claim of "it works" has to beat a crowd of random edits first.
|
|
67
|
+
|
|
68
|
+
## What it found
|
|
69
|
+
|
|
70
|
+
The worked example is **PD-1**. Many tumours switch off the immune system's T cells by leaning on a protein
|
|
71
|
+
called PD-1, so turning PD-1 down in tumour T cells is a real strategy. The catch is that T cells in healthy
|
|
72
|
+
tissue also use PD-1, so the edit has to be selective. We used real single-cell data from colorectal cancer
|
|
73
|
+
(62 patients, [Pelka et al., *Cell* 2021](https://doi.org/10.1016/j.cell.2021.08.003)) and let AlphaGenome 2 play
|
|
74
|
+
the judge.
|
|
75
|
+
|
|
76
|
+
**No edit passed every check.** Eight single-letter edits were tested against six safety checks. Seven of the
|
|
77
|
+
eight disturbed DNA methylation, the chemical tags that help control which genes are active, more than the
|
|
78
|
+
safety limit allows. The closest miss was 0.146 against a limit of 0.12.
|
|
79
|
+
|
|
80
|
+

|
|
81
|
+
|
|
82
|
+
**A pattern showed up underneath.** The more strongly an edit turned PD-1 down, the more it also shifted
|
|
83
|
+
methylation. The same held at all six exhaustion-related genes we tried. It is a moderate link, not a precise
|
|
84
|
+
one, and the data cannot yet say whether it is specific to methylation or something every strong edit does.
|
|
85
|
+
|
|
86
|
+

|
|
87
|
+
|
|
88
|
+

|
|
89
|
+
|
|
90
|
+

|
|
91
|
+
|
|
92
|
+
**Why a negative result is useful.** It tells a lab which edits not to spend months on, and it points to the
|
|
93
|
+
real obstacle (methylation at this gene) rather than leaving a vague sense that "it didn't work".
|
|
94
|
+
|
|
95
|
+
**What it does not mean.** These are predictions from a model, not lab measurements. An earlier draft of this
|
|
96
|
+
project claimed a much stronger link (a correlation of +0.94). A larger random comparison did not support it,
|
|
97
|
+
so it was retracted, and the numbers above are the corrected ones. The full account, including what did not
|
|
98
|
+
hold up, is in [docs/RESULTS.md](docs/RESULTS.md).
|
|
99
|
+
|
|
100
|
+
> *Research use only. Nothing here is validated in a lab or fit for clinical, diagnostic or therapeutic use.*
|
|
101
|
+
|
|
102
|
+
### Plain-language glossary
|
|
103
|
+
|
|
104
|
+
| Term | What it means here |
|
|
105
|
+
|---|---|
|
|
106
|
+
| **Base edit** | Changing one letter of DNA (for example A to G) without cutting the strand. |
|
|
107
|
+
| **Cell state** | A kind of cell in a particular condition, such as "exhausted T cell inside a tumour". |
|
|
108
|
+
| **Methylation** | Chemical tags on DNA that help switch genes on and off. Disturbing them can have wide effects. |
|
|
109
|
+
| **Splicing** | How a gene's raw copy is cut and joined into a finished message. Edits can break it. |
|
|
110
|
+
| **AlphaGenome 2** | A DeepMind AI model that predicts what a DNA change does in different cells. |
|
|
111
|
+
| **Random null** | A crowd of random edits tried first, so a "good" edit has to beat chance, not just look good. |
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## Install
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
pip install gene-edit-check # the command-line tool and Python library
|
|
119
|
+
pipx install gene-edit-check # same, in its own isolated environment (recommended for the CLI)
|
|
120
|
+
pip install "gene-edit-check[mcp]" # also adds the server for AI coding agents
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Needs Python 3.11 or newer. From source: `pip install git+https://github.com/aravmendiratta/gene-edit-check`.
|
|
124
|
+
|
|
125
|
+
## What happens when you install it
|
|
126
|
+
|
|
127
|
+
You get one command, `gene-edit-check`, and an importable Python package. Installing does not download
|
|
128
|
+
data, call any API or create any files. Nothing happens until you run something.
|
|
129
|
+
|
|
130
|
+
| You have | You can do | Needs |
|
|
131
|
+
|---|---|---|
|
|
132
|
+
| **Nothing else** | Check your setup, browse AlphaGenome 2's 2,799 reference conditions ranked by how well the model actually knows each one, run the plumbing with the simulator | just the install |
|
|
133
|
+
| **A free API key** | Run the full pipeline on the built-in colorectal and breast cancer cohorts and get a report and figure | key, plus a one-time 396 MB atlas download |
|
|
134
|
+
| **Your own `.h5ad` file** | Run the same pipeline on any single-cell dataset, for any target gene | key, plus your data |
|
|
135
|
+
|
|
136
|
+
### 30 seconds, no key
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
gene-edit-check doctor # what is set up, and where files will go
|
|
140
|
+
gene-edit-check conditions "CD8-positive" # which reference conditions are best evidenced
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### A real run
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
export ALPHAGENOME_API_KEY=... # free, non-commercial: https://deepmind.google.com/science/alphagenome
|
|
147
|
+
# PowerShell: $env:ALPHAGENOME_API_KEY='...' or put it in a .env file
|
|
148
|
+
gene-edit-check optimize # PD-1 in exhausted colorectal-cancer T cells
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
The first run downloads the Pelka et al. 2021 atlas (396 MB, once) and takes a few minutes. It makes tens of
|
|
152
|
+
AlphaGenome calls and caches every response, so repeating a run is fast and free. You get:
|
|
153
|
+
|
|
154
|
+
- a **terminal report**: the candidate edits, each check it passed or failed, and why
|
|
155
|
+
- `outputs/report_crc-pd1-exhaustion.json`: the full machine-readable record
|
|
156
|
+
- `outputs/figure_crc-pd1-exhaustion.png`: a one-page summary: the scorecard, the efficacy-versus-hazard chart and its confidence intervals
|
|
157
|
+
|
|
158
|
+
Without a key, a real-data run stops and tells you how to get one. It will not quietly substitute fake output.
|
|
159
|
+
|
|
160
|
+
### Your own data
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
gene-edit-check run-h5ad \
|
|
164
|
+
--h5ad my_atlas.h5ad --gene-id ENSG00000188389 --gene-symbol PDCD1 \
|
|
165
|
+
--target-query "cell_type == 'CD8 T cell' and condition == 'tumour'" \
|
|
166
|
+
--healthy-query "cell_type == 'CD8 T cell' and condition == 'normal'" \
|
|
167
|
+
--cell-type "CD8-positive" --tissue "colon"
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
The file needs raw integer UMI counts (in `.raw.X`, `.layers["counts"]` or `.X`) and a column identifying the
|
|
171
|
+
patient or donor. Cell groups are selected with pandas queries, including `expr_GENE > 0` conditions. The
|
|
172
|
+
Tier 2 reference condition is chosen automatically from your `--cell-type`.
|
|
173
|
+
|
|
174
|
+
## Who this is for
|
|
175
|
+
|
|
176
|
+
- **Someone designing a state-selective regulatory edit** who wants a cheap first pass before committing to
|
|
177
|
+
wet-lab work: does the model think this edit moves the gene in the cells you care about and not in the ones
|
|
178
|
+
you don't, and what does it break on the way?
|
|
179
|
+
- **Anyone using AlphaGenome 2** who wants a better way to pick a reference condition. `gene-edit-check
|
|
180
|
+
conditions` ranks them by whether the model saw real training data or only imputed it. Only 185 of 2,799
|
|
181
|
+
human conditions have observed methylation.
|
|
182
|
+
- **Single-cell groups** who need to condition AlphaGenome on a population but are limited to 256 cells. The
|
|
183
|
+
coreset sketching and patient-disjoint hold-out are reusable on their own.
|
|
184
|
+
- **Researchers evaluating verifier-guided search**, with a worked and honest negative result.
|
|
185
|
+
|
|
186
|
+
It is not a guide-RNA design tool, it does not predict off-target cutting, and it does not replace experiments.
|
|
187
|
+
|
|
188
|
+
## Use it from Python
|
|
189
|
+
|
|
190
|
+
```python
|
|
191
|
+
from gene_edit_check.conditions import search_conditions, evidence_profile
|
|
192
|
+
|
|
193
|
+
hits = search_conditions("CD8-positive", modality="methylation") # strongest evidence first
|
|
194
|
+
print(hits[["condition", "biosample_name", "methylation"]].head())
|
|
195
|
+
print(evidence_profile("UBERON:0000178_CL:0000625")) # blood CD8 T cell: all four 'observed'
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
The full pipeline is `gene_edit_check.pipeline.run_scenario`. The scripted simulator in
|
|
199
|
+
`gene_edit_check.ag_backend.simulator` lets you test code offline; its output is not a prediction.
|
|
200
|
+
|
|
201
|
+
## Use it from an AI agent
|
|
202
|
+
|
|
203
|
+
- **Skill.** `skills/alphagenome_v2_single_cell_crispr/SKILL.md` teaches an agent how to drive the CLI and how to
|
|
204
|
+
report results honestly.
|
|
205
|
+
- **MCP server.** `gene-edit-check-mcp` exposes `run_optimization_tool`, `list_scenarios_tool` and
|
|
206
|
+
`search_conditions_tool` to any MCP-capable agent.
|
|
207
|
+
|
|
208
|
+
## Where files go
|
|
209
|
+
|
|
210
|
+
| What | Where |
|
|
211
|
+
|---|---|
|
|
212
|
+
| Reports and figures | `./outputs/` in the folder you run from |
|
|
213
|
+
| Downloaded atlases and cached AlphaGenome responses | a per-user cache folder (`%LOCALAPPDATA%\gene-edit-check`, `~/Library/Caches/gene-edit-check`, or `~/.cache/gene-edit-check`) |
|
|
214
|
+
| Override the cache location | set `GENE_EDIT_CHECK_HOME` |
|
|
215
|
+
|
|
216
|
+
`gene-edit-check doctor` prints the exact paths on your machine.
|
|
217
|
+
|
|
218
|
+
## Limits and terms
|
|
219
|
+
|
|
220
|
+
- AlphaGenome 2 is used under its [non-commercial terms](https://deepmind.google.com/science/alphagenome/terms),
|
|
221
|
+
and you need your own API key. The code here is MIT licensed; the model and its predictions are not.
|
|
222
|
+
- No wet-lab validation. "Selective" means AlphaGenome 2 says so.
|
|
223
|
+
- The healthy comparators are imperfect (memory-like colon T cells, not naive ones), the Tier 2 hazard
|
|
224
|
+
reference is blood CD8 T cells because the colon one is only imputed, and the breast cohort has 5 patients.
|
|
225
|
+
|
|
226
|
+
## Develop
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
git clone https://github.com/aravmendiratta/gene-edit-check && cd gene-edit-check
|
|
230
|
+
uv venv --python 3.12 .venv && uv pip install --python .venv/Scripts/python.exe -e ".[dev,mcp]"
|
|
231
|
+
pytest # offline: no API key and no download needed
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
## Cite
|
|
235
|
+
|
|
236
|
+
Pelka et al., *Cell* 2021 (data); Wu et al., *EMBO J* 2020 (breast cohort); Avsec et al. and Google DeepMind
|
|
237
|
+
(AlphaGenome). See [CITATION.cff](CITATION.cff) and [references/citation.bib](references/citation.bib).
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# STATUS (2026-11-15): real-data pipeline built; first live result is "not converged"
|
|
2
|
+
|
|
3
|
+
- Real dataset wired in: Pelka et al. 2021 colorectal cancer T cells (62 patients) via CELLxGENE. States use the authors' annotations. Synthetic cohort kept for tests/CI only.
|
|
4
|
+
- Fabricated "published ground truth" benchmark removed; replaced by `validate-fidelity` (predicted vs observed fold-change, rho +0.65).
|
|
5
|
+
- Fixed: Sketch B now held out by patient; efficacy test now direction-aware and null-calibrated (was circular); duplicate edit evaluation; encode_cells wrongly capped at 256; sparse-safe hashing.
|
|
6
|
+
- Live run: no candidate passed all checks; two selective ones fail only the methylation hazard. See `docs/examples/crc_pd1_real_run.md`.
|
|
7
|
+
- Open: stronger proposer (wrong-direction edits fill iterations 5-8), tissue-matched Tier 2 reference, more seeds/genes, larger null, a second independent dataset.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# gene-edit-check (`gene-edit-check`) — Revised Engineering & Execution Plan (v2)
|
|
12
|
+
|
|
13
|
+
> **Research-Use-Only Notice:** `gene-edit-check` is an in-silico research tool for exploring regulatory sequence grammar and single-cell variant effects using Google DeepMind's AlphaGenome 2 API. Following DeepMind's terms, outputs are candidate computational hypotheses and are **not** validated for clinical, diagnostic, or therapeutic use.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 1. Core Architectural Revisions (Addressing v2 API Physics & Scientific Rigor)
|
|
18
|
+
|
|
19
|
+
### 1.1 Two-Tier Verifier Architecture (`Selectivity` vs. `Sequence Hazards`)
|
|
20
|
+
In `alphagenome.models.v2`, custom single-cell conditioning (`cell_conditioning` via `encode_cells()`, capped at `MAX_CONDITIONING_CELLS = 256`) unlocks **`OutputType.SC_GENE_EXPRESSION_DENOISED`**, whereas specialized variant scorers (`SpliceJunctionScorer()`, `MethylationScorer(width=1201)`, `ContactMapScorer()`) operate under ontology-curated reference conditions (`ModelCondition.from_curies(...)`, e.g., `UBERON:0000178_CL:0001054`).
|
|
21
|
+
|
|
22
|
+
We encode this distinction directly in the type system (`Tier1SelectivityResult` vs. `Tier2HazardResult`) so no output ever implies single-cell resolution where the underlying scorer uses reference tissue/cell CURIEs:
|
|
23
|
+
* **Tier 1 — Single-Cell Selectivity (`cell_conditioning`, `SC_GENE_EXPRESSION_DENOISED`):**
|
|
24
|
+
Evaluates differential target gene expression between the **Target Pathological Cell Sketch** and **Healthy Control Cell Sketches**.
|
|
25
|
+
* **Tier 2 — Sequence-Intrinsic Hazards (`ModelCondition.from_curies`, Matched Ontology):**
|
|
26
|
+
Evaluates cryptic splice site creation (`SpliceJunctionScorer()`), local CpG methylation disruption (`MethylationScorer(width=1201)`), and chromatin accessibility shifts on the closest matched `UBERON`/`CL` reference conditions.
|
|
27
|
+
|
|
28
|
+
### 1.2 "Gradients Propose, Scoped ISM Verifies" (Test-Time Compute Split)
|
|
29
|
+
Running `score_ism_variants()` across a full 1-Mb window ($\sim 3 \times 10^6$ variants per condition) is computationally infeasible. Instead, we exploit AlphaGenome 2's native input-gradient endpoint (`predict_interval_gradients` / `predict_interval_gradients_batch` at 100 KB / 1 MB resolution):
|
|
30
|
+
1. **Proposal Phase (1 Gradient Call per State):** Call `predict_interval_gradients` centered on the target gene's median TSS for `OutputType.SC_GENE_EXPRESSION_DENOISED` in Target vs. Healthy cell sketches.
|
|
31
|
+
2. **Differential Saliency Attribution:** Identify short ($\le 60\text{ bp}$) PAM-accessible windows where the nucleotide gradient magnitude $|\nabla_x \text{Expr}(x \mid C_{\text{target}})|$ is high while $|\nabla_x \text{Expr}(x \mid C_{\text{safe}})|$ is near zero.
|
|
32
|
+
3. **Verification Phase (Scoped ISM + Multi-Tier Scorers):** Run `score_ism_variants()` **strictly inside the top candidate 20–40 bp protospacer windows** ($\le 120$ variants total, bounded by `budget.py`), followed by Tier 1 and Tier 2 verification on the surviving base-editor designs.
|
|
33
|
+
|
|
34
|
+
### 1.3 Batch-Stratified Coreset Selection in AlphaGenome's Own Latent Space
|
|
35
|
+
AlphaGenome 2's `encode_cells()` maps raw UMI count matrices into the model's internal cell-state representation, and its docstring explicitly notes that `encode_cells()` **does not perform batch correction**. Running facility location solely in PCA space optimizes a metric the model never sees.
|
|
36
|
+
Our revised sketching pipeline (`sc_sketch/coreset.py`):
|
|
37
|
+
```text
|
|
38
|
+
.h5ad (raw UMI counts, gene symbol → ENSG mapping)
|
|
39
|
+
└── Stratify by donor/batch metadata (prevent single-donor dominance)
|
|
40
|
+
└── Cheap PCA pre-filter to ~2,000–5,000 candidate cells
|
|
41
|
+
└── encode_cells() → AlphaGenome 2 Latent Space Embeddings
|
|
42
|
+
└── Lazy-Greedy Facility Location in AG2 Latent Space
|
|
43
|
+
└── Emit Disjoint Sketches:
|
|
44
|
+
├── Sketch A (256 cells) → Used for Gradient Proposal & Inner Loop
|
|
45
|
+
└── Sketch B (256 cells, held-out donors/cells) → Used for Final Verification
|
|
46
|
+
```
|
|
47
|
+
* **Built-In Ablation:** We evaluate sketch stability **with vs. without donor/batch stratification** and measure **Cross-Sketch Generalization ($\text{Sketch } A \to \text{Sketch } B$)** to eliminate Goodhart's Law / self-confirmation bias.
|
|
48
|
+
|
|
49
|
+
### 1.4 Honest Uncertainty & Ground-Truth Benchmarking
|
|
50
|
+
* **Cross-Sketch Stability (`sketch_variance.py`):** Replaces overclaimed "conformal prediction" with honest bootstrap/partition variance across $M$ disjoint 256-cell sketches ($\mu \pm \text{SE}$ and cross-donor transfer correlation).
|
|
51
|
+
* **Wet-Lab Ground Truth Anchor (`benchmarks/ground_truth.py`):** Includes a validation benchmark comparing model variant scores against published experimental measurements (**ENCODE CRISPRi-FlowFISH enhancer-gene pairs** / **Gosai et al. *Nature* 2024 MPRA**) reporting Spearman $\rho$ and AUPRC.
|
|
52
|
+
* **Strict Provenance & Simulator Labeling (`provenance.py`):** Every CLI run, JSON output, and plot carries an explicit provenance banner (`backend: LIVE_ALPHAGENOME_V2` vs. `backend: SURROGATE_SIMULATOR`, `model_version`, `random_seed`, `api_calls_used`, `cache_hits`). No hardcoded or scripted iteration drama—every trace is generated from a committed random seed.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## 2. Revised Repository Layout
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
gene-edit-check/
|
|
60
|
+
├── pyproject.toml # Single primary CLI: `gene-edit-check`
|
|
61
|
+
├── README.md # Architecture, two-tier defense, RUO notice, citations
|
|
62
|
+
├── PROJECT_PLAN.md # This revised plan
|
|
63
|
+
├── SKILL.md # Agent Skill definition (Claude Code / Cursor / Antigravity)
|
|
64
|
+
├── scripts/
|
|
65
|
+
│ └── probe_ag2_api.py # Phase 0 live API probe (tests cell_conditioning + scorers + gradients)
|
|
66
|
+
├── src/
|
|
67
|
+
│ └── gene_edit_check/
|
|
68
|
+
│ ├── __init__.py
|
|
69
|
+
│ ├── cli.py # CLI: `probe`, `audit`, `optimize`, `ablate-sketch`, `validate-gt`
|
|
70
|
+
│ ├── models.py # Pydantic v2 types (explicit Tier1Selectivity vs Tier2Hazard)
|
|
71
|
+
│ ├── budget.py # Hard caps on API calls, ISM window width (<=60bp), and variants/run
|
|
72
|
+
│ ├── cache.py # Content-addressed SQLite cache: (sha256(seq), cond_hash, outputs, model_ver)
|
|
73
|
+
│ ├── provenance.py # Tracks seeds, model_version, call counts, LIVE vs SIMULATOR badge
|
|
74
|
+
│ ├── ag_backend/ # Named `ag_backend` so it never shadows `import alphagenome`
|
|
75
|
+
│ │ ├── __init__.py
|
|
76
|
+
│ │ ├── protocol.py # `VerifierBackend` Protocol (encode_cells, gradients, ism, score_variant)
|
|
77
|
+
│ │ ├── live_client.py # Adapter for `alphagenome.models.v2.dna_client` & `variant_scorers`
|
|
78
|
+
│ │ └── simulator.py # Clearly badged surrogate backend for zero-key offline testing/CI
|
|
79
|
+
│ ├── sc_sketch/
|
|
80
|
+
│ │ ├── __init__.py
|
|
81
|
+
│ │ ├── coreset.py # Donor-stratified AG2-latent Facility Location + Sketch A / Sketch B split
|
|
82
|
+
│ │ └── sketch_variance.py # Cross-sketch variance & stratified vs. unstratified ablation
|
|
83
|
+
│ ├── crispr/
|
|
84
|
+
│ │ ├── __init__.py
|
|
85
|
+
│ │ ├── constraints.py # SpCas9/Cas9-NG PAMs, ABE8e/CBE [4..8] window & bystander checks
|
|
86
|
+
│ │ └── motifs.py # JASPAR PWM scanner for mechanistic attribution
|
|
87
|
+
│ ├── verifier/
|
|
88
|
+
│ │ ├── __init__.py
|
|
89
|
+
│ │ └── two_tier.py # Tier 1 (scRNA selectivity on Sketch A/B) + Tier 2 (CURIE splice/CpG hazards)
|
|
90
|
+
│ ├── agent/
|
|
91
|
+
│ │ ├── __init__.py
|
|
92
|
+
│ │ └── reflexion_loop.py # Deterministic Gradient-Propose → Scoped-ISM → Reflexion engine (LLM opt-in)
|
|
93
|
+
│ ├── benchmarks/
|
|
94
|
+
│ │ └── ground_truth.py # Spearman correlation against measured CRISPRi / MPRA ground truth
|
|
95
|
+
│ ├── ui/
|
|
96
|
+
│ │ ├── terminal_hud.py # Rich summary tables & provenance banner
|
|
97
|
+
│ │ └── plots.py # Multi-panel figure with explicit Tier 1 / Tier 2 & backend stamps
|
|
98
|
+
│ └── mcp_server/
|
|
99
|
+
│ └── server.py # FastMCP server wrapping the deterministic pipeline
|
|
100
|
+
└── tests/
|
|
101
|
+
├── test_determinism_and_cache.py # Verifies content-addressed caching & seed reproducibility
|
|
102
|
+
├── test_budget_guardrails.py # Verifies BudgetExceededError on oversized ISM intervals (>60bp)
|
|
103
|
+
├── test_coreset_stratified.py # Verifies Sketch A/B disjointness & AG2 latent facility location
|
|
104
|
+
├── test_crispr_constraints.py # Verifies PAM, ABE8e/CBE windows, and bystander flagging
|
|
105
|
+
└── test_two_tier_loop.py # Verifies Gradient-Propose -> Scoped-ISM -> Held-out Sketch B check
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## 3. Reordered De-Risked Execution Sequence
|
|
111
|
+
|
|
112
|
+
### Phase 0: Live API Capability & Quota Probe (`scripts/probe_ag2_api.py`)
|
|
113
|
+
- [x] Write `scripts/probe_ag2_api.py` to test against a live `ALPHAGENOME_API_KEY`:
|
|
114
|
+
1. `encode_cells()` latency and output embedding shape.
|
|
115
|
+
2. Whether `score_variant(..., cell_conditioning=...)` accepts `MethylationScorer(width=1201)` and `SpliceJunctionScorer()`, or strictly requires `ModelCondition.from_curies(...)`.
|
|
116
|
+
3. `predict_interval_gradients(..., output_type=OutputType.SC_GENE_EXPRESSION_DENOISED)` output tensor shape.
|
|
117
|
+
|
|
118
|
+
### Phase 1: Core Vertical Slice (Models, Budget, Cache, Provenance, `VerifierBackend` Protocol)
|
|
119
|
+
- [ ] Implement `models.py` (with explicit `Tier1SelectivityResult` and `Tier2HazardResult`), `budget.py`, `cache.py`, `provenance.py`, and `ag_backend/protocol.py` + `simulator.py` + `live_client.py`.
|
|
120
|
+
|
|
121
|
+
### Phase 2: Batch-Stratified AG2-Latent Coreset Sketcher (`Sketch A` / `Sketch B` Split)
|
|
122
|
+
- [ ] Implement `sc_sketch/coreset.py` and `sc_sketch/sketch_variance.py` (supporting both donor-stratified facility location in `encode_cells()` latent space and the stratified vs. unstratified ablation).
|
|
123
|
+
|
|
124
|
+
### Phase 3: Two-Tier Verifier & Deterministic "Gradients Propose, ISM Verifies" Loop
|
|
125
|
+
- [ ] Implement `crispr/constraints.py`, `verifier/two_tier.py`, and `agent/reflexion_loop.py` (deterministic rule engine by default; evaluates winning candidates on held-out `Sketch B`).
|
|
126
|
+
|
|
127
|
+
### Phase 4: Ground-Truth Validation Benchmark, CLI, Plots, MCP & Tests
|
|
128
|
+
- [ ] Implement `benchmarks/ground_truth.py`, `cli.py`, `ui/terminal_hud.py`, `ui/plots.py`, `SKILL.md`, and run `pytest`.
|