tooluniverse-precision-medicine-stratification

# Precision Medicine Patient Stratification

Transform patient genomic and clinical profiles into actionable risk stratification, treatment recommendations, and personalized therapeutic strategies.

## Reasoning Before Searching

Stratification means splitting patients into groups that respond differently to a treatment or have different prognoses. Ask these questions before running any tools:

1. **What molecular feature predicts response?** Candidates: somatic mutation (e.g., EGFR L858R), germline variant (e.g., BRCA1 LoF), expression level (e.g., HER2 overexpression), germline pharmacogenomic variant (e.g., CYP2C19 PM), or composite biomarker (e.g., TMB-H + MSI-H).
2. **Is the predictive feature actionable?** Knowing it must change treatment — either the drug choice, dose, or monitoring plan. A variant with prognostic value but no therapeutic consequence is not a stratification biomarker.
3. **What is the evidence level for the stratifier?** FDA-approved companion diagnostic (T1) vs. exploratory (T4) changes how much weight to place on the finding.

Route to the correct Phase 3 path BEFORE running Phase 2 tools — cancer, metabolic, CVD, rare disease, and autoimmune pipelines require different stratifiers.

**LOOK UP DON'T GUESS**: Never assume a variant is pathogenic, never assume a gene is relevant to a disease, never assign metabolizer status without PharmGKB or CPIC evidence.

**KEY PRINCIPLES**:
1. **Report-first** - Create report file FIRST, then populate progressively
2. **Disease-specific logic** - Cancer vs metabolic vs rare disease pipelines diverge at Phase 3
3. **Multi-level integration** - Germline + somatic + expression + clinical data layers
4. **Evidence-graded** - Every finding has an evidence tier (T1-T4)
5. **Quantitative output** - Precision Medicine Risk Score (0-100)
6. **Source-referenced** - Every statement cites the tool/database source
7. **English-first queries** - Always use English terms in tool calls

**Reference files** (same directory):
- `TOOLS_REFERENCE.md` - Tool parameters, response formats, phase-by-phase tool lists
- `SCORING_REFERENCE.md` - Scoring matrices, risk tiers, pathogenicity tables, PGx tables
- `REPORT_TEMPLATE.md` - Output report template, treatment algorithms, completeness requirements
- `EXAMPLES.md` - Six worked examples (cancer, metabolic, NSCLC, CVD, rare, neuro)
- `QUICK_START.md` - Sample prompts and output summary

---

## COMPUTE, DON'T DESCRIBE
When analysis requires computation (statistics, data processing, scoring, enrichment), write and run Python code via Bash. Don't describe what you would do — execute it and report actual results. Use ToolUniverse tools to retrieve data, then Python (pandas, scipy, statsmodels, matplotlib) to analyze it.

## When to Use

Apply when user asks about patient risk stratification, treatment selection, prognosis prediction, or personalized therapeutic strategy for any disease with genomic/clinical data.

**NOT for** (use other skills instead):
- Single variant interpretation -> `tooluniverse-variant-interpretation`
- Immunotherapy-specific prediction -> `tooluniverse-immunotherapy-response-prediction`
- Drug safety profiling only -> `tooluniverse-adverse-event-detection`
- Target validation -> `tooluniverse-drug-target-validation`
- Clinical trial search only -> `tooluniverse-clinical-trial-matching`
- Drug-drug interaction only -> `tooluniverse-drug-drug-interaction`
- PRS calculation only -> `tooluniverse-polygenic-risk-score`

---

## Input Parsing

### Required
- **Disease/condition**: Free-text disease name
- **At least one of**: Germline variants, somatic mutations, gene list, or clinical biomarkers

### Optional (improves stratification)
- Age, sex, ethnicity, disease stage, comorbidities, prior treatments, family history
- Current medications (for DDI and PGx), stratification goal

### Disease Type Classification

Classify into one category (determines Phase 3 routing):

