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.
Files changed (81) hide show
  1. gene_edit_check-0.3.0/.env.example +1 -0
  2. gene_edit_check-0.3.0/.github/workflows/ci.yml +39 -0
  3. gene_edit_check-0.3.0/.github/workflows/release.yml +48 -0
  4. gene_edit_check-0.3.0/.gitignore +37 -0
  5. gene_edit_check-0.3.0/CHANGELOG.md +44 -0
  6. gene_edit_check-0.3.0/CITATION.cff +33 -0
  7. gene_edit_check-0.3.0/LICENSE +21 -0
  8. gene_edit_check-0.3.0/PKG-INFO +237 -0
  9. gene_edit_check-0.3.0/PROJECT_PLAN.md +128 -0
  10. gene_edit_check-0.3.0/README.md +203 -0
  11. gene_edit_check-0.3.0/SKILL.md +113 -0
  12. gene_edit_check-0.3.0/docs/HOW_IT_WORKS.md +86 -0
  13. gene_edit_check-0.3.0/docs/RELATED_WORK.md +40 -0
  14. gene_edit_check-0.3.0/docs/RELEASING.md +47 -0
  15. gene_edit_check-0.3.0/docs/RESULTS.md +145 -0
  16. gene_edit_check-0.3.0/docs/examples/crc_pd1_real_run.md +111 -0
  17. gene_edit_check-0.3.0/outputs/fig_coupling.png +0 -0
  18. gene_edit_check-0.3.0/outputs/fig_forest.png +0 -0
  19. gene_edit_check-0.3.0/outputs/fig_loci.png +0 -0
  20. gene_edit_check-0.3.0/outputs/fig_pipeline.png +0 -0
  21. gene_edit_check-0.3.0/outputs/fig_scorecard.png +0 -0
  22. gene_edit_check-0.3.0/outputs/figure_crc-pd1-exhaustion.png +0 -0
  23. gene_edit_check-0.3.0/outputs/report_crc-pd1-exhaustion.json +1077 -0
  24. gene_edit_check-0.3.0/outputs/sweep_coupling_seed42.json +128 -0
  25. gene_edit_check-0.3.0/outputs/universality_report.json +269 -0
  26. gene_edit_check-0.3.0/plugin.json +10 -0
  27. gene_edit_check-0.3.0/pyproject.toml +60 -0
  28. gene_edit_check-0.3.0/references/citation.bib +18 -0
  29. gene_edit_check-0.3.0/scripts/make_figures.py +19 -0
  30. gene_edit_check-0.3.0/scripts/probe_ag2_api.py +199 -0
  31. gene_edit_check-0.3.0/skills/alphagenome_v2_single_cell_crispr/SKILL.md +113 -0
  32. gene_edit_check-0.3.0/src/gene_edit_check/__init__.py +7 -0
  33. gene_edit_check-0.3.0/src/gene_edit_check/adata_utils.py +42 -0
  34. gene_edit_check-0.3.0/src/gene_edit_check/ag_backend/__init__.py +4 -0
  35. gene_edit_check-0.3.0/src/gene_edit_check/ag_backend/live_client.py +339 -0
  36. gene_edit_check-0.3.0/src/gene_edit_check/ag_backend/protocol.py +102 -0
  37. gene_edit_check-0.3.0/src/gene_edit_check/ag_backend/simulator.py +173 -0
  38. gene_edit_check-0.3.0/src/gene_edit_check/agent/__init__.py +1 -0
  39. gene_edit_check-0.3.0/src/gene_edit_check/agent/reflexion_loop.py +429 -0
  40. gene_edit_check-0.3.0/src/gene_edit_check/benchmarks/__init__.py +1 -0
  41. gene_edit_check-0.3.0/src/gene_edit_check/benchmarks/hazard_coupling.py +319 -0
  42. gene_edit_check-0.3.0/src/gene_edit_check/benchmarks/state_fidelity.py +81 -0
  43. gene_edit_check-0.3.0/src/gene_edit_check/benchmarks/universality.py +341 -0
  44. gene_edit_check-0.3.0/src/gene_edit_check/budget.py +93 -0
  45. gene_edit_check-0.3.0/src/gene_edit_check/cache.py +79 -0
  46. gene_edit_check-0.3.0/src/gene_edit_check/cli.py +629 -0
  47. gene_edit_check-0.3.0/src/gene_edit_check/conditions.py +232 -0
  48. gene_edit_check-0.3.0/src/gene_edit_check/crispr/__init__.py +1 -0
  49. gene_edit_check-0.3.0/src/gene_edit_check/crispr/constraints.py +175 -0
  50. gene_edit_check-0.3.0/src/gene_edit_check/crispr/motifs.py +50 -0
  51. gene_edit_check-0.3.0/src/gene_edit_check/data/ag2_supported_conditions.tsv.gz +0 -0
  52. gene_edit_check-0.3.0/src/gene_edit_check/datasets/__init__.py +0 -0
  53. gene_edit_check-0.3.0/src/gene_edit_check/datasets/crc_pelka.py +166 -0
  54. gene_edit_check-0.3.0/src/gene_edit_check/datasets/generic_h5ad.py +364 -0
  55. gene_edit_check-0.3.0/src/gene_edit_check/mcp_server/server.py +88 -0
  56. gene_edit_check-0.3.0/src/gene_edit_check/models.py +288 -0
  57. gene_edit_check-0.3.0/src/gene_edit_check/paths.py +51 -0
  58. gene_edit_check-0.3.0/src/gene_edit_check/pipeline.py +130 -0
  59. gene_edit_check-0.3.0/src/gene_edit_check/provenance.py +29 -0
  60. gene_edit_check-0.3.0/src/gene_edit_check/sc_sketch/__init__.py +1 -0
  61. gene_edit_check-0.3.0/src/gene_edit_check/sc_sketch/coreset.py +101 -0
  62. gene_edit_check-0.3.0/src/gene_edit_check/sc_sketch/sketch_variance.py +152 -0
  63. gene_edit_check-0.3.0/src/gene_edit_check/scenarios/__init__.py +1 -0
  64. gene_edit_check-0.3.0/src/gene_edit_check/scenarios/registry.py +344 -0
  65. gene_edit_check-0.3.0/src/gene_edit_check/ui/__init__.py +1 -0
  66. gene_edit_check-0.3.0/src/gene_edit_check/ui/plots.py +409 -0
  67. gene_edit_check-0.3.0/src/gene_edit_check/ui/terminal_hud.py +239 -0
  68. gene_edit_check-0.3.0/src/gene_edit_check/verifier/__init__.py +1 -0
  69. gene_edit_check-0.3.0/src/gene_edit_check/verifier/off_tissue.py +80 -0
  70. gene_edit_check-0.3.0/src/gene_edit_check/verifier/two_tier.py +292 -0
  71. gene_edit_check-0.3.0/tests/test_agnostic_h5ad_and_universality.py +286 -0
  72. gene_edit_check-0.3.0/tests/test_budget_guardrails.py +42 -0
  73. gene_edit_check-0.3.0/tests/test_conditions_and_offtarget.py +174 -0
  74. gene_edit_check-0.3.0/tests/test_coreset_stratified.py +34 -0
  75. gene_edit_check-0.3.0/tests/test_crispr_constraints.py +37 -0
  76. gene_edit_check-0.3.0/tests/test_determinism_and_cache.py +34 -0
  77. gene_edit_check-0.3.0/tests/test_hazard_coupling.py +143 -0
  78. gene_edit_check-0.3.0/tests/test_ism_prescreen.py +122 -0
  79. gene_edit_check-0.3.0/tests/test_real_data_and_verifier_rules.py +214 -0
  80. gene_edit_check-0.3.0/tests/test_report_rendering.py +54 -0
  81. 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
