wotann 0.5.0 → 0.5.39

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

@@ -0,0 +1,50 @@
+# JASPAR (Transcription Factor Binding Profiles)
+
+## Base URL
+```
+https://jaspar.elixir.no/api/v1/
+```
+
+## Auth
+No auth required.
+
+## Key Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/matrix/` | List all TF binding profiles |
+| `/matrix/{matrix_id}/` | Specific profile (e.g. MA0139.1 for CTCF) |
+| `/matrix/?tax_id={id}&collection=CORE` | Filter by species + collection |
+| `/matrix/{id}/?format=jaspar` | Profile in JASPAR format |
+| `/matrix/{id}/?format=meme` | Profile in MEME format |
+| `/matrix/{id}/?format=transfac` | Profile in TRANSFAC format |
+| `/taxon/` | List taxonomic groups |
+| `/collection/` | List collections (CORE, CNE, etc.) |
+
+## Filter Parameters
+- `tax_id` — NCBI taxonomy ID (9606 for human)
+- `collection` — CORE, CNE, PHYLOFACTS, etc.
+- `tf_class` — TF structural class
+- `name` — TF name search
+- `page`, `page_size` — pagination
+
+## Example Calls
+```
+# Get CTCF binding profile
+https://jaspar.elixir.no/api/v1/matrix/MA0139.1/
+
+# Human CORE TF profiles
+https://jaspar.elixir.no/api/v1/matrix/?tax_id=9606&collection=CORE&page_size=10
+
+# Get profile in MEME format
+https://jaspar.elixir.no/api/v1/matrix/MA0139.1/?format=meme
+```
+
+## Response Format
+JSON. Profiles include: `matrix_id`, `name`, `pfm` (position frequency matrix as A/C/G/T dict), `sequence_logo` URL, `species`, `class`, `family`.
+
+## API Docs
+Swagger at https://jaspar.elixir.no/api/v1/docs/
+
+## Rate Limits
+No published limits. Be reasonable.

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

@@ -0,0 +1,78 @@
+# KEGG REST API
+
+## Base URL
+```
+https://rest.kegg.jp
+```
+
+## Auth
+No API key required. Free for academic use. Commercial use requires license.
+
+## Important: KEGG returns tab-delimited text and flat-file format, NOT JSON.
+
+## Key Operations (URL-path-based, no query parameters)
+
+| URL Pattern | Description |
+|-------------|-------------|
+| `/list/{database}` | List all entries |
+| `/list/{database}/{organism}` | List entries for organism |
+| `/get/{dbentries}` | Get entry data (flat-file) |
+| `/get/{dbentries}/image` | Pathway image (PNG) |
+| `/get/{dbentries}/kgml` | Pathway as KGML XML |
+| `/find/{database}/{query}` | Search by keyword |
+| `/find/{database}/{query}/formula` | Search by molecular formula |
+| `/find/{database}/{value}/exact_mass` | Search by exact mass |
+| `/link/{target_db}/{source_db}` | Find linked entries between databases |
+| `/link/{target_db}/{dbentries}` | Links for specific IDs |
+| `/conv/{target_db}/{dbentries}` | Cross-reference ID conversion |
+| `/ddi/{dbentries}` | Drug-drug interactions |
+
+## Database Codes
+
+| Code | Database | Example ID |
+|------|----------|------------|
+| `pathway` | Pathways | `hsa00010` |
+| `compound` | Compounds | `C00001` |
+| `drug` | Drugs | `D00001` |
+| `enzyme` | Enzymes | `ec:1.1.1.1` |
+| `genes`/`hsa` | Genes | `hsa:10458` |
+| `disease` | Diseases | `H00001` |
+| `reaction` | Reactions | `R00001` |
+| `ko` | KO orthologs | `K00001` |
+
+## Example Calls
+
+```
+# List human pathways
+https://rest.kegg.jp/list/pathway/hsa
+
+# Get pathway entry
+https://rest.kegg.jp/get/hsa00010
+
+# Search compounds by name
+https://rest.kegg.jp/find/compound/aspirin
+
+# Search by molecular formula
+https://rest.kegg.jp/find/compound/C9H8O4/formula
+
+# Find pathways for a gene
+https://rest.kegg.jp/link/pathway/hsa:10458
+
+# Find diseases for a gene
+https://rest.kegg.jp/link/disease/hsa:672
+
+# Convert KEGG to PubChem IDs
+https://rest.kegg.jp/conv/pubchem/C00001
+
+# Get multiple entries (max 10, joined with +)
+https://rest.kegg.jp/get/C00001+C00002+C00003
+
+# Drug-drug interactions
+https://rest.kegg.jp/ddi/D00564+D00110
+```
+
+## Response Format
+Tab-delimited text for list/find/link/conv. Flat-file text for get. **No JSON support.**
+
+## Rate Limits
+No published limits. Keep to a few requests per second. Batch up to 10 IDs per `/get` with `+`. May return HTTP 403 if too many requests.

