alphagenome-single-variant-analysis

Variant Analysis using AlphaGenome

Prerequisites

1. uv: Read the uv skill and follow its Setup instructions to ensure uv is installed and on PATH.

2. User Notification: If .licenses/alphagenome_single_variant_analysis_LICENSE.txt does not already exist in the workspace root directory then (1) prominently notify the user to check the terms at https://deepmind.google.com/science/alphagenome/, then (2) create the file recording the notification text and timestamp.

3. .env file: Make sure the .env file exists in your home directory. Create one if it does not exist.

4. ALPHAGENOME_API_KEY: This skill requires an API key to function.

   You can register for a key at https://deepmind.google.com/science/alphagenome/. You MUST use the safe credentials protocol in the credentials skill to check for and request this key if this skill looks relevant to the user's request.

5. ALPHAGENOME_GTF_PATH (Optional): Accelerate gene/transcript lookup by pointing to a local copy of the GTF feather file instead of downloading from GCS:

   echo "ALPHAGENOME_GTF_PATH=/path/to/local/gencode.v46.annotation.gtf.gz.feather" >> ~/.env
   

Core Rules

• NEVER run python3 or python3 -c directly. The system Python does not necessarily have pandas, numpy, and other key dependencies. ALWAYS use uv run to run ALL Python code — including scripts, ad-hoc analysis files, and one-liners. Do not attempt to pip install or create new venvs — uv manages an isolated environment automatically.
• Offline Only: NEVER use external APIs (e.g., MyGene.info, Ensembl REST) for gene/transcript lookup. Use lookup_gene_info.py with the local GTF. If it fails, fix the environment/paths, do not switch to external APIs.
• API Key is required: ALPHAGENOME_API_KEY must be set before running any script.
• Notification: If this skill is used, ensure this is mentioned in the output.
• Report Format: Always use the templates in docs/report-templates.md for generating analysis reports, and ensure to include the table of top hits from the discovery scan.

Environment Setup & Troubleshooting

Python Environment

All scripts must be executed using uv run, which manages an isolated virtual environment with the correct dependencies via uv.

uv run <script_name> [args...]