wotann 0.5.0 → 0.5.39

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

@@ -0,0 +1,121 @@
+# NASA APIs
+
+## Base URL
+
+```
+https://api.nasa.gov
+```
+
+## Authentication
+
+All endpoints require an API key passed as `api_key` query parameter.
+- Get a free key at: https://api.nasa.gov/#signUp
+- Demo key: `DEMO_KEY` (rate-limited: 30 req/hour, 50 req/day per IP)
+- Registered keys: 1,000 req/hour
+
+## Key Endpoints
+
+### 1. APOD (Astronomy Picture of the Day)
+
+```
+GET /planetary/apod
+```
+
+**Parameters:**
+
+| Parameter  | Type   | Description |
+|------------|--------|-------------|
+| `api_key`  | string | **Required.** API key. |
+| `date`     | string | YYYY-MM-DD. Default: today. |
+| `start_date` | string | Start of date range (YYYY-MM-DD). |
+| `end_date` | string | End of date range (YYYY-MM-DD). |
+| `count`    | int    | Return N random images (cannot combine with date/range). |
+| `thumbs`   | bool   | Return thumbnail URL for video entries. |
+
+**Example:**
+```
+https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY&date=2024-01-15
+```
+
+**Response (JSON):**
+```json
+{
+  "date": "2024-01-15",
+  "title": "...",
+  "explanation": "...",
+  "url": "https://apod.nasa.gov/apod/image/...",
+  "hdurl": "https://apod.nasa.gov/apod/image/...",
+  "media_type": "image",
+  "copyright": "..."
+}
+```
+
+### 2. NEO — Near Earth Objects (Asteroids NeoWs)
+
+```
+GET /neo/rest/v1/feed
+```
+
+**Parameters:**
+
+| Parameter    | Type   | Description |
+|--------------|--------|-------------|
+| `api_key`    | string | **Required.** |
+| `start_date` | string | YYYY-MM-DD. Default: today. |
+| `end_date`   | string | YYYY-MM-DD. Max 7 days from start. |
+
+**Example:**
+```
+https://api.nasa.gov/neo/rest/v1/feed?start_date=2024-01-01&end_date=2024-01-03&api_key=DEMO_KEY
+```
+
+**Lookup by asteroid ID:**
+```
+GET /neo/rest/v1/neo/{asteroid_id}?api_key=DEMO_KEY
+```
+
+**Browse all:**
+```
+GET /neo/rest/v1/neo/browse?api_key=DEMO_KEY
+```
+
+**Response structure:** `near_earth_objects` keyed by date, each containing array of objects with `name`, `nasa_jpl_url`, `estimated_diameter`, `close_approach_data`, `is_potentially_hazardous_asteroid`.
+
+### 3. Mars Rover Photos
+
+```
+GET /mars-photos/api/v1/rovers/{rover}/photos
+```
+
+Rovers: `curiosity`, `opportunity`, `spirit`, `perseverance`
+
+**Parameters:**
+
+| Parameter | Type   | Description |
+|-----------|--------|-------------|
+| `api_key` | string | **Required.** |
+| `sol`     | int    | Martian sol (day). Use `sol` OR `earth_date`, not both. |
+| `earth_date` | string | YYYY-MM-DD. |
+| `camera`  | string | Filter by camera: `FHAZ`, `RHAZ`, `MAST`, `CHEMCAM`, `NAVCAM`, etc. |
+| `page`    | int    | 25 results per page. |
+
+**Example:**
+```
+https://api.nasa.gov/mars-photos/api/v1/rovers/curiosity/photos?sol=1000&camera=NAVCAM&api_key=DEMO_KEY
+```
+
+**Rover manifest (mission metadata):**
+```
+GET /mars-photos/api/v1/manifests/{rover}?api_key=DEMO_KEY
+```
+
+**Response:** Array of `photos`, each with `id`, `sol`, `camera` (with `full_name`), `img_src`, `earth_date`, `rover`.
+
+## Rate Limits
+
+| Key Type   | Hourly Limit | Daily Limit |
+|------------|-------------|-------------|
+| `DEMO_KEY` | 30/hour     | 50/day      |
+| Registered | 1,000/hour  | Unlimited   |
+
+Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`.

package/skills/scientific/database-lookup/references/ncbi-gene.md

@@ -0,0 +1,64 @@
+# NCBI Gene (E-utilities)
+
+## Base URL
+```
+https://eutils.ncbi.nlm.nih.gov/entrez/eutils/
+```
+
+## Auth
+API key optional but recommended. Without key: 3 req/sec. With key: 10 req/sec.
+Free key from: https://www.ncbi.nlm.nih.gov/account/settings/
+Pass as: `&api_key=YOUR_KEY`
+
+## Key Endpoints
+
+### eSearch — Search for gene IDs
+```
+GET /esearch.fcgi?db=gene&term={query}&retmode=json&retmax={n}
+```
+
+Parameters:
+- `db=gene` (required)
+- `term` — search query (e.g. `BRCA1[gene]+AND+human[orgn]`)
+- `retmode=json`
+- `retmax` — max results (default 20)
+- `retstart` — pagination offset
+
+Example:
+```
+/esearch.fcgi?db=gene&term=BRCA1[gene]+AND+human[orgn]&retmode=json&retmax=5
+```
+
+### eSummary — Get gene metadata
+```
+GET /esummary.fcgi?db=gene&id={gene_ids}&retmode=json
+```
+
+Key response fields: `name`, `description`, `chromosome`, `maplocation`, `otheraliases`, `nomenclaturesymbol`, `organism`
+
+Example:
+```
+/esummary.fcgi?db=gene&id=672&retmode=json
+```
+
+### eFetch — Full gene records (XML/text only, no JSON)
+```
+GET /efetch.fcgi?db=gene&id={gene_ids}&rettype=gene_table&retmode=text
+```
+
+### eLink — Cross-database links (gene to pathways, PubMed, OMIM)
+```
+GET /elink.fcgi?dbfrom=gene&db={target_db}&id={gene_id}&retmode=json
+```
+
+Target databases: `biosystems` (pathways), `pubmed`, `omim`, `nuccore`, `protein`
+
+Example — gene to pathways:
+```
+/elink.fcgi?dbfrom=gene&db=biosystems&id=672&retmode=json
+```
+
+## Rate Limits
+- Without API key: 3 requests/second
+- With API key: 10 requests/second
+- For bulk: use `usehistory=y` with eSearch, then retrieve via `query_key` and `WebEnv`

package/skills/scientific/database-lookup/references/ncbi-protein.md

@@ -0,0 +1,104 @@
+# NCBI Protein API Reference
+
+## Overview
+Protein sequence records (RefSeq, GenBank, UniProt imports) accessible via NCBI E-utilities with `db=protein`.
+
+## Base URL
+```
+https://eutils.ncbi.nlm.nih.gov/entrez/eutils/
+```
+
+## Authentication
+- **API key** (recommended): Register at https://www.ncbi.nlm.nih.gov/account/ and append `&api_key=YOUR_KEY`.
+- Without key: 3 requests/second. With key: 10 requests/second.
+- Provide `tool` and `email` parameters for identification.
+
+## Key Endpoints
+
+### 1. ESearch -- Search protein records
+```
+GET esearch.fcgi?db=protein&term=QUERY&retmax=N&retmode=json
+```
+| Param | Description |
+|-------|-------------|
+| `term` | Search query (Entrez syntax). Fields: `[Protein Name]`, `[Organism]`, `[Accession]`, `[Gene Name]` |
+| `retmax` | Max IDs returned (default 20, max 100000) |
+| `retstart` | Offset for pagination |
+| `usehistory` | `y` to store results on server (use with large sets) |
+
+**Example -- search human insulin:**
+```
+GET esearch.fcgi?db=protein&term=insulin+AND+homo+sapiens[Organism]&retmax=5&retmode=json
+```
+Response (JSON):
+```json
+{
+  "esearchresult": {
+    "count": "1523",
+    "retmax": "5",
+    "idlist": ["116734704", "AAA59172.1", "NP_000198.1", ...],
+    "querytranslation": "insulin AND \"Homo sapiens\"[Organism]"
+  }
+}
+```
+
+### 2. EFetch -- Retrieve protein records
+```
+GET efetch.fcgi?db=protein&id=IDS&rettype=TYPE&retmode=MODE
+```
+| rettype | retmode | Output |
+|---------|---------|--------|
+| `fasta` | `text` | FASTA sequence |
+| `gp` | `text` | GenPept flat file |
+| `gp` | `xml` | GenPept XML (INSDSeq) |
+| `acc` | `text` | Accession list |
+| `seqid` | `text` | SeqID list |
+| `ft` | `text` | Feature table |
+
+**Example -- fetch FASTA for NP_000198.1 (human insulin):**
+```
+GET efetch.fcgi?db=protein&id=NP_000198.1&rettype=fasta&retmode=text
+```
+Response:
+```
+>NP_000198.1 insulin preproprotein [Homo sapiens]
+MALWMRLLPLLALLALWGPDPAAAFVNQHLCGSHLVEALYLVCGERGFFYTPKTRREAED
+LQVGQVELGGGPGAGSLQPLALEGSLQKRGIVEQCCTSICSLYQLENYCN
+```
+
+**Example -- fetch GenPept XML for multiple IDs:**
+```
+GET efetch.fcgi?db=protein&id=NP_000198.1,NP_001278826.1&rettype=gp&retmode=xml
+```
+
+### 3. ESummary -- Brief record summaries
+```
+GET esummary.fcgi?db=protein&id=IDS&retmode=json
+```
+Returns: accession, title, organism, length, taxonomy, create/update dates.
+
+### 4. ELink -- Find related records
+```
+GET elink.fcgi?dbfrom=protein&db=gene&id=NP_000198.1
+```
+Links protein to gene, nucleotide, structure, taxonomy, etc.
+
+## Common Search Patterns
+```
+# By accession
+term=NP_000198.1[Accession]
+
+# By gene name + organism
+term=BRCA1[Gene Name] AND human[Organism]
+
+# RefSeq only
+term=insulin AND srcdb_refseq[Properties]
+
+# By sequence length range
+term=100:500[Sequence Length] AND kinase[Protein Name]
+```
+
+## Rate Limits
+- Without API key: 3 requests/second
+- With API key: 10 requests/second
+- Large batch downloads: use `usehistory=y` with `WebEnv`/`query_key`, then fetch in chunks of 500

package/skills/scientific/database-lookup/references/ncbi-taxonomy.md

@@ -0,0 +1,121 @@
+# NCBI Taxonomy API Reference
+
+## Overview
+Taxonomic classification data (names, lineages, ranks) for all organisms in NCBI databases. Accessible via E-utilities with `db=taxonomy`.
+
+## Base URL
+```
+https://eutils.ncbi.nlm.nih.gov/entrez/eutils/
+```
+
+## Authentication
+- **API key** (recommended): Append `&api_key=YOUR_KEY` (register at ncbi.nlm.nih.gov/account).
+- Without key: 3 req/sec. With key: 10 req/sec.
+- Provide `tool` and `email` parameters.
+
+## Key Endpoints
+
+### 1. ESearch -- Search taxonomy by name
+```
+GET esearch.fcgi?db=taxonomy&term=QUERY&retmode=json
+```
+| Param | Description |
+|-------|-------------|
+| `term` | Organism name, common name, or taxid. Fields: `[Scientific Name]`, `[Common Name]`, `[All Names]`, `[Rank]` |
+| `retmax` | Max IDs returned (default 20) |
+
+**Example -- search by scientific name:**
+```
+GET esearch.fcgi?db=taxonomy&term=Homo+sapiens[Scientific Name]&retmode=json
+```
+Response:
+```json
+{
+  "esearchresult": {
+    "count": "1",
+    "idlist": ["9606"]
+  }
+}
+```
+
+**Example -- search by common name:**
+```
+GET esearch.fcgi?db=taxonomy&term=dog[Common Name]&retmode=json
+```
+
+### 2. EFetch -- Retrieve full taxonomy records
+```
+GET efetch.fcgi?db=taxonomy&id=TAXIDS&retmode=xml
+```
+Note: Taxonomy EFetch only supports XML output.
+
+**Example -- fetch human taxonomy (taxid 9606):**
+```
+GET efetch.fcgi?db=taxonomy&id=9606&retmode=xml
+```
+Response (abbreviated XML):
+```xml
+<TaxaSet>
+  <Taxon>
+    <TaxId>9606</TaxId>
+    <ScientificName>Homo sapiens</ScientificName>
+    <OtherNames>
+      <CommonName>human</CommonName>
+    </OtherNames>
+    <Rank>species</Rank>
+    <Division>Primates</Division>
+    <GeneticCode><GCId>1</GCId><GCName>Standard</GCName></GeneticCode>
+    <MitoGeneticCode><MGCId>2</MGCId><MGCName>Vertebrate Mitochondrial</MGCName></MitoGeneticCode>
+    <Lineage>cellular organisms; Eukaryota; Opisthokonta; Metazoa; ... ; Hominidae; Homo</Lineage>
+    <LineageEx>
+      <Taxon><TaxId>131567</TaxId><ScientificName>cellular organisms</ScientificName><Rank>no rank</Rank></Taxon>
+      <Taxon><TaxId>2759</TaxId><ScientificName>Eukaryota</ScientificName><Rank>superkingdom</Rank></Taxon>
+      <!-- ... each ancestor node ... -->
+    </LineageEx>
+  </Taxon>
+</TaxaSet>
+```
+
+### 3. ESummary -- Brief taxonomy summaries
+```
+GET esummary.fcgi?db=taxonomy&id=TAXIDS&retmode=json
+```
+**Example -- multiple taxa:**
+```
+GET esummary.fcgi?db=taxonomy&id=9606,10090,7227&retmode=json
+```
+Response includes: `ScientificName`, `CommonName`, `Rank`, `Division`, `TaxId`, `Genus`, `Species`.
+
+### 4. ELink -- Cross-link taxonomy to other databases
+```
+GET elink.fcgi?dbfrom=taxonomy&db=protein&id=9606&term=insulin
+```
+Find all protein records for a given taxid, optionally filtered by keyword.
+
+## Common Search Patterns
+```
+# All species under a genus
+term=Drosophila[Next Level] AND species[Rank]
+
+# Search by taxid directly
+term=txid9606[Organism:exp]
+
+# By rank
+term=Mammalia[Scientific Name] AND class[Rank]
+
+# Subtree search (all descendants)
+term=txid9606[Organism:exp]
+```
+
+## Useful Cross-references
+| Link | Description |
+|------|-------------|
+| `taxonomy_protein` | All proteins for a taxon |
+| `taxonomy_gene` | All genes for a taxon |
+| `taxonomy_nuccore` | All nucleotide records for a taxon |
+| `taxonomy_genome` | Genome assemblies for a taxon |
+
+## Rate Limits
+- Without API key: 3 requests/second
+- With API key: 10 requests/second
+- EFetch supports multiple taxids in a single call (comma-separated)

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

@@ -0,0 +1,105 @@
+# NIST Data APIs
+
+## Overview
+
+NIST provides several scientific databases. REST API availability varies by dataset.
+
+## 1. NIST CODATA Fundamental Physical Constants
+
+### Base URL
+```
+https://physics.nist.gov/cgi-bin/cuu
+```
+
+**No formal REST API.** Data is served via CGI scripts returning HTML. The constants can be accessed programmatically via structured URLs but responses are HTML, not JSON/XML.
+
+**Workaround — machine-readable ASCII:**
+```
+https://physics.nist.gov/cuu/Constants/Table/allascii.txt
+```
+Returns a tab-delimited text file of all fundamental constants with values, uncertainties, and units.
+
+**Individual constant lookup:**
+```
+https://physics.nist.gov/cgi-bin/cuu/Value?{constant_key}
+```
+Example keys: `bohrrada0` (Bohr radius), `c` (speed of light), `h` (Planck constant), `e` (electron charge), `me` (electron mass), `na` (Avogadro number), `k` (Boltzmann constant).
+
+Example:
+```
+https://physics.nist.gov/cgi-bin/cuu/Value?h
+```
+Returns HTML page. Parse the value from the page content.
+
+**No API key required. No rate limits documented.**
+
+## 2. NIST Atomic Spectra Database (ASD)
+
+### Base URL
+```
+https://physics.nist.gov/cgi-bin/ASD
+```
+
+**No formal REST API.** Queries are CGI-based, returning HTML. However, machine-readable output is available via specific parameters.
+
+**Spectral lines query:**
+```
+https://physics.nist.gov/cgi-bin/ASD/lines1.pl?spectra={element}&low_w={min_wavelength}&upp_w={max_wavelength}&unit={unit}&format={format}
+```
+
+| Parameter  | Type   | Description |
+|------------|--------|-------------|
+| `spectra`  | string | Element symbol or ion (e.g., `H`, `Fe`, `He+I`, `O+II`). |
+| `low_w`    | float  | Lower wavelength bound. |
+| `upp_w`    | float  | Upper wavelength bound. |
+| `unit`     | int    | `0` = Angstroms, `1` = nm, `2` = um. |
+| `format`   | int    | `0` = HTML, `1` = ASCII, `2` = CSV, `3` = tab-delimited. |
+| `line_out` | int    | `0` = all, `1` = only observed, `2` = only Ritz. |
+| `show_obs_wl` | int | `1` = show observed wavelengths. |
+| `show_calc_wl` | int | `1` = show Ritz wavelengths. |
+| `A_out`    | int    | `1` = include transition probabilities. |
+
+**Example — Hydrogen lines 3000-7000 Angstroms as CSV:**
+```
+https://physics.nist.gov/cgi-bin/ASD/lines1.pl?spectra=H&low_w=3000&upp_w=7000&unit=0&format=2&line_out=0&show_obs_wl=1&A_out=1
+```
+
+**Energy levels query:**
+```
+https://physics.nist.gov/cgi-bin/ASD/energy1.pl?spectra={element}&units={units}&format={format}
+```
+
+**No API key required. No formal rate limits but automated bulk queries are discouraged.**
+
+## 3. NIST Chemistry WebBook
+
+### Base URL
+```
+https://webbook.nist.gov/cgi/cbook.cgi
+```
+
+**No formal REST API.** CGI-based with HTML output. Structured URLs can be used.
+
+**Search by name:**
+```
+https://webbook.nist.gov/cgi/cbook.cgi?Name={compound}&Units=SI
+```
+
+**Search by CAS number:**
+```
+https://webbook.nist.gov/cgi/cbook.cgi?ID={cas_number}&Units=SI
+```
+
+**Search by formula:**
+```
+https://webbook.nist.gov/cgi/cbook.cgi?Formula={formula}&Units=SI
+```
+
+**JCAMP-DX spectra (machine-readable):**
+```
+https://webbook.nist.gov/cgi/cbook.cgi?ID={cas_number}&Type=IR-Spec&Index=0&JCAMP=C{cas_no_dashes}
+```
+
+## Summary
+
+NIST databases generally do **not** offer modern REST/JSON APIs. Data access is primarily through CGI endpoints returning HTML or delimited text. For programmatic use, the ASCII/CSV output options from ASD are the most practical. No authentication is required for any NIST endpoint.