@wentorai/research-plugins 1.3.1 → 1.4.0

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

package/skills/domains/biomedical/clinical-research-guide/SKILL.md

@@ -3,7 +3,7 @@ name: clinical-research-guide
 description: "Design clinical studies and report using CONSORT, STROBE guidelines"
 metadata:
   openclaw:
-    emoji: "hospital"
+    emoji: "🏥"
     category: "domains"
     subcategory: "biomedical"
     keywords: ["clinical research", "CONSORT", "STROBE", "clinical trial", "study design", "reporting guidelines"]

package/skills/domains/biomedical/clinicaltrials-api-v2/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: clinicaltrials-api-v2
+description: "Search and analyze clinical trials via the ClinicalTrials.gov v2 API"
+metadata:
+  openclaw:
+    emoji: "🏥"
+    category: "domains"
+    subcategory: "biomedical"
+    keywords: ["clinical trials", "ClinicalTrials.gov", "medical research", "study design", "FDA", "drug trials"]
+    source: "https://clinicaltrials.gov/data-api/about-api"
+---
+
+# ClinicalTrials.gov v2 API Guide
+
+## Overview
+
+ClinicalTrials.gov is the world's largest clinical trial registry, maintained by the U.S. National Library of Medicine (NLM) at NIH. It contains over 576,000 study records from 220+ countries covering interventional trials, observational studies, and expanded access programs. The v2 API provides structured JSON access with field-level filtering, cursor-based pagination, and statistics endpoints.
+
+Key v2 improvements over the legacy API: JSON-native responses, sparse field selection via the `fields` parameter, `nextPageToken` pagination, and dedicated statistics endpoints. Study data is organized into `protocolSection` (sponsor-submitted) and `derivedSection` (NLM-computed).
+
+## Authentication
+
+No authentication required. All endpoints are publicly accessible without API keys or registration. Users should comply with NCBI usage policies and maintain reasonable request rates.
+
+## Core Endpoints
+
+### Search Studies
+
+- **URL**: `GET https://clinicaltrials.gov/api/v2/studies`
+- **Parameters**:
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| query.term | string | No | Free-text search across all fields |
+| query.cond | string | No | Condition or disease filter |
+| query.intr | string | No | Intervention or treatment filter |
+| query.spons | string | No | Sponsor or collaborator filter |
+| filter.overallStatus | string | No | `RECRUITING`, `COMPLETED`, `ACTIVE_NOT_RECRUITING`, etc. |
+| filter.phase | string | No | `EARLY_PHASE1`, `PHASE1`, `PHASE2`, `PHASE3`, `PHASE4`, `NA` |
+| filter.geo | string | No | Geographic filter (`distance(lat,lng,dist)`) |
+| fields | string | No | Comma-separated fields for sparse response |
+| sort | string | No | Sort field and direction (e.g., `LastUpdatePostDate:desc`) |
+| pageSize | int | No | Results per page (default 10, max 1000) |
+| pageToken | string | No | Cursor token for next page |
+| format | string | No | `json` (default) or `csv` |
+
+- **Example**:
+
+```bash
+curl "https://clinicaltrials.gov/api/v2/studies?query.cond=diabetes&query.intr=metformin&pageSize=1&fields=NCTId,BriefTitle,OverallStatus"
+```
+
+- **Response**:
+
+```json
+{
+  "studies": [{
+    "protocolSection": {
+      "identificationModule": {
+        "nctId": "NCT06649773",
+        "briefTitle": "The Experiment of Noiiglutide Injection in Type 2 Diabetes Patients"
+      },
+      "statusModule": { "overallStatus": "ACTIVE_NOT_RECRUITING" }
+    }
+  }],
+  "nextPageToken": "ZVNj7o2Elu8o3lpo..."
+}
+```
+
+Full responses include `protocolSection` with: `identificationModule` (NCT ID, titles, organization), `statusModule` (status, dates), `descriptionModule` (summary), `conditionsModule`, `designModule` (type, phases, enrollment), `armsInterventionsModule`, `eligibilityModule` (criteria, sex, age), `outcomesModule`, and `contactsLocationsModule`.
+
+### Get Single Study
+
+- **URL**: `GET https://clinicaltrials.gov/api/v2/studies/{nctId}`
+
+```bash
+curl "https://clinicaltrials.gov/api/v2/studies/NCT04280705?fields=NCTId,BriefTitle,OverallStatus,Phase,LeadSponsorName,EnrollmentCount,Condition,InterventionName"
+```
+
+```json
+{
+  "protocolSection": {
+    "identificationModule": {
+      "nctId": "NCT04280705",
+      "briefTitle": "Adaptive COVID-19 Treatment Trial (ACTT)"
+    },
+    "statusModule": {
+      "overallStatus": "COMPLETED",
+      "startDateStruct": { "date": "2020-02-21" },
+      "completionDateStruct": { "date": "2020-05-21" }
+    },
+    "sponsorCollaboratorsModule": {
+      "leadSponsor": { "name": "National Institute of Allergy and Infectious Diseases (NIAID)" }
+    },
+    "conditionsModule": { "conditions": ["COVID-19"] },
+    "designModule": { "phases": ["PHASE3"], "enrollmentInfo": { "count": 1062 } },
+    "armsInterventionsModule": {
+      "interventions": [{ "name": "Placebo" }, { "name": "Remdesivir" }]
+    }
+  }
+}
+```
+
+### Database Statistics
+
+- **URL**: `GET https://clinicaltrials.gov/api/v2/stats/size`
+
+```bash
+curl "https://clinicaltrials.gov/api/v2/stats/size"
+```
+
+```json
+{
+  "totalStudies": 576554,
+  "averageSizeBytes": 17186,
+  "largestStudies": [
+    { "id": "NCT02723955", "sizeBytes": 3596689 },
+    { "id": "NCT03688620", "sizeBytes": 2865033 }
+  ]
+}
+```
+
+### Field Value Statistics
+
+- **URL**: `GET https://clinicaltrials.gov/api/v2/stats/fieldValues/{fieldName}`
+
+```bash
+curl "https://clinicaltrials.gov/api/v2/stats/fieldValues/Phase"
+```
+
+```json
+{
+  "type": "ENUM",
+  "piece": "Phase",
+  "field": "protocolSection.designModule.phases",
+  "missingStudiesCount": 136632,
+  "topValues": [
+    { "value": "NA", "studiesCount": 222829 },
+    { "value": "PHASE2", "studiesCount": 87478 },
+    { "value": "PHASE1", "studiesCount": 63716 },
+    { "value": "PHASE3", "studiesCount": 48700 },
+    { "value": "PHASE4", "studiesCount": 34911 },
+    { "value": "EARLY_PHASE1", "studiesCount": 6179 }
+  ]
+}
+```
+
+## Rate Limits
+
+No formal rate limits are published for the v2 API. Follow NCBI usage guidelines: stay under 3 requests/second without an API key, up to 10/second with one. For bulk data access, use the AACT relational database (https://aact.ctti-clinicaltrials.org/) or downloadable flat files rather than paginating through the full API.
+
+## Academic Use Cases
+
+- **Systematic reviews**: Use `query.cond` + `query.intr` + `filter.overallStatus=COMPLETED` to build PRISMA-compliant trial inventories. Paginate with `nextPageToken` to collect all records, then extract outcomes and enrollment for quantitative synthesis.
+- **Landscape mapping**: Combine search with `stats/fieldValues` to map phase distributions, sponsor concentration, and geographic spread for a therapeutic area -- useful for identifying evidence gaps in grant proposals.
+- **Recruitment tracking**: Filter by `RECRUITING` status and `filter.geo` to find active enrollment opportunities. Automate periodic queries for new trials in your domain.
+
+## Code Examples
+
+### Paginated Collection for Systematic Review
+
+```python
+import requests, time
+
+def collect_trials(condition, intervention, status="COMPLETED"):
+    base = "https://clinicaltrials.gov/api/v2/studies"
+    studies, token = [], None
+    while True:
+        params = {
+            "query.cond": condition, "query.intr": intervention,
+            "filter.overallStatus": status, "pageSize": 100,
+            "fields": "NCTId,BriefTitle,Phase,EnrollmentCount,CompletionDate",
+        }
+        if token:
+            params["pageToken"] = token
+        data = requests.get(base, params=params).json()
+        studies.extend(data.get("studies", []))
+        token = data.get("nextPageToken")
+        if not token:
+            break
+        time.sleep(0.34)
+    return studies
+
+trials = collect_trials("type 2 diabetes", "metformin")
+print(f"Collected {len(trials)} completed metformin T2D trials")
+```
+
+### Sponsor and Phase Analysis
+
+```python
+import requests
+from collections import Counter
+
+params = {"query.cond": "Alzheimer's Disease", "pageSize": 100,
+          "fields": "NCTId,Phase,LeadSponsorName"}
+data = requests.get("https://clinicaltrials.gov/api/v2/studies", params=params).json()
+
+phases, sponsors = Counter(), Counter()
+for s in data["studies"]:
+    p = s["protocolSection"]
+    for ph in p.get("designModule", {}).get("phases", []):
+        phases[ph] += 1
+    sponsors[p.get("sponsorCollaboratorsModule", {})
+              .get("leadSponsor", {}).get("name", "Unknown")] += 1
+
+for ph, n in phases.most_common():
+    print(f"{ph}: {n}")
+```
+
+## References
+
+- v2 API reference: https://clinicaltrials.gov/data-api/api
+- About the API: https://clinicaltrials.gov/data-api/about-api
+- AACT database (bulk access): https://aact.ctti-clinicaltrials.org/
+- WHO ICTRP: https://trialsearch.who.int/
+- NCBI usage policies: https://www.ncbi.nlm.nih.gov/home/about/policies/