Tooluniverse Precision Oncology

Precision Oncology Treatment Advisor

Provide actionable treatment recommendations for cancer patients based on their molecular profile using CIViC, ClinVar, OpenTargets, ClinicalTrials.gov, and structure-based analysis.

Domain Reasoning

Treatment selection follows a strict evidence hierarchy: FDA-approved for this specific mutation in this cancer type ranks highest, followed by approval for this mutation in any cancer (tumor-agnostic), then active clinical trials, and finally off-label use. Skipping this hierarchy to recommend off-label therapies when an approved option exists is a clinical error. Always check current NCCN guidelines and recent literature, as approvals change rapidly — a drug that was investigational last year may now be first-line.

When looking up treatment for a specific mutation, search CIViC and OncoKB FIRST, not PubMed. These databases have curated evidence levels. PubMed is for when curated databases don't have the answer.

Treatment Selection Reasoning

Biomarker-to-drug logic — When a biomarker is identified, the first-line targeted therapy follows established mappings. Always verify current approval status via OncoKB/CIViC, but use this as a starting framework:

• NSCLC: EGFR exon 19 del / L858R → osimertinib (1L); ALK fusion → alectinib/lorlatinib; ROS1 fusion → crizotinib/entrectinib; KRAS G12C → sotorasib/adagrasib; MET exon 14 skip → capmatinib/tepotinib; RET fusion → selpercatinib; BRAF V600E → dabrafenib+trametinib; NTRK fusion → larotrectinib/entrectinib (tumor-agnostic)
• Breast: HER2+ → trastuzumab+pertuzumab (1L), T-DXd (2L); HR+/HER2- → CDK4/6i (palbociclib/ribociclib) + AI; BRCA1/2 mut → olaparib/talazoparib; PIK3CA mut → alpelisib+fulvestrant
• Colorectal: BRAF V600E → encorafenib+cetuximab; MSI-H/dMMR → pembrolizumab (tumor-agnostic); KRAS/NRAS wild-type → cetuximab/panitumumab (anti-EGFR)
• Melanoma: BRAF V600E/K → dabrafenib+trametinib or encorafenib+binimetinib; wild-type → immunotherapy (nivolumab+ipilimumab)
• Tumor-agnostic: MSI-H/dMMR → pembrolizumab; NTRK fusion → larotrectinib; TMB-H (>=10 mut/Mb) → pembrolizumab; RET fusion → selpercatinib

Resistance mechanism reasoning — When a patient progresses on targeted therapy, distinguish primary resistance (never responded — check if the mutation was truly the driver, or if co-mutations like TP53/RB1 abrogate response) from acquired resistance (responded then progressed — on-target mutations or bypass activation). Common patterns:

• EGFR TKIs: 1st/2nd-gen resistance → T790M (50-60%); osimertinib resistance → C797S (10-25%), MET amp (15-20%), HER2 amp, histologic transformation (SCLC ~5%)
• ALK TKIs: crizotinib resistance → ALK secondary mutations (L1196M, G1269A); alectinib resistance → G1202R (solvent front); lorlatinib resistance → compound mutations
• BRAF inhibitors: MAPK reactivation (MEK mutations, BRAF amplification, NRAS mutations), PI3K/AKT bypass
• Anti-HER2: HER2 truncation (p95HER2), PIK3CA activation, HER3 upregulation
• Immunotherapy (anti-PD1): B2M loss (MHC-I loss), JAK1/2 loss-of-function (IFN-gamma signaling escape), WNT/beta-catenin activation (T-cell exclusion)

For resistance workup: query civic_search_evidence_items with the drug name + "resistance", then PubMed_search_articles for recent mechanisms.

LOOK UP DON'T GUESS

• FDA approval status for a mutation-drug pair: query OncoKB_annotate_variant and civic_search_variants; never assume approval status from memory.
• Active clinical trials: search search_clinical_trials with the specific condition and mutation; do not cite trials from memory.
• Resistance mechanisms for specific drugs: query civic_search_evidence_items and PubMed_search_articles; do not assume resistance pathways.
• Variant frequency in TCGA: retrieve from GDC_get_mutation_frequency or cBioPortal_get_mutations; do not estimate prevalence.

---

KEY PRINCIPLES: 1. Report-first - Create report file FIRST, update progressively 2. Evidence-graded - Every recommendation has evidence level 3. Actionable output - Prioritized treatment options, not data dumps 4. Clinical focus - Answer "what should we do?" not "what exists?" 5. English-first queries - Always use English terms in tool calls (mutations, drug names, cancer types), even if the user writes in another language. Only try original-language terms as a fallback. Respond in the user's language

---

When to Use

• "Patient has [cancer] with [mutation] - what treatments?"
• "What are options for EGFR-mutant lung cancer?"
• "Patient failed [drug], what's next?"
• "Clinical trials for KRAS G12C?"
• "Why isn't [drug] working anymore?"

---

Phase 0: Tool Verification

---

Workflow Overview

Input: Cancer type + Molecular profile (mutations, fusions, amplifications)

Phase 1: Profile Validation -> Resolve gene IDs (Ensembl, UniProt, ChEMBL)
Phase 2: Variant Interpretation -> CIViC, ClinVar, COSMIC, GDC/TCGA, DepMap, OncoKB, cBioPortal, HPA
Phase 2.5: Tumor Expression -> CELLxGENE cell-type expression, ChIPAtlas regulatory context
Phase 3: Treatment Options -> OpenTargets + DailyMed (approved), ChEMBL (off-label)
Phase 3.5: Pathway & Network -> KEGG/Reactome pathways, IntAct interactions
Phase 4: Resistance Analysis -> CIViC + PubMed + NvidiaNIM structure analysis
Phase 5: Clinical Trials -> ClinicalTrials.gov search + eligibility
Phase 5.5: Literature -> PubMed, BioRxiv/MedRxiv preprints, OpenAlex citations
Phase 6: Report Synthesis -> Executive summary + prioritized recommendations

---

Key Tools by Phase

Phase 1: Profile Validation

• MyGene_query_genes - Resolve gene to Ensembl ID
• UniProt_search - Get UniProt accession
• ChEMBL_search_targets - Get ChEMBL target ID

Phase 2: Variant Interpretation

• civic_search_variants / civic_get_variant - CIViC evidence
• COSMIC_get_mutations_by_gene / COSMIC_search_mutations - Somatic mutations
• GDC_get_mutation_frequency / GDC_get_ssm_by_gene - TCGA patient data
• GDC_get_gene_expression / GDC_get_cnv_data - Expression and CNV
• GDC_get_survival - Kaplan-Meier survival data by project and optional gene mutation filter
• GDC_get_clinical_data - TCGA clinical metadata (stage, vital status, treatment, demographics)
• Progenetix_cnv_search - Copy number variation biosamples by genomic region and cancer type (NCIt code)
• DepMap_get_gene_dependencies / PharmacoDB_get_experiments - Target essentiality
• OncoKB_annotate_variant / OncoKB_get_gene_info - Actionability
• cBioPortal_get_mutations / cBioPortal_get_cancer_studies - Cross-study data
• HPA_search_genes_by_query / HPA_get_comparative_expression_by_gene_and_cellline - Expression

Phase 2.5: Tumor Expression

• CELLxGENE_get_expression_data / CELLxGENE_get_cell_metadata - Cell-type expression

Phase 3: Treatment Options

• OpenTargets_get_associated_drugs_by_target_ensemblID - Approved drugs (param: ensemblId, camelCase)
• DGIdb_get_drug_gene_interactions - Drug-gene interactions (param: genes as array, e.g., ["EGFR"]). Comprehensive; covers inhibitors, antibodies, and investigational agents.
• DailyMed_search_spls - FDA label details
• ChEMBL_get_drug_mechanisms - Drug mechanism

Phase 3.5: Pathway & Network

