@wentorai/research-plugins 1.3.2 → 1.4.0

package/skills/domains/biomedical/alphafold-api/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: alphafold-api
+description: "Query AlphaFold protein structure predictions by UniProt accession"
+metadata:
+  openclaw:
+    emoji: "🧬"
+    category: "domains"
+    subcategory: "biomedical"
+    keywords: ["protein structure", "AlphaFold", "structure prediction", "UniProt", "pLDDT", "bioinformatics"]
+    source: "https://alphafold.ebi.ac.uk"
+---
+
+# AlphaFold Protein Structure Database API
+
+## Overview
+
+The AlphaFold DB, maintained by EMBL-EBI and DeepMind, provides open access to over 200 million protein structure predictions. The REST API enables programmatic lookup of predicted structures, confidence metrics (pLDDT, PAE), and downloadable structure files (PDB, mmCIF, BinaryCIF) keyed on UniProt accessions. Free, no authentication required.
+
+## Authentication
+
+None. All endpoints are publicly accessible without API keys or tokens.
+
+## Core Endpoints
+
+Base URL: `https://alphafold.ebi.ac.uk/api`
+
+### 1. Get Prediction by UniProt Accession
+
+Retrieves all AlphaFold models for a given UniProt accession or model ID.
+
+```bash
+curl "https://alphafold.ebi.ac.uk/api/prediction/P04637"
+```
+
+**Response** (first entry, abbreviated):
+
+```json
+[
+  {
+    "entryId": "AF-P04637-F1",
+    "uniprotAccession": "P04637",
+    "uniprotId": "P53_HUMAN",
+    "uniprotDescription": "Cellular tumor antigen p53",
+    "gene": "TP53",
+    "organismScientificName": "Homo sapiens",
+    "taxId": 9606,
+    "globalMetricValue": 75.06,
+    "fractionPlddtVeryHigh": 0.527,
+    "fractionPlddtConfident": 0.071,
+    "fractionPlddtLow": 0.104,
+    "fractionPlddtVeryLow": 0.298,
+    "latestVersion": 6,
+    "modelCreatedDate": "2025-08-01T00:00:00Z",
+    "sequenceStart": 1,
+    "sequenceEnd": 393,
+    "pdbUrl": "https://alphafold.ebi.ac.uk/files/AF-P04637-F1-model_v6.pdb",
+    "cifUrl": "https://alphafold.ebi.ac.uk/files/AF-P04637-F1-model_v6.cif",
+    "bcifUrl": "https://alphafold.ebi.ac.uk/files/AF-P04637-F1-model_v6.bcif",
+    "paeImageUrl": "https://alphafold.ebi.ac.uk/files/AF-P04637-F1-predicted_aligned_error_v6.png",
+    "paeDocUrl": "https://alphafold.ebi.ac.uk/files/AF-P04637-F1-predicted_aligned_error_v6.json",
+    "plddtDocUrl": "https://alphafold.ebi.ac.uk/files/AF-P04637-F1-confidence_v6.json",
+    "amAnnotationsUrl": "https://alphafold.ebi.ac.uk/files/AF-P04637-F1-aa-substitutions.csv"
+  }
+]
+```
+
+### 2. Per-Residue Confidence Scores (pLDDT)
+
+Download the per-residue pLDDT confidence JSON linked in `plddtDocUrl`:
+
+```bash
+curl "https://alphafold.ebi.ac.uk/files/AF-P04637-F1-confidence_v6.json"
+```
+
+**Response** (truncated):
+
+```json
+{
+  "residueNumber": [1, 2, 3, 4, 5],
+  "confidenceScore": [40.66, 44.53, 49.97, 48.59, 44.88],
+  "confidenceCategory": ["D", "D", "D", "D", "D"]
+}
+```
+
+Categories: **A** (Very High, >90), **B** (Confident, 70-90), **C** (Low, 50-70), **D** (Very Low, <50).
+
+### 3. UniProt Summary (3D-Beacons Format)
+
+Returns model metadata following the 3D-Beacons data standard:
+
+```bash
+curl "https://alphafold.ebi.ac.uk/api/uniprot/summary/P04637.json"
+```
+
+**Response** (abbreviated):
+
+```json
+{
+  "uniprot_entry": {
+    "ac": "P04637",
+    "id": "P53_HUMAN",
+    "sequence_length": 393
+  },
+  "structures": [
+    {
+      "summary": {
+        "model_identifier": "AF-P04637-F1",
+        "model_url": "https://alphafold.ebi.ac.uk/files/AF-P04637-F1-model_v6.cif",
+        "provider": "AlphaFold DB",
+        "confidence_type": "pLDDT",
+        "confidence_avg_local_score": 75.06,
+        "coverage": 1.0
+      }
+    }
+  ]
+}
+```
+
+### 4. Download Structure Files
+
+Structure files are available at the URLs returned in prediction responses:
+
+```bash
+# PDB format
+curl -O "https://alphafold.ebi.ac.uk/files/AF-P04637-F1-model_v6.pdb"
+
+# mmCIF format
+curl -O "https://alphafold.ebi.ac.uk/files/AF-P04637-F1-model_v6.cif"
+
+# Predicted Aligned Error (PAE) matrix
+curl -O "https://alphafold.ebi.ac.uk/files/AF-P04637-F1-predicted_aligned_error_v6.json"
+```
+
+## Key Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `entryId` | string | AlphaFold model ID (e.g., `AF-P04637-F1`) |
+| `uniprotAccession` | string | UniProt accession code |
+| `gene` | string | Gene symbol |
+| `globalMetricValue` | float | Average pLDDT score (0-100) |
+| `fractionPlddtVeryHigh` | float | Fraction of residues with pLDDT > 90 |
+| `fractionPlddtConfident` | float | Fraction with pLDDT 70-90 |
+| `fractionPlddtLow` | float | Fraction with pLDDT 50-70 |
+| `fractionPlddtVeryLow` | float | Fraction with pLDDT < 50 |
+| `pdbUrl` | string | Direct download URL for PDB file |
+| `cifUrl` | string | Direct download URL for mmCIF file |
+| `paeDocUrl` | string | URL for predicted aligned error JSON |
+| `plddtDocUrl` | string | URL for per-residue confidence JSON |
+| `latestVersion` | int | Model version number |
+
+## Rate Limits
+
+The AlphaFold DB API has no published per-request rate limits. EMBL-EBI's general fair use policy applies: usage that degrades service for others may result in blocking. For bulk downloads (entire proteomes), use the FTP archive at `https://ftp.ebi.ac.uk/pub/databases/alphafold/` rather than repeated API calls.
+
+## Python Example
+
+```python
+import requests
+
+
+def get_alphafold_prediction(uniprot_id: str) -> dict:
+    """Fetch AlphaFold structure prediction for a UniProt accession."""
+    url = f"https://alphafold.ebi.ac.uk/api/prediction/{uniprot_id}"
+    resp = requests.get(url)
+    resp.raise_for_status()
+    entries = resp.json()
+    # Return the canonical (first) entry
+    return entries[0] if entries else None
+
+
+def get_confidence_scores(prediction: dict) -> dict:
+    """Download per-residue pLDDT confidence scores."""
+    resp = requests.get(prediction["plddtDocUrl"])
+    resp.raise_for_status()
+    return resp.json()
+
+
+def download_structure(prediction: dict, fmt: str = "pdb",
+                       output_dir: str = ".") -> str:
+    """Download structure file in pdb, cif, or bcif format."""
+    url_key = {"pdb": "pdbUrl", "cif": "cifUrl", "bcif": "bcifUrl"}[fmt]
+    url = prediction[url_key]
+    filename = url.split("/")[-1]
+    path = f"{output_dir}/{filename}"
+
+    resp = requests.get(url)
+    resp.raise_for_status()
+    with open(path, "wb") as f:
+        f.write(resp.content)
+    return path
+
+
+# Example: fetch p53 structure and assess quality
+pred = get_alphafold_prediction("P04637")
+print(f"Gene: {pred['gene']} ({pred['uniprotDescription']})")
+print(f"Organism: {pred['organismScientificName']}")
+print(f"Average pLDDT: {pred['globalMetricValue']}")
+print(f"Very high confidence: {pred['fractionPlddtVeryHigh']:.1%}")
+
+# Download per-residue scores
+scores = get_confidence_scores(pred)
+high_conf = [i+1 for i, c in enumerate(scores["confidenceCategory"])
+             if c in ("A", "B")]
+print(f"High-confidence residues: {len(high_conf)}/{len(scores['residueNumber'])}")
+
+# Download PDB file
+path = download_structure(pred, fmt="pdb")
+print(f"Structure saved to: {path}")
+```
+
+## Academic Use Cases
+
+- **Drug target assessment**: Check pLDDT scores in binding pockets before docking
+- **Homology model comparison**: Compare AlphaFold predictions with experimental PDB structures
+- **Disorder prediction**: Low pLDDT regions (<50) correlate with intrinsically disordered regions
+- **Variant interpretation**: Use AlphaMissense annotations (via `amAnnotationsUrl`) to assess pathogenicity
+- **Structural coverage**: Quickly check if a protein of interest has a predicted structure
+- **Batch proteome analysis**: Retrieve predictions for all proteins in a reference proteome
+
+## References
+
+- [AlphaFold Protein Structure Database](https://alphafold.ebi.ac.uk/)
+- [AlphaFold DB API Documentation](https://alphafold.ebi.ac.uk/api/openapi.json)
+- [AlphaFold DB FTP (Bulk Downloads)](https://ftp.ebi.ac.uk/pub/databases/alphafold/)
+- Jumper, J. et al. (2021). "Highly accurate protein structure prediction with AlphaFold." *Nature* 596, 583-589.
+- Varadi, M. et al. (2022). "AlphaFold Protein Structure Database: massively expanding the structural coverage of protein-sequence space with high-accuracy models." *Nucleic Acids Research* 50(D1).

package/skills/domains/biomedical/biothings-api/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: biothings-api
+description: "Query gene, variant, and drug annotations via BioThings APIs"
+metadata:
+  openclaw:
+    emoji: "🧪"
+    category: "domains"
+    subcategory: "biomedical"
+    keywords: ["gene annotation", "variant annotation", "drug data", "BioThings", "mygene", "myvariant", "bioinformatics"]
+    source: "https://biothings.io"
+---
+
+# BioThings API Suite
+
+## Overview
+
+BioThings is a family of high-performance biomedical annotation APIs developed at the Scripps Research Institute. The suite provides unified, up-to-date access to gene, variant, and chemical/drug annotations aggregated from dozens of authoritative sources. Three primary services cover the core entities in translational research:
+
+- **MyGene.info** — Gene annotations from NCBI Entrez, Ensembl, UniProt, GO, KEGG, Reactome, and 20+ sources.
+- **MyVariant.info** — Variant annotations from dbSNP, ClinVar, gnomAD, CADD, COSMIC, and 15+ sources.
+- **MyChem.info** — Drug and chemical annotations from NDC, DrugBank, ChEMBL, FDA, PubChem, and 10+ sources.
+
+All three share identical query syntax, require no authentication, and return JSON. Free for academic and commercial use.
+
+## Authentication
+
+No authentication or API keys are required. All endpoints are open-access.
+
+```bash
+# No API key needed — just query directly
+curl "https://mygene.info/v3/query?q=BRCA1&size=1"
+```
+
+## MyGene.info — Gene Annotations
+
+### Search Genes
+
+```
+GET https://mygene.info/v3/query?q={query}&size={n}
+```
+
+Query by gene symbol, name, Entrez ID, Ensembl ID, or keyword. Supports boolean operators (`AND`, `OR`, `NOT`) and field-specific queries like `symbol:CDK2`.
+
+```bash
+curl -s "https://mygene.info/v3/query?q=BRCA1&size=1"
+```
+
+Response:
+
+```json
+{
+  "took": 178,
+  "total": 13223,
+  "hits": [
+    {
+      "_id": "672",
+      "_score": 145.6796,
+      "entrezgene": "672",
+      "name": "BRCA1 DNA repair associated",
+      "symbol": "BRCA1",
+      "taxid": 9606
+    }
+  ]
+}
+```
+
+### Get Gene by ID
+
+```
+GET https://mygene.info/v3/gene/{entrez_id}
+```
+
+Returns comprehensive annotations for a single gene. Use the `fields` parameter to select specific data sources.
+
+```bash
+# Full annotation (large response)
+curl -s "https://mygene.info/v3/gene/1017"
+
+# Selective fields
+curl -s "https://mygene.info/v3/gene/1017?fields=symbol,name,summary,genomic_pos,go"
+```
+
+Response (key fields for CDK2, Entrez ID 1017):
+
+```json
+{
+  "_id": "1017",
+  "symbol": "CDK2",
+  "name": "cyclin dependent kinase 2",
+  "HGNC": "1771",
+  "MIM": "116953",
+  "AllianceGenome": "1771",
+  "taxid": 9606,
+  "type_of_gene": "protein-coding"
+}
+```
+
+The full response includes accessions, Gene Ontology terms, pathway memberships (KEGG, Reactome, WikiPathways), protein domains (InterPro, Pfam), homology data, and genomic coordinates.
+
+## MyVariant.info — Variant Annotations
+
+### Search Variants
+
+```
+GET https://myvariant.info/v1/query?q={query}&size={n}
+```
+
+Query by rsID, HGVS notation (e.g., `chr7:g.140453136A>T`), gene symbol, or ClinVar significance. Returns aggregated annotations from 15+ sources.
+
+```bash
+curl -s "https://myvariant.info/v1/query?q=rs58991260&size=1"
+```
+
+Response (truncated):
+
+```json
+{
+  "took": 20,
+  "total": 1,
+  "hits": [
+    {
+      "_id": "chr1:g.218631822G>A",
+      "_score": 21.382616,
+      "dbsnp": {
+        "rsid": "rs58991260",
+        "vartype": "snv",
+        "ref": "G",
+        "alt": "A",
+        "chrom": "1"
+      },
+      "cadd": {
+        "phred": 1.679,
+        "consequence": "INTERGENIC",
+        "chrom": 1,
+        "pos": 218631822
+      },
+      "gnomad_genome": {
+        "af": { "af": 0.0150338, "af_afr": 0.0528007, "af_eas": 0.0, "af_nfe": 0.00032417 },
+        "alt": "A",
+        "ref": "G"
+      }
+    }
+  ]
+}
+```
+
+### Get Variant by HGVS ID
+
+```
+GET https://myvariant.info/v1/variant/{hgvs_id}
+```
+
+```bash
+curl -s "https://myvariant.info/v1/variant/chr1:g.218631822G>A?fields=dbsnp,cadd,clinvar"
+```
+
+## MyChem.info — Drug & Chemical Annotations
+
+### Search Drugs/Chemicals
+
+```
+GET https://mychem.info/v1/query?q={query}&size={n}
+```
+
+Query by drug name, NDC code, InChIKey, or active ingredient. Aggregates data from FDA NDC, DrugBank, ChEMBL, PubChem, SIDER, and more.
+
+```bash
+curl -s "https://mychem.info/v1/query?q=aspirin&size=1"
+```
+
+Response (truncated):
+
+```json
+{
+  "took": 82,
+  "total": 248,
+  "hits": [
+    {
+      "_id": "0615-8613",
+      "_score": 13.657401,
+      "ndc": {
+        "substancename": "ASPIRIN",
+        "nonproprietaryname": "Aspirin",
+        "proprietaryname": "Adult Low Dose Aspirin",
+        "active_numerator_strength": "81",
+        "active_ingred_unit": "mg/1",
+        "dosageformname": "TABLET, DELAYED RELEASE",
+        "routename": "ORAL",
+        "producttypename": "HUMAN OTC DRUG",
+        "pharm_classes": [
+          "Cyclooxygenase Inhibitors [MoA]",
+          "Decreased Platelet Aggregation [PE]",
+          "Anti-Inflammatory Agents, Non-Steroidal [CS]",
+          "Nonsteroidal Anti-inflammatory Drug [EPC]",
+          "Platelet Aggregation Inhibitor [EPC]"
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Get Chemical by ID
+
+```
+GET https://mychem.info/v1/chem/{id}
+```
+
+```bash
+curl -s "https://mychem.info/v1/chem/CHEMBL25?fields=drugbank,chembl,pubchem"
+```
+
+## Query Syntax (Shared Across All Three APIs)
+
+All BioThings APIs share the same query engine. Key features:
+
+| Feature | Syntax | Example |
+|---------|--------|---------|
+| Field-specific | `field:value` | `symbol:TP53` |
+| Boolean | `AND`, `OR`, `NOT` | `BRCA1 AND cancer` |
+| Wildcard | `*` | `CDK*` |
+| Range | `[min TO max]` | `exac.af:[0.01 TO 0.05]` |
+| Pagination | `size`, `from` | `size=20&from=40` |
+| Field selection | `fields` | `fields=symbol,name,go` |
+| Sorting | `sort` | `sort=_score:desc` |
+| Batch POST | POST with `ids` | Up to 1000 IDs per request |
+
+## Rate Limits
+
+- **GET requests:** 3 per second sustained; bursts up to 10/s tolerated
+- **POST batch requests:** 1 per second; up to 1000 IDs per batch
+- **No daily cap** for reasonable academic usage
+- **Best practice:** Add 350ms delays between sequential requests; use batch POST for bulk queries
+- **User-Agent header:** Set a descriptive User-Agent for priority support from the BioThings team
+
+## Python Example: Cross-API Gene-Variant-Drug Lookup
+
+```python
+import requests, time
+
+MYGENE = "https://mygene.info/v3"
+MYVARIANT = "https://myvariant.info/v1"
+MYCHEM = "https://mychem.info/v1"
+
+def search_gene(symbol):
+    resp = requests.get(f"{MYGENE}/query",
+                        params={"q": f"symbol:{symbol}", "size": 1, "species": "human"})
+    resp.raise_for_status()
+    hits = resp.json().get("hits", [])
+    return hits[0] if hits else {}
+
+def search_variants(gene_symbol, size=5):
+    resp = requests.get(f"{MYVARIANT}/query",
+                        params={"q": f"clinvar.gene.symbol:{gene_symbol}",
+                                "fields": "dbsnp.rsid,clinvar.rcv.clinical_significance,cadd.phred",
+                                "size": size})
+    resp.raise_for_status()
+    return resp.json().get("hits", [])
+
+def search_drug(name):
+    resp = requests.get(f"{MYCHEM}/query",
+                        params={"q": name, "size": 1,
+                                "fields": "ndc.substancename,ndc.pharm_classes"})
+    resp.raise_for_status()
+    hits = resp.json().get("hits", [])
+    return hits[0] if hits else {}
+
+# Translational research pipeline: gene -> variants -> drug
+gene = search_gene("BRCA1")
+print(f"Gene: {gene.get('symbol')} (Entrez: {gene.get('entrezgene')})")
+time.sleep(0.35)
+
+variants = search_variants("BRCA1", size=3)
+for v in variants:
+    rsid = v.get("dbsnp", {}).get("rsid", v.get("_id"))
+    print(f"  Variant: {rsid} | CADD: {v.get('cadd', {}).get('phred', 'N/A')}")
+time.sleep(0.35)
+
+drug = search_drug("olaparib")
+print(f"  Drug: {drug.get('ndc', {}).get('substancename', 'N/A')}")
+```
+
+## Academic Use Cases
+
+- **GWAS follow-up:** Annotate thousands of significant SNPs with allele frequencies (gnomAD), functional predictions (CADD, SIFT, PolyPhen), and clinical significance (ClinVar) via MyVariant.info batch queries.
+- **Drug target mapping:** Link gene symbols to pathway memberships (KEGG, Reactome) via MyGene.info, then find approved drugs targeting those pathways via MyChem.info.
+- **Pharmacogenomics:** Cross-reference variant annotations with drug metabolism data to identify clinically actionable gene-drug interactions.
+- **Systematic reviews:** Programmatically collect gene/variant metadata across large candidate lists to populate supplementary tables in genomics publications.
+
+## References
+
+- BioThings API Hub: https://biothings.io
+- MyGene.info Documentation: https://docs.mygene.info
+- MyVariant.info Documentation: https://docs.myvariant.info
+- MyChem.info Documentation: https://docs.mychem.info
+- Publication: Xin J et al. *Genome Biology* 17:91 (2016). https://doi.org/10.1186/s13059-016-0953-9