| Category | Examples |
|----------|----------|
| **CANCER** | Breast, lung, colorectal, melanoma |
| **METABOLIC** | Type 2 diabetes, obesity, NAFLD |
| **CARDIOVASCULAR** | CAD, heart failure, AF |
| **NEUROLOGICAL** | Alzheimer, Parkinson, epilepsy |
| **RARE/MONOGENIC** | Marfan, CF, sickle cell, Huntington |
| **AUTOIMMUNE** | RA, lupus, MS, Crohn's |

---

## Critical Tool Parameter Notes

See `TOOLS_REFERENCE.md` for full details. Key gotchas:

- **MyGene_query_genes**: param is `query` (NOT `q`)
- **EnsemblVEP_annotate_rsid**: param is `variant_id` (NOT `rsid`)
- **ensembl_lookup_gene**: REQUIRES `species='homo_sapiens'`
- **DrugBank tools**: ALL require 4 params: `query`, `case_sensitive`, `exact_match`, `limit`
- **cBioPortal_get_mutations**: `gene_list` is a STRING (space-separated), not array
- **PubMed_search_articles**: Returns a plain list of dicts, NOT `{articles: [...]}`
- **fda_pharmacogenomic_biomarkers**: Use `limit=1000` for all results
- **gnomAD**: May return "Service overloaded" - skip gracefully
- **OpenTargets**: Always nested `{data: {entity: {field: ...}}}` structure

---

## Workflow Overview

```
Phase 1: Disease Disambiguation & Profile Standardization
Phase 2: Genetic Risk Assessment
Phase 3: Disease-Specific Molecular Stratification (routes by disease type)
Phase 4: Pharmacogenomic Profiling
Phase 5: Comorbidity & Drug Interaction Risk
Phase 6: Molecular Pathway Analysis
Phase 7: Clinical Evidence & Guidelines
Phase 8: Clinical Trial Matching
Phase 9: Integrated Scoring & Recommendations
```

---

## Phase 1: Disease Disambiguation & Profile Standardization

1. **Resolve disease to EFO ID** using `OpenTargets_get_disease_id_description_by_name`
2. **Classify disease type** (CANCER/METABOLIC/CVD/NEUROLOGICAL/RARE/AUTOIMMUNE)
3. **Parse genomic data** into structured format (gene, variant, type)
4. **Resolve gene IDs** using `MyGene_query_genes` to get Ensembl/Entrez IDs

## Phase 2: Genetic Risk Assessment

1. **Germline variant pathogenicity**: `ClinVar_search_variants`, `EnsemblVEP_annotate_rsid`/`_hgvs`
2. **Gene-disease association**: `OpenTargets_target_disease_evidence`
3. **GWAS polygenic risk**: `gwas_get_associations_for_trait`, `OpenTargets_search_gwas_studies_by_disease`
4. **Population frequency**: `gnomad_get_variant`
5. **Gene constraint**: `gnomad_get_gene_constraints` (pLI, LOEUF scores)

Scoring: See `SCORING_REFERENCE.md` for genetic risk score component (0-35 points).

## Phase 3: Disease-Specific Molecular Stratification

### CANCER PATH
1. **Molecular subtyping**: `cBioPortal_get_mutations`, `HPA_get_cancer_prognostics_by_gene`
2. **TMB/MSI/HRD**: `fda_pharmacogenomic_biomarkers` for FDA cutoffs
3. **Prognostic stratification**: Combine stage + molecular features

### METABOLIC PATH
1. **Genetic risk integration**: `GWAS_search_associations_by_gene`, `OpenTargets_target_disease_evidence`
2. **Complication risk**: Based on HbA1c, duration, existing complications

### CVD PATH
1. **FH gene check**: `ClinVar_search_variants` for LDLR, APOB, PCSK9
2. **Statin PGx**: `PharmGKB_get_clinical_annotations` for SLCO1B1

### RARE DISEASE PATH
1. **Causal variant identification**: `ClinVar_search_variants`
2. **Genotype-phenotype**: `UniProt_get_disease_variants_by_accession`

Scoring: See `SCORING_REFERENCE.md` for disease-specific tables.

## Phase 4: Pharmacogenomic Profiling

1. **Drug-metabolizing enzymes**: `PharmGKB_get_clinical_annotations`, `PharmGKB_get_dosing_guidelines`
2. **FDA PGx biomarkers**: `fda_pharmacogenomic_biomarkers` (use `limit=1000`)
3. **Treatment-specific PGx**: `PharmGKB_get_drug_details`

Scoring: See `SCORING_REFERENCE.md` for PGx risk score (0-10 points).

## Phase 5: Comorbidity & Drug Interaction Risk

1. **Disease overlap**: `OpenTargets_get_associated_targets_by_disease_efoId`
2. **DDI check**: `drugbank_get_drug_interactions_by_drug_name_or_id`, `FDA_get_drug_interactions_by_drug_name`
3. **PGx-amplified DDI**: If PM genotype + CYP inhibitor, flag compounded risk

## Phase 6: Molecular Pathway Analysis

1. **Pathway enrichment**: `enrichr_gene_enrichment_analysis` (libs: `KEGG_2021_Human`, `Reactome_2022`, `GO_Biological_Process_2023`)
2. **Reactome mapping**: `ReactomeAnalysis_pathway_enrichment`, `Reactome_map_uniprot_to_pathways`
3. **Network analysis**: `STRING_get_interaction_partners`, `STRING_functional_enrichment`
4. **Druggable targets**: `OpenTargets_get_target_tractability_by_ensemblID`

## Phase 7: Clinical Evidence & Guidelines

1. **Guidelines search**: `PubMed_Guidelines_Search` (fallback: `PubMed_search_articles`)
2. **FDA-approved therapies**: `OpenTargets_get_associated_drugs_by_disease_efoId`, `FDA_get_indications_by_drug_name`
3. **Biomarker-drug evidence**: `civic_search_evidence_items`, `civic_search_assertions`

## Phase 8: Clinical Trial Matching

1. **Biomarker-driven trials**: `search_clinical_trials` with condition + intervention
2. **Precision medicine trials**: `search_clinical_trials` for basket/umbrella trials

## Phase 9: Integrated Scoring & Recommendations

### Score Components (total 0-100)
- **Genetic Risk** (0-35): Pathogenicity + gene-disease association + PRS
- **Clinical Risk** (0-30): Stage/biomarkers/comorbidities
- **Molecular Features** (0-25): Driver mutations, subtypes, actionable targets
- **Pharmacogenomic Risk** (0-10): Metabolizer status, HLA alleles

### Risk Tiers
| Score | Tier | Management |
|-------|------|------------|
| 75-100 | VERY HIGH | Intensive treatment, subspecialty referral, clinical trial |
| 50-74 | HIGH | Aggressive treatment, close monitoring |
| 25-49 | INTERMEDIATE | Standard guideline-based care, PGx-guided dosing |
| 0-24 | LOW | Surveillance, prevention, risk factor modification |

### Output
Generate report per `REPORT_TEMPLATE.md`. See `SCORING_REFERENCE.md` for detailed scoring matrices.

---

## Common Use Patterns

See `EXAMPLES.md` for six detailed worked examples:
1. **Cancer + actionable mutation**: Breast cancer, BRCA1, ER+/HER2- -> Score ~55-65 (HIGH)
2. **Metabolic + PGx concern**: T2D, CYP2C19 PM on clopidogrel -> Score ~55-65 (HIGH)
3. **NSCLC comprehensive**: EGFR L858R, TMB 25, PD-L1 80% -> Score ~75-85 (VERY HIGH)
4. **CVD risk**: LDL 190, SLCO1B1*5, family hx MI -> Score ~50-60 (HIGH)
5. **Rare disease**: Marfan, FBN1 variant -> Score ~55-65 (HIGH)
6. **Neurological risk**: APOE e4/e4, family hx Alzheimer's -> Score ~60-72 (HIGH)