package/skills/scientific/database-lookup/references/lincs-l1000.md

@@ -0,0 +1,68 @@
+# LINCS L1000 (Clue.io) API Reference
+
+## Overview
+The LINCS L1000 dataset is accessible via the **Connectivity Map (CMap) API** at clue.io.
+
+## Base URL
+```
+https://api.clue.io/api
+```
+
+## Authentication
+- **API key required** (free registration at clue.io)
+- Pass via header: `user_key: YOUR_API_KEY`
+
+## Key Endpoints
+
+| Endpoint | Description |
+|---|---|
+| `GET /perts` | Query perturbagens (compounds, gene knockdowns, overexpression) |
+| `GET /genes` | Query genes (L1000 landmark + inferred) |
+| `GET /cells` | Query cell lines used in L1000 |
+| `GET /sigs` | Query connectivity signatures |
+| `GET /profiles` | Access expression profiles (level 5 z-scores) |
+| `GET /pcls` | Perturbagen classes |
+
+## Query Parameters
+All endpoints support a `filter` parameter using Loopback-style JSON:
+- `where` — filter conditions
+- `fields` — select specific fields
+- `limit` / `skip` — pagination
+
+## Example Calls
+
+```bash
+# Search for a compound perturbagen by name
+curl -H "user_key: YOUR_API_KEY" \
+  "https://api.clue.io/api/perts?filter={\"where\":{\"pert_iname\":\"vorinostat\"}}"
+
+# Get landmark genes
+curl -H "user_key: YOUR_API_KEY" \
+  "https://api.clue.io/api/genes?filter={\"where\":{\"is_lm\":true},\"limit\":10}"
+
+# Query cell lines
+curl -H "user_key: YOUR_API_KEY" \
+  "https://api.clue.io/api/cells?filter={\"where\":{\"cell_iname\":\"MCF7\"}}"
+
+# Get connectivity signatures for a compound
+curl -H "user_key: YOUR_API_KEY" \
+  "https://api.clue.io/api/sigs?filter={\"where\":{\"pert_iname\":\"vorinostat\"},\"limit\":5}"
+```
+
+## Response Format
+JSON. Example (perturbagen):
+```json
+[
+  {
+    "pert_id": "BRD-K81418486",
+    "pert_iname": "vorinostat",
+    "pert_type": "trt_cp",
+    "moa": ["HDAC inhibitor"],
+    "target": ["HDAC1","HDAC2","HDAC3","HDAC6"]
+  }
+]
+```
+
+## Rate Limits
+- Free tier: moderate rate limiting (exact numbers not publicly documented)
+- Bulk data downloads available separately via clue.io data portal

package/skills/scientific/database-lookup/references/materials-project.md