• kegg_find_genes / kegg_get_gene_info - KEGG pathways
• reactome_disease_target_score - Reactome disease relevance
• intact_get_interaction_network - Protein interactions

Phase 4: Resistance Analysis

• civic_search_evidence_items - Search by known resistance mutations individually (e.g., molecular_profile="EGFR C797S", molecular_profile="MET Amplification"). The significance field in results indicates Resistance/Sensitivity — filter on it after retrieval.
• PubMed_search_articles - Resistance literature (e.g., "osimertinib resistance C797S combination therapy")
• alphafold_get_prediction / get_diffdock_info - Structure-based analysis (AlphaFold for structure, DiffDock for docking)

Phase 5: Clinical Trials

• search_clinical_trials - Find trials (param: condition, NOT disease)
• get_clinical_trial_eligibility_criteria - Eligibility details

Phase 5.5: Safety & Pharmacogenomics (MANDATORY — do NOT skip)

You MUST call FAERS for the leading approved drug before finalizing the report. A clinical brief without real-world adverse-event data is incomplete.

• FAERS_search_adverse_event_reports — REQUIRED: call with medicinalproduct="<drug_name>" for at least the top 1-2 approved drugs. Report top 10 serious AEs + death count.
• FDA_get_warnings_and_cautions_by_drug_name — REQUIRED: boxed warnings + key precautions.
• FAERS_count_death_related_by_drug - Mortality signal for a drug
• CPIC_list_guidelines - Check for relevant PGx guidelines (e.g., DPYD for fluoropyrimidines in chemo regimens, UGT1A1 for irinotecan). No CPIC guidelines exist for EGFR TKIs.
• fda_pharmacogenomic_biomarkers - FDA-labeled PGx biomarkers for the drug

OncoKB demo mode: Without ONCOKB_API_TOKEN env var, OncoKB only covers BRAF, TP53, ROS1. For other genes (EGFR, KRAS, ALK, etc.), set the API key or use CIViC as the primary evidence source.

Phase 6: Literature

• PubMed_search_articles - Published evidence (use limit, mindate, maxdate for date filtering)
• BioRxiv_list_recent_preprints / MedRxiv_get_preprint - Preprints (flag as NOT peer-reviewed)
• openalex_search_works - Citation analysis

---

Cross-Skill References

For CYP interaction with cancer drugs, run: python3 skills/tooluniverse-drug-drug-interaction/scripts/pharmacology_ref.py --type cyp_substrate --drug drugname

---

References

• TOOLS_REFERENCE.md - Complete tool documentation with parameters and examples
• API_USAGE_PATTERNS.md - Detailed code examples for each phase
• TREATMENT_ALGORITHMS.md - Evidence grading, treatment prioritization, cancer type mappings, DepMap interpretation
• REPORT_TEMPLATE.md - Report template with output tables
• EXAMPLES.md - Worked examples (EGFR NSCLC, T790M resistance, KRAS G12C, no actionable mutations)
• CHECKLIST.md - Quality and completeness checklist

API Usage Patterns for Precision Oncology

Detailed code examples and parameter references for each phase of the precision oncology workflow.

---

Phase 1: Profile Validation

1.1 Resolve Gene Identifiers

def resolve_gene(tu, gene_symbol):
    """Resolve gene to all needed IDs."""
    ids = {}

    # Ensembl ID (for OpenTargets)
    gene_info = tu.tools.MyGene_query_genes(q=gene_symbol, species="human")
    ids['ensembl'] = gene_info.get('ensembl', {}).get('gene')

    # UniProt (for structure)
    uniprot = tu.tools.UniProt_search(query=gene_symbol, organism="human")
    ids['uniprot'] = uniprot[0].get('primaryAccession') if uniprot else None

    # ChEMBL target
    target = tu.tools.ChEMBL_search_targets(query=gene_symbol, organism="Homo sapiens")
    ids['chembl_target'] = target[0].get('target_chembl_id') if target else None

    return ids

1.2 Validate Variant Nomenclature

• HGVS protein: p.L858R, p.V600E
• cDNA: c.2573T>G
• Common names: T790M, G12C

---

Phase 2: Variant Interpretation

2.1 CIViC Evidence Query

def get_civic_evidence(tu, gene_symbol, variant_name):
    """Get CIViC evidence for variant."""
    variants = tu.tools.civic_search_variants(query=f"{gene_symbol} {variant_name}")

    evidence_items = []
    for var in variants:
        evi = tu.tools.civic_get_variant(id=var['id'])
        evidence_items.extend(evi.get('evidence_items', []))

    return {
        'predictive': [e for e in evidence_items if e['evidence_type'] == 'Predictive'],
        'prognostic': [e for e in evidence_items if e['evidence_type'] == 'Prognostic'],
        'diagnostic': [e for e in evidence_items if e['evidence_type'] == 'Diagnostic']
    }

2.2 COSMIC Somatic Mutation Analysis

def get_cosmic_mutations(tu, gene_symbol, variant_name=None):
    """Get somatic mutation data from COSMIC database."""
    gene_mutations = tu.tools.COSMIC_get_mutations_by_gene(
        operation="get_by_gene",
        gene=gene_symbol,
        max_results=100,
        genome_build=38
    )

    if variant_name:
        specific = tu.tools.COSMIC_search_mutations(
            operation="search",
            terms=f"{gene_symbol} {variant_name}",
            max_results=20
        )
        return {
            'specific_variant': specific.get('results', []),
            'all_gene_mutations': gene_mutations.get('results', [])
        }

    return gene_mutations

def get_cosmic_hotspots(tu, gene_symbol):
    """Identify mutation hotspots in COSMIC."""
    mutations = tu.tools.COSMIC_get_mutations_by_gene(
        operation="get_by_gene",
        gene=gene_symbol,
        max_results=500
    )
    position_counts = Counter(m['MutationAA'] for m in mutations.get('results', []))
    return position_counts.most_common(10)

Why COSMIC matters:

• Gold standard for somatic cancer mutations
• Cancer type distribution (which cancers have this mutation)
• FATHMM pathogenicity prediction for novel variants
• Identifies hotspots vs. rare mutations

2.3 GDC/TCGA Pan-Cancer Analysis

def get_tcga_mutation_data(tu, gene_symbol, cancer_type=None):
    """Get somatic mutations from TCGA via GDC."""
    frequency = tu.tools.GDC_get_mutation_frequency(gene_symbol=gene_symbol)

    mutations = tu.tools.GDC_get_ssm_by_gene(
        gene_symbol=gene_symbol,
        project_id=f"TCGA-{cancer_type}" if cancer_type else None,
        size=50
    )

    return {
        'frequency': frequency.get('data', {}),
        'mutations': mutations.get('data', {})
    }

def get_tcga_expression_profile(tu, gene_symbol, cancer_type):
    """Get gene expression data from TCGA."""
    project_map = {
        'lung': 'TCGA-LUAD', 'breast': 'TCGA-BRCA',
        'colorectal': 'TCGA-COAD', 'melanoma': 'TCGA-SKCM',
        'glioblastoma': 'TCGA-GBM'
    }
    project_id = project_map.get(cancer_type.lower(), f'TCGA-{cancer_type.upper()}')

    expression = tu.tools.GDC_get_gene_expression(project_id=project_id, size=20)
    return expression.get('data', {})

def get_tcga_cnv_status(tu, gene_symbol, cancer_type):
    """Get copy number status from TCGA."""
    project_map = {'lung': 'TCGA-LUAD', 'breast': 'TCGA-BRCA'}
    project_id = project_map.get(cancer_type.lower(), f'TCGA-{cancer_type.upper()}')

    cnv = tu.tools.GDC_get_cnv_data(
        project_id=project_id, gene_symbol=gene_symbol, size=20
    )
    return cnv.get('data', {})

