wotann 0.5.0 → 0.5.39

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

@@ -0,0 +1,121 @@
+# RCSB Protein Data Bank (PDB) API Reference
+
+## Base URLs
+- **Data API**: `https://data.rcsb.org/rest/v1`
+- **Search API**: `https://search.rcsb.org/rcsbsearch/v2/query`
+- **GraphQL**: `https://data.rcsb.org/graphql`
+- **Files**: `https://files.rcsb.org`
+
+## Authentication
+None required. Fully public API.
+
+## Rate Limits
+No published hard limits; be courteous (a few requests/second). Bulk downloads available via FTP.
+
+## Key Endpoints
+
+### 1. Entry Lookup (Data API)
+```
+GET https://data.rcsb.org/rest/v1/core/entry/{entry_id}
+```
+Example:
+```
+GET https://data.rcsb.org/rest/v1/core/entry/4HHB
+```
+Returns JSON with resolution, method, deposition date, title, authors, etc.
+
+### 2. Polymer Entity (chain-level info)
+```
+GET https://data.rcsb.org/rest/v1/core/polymer_entity/{entry_id}/{entity_id}
+```
+Example:
+```
+GET https://data.rcsb.org/rest/v1/core/polymer_entity/4HHB/1
+```
+
+### 3. Assembly Info
+```
+GET https://data.rcsb.org/rest/v1/core/assembly/{entry_id}/{assembly_id}
+```
+
+### 4. Full-Text and Attribute Search (Search API)
+```
+POST https://search.rcsb.org/rcsbsearch/v2/query
+Content-Type: application/json
+```
+Example — search by UniProt accession:
+```json
+{
+  "query": {
+    "type": "terminal",
+    "service": "text",
+    "parameters": {
+      "attribute": "rcsb_polymer_entity_container_identifiers.reference_sequence_identifiers.database_accession",
+      "operator": "exact_match",
+      "value": "P69905"
+    }
+  },
+  "return_type": "entry"
+}
+```
+
+### 5. Sequence Search (Search API)
+```json
+{
+  "query": {
+    "type": "terminal",
+    "service": "sequence",
+    "parameters": {
+      "evalue_cutoff": 0.1,
+      "identity_cutoff": 0.9,
+      "sequence_type": "protein",
+      "value": "MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSH"
+    }
+  },
+  "return_type": "polymer_entity"
+}
+```
+
+### 6. Structure Similarity Search
+```json
+{
+  "query": {
+    "type": "terminal",
+    "service": "structure",
+    "parameters": {
+      "value": {"entry_id": "4HHB", "assembly_id": "1"},
+      "operator": "strict_shape_match"
+    }
+  },
+  "return_type": "assembly"
+}
+```
+
+### 7. Download Structure Files
+```
+GET https://files.rcsb.org/download/{entry_id}.cif
+GET https://files.rcsb.org/download/{entry_id}.pdb
+```
+
+### 8. GraphQL Query
+```
+POST https://data.rcsb.org/graphql
+```
+Body example:
+```json
+{
+  "query": "{ entry(entry_id: \"4HHB\") { rcsb_entry_info { resolution_combined } struct { title } } }"
+}
+```
+
+## Response Format
+All REST/Search endpoints return JSON. File downloads return PDB/mmCIF text.
+
+## Useful `return_type` Values for Search
+- `entry` — PDB IDs
+- `polymer_entity` — entity-level results (e.g., 4HHB_1)
+- `assembly` — biological assembly results
+
+## Notes
+- Search API uses POST with a JSON query DSL. Combine queries with `"type": "group"` and `"logical_operator": "and"/"or"`.
+- Pagination via `"request_options": {"paginate": {"start": 0, "rows": 25}}`.

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