@@ -0,0 +1,123 @@
+# Materials Project API
+
+## Base URL
+
+```
+https://api.materialsproject.org
+```
+
+## Authentication
+
+Requires a free API key. Register at https://materialsproject.org (free account).
+
+| Env Variable | Header |
+|---|---|
+| `MP_API_KEY` | `X-API-KEY: your_key_here` |
+
+All requests must include the API key header.
+
+## API Version
+
+The current API is **v2** (based on the `mp-api` Python client and the new MAPI endpoints). The legacy v1 REST API at `https://www.materialsproject.org/rest/v2/` is deprecated.
+
+## Key Endpoints
+
+### Search materials by formula or elements
+
+```
+GET /materials/summary/?formula=Fe2O3&_fields=material_id,formula_pretty,band_gap,formation_energy_per_atom
+```
+
+```
+GET /materials/summary/?elements=Si,O&_fields=material_id,formula_pretty,band_gap
+```
+
+Query parameters:
+- `formula` — exact chemical formula (e.g., `Fe2O3`, `SiO2`)
+- `chemsys` — chemical system, dash-separated (e.g., `Fe-O`, `Li-Fe-P-O`)
+- `elements` — comma-separated elements that must be present
+- `band_gap_min` / `band_gap_max` — filter by band gap (eV)
+- `is_stable` — `true` to return only thermodynamically stable phases
+- `_fields` — comma-separated list of fields to return
+- `_limit` — max results (default 10, max 1000)
+- `_skip` — offset for pagination
+
+### Get material by ID
+
+```
+GET /materials/summary/mp-149?_fields=material_id,formula_pretty,band_gap,formation_energy_per_atom,symmetry
+```
+
+Material IDs have the format `mp-NNNNN` (e.g., `mp-149` for silicon).
+
+### Available fields (summary)
+
+`material_id`, `formula_pretty`, `formula_anonymous`, `chemsys`, `volume`, `density`, `density_atomic`, `symmetry`, `band_gap`, `cbm`, `vbm`, `is_gap_direct`, `is_metal`, `is_magnetic`, `ordering`, `total_magnetization`, `formation_energy_per_atom`, `energy_above_hull`, `is_stable`, `equilibrium_reaction_energy_per_atom`, `nsites`, `elements`, `nelements`, `composition`, `structure`
+
+### Crystal structure
+
+```
+GET /materials/summary/mp-149?_fields=structure
+```
+
+Returns the structure as a pymatgen-compatible JSON dict with lattice parameters and atomic sites.
+
+### Elastic properties
+
+```
+GET /materials/elasticity/?material_id=mp-149&_fields=material_id,bulk_modulus,shear_modulus,elastic_tensor
+```
+
+### Electronic structure (band structure / DOS)
+
+```
+GET /materials/electronic_structure/bandstructure/mp-149
+GET /materials/electronic_structure/dos/mp-149
+```
+
+### Thermodynamic properties
+
+```
+GET /materials/thermo/?formula=Fe2O3&_fields=material_id,formation_energy_per_atom,energy_above_hull
+```
+
+### Example: Find stable oxides with band gap > 2 eV
+
+```
+GET /materials/summary/?elements=O&band_gap_min=2&is_stable=true&_fields=material_id,formula_pretty,band_gap,formation_energy_per_atom&_limit=10
+```
+
+## Response Format
+
+```json
+{
+  "data": [
+    {
+      "material_id": "mp-149",
+      "formula_pretty": "Si",
+      "band_gap": 0.6105,
+      "formation_energy_per_atom": 0.0
+    }
+  ],
+  "meta": {
+    "total_doc": 1
+  }
+}
+```
+
+## Rate Limits
+
+- Authenticated: ~50 requests/minute (varies by server load)
+- Batch requests preferred over many individual calls
+- Use `_fields` to reduce payload size and improve performance
+- The Python client `mp-api` handles pagination and retries automatically
+
+## Error Format
+
+```json
+{
+  "detail": "Not authenticated"
+}
+```
+
+HTTP 401 = missing or invalid API key. HTTP 404 = material not found. HTTP 429 = rate limited.

package/skills/scientific/database-lookup/references/metabolomics-workbench.md