GDC Tools Summary:

2.4 DepMap Target Validation

def assess_target_essentiality(tu, gene_symbol, cancer_type=None):
    """Is this gene essential in cancer cell lines?"""
    dependencies = tu.tools.DepMap_get_gene_dependencies(gene_symbol=gene_symbol)

    if cancer_type:
        cell_lines = tu.tools.DepMap_get_cell_lines(
            cancer_type=cancer_type, page_size=20
        )
        return {
            'gene': gene_symbol,
            'dependencies': dependencies.get('data', {}),
            'cell_lines': cell_lines.get('data', {}),
            'interpretation': 'Negative scores = gene is essential for cell survival'
        }
    return dependencies

def get_gdsc_drug_sensitivity(drug_name, cancer_type=None, top=20):
    """Get cancer cell-line drug sensitivity (IC50/AUC) from GDSC.

    There is NO TU tool for drug response: DepMap/GDSC drug-sensitivity is a bulk
    download, not a REST API. Use the bundled helper, which downloads the public
    GDSC table once (cached) and returns the most-sensitive cell lines
    (lowest LN_IC50). The script also supports `cell-line` and `target` modes.
    """
    import os
    import subprocess

    here = os.path.dirname(__file__)
    script = os.path.join(here, "scripts", "gdsc_drug_response.py")
    cmd = ["python3", script, "drug", drug_name, "--top", str(top)]
    if cancer_type:
        cmd += ["--tcga", cancer_type]  # TCGA code, e.g. SKCM, LUAD, BRCA
    return subprocess.run(cmd, capture_output=True, text=True).stdout

DepMap / drug-sensitivity capabilities:

2.5 OncoKB Actionability Assessment

def get_oncokb_annotations(tu, gene_symbol, variant_name, tumor_type=None):
    """Get OncoKB actionability annotations."""
    annotation = tu.tools.OncoKB_annotate_variant(
        operation="annotate_variant",
        gene=gene_symbol,
        variant=variant_name,
        tumor_type=tumor_type  # OncoTree code e.g., "MEL", "LUAD"
    )

    result = {
        'oncogenic': annotation.get('data', {}).get('oncogenic'),
        'mutation_effect': annotation.get('data', {}).get('mutationEffect'),
        'highest_sensitive_level': annotation.get('data', {}).get('highestSensitiveLevel'),
        'treatments': annotation.get('data', {}).get('treatments', [])
    }

    gene_info = tu.tools.OncoKB_get_gene_info(
        operation="get_gene_info", gene=gene_symbol
    )
    result['is_oncogene'] = gene_info.get('data', {}).get('oncogene', False)
    result['is_tumor_suppressor'] = gene_info.get('data', {}).get('tsg', False)

    return result

def get_oncokb_cnv_annotation(tu, gene_symbol, alteration_type, tumor_type=None):
    """Get OncoKB annotation for copy number alterations."""
    annotation = tu.tools.OncoKB_annotate_copy_number(
        operation="annotate_copy_number",
        gene=gene_symbol,
        copy_number_type=alteration_type,  # "AMPLIFICATION" or "DELETION"
        tumor_type=tumor_type
    )
    return {
        'oncogenic': annotation.get('data', {}).get('oncogenic'),
        'treatments': annotation.get('data', {}).get('treatments', [])
    }

2.6 cBioPortal Cross-Study Analysis

def get_cbioportal_mutations(tu, gene_symbols, study_id="brca_tcga"):
    """Get mutation data from cBioPortal across cancer studies."""
    mutations = tu.tools.cBioPortal_get_mutations(
        study_id=study_id,
        gene_list=",".join(gene_symbols)
    )

    results = []
    for mut in mutations or []:
        results.append({
            'gene': mut.get('gene', {}).get('hugoGeneSymbol'),
            'protein_change': mut.get('proteinChange'),
            'mutation_type': mut.get('mutationType'),
            'sample_id': mut.get('sampleId'),
            'validation_status': mut.get('validationStatus')
        })
    return results

def get_cbioportal_cancer_studies(tu, cancer_type=None):
    """Get available cancer studies from cBioPortal."""
    studies = tu.tools.cBioPortal_get_cancer_studies(limit=50)
    if cancer_type:
        studies = [s for s in studies if cancer_type.lower() in s.get('cancerTypeId', '').lower()]
    return studies

def analyze_co_mutations(tu, gene_symbol, study_id):
    """Find frequently co-mutated genes."""
    profiles = tu.tools.cBioPortal_get_molecular_profiles(study_id=study_id)
    mutations = tu.tools.cBioPortal_get_mutations(
        study_id=study_id, gene_list=gene_symbol
    )
    return {'profiles': profiles, 'mutations': mutations, 'study_id': study_id}

cBioPortal Use Cases:

2.7 Human Protein Atlas Expression

def get_hpa_expression(tu, gene_symbol):
    """Get protein expression data from Human Protein Atlas."""
    gene_info = tu.tools.HPA_search_genes_by_query(search_query=gene_symbol)
    if not gene_info:
        return None

    cell_line_data = tu.tools.HPA_get_comparative_expression_by_gene_and_cellline(
        gene_name=gene_symbol,
        cell_line="a549"  # Lung cancer cell line
    )
    return {'gene_info': gene_info, 'cell_line_expression': cell_line_data}

def check_tumor_specific_expression(tu, gene_symbol, cancer_type):
    """Check if target has tumor-specific expression pattern."""
    cancer_to_cellline = {
        'lung': 'a549', 'breast': 'mcf7', 'liver': 'hepg2',
        'cervical': 'hela', 'prostate': 'pc3'
    }
    cell_line = cancer_to_cellline.get(cancer_type.lower(), 'a549')

    return tu.tools.HPA_get_comparative_expression_by_gene_and_cellline(
        gene_name=gene_symbol, cell_line=cell_line
    )

---

Phase 2.5: Tumor Expression Context (CELLxGENE)

def get_tumor_expression_context(tu, gene_symbol, cancer_type):
    """Get cell-type specific expression in tumor microenvironment."""
    expression = tu.tools.CELLxGENE_get_expression_data(
        gene=gene_symbol, tissue=cancer_type
    )
    cell_metadata = tu.tools.CELLxGENE_get_cell_metadata(gene=gene_symbol)

    tumor_expression = [c for c in expression if 'tumor' in c.get('cell_type', '').lower()]
    normal_expression = [c for c in expression if 'normal' in c.get('cell_type', '').lower()]

    return {
        'tumor_expression': tumor_expression,
        'normal_expression': normal_expression,
        'ratio': calculate_tumor_normal_ratio(tumor_expression, normal_expression)
    }

Why it matters:

• Confirms target is expressed in tumor cells (not just stroma)
• Identifies potential resistance from tumor heterogeneity
• Supports drug selection based on expression patterns

---

Phase 3: Treatment Options

Query Order

1. OpenTargets_get_associated_drugs_by_target_ensemblID -> Approved drugs 2. DailyMed_search_spls -> FDA label details 3. ChEMBL_get_drug_mechanisms_of_action_by_chemblId -> Mechanism

Treatment Output Example

## Treatment Recommendations

### First-Line Options
**1. Osimertinib (Tagrisso)** (Tier 1)
- FDA-approved for EGFR T790M+ NSCLC
- Evidence: AURA3 trial (ORR 71%, mPFS 10.1 mo)
- Source: FDA label, PMID:27959700

### Second-Line Options
**2. Combination: Osimertinib + [Agent]** (Tier 2)
- Evidence: Phase 2 data
- Source: NCT04487080

---

Phase 3.5: Pathway & Network Analysis

Pathway Context (KEGG/Reactome)

