User Input (gene list OR cancer type OR single gene)
│
├─ PATH 0: Input Processing & Validation
│   ├─ Validate gene symbols
│   ├─ Determine analysis mode
│   └─ Set context parameters
│
├─ PATH 1: Gene Essentiality Analysis (DepMap)
│   ├─ Query gene dependencies for each hit
│   ├─ Retrieve essentiality scores across cell lines
│   ├─ Calculate pan-cancer vs selective essentiality
│   └─ Rank genes by dependency strength
│
├─ PATH 2: Pathway & Functional Enrichment
│   ├─ GO enrichment (biological process, molecular function)
│   ├─ Pathway enrichment (Reactome, WikiPathways, KEGG)
│   ├─ Hallmark gene set enrichment (MSigDB)
│   └─ Identify pathway-level vulnerabilities
│
├─ PATH 3: Protein-Protein Interaction Networks
│   ├─ Build PPI network for hit genes
│   ├─ Identify protein complexes
│   ├─ Find synthetic lethal candidates
│   └─ Hub gene analysis
│
├─ PATH 4: Druggability & Target Assessment
│   ├─ Check existing drugs (DGIdb, ChEMBL)
│   ├─ Assess chemical tractability (Pharos TDL)
│   ├─ Find chemical probes (Open Targets)
│   └─ Clinical trial status (ClinicalTrials.gov)
│
├─ PATH 5: Disease Association & Clinical Relevance
│   ├─ Gene-disease associations (Open Targets)
│   ├─ Somatic mutations in cancer (COSMIC, cBioPortal)
│   ├─ Expression in patient samples (GTEx, TCGA)
│   └─ Prognostic/predictive biomarker status
│
└─ PATH 6: Hit Prioritization & Validation Guidance
    ├─ Integrate all evidence dimensions
    ├─ Calculate priority score (essentiality + druggability + clinical relevance)
    ├─ Recommend validation experiments
    └─ Identify top 5-10 targets for follow-up

def determine_analysis_mode(user_input):
    """
    Figure out what type of analysis to run.

    Returns: 'gene_list', 'cancer_type', or 'single_gene'
    """
    if isinstance(user_input, list) and len(user_input) >= 5:
        return 'gene_list'  # User provided hits from their screen
    elif isinstance(user_input, str) and len(user_input.split()) > 1:
        return 'cancer_type'  # User asks about a cancer type
    else:
        return 'single_gene'  # Single gene target validation

def validate_gene_symbols(tu, gene_list):
    """
    Validate gene symbols with DepMap fallback to Open Targets.

    Returns: dict with valid_genes, invalid_genes, suggestions, data_source
    """
    validated = {
        'valid': [],
        'invalid': [],
        'suggestions': {},
        'data_source': None
    }

    # Try DepMap first
    depmap_available = False
    test_result = tu.tools.DepMap_search_genes(query="KRAS")
    if (test_result.get('status') == 'success' and
        not test_result.get('error', '').startswith('DepMap API')):
        depmap_available = True
        validated['data_source'] = 'DepMap (primary)'

    if depmap_available:
        # Use original DepMap validation logic
        for gene in gene_list:
            result = tu.tools.DepMap_search_genes(query=gene)
            if result.get('status') == 'success':
                genes = result.get('data', {}).get('genes', [])
                exact_matches = [g for g in genes
                               if g.get('symbol', '').upper() == gene.upper()]

                if exact_matches:
                    validated['valid'].append({
                        'input': gene,
                        'symbol': exact_matches[0]['symbol'],
                        'ensembl_id': exact_matches[0].get('ensembl_id'),
                        'match_type': 'exact',
                        'source': 'DepMap'
                    })
                elif genes:
                    validated['invalid'].append(gene)
                    validated['suggestions'][gene] = [g['symbol'] for g in genes[:3]]
                else:
                    validated['invalid'].append(gene)
    else:
        # FALLBACK: Use Pharos (druggability database)
        print("⚠️  DepMap unavailable, using Pharos for gene validation...")
        validated['data_source'] = 'Pharos (fallback - ★★☆)'

        for gene in gene_list:
            # Query Pharos to check if gene exists
            result = tu.tools.Pharos_get_target(gene=gene)

            if result.get('status') == 'success' and result.get('data'):
                target_data = result.get('data', {})
                validated['valid'].append({
                    'input': gene,
                    'symbol': target_data.get('name', gene),
                    'tdl': target_data.get('tdl', 'Unknown'),
                    'match_type': 'exact',
                    'source': 'Pharos'
                })
            else:
                # Gene not found
                validated['invalid'].append(gene)

    return validated

undefined

---