@@ -0,0 +1,98 @@
+# Metabolomics Workbench REST API
+
+## Base URL
+```
+https://www.metabolomicsworkbench.org/rest/
+```
+
+## Auth
+No API key required. Fully public.
+
+## URL Structure
+```
+/rest/{context}/{input_item}/{input_value}/{output_item}
+```
+
+Contexts: `study`, `compound`, `refmet`, `gene`, `protein`, `moverz`, `exactmass`
+
+## Key Endpoints
+
+### Study Context
+| URL Pattern | Description |
+|---|---|
+| `/rest/study/study_id/{ST_ID}/summary` | Study summary metadata |
+| `/rest/study/study_id/{ST_ID}/metabolites` | Metabolites in a study |
+| `/rest/study/study_id/{ST_ID}/analysis` | Analysis details |
+| `/rest/study/study_id/{ST_ID}/factors` | Experimental factors |
+| `/rest/study/study_id/{ST_ID}/data` | Named metabolite data matrix |
+| `/rest/study/study_id/{ST_ID}/species` | Species information |
+| `/rest/study/study_id/{ST_ID}/disease` | Disease information |
+| `/rest/study/study_title/{keyword}/summary` | Search studies by title keyword |
+| `/rest/study/study_type/{type}/summary` | Search by study type |
+| `/rest/study/analysis_id/{AN_ID}/summary` | Summary by analysis ID |
+
+Study IDs: `ST######` (e.g., `ST000001`). Analysis IDs: `AN######`.
+
+### Compound Context
+| URL Pattern | Description |
+|---|---|
+| `/rest/compound/name/{NAME}/summary` | Search compound by name |
+| `/rest/compound/pubchem_cid/{CID}/summary` | Search by PubChem CID |
+| `/rest/compound/hmdb_id/{HMDB_ID}/summary` | Search by HMDB ID |
+| `/rest/compound/kegg_id/{KEGG_ID}/summary` | Search by KEGG ID |
+| `/rest/compound/inchi_key/{KEY}/summary` | Search by InChI key |
+| `/rest/compound/regno/{REGNO}/classification` | Compound classification |
+| `/rest/compound/regno/{REGNO}/molfile` | MOL file (structure) |
+
+### RefMet (Standardized Nomenclature)
+| URL Pattern | Description |
+|---|---|
+| `/rest/refmet/name/{NAME}/all` | Full RefMet record |
+| `/rest/refmet/match/{NAME}/name` | Match name to standardized RefMet name |
+
+### Gene / Protein Context
+| URL Pattern | Description |
+|---|---|
+| `/rest/gene/gene_symbol/{SYMBOL}/all` | Gene info by symbol |
+| `/rest/gene/gene_id/{ID}/all` | Gene info by Entrez ID |
+| `/rest/protein/uniprot_id/{ID}/all` | Protein by UniProt ID |
+
+### Mass Search (MoverZ / ExactMass)
+```
+/rest/moverz/mz/{MZ_VALUE}/tol/{TOLERANCE}/mode/{pos|neg}
+/rest/exactmass/mass/{MASS_VALUE}/tol/{TOLERANCE}
+```
+
+## Example Calls
+
+```
+# Study summary
+https://www.metabolomicsworkbench.org/rest/study/study_id/ST000001/summary
+
+# Metabolites in a study
+https://www.metabolomicsworkbench.org/rest/study/study_id/ST000001/metabolites
+
+# Search studies by title
+https://www.metabolomicsworkbench.org/rest/study/study_title/diabetes/summary
+
+# Compound by name
+https://www.metabolomicsworkbench.org/rest/compound/name/glucose/summary
+
+# Compound by PubChem CID
+https://www.metabolomicsworkbench.org/rest/compound/pubchem_cid/5793/summary
+
+# RefMet standardized name match
+https://www.metabolomicsworkbench.org/rest/refmet/match/alpha-D-Glucose/name
+
+# m/z search in positive mode
+https://www.metabolomicsworkbench.org/rest/moverz/mz/175.0354/tol/0.005/mode/pos
+
+# Exact mass search
+https://www.metabolomicsworkbench.org/rest/exactmass/mass/174.0282/tol/0.005
+```
+
+## Response Format
+Default is JSON. `mwtab` output returns MWTab text. `molfile` returns MOL/SDF text. No pagination — full results returned.
+
+## Rate Limits
+No published limits. Be reasonable. Add 0.5-1s delay for batch calls.

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