def get_pathway_context(tu, gene_symbols, cancer_type):
    """Get pathway context for drug combinations and resistance."""
    pathway_map = {}
    for gene in gene_symbols:
        kegg_gene = tu.tools.kegg_find_genes(query=f"hsa:{gene}")
        if kegg_gene:
            pathways = tu.tools.kegg_get_gene_info(gene_id=kegg_gene[0]['id'])
            pathway_map[gene] = pathways.get('pathways', [])

        reactome = tu.tools.reactome_disease_target_score(
            disease=cancer_type, target=gene
        )
        pathway_map[f"{gene}_reactome"] = reactome
    return pathway_map

Protein Interaction Network (IntAct)

def get_resistance_network(tu, drug_target, bypass_candidates):
    """Find protein interactions that may mediate resistance."""
    network = tu.tools.intact_get_interaction_network(
        gene=drug_target, depth=2
    )
    bypass_in_network = [
        node for node in network['nodes']
        if node['gene'] in bypass_candidates
    ]
    return {
        'network': network,
        'bypass_connections': bypass_in_network,
        'total_interactors': len(network['nodes'])
    }

---

Phase 4: Resistance Analysis

Known Mechanisms (Literature + CIViC)

def analyze_resistance(tu, drug_name, gene_symbol):
    """Find known resistance mechanisms."""
    resistance = tu.tools.civic_search_evidence_items(
        drug=drug_name,
        evidence_type="Predictive",
        clinical_significance="Resistance"
    )
    papers = tu.tools.PubMed_search_articles(
        query=f'"{drug_name}" AND "{gene_symbol}" AND resistance',
        limit=20
    )
    return {'civic': resistance, 'literature': papers}

Structure-Based Analysis (NvidiaNIM)

def model_resistance_mechanism(tu, gene_ids, mutation, drug_smiles):
    """Model structural impact of resistance mutation."""
    structure = tu.tools.NvidiaNIM_alphafold2(sequence=wild_type_sequence)
    wt_docking = tu.tools.NvidiaNIM_diffdock(
        protein=structure['structure'],
        ligand=drug_smiles,
        num_poses=5
    )
    # Compare binding site changes
    # Report: "T790M introduces bulky methionine, steric clash with erlotinib"

---

Phase 5: Clinical Trial Matching

def find_trials(tu, condition, biomarker, location=None):
    """Find matching clinical trials."""
    trials = tu.tools.search_clinical_trials(
        condition=condition,
        intervention=biomarker,
        status="Recruiting",
        pageSize=50
    )
    nct_ids = [t['nct_id'] for t in trials[:20]]
    eligibility = tu.tools.get_clinical_trial_eligibility_criteria(nct_ids=nct_ids)
    return trials, eligibility

---

Phase 5.5: Literature Evidence

Published Literature (PubMed)

def search_treatment_literature(tu, cancer_type, biomarker, drug_name):
    """Search for treatment evidence in literature."""
    drug_papers = tu.tools.PubMed_search_articles(
        query=f'"{drug_name}" AND "{biomarker}" AND "{cancer_type}"',
        limit=20
    )
    resistance_papers = tu.tools.PubMed_search_articles(
        query=f'"{drug_name}" AND resistance AND mechanism',
        limit=15
    )
    return {'treatment_evidence': drug_papers, 'resistance_literature': resistance_papers}

Preprints (BioRxiv/MedRxiv)

def search_preprints(tu, cancer_type, biomarker):
    """Search preprints for cutting-edge findings."""
    biorxiv = tu.tools.BioRxiv_list_recent_preprints(
        query=f"{cancer_type} {biomarker} treatment", limit=10
    )
    medrxiv = tu.tools.MedRxiv_get_preprint(
        query=f"{cancer_type} {biomarker}", limit=10
    )
    return {'biorxiv': biorxiv, 'medrxiv': medrxiv}

Citation Analysis (OpenAlex)

def analyze_key_papers(tu, key_papers):
    """Get citation metrics for key evidence papers."""
    analyzed = []
    for paper in key_papers[:10]:
        work = tu.tools.openalex_search_works(query=paper['title'], limit=1)
        if work:
            analyzed.append({
                'title': paper['title'],
                'citations': work[0].get('cited_by_count', 0),
                'year': work[0].get('publication_year'),
                'open_access': work[0].get('is_oa', False)
            })
    return analyzed

Precision Oncology - Completeness Checklist

Use this checklist to verify report completeness before delivery.

Pre-Execution Checklist

• [ ] User provided cancer type
• [ ] User provided molecular profile (mutations/fusions/amplifications)
• [ ] Prior therapy history obtained (or confirmed treatment-naive)
• [ ] Tool parameters verified (see SKILL.md Phase 0)

---

Report Section Checklist

Section 1: Variant Interpretation

• [ ] All reported variants included in table
• [ ] Each variant has significance assessment
• [ ] Each variant has evidence level (★★★/★★☆/★☆☆/☆☆☆)
• [ ] Clinical implication stated for each variant
• [ ] Sources cited (CIViC EID, ClinVar VCV, PMID)

Section 2: Treatment Recommendations

• [ ] ≥1 first-line option with ★★★ evidence (or explanation why none)
• [ ] Dosing information included
• [ ] Key trial data cited (ORR, PFS, OS where available)
• [ ] Contraindications/cautions noted if applicable
• [ ] FDA approval status stated

Section 3: Resistance Analysis

• [ ] Current resistance mechanism explained (if applicable)
• [ ] Structural basis described (if known)
• [ ] Future resistance mechanisms anticipated
• [ ] Monitoring strategy suggested
• [ ] "Not applicable" stated if treatment-naive

Section 4: Clinical Trials

• [ ] ≥3 relevant trials listed (or "no matching trials")
• [ ] NCT IDs included
• [ ] Phase stated
• [ ] Status (Recruiting/Active) stated
• [ ] Biomarker requirement noted
• [ ] Access date noted

Section 5: Next Steps

• [ ] Specific treatment recommendation made
• [ ] Follow-up plan stated
• [ ] Additional testing recommended if appropriate
• [ ] Timeline suggested (when to reassess)

---

Executive Summary Checklist

• [ ] Summarizes key finding in 2-3 sentences
• [ ] States recommended treatment explicitly
• [ ] Evidence level mentioned
• [ ] Actionable (tells user what to DO)

---

Data Quality Checklist

• [ ] All sources cited (CIViC, ClinVar, PMID, NCT, FDA)
• [ ] Evidence grades applied consistently
• [ ] No unsupported claims
• [ ] Data gaps acknowledged in relevant sections

---

Tool Execution Checklist

---

Final Quality Check

• [ ] Report is actionable (answers "what should we do?")
• [ ] No tool outputs shown directly (processed into narrative)
• [ ] Appropriate caveats for uncertainty
• [ ] Patient-specific (not generic disease info)
• [ ] Reviewed for clinical accuracy

---

Data Gaps Documentation

If any tool failed or data unavailable:

---

Sign-off

• Report generated: [ ] Yes
• Completeness verified: [ ] Yes
• Ready for delivery: [ ] Yes

Precision Oncology - Examples

Example 1: EGFR-Mutant NSCLC (First-Line)

User Query

"Patient with stage IV NSCLC, molecular testing shows EGFR L858R mutation. What are the treatment options?"

Expected Output

# Precision Oncology Report

**Date**: 2026-02-04

## Patient Profile
- **Diagnosis**: Stage IV Non-Small Cell Lung Cancer (NSCLC)
- **Molecular Profile**: EGFR L858R mutation
- **Prior Therapy**: Treatment-naive

---

## Executive Summary

This patient has an EGFR L858R-driven NSCLC with multiple FDA-approved targeted therapy options. **Recommended first-line treatment: Osimertinib (Tagrisso)** based on FLAURA trial data showing superior PFS and OS compared to earlier-generation TKIs. Alternative options include erlotinib or gefitinib if osimertinib is unavailable.

---

## 1. Variant Interpretation

