@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/cart-design-optimizer-agent/SKILL.md

@@ -0,0 +1,162 @@
+<!--
+# COPYRIGHT NOTICE
+# This file is part of the "Universal Biomedical Skills" project.
+# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
+# All Rights Reserved.
+#
+# This code is proprietary and confidential.
+# Unauthorized copying of this file, via any medium is strictly prohibited.
+#
+# Provenance: Authenticated by MD BABU MIA
+
+-->
+
+---
+name: 'cart-design-optimizer-agent'
+description: 'AI-guided CAR-T cell design for solid tumors using antigen prioritization, safety-by-design architectures, and exhaustion-resistant engineering.'
+measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes.
+allowed-tools:
+  - read_file
+  - run_shell_command
+---
+
+
+# CAR-T Design Optimizer Agent
+
+The **CAR-T Design Optimizer Agent** provides end-to-end AI-guided design of chimeric antigen receptor T-cells. It integrates antigen prioritization, safety-constrained CAR architectures, exhaustion resistance engineering, and computational modeling of CAR-T kinetics for optimized therapeutic design.
+
+## When to Use This Skill
+
+* When designing CAR-T therapies for solid tumors with limited target antigens.
+* To optimize CAR construct sequences for reduced exhaustion and self-activation.
+* For selecting safety-by-design architectures (logic-gated, modular, armored).
+* When predicting CAR-T expansion, persistence, and efficacy.
+* To engineer exhaustion-resistant CAR-T cells via gene editing strategies.
+
+## Core Capabilities
+
+1. **Antigen Prioritization**: AI-driven ranking of target antigens based on tumor specificity, expression levels, and safety profiles.
+
+2. **CARMSeD Prediction**: Predictive model forecasting CAR constructs prone to tonic signaling, self-activation, and dysfunction.
+
+3. **Safety Architecture Design**: Logic-gated (synNotch), ON/OFF switches, armored designs for solid tumor safety.
+
+4. **Exhaustion Resistance**: CRISPR target selection (TOX, NR4A, PD-1 knockouts) and PD-1 locus integration strategies.
+
+5. **Pharmacokinetic Modeling**: Multi-population models predicting CAR-T expansion, distribution, and persistence.
+
+6. **LLM-Assisted Design**: Constrained large language model reasoning for evidence synthesis and design justification.
+
+## CAR Architecture Options
+
+| Architecture | Mechanism | Best For |
+|--------------|-----------|----------|
+| Standard 2nd Gen | CD28 or 4-1BB costimulation | Hematological malignancies |
+| Logic-Gated (AND) | Requires 2 antigens for activation | Solid tumors, safety |
+| synNotch Priming | TME signal triggers CAR expression | Local activation |
+| Armored CAR | Cytokine secretion (IL-15, IL-21) | Hostile TME |
+| Universal/SUPRA | Adaptable targeting via adaptor | Multi-antigen, flexibility |
+| PD-1 Knock-in | CAR in PD-1 locus | Exhaustion resistance |
+
+## Workflow
+
+1. **Antigen Selection**: Analyze tumor expression data to prioritize targets.
+
+2. **Safety Assessment**: Evaluate off-tumor expression in normal tissues.
+
+3. **CAR Design**: Generate construct sequences with selected domains.
+
+4. **CARMSeD Screening**: Predict self-activation and exhaustion propensity.
+
+5. **Architecture Selection**: Match patient/tumor to optimal CAR design.
+
+6. **Gene Editing Design**: Select CRISPR targets for enhanced function.
+
+7. **Output**: Optimized CAR sequence, predicted performance, manufacturing specs.
+
+## Example Usage
+
+**User**: "Design an optimized CAR-T construct targeting HER2 for breast cancer with minimized exhaustion."
+
+**Agent Action**:
+```bash
+python3 Skills/Immunology_Vaccines/CART_Design_Optimizer_Agent/cart_designer.py \
+    --target HER2 \
+    --tumor_type breast_cancer \
+    --expression_data tumor_rnaseq.tsv \
+    --normal_tissues gtex_expression.tsv \
+    --architecture synnotch_armored \
+    --exhaustion_engineering tox_knockout \
+    --model carmsed_v2 \
+    --output cart_design_report/
+```
+
+## CARMSeD Model Details
+
+**Prediction Targets**:
+- Tonic signaling propensity
+- Self-activation risk
+- Exhaustion trajectory
+- Proliferative capacity
+
+**Input Features**:
+- scFv binding affinity
+- Hinge/spacer length
+- Costimulatory domain
+- Transmembrane sequence
+- Expression system
+
+**Validated Performance**:
+- AUC > 0.85 for dysfunction prediction
+- In vitro to in vivo correlation
+
+## Anti-Exhaustion Engineering Strategies
+
+| Target | Method | Effect |
+|--------|--------|--------|
+| TOX | CRISPR KO | Prevents exhaustion program |
+| NR4A1-3 | Triple KO | Blocks exhaustion TFs |
+| PD-1 locus | CAR integration | TME-responsive expression |
+| c-Jun | Overexpression | Overcomes AP-1 imbalance |
+| DNMT3A | KO | Epigenetic reprogramming |
+
+## Computational Pharmacokinetics
+
+**Lotka-Volterra Model**:
+```
+dC/dt = r*C*(1 - C/K) - k*C*T  # CAR-T expansion
+dT/dt = -α*C*T                   # Tumor killing
+```
+
+**Multi-Population Extensions**:
+- Memory vs. effector subsets
+- Exhaustion state transitions
+- Cytokine-mediated effects
+- Checkpoint interactions
+
+## Prerequisites
+
+* Python 3.10+
+* PyTorch for ML models
+* CRISPRscan for guide design
+* Protein structure tools (optional)
+
+## Related Skills
+
+* TCell_Exhaustion_Analysis_Agent - For exhaustion profiling
+* Neoantigen_Vaccine_Agent - For antigen identification
+* CRISPR_Design_Agent - For gene editing optimization
+
+## Clinical Considerations
+
+1. **Cytokine Release Syndrome**: Risk assessment and mitigation designs
+2. **ICANS Neurotoxicity**: CNS penetration modeling
+3. **Manufacturing**: Transduction efficiency predictions
+4. **Persistence**: Memory phenotype engineering
+
+## Author
+
+AI Group - Biomedical AI Platform
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->

