wotann 0.5.0 → 0.5.39

package/skills/scientific/database-lookup/references/clinicaltrials.md

@@ -0,0 +1,77 @@
+# ClinicalTrials.gov (v2 API)
+
+## Base URL
+```
+https://clinicaltrials.gov/api/v2/
+```
+
+## Auth
+No API key required. Fully public.
+
+## Key Endpoints
+
+### Search studies
+```
+GET /studies
+```
+
+Key parameters:
+- `query.cond` — condition/disease (e.g. `breast cancer`)
+- `query.intr` — intervention/treatment (e.g. `pembrolizumab`)
+- `query.term` — general search terms
+- `query.spons` — sponsor
+- `query.id` — NCT ID
+- `filter.overallStatus` — pipe-delimited: `RECRUITING|COMPLETED|ACTIVE_NOT_RECRUITING|...`
+- `filter.phase` — `PHASE1|PHASE2|PHASE3|PHASE4|NA`
+- `filter.geo` — `distance(lat,lon,dist)` e.g. `distance(38.89,-77.03,50mi)`
+- `fields` — comma-separated field list to reduce payload
+- `sort` — e.g. `LastUpdatePostDate:desc`
+- `pageSize` — results per page (default 10, max 1000)
+- `pageToken` — cursor for next page (from `nextPageToken` in response)
+- `countTotal=true` — include total count
+
+Example — recruiting Phase 3 breast cancer trials:
+```
+/studies?query.cond=breast+cancer&filter.overallStatus=RECRUITING&filter.phase=PHASE3&pageSize=5&countTotal=true
+```
+
+Response structure:
+```json
+{
+  "totalCount": 1234,
+  "studies": [
+    {
+      "protocolSection": {
+        "identificationModule": {"nctId": "NCT05123456", "briefTitle": "..."},
+        "statusModule": {"overallStatus": "RECRUITING"},
+        "designModule": {"phases": ["PHASE3"], "enrollmentInfo": {"count": 500}},
+        "conditionsModule": {"conditions": ["Breast Cancer"]},
+        "eligibilityModule": {"minimumAge": "18 Years", "sex": "ALL"}
+      }
+    }
+  ],
+  "nextPageToken": "CAYQAg"
+}
+```
+
+### Single study by NCT ID
+```
+GET /studies/{nctId}
+```
+Example: `/studies/NCT05123456`
+
+### Study count
+```
+GET /stats/size?query.cond={condition}&filter.overallStatus=RECRUITING
+```
+
+### Field metadata
+```
+GET /studies/metadata
+```
+
+## Pagination
+Uses cursor-based pagination via `pageToken` (NOT numeric offsets). Include `countTotal=true` on first request to get total.
+
+## Rate Limits
+No API key. Be reasonable — a few requests per second. Bulk: https://clinicaltrials.gov/AllAPIJSON.zip

package/skills/scientific/database-lookup/references/clinpgx.md

@@ -0,0 +1,64 @@
+# PharmGKB (Clinical Pharmacogenomics)
+
+## Base URL
+```
+https://api.pharmgkb.org/v1/data/
+```
+
+## Auth
+No API key required for read-only access.
+
+## Key Endpoints
+
+### General search
+```
+GET https://api.pharmgkb.org/v1/search?q={term}&page=0&size=10
+```
+
+### Gene data
+```
+GET /gene?symbol={symbol}
+```
+Example: `/gene?symbol=CYP2D6`
+
+Response includes: id, symbol, chromosome, hasGuideline, hasClinicalAnnotation, cpicGene
+
+### Drug data
+```
+GET /drug?name={name}
+```
+Example: `/drug?name=warfarin`
+
+Response includes: id, name, genericNames, tradeNames, rxNormId, atcCodes
+
+### Clinical annotations (drug-gene interactions)
+```
+GET /clinicalAnnotation?gene={symbol}&drug={name}&level={level}
+```
+
+Evidence levels: `1A`, `1B`, `2A`, `2B`, `3`, `4`
+
+Example:
+```
+/clinicalAnnotation?gene=CYP2C19&drug=clopidogrel&level=1A
+```
+
+Response includes: level, gene, drug, phenotype, significance, variants, url
+
+### CPIC/DPWG guidelines
+```
+GET /guideline?gene={symbol}&drug={name}&source=CPIC
+```
+
+### Pharmacokinetic pathways
+```
+GET /pathway?drug={name}
+```
+
+### Drug labels (FDA, EMA)
+```
+GET /drugLabel?drug={name}&source=FDA
+```
+
+## Rate Limits
+No hard published limit. Be reasonable. Bulk data via PharmGKB download page.