def analyze_gene_essentiality(tu, gene_list, cancer_type=None):
    """
    Get gene essentiality data with DepMap fallback to Open Targets.

    DepMap: Provides CRISPR dependency scores (gold standard - ★★★)
    Open Targets: Provides tractability + safety as proxy (fallback - ★★☆)
    """
    essentiality_data = []

    # Check if DepMap is available
    test_result = tu.tools.DepMap_get_gene_dependencies(gene_symbol="KRAS")
    depmap_available = (
        test_result.get('status') == 'success' and
        not test_result.get('error', '').startswith('DepMap API')
    )

    if depmap_available:
        # Use original DepMap logic (optimal - ★★★)
        for gene in gene_list:
            dep_result = tu.tools.DepMap_get_gene_dependencies(gene_symbol=gene)
            if dep_result.get('status') == 'success':
                gene_data = dep_result.get('data', {})
                essentiality_data.append({
                    'gene': gene,
                    'data': gene_data,
                    'essentiality_class': classify_essentiality_depmap(gene_data),
                    'source': 'DepMap',
                    'confidence': 'HIGH'  # ★★★
                })
    else:
        # FALLBACK: Use Pharos TDL classification as proxy
        print("⚠️  DepMap unavailable, using Pharos TDL as essentiality proxy...")

        for gene in gene_list:
            pharos_result = tu.tools.Pharos_get_target(gene=gene)

            if pharos_result.get('status') == 'success' and pharos_result.get('data'):
                target_data = pharos_result.get('data', {})

                # Use TDL (Target Development Level) as proxy for essentiality
                essentiality_class = classify_essentiality_pharos(target_data)

                essentiality_data.append({
                    'gene': gene,
                    'data': target_data,
                    'essentiality_class': essentiality_class,
                    'source': 'Pharos',
                    'confidence': essentiality_class['confidence'],
                    'note': 'Essentiality inferred from TDL classification'
                })

    return essentiality_data


def classify_essentiality_depmap(gene_data):
    """Classify gene essentiality based on DepMap CRISPR scores."""
    # Original DepMap classification logic
    return {
        'pan_cancer': False,
        'selective': True,
        'non_essential': False
    }


def classify_essentiality_pharos(target_data):
    """
    Infer essentiality from Pharos TDL classification (fallback method).

    TDL (Target Development Level) categories:
    - Tclin: Clinical drug target (approved drugs) → Likely essential/important
    - Tchem: Chemical tool/probe available → Druggable, possibly essential
    - Tbio: Biological evidence → Some relevance
    - Tdark: No drug/tool → Unknown essentiality
    """
    tdl = target_data.get('tdl', 'Unknown')

    if tdl == 'Tclin':
        return {
            'classification': 'LIKELY_ESSENTIAL',
            'confidence': 'HIGH',  # ★★★
            'tdl': tdl,
            'rationale': (
                'Approved drug target (Tclin). '
                'Clinically validated targets are often essential. '
                'For cell-line-specific scores, await DepMap restoration.'
            )
        }
    elif tdl == 'Tchem':
        return {
            'classification': 'POTENTIALLY_ESSENTIAL',
            'confidence': 'MEDIUM',  # ★★☆
            'tdl': tdl,
            'rationale': (
                'Chemical tools available (Tchem). '
                'Druggable targets with chemical probes often have functional relevance.'
            )
        }
    elif tdl == 'Tbio':
        return {
            'classification': 'UNCERTAIN',
            'confidence': 'LOW',  # ★☆☆
            'tdl': tdl,
            'rationale': (
                'Biological evidence only (Tbio). '
                'Limited druggability data. Essentiality unclear.'
            )
        }
    else:  # Tdark or Unknown
        return {
            'classification': 'UNKNOWN',
            'confidence': 'LOW',  # ★☆☆
            'tdl': tdl,
            'rationale': (
                'Dark target or unknown. '
                'No drug/tool data. Essentiality cannot be inferred.'
            )
        }

def get_top_essential_genes_for_cancer(tu, cancer_type, top_n=50):
    """
    Retrieve top essential genes for a specific cancer type from DepMap.
    """
    # Get cell lines for this cancer type
    cell_lines = tu.tools.DepMap_get_cell_lines(
        cancer_type=cancer_type,
        page_size=100
    )

    if not cell_lines.get('data', {}).get('cell_lines'):
        return {'error': f'No cell lines found for {cancer_type}'}

    # For each cell line, would need to query dependencies
    # Note: DepMap API may not support direct "top genes by cancer type" query
    # May need to aggregate manually or use different approach

    return {
        'cancer_type': cancer_type,
        'cell_lines': cell_lines.get('data', {}).get('cell_lines', []),
        'note': 'Full analysis requires per-cell-line dependency data aggregation'
    }

undefined