@@ -0,0 +1,46 @@
+# Monarch Initiative API
+
+## Base URL
+```
+https://api.monarchinitiative.org/v3/api
+```
+
+## Auth
+No API key required.
+
+## Key Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/search?q={query}` | Text search across all entities |
+| `/autocomplete?q={prefix}` | Autocomplete entity names |
+| `/entity/{id}` | Entity details (gene, disease, phenotype) |
+| `/entity/{id}/associations` | Associations for an entity |
+| `/entity/{id}/associations?category={cat}` | Filtered associations |
+
+## Entity ID Prefixes
+- `MONDO:` — diseases (e.g. `MONDO:0007947`)
+- `HP:` — phenotypes (e.g. `HP:0001250`)
+- `HGNC:` — genes (e.g. `HGNC:3603`)
+- `NCBIGene:` — genes (e.g. `NCBIGene:7157`)
+
+## Association Categories
+`biolink:GeneToPhenotypicFeatureAssociation`, `biolink:DiseaseToPhenotypicFeatureAssociation`, `biolink:GeneToDiseaseAssociation`
+
+## Example Calls
+```
+# Search for Marfan syndrome
+https://api.monarchinitiative.org/v3/api/search?q=Marfan+syndrome&limit=5
+
+# Entity details for a disease
+https://api.monarchinitiative.org/v3/api/entity/MONDO:0007947
+
+# Gene-to-phenotype for FBN1
+https://api.monarchinitiative.org/v3/api/entity/HGNC:3603/associations?category=biolink:GeneToPhenotypicFeatureAssociation&limit=10
+```
+
+## Response Format
+JSON. Search: `items[]` with `id`, `name`, `category`. Associations: `items[]` with `subject`, `predicate`, `object`, `publications`.
+
+## Rate Limits
+No published limits. Be reasonable.

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

@@ -0,0 +1,40 @@
+# MouseMine (Mouse Genome Informatics, InterMine-based)
+
+## Base URL
+```
+https://www.mousemine.org/mousemine/service
+```
+
+## Auth
+No auth for most queries. Free account token needed for saved lists.
+
+## Key Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/search?q={query}&format=json` | Keyword search across all objects |
+| `/template/results?name={template}&op1=LOOKUP&value1={value}&format=json` | Run pre-built template query |
+| `/query/results` (POST) | Run custom PathQuery (XML) |
+| `/model` | Retrieve data model |
+
+## Example Calls
+```
+# Keyword search for Brca1
+https://www.mousemine.org/mousemine/service/search?q=Brca1&format=json
+
+# Template: Gene → GO terms
+https://www.mousemine.org/mousemine/service/template/results?name=Gene_GO&op1=LOOKUP&value1=Pax6&format=json
+```
+
+## Custom Query (POST)
+```
+POST /query/results
+Content-Type: application/x-www-form-urlencoded
+query=<query model="genomic" view="Gene.symbol Gene.name" sortOrder="Gene.symbol asc"><constraint path="Gene.organism.name" op="=" value="Mus musculus"/></query>&format=json
+```
+
+## Response Format
+JSON: `{"results": [...], "statusCode": 200}`. Also supports XML, TSV, CSV via `format` param.
+
+## Rate Limits
+No published limits. Be reasonable.

package/skills/scientific/database-lookup/references/nasa-exoplanet-archive.md