package/skills/scientific/database-lookup/references/clinvar.md

@@ -0,0 +1,91 @@
+# ClinVar API Reference
+
+## Base URLs
+- **NCBI E-utilities**: `https://eutils.ncbi.nlm.nih.gov/entrez/eutils`
+- **ClinVar web API (VCV)**: `https://www.ncbi.nlm.nih.gov/clinvar`
+- **NCBI Variation Services**: `https://api.ncbi.nlm.nih.gov/variation/v0`
+
+## Authentication
+- E-utilities: No key required, but **strongly recommended**. Register at https://www.ncbi.nlm.nih.gov/account/ to get an `api_key`.
+- Without key: 3 requests/second. With key: 10 requests/second.
+- Append `&api_key=YOUR_KEY` to all E-utility requests.
+
+## Rate Limits
+- Without API key: 3 req/sec
+- With API key: 10 req/sec
+
+## Key Endpoints
+
+### 1. Search ClinVar (esearch)
+```
+GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=clinvar&term={query}&retmode=json
+```
+Example — search for BRCA1 pathogenic variants:
+```
+GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=clinvar&term=BRCA1[gene]+AND+pathogenic[clinical_significance]&retmode=json&retmax=10
+```
+Returns JSON with `idlist` of ClinVar Variation IDs.
+
+### 2. Fetch ClinVar Records (esummary)
+```
+GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=clinvar&id={id_list}&retmode=json
+```
+Example:
+```
+GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=clinvar&id=37088,37087&retmode=json
+```
+Returns JSON with clinical significance, variant name, gene, conditions, review status.
+
+### 3. Full Record (efetch)
+```
+GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=clinvar&id={id}&rettype=vcv&is_variationid&retmode=xml
+```
+Note: ClinVar efetch returns **XML only** (no JSON for efetch).
+
+### 4. Variation Services API — SPDI/HGVS Lookup
+```
+GET https://api.ncbi.nlm.nih.gov/variation/v0/spdi/{spdi_expression}/clinvar
+GET https://api.ncbi.nlm.nih.gov/variation/v0/hgvs/{hgvs_expression}/clinvar
+```
+Example:
+```
+GET https://api.ncbi.nlm.nih.gov/variation/v0/hgvs/NM_007294.4%3Ac.5266dupC/clinvar
+```
+
+### 5. ClinVar VCV/RCV Direct Access
+```
+GET https://www.ncbi.nlm.nih.gov/clinvar/variation/{variation_id}/?redir=vcv
+```
+This returns HTML. For programmatic access, use E-utilities or the Variation Services API.
+
+## Useful Search Qualifiers
+- `[gene]` — gene symbol (e.g., `BRCA1[gene]`)
+- `[clinical_significance]` — pathogenic, likely_pathogenic, benign, uncertain_significance
+- `[molecular_consequence]` — missense, nonsense, frameshift, etc.
+- `[review_status]` — criteria_provided_single_submitter, reviewed_by_expert_panel, etc.
+- `[condition]` — disease name
+
+## Response Format
+- esearch/esummary: JSON (with `retmode=json`)
+- efetch: XML only for ClinVar
+- Variation Services: JSON
+
+## esummary Response Key Fields
+```json
+{
+  "result": {
+    "37088": {
+      "uid": "37088",
+      "title": "NM_007294.4(BRCA1):c.5266dupC (p.Gln1756Profs*74)",
+      "clinical_significance": { "description": "Pathogenic" },
+      "genes": [{"symbol": "BRCA1", "geneid": 672}],
+      "variation_set": [...],
+      "trait_set": [{"trait_name": "Hereditary breast and ovarian cancer syndrome"}]
+    }
+  }
+}
+```
+
+## Notes
+- Combine esearch + esummary for search-then-fetch workflows.
+- For bulk downloads, use ClinVar FTP: https://ftp.ncbi.nlm.nih.gov/pub/clinvar/