@@ -0,0 +1,74 @@
+# PRIDE Archive REST API Reference
+
+## Overview
+PRIDE (PRoteomics IDEntifications Database) at EMBL-EBI provides a full public REST API for querying proteomics datasets, proteins, peptides, and spectra.
+
+## Base URL
+```
+https://www.ebi.ac.uk/pride/ws/archive/v2
+```
+(Legacy v1 also exists but v2 is current)
+
+## Authentication
+- **No authentication required** for read access
+- Open and free to use
+
+## Key Endpoints
+
+| Endpoint | Description |
+|---|---|
+| `GET /projects` | Search/list proteomics projects |
+| `GET /projects/{accession}` | Get a specific project by PXD accession |
+| `GET /projects/{accession}/files` | List files for a project |
+| `GET /spectra` | Search spectra |
+| `GET /peptideevidences` | Search peptide evidences |
+| `GET /proteinevidences` | Search protein evidences |
+| `GET /stats` | Database statistics |
+
+## Query Parameters
+- `keyword` — free-text search
+- `filter` — field-specific filters (e.g., species, instrument, modification)
+- `pageSize` — results per page (default 10, max 100)
+- `page` — page number (0-indexed)
+- `sortDirection` — ASC or DESC
+- `sortFields` — field to sort by
+
+## Example Calls
+
+```bash
+# Search projects by keyword
+curl "https://www.ebi.ac.uk/pride/ws/archive/v2/projects?keyword=alzheimer&pageSize=5"
+
+# Get a specific project
+curl "https://www.ebi.ac.uk/pride/ws/archive/v2/projects/PXD010000"
+
+# List files for a project
+curl "https://www.ebi.ac.uk/pride/ws/archive/v2/projects/PXD010000/files?pageSize=10"
+
+# Search by species (human = 9606)
+curl "https://www.ebi.ac.uk/pride/ws/archive/v2/projects?filter=organisms_facet==9606&pageSize=5"
+
+# Get database statistics
+curl "https://www.ebi.ac.uk/pride/ws/archive/v2/stats"
+```
+
+## Response Format
+JSON. Example (project):
+```json
+{
+  "accession": "PXD010000",
+  "title": "Project title here",
+  "projectDescription": "...",
+  "organisms": [{"accession": "9606", "name": "Homo sapiens"}],
+  "instruments": [{"name": "Q Exactive"}],
+  "submissionDate": "2018-05-01",
+  "publicationDate": "2018-09-01",
+  "numAssays": 12,
+  "references": [{"pubmedId": 12345678}]
+}
+```
+
+## Rate Limits
+- No strict published rate limits, but standard EBI fair-use policies apply
+- Recommended: limit to a few requests per second
+- Bulk data available via FTP/Aspera at ftp.pride.ebi.ac.uk

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

@@ -0,0 +1,145 @@
+# PubChem PUG REST API
+
+## Base URL
+
+```
+https://pubchem.ncbi.nlm.nih.gov/rest/pug
+```
+
+## URL Pattern
+
+```
+/{domain}/{namespace}/{identifiers}/{operation}/{output}
+```
+
+- **domain**: `compound`, `substance`, `assay`
+- **namespace**: `cid`, `name`, `smiles`, `inchi`, `inchikey`, `fastformula`
+- **operation**: `record`, `property`, `synonyms`, `description`, `cids`, `xrefs`
+- **output**: `JSON`, `XML`, `CSV`, `TXT`, `SDF`, `PNG`
+
+## Key Endpoints
+
+### Search by name
+```
+GET /compound/name/{name}/JSON
+```
+Example: `/compound/name/aspirin/JSON`
+
+### Search by CID
+```
+GET /compound/cid/{cid}/JSON
+```
+Example: `/compound/cid/2244/JSON`
+
+Multiple CIDs: `/compound/cid/2244,5988,3672/JSON`
+
+### Search by SMILES
+```
+GET /compound/smiles/{smiles}/JSON
+```
+For SMILES with special characters, use POST:
+```
+POST /compound/smiles/JSON
+Content-Type: application/x-www-form-urlencoded
+smiles=CC(=O)OC1=CC=CC=C1C(=O)O
+```
+
+### Search by InChIKey
+```
+GET /compound/inchikey/{inchikey}/JSON
+```
+
+### Search by InChI (POST only — InChI strings are too long for URLs)
+```
+POST /compound/inchi/JSON
+Content-Type: application/x-www-form-urlencoded
+inchi=InChI=1S/C9H8O4/...
+```
+
+### Search by molecular formula
+```
+GET /compound/fastformula/{formula}/JSON
+```
+Example: `/compound/fastformula/C9H8O4/JSON`
+
+### Property retrieval
+```
+GET /compound/{namespace}/{id}/property/{property_list}/JSON
+```
+Properties are comma-separated. Available properties:
+
+`MolecularFormula`, `MolecularWeight`, `CanonicalSMILES`, `IsomericSMILES`, `InChI`, `InChIKey`, `IUPACName`, `XLogP`, `ExactMass`, `MonoisotopicMass`, `TPSA`, `Complexity`, `Charge`, `HBondDonorCount`, `HBondAcceptorCount`, `RotatableBondCount`, `HeavyAtomCount`, `CID`
+
+Example:
+```
+/compound/cid/2244/property/MolecularFormula,MolecularWeight,CanonicalSMILES,IUPACName/JSON
+```
+
+Response:
+```json
+{
+  "PropertyTable": {
+    "Properties": [
+      {
+        "CID": 2244,
+        "MolecularFormula": "C9H8O4",
+        "MolecularWeight": 180.16,
+        "IUPACName": "2-acetyloxybenzoic acid",
+        "CanonicalSMILES": "CC(=O)OC1=CC=CC=C1C(O)=O"
+      }
+    ]
+  }
+}
+```
+
+### Synonym lookup
+```
+GET /compound/{namespace}/{id}/synonyms/JSON
+```
+
+### Compound description
+```
+GET /compound/cid/{cid}/description/JSON
+```
+
+### Get just CIDs from a name
+```
+GET /compound/name/{name}/cids/JSON
+```
+
+### Cross-references (patents, registry IDs)
+```
+GET /compound/cid/{cid}/xrefs/PatentID/JSON
+GET /compound/cid/{cid}/xrefs/RegistryID/JSON
+```
+
+### Similarity search (POST, returns listkey for async retrieval)
+```
+POST /compound/fastsimilarity_2d/smiles/cids/JSON
+smiles=CC(=O)OC1=CC=CC=C1C(=O)O&Threshold=90
+```
+
+### 2D structure image
+```
+GET /compound/cid/{cid}/PNG
+GET /compound/cid/{cid}/PNG?image_size=300x300
+```
+
+## Rate Limits
+
+- Max **5 requests per second**
+- Max **400 requests per minute**
+- Batch CIDs with commas (up to 100 per GET, ~10,000 per POST)
+- Throttle error returns `PUGREST.ServerBusy` fault code
+
+## Error Format
+
+```json
+{
+  "Fault": {
+    "Code": "PUGREST.NotFound",
+    "Message": "No CID found",
+    "Details": ["..."]
+  }
+}
+```

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