| Variant | Gene | Significance | Evidence Level | Clinical Implication |
|---------|------|--------------|----------------|---------------------|
| L858R | EGFR | Activating, oncogenic driver | ★★★ (Level A) | Sensitive to EGFR TKIs |

**Details**: L858R is the most common EGFR activating mutation (~40-45% of EGFR-mutant NSCLC). Located in exon 21, it increases kinase activity and sensitivity to EGFR tyrosine kinase inhibitors.

*Source: CIViC EID:883, ClinVar VCV000016610*

---

## 2. Treatment Recommendations

### First-Line Options

**1. Osimertinib (Tagrisso)** ★★★ RECOMMENDED
- **Approval**: FDA-approved first-line for EGFR-mutant NSCLC (2018)
- **Dosing**: 80 mg PO daily
- **Evidence**: FLAURA trial - mPFS 18.9 mo vs 10.2 mo (erlotinib/gefitinib), mOS 38.6 mo vs 31.8 mo
- **Advantages**: CNS penetration, activity against T790M if it emerges
- **Source**: FDA label, PMID:29151359

**2. Erlotinib (Tarceva)** ★★★
- **Approval**: FDA-approved for EGFR exon 19 del or L858R
- **Dosing**: 150 mg PO daily
- **Evidence**: EURTAC trial - mPFS 9.7 mo vs 5.2 mo (chemotherapy)
- **Source**: FDA label, PMID:22452896

**3. Gefitinib (Iressa)** ★★★
- **Approval**: FDA-approved for EGFR-mutant NSCLC
- **Dosing**: 250 mg PO daily
- **Evidence**: IPASS trial established EGFR-TKI paradigm
- **Source**: FDA label, PMID:19692680

### Second-Line (After Progression)

**If T790M emerges**: Switch to osimertinib (if not used first-line)
**If non-T790M resistance**: Consider combination strategies or clinical trials

---

## 3. Resistance Analysis

**Not applicable** - Patient is treatment-naive.

**Anticipated resistance mechanisms to monitor**:
- T790M mutation (~50-60% of osimertinib-naive patients on 1st/2nd gen TKIs)
- C797S mutation (after osimertinib)
- MET amplification
- HER2 amplification
- Small cell transformation

---

## 4. Clinical Trial Options

| NCT ID | Phase | Agent | Biomarker | Status |
|--------|-------|-------|-----------|--------|
| NCT04487080 | 2 | Amivantamab + lazertinib | EGFR-mutant | Recruiting |
| NCT05388669 | 3 | Patritumab deruxtecan | EGFR-mutant | Recruiting |
| NCT04862780 | 2 | Osimertinib + savolitinib | EGFR-mutant | Recruiting |

*Source: ClinicalTrials.gov, accessed 2026-02-04*

---

## 5. Next Steps

1. **Initiate osimertinib 80 mg daily** as first-line therapy
2. **Baseline brain MRI** given CNS tropism of NSCLC
3. **Educate patient** on common side effects (rash, diarrhea, QTc)
4. **Schedule reassessment** at 8-12 weeks with imaging
5. **Plan liquid biopsy** at progression for resistance profiling

---

## Data Sources

| Source | Query | Data Retrieved |
|--------|-------|----------------|
| CIViC | EGFR L858R | Evidence items (Level A, Predictive) |
| OpenTargets | ENSG00000146648 | Approved drugs (7) |
| ClinicalTrials.gov | EGFR NSCLC Recruiting | 47 trials |

---

Example 2: Acquired Resistance (T790M)

User Query

"Patient was on erlotinib for EGFR-mutant lung cancer for 14 months, now progressing. Liquid biopsy shows T790M. What next?"

Expected Output

# Precision Oncology Report

**Date**: 2026-02-04

## Patient Profile
- **Diagnosis**: Stage IV NSCLC, EGFR-mutant
- **Molecular Profile**: EGFR L858R + T790M (acquired)
- **Prior Therapy**: Erlotinib x 14 months → progression

---

## Executive Summary

Patient has developed T790M-mediated resistance, the most common mechanism after 1st/2nd generation EGFR TKIs. **Recommended: Switch to osimertinib**, a 3rd-generation TKI specifically designed for T790M. This is FDA-approved with strong Level A evidence.

---

## 1. Variant Interpretation

| Variant | Gene | Significance | Evidence Level | Clinical Implication |
|---------|------|--------------|----------------|---------------------|
| L858R | EGFR | Activating driver | ★★★ | Original sensitizing mutation |
| T790M | EGFR | Acquired resistance | ★★★ | Resistant to erlotinib, sensitive to osimertinib |

**Mechanism**: T790M substitutes threonine with bulkier methionine at the "gatekeeper" position (codon 790). This creates steric hindrance blocking erlotinib binding while the kinase remains active. Osimertinib covalently binds C797, bypassing T790M.

*Source: CIViC EID:1021, PMID:23948351*

---

## 2. Treatment Recommendations

### Recommended

**Osimertinib (Tagrisso)** ★★★
- **Approval**: FDA-approved for T790M+ NSCLC (2015, accelerated; 2017, regular)
- **Dosing**: 80 mg PO daily
- **Evidence**: AURA3 trial - mPFS 10.1 mo vs 4.4 mo (chemotherapy), ORR 71%
- **Source**: FDA label, PMID:27959700

### Alternatives (if osimertinib unavailable)

**Chemotherapy (platinum + pemetrexed)** ★★☆
- Standard salvage if targeted therapy not feasible
- mPFS ~5 months in this setting

---

## 3. Resistance Analysis

### Current Resistance Mechanism: T790M

**Structural basis**: T790M mutation substitutes the "gatekeeper" threonine-790 with methionine. The bulkier methionine side chain sterically blocks binding of 1st/2nd-generation reversible EGFR TKIs (erlotinib, gefitinib, afatinib).

[Structure-based visualization could be generated with NvidiaNIM if needed]

### Future Resistance Concerns (after osimertinib)

| Mechanism | Frequency | Detection | Options |
|-----------|-----------|-----------|---------|
| C797S (cis) | ~20% | Liquid biopsy | Combination strategies, trials |
| C797S (trans) | ~5% | Liquid biopsy | 1st-gen TKI may work |
| MET amp | ~15% | NGS, FISH | MET inhibitor combination |
| HER2 amp | ~5% | NGS, FISH | HER2-directed therapy |
| SCLC transformation | ~5% | Biopsy | Platinum-etoposide |

*Source: PMID:29106415*

---

## 4. Clinical Trial Options

| NCT ID | Phase | Agent | Rationale | Status |
|--------|-------|-------|-----------|--------|
| NCT04487080 | 2 | Amivantamab + lazertinib | EGFR/MET bispecific | Recruiting |
| NCT05338970 | 2 | BBT-176 | 4th-gen TKI | Recruiting |

---

## 5. Next Steps

1. **Start osimertinib 80 mg daily** immediately
2. **Reassess response** at 8 weeks with CT
3. **Repeat liquid biopsy** at progression to identify next resistance mechanism
4. **Consider clinical trial enrollment** proactively for post-osimertinib options

---

Example 3: KRAS G12C (Limited Options)

User Query

"Stage IV lung adenocarcinoma with KRAS G12C mutation, failed platinum-based chemotherapy. Options?"

Expected Output

# Precision Oncology Report

**Date**: 2026-02-04

## Patient Profile
- **Diagnosis**: Stage IV Lung Adenocarcinoma
- **Molecular Profile**: KRAS G12C
- **Prior Therapy**: Platinum-based chemotherapy (failed)

---

## Executive Summary

KRAS G12C is now a druggable target with FDA-approved inhibitors. **Recommended: Sotorasib (Lumakras) or adagrasib (Krazati)** as second-line treatment. Both are covalent KRAS G12C inhibitors with demonstrated clinical benefit.

---

## 1. Variant Interpretation