+ [![CI](https://github.com/aravmendiratta/gene-edit-check/actions/workflows/ci.yml/badge.svg)](https://github.com/aravmendiratta/gene-edit-check/actions/workflows/ci.yml)
40
+ [![PyPI](https://img.shields.io/pypi/v/gene-edit-check)](https://pypi.org/project/gene-edit-check/)
41
+ ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
42
+ ![License](https://img.shields.io/badge/license-MIT-green)
43
+ ![Use](https://img.shields.io/badge/use-research%20only-orange)
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
+ ![How a candidate edit is judged](https://raw.githubusercontent.com/aravmendiratta/gene-edit-check/main/outputs/fig_pipeline.png)
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
+ ![Candidate scorecard](https://raw.githubusercontent.com/aravmendiratta/gene-edit-check/main/outputs/fig_scorecard.png)
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
+ ![Efficacy against hazard](https://raw.githubusercontent.com/aravmendiratta/gene-edit-check/main/outputs/fig_coupling.png)
87
+
88
+ ![Correlation with its uncertainty](https://raw.githubusercontent.com/aravmendiratta/gene-edit-check/main/outputs/fig_forest.png)
89
+
90
+ ![The same pattern at six genes](https://raw.githubusercontent.com/aravmendiratta/gene-edit-check/main/outputs/fig_loci.png)
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`.