package/data/skills/cbioportal-database/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: cbioportal-database
+description: Query cBioPortal for cancer genomics data including somatic mutations, copy number alterations, gene expression, and survival data across hundreds of cancer studies. Essential for cancer target validation, oncogene/tumor suppressor analysis, and patient-level genomic profiling.
+license: LGPL-3.0
+metadata:
+    skill-author: Kuan-lin Huang
+---
+
+# cBioPortal Database
+
+## Overview
+
+cBioPortal for Cancer Genomics (https://www.cbioportal.org/) is an open-access resource for exploring, visualizing, and analyzing multidimensional cancer genomics data. It hosts data from The Cancer Genome Atlas (TCGA), AACR Project GENIE, MSK-IMPACT, and hundreds of other cancer studies — covering mutations, copy number alterations (CNA), structural variants, mRNA/protein expression, methylation, and clinical data for thousands of cancer samples.
+
+**Key resources:**
+- cBioPortal website: https://www.cbioportal.org/
+- REST API: https://www.cbioportal.org/api/
+- API docs (Swagger): https://www.cbioportal.org/api/swagger-ui/index.html
+- Python client: `bravado` or `requests`
+- GitHub: https://github.com/cBioPortal/cbioportal
+
+## When to Use This Skill
+
+Use cBioPortal when:
+
+- **Mutation landscape**: What fraction of a cancer type has mutations in a specific gene?
+- **Oncogene/TSG validation**: Is a gene frequently mutated, amplified, or deleted in cancer?
+- **Co-mutation patterns**: Are mutations in gene A and gene B mutually exclusive or co-occurring?
+- **Survival analysis**: Do mutations in a gene associate with better or worse patient outcomes?
+- **Alteration profiles**: What types of alterations (missense, truncating, amplification, deletion) affect a gene?
+- **Pan-cancer analysis**: Compare alteration frequencies across cancer types
+- **Clinical associations**: Link genomic alterations to clinical variables (stage, grade, treatment response)
+- **TCGA/GENIE exploration**: Systematic access to TCGA and clinical sequencing datasets
+
+## Core Capabilities
+
+### 1. cBioPortal REST API
+
+Base URL: `https://www.cbioportal.org/api`
+
+The API is RESTful, returns JSON, and requires no API key for public data.
+
+```python
+import requests
+
+BASE_URL = "https://www.cbioportal.org/api"
+HEADERS = {"Accept": "application/json", "Content-Type": "application/json"}
+
+def cbioportal_get(endpoint, params=None):
+    url = f"{BASE_URL}/{endpoint}"
+    response = requests.get(url, params=params, headers=HEADERS)
+    response.raise_for_status()
+    return response.json()
+
+def cbioportal_post(endpoint, body):
+    url = f"{BASE_URL}/{endpoint}"
+    response = requests.post(url, json=body, headers=HEADERS)
+    response.raise_for_status()
+    return response.json()
+```
+
+### 2. Browse Studies
+
+```python
+def get_all_studies():
+    """List all available cancer studies."""
+    return cbioportal_get("studies", {"pageSize": 500})
+
+# Each study has:
+# studyId: unique identifier (e.g., "brca_tcga")
+# name: human-readable name
+# description: dataset description
+# cancerTypeId: cancer type abbreviation
+# referenceGenome: GRCh37 or GRCh38
+# pmid: associated publication
+
+studies = get_all_studies()
+print(f"Total studies: {len(studies)}")
+
+# Common TCGA study IDs:
+# brca_tcga, luad_tcga, coadread_tcga, gbm_tcga, prad_tcga,
+# skcm_tcga, blca_tcga, hnsc_tcga, lihc_tcga, stad_tcga
+
+# Filter for TCGA studies
+tcga_studies = [s for s in studies if "tcga" in s["studyId"]]
+print([s["studyId"] for s in tcga_studies[:10]])
+```
+
+### 3. Molecular Profiles
+
+Each study has multiple molecular profiles (mutation, CNA, expression, etc.):
+
+```python
+def get_molecular_profiles(study_id):
+    """Get all molecular profiles for a study."""
+    return cbioportal_get(f"studies/{study_id}/molecular-profiles")
+
+profiles = get_molecular_profiles("brca_tcga")
+for p in profiles:
+    print(f"  {p['molecularProfileId']}: {p['name']} ({p['molecularAlterationType']})")
+
+# Alteration types:
+# MUTATION_EXTENDED — somatic mutations
+# COPY_NUMBER_ALTERATION — CNA (GISTIC)
+# MRNA_EXPRESSION — mRNA expression
+# PROTEIN_LEVEL — RPPA protein expression
+# STRUCTURAL_VARIANT — fusions/rearrangements
+```
+
+### 4. Mutation Data
+
+```python
+def get_mutations(molecular_profile_id, entrez_gene_ids, sample_list_id=None):
+    """Get mutations for specified genes in a molecular profile."""
+    body = {
+        "entrezGeneIds": entrez_gene_ids,
+        "sampleListId": sample_list_id or molecular_profile_id.replace("_mutations", "_all")
+    }
+    return cbioportal_post(
+        f"molecular-profiles/{molecular_profile_id}/mutations/fetch",
+        body
+    )
+
+# BRCA1 Entrez ID is 672, TP53 is 7157, PTEN is 5728
+mutations = get_mutations("brca_tcga_mutations", entrez_gene_ids=[7157])  # TP53
+
+# Each mutation record contains:
+# patientId, sampleId, entrezGeneId, gene.hugoGeneSymbol
+# mutationType (Missense_Mutation, Nonsense_Mutation, Frame_Shift_Del, etc.)
+# proteinChange (e.g., "R175H")
+# variantClassification, variantType
+# ncbiBuild, chr, startPosition, endPosition, referenceAllele, variantAllele
+# mutationStatus (Somatic/Germline)
+# alleleFreqT (tumor VAF)
+
+import pandas as pd
+df = pd.DataFrame(mutations)
+print(df[["patientId", "mutationType", "proteinChange", "alleleFreqT"]].head())
+print(f"\nMutation types:\n{df['mutationType'].value_counts()}")
+```
+
+### 5. Copy Number Alteration Data
+
+```python
+def get_cna(molecular_profile_id, entrez_gene_ids):
+    """Get discrete CNA data (GISTIC: -2, -1, 0, 1, 2)."""
+    body = {
+        "entrezGeneIds": entrez_gene_ids,
+        "sampleListId": molecular_profile_id.replace("_gistic", "_all").replace("_cna", "_all")
+    }
+    return cbioportal_post(
+        f"molecular-profiles/{molecular_profile_id}/discrete-copy-number/fetch",
+        body
+    )
+
+# GISTIC values:
+# -2 = Deep deletion (homozygous loss)
+# -1 = Shallow deletion (heterozygous loss)
+#  0 = Diploid (neutral)
+#  1 = Low-level gain
+#  2 = High-level amplification
+
+cna_data = get_cna("brca_tcga_gistic", entrez_gene_ids=[1956])  # EGFR
+df_cna = pd.DataFrame(cna_data)
+print(df_cna["value"].value_counts())
+```
+
+### 6. Alteration Frequency (OncoPrint-style)
+
+```python
+def get_alteration_frequency(study_id, gene_symbols, alteration_types=None):
+    """Compute alteration frequencies for genes across a cancer study."""
+    import requests, pandas as pd
+
+    # Get sample list
+    samples = requests.get(
+        f"{BASE_URL}/studies/{study_id}/sample-lists",
+        headers=HEADERS
+    ).json()
+    all_samples_id = next(
+        (s["sampleListId"] for s in samples if s["category"] == "all_cases_in_study"), None
+    )
+    total_samples = len(requests.get(
+        f"{BASE_URL}/sample-lists/{all_samples_id}/sample-ids",
+        headers=HEADERS
+    ).json())
+
+    # Get gene Entrez IDs
+    gene_data = requests.post(
+        f"{BASE_URL}/genes/fetch",
+        json=[{"hugoGeneSymbol": g} for g in gene_symbols],
+        headers=HEADERS
+    ).json()
+    entrez_ids = [g["entrezGeneId"] for g in gene_data]
+
+    # Get mutations
+    mutation_profile = f"{study_id}_mutations"
+    mutations = get_mutations(mutation_profile, entrez_ids, all_samples_id)
+
+    freq = {}
+    for g_symbol, e_id in zip(gene_symbols, entrez_ids):
+        mutated = len(set(m["patientId"] for m in mutations if m["entrezGeneId"] == e_id))
+        freq[g_symbol] = mutated / total_samples * 100
+
+    return freq
+
+# Example
+freq = get_alteration_frequency("brca_tcga", ["TP53", "PIK3CA", "BRCA1", "BRCA2"])
+for gene, pct in sorted(freq.items(), key=lambda x: -x[1]):
+    print(f"  {gene}: {pct:.1f}%")
+```
+
+### 7. Clinical Data
+
+```python
+def get_clinical_data(study_id, attribute_ids=None):
+    """Get patient-level clinical data."""
+    params = {"studyId": study_id}
+    all_clinical = cbioportal_get(
+        "clinical-data/fetch",
+        params
+    )
+    # Returns list of {patientId, studyId, clinicalAttributeId, value}
+
+# Clinical attributes include:
+# OS_STATUS, OS_MONTHS, DFS_STATUS, DFS_MONTHS (survival)
+# TUMOR_STAGE, GRADE, AGE, SEX, RACE
+# Study-specific attributes vary
+
+def get_clinical_attributes(study_id):
+    """List all available clinical attributes for a study."""
+    return cbioportal_get(f"studies/{study_id}/clinical-attributes")
+```
+
+## Query Workflows
+
+### Workflow 1: Gene Alteration Profile in a Cancer Type
+
+```python
+import requests, pandas as pd
+
+def alteration_profile(study_id, gene_symbol):
+    """Full alteration profile for a gene in a cancer study."""
+
+    # 1. Get gene Entrez ID
+    gene_info = requests.post(
+        f"{BASE_URL}/genes/fetch",
+        json=[{"hugoGeneSymbol": gene_symbol}],
+        headers=HEADERS
+    ).json()[0]
+    entrez_id = gene_info["entrezGeneId"]
+
+    # 2. Get mutations
+    mutations = get_mutations(f"{study_id}_mutations", [entrez_id])
+    mut_df = pd.DataFrame(mutations) if mutations else pd.DataFrame()
+
+    # 3. Get CNAs
+    cna = get_cna(f"{study_id}_gistic", [entrez_id])
+    cna_df = pd.DataFrame(cna) if cna else pd.DataFrame()
+
+    # 4. Summary
+    n_mut = len(set(mut_df["patientId"])) if not mut_df.empty else 0
+    n_amp = len(cna_df[cna_df["value"] == 2]) if not cna_df.empty else 0
+    n_del = len(cna_df[cna_df["value"] == -2]) if not cna_df.empty else 0
+
+    return {"mutations": n_mut, "amplifications": n_amp, "deep_deletions": n_del}
+
+result = alteration_profile("brca_tcga", "PIK3CA")
+print(result)
+```
+
+### Workflow 2: Pan-Cancer Gene Mutation Frequency
+
+```python
+import requests, pandas as pd
+
+def pan_cancer_mutation_freq(gene_symbol, cancer_study_ids=None):
+    """Mutation frequency of a gene across multiple cancer types."""
+    studies = get_all_studies()
+    if cancer_study_ids:
+        studies = [s for s in studies if s["studyId"] in cancer_study_ids]
+
+    results = []
+    for study in studies[:20]:  # Limit for demo
+        try:
+            freq = get_alteration_frequency(study["studyId"], [gene_symbol])
+            results.append({
+                "study": study["studyId"],
+                "cancer": study.get("cancerTypeId", ""),
+                "mutation_pct": freq.get(gene_symbol, 0)
+            })
+        except Exception:
+            pass
+
+    df = pd.DataFrame(results).sort_values("mutation_pct", ascending=False)
+    return df
+```
+
+### Workflow 3: Survival Analysis by Mutation Status
+
+```python
+import requests, pandas as pd
+
+def survival_by_mutation(study_id, gene_symbol):
+    """Get survival data split by mutation status."""
+    # This workflow fetches clinical and mutation data for downstream analysis
+
+    gene_info = requests.post(
+        f"{BASE_URL}/genes/fetch",
+        json=[{"hugoGeneSymbol": gene_symbol}],
+        headers=HEADERS
+    ).json()[0]
+    entrez_id = gene_info["entrezGeneId"]
+
+    mutations = get_mutations(f"{study_id}_mutations", [entrez_id])
+    mutated_patients = set(m["patientId"] for m in mutations)
+
+    clinical = cbioportal_get("clinical-data/fetch", {"studyId": study_id})
+    clinical_df = pd.DataFrame(clinical)
+
+    os_data = clinical_df[clinical_df["clinicalAttributeId"].isin(["OS_MONTHS", "OS_STATUS"])]
+    os_wide = os_data.pivot(index="patientId", columns="clinicalAttributeId", values="value")
+    os_wide["mutated"] = os_wide.index.isin(mutated_patients)
+
+    return os_wide
+```
+
+## Key API Endpoints Summary
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /studies` | List all studies |
+| `GET /studies/{studyId}/molecular-profiles` | Molecular profiles for a study |
+| `POST /molecular-profiles/{profileId}/mutations/fetch` | Get mutation data |
+| `POST /molecular-profiles/{profileId}/discrete-copy-number/fetch` | Get CNA data |
+| `POST /molecular-profiles/{profileId}/molecular-data/fetch` | Get expression data |
+| `GET /studies/{studyId}/clinical-attributes` | Available clinical variables |
+| `GET /clinical-data/fetch` | Clinical data |
+| `POST /genes/fetch` | Gene metadata by symbol or Entrez ID |
+| `GET /studies/{studyId}/sample-lists` | Sample lists |
+
+## Best Practices
+
+- **Know your study IDs**: Use the Swagger UI or `GET /studies` to find the correct study ID
+- **Use sample lists**: Each study has an `all` sample list and subsets; always specify the appropriate one
+- **TCGA vs. GENIE**: TCGA data is comprehensive but older; GENIE has more recent clinical sequencing data
+- **Entrez gene IDs**: The API uses Entrez IDs — use `/genes/fetch` to convert from symbols
+- **Handle 404s**: Some molecular profiles may not exist for all studies
+- **Rate limiting**: Add delays for bulk queries; consider downloading data files for large-scale analyses
+
+## Data Downloads
+
+For large-scale analyses, download study data directly:
+```bash
+# Download TCGA BRCA data
+wget https://cbioportal-datahub.s3.amazonaws.com/brca_tcga.tar.gz
+```
+
+## Additional Resources
+
+- **cBioPortal website**: https://www.cbioportal.org/
+- **API Swagger UI**: https://www.cbioportal.org/api/swagger-ui/index.html
+- **Documentation**: https://docs.cbioportal.org/
+- **GitHub**: https://github.com/cBioPortal/cbioportal
+- **Data hub**: https://datahub.cbioportal.org/
+- **Citation**: Cerami E et al. (2012) Cancer Discovery. PMID: 22588877
+- **API clients**: https://docs.cbioportal.org/web-api-and-clients/