**Output for Report (when using Pharos fallback)**:
```markdown

---

def perform_pathway_enrichment(tu, gene_list):
    """
    Run enrichment analysis across multiple libraries.
    """
    # Enrichr libraries to query
    libraries = [
        "WikiPathways_2024_Human",
        "Reactome_Pathways_2024",
        "MSigDB_Hallmark_2020",
        "GO_Biological_Process_2023",
        "GO_Molecular_Function_2023",
        "GO_Cellular_Component_2023",
        "KEGG_2024_Human"
    ]

    result = tu.tools.enrichr_gene_enrichment_analysis(
        gene_list=gene_list,
        libs=libraries
    )

    # Parse results - Enrichr returns pathway rankings with p-values
    return result

undefined

---

def build_ppi_network(tu, gene_list):
    """
    Construct protein interaction network for hit genes.
    """
    # Use STRING for comprehensive PPI data
    ppi_result = tu.tools.STRING_get_protein_interactions(
        protein_ids=gene_list,
        species=9606  # Human
    )

    # Also check IntAct for curated interactions
    interactions = []
    for gene in gene_list:
        # Get UniProt ID first
        uniprot = resolve_gene_to_uniprot(tu, gene)
        if uniprot:
            intact_result = tu.tools.intact_get_interactions(identifier=uniprot)
            interactions.append(intact_result)

    return {
        'string': ppi_result,
        'intact': interactions
    }

def identify_protein_complexes(ppi_data):
    """
    Identify protein complexes from PPI network.

    Could use complex detection algorithms or query Complex Portal.
    """
    # Implementation for complex detection
    pass

undefined

---

def assess_druggability(tu, gene_list):
    """
    Evaluate druggability of hit genes.
    """
    drug_targets = []

    for gene in gene_list:
        # Check Pharos for target development level
        pharos = tu.tools.Pharos_get_target(gene=gene)

        # Check DGIdb for existing drugs
        dgidb = tu.tools.DGIdb_get_drug_gene_interactions(genes=[gene])

        # Check Open Targets for chemical probes
        ensembl_id = resolve_gene_to_ensembl(tu, gene)
        if ensembl_id:
            probes = tu.tools.OpenTargets_get_chemical_probes_by_target_ensemblId(
                ensemblId=ensembl_id
            )

        # Check clinical trials
        trials = tu.tools.search_clinical_trials(
            intervention=gene,
            pageSize=20
        )

        drug_targets.append({
            'gene': gene,
            'pharos_tdl': pharos.get('data', {}).get('tdl'),
            'existing_drugs': dgidb,
            'chemical_probes': probes,
            'clinical_trials': trials
        })

    return drug_targets

undefined

---

def assess_clinical_relevance(tu, gene_list, cancer_type):
    """
    Evaluate clinical relevance of hits in target cancer type.
    """
    clinical_data = []

    for gene in gene_list:
        ensembl_id = resolve_gene_to_ensembl(tu, gene)

        if ensembl_id:
            # Disease associations
            diseases = tu.tools.OpenTargets_get_diseases_phenotypes_by_target_ensemblId(
                ensemblId=ensembl_id
            )

            # Mouse models
            mouse = tu.tools.OpenTargets_get_biological_mouse_models_by_ensemblId(
                ensemblId=ensembl_id
            )

        # COSMIC mutations (somatic alterations in cancer)
        cosmic = tu.tools.COSMIC_get_gene_mutations(gene=gene)

        # GTEx expression (is it expressed in relevant tissue?)
        gtex = tu.tools.GTEx_get_median_gene_expression(
            gencode_id=ensembl_id,
            operation="median"
        )

        clinical_data.append({
            'gene': gene,
            'diseases': diseases,
            'mutations': cosmic,
            'expression': gtex,
            'mouse_models': mouse
        })

    return clinical_data

undefined

---

def calculate_priority_score(gene_data):
    """
    Calculate multi-dimensional priority score.

    Components:
    - Essentiality strength (DepMap score)
    - Selectivity (tissue-specific vs pan-cancer)
    - Druggability (Pharos TDL, existing compounds)
    - Clinical relevance (mutations, expression, biomarkers)
    - Validation feasibility (tool compounds available)

    Returns score 0-100
    """
    score = 0

    # Essentiality (0-30 points)
    if gene_data['depmap_score'] < -1.0:
        score += 30
    elif gene_data['depmap_score'] < -0.5:
        score += 20
    else:
        score += 10

    # Selectivity (0-25 points)
    if gene_data['selective']:  # Tissue-specific
        score += 25
    elif gene_data['pan_cancer']:  # Pan-cancer (deprioritize)
        score += 5

    # Druggability (0-25 points)
    if gene_data['pharos_tdl'] == 'Tclin':
        score += 25
    elif gene_data['pharos_tdl'] == 'Tchem':
        score += 20
    elif gene_data['pharos_tdl'] == 'Tbio':
        score += 10
    else:
        score += 5

    # Clinical relevance (0-20 points)
    if gene_data['mutation_frequency'] > 20:
        score += 10
    if gene_data['biomarker_status']:
        score += 10

    return score

undefined

---