@@ -0,0 +1,45 @@
+# QuickGO (EBI GO Annotation Browser)
+
+## Base URL
+```
+https://www.ebi.ac.uk/QuickGO/services/
+```
+
+## Auth
+No auth required.
+
+## Key Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/ontology/go/terms/{goId}` | GO term details |
+| `/ontology/go/terms/{goId}/children` | Child terms |
+| `/ontology/go/terms/{goId}/ancestors` | Ancestor terms |
+| `/ontology/go/search?query={term}` | Search GO terms by keyword |
+| `/annotation/search` | Search annotations by gene/taxon/GO term |
+
+## Annotation Search Parameters
+- `goId` — GO term (e.g. GO:0003723)
+- `taxonId` — NCBI taxonomy (e.g. 9606 for human)
+- `geneProductId` — UniProt accession
+- `evidence` — evidence code (e.g. ECO:0000269)
+- `aspect` — biological_process, molecular_function, cellular_component
+- `limit`, `page` — pagination
+
+## Example Calls
+```
+# GO term details
+https://www.ebi.ac.uk/QuickGO/services/ontology/go/terms/GO:0003723
+
+# Human annotations for RNA binding
+https://www.ebi.ac.uk/QuickGO/services/annotation/search?goId=GO:0003723&taxonId=9606&limit=10
+
+# Search terms by keyword
+https://www.ebi.ac.uk/QuickGO/services/ontology/go/search?query=apoptosis&limit=5
+```
+
+## Response Format
+JSON. Annotations: paginated results with gene product, GO term, evidence, qualifier.
+
+## Rate Limits
+EBI fair-use policy. Use download endpoint for large result sets.

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