| Variant | Gene | Significance | Evidence Level | Clinical Implication |
|---------|------|--------------|----------------|---------------------|
| G12C | KRAS | Oncogenic driver | ★★★ | Targetable with G12C inhibitors |

**Details**: KRAS G12C is found in ~13% of NSCLC. The cysteine substitution at codon 12 creates a unique druggable pocket exploited by covalent inhibitors. Historically "undruggable" until sotorasib approval in 2021.

*Source: CIViC, PMID:34096690*

---

## 2. Treatment Recommendations

### First Choice (post-chemotherapy)

**1. Sotorasib (Lumakras)** ★★★
- **Approval**: FDA-approved (2021) for KRAS G12C NSCLC after prior therapy
- **Dosing**: 960 mg PO daily
- **Evidence**: CodeBreaK 100 - ORR 37%, mPFS 6.8 mo, mOS 12.5 mo
- **Source**: PMID:34096690

**2. Adagrasib (Krazati)** ★★★
- **Approval**: FDA-approved (2022) for KRAS G12C NSCLC after prior therapy
- **Dosing**: 600 mg PO BID
- **Evidence**: KRYSTAL-1 - ORR 43%, mPFS 6.5 mo
- **Advantage**: Better CNS penetration
- **Source**: PMID:36546659

### Combinations in Development

**Sotorasib + anti-EGFR** ★★☆
- Rationale: EGFR blockade may overcome adaptive resistance
- Evidence: Phase 1b data promising
- Status: Clinical trials ongoing

---

## 3. Resistance Analysis

### Anticipated Resistance Mechanisms

| Mechanism | Frequency | Strategy |
|-----------|-----------|----------|
| KRAS secondary mutations | ~20% | Novel KRAS inhibitors |
| KRAS amplification | ~10% | Dose escalation studies |
| RTK bypass (EGFR, MET) | ~25% | Combination strategies |
| PI3K/mTOR activation | ~15% | PI3K inhibitor combinations |

*Note: Resistance to G12C inhibitors is an active research area*

---

## 4. Clinical Trial Options

| NCT ID | Phase | Agent | Mechanism | Status |
|--------|-------|-------|-----------|--------|
| NCT04185883 | 3 | Sotorasib + pembrolizumab | G12C + PD-1 | Recruiting |
| NCT05198934 | 2 | Adagrasib + pembrolizumab | G12C + PD-1 | Recruiting |
| NCT04330664 | 1/2 | JDQ443 | Next-gen G12C | Recruiting |

---

## 5. Next Steps

1. **Initiate sotorasib or adagrasib** based on formulary/access
2. **If CNS disease present**: Prefer adagrasib (better CNS penetration)
3. **Baseline LFTs** - hepatotoxicity is a class effect
4. **Clinical trial consideration** for combination approaches

---

Example 4: No Actionable Mutations

User Query

"Stage IV lung adenocarcinoma, NGS panel shows no actionable mutations, PD-L1 <1%. What now?"

Expected Output

# Precision Oncology Report

## Executive Summary

No FDA-approved targeted therapy applies. Low PD-L1 limits single-agent immunotherapy benefit. **Recommended: Platinum-based chemotherapy ± immunotherapy** per standard guidelines.

## 1. Molecular Profile Analysis

| Finding | Clinical Implication |
|---------|---------------------|
| EGFR wild-type | Not eligible for EGFR TKIs |
| ALK negative | Not eligible for ALK inhibitors |
| ROS1 negative | Not eligible for ROS1 inhibitors |
| KRAS wild-type | Not eligible for G12C inhibitors |
| PD-L1 <1% | Limited benefit from single-agent IO |

## 2. Treatment Recommendations

**1. Carboplatin + pemetrexed + pembrolizumab** ★★★
- KEYNOTE-189: Benefit across PD-L1 subgroups
- mPFS 8.8 mo, mOS 22.0 mo

**2. Carboplatin + paclitaxel + bevacizumab + atezolizumab** ★★★
- IMpower150: Alternative chemo-IO regimen

## 3. Recommend Additional Testing

Consider:
- **RNA-based fusion panel** (may detect fusions missed by DNA-only)
- **ctDNA if tissue insufficient**
- **HER2 mutations** (emerging target)
- **NTRK fusions** (pan-tumor approval)
- **MET exon 14 skipping** (FDA-approved options)

Precision Oncology Report Template

File naming: [PATIENT_ID]_oncology_report.md

---

Template Structure

# Precision Oncology Report

**Patient ID**: [ID] | **Date**: [Date]

## Patient Profile
- **Diagnosis**: [Cancer type, stage]
- **Molecular Profile**: [Mutations, fusions]
- **Prior Therapy**: [Previous treatments]

---

## Executive Summary
[2-3 sentence summary of key findings and recommendation]

---

## 1. Variant Interpretation
[Table with variants, significance, evidence levels]

### COSMIC Mutation Frequency

| Gene | Mutation | COSMIC Count | Primary Cancer Types | FATHMM Prediction |
|------|----------|--------------|---------------------|-------------------|
| EGFR | L858R | 15,234 | Lung (85%), Colorectal (5%) | Pathogenic |
| EGFR | T790M | 8,567 | Lung (95%) | Pathogenic |
| BRAF | V600E | 45,678 | Melanoma (50%), Colorectal (15%) | Pathogenic |

### TCGA/GDC Patient Tumor Data

| Gene | TCGA Project | SSM Cases | CNV Amp | CNV Del | % Samples |
|------|-------------|-----------|---------|---------|-----------|
| EGFR | TCGA-LUAD | 156 | 89 | 5 | 28% |
| EGFR | TCGA-GBM | 45 | 312 | 2 | 57% |
| KRAS | TCGA-PAAD | 134 | 8 | 1 | 92% |

*Source: GDC via `GDC_get_mutation_frequency`, `GDC_get_cnv_data`*

### DepMap Target Essentiality

| Gene | Mean Effect (All) | Mean Effect (Cancer Type) | Selectivity | Interpretation |
|------|-------------------|---------------------------|-------------|----------------|
| EGFR | -0.15 | -0.45 (lung) | Cancer-selective | Good target |
| KRAS | -0.82 | -0.91 (pancreatic) | Essential | Hard to target |
| MYC | -0.95 | -0.93 | Pan-essential | Challenging target |

*Effect score <-0.5 = strongly essential for cell survival*
*Source: DepMap via `DepMap_get_gene_dependencies`*

### Expression Validation (Human Protein Atlas)

| Gene | Tumor Cell Line | Expression | Normal Tissue | Differential |
|------|-----------------|------------|---------------|--------------|
| EGFR | A549 (lung) | High | Low-Medium | Tumor-elevated |
| ALK | H3122 (lung) | High | Not detected | Tumor-specific |
| HER2 | MCF7 (breast) | Medium | Low | Elevated |

*Source: Human Protein Atlas via `HPA_get_comparative_expression_by_gene_and_cellline`*

## 2. Tumor Expression Context

### Target Expression in Tumor Microenvironment (CELLxGENE)

| Gene | Tumor Cells | Normal Cells | Tumor/Normal Ratio | Interpretation |
|------|-------------|--------------|-------------------|----------------|
| EGFR | High (TPM=85) | Medium (TPM=25) | 3.4x | Good target |
| MET | Medium (TPM=35) | Low (TPM=8) | 4.4x | Potential bypass |
| AXL | High (TPM=120) | Low (TPM=15) | 8.0x | Resistance marker |

### Cell Type Distribution

- **EGFR-high cells**: Tumor epithelial (85%), CAFs (10%), immune (5%)
- **MET-high cells**: Tumor epithelial (70%), endothelial (20%), immune (10%)

## 3. Treatment Recommendations
### First-Line Options
[Prioritized list with evidence]

### Second-Line Options
[Alternative approaches]