package/skills/scientific/database-lookup/references/cod.md

@@ -0,0 +1,121 @@
+# Crystallography Open Database (COD) API
+
+## Base URL
+
+```
+https://www.crystallography.net/cod
+```
+
+## Authentication
+
+**None required.** COD is fully open-access with no API key needed.
+
+## Key Endpoints
+
+### Search by formula
+
+```
+GET /result?formula=Fe2%20O3&format=json
+```
+
+Formula format uses spaces between elements: `Fe2 O3`, `Si O2`, `C6 H12 O6`. URL-encode spaces as `%20`.
+
+### Search by elements
+
+```
+GET /result?el1=Fe&el2=O&format=json
+```
+
+Use `el1`, `el2`, `el3`, etc. for element filters. Use `nel=2` to restrict to exactly 2 elements.
+
+### Search by cell parameters
+
+```
+GET /result?a_min=5.0&a_max=6.0&b_min=5.0&b_max=6.0&c_min=5.0&c_max=6.0&format=json
+```
+
+Cell parameter filters:
+- `a_min`, `a_max` — a-axis length (Angstroms)
+- `b_min`, `b_max` — b-axis length
+- `c_min`, `c_max` — c-axis length
+- `alpha_min`, `alpha_max` — alpha angle (degrees)
+- `beta_min`, `beta_max` — beta angle
+- `gamma_min`, `gamma_max` — gamma angle
+- `vol_min`, `vol_max` — unit cell volume (A^3)
+
+### Search by space group
+
+```
+GET /result?sg=F%20m%20-3%20m&format=json
+```
+
+### Search by text (author, journal, title)
+
+```
+GET /result?text=perovskite&format=json
+```
+
+### Combined search example
+
+```
+GET /result?el1=Ti&el2=O&nel=2&sg=P%2042/m%20n%20m&format=json
+```
+
+### Retrieve a specific CIF file
+
+```
+GET /1000000.cif
+```
+
+COD IDs are 7-digit integers. Append `.cif` for the crystallographic information file, or `.html` for the web page.
+
+### Retrieve entry metadata as JSON
+
+```
+GET /result?id=1000000&format=json
+```
+
+### Output formats
+
+- `format=json` — JSON array of matching entries
+- `format=csv` — CSV output
+- `format=lst` — list of COD IDs only
+- Default (no format) — HTML page
+
+## Response Format
+
+```json
+[
+  {
+    "file": "1526463",
+    "a": "4.759",
+    "b": "4.759",
+    "c": "12.992",
+    "alpha": "90",
+    "beta": "90",
+    "gamma": "120",
+    "vol": "254.94",
+    "sg": "R -3 c",
+    "formula": "Fe2 O3",
+    "title": "Refinement of the crystal structure of ...",
+    "journal": "Zeitschrift fuer Kristallographie",
+    "year": "1966",
+    "authors": "Blake, R.L.; et al."
+  }
+]
+```
+
+The `file` field is the COD ID. Use it to fetch the CIF: `https://www.crystallography.net/cod/{file}.cif`
+
+## Rate Limits
+
+- No formal rate limits documented
+- Be courteous: avoid bulk-downloading thousands of entries rapidly
+- For bulk access, COD provides downloadable database dumps at https://www.crystallography.net/cod/archives/
+
+## Notes
+
+- COD contains ~500,000+ crystal structures from published literature
+- All data is open-access under public domain / open licenses
+- The search API returns metadata; use the CIF endpoint for full structural data
+- Alternative access: MySQL database dumps and SVN access are available for bulk use

package/skills/scientific/database-lookup/references/cosmic.md

@@ -0,0 +1,59 @@
+# COSMIC (Catalogue of Somatic Mutations in Cancer)
+
+## Base URL
+```
+https://cancer.sanger.ac.uk/cosmic/api/v1/
+```
+
+## Auth
+**Registration required.** Free academic account or paid commercial license.
+
+Login to get JWT token:
+```
+POST /auth/login
+Content-Type: application/json
+{"email": "you@example.com", "password": "yourpassword"}
+```
+Pass token as: `Authorization: Bearer <token>`
+
+## Key Endpoints
+
+### Search mutations by gene
+```
+GET /mutations/search?q={gene_symbol}&page=1&page_size=5
+```
+
+### Get gene information
+```
+GET /genes/{gene_symbol}
+```
+Example: `/genes/BRAF`
+
+Response includes: gene_symbol, gene_name, chromosome, cancer_census (bool), tier, mutation_count, sample_count
+
+### Get specific mutation by COSMIC ID
+```
+GET /mutations/{cosmic_mutation_id}
+```
+Example: `/mutations/COSV56056643`
+
+Response includes: gene, cds_mutation, aa_mutation, mutation_type, fathmm_prediction, genomic_coordinates, tissue_distribution
+
+### Cancer Gene Census
+```
+GET /cancer-gene-census?tier=1&page_size=10
+```
+
+### Mutations by tissue/histology
+```
+GET /mutations/distribution/{gene_symbol}
+```
+
+## Rate Limits
+Not officially published. Bulk data requires SFTP download (licensed).
+
+## Important
+- COSMIC requires authentication for all API calls
+- Commercial use requires a paid license
+- Bulk data access via SFTP is preferred over API for large queries
+- API structure may change across COSMIC versions

package/skills/scientific/database-lookup/references/dailymed.md

@@ -0,0 +1,65 @@
+# DailyMed (NIH/NLM Drug Labels)
+
+## Base URL
+```
+https://dailymed.nlm.nih.gov/dailymed/services/
+```
+
+## Auth
+No API key required.
+
+## Key Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `v2/spls.json?drug_name={name}` | Search drug labels by name |
+| `v2/spls/{setid}.json` | Get label metadata by SetID |
+| `v2/spls/{setid}/ndcs.json` | NDC codes for a label |
+| `v2/spls/{setid}/media.json` | Images/media for a label |
+| `v2/drugnames.json?drug_name={prefix}` | Drug name autocomplete |
+| `v2/drugclasses.json?drug_class_name={name}` | Search by pharmacologic class |
+| `v2/rxcuis.json?drug_name={name}` | RxNorm CUIs for a drug |
+| `v2/ndc/{ndc_code}/spls.json` | Find labels by NDC code |
+
+## Additional filters for `/v2/spls.json`
+- `drug_class` — pharmacologic class
+- `labeler` — manufacturer name
+- `page` / `pagesize` — pagination (max 100)
+
+## Example Calls
+
+```
+# Search metformin labels
+https://dailymed.nlm.nih.gov/dailymed/services/v2/spls.json?drug_name=metformin
+
+# Drug name autocomplete
+https://dailymed.nlm.nih.gov/dailymed/services/v2/drugnames.json?drug_name=ator
+
+# Search by pharmacologic class
+https://dailymed.nlm.nih.gov/dailymed/services/v2/spls.json?drug_class=HMG-CoA+Reductase+Inhibitor
+
+# Full label XML (SPL content with sections)
+https://dailymed.nlm.nih.gov/dailymed/services/v2/spls/{setid}/packaging.xml
+```
+
+## Response Format
+```json
+{
+  "metadata": {
+    "total_elements": 12,
+    "elements_per_page": 10,
+    "current_page": 1,
+    "total_pages": 2
+  },
+  "data": [
+    {
+      "published_date": "2024-01-15",
+      "title": "METFORMIN HYDROCHLORIDE tablet",
+      "setid": "b03f295f-..."
+    }
+  ]
+}
+```
+
+## Rate Limits
+No published limits. Be reasonable.