@@ -0,0 +1,140 @@
+# Reactome Content Service REST API
+
+## Base URL
+
+```
+https://reactome.org/ContentService
+```
+
+No authentication required. JSON by default.
+
+## Key Endpoints
+
+### Search (full-text across pathways, reactions, proteins)
+
+```
+GET /search/query?query={term}
+```
+
+Parameters:
+- `query` (required) — search term (e.g. "apoptosis", "TP53", "R-HSA-109581")
+- `species` — filter by species (e.g. "Homo sapiens")
+- `types` — filter by type: `Pathway`, `Reaction`, `Protein`, `Complex`, `SmallMolecule`
+- `cluster` — boolean, cluster results (default true)
+- `rows` — page size
+- `Start row` — offset for pagination
+
+Example:
+```
+/search/query?query=apoptosis&species=Homo+sapiens&types=Pathway
+```
+
+Response:
+```json
+{
+  "results": [
+    {
+      "typeName": "Pathway",
+      "rows": [
+        {
+          "dbId": 109581,
+          "stId": "R-HSA-109581",
+          "name": "Apoptosis",
+          "species": ["Homo sapiens"],
+          "summation": ["..."]
+        }
+      ]
+    }
+  ],
+  "found": 42
+}
+```
+
+### Autocomplete
+```
+GET /search/suggest?query={partial_term}
+```
+
+### Top-level pathways for a species
+```
+GET /data/pathways/top/{species}
+```
+Example: `/data/pathways/top/Homo+sapiens`
+
+### Pathway details
+```
+GET /data/query/{id}
+```
+Where `{id}` is a stable ID like `R-HSA-109581` or a numeric dbId.
+
+### Events contained in a pathway
+```
+GET /data/pathway/{id}/containedEvents
+```
+
+### Participants of a reaction
+```
+GET /data/event/{id}/participants
+```
+
+### Ancestors of an event
+```
+GET /data/event/{id}/ancestors
+```
+
+### Map external ID to pathways (e.g. UniProt to Reactome pathways)
+```
+GET /data/mapping/{resource}/{id}/pathways
+```
+Example — find pathways for TP53 (UniProt P04637):
+```
+/data/mapping/UniProt/P04637/pathways
+```
+
+### Map external ID to reactions
+```
+GET /data/mapping/{resource}/{id}/reactions
+```
+
+### Generic entity lookup
+```
+GET /data/query/{id}
+```
+
+### Reference entities for an event
+```
+GET /data/participants/{id}/referenceEntities
+```
+
+### All species
+```
+GET /data/species/all
+```
+
+### Event hierarchy for a species (large response)
+```
+GET /data/eventsHierarchy/{species}
+```
+
+## Stable ID Format
+
+`R-{species_code}-{number}`
+
+| Code | Species |
+|---|---|
+| HSA | Homo sapiens |
+| MMU | Mus musculus |
+| RNO | Rattus norvegicus |
+| DME | Drosophila melanogaster |
+| CEL | C. elegans |
+| SCE | S. cerevisiae |
+
+## External Resource Names for Mapping
+
+`UniProt`, `ChEBI`, `ENSEMBL`, `miRBase`, `GeneCards`, `NCBI`
+
+Multiple values for same parameter: repeat the parameter (e.g. `types=Pathway&types=Reaction`).
+
+## Rate Limits
+
+No API key required. No formal rate limit published, but be reasonable — avoid hundreds of concurrent requests. For bulk data, use Reactome's downloadable dumps (MySQL, Neo4j, BioPAX, SBML).

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

@@ -0,0 +1,32 @@
+# RummaGEO (GEO Gene Set Enrichment Search)
+
+## Base URL
+```
+https://rummageo.com/
+```
+
+## Auth
+No auth required.
+
+## Key Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/enrich` | POST | Submit gene set for enrichment against GEO signatures |
+| `/api/table` | GET | Paginated table of indexed GEO signatures |
+
+## Example Call
+```bash
+curl -X POST "https://rummageo.com/api/enrich" \
+  -H "Content-Type: application/json" \
+  -d '{"genes": ["BRCA1","TP53","EGFR","MYC","PTEN"]}'
+```
+
+## Response Format
+JSON. Ranked list of matching GEO signatures with overlap stats, p-values, source study links.
+
+## Note
+POST endpoint — use `curl` via shell, not WebFetch.
+
+## Rate Limits
+No published limits. Designed for interactive/programmatic use.

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

@@ -0,0 +1,130 @@
+# SDSS SkyServer API
+
+## Base URL
+
+```
+https://skyserver.sdss.org/dr18/SkyServerWS
+```
+
+Replace `dr18` with the desired data release (e.g., `dr17`, `dr16`).
+
+## Authentication
+
+No API key required. All endpoints are public.
+
+## Key Endpoints
+
+### 1. SQL Search (CasJobs-style free-form SQL)
+
+```
+GET /SearchTools/SqlSearch
+```
+
+| Parameter | Type   | Description |
+|-----------|--------|-------------|
+| `cmd`     | string | **Required.** SQL query against SDSS CasJobs schema. |
+| `format`  | string | `json`, `xml`, `csv`, `html`, `votable`. Default: `html`. |
+
+**Example — query 10 galaxies:**
+```
+https://skyserver.sdss.org/dr18/SkyServerWS/SearchTools/SqlSearch?cmd=SELECT TOP 10 objid,ra,dec,u,g,r,i,z FROM PhotoObj WHERE type=3&format=json
+```
+
+Type codes: `3` = galaxy, `6` = star.
+
+**Response (JSON):**
+```json
+[
+  {"Rows": [
+    {"objid": 1237645941825863680, "ra": 195.123, "dec": 2.456, "u": 22.1, "g": 20.8, "r": 19.5, "i": 19.1, "z": 18.9}
+  ]}
+]
+```
+
+### 2. Radial Search
+
+```
+GET /SearchTools/RadialSearch
+```
+
+| Parameter    | Type   | Description |
+|--------------|--------|-------------|
+| `ra`         | float  | **Required.** Right ascension (degrees). |
+| `dec`        | float  | **Required.** Declination (degrees). |
+| `radius`     | float  | Search radius in arcminutes. Default: 1. |
+| `format`     | string | `json`, `xml`, `csv`. |
+| `limit`      | int    | Max results. |
+| `objtype`    | string | Filter: `star`, `galaxy`, or blank for all. |
+
+**Example — objects within 2 arcmin of RA=180, Dec=+0.5:**
+```
+https://skyserver.sdss.org/dr18/SkyServerWS/SearchTools/RadialSearch?ra=180&dec=0.5&radius=2&format=json&limit=10
+```
+
+### 3. Rectangular Search
+
+```
+GET /SearchTools/RectangularSearch
+```
+
+| Parameter | Type   | Description |
+|-----------|--------|-------------|
+| `min_ra`  | float  | Minimum RA (degrees). |
+| `max_ra`  | float  | Maximum RA (degrees). |
+| `min_dec` | float  | Minimum Dec (degrees). |
+| `max_dec` | float  | Maximum Dec (degrees). |
+| `format`  | string | `json`, `xml`, `csv`. |
+| `limit`   | int    | Max results. |
+
+### 4. Object Lookup by ObjID
+
+```
+GET /SearchTools/SqlSearch?cmd=SELECT * FROM PhotoObj WHERE objid={objid}&format=json
+```
+
+### 5. Spectra Search by Plate-MJD-Fiber
+
+```
+GET /SearchTools/SqlSearch?cmd=SELECT * FROM SpecObj WHERE plate={plate} AND mjd={mjd} AND fiberid={fiberid}&format=json
+```
+
+### 6. Image Cutout Service
+
+```
+GET /ImgCutout/getjpeg
+```
+
+| Parameter | Type   | Description |
+|-----------|--------|-------------|
+| `ra`      | float  | **Required.** RA (degrees). |
+| `dec`     | float  | **Required.** Dec (degrees). |
+| `scale`   | float  | Arcsec/pixel. Default: 0.396127. |
+| `width`   | int    | Image width in pixels. Default: 512. |
+| `height`  | int    | Image height in pixels. Default: 512. |
+
+**Example:**
+```
+https://skyserver.sdss.org/dr18/SkyServerWS/ImgCutout/getjpeg?ra=180.0&dec=0.5&scale=0.4&width=256&height=256
+```
+
+Returns JPEG image data.
+
+### 7. Spectrum Plot/Data
+
+Spectrum FITS files can be retrieved from the Science Archive Server:
+```
+https://data.sdss.org/sas/dr18/spectro/sdss/redux/{run2d}/spectra/{plate}/spec-{plate}-{mjd}-{fiberid}.fits
+```
+
+## Important SQL Tables
+
+| Table       | Description |
+|-------------|-------------|
+| `PhotoObj`  | Photometric measurements (positions, magnitudes). |
+| `SpecObj`   | Spectroscopic measurements (redshifts, classifications). |
+| `Galaxy`    | View of PhotoObj filtered to galaxies. |
+| `Star`      | View of PhotoObj filtered to stars. |
+
+## Rate Limits
+
+No formal documented rate limits. Queries returning very large result sets may time out. Use `TOP N` in SQL queries to limit results. For bulk data, use CasJobs (https://skyserver.sdss.org/CasJobs/) with a free account.