## 4. Pathway & Network Analysis

### Signaling Pathway Context (KEGG)

| Pathway | Genes Involved | Relevance | Drug Targets |
|---------|---------------|-----------|--------------|
| EGFR signaling (hsa04012) | EGFR, MET, ERBB3 | Primary pathway | Osimertinib, Capmatinib |
| PI3K-AKT (hsa04151) | PIK3CA, AKT1 | Downstream | Alpelisib |
| RAS-MAPK (hsa04010) | KRAS, BRAF, MEK | Bypass potential | Sotorasib, Trametinib |

### Protein Interaction Network (IntAct)

| Target | Direct Interactors | Key Partners | Relevance |
|--------|-------------------|--------------|-----------|
| EGFR | 156 | MET, ERBB2, ERBB3, GRB2 | Bypass pathways |
| MET | 89 | EGFR, HGF, GAB1 | Resistance mediator |

## 5. Resistance Analysis (if applicable)
[Mechanism explanation, strategies to overcome]

## 6. Clinical Trial Options
[Matched trials with eligibility]

## 7. Literature Evidence

### Key Clinical Studies

| PMID | Title | Year | Citations | Evidence Type |
|------|-------|------|-----------|---------------|
| 27959700 | AURA3: Osimertinib vs chemotherapy... | 2017 | 2,450 | Phase 3 trial |
| 30867819 | Mechanisms of osimertinib resistance... | 2019 | 680 | Review |

### Recent Preprints (Not Peer-Reviewed)

| Source | Title | Posted | Key Finding |
|--------|-------|--------|-------------|
| MedRxiv | Novel C797S resistance strategy... | 2024-01 | Fourth-gen TKI |
| BioRxiv | scRNA-seq reveals resistance... | 2024-02 | Cell state switch |

**Note**: Preprints have NOT undergone peer review. Interpret with caution.

## 8. Next Steps
1. [Specific actionable recommendation]
2. [Follow-up testing if needed]
3. [Referral if appropriate]

---

## Data Sources
| Source | Query | Data Retrieved |
|--------|-------|----------------|
| CIViC | [gene] [variant] | Evidence items |
| ClinicalTrials.gov | [condition] | Active trials |
| COSMIC | [gene] | Somatic mutation frequency |
| GDC/TCGA | [gene] [project] | Patient tumor data |
| DepMap | [gene] | Target essentiality |
| OncoKB | [gene] [variant] | Actionability level |
| cBioPortal | [study] [genes] | Cross-study mutations |
| HPA | [gene] | Expression validation |
| CELLxGENE | [gene] [tissue] | Cell-type expression |
| KEGG/Reactome | [gene] | Pathway context |
| IntAct | [gene] | Protein interactions |
| PubMed | [query] | Published evidence |
| BioRxiv/MedRxiv | [query] | Preprints |
| OpenAlex | [paper] | Citation analysis |

---

Completeness Checklist

Before finalizing report:

• [ ] All variants interpreted with evidence levels
• [ ] >= 1 first-line recommendation with evidence (or explain why none)
• [ ] Resistance mechanism addressed (if prior therapy failed)
• [ ] >= 3 clinical trials listed (or "no matching trials")
• [ ] Executive summary is actionable (says what to DO)
• [ ] All recommendations have source citations
• [ ] COSMIC hotspot analysis included
• [ ] TCGA/GDC real patient data included
• [ ] DepMap target essentiality assessed
• [ ] Expression validation (HPA + CELLxGENE) performed
• [ ] Pathway context provided for combination rationale

Precision Oncology - Tool Reference

Variant Interpretation Tools

CIViC (Clinical Interpretation of Variants in Cancer)

Example - Get EGFR L858R evidence:

# 1. Search for variant
variants = tu.tools.civic_search_variants(query="EGFR L858R")
# 2. Get evidence items
for v in variants:
    evidence = tu.tools.civic_get_variant(id=v['id'])

ClinVar

COSMIC - Somatic Cancer Mutations (NEW)

Example - Get BRAF mutations:

# Search for specific mutation
result = tu.tools.COSMIC_search_mutations(
    operation="search",
    terms="BRAF V600E",
    max_results=20
)
# Returns: mutation_id, GeneName, MutationCDS, MutationAA, PrimarySite, PrimaryHistology

# Get all mutations for gene (for hotspot analysis)
mutations = tu.tools.COSMIC_get_mutations_by_gene(
    operation="get_by_gene",
    gene="EGFR",
    max_results=200,
    genome_build=38
)
# Returns: All EGFR mutations with cancer type distribution

Why use COSMIC:

• Gold standard for somatic cancer mutations
• Cancer type distribution (which tumors have this mutation)
• Mutation frequency (recurrent vs. rare)
• FATHMM pathogenicity prediction

Genome Build Note: Use genome_build=38 for GRCh38 or genome_build=37 for GRCh37.

---

GDC/TCGA - Patient Tumor Data (NEW)

Access real patient tumor data from The Cancer Genome Atlas.

Example - Get EGFR mutations in lung cancer:

# Get mutation frequency for gene
freq = tu.tools.GDC_get_mutation_frequency(
    gene_symbol="EGFR"
)
# Returns: SSM case count, CNV gain/loss counts

# Get specific mutations in lung adenocarcinoma
mutations = tu.tools.GDC_get_ssm_by_gene(
    gene_symbol="EGFR",
    project_id="TCGA-LUAD",
    size=50
)
# Returns: mutation coordinates, amino acid changes, sample counts

TCGA Project IDs:

Why use GDC/TCGA:

• Real patient tumor data - Not cell lines, actual human tumors
• Pan-cancer analysis - Same gene across 33 cancer types
• Multi-omics - Mutations + expression + CNV
• Clinical annotations - Stage, survival data available

---

OncoKB - Therapeutic Actionability (NEW)

FDA-recognized biomarker annotations and treatment recommendations.

Example - Get variant actionability:

# Annotate BRAF V600E in melanoma
result = tu.tools.OncoKB_annotate_variant(
    operation="annotate_variant",
    gene="BRAF",
    variant="V600E",
    tumor_type="MEL"  # Melanoma
)
# Returns: oncogenic, mutationEffect, highestSensitiveLevel, treatments

# Check if gene is oncogene/TSG
gene_info = tu.tools.OncoKB_get_gene_info(
    operation="get_gene_info",
    gene="BRAF"
)
# Returns: oncogene=True, tsg=False

OncoKB Evidence Levels:

OncoTree Tumor Type Codes (common):

---

cBioPortal - Cross-Study Analysis (NEW)

Aggregate genomic data across cancer studies.

Example - Query mutations across studies:

# Get studies
studies = tu.tools.cBioPortal_get_cancer_studies(limit=50)

# Get EGFR mutations in TCGA-LUAD
mutations = tu.tools.cBioPortal_get_mutations(
    study_id="luad_tcga",
    gene_list="EGFR,KRAS,ALK"
)
# Returns: proteinChange, mutationType, sampleId, validationStatus

# Get molecular profiles for study
profiles = tu.tools.cBioPortal_get_molecular_profiles(
    study_id="brca_tcga"
)
# Returns: mutation profiles, CNA profiles, expression profiles

Common cBioPortal Study IDs:

---

Human Protein Atlas - Expression Validation (NEW)

Protein expression data in tissues and cell lines.

Example - Check target expression:

# Search for gene
gene = tu.tools.HPA_search_genes_by_query(search_query="EGFR")
# Returns: Gene name, Ensembl ID, synonyms

# Compare expression in cancer cell line vs normal
expression = tu.tools.HPA_get_comparative_expression_by_gene_and_cellline(
    gene_name="EGFR",
    cell_line="a549"  # Lung cancer cell line
)
# Returns: expression level differences vs healthy tissue

Supported Cancer Cell Lines:

Why HPA matters for precision oncology:

• Target validation - Confirm target expressed in tumor
• Differential expression - Compare tumor vs normal
• Tissue specificity - Predict on-target/off-tumor effects
• Cell line selection - Choose appropriate models

---

DepMap - Target Validation (NEW)

Cancer cell line dependency data from CRISPR knockout screens.

Example - Assess target essentiality:

# Is KRAS essential in cancer cells?
deps = tu.tools.DepMap_get_gene_dependencies(
    gene_symbol="KRAS"
)
# Returns: gene info, note about effect scores

# Get lung cancer cell lines
cells = tu.tools.DepMap_get_cell_lines(
    tissue="Lung",
    cancer_type="Non-Small Cell Lung Cancer",
    page_size=20
)
# Returns: cell line names, cancer types, MSI status

Effect Score Interpretation:

Why use DepMap for Precision Oncology:

• Target validation - Proves gene is essential for cancer survival
• Cancer selectivity - Is it essential only in cancer?
• Combination targets - Identify synthetic lethal partners
• Drug sensitivity - Which cell lines respond to drugs?

---

Drug/Treatment Tools

OpenTargets

Parameter Note: Always use ensemblId (camelCase), NOT ensemblID.

ChEMBL

DailyMed

---

Clinical Trial Tools

ClinicalTrials.gov

Common Status Values: "Recruiting", "Active, not recruiting", "Completed"

---

Gene/Protein Tools

MyGene.info

UniProt

---

Structure Analysis Tools (NvidiaNIM)

Protein Structure

Molecular Docking

---

Literature Tools

PubMed

EuropePMC

---

Expression & Network Tools (NEW)

CELLxGENE - Tumor Single-Cell Expression

Example - Tumor expression:

# Get expression in lung cancer
expression = tu.tools.CELLxGENE_get_expression_data(
    gene="EGFR",
    tissue="lung"
)
# Returns: Expression per cell type (tumor, CAF, immune, etc.)

IntAct - Protein Interactions

Example - Resistance network:

# Get EGFR interaction partners
network = tu.tools.intact_get_interaction_network(
    gene="EGFR",
    depth=1  # Direct interactors
)
# Returns: MET, ERBB2, ERBB3, etc.

KEGG - Cancer Pathways

Example - Get pathway context:

pathways = tu.tools.kegg_get_gene_info(gene_id="hsa:1956")  # EGFR
# Returns: EGFR signaling, NSCLC pathway, etc.

---

Literature Tools (NEW)

PubMed - Published Literature

BioRxiv/MedRxiv - Preprints

⚠️ Important: Flag preprints as NOT peer-reviewed in reports.

Example - Search preprints:

# bioRxiv/medRxiv don't have search APIs, use EuropePMC
preprints = tu.tools.EuropePMC_search_articles(
    query="EGFR inhibitor resistance",
    source="PPR",  # PPR = Preprints only
    pageSize=20
)

### OpenAlex - Citation Analysis

| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `openalex_search_works` | Search with citations | `query`, `limit` |
| `openalex_get_author` | Author metrics | `author_id` |

---

## Workflow Examples

### Example 1: EGFR-Mutant Lung Cancer

1. Resolve EGFR IDs

gene_ids = resolve_gene(tu, "EGFR")

2. Get CIViC evidence for L858R

civic_ev = get_civic_evidence(tu, "EGFR", "L858R")

3. Get approved drugs

drugs = tu.tools.OpenTargets_get_associated_drugs_by_target_ensemblID( ensemblId=gene_ids['ensembl'] )

4. Find clinical trials

trials = tu.tools.search_clinical_trials( condition="Non-Small Cell Lung Cancer", intervention="EGFR", status="Recruiting" )

### Example 2: Resistance Analysis

1. Get known resistance mechanisms for osimertinib

resistance = tu.tools.civic_search_evidence_items( drug="osimertinib", evidence_type="Predictive", clinical_significance="Resistance" )

2. Literature on C797S

papers = tu.tools.PubMed_search_articles( query='"osimertinib" AND "C797S" AND resistance', limit=20 )

3. Structural analysis if needed

Get protein structure for binding analysis

---

## Prognosis & Survival Tools

### CancerPrognosis

| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `CancerPrognosis_get_survival_data` | OS/DFS survival curves for TCGA cancers | `cancer` (TCGA code, e.g. `"BRCA"`), `limit` |
| `CancerPrognosis_get_gene_expression` | mRNA expression by cancer type | `cancer`, `gene` |
| `CancerPrognosis_search_studies` | Find non-TCGA studies in cBioPortal | `keyword` |

**Supported TCGA codes** (33 total): ACC, BLCA, BRCA, CESC, CHOL, COAD, DLBC, ESCA, GBM, HNSC, KICH, KIRC, KIRP, LAML, LGG, LIHC, LUAD, LUSC, MESO, OV, PAAD, PCPG, PRAD, READ, SARC, SKCM, STAD, TGCT, THCA, THYM, UCEC, UCS, UVM

**Non-TCGA cancer type routing** — these cancers are NOT in TCGA; use `CancerPrognosis_search_studies`:

| Cancer | Keyword for search_studies | Notes |
|--------|---------------------------|-------|
| CLL / Chronic lymphocytic leukemia | `"CLL"` or `"leukemia"` | Most CLL studies are WES-only (no survival/expression data) |
| SLL | `"CLL"` | Treated as CLL in cBioPortal |
| Multiple myeloma (MM) | `"myeloma"` | |
| Follicular lymphoma (FL) | `"follicular"` | |
| Mantle cell lymphoma (MCL) | `"mantle"` | |
| Osteosarcoma | `"osteosarcoma"` | |
| Ewing sarcoma | `"sarcoma"` | |
| Neuroblastoma | `"neuroblastoma"` | |
| Medulloblastoma | `"medulloblastoma"` | |
| Pancreatic ductal adenocarcinoma | `"pancreatic"` | TCGA code is PAAD |
| AML / Acute myeloid leukemia | `"leukemia"` | TCGA code is LAML |
| Glioblastoma | `"glioblastoma"` | TCGA code is GBM |

**Workflow for non-TCGA cancers:**

1. CancerPrognosis_search_studies(keyword="<disease>") → identify study_id (e.g. "msk_impact_2017") 2. CancerPrognosis_get_survival_data(cancer="<study_id>") → check if OS_MONTHS / DFS_MONTHS fields present 3. If no survival data: study is mutation-only (WES) — note limitation in report

---

## Fallback Chain Details

### Variant Interpretation

CIViC → COSMIC_get_mutations_by_gene → ClinVar → OncoKB (manual) → PubMed

### Somatic Mutation Analysis (NEW)

COSMIC_get_mutations_by_gene (somatic) → CIViC (clinical) → ClinVar (germline) → PubMed

### Prognosis / Survival

CancerPrognosis_get_survival_data (TCGA) → CancerPrognosis_search_studies → CancerPrognosis_get_gene_expression

### Drug Information

OpenTargets → ChEMBL → DailyMed → DrugBank

### Clinical Trials

ClinicalTrials.gov (primary) → WHO ICTRP → EudraCT

### Structure Prediction

AlphaFold DB (precomputed) → NvidiaNIM_alphafold2 → NvidiaNIM_esmfold

Treatment Algorithms & Evidence Grading

Evidence Grading

CIViC Evidence Level Mapping

OncoKB Level Mapping

---

Treatment Prioritization

---

Fallback Chains

---

Cancer Type Mappings

TCGA Project Codes

HPA Cancer Cell Lines

OncoTree Tumor Type Codes (common)

---

DepMap Interpretation Guide

• Effect score < -0.5 = strongly essential for cell survival
• Compare cancer-type-specific vs pan-cancer scores for selectivity
• Pan-essential genes (e.g., MYC) are challenging therapeutic targets
• Cancer-selective genes are better drug targets