@@ -0,0 +1,112 @@
+# NASA Exoplanet Archive API
+
+## Base URL
+
+```
+https://exoplanetarchive.ipac.caltech.edu
+```
+
+## Authentication
+
+No API key required. All endpoints are public.
+
+## Key Endpoints
+
+### 1. TAP Service (recommended — current method)
+
+```
+GET /TAP/sync?query={ADQL}&format={format}
+```
+
+| Parameter | Type   | Description |
+|-----------|--------|-------------|
+| `query`   | string | **Required.** ADQL query. |
+| `format`  | string | `json`, `csv`, `votable`, `tsv`, `ipac`. Default: `votable`. |
+
+**Example — confirmed planets with key parameters:**
+```
+https://exoplanetarchive.ipac.caltech.edu/TAP/sync?query=SELECT pl_name,hostname,sy_dist,pl_orbper,pl_rade,pl_bmasse,disc_year,discoverymethod FROM ps WHERE default_flag=1 ORDER BY disc_year DESC&format=json
+```
+
+**Example — planets in habitable zone (rough estimate):**
+```
+https://exoplanetarchive.ipac.caltech.edu/TAP/sync?query=SELECT TOP 50 pl_name,hostname,pl_orbsmax,st_teff,pl_rade FROM ps WHERE default_flag=1 AND pl_orbsmax BETWEEN 0.8 AND 1.5 AND st_teff BETWEEN 4000 AND 7000&format=json
+```
+
+**Example — planets discovered by TESS:**
+```
+https://exoplanetarchive.ipac.caltech.edu/TAP/sync?query=SELECT pl_name,pl_rade,pl_orbper,disc_year FROM ps WHERE default_flag=1 AND disc_facility='Transiting Exoplanet Survey Satellite (TESS)'&format=json
+```
+
+**Example — count planets by discovery method:**
+```
+https://exoplanetarchive.ipac.caltech.edu/TAP/sync?query=SELECT discoverymethod, COUNT(*) as cnt FROM ps WHERE default_flag=1 GROUP BY discoverymethod ORDER BY cnt DESC&format=json
+```
+
+### 2. Legacy API (older, still functional)
+
+```
+GET /cgi-bin/nstedAPI/nph-nstedAPI?table={table}&format={format}&where={conditions}&select={columns}
+```
+
+**Example:**
+```
+https://exoplanetarchive.ipac.caltech.edu/cgi-bin/nstedAPI/nph-nstedAPI?table=ps&select=pl_name,pl_orbper,pl_rade&where=disc_year=2023&format=json
+```
+
+Note: The legacy API is deprecated in favor of TAP. Use TAP for new applications.
+
+## Key TAP Tables
+
+| Table  | Description |
+|--------|-------------|
+| `ps`   | **Planetary Systems** — one row per reference per planet. Use `default_flag=1` for the default/best parameter set. |
+| `pscomppars` | **Planetary Systems Composite Parameters** — one row per planet with best-fit values from multiple references. |
+| `stellarhosts` | Stellar properties of host stars. |
+| `td`   | Time-series data (transit curves, RV curves). |
+| `keplernames` | Kepler Object of Interest cross-references. |
+| `k2names` | K2 campaign cross-references. |
+| `toi`  | TESS Objects of Interest. |
+
+## Key Columns (ps table)
+
+| Column           | Description |
+|------------------|-------------|
+| `pl_name`        | Planet name (e.g., "Kepler-22 b"). |
+| `hostname`       | Host star name. |
+| `default_flag`   | 1 = default parameter set for this planet. |
+| `disc_year`      | Discovery year. |
+| `discoverymethod` | `Transit`, `Radial Velocity`, `Imaging`, `Microlensing`, etc. |
+| `pl_orbper`      | Orbital period (days). |
+| `pl_orbsmax`     | Semi-major axis (AU). |
+| `pl_rade`        | Planet radius (Earth radii). |
+| `pl_bmasse`      | Planet mass (Earth masses). |
+| `pl_eqt`         | Equilibrium temperature (K). |
+| `sy_dist`        | Distance to system (parsecs). |
+| `st_teff`        | Stellar effective temperature (K). |
+| `st_rad`         | Stellar radius (solar radii). |
+| `st_mass`        | Stellar mass (solar masses). |
+| `disc_facility`  | Discovery facility name. |
+
+## Response Format (TAP JSON)
+
+```json
+{
+  "metadata": [
+    {"name": "pl_name", "datatype": "char"},
+    {"name": "pl_orbper", "datatype": "double"}
+  ],
+  "data": [
+    ["Kepler-22 b", 289.8623]
+  ]
+}
+```
+
+## Rate Limits
+
+No API key or authentication required. No formal rate limits documented, but the archive requests that users avoid excessive automated queries. Large result sets may cause timeouts; use `TOP N` in ADQL or paginate with `OFFSET` and `MAXREC`.
+
+For very large downloads, use the bulk download interface at:
+```
+https://exoplanetarchive.ipac.caltech.edu/cgi-bin/TblView/nph-tblView?app=ExoTbls&config=PS
+```