wotann 0.5.0 → 0.5.39

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

@@ -0,0 +1,283 @@
+# UniProt REST API
+
+## Base URL
+
+```
+https://rest.uniprot.org
+```
+
+## Authentication
+
+No API key required. All endpoints are public.
+
+## Key Endpoints
+
+### 1. Search proteins
+
+```
+GET /uniprotkb/search
+```
+
+**Parameters:**
+
+| Parameter | Type   | Description |
+|-----------|--------|-------------|
+| `query`   | string | **Required.** Search query using UniProt query syntax (field:value pairs, boolean operators). |
+| `format`  | string | `json` (default), `tsv`, `fasta`, `xml`, `list`, `xlsx`, `obo` |
+| `fields`  | string | Comma-separated list of columns to return. Key fields: `accession`, `id`, `protein_name`, `gene_names`, `organism_name`, `organism_id`, `length`, `sequence`, `cc_function`, `go_id`, `go`, `xref_pdb`, `reviewed`, `ec`, `cc_subcellular_location`, `ft_domain`, `lineage` |
+| `size`    | int    | Results per page (max 500, default 25) |
+| `cursor`  | string | Pagination cursor (returned in `Link` response header) |
+| `sort`    | string | Sort field and direction, e.g. `gene asc`, `length desc`, `annotation_score desc` |
+
+**Example calls:**
+
+Search for reviewed human TP53:
+```
+https://rest.uniprot.org/uniprotkb/search?query=(gene:TP53) AND (organism_id:9606) AND (reviewed:true)&format=json&fields=accession,protein_name,gene_names,organism_name,length,cc_function&size=10
+```
+
+Search by protein name keyword:
+```
+https://rest.uniprot.org/uniprotkb/search?query=(protein_name:insulin) AND (reviewed:true)&format=json&size=5
+```
+
+Search by EC number (enzyme classification):
+```
+https://rest.uniprot.org/uniprotkb/search?query=(ec:2.7.11.1) AND (organism_id:9606)&format=json&size=25
+```
+
+Search by Gene Ontology:
+```
+https://rest.uniprot.org/uniprotkb/search?query=(go:0006915) AND (organism_id:9606) AND (reviewed:true)&format=json&size=25
+```
+
+**Response (JSON):**
+```json
+{
+  "results": [
+    {
+      "entryType": "UniProtKB reviewed (Swiss-Prot)",
+      "primaryAccession": "P04637",
+      "uniProtkbId": "P53_HUMAN",
+      "organism": {
+        "scientificName": "Homo sapiens",
+        "taxonId": 9606
+      },
+      "proteinDescription": {
+        "recommendedName": {
+          "fullName": { "value": "Cellular tumor antigen p53" }
+        }
+      },
+      "genes": [
+        {
+          "geneName": { "value": "TP53" },
+          "synonyms": [{ "value": "P53" }]
+        }
+      ],
+      "sequence": {
+        "value": "MEEPQSDP...",
+        "length": 393,
+        "molWeight": 43653,
+        "crc64": "..."
+      },
+      "comments": [...],
+      "features": [...],
+      "references": [...]
+    }
+  ]
+}
+```
+
+**Pagination:** The `Link` response header contains the next page URL with the cursor parameter. Follow it to get subsequent pages.
+
+---
+
+### 2. Fetch single entry by accession
+
+```
+GET /uniprotkb/{accession}
+```
+
+**Parameters:**
+
+| Parameter | Type   | Description |
+|-----------|--------|-------------|
+| `format`  | string | `json`, `tsv`, `fasta`, `xml`, `gff` |
+
+**Example calls:**
+
+```
+https://rest.uniprot.org/uniprotkb/P04637?format=json
+https://rest.uniprot.org/uniprotkb/P04637.fasta
+```
+
+---
+
+### 3. FASTA sequence retrieval
+
+Append `.fasta` to the accession or use `format=fasta`:
+
+```
+https://rest.uniprot.org/uniprotkb/P04637.fasta
+```
+
+Batch FASTA from search:
+```
+https://rest.uniprot.org/uniprotkb/search?query=(gene:BRCA1) AND (organism_id:9606) AND (reviewed:true)&format=fasta
+```
+
+---
+
+### 4. ID Mapping (convert between ID types)
+
+ID mapping is a two-step async process.
+
+**Step 1: Submit job**
+```
+POST /idmapping/run
+Content-Type: application/x-www-form-urlencoded
+
+from={dbFrom}&to={dbTo}&ids={comma-separated-ids}
+```
+
+Common `from`/`to` database names:
+- `UniProtKB_AC-ID` (UniProt accession)
+- `Gene_Name`
+- `GeneID` (NCBI Gene / Entrez Gene)
+- `Ensembl`, `Ensembl_Genomes`
+- `RefSeq_Protein`
+- `PDB`
+- `ChEMBL`
+- `EMBL-GenBank-DDBJ`
+- `STRING`
+
+Returns:
+```json
+{ "jobId": "abc123def456" }
+```
+
+**Step 2: Poll and retrieve results**
+```
+GET /idmapping/status/{jobId}
+```
+When complete, redirects to:
+```
+GET /idmapping/results/{jobId}?format=json&size=500
+```
+
+**Example:**
+
+Map Ensembl gene IDs to UniProt accessions:
+```
+POST /idmapping/run
+from=Ensembl&to=UniProtKB_AC-ID&ids=ENSG00000141510,ENSG00000012048
+```
+
+Map UniProt to PDB:
+```
+POST /idmapping/run
+from=UniProtKB_AC-ID&to=PDB&ids=P04637,P38398
+```
+
+**Response (results):**
+```json
+{
+  "results": [
+    {
+      "from": "ENSG00000141510",
+      "to": {
+        "primaryAccession": "P04637",
+        "uniProtkbId": "P53_HUMAN",
+        ...
+      }
+    }
+  ]
+}
+```
+
+---
+
+### 5. UniRef (clustered sequences)
+
+```
+GET /uniref/search?query={query}&format=json
+GET /uniref/{id}
+```
+
+Cluster IDs: `UniRef100_P04637`, `UniRef90_P04637`, `UniRef50_P04637`
+
+---
+
+### 6. UniParc (sequence archive)
+
+```
+GET /uniparc/search?query={query}&format=json
+GET /uniparc/{upi}
+```
+
+---
+
+### 7. Proteomes
+
+```
+GET /proteomes/search?query=(organism_id:9606)&format=json
+GET /proteomes/{upid}
+```
+
+Example — human reference proteome:
+```
+https://rest.uniprot.org/proteomes/UP000005640?format=json
+```
+
+---
+
+### 8. Taxonomy
+
+```
+GET /taxonomy/search?query={query}&format=json
+GET /taxonomy/{taxonId}
+```
+
+---
+
+## Query Syntax
+
+UniProt search queries support field:value syntax with boolean operators:
+
+- `(gene:TP53)` -- gene name
+- `(organism_id:9606)` -- NCBI taxonomy ID (9606 = human, 10090 = mouse)
+- `(organism_name:"Homo sapiens")` -- organism name
+- `(reviewed:true)` -- Swiss-Prot only (manually reviewed)
+- `(protein_name:kinase)` -- protein name contains keyword
+- `(ec:2.7.11.1)` -- enzyme classification
+- `(go:0006915)` -- Gene Ontology term ID
+- `(xref:pdb-P04637)` -- cross-reference
+- `(length:[100 TO 300])` -- sequence length range
+- `(cc_disease:cancer)` -- disease involvement
+- `(ft_domain:SH2)` -- domain annotation
+- `(cc_subcellular_location:nucleus)` -- subcellular location
+- `(date_modified:[2024-01-01 TO *])` -- modification date
+
+Combine with `AND`, `OR`, `NOT`:
+```
+(gene:BRCA1) AND (organism_id:9606) AND (reviewed:true)
+```
+
+## Rate Limits
+
+- No hard published rate limit, but excessive requests will be throttled.
+- Use pagination (`size` + `cursor`) to batch results.
+- Batch ID mapping jobs instead of one-at-a-time lookups.
+- For large downloads, use the streaming endpoints or FTP site.
+- Respect `Retry-After` headers if you receive HTTP 429.
+
+## Error Format
+
+```json
+{
+  "url": "https://rest.uniprot.org/...",
+  "messages": ["Error message here"]
+}
+```
+
+HTTP 400 for bad queries, 404 for not found, 429 for rate limiting, 500 for server errors.

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

