wotann 0.5.0 → 0.5.39

package/skills/scientific/database-lookup/references/federal-reserve.md

@@ -0,0 +1,216 @@
+# Federal Reserve Economic Data (FRED) API
+
+## Base URL
+
+```
+https://api.stlouisfed.org/fred
+```
+
+## Authentication
+
+**API key required.** Register at https://fred.stlouisfed.org/docs/api/api_key.html
+
+Pass as query parameter: `&api_key=YOUR_KEY`
+
+## Key Endpoints
+
+### Get a Series (metadata)
+```
+GET /series
+```
+| Parameter   | Required | Description                        |
+|-------------|----------|------------------------------------|
+| series_id   | Yes      | FRED series ID (e.g., `FEDFUNDS`) |
+| api_key     | Yes      | Your API key                       |
+| file_type   | No       | `json` (default), `xml`           |
+
+Example:
+```
+https://api.stlouisfed.org/fred/series?series_id=FEDFUNDS&api_key=YOUR_KEY&file_type=json
+```
+
+### Get Series Observations (the actual data points)
+```
+GET /series/observations
+```
+| Parameter         | Required | Description                                            |
+|-------------------|----------|--------------------------------------------------------|
+| series_id         | Yes      | FRED series ID                                         |
+| api_key           | Yes      | Your API key                                           |
+| file_type         | No       | `json`, `xml`                                          |
+| observation_start | No       | `YYYY-MM-DD` start date                               |
+| observation_end   | No       | `YYYY-MM-DD` end date                                 |
+| units             | No       | `lin` (levels), `chg`, `ch1`, `pch`, `pc1`, `pca`, `cch`, `cca`, `log` |
+| frequency         | No       | `d`, `w`, `bw`, `m`, `q`, `sa`, `a` (daily to annual)|
+| aggregation_method| No       | `avg`, `sum`, `eop`                                   |
+| sort_order        | No       | `asc` (default), `desc`                               |
+| limit             | No       | Max observations (default 100000)                      |
+| offset            | No       | Pagination offset                                      |
+
+Example:
+```
+https://api.stlouisfed.org/fred/series/observations?series_id=FEDFUNDS&api_key=YOUR_KEY&file_type=json&observation_start=2023-01-01&observation_end=2024-01-01
+```
+
+### Search for Series
+```
+GET /series/search
+```
+| Parameter     | Required | Description                                  |
+|---------------|----------|----------------------------------------------|
+| search_text   | Yes      | Keywords to search                           |
+| api_key       | Yes      | Your API key                                 |
+| file_type     | No       | `json`, `xml`                                |
+| search_type   | No       | `full_text` (default), `series_id`           |
+| limit         | No       | Max results (default 1000)                   |
+| offset        | No       | Pagination offset                            |
+| order_by      | No       | `search_rank`, `series_id`, `title`, `units`, `frequency`, `seasonal_adjustment`, `realtime_start`, `realtime_end`, `last_updated`, `observation_start`, `observation_end`, `popularity`, `group_popularity` |
+| tag_names     | No       | Semicolon-delimited tag filter               |
+
+Example:
+```
+https://api.stlouisfed.org/fred/series/search?search_text=monetary+base&api_key=YOUR_KEY&file_type=json&limit=10
+```
+
+### Get Categories for a Series
+```
+GET /series/categories
+```
+Example:
+```
+https://api.stlouisfed.org/fred/series/categories?series_id=FEDFUNDS&api_key=YOUR_KEY&file_type=json
+```
+
+### Browse Categories
+```
+GET /category
+GET /category/children
+GET /category/series
+```
+Example (root category):
+```
+https://api.stlouisfed.org/fred/category?category_id=0&api_key=YOUR_KEY&file_type=json
+```
+
+### Get Releases
+```
+GET /releases
+GET /release/series
+```
+Example:
+```
+https://api.stlouisfed.org/fred/release/series?release_id=10&api_key=YOUR_KEY&file_type=json
+```
+
+### Get Tags
+```
+GET /tags
+GET /series/tags
+```
+
+## Common Series IDs
+
+| Series ID   | Description                              |
+|-------------|------------------------------------------|
+| FEDFUNDS    | Federal Funds Effective Rate             |
+| DFF         | Federal Funds Rate (daily)               |
+| DGS10       | 10-Year Treasury Constant Maturity Rate  |
+| DGS2        | 2-Year Treasury Constant Maturity Rate   |
+| M2SL        | M2 Money Stock                           |
+| CPIAUCSL    | Consumer Price Index (All Urban)         |
+| UNRATE      | Unemployment Rate                        |
+| GDP         | Gross Domestic Product                   |
+| GDPC1       | Real GDP                                 |
+| A191RL1Q225SBEA | Real GDP Growth Rate (quarterly)    |
+| PAYEMS      | Total Nonfarm Payrolls                   |
+| T10Y2Y      | 10Y-2Y Treasury Spread                  |
+| MORTGAGE30US| 30-Year Fixed Mortgage Rate              |
+| DTWEXBGS    | Trade Weighted US Dollar Index           |
+| BOGMBASE    | Monetary Base (total)                    |
+| WALCL       | Fed Total Assets                         |
+
+## Response Format
+
+### Series metadata (`/series`)
+```json
+{
+  "realtime_start": "2024-01-01",
+  "realtime_end": "2024-01-01",
+  "seriess": [
+    {
+      "id": "FEDFUNDS",
+      "realtime_start": "2024-01-01",
+      "realtime_end": "2024-01-01",
+      "title": "Federal Funds Effective Rate",
+      "observation_start": "1954-07-01",
+      "observation_end": "2024-01-01",
+      "frequency": "Monthly",
+      "frequency_short": "M",
+      "units": "Percent",
+      "units_short": "%",
+      "seasonal_adjustment": "Not Seasonally Adjusted",
+      "seasonal_adjustment_short": "NSA",
+      "last_updated": "2024-02-01 15:51:07-06",
+      "popularity": 95,
+      "notes": "..."
+    }
+  ]
+}
+```
+
+### Observations (`/series/observations`)
+```json
+{
+  "realtime_start": "2024-01-01",
+  "realtime_end": "2024-01-01",
+  "observation_start": "2023-01-01",
+  "observation_end": "2024-01-01",
+  "units": "lin",
+  "output_type": 1,
+  "file_type": "json",
+  "order_by": "observation_date",
+  "sort_order": "asc",
+  "count": 12,
+  "offset": 0,
+  "limit": 100000,
+  "observations": [
+    {
+      "realtime_start": "2024-01-01",
+      "realtime_end": "2024-01-01",
+      "date": "2023-01-01",
+      "value": "4.33"
+    }
+  ]
+}
+```
+
+Note: `value` is always a string. Missing data appears as `"."`.
+
+### Search results (`/series/search`)
+```json
+{
+  "realtime_start": "...",
+  "realtime_end": "...",
+  "order_by": "search_rank",
+  "sort_order": "desc",
+  "count": 500,
+  "offset": 0,
+  "limit": 1000,
+  "seriess": [
+    {
+      "id": "BOGMBASE",
+      "title": "Monetary Base; Total",
+      "frequency": "Bi-Weekly",
+      "units": "Millions of Dollars",
+      "popularity": 72,
+      "notes": "..."
+    }
+  ]
+}
+```
+
+## Rate Limits
+
+- **120 requests per minute** per API key.
+- No daily limit documented, but excessive use may be throttled.
+- Responses include no rate-limit headers; implement client-side throttling.

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

@@ -0,0 +1,297 @@
+# FRED (Federal Reserve Economic Data) API Reference
+
+## Overview
+The FRED API, provided by the Federal Reserve Bank of St. Louis, offers access to over 800,000 economic time series from 100+ sources. Covers GDP, employment, inflation, interest rates, money supply, trade, housing, and much more.
+
+## Base URL
+```
+https://api.stlouisfed.org/fred
+```
+
+## Authentication
+- **API Key: REQUIRED.** Register at https://fred.stlouisfed.org/docs/api/api_key.html
+- Pass as query parameter: `&api_key=YOUR_KEY`
+
+## Rate Limits
+- **120 requests per minute** per API key.
+- No daily limit documented, but excessive use may trigger throttling.
+
+## Common Parameters (apply to most endpoints)
+| Parameter       | Type   | Required | Default | Description |
+|----------------|--------|----------|---------|-------------|
+| `api_key`      | string | Yes      | -       | Your FRED API key. |
+| `file_type`    | string | No       | `xml`   | Response format: `xml` or `json`. |
+| `realtime_start` | string | No     | today   | Start of real-time period `YYYY-MM-DD`. |
+| `realtime_end`   | string | No     | today   | End of real-time period `YYYY-MM-DD`. |
+
+---
+
+## Key Endpoints
+
+### 1. Series Observations (Time Series Data)
+
+#### `GET /fred/series/observations`
+Returns the data values for an economic time series.
+
+**Parameters:**
+| Parameter           | Type   | Required | Default       | Description |
+|--------------------|--------|----------|---------------|-------------|
+| `series_id`        | string | Yes      | -             | FRED series ID (e.g., `GDP`, `UNRATE`, `CPIAUCSL`). |
+| `observation_start`| string | No       | `1776-07-04`  | Start date `YYYY-MM-DD`. |
+| `observation_end`  | string | No       | `9999-12-31`  | End date `YYYY-MM-DD`. |
+| `units`            | string | No       | `lin`         | Data transformation: `lin` (levels), `chg` (change), `ch1` (change from year ago), `pch` (% change), `pc1` (% change from year ago), `pca` (compounded annual % change), `cch` (continuously compounded rate of change), `cca` (continuously compounded annual rate), `log` (natural log). |
+| `frequency`        | string | No       | (native)      | Aggregation frequency: `d`, `w`, `bw`, `m`, `q`, `sa`, `a` (daily through annual). |
+| `aggregation_method` | string | No    | `avg`         | `avg`, `sum`, `eop` (end of period). |
+| `sort_order`       | string | No       | `asc`         | `asc` or `desc`. |
+| `limit`            | int    | No       | 100000        | Max observations returned (max 100000). |
+| `offset`           | int    | No       | 0             | Pagination offset. |
+
+**Example:**
+```
+https://api.stlouisfed.org/fred/series/observations?series_id=GDP&api_key=YOUR_KEY&file_type=json&observation_start=2020-01-01&observation_end=2024-12-31&units=pch&frequency=q
+```
+
+**Response:**
+```json
+{
+  "realtime_start": "2024-11-01",
+  "realtime_end": "2024-11-01",
+  "observation_start": "2020-01-01",
+  "observation_end": "2024-12-31",
+  "units": "Percent Change",
+  "output_type": 1,
+  "file_type": "json",
+  "order_by": "observation_date",
+  "sort_order": "asc",
+  "count": 20,
+  "offset": 0,
+  "limit": 100000,
+  "observations": [
+    {
+      "realtime_start": "2024-11-01",
+      "realtime_end": "2024-11-01",
+      "date": "2020-01-01",
+      "value": "-1.3"
+    },
+    {
+      "realtime_start": "2024-11-01",
+      "realtime_end": "2024-11-01",
+      "date": "2020-04-01",
+      "value": "-8.4"
+    }
+  ]
+}
+```
+
+Note: `value` is always a string. Missing values appear as `"."`.
+
+---
+
+### 2. Series Info (Metadata)
+
+#### `GET /fred/series`
+Returns metadata for a series.
+
+**Parameters:**
+| Parameter   | Type   | Required | Description |
+|------------|--------|----------|-------------|
+| `series_id`| string | Yes      | FRED series ID. |
+
+**Example:**
+```
+https://api.stlouisfed.org/fred/series?series_id=UNRATE&api_key=YOUR_KEY&file_type=json
+```
+
+**Response:**
+```json
+{
+  "realtime_start": "2024-11-01",
+  "realtime_end": "2024-11-01",
+  "seriess": [
+    {
+      "id": "UNRATE",
+      "title": "Unemployment Rate",
+      "observation_start": "1948-01-01",
+      "observation_end": "2024-10-01",
+      "frequency": "Monthly",
+      "frequency_short": "M",
+      "units": "Percent",
+      "units_short": "%",
+      "seasonal_adjustment": "Seasonally Adjusted",
+      "seasonal_adjustment_short": "SA",
+      "last_updated": "2024-11-01 07:41:02-05",
+      "popularity": 95,
+      "notes": "The unemployment rate represents..."
+    }
+  ]
+}
+```
+
+---
+
+### 3. Series Search
+
+#### `GET /fred/series/search`
+Search for series by keywords.
+
+**Parameters:**
+| Parameter       | Type   | Required | Default        | Description |
+|----------------|--------|----------|----------------|-------------|
+| `search_text`  | string | Yes      | -              | Keywords to search. |
+| `search_type`  | string | No       | `full_text`    | `full_text` or `series_id`. |
+| `order_by`     | string | No       | `search_rank`  | `search_rank`, `series_id`, `title`, `units`, `frequency`, `seasonal_adjustment`, `realtime_start`, `realtime_end`, `last_updated`, `observation_start`, `observation_end`, `popularity`, `group_popularity`. |
+| `sort_order`   | string | No       | `asc`          | `asc` or `desc`. |
+| `limit`        | int    | No       | 1000           | Max results (max 1000). |
+| `offset`       | int    | No       | 0              | Pagination offset. |
+| `filter_variable` | string | No    | -              | `frequency`, `units`, `seasonal_adjustment`. |
+| `filter_value` | string | No       | -              | Value to filter on (e.g., `Monthly`). |
+| `tag_names`    | string | No       | -              | Semicolon-delimited tags to filter (e.g., `gdp;quarterly`). |
+
+**Example:**
+```
+https://api.stlouisfed.org/fred/series/search?search_text=consumer+price+index&api_key=YOUR_KEY&file_type=json&limit=5
+```
+
+**Response:**
+```json
+{
+  "realtime_start": "2024-11-01",
+  "realtime_end": "2024-11-01",
+  "order_by": "search_rank",
+  "sort_order": "asc",
+  "count": 1256,
+  "offset": 0,
+  "limit": 5,
+  "seriess": [
+    {
+      "id": "CPIAUCSL",
+      "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
+      "observation_start": "1947-01-01",
+      "observation_end": "2024-09-01",
+      "frequency": "Monthly",
+      "units": "Index 1982-1984=100",
+      "seasonal_adjustment": "Seasonally Adjusted",
+      "popularity": 95
+    }
+  ]
+}
+```
+
+---
+
+### 4. Category Lookup
+
+#### `GET /fred/category`
+Get info for a specific category.
+
+**Parameters:**
+| Parameter    | Type | Required | Description |
+|-------------|------|----------|-------------|
+| `category_id`| int | Yes      | Category ID (0 = root). |
+
+**Example:**
+```
+https://api.stlouisfed.org/fred/category?category_id=0&api_key=YOUR_KEY&file_type=json
+```
+
+#### `GET /fred/category/children`
+Get child categories.
+
+**Example:**
+```
+https://api.stlouisfed.org/fred/category/children?category_id=0&api_key=YOUR_KEY&file_type=json
+```
+
+#### `GET /fred/category/series`
+Get all series in a category.
+
+**Parameters:**
+| Parameter    | Type | Required | Description |
+|-------------|------|----------|-------------|
+| `category_id`| int | Yes      | Category ID. |
+| `limit`     | int  | No       | Max results (max 1000). |
+| `offset`    | int  | No       | Pagination offset. |
+
+**Example:**
+```
+https://api.stlouisfed.org/fred/category/series?category_id=125&api_key=YOUR_KEY&file_type=json
+```
+
+---
+
+### 5. Releases
+
+#### `GET /fred/releases`
+Get all economic data releases.
+
+**Example:**
+```
+https://api.stlouisfed.org/fred/releases?api_key=YOUR_KEY&file_type=json
+```
+
+#### `GET /fred/release/series`
+Get all series in a specific release.
+
+**Parameters:**
+| Parameter   | Type | Required | Description |
+|------------|------|----------|-------------|
+| `release_id`| int | Yes      | Release ID. |
+
+**Example:**
+```
+https://api.stlouisfed.org/fred/release/series?release_id=53&api_key=YOUR_KEY&file_type=json
+```
+
+---
+
+### 6. Tags
+
+#### `GET /fred/tags`
+Get all tags and their frequency of use.
+
+#### `GET /fred/series/search/tags`
+Get tags matching a series search.
+
+**Example:**
+```
+https://api.stlouisfed.org/fred/series/search/tags?series_search_text=mortgage+rate&api_key=YOUR_KEY&file_type=json
+```
+
+---
+
+## Commonly Used Series IDs
+
+| Series ID     | Description |
+|--------------|-------------|
+| `GDP`        | Gross Domestic Product (quarterly, billions $) |
+| `GDPC1`     | Real GDP (chained 2017 dollars) |
+| `A191RL1Q225SBEA` | Real GDP growth rate (annualized quarterly) |
+| `UNRATE`    | Unemployment Rate (monthly, %) |
+| `PAYEMS`    | Total Nonfarm Payrolls (monthly, thousands) |
+| `CPIAUCSL`  | CPI All Urban Consumers (monthly, index) |
+| `CPILFESL`  | Core CPI (excl. food & energy) |
+| `PCEPI`     | PCE Price Index |
+| `PCEPILFE`  | Core PCE Price Index |
+| `FEDFUNDS`  | Federal Funds Effective Rate (monthly, %) |
+| `DFF`       | Federal Funds Effective Rate (daily) |
+| `DGS10`     | 10-Year Treasury Constant Maturity Rate (daily) |
+| `DGS2`      | 2-Year Treasury Rate (daily) |
+| `T10Y2Y`    | 10Y-2Y Treasury Spread |
+| `MORTGAGE30US` | 30-Year Fixed Mortgage Rate (weekly) |
+| `M2SL`      | M2 Money Stock (monthly) |
+| `HOUST`     | Housing Starts (monthly, thousands) |
+| `RSAFS`     | Retail Sales (monthly, millions $) |
+| `INDPRO`    | Industrial Production Index |
+| `UMCSENT`   | U. of Michigan Consumer Sentiment |
+| `SP500`     | S&P 500 Index (daily) |
+| `VIXCLS`    | CBOE Volatility Index (daily) |
+| `DEXUSEU`   | USD/EUR Exchange Rate (daily) |
+| `DCOILWTICO`| WTI Crude Oil Price (daily) |
+| `BOPGSTB`   | Trade Balance (monthly, millions $) |
+| `GFDEBTN`   | Federal Debt Total Public Debt |
+
+## Notes
+- Real-time periods: FRED supports vintage data. The `realtime_start`/`realtime_end` parameters let you retrieve data as it was known at a specific point in time (useful for analyzing data revisions).
+- The `units` parameter for transformations is very powerful -- it avoids having to compute percent changes client-side.
+- Values are returned as strings; `"."` means missing/unavailable.
+- For FRED bulk data, they offer a download API at `https://api.stlouisfed.org/geofred/` for geographic/regional data.

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

@@ -0,0 +1,147 @@
+# Gene Ontology (GO) API Reference
+
+## Base URLs
+- **QuickGO (EBI, recommended)**: `https://www.ebi.ac.uk/QuickGO/services` — most reliable endpoint
+- **GO API**: `https://api.geneontology.org/api` — may return 403; use QuickGO as fallback
+- **AmiGO / GOlr (Solr-based)**: `http://golr-aux.geneontology.org/solr`
+
+## Authentication
+None required. All endpoints are public.
+
+## Rate Limits
+No published hard limits. QuickGO recommends reasonable usage.
+
+---
+
+## GO API (api.geneontology.org)
+
+### 1. GO Term Lookup
+```
+GET https://api.geneontology.org/api/ontology/term/{go_id}
+```
+Example:
+```
+GET https://api.geneontology.org/api/ontology/term/GO%3A0008150
+```
+Returns JSON with term name, definition, namespace (biological_process / molecular_function / cellular_component), synonyms.
+
+### 2. Gene/Protein Annotations (Bioentity)
+```
+GET https://api.geneontology.org/api/bioentity/gene/{gene_id}/function
+```
+Example — GO annotations for a UniProt protein:
+```
+GET https://api.geneontology.org/api/bioentity/gene/UniProtKB%3AP04637/function
+```
+Returns GO annotations with evidence codes, qualifiers, references.
+
+### 3. Genes Annotated to a GO Term
+```
+GET https://api.geneontology.org/api/bioentity/function/{go_id}/genes
+```
+Example:
+```
+GET https://api.geneontology.org/api/bioentity/function/GO%3A0006915/genes?rows=20
+```
+Returns genes/proteins annotated with that GO term.
+
+### 4. Search Entities
+```
+GET https://api.geneontology.org/api/search/entity/{query}
+```
+Example:
+```
+GET https://api.geneontology.org/api/search/entity/apoptosis?rows=10
+```
+
+### 5. Ontology Ancestors / Descendants
+```
+GET https://api.geneontology.org/api/ontology/term/{go_id}/graph
+```
+
+---
+
+## QuickGO API (EBI — recommended for robust annotation queries)
+
+### 1. GO Term Details
+```
+GET https://www.ebi.ac.uk/QuickGO/services/ontology/go/terms/{go_ids}
+```
+Example:
+```
+GET https://www.ebi.ac.uk/QuickGO/services/ontology/go/terms/GO:0008150
+```
+Accepts comma-separated IDs (up to 25).
+
+### 2. Search Annotations
+```
+GET https://www.ebi.ac.uk/QuickGO/services/annotation/search?geneProductId={uniprot_id}
+```
+Example — annotations for TP53:
+```
+GET https://www.ebi.ac.uk/QuickGO/services/annotation/search?geneProductId=P04637&limit=25
+```
+
+### 3. Annotations by GO Term
+```
+GET https://www.ebi.ac.uk/QuickGO/services/annotation/search?goId=GO:0006915&taxonId=9606&limit=25
+```
+
+### 4. Filter Annotations by Evidence
+```
+GET https://www.ebi.ac.uk/QuickGO/services/annotation/search?geneProductId=P04637&goUsage=descendants&evidenceCode=ECO:0000269&limit=25
+```
+
+### 5. GO Term Children
+```
+GET https://www.ebi.ac.uk/QuickGO/services/ontology/go/terms/GO:0008150/children
+```
+
+### 6. GO Term Ancestors (Chart)
+```
+GET https://www.ebi.ac.uk/QuickGO/services/ontology/go/terms/GO:0006915/ancestors?relations=is_a,part_of
+```
+
+### 7. Search GO Terms by Name
+```
+GET https://www.ebi.ac.uk/QuickGO/services/ontology/go/search?query=apoptosis&limit=10
+```
+
+## QuickGO Annotation Search Parameters
+| Parameter | Description |
+|-----------|-------------|
+| `geneProductId` | UniProt accession (e.g., P04637) |
+| `goId` | GO term (e.g., GO:0006915) |
+| `goUsage` | `exact` or `descendants` (include child terms) |
+| `taxonId` | NCBI taxonomy ID (9606 = human) |
+| `evidenceCode` | ECO code (e.g., ECO:0000269 = experimental) |
+| `aspect` | `biological_process`, `molecular_function`, `cellular_component` |
+| `limit` | Results per page (max 100) |
+| `page` | Page number (1-based) |
+
+## QuickGO Response Format
+```json
+{
+  "numberOfHits": 1234,
+  "results": [
+    {
+      "geneProductId": "P04637",
+      "symbol": "TP53",
+      "goId": "GO:0006915",
+      "goName": "apoptotic process",
+      "evidenceCode": "ECO:0000269",
+      "goAspect": "biological_process",
+      "taxonId": 9606,
+      "reference": "PMID:12345678",
+      "assignedBy": "UniProt"
+    }
+  ]
+}
+```
+
+## Notes
+- QuickGO (EBI) is generally more robust and better documented for annotation queries.
+- GO API (geneontology.org) is better for ontology structure traversal.
+- GO IDs must be URL-encoded when used in paths (e.g., `GO%3A0008150` for `GO:0008150`).
+- Three GO namespaces: biological_process (BP), molecular_function (MF), cellular_component (CC).
+- Evidence codes: IDA (direct assay), IMP (mutant phenotype), IGI (genetic interaction), IEA (electronic annotation), etc.