tooluniverse-immunotherapy-response-prediction

# Immunotherapy Response Prediction

Predict patient response to immune checkpoint inhibitors (ICIs) using multi-biomarker integration. Transforms a patient tumor profile (cancer type + mutations + biomarkers) into a quantitative ICI Response Score with drug-specific recommendations, resistance risk assessment, and monitoring plan.

## Reasoning Before Searching

Not all tumors respond to checkpoint inhibitors. Reason through the biology before running tools:

- **TMB (tumor mutational burden)**: More somatic mutations produce more neoantigens, which are recognized by T cells. High TMB (>=10 mut/Mb, FDA-approved threshold for pembrolizumab) generally predicts better response — but this varies by cancer type (e.g., RCC responds despite low TMB).
- **MSI-H (microsatellite instability-high)**: Caused by defective DNA mismatch repair (MMR). MSI-H tumors have very high TMB and are pan-cancer approved for pembrolizumab. Check MLH1, MSH2, MSH6, PMS2 mutations.
- **PD-L1 expression**: The direct target of pembrolizumab/atezolizumab. High PD-L1 (TPS >=50% or CPS >=10 depending on cancer) predicts response in some cancers (NSCLC) but not all (melanoma, where TMB is more predictive).
- **Resistance factors** are equally important: STK11, KEAP1, JAK1/2 loss, B2M mutations can render an otherwise TMB-high tumor non-responsive.

Before calling any tool, determine which biomarkers are available for this patient and which are unknown. This determines which phases can be scored with data vs. must use cancer-type priors. Do not default to "moderate" for unknowns — flag them explicitly as missing.

**LOOK UP DON'T GUESS**: Never assume FDA approval for a biomarker-ICI combination — always verify with `fda_pharmacogenomic_biomarkers` or `FDA_get_indications_by_drug_name`. Cancer-specific thresholds differ from pan-cancer approvals.

**KEY PRINCIPLES**:
1. **Report-first approach** - Create report file FIRST, then populate progressively
2. **Evidence-graded** - Every finding has an evidence tier (T1-T4)
3. **Quantitative output** - ICI Response Score (0-100) with transparent component breakdown
4. **Cancer-specific** - All thresholds and predictions are cancer-type adjusted
5. **Multi-biomarker** - Integrate TMB + MSI + PD-L1 + neoantigen + mutations
6. **Resistance-aware** - Always check for known resistance mutations (STK11, PTEN, JAK1/2, B2M)
7. **Drug-specific** - Recommend specific ICI agents with evidence
8. **Source-referenced** - Every statement cites the tool/database source
9. **English-first queries** - Always use English terms in tool calls

---

## 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:
- "Will this patient respond to immunotherapy?"
- "Should I give pembrolizumab to this melanoma patient?"
- "Patient has NSCLC with TMB 25, PD-L1 80% - predict ICI response"
- "MSI-high colorectal cancer - which checkpoint inhibitor?"
- "Patient has BRAF V600E melanoma, TMB 15 - immunotherapy or targeted?"
- "Compare pembrolizumab vs nivolumab for this patient profile"

---

## Input Parsing

**Required**: Cancer type + at least one of: mutation list OR TMB value
**Optional**: PD-L1 expression, MSI status, immune infiltration data, HLA type, prior treatments, intended ICI

See [INPUT_REFERENCE.md](INPUT_REFERENCE.md) for input format examples, cancer type normalization, and gene symbol normalization tables.

---

## Workflow Overview

```
Input: Cancer type + Mutations/TMB + Optional biomarkers (PD-L1, MSI, etc.)

Phase 1: Input Standardization & Cancer Context
Phase 2: TMB Analysis
Phase 3: Neoantigen Analysis
Phase 4: MSI/MMR Status Assessment
Phase 5: PD-L1 Expression Analysis
Phase 6: Immune Microenvironment Profiling
Phase 7: Mutation-Based Predictors
Phase 8: Clinical Evidence & ICI Options
Phase 9: Resistance Risk Assessment
Phase 10: Multi-Biomarker Score Integration
Phase 11: Clinical Recommendations
```

---

## Phase 1: Input Standardization & Cancer Context

1. **Resolve cancer type** to EFO ID via `OpenTargets_get_disease_id_description_by_name`
2. **Parse mutations** into structured format: `{gene, variant, type}`
3. **Resolve gene IDs** via `MyGene_query_genes`
4. Look up cancer-specific ICI baseline ORR from the cancer context table (see [SCORING_TABLES.md](SCORING_TABLES.md))

## Phase 2: TMB Analysis

1. Classify TMB: Very-Low (<5), Low (5-9.9), Intermediate (10-19.9), High (>=20)
2. Check FDA TMB-H biomarker via `fda_pharmacogenomic_biomarkers(drug_name='pembrolizumab')`
3. Apply cancer-specific TMB thresholds (see [SCORING_TABLES.md](SCORING_TABLES.md))
4. Note: RCC responds to ICIs despite low TMB; TMB is less predictive in some cancers

## Phase 3: Neoantigen Analysis

1. Estimate neoantigen burden: missense_count * 0.3 + frameshift_count * 1.5
2. Check mutation impact via `UniProt_get_function_by_accession`
3. Query known epitopes via `iedb_search_epitopes`
4. POLE/POLD1 mutations indicate ultra-high neoantigen load

## Phase 4: MSI/MMR Status Assessment

1. Integrate MSI status if provided (MSI-H = 25 pts, MSS = 5 pts)
2. Check mutations in MMR genes: MLH1, MSH2, MSH6, PMS2, EPCAM
3. Check FDA MSI-H approvals via `fda_pharmacogenomic_biomarkers(biomarker='Microsatellite Instability')`

## Phase 5: PD-L1 Expression Analysis

1. Classify PD-L1: High (>=50%), Positive (1-49%), Negative (<1%)
2. Apply cancer-specific PD-L1 thresholds and scoring methods (TPS vs CPS)
3. Get baseline expression via `HPA_get_cancer_prognostics_by_gene(gene_name='CD274')`

## Phase 6: Immune Microenvironment Profiling

1. Query immune checkpoint gene expression for: CD274, PDCD1, CTLA4, LAG3, HAVCR2, TIGIT, CD8A, CD8B, GZMA, GZMB, PRF1, IFNG
2. Classify tumor: Hot (T cell inflamed), Cold (i