@@ -0,0 +1,260 @@
+# USGS API Reference (Earthquake Hazards + Water Services)
+
+## Part A: Earthquake Hazards Program
+
+### Base URL
+```
+https://earthquake.usgs.gov/fdsnws/event/1
+```
+
+### Authentication
+**None required.** Fully public, no API key needed.
+
+### Rate Limits
+- No documented per-user rate limit, but USGS asks users to limit automated queries to avoid overloading the service.
+- Requests returning very large result sets (>20,000 events) will be rejected. Use pagination or narrow your query.
+
+### Key Endpoints
+
+#### 1. Query Earthquakes
+```
+GET /query
+```
+Returns earthquake events matching search criteria. This is the primary endpoint.
+
+**Parameters:**
+| Parameter     | Type   | Required | Default    | Description |
+|--------------|--------|----------|------------|-------------|
+| `format`     | string | No       | `quakeml`  | `geojson`, `csv`, `quakeml`, `text`, `kml`. Use `geojson` for JSON. |
+| `starttime`  | string | No       | (now - 30d)| ISO8601 date, e.g. `2024-01-01`. |
+| `endtime`    | string | No       | (now)      | ISO8601 date. |
+| `minmagnitude`| float | No       | -          | Minimum magnitude (e.g. `4.5`). |
+| `maxmagnitude`| float | No       | -          | Maximum magnitude. |
+| `mindepth`   | float  | No       | -          | Minimum depth in km. |
+| `maxdepth`   | float  | No       | -          | Maximum depth in km. |
+| `latitude`   | float  | No       | -          | Center latitude for circle search (-90 to 90). |
+| `longitude`  | float  | No       | -          | Center longitude for circle search (-180 to 180). |
+| `maxradiuskm`| float  | No       | -          | Max radius in km (with lat/lon). |
+| `minlatitude`| float  | No       | -          | Bounding box south edge. |
+| `maxlatitude`| float  | No       | -          | Bounding box north edge. |
+| `minlongitude`| float | No       | -          | Bounding box west edge. |
+| `maxlongitude`| float | No       | -          | Bounding box east edge. |
+| `limit`      | int    | No       | -          | Max events returned (max 20000). |
+| `offset`     | int    | No       | 1          | Pagination offset (1-based). |
+| `orderby`    | string | No       | `time`     | `time`, `time-asc`, `magnitude`, `magnitude-asc`. |
+| `alertlevel` | string | No       | -          | PAGER alert: `green`, `yellow`, `orange`, `red`. |
+| `eventtype`  | string | No       | -          | e.g. `earthquake`, `quarry blast`. |
+
+**Example -- significant earthquakes in a region:**
+```
+https://earthquake.usgs.gov/fdsnws/event/1/query?format=geojson&starttime=2024-01-01&endtime=2024-12-31&minmagnitude=5.0&minlatitude=30&maxlatitude=45&minlongitude=-125&maxlongitude=-110&orderby=magnitude
+```
+
+**GeoJSON Response:**
+```json
+{
+  "type": "FeatureCollection",
+  "metadata": {
+    "generated": 1700000000000,
+    "url": "https://earthquake.usgs.gov/fdsnws/event/1/query?...",
+    "title": "USGS Earthquakes",
+    "status": 200,
+    "api": "1.14.1",
+    "count": 42
+  },
+  "features": [
+    {
+      "type": "Feature",
+      "properties": {
+        "mag": 6.2,
+        "place": "15 km NNE of Ridgecrest, CA",
+        "time": 1700000000000,
+        "updated": 1700100000000,
+        "tz": null,
+        "url": "https://earthquake.usgs.gov/earthquakes/eventpage/ci00000001",
+        "detail": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=ci00000001&format=geojson",
+        "felt": 1500,
+        "cdi": 7.1,
+        "mmi": 6.5,
+        "alert": "yellow",
+        "status": "reviewed",
+        "tsunami": 0,
+        "sig": 800,
+        "net": "ci",
+        "code": "00000001",
+        "type": "earthquake",
+        "title": "M 6.2 - 15 km NNE of Ridgecrest, CA"
+      },
+      "geometry": {
+        "type": "Point",
+        "coordinates": [-117.5, 35.8, 10.5]
+      },
+      "id": "ci00000001"
+    }
+  ]
+}
+```
+Note: `geometry.coordinates` is `[longitude, latitude, depth_km]`.
+
+#### 2. Event Detail
+```
+GET /query?eventid={EVENTID}&format=geojson
+```
+Returns detailed info for a single event, including moment tensor, focal mechanism, and nearby cities.
+
+#### 3. Event Count
+```
+GET /count
+```
+Same parameters as `/query`, returns just the count of matching events. Useful for checking result size before querying.
+
+**Example:**
+```
+https://earthquake.usgs.gov/fdsnws/event/1/count?starttime=2024-01-01&endtime=2024-12-31&minmagnitude=4.5
+```
+
+#### 4. Real-Time Feeds (no parameters)
+Pre-built GeoJSON feeds updated every minute/5 min/15 min/hour:
+```
+https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/significant_month.geojson
+https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/4.5_week.geojson
+https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_day.geojson
+https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson
+```
+Pattern: `{significance}_{timeperiod}.geojson` where significance is `significant`, `4.5`, `2.5`, `1.0`, `all` and timeperiod is `hour`, `day`, `week`, `month`.
+
+---
+
+## Part B: Water Services
+
+### Base URL
+```
+https://waterservices.usgs.gov/nwis
+```
+
+### Authentication
+**None required.** Fully public, no API key needed.
+
+### Rate Limits
+- No strict per-user limit, but USGS recommends limiting automated requests. Large queries may time out.
+
+### Key Endpoints
+
+#### 1. Instantaneous Values (Real-Time Data)
+```
+GET /iv/
+```
+Returns the most recent sensor readings (typically 15-minute intervals).
+
+**Parameters:**
+| Parameter       | Type   | Required | Default | Description |
+|----------------|--------|----------|---------|-------------|
+| `format`       | string | No       | `wml`   | `json`, `xml`, `wml,1.1`, `wml,2.0`, `rdb`. Use `json` for JSON. |
+| `sites`        | string | Cond.    | -       | Comma-separated USGS site numbers (e.g. `01646500`). |
+| `stateCd`      | string | Cond.    | -       | 2-letter state code (e.g. `NY`). |
+| `huc`          | string | Cond.    | -       | Hydrologic Unit Code(s). |
+| `bBox`         | string | Cond.    | -       | Bounding box: `west,south,east,north` (decimal degrees). |
+| `countyCd`     | string | Cond.    | -       | 5-digit FIPS county code(s). |
+| `parameterCd`  | string | No       | `00060` | Parameter code(s). `00060`=streamflow, `00065`=gage height, `00010`=water temp. |
+| `period`       | string | No       | -       | ISO8601 duration, e.g. `P7D` (past 7 days). |
+| `startDT`      | string | No       | -       | Start datetime (ISO8601). |
+| `endDT`        | string | No       | -       | End datetime (ISO8601). |
+| `siteType`     | string | No       | -       | e.g. `ST` (stream), `GW` (groundwater), `LK` (lake). |
+| `siteStatus`   | string | No       | `all`   | `active`, `inactive`, `all`. |
+
+At least one location parameter (`sites`, `stateCd`, `huc`, `bBox`, or `countyCd`) is required.
+
+**Example -- real-time streamflow for a site:**
+```
+https://waterservices.usgs.gov/nwis/iv/?format=json&sites=01646500&parameterCd=00060&period=P1D
+```
+
+**JSON Response (abbreviated):**
+```json
+{
+  "name": "ns1:timeSeriesResponseType",
+  "declaredType": "org.cuahsi.waterml.TimeSeriesResponseType",
+  "value": {
+    "timeSeries": [
+      {
+        "sourceInfo": {
+          "siteName": "Potomac River near Wash, DC Little Falls Pump Sta",
+          "siteCode": [{"value": "01646500", "agencyCode": "USGS"}],
+          "geoLocation": {
+            "geogLocation": {"latitude": 38.94977778, "longitude": -77.12763889}
+          }
+        },
+        "variable": {
+          "variableCode": [{"value": "00060"}],
+          "variableName": "Streamflow, ft³/s",
+          "unit": {"unitCode": "ft3/s"}
+        },
+        "values": [
+          {
+            "value": [
+              {"value": "5280", "dateTime": "2024-01-15T00:00:00.000-05:00"},
+              {"value": "5310", "dateTime": "2024-01-15T00:15:00.000-05:00"}
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+#### 2. Daily Values (Historical Aggregates)
+```
+GET /dv/
+```
+Returns daily statistical values (mean, max, min). Same location parameters as `/iv/`.
+
+**Additional Parameters:**
+| Parameter  | Type   | Description |
+|-----------|--------|-------------|
+| `statCd`  | string | Statistic code: `00001`=max, `00002`=min, `00003`=mean, `00006`=sum. Default `00003`. |
+
+**Example -- daily mean streamflow, 1 year:**
+```
+https://waterservices.usgs.gov/nwis/dv/?format=json&sites=01646500&parameterCd=00060&statCd=00003&startDT=2023-01-01&endDT=2023-12-31
+```
+
+#### 3. Site Information
+```
+GET /site/
+```
+Returns metadata about monitoring sites. Same location parameters apply.
+
+**Example -- active stream sites in Virginia:**
+```
+https://waterservices.usgs.gov/nwis/site/?format=rdb&stateCd=VA&siteType=ST&siteStatus=active&hasDataTypeCd=iv
+```
+
+#### 4. Statistics (Pre-computed)
+```
+GET /stat/
+```
+Returns pre-computed statistics (percentiles, mean, median) for daily values, useful for comparing current conditions to historical norms.
+
+**Example:**
+```
+https://waterservices.usgs.gov/nwis/stat/?format=rdb&sites=01646500&parameterCd=00060&statReportType=daily&statTypeCd=mean,p05,p25,p50,p75,p95
+```
+
+### Common Parameter Codes
+| Code    | Description |
+|---------|-------------|
+| `00060` | Discharge/streamflow (ft3/s) |
+| `00065` | Gage height (ft) |
+| `00010` | Water temperature (C) |
+| `00045` | Precipitation (in) |
+| `00400` | pH |
+| `00300` | Dissolved oxygen (mg/L) |
+| `00095` | Specific conductance (uS/cm) |
+| `72019` | Groundwater level depth below land surface (ft) |
+
+## Notes
+- Earthquake API returns coordinates as `[lon, lat, depth]` (note: longitude first).
+- Water Services JSON wraps data in a verbose WaterML-like structure. The `rdb` (tab-delimited) format is simpler for tabular data.
+- USGS site numbers are typically 8 digits for surface water, 15 for groundwater.
+- Both APIs are free, public, and require no authentication.

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

@@ -0,0 +1,130 @@
+# USPTO Public APIs
+
+## 1. PatentsView API (Primary Patent Search)
+
+The newer Elasticsearch-based API is the recommended endpoint.
+
+### Base URL
+
+```
+https://search.patentsview.org/api/v1/
+```
+
+**API key required** — register at `https://patentsview.org/apis/keyrequest`
+
+Pass as query parameter: `?api_key=YOUR_KEY`
+
+### Key Endpoints
+
+#### Search patents
+```
+GET or POST /patent/
+```
+
+Query parameter `q` accepts a JSON query object.
+
+Operators: `_eq`, `_neq`, `_gt`, `_gte`, `_lt`, `_lte`, `_begins`, `_contains`, `_text_any`, `_text_all`, `_text_phrase`, `_and`, `_or`, `_not`
+
+Parameters:
+- `q` — JSON query
+- `f` — fields to return (JSON array)
+- `o` — options: `{"size": 25}` for pagination
+- `s` — sort: `[{"patent_date": "desc"}]`
+
+#### Search by keyword
+```
+GET /patent/?q={"_text_any":{"patent_abstract":"autonomous vehicle"}}&f=["patent_id","patent_title","patent_date"]&o={"size":5}&api_key=KEY
+```
+
+#### Search by inventor
+```
+GET /patent/?q={"inventors.inventor_name_last":"Tesla"}&f=["patent_id","patent_title","patent_date"]&api_key=KEY
+```
+
+#### Search by assignee
+```
+GET /patent/?q={"assignees.assignee_organization":"Google LLC"}&f=["patent_id","patent_title","patent_date","assignees"]&api_key=KEY
+```
+
+#### Lookup by patent number
+```
+GET /patent/{patent_number}/?api_key=KEY
+```
+
+#### Other entity endpoints
+```
+/inventor/
+/assignee/
+/cpc_group/
+```
+
+### Response Structure
+
+```json
+{
+  "patents": [
+    {
+      "patent_id": "11234567",
+      "patent_title": "...",
+      "patent_date": "2022-03-15",
+      "patent_abstract": "...",
+      "assignees": [{"assignee_organization": "..."}],
+      "inventors": [{"inventor_name_first": "...", "inventor_name_last": "..."}]
+    }
+  ],
+  "count": 1,
+  "total_hits": 8923
+}
+```
+
+### Rate Limits
+
+~45 requests per minute per API key.
+
+### Important Note
+
+The user must have a PatentsView API key for this endpoint. If they don't have one, let them know they need to register at `https://patentsview.org/apis/keyrequest`. Load the key from `.env` as `PATENTSVIEW_API_KEY`.
+
+**Note:** The legacy API at `api.patentsview.org` has been decommissioned (returns 410 Gone). Only the new API above works.
+
+## 3. PEDS — Patent Examination Data System
+
+**URL**: `https://ped.uspto.gov/api/queries`
+
+**Method**: POST
+
+For patent prosecution data (application status, filing dates, examiner info).
+
+```json
+{
+  "searchText": "applicationNumberText:16123456",
+  "fl": "*",
+  "mm": "100%",
+  "df": "patentTitle",
+  "facet": "false",
+  "sort": "applId asc",
+  "start": 0
+}
+```
+
+No API key required but heavily rate limited. Availability can be unreliable.
+
+## 4. TSDR — Trademark Status & Document Retrieval
+
+For trademark lookup by serial or registration number (not full-text search).
+
+```
+GET https://tsdr.uspto.gov/documentxml/status/{serial_number}
+GET https://tsdr.uspto.gov/documentxml/status/rn{registration_number}
+```
+
+Returns XML with mark details, status, owner, goods/services, prosecution history.
+
+No API key. Rate limited. No JSON endpoint — responses are XML.
+
+## 5. Limitations
+
+- **No public REST API for trademark full-text search** (TESS is web-only)
+- PatentsView new API requires registration for an API key
+- PEDS availability is inconsistent
+- TSDR requires knowing the serial/registration number already