wotann 0.5.0 → 0.5.39

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

@@ -0,0 +1,85 @@
+# BindingDB REST API
+
+## Base URLs
+```
+https://bindingdb.org/rest/
+https://bindingdb.org/axis2/services/BDBService/
+```
+
+## Auth
+No API key required. Fully open and free.
+
+## Response Format
+Default is XML. Append `&response=application/json` to any endpoint for JSON.
+
+## Key Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/rest/getLigandsByUniprot` | Ligands for a single protein target |
+| `/rest/getLigandsByUniprots` | Ligands for multiple protein targets |
+| `/rest/getLigandsByPDBs` | Ligands by PDB structure IDs |
+| `/rest/getTargetByCompound` | Targets for a compound (SMILES similarity) |
+
+## Endpoint Details
+
+### Get ligands for a single target
+```
+GET https://bindingdb.org/rest/getLigandsByUniprot?uniprot={UNIPROT_ID};{IC50_cutoff_nM}&response=application/json
+```
+- `uniprot` — UniProt ID followed by `;` and affinity cutoff in nM
+- Returns monomerIDs, SMILES, affinity types (IC50, Ki, Kd), and values
+- Returns empty string if UniProt ID not found
+
+Example:
+```
+https://bindingdb.org/rest/getLigandsByUniprot?uniprot=P35355;100&response=application/json
+```
+
+### Get ligands for multiple targets
+```
+GET https://bindingdb.org/rest/getLigandsByUniprots?uniprot={IDs}&cutoff={nM}&response=application/json
+```
+- `uniprot` — Comma-separated UniProt IDs
+- `cutoff` — Affinity cutoff in nM
+- Returns empty string if no matching IDs
+
+Example:
+```
+https://bindingdb.org/rest/getLigandsByUniprots?uniprot=P00176,P00183&cutoff=10000&response=application/json
+```
+
+### Get ligands by PDB structure
+```
+GET https://bindingdb.org/rest/getLigandsByPDBs?pdb={PDBs}&cutoff={nM}&identity={percent}&response=application/json
+```
+- `pdb` — Comma-separated PDB IDs
+- `cutoff` — Affinity cutoff in nM
+- `identity` — Sequence identity cutoff (percent, e.g. 92)
+
+Example:
+```
+https://bindingdb.org/rest/getLigandsByPDBs?pdb=1Q0L,3ANM&cutoff=100&identity=92&response=application/json
+```
+
+### Find targets for a compound (similarity search)
+```
+GET https://bindingdb.org/rest/getTargetByCompound?smiles={SMILES}&cutoff={similarity}&response=application/json
+```
+- `smiles` — Compound SMILES (must be URL-encoded)
+- `cutoff` — Tanimoto similarity cutoff (decimal, e.g. 0.85)
+- Returns similar compounds with their protein targets and affinities
+
+Example:
+```
+https://bindingdb.org/rest/getTargetByCompound?smiles=CCC%5BN%2B%5D%28C%29%28C%29CCn1nncc1COc1cc%28%3DO%29n%28C%29c2ccccc12&cutoff=0.85&response=application/json
+```
+
+## Rate Limits
+No documented limit. Keep requests to ~1 per second as a courtesy.
+
+## Notes
+- The API surface is small (4 endpoints) but focused on binding affinity data
+- For compound-name search, resolve to SMILES first via PubChem, then use `getTargetByCompound`
+- For bulk data access, use downloadable TSV/SDF files from https://www.bindingdb.org/bind/chemsearch/marvin/Download.jsp
+- Contains ~3.2M binding measurements for ~1.4M compounds and ~11.4K targets

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

@@ -0,0 +1,110 @@
+# BioGRID API Reference
+
+## Base URL
+```
+https://webservice.thebiogrid.org/interactions
+```
+
+## Authentication
+**API key REQUIRED.** Register free at https://webservice.thebiogrid.org/ to obtain an access key.
+- Pass as query parameter: `?accesskey=YOUR_ACCESS_KEY`
+
+## Rate Limits
+Not formally published. Reasonable usage expected.
+
+## Response Format
+JSON (with `&format=json`), tab-delimited (`&format=tab2`), or XML. Default is tab2.
+
+## Key Endpoints
+
+### 1. Search Interactions by Gene
+```
+GET https://webservice.thebiogrid.org/interactions?accesskey={key}&format=json&searchNames=true&geneList={gene_symbol}&taxId={taxon_id}
+```
+Example — get TP53 interactions in human:
+```
+GET https://webservice.thebiogrid.org/interactions?accesskey=YOUR_KEY&format=json&searchNames=true&geneList=TP53&taxId=9606&max=50
+```
+
+### 2. Multiple Genes
+```
+GET https://webservice.thebiogrid.org/interactions?accesskey={key}&format=json&geneList=BRCA1|BRCA2&taxId=9606&max=100
+```
+Separate gene names with `|` (pipe).
+
+### 3. Filter by Evidence Type
+```
+GET https://webservice.thebiogrid.org/interactions?accesskey={key}&format=json&geneList=TP53&taxId=9606&evidenceList=physical&max=50
+```
+Evidence types: `physical`, `genetic`.
+
+### 4. Filter by Experimental System
+```
+GET https://webservice.thebiogrid.org/interactions?accesskey={key}&format=json&geneList=TP53&taxId=9606&experimentalSystemList=Two-hybrid&max=50
+```
+Systems include: `Two-hybrid`, `Affinity Capture-MS`, `Co-fractionation`, `Reconstituted Complex`, `Synthetic Lethality`, `Dosage Rescue`, etc.
+
+### 5. Search by BioGRID Interaction ID
+```
+GET https://webservice.thebiogrid.org/interactions/{interaction_id}?accesskey={key}&format=json
+```
+
+### 6. Search by PubMed ID
+```
+GET https://webservice.thebiogrid.org/interactions?accesskey={key}&format=json&pubmedList=12345678
+```
+
+### 7. Inter-species Interactions
+```
+GET https://webservice.thebiogrid.org/interactions?accesskey={key}&format=json&geneList=TP53&taxId=9606&interSpeciesExcluded=false
+```
+
+### 8. Include Interactor Annotations
+```
+GET https://webservice.thebiogrid.org/interactions?accesskey={key}&format=json&geneList=TP53&taxId=9606&includeInteractors=true&max=50
+```
+
+## Common Query Parameters
+| Parameter | Description |
+|-----------|-------------|
+| `geneList` | Gene symbol(s), pipe-separated |
+| `taxId` | NCBI taxonomy ID (9606=human, 10090=mouse, 559292=yeast) |
+| `max` | Max results to return (default 10000) |
+| `start` | Offset for pagination |
+| `format` | `json`, `tab2`, `extendedTab2`, `count` |
+| `searchNames` | `true` to match official symbols |
+| `selfInteractionsExcluded` | `true` to exclude self-interactions |
+| `evidenceList` | `physical` or `genetic` |
+| `throughputTag` | `low` or `high` |
+
+## JSON Response Structure
+```json
+{
+  "12345": {
+    "BIOGRID_INTERACTION_ID": 12345,
+    "ENTREZ_GENE_A": "7157",
+    "ENTREZ_GENE_B": "672",
+    "OFFICIAL_SYMBOL_A": "TP53",
+    "OFFICIAL_SYMBOL_B": "BRCA1",
+    "EXPERIMENTAL_SYSTEM": "Two-hybrid",
+    "EXPERIMENTAL_SYSTEM_TYPE": "physical",
+    "PUBMED_ID": "9482880",
+    "ORGANISM_A": 9606,
+    "ORGANISM_B": 9606,
+    "THROUGHPUT": "Low Throughput",
+    "SCORE": "-"
+  }
+}
+```
+
+## Count-Only Query
+```
+GET https://webservice.thebiogrid.org/interactions?accesskey={key}&format=count&geneList=TP53&taxId=9606
+```
+Returns just the integer count.
+
+## Notes
+- BioGRID aggregates curated interaction data from literature.
+- Covers physical (protein-protein) and genetic interactions.
+- For bulk data, use BioGRID downloads (tab-delimited files) at https://downloads.thebiogrid.org/.
+- Cross-reference with STRING for combined interaction evidence.

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

@@ -0,0 +1,235 @@
+# Bureau of Labor Statistics (BLS) Public Data API
+
+## Base URL
+
+```
+https://api.bls.gov/publicAPI/v2
+```
+
+Version 1 (no key): `https://api.bls.gov/publicAPI/v1`
+
+## Authentication
+
+**API key optional but strongly recommended.** Register at https://data.bls.gov/registrationEngine/
+
+- **V1 (no key):** Limited to 25 requests/day, 10-year date range, 25 series per query.
+- **V2 (with key):** 500 requests/day, 20-year date range, 50 series per query, plus catalog data and calculations.
+
+## Key Endpoints
+
+### 1. Get Series Data (POST -- primary method)
+```
+POST /timeseries/data/
+```
+Content-Type: `application/json`
+
+**Request body:**
+```json
+{
+  "seriesid": ["CUUR0000SA0", "LNS14000000"],
+  "startyear": "2020",
+  "endyear": "2024",
+  "registrationkey": "YOUR_KEY",
+  "catalog": true,
+  "calculations": true,
+  "annualaverage": true,
+  "aspects": true
+}
+```
+
+| Field            | Required | V1  | V2  | Description                                          |
+|------------------|----------|-----|-----|------------------------------------------------------|
+| seriesid         | Yes      | Yes | Yes | Array of series IDs (max 25 v1 / 50 v2)            |
+| startyear        | Yes      | Yes | Yes | 4-digit start year                                  |
+| endyear          | Yes      | Yes | Yes | 4-digit end year                                    |
+| registrationkey  | No       | No  | Yes | API key (required for v2 features)                  |
+| catalog          | No       | No  | Yes | `true` to include series metadata                   |
+| calculations     | No       | No  | Yes | `true` to include net/pct changes                   |
+| annualaverage    | No       | No  | Yes | `true` to include annual averages                   |
+| aspects          | No       | No  | Yes | `true` to include footnotes and aspects             |
+
+### 2. Get Single Series Data (GET -- convenience)
+```
+GET /timeseries/data/{seriesID}
+```
+Example:
+```
+https://api.bls.gov/publicAPI/v2/timeseries/data/CUUR0000SA0?registrationkey=YOUR_KEY&startyear=2022&endyear=2024
+```
+
+### 3. Latest Data (GET -- no date range)
+```
+GET /timeseries/data/{seriesID}
+```
+Without startyear/endyear, returns the most recent 3 years.
+
+Example:
+```
+https://api.bls.gov/publicAPI/v2/timeseries/data/LNS14000000?registrationkey=YOUR_KEY
+```
+
+## Common Series IDs
+
+### Consumer Price Index (CPI)
+| Series ID       | Description                                       |
+|-----------------|---------------------------------------------------|
+| CUUR0000SA0     | CPI-U All Items, US City Avg, Not Seasonally Adj  |
+| CUSR0000SA0     | CPI-U All Items, US City Avg, Seasonally Adj      |
+| CUUR0000SAF1    | CPI-U Food, US City Avg                           |
+| CUUR0000SETB01  | CPI-U Gasoline (all types)                        |
+| CUUR0000SAH1    | CPI-U Shelter                                     |
+| CUUR0000SAM     | CPI-U Medical Care                                |
+
+CPI series ID structure: `CU` + `U/S` (unadj/adj) + `R/S` (revision) + area code + item code
+
+### Employment / Unemployment (Current Population Survey)
+| Series ID       | Description                                       |
+|-----------------|---------------------------------------------------|
+| LNS14000000     | Unemployment Rate (seasonally adjusted)            |
+| LNS11000000     | Civilian Labor Force Level                         |
+| LNS12000000     | Employment Level                                   |
+| LNS13000000     | Unemployment Level                                 |
+| LNS14000006     | Unemployment Rate - Black or African American      |
+| LNS14000009     | Unemployment Rate - Hispanic or Latino             |
+
+### Employment (Current Employment Statistics / Nonfarm Payrolls)
+| Series ID       | Description                                       |
+|-----------------|---------------------------------------------------|
+| CES0000000001   | Total Nonfarm Employment (seasonally adj)          |
+| CES0500000003   | Average Hourly Earnings, Total Private             |
+| CES0500000002   | Average Weekly Hours, Total Private                |
+
+### Producer Price Index (PPI)
+| Series ID       | Description                                       |
+|-----------------|---------------------------------------------------|
+| WPSFD4          | PPI Final Demand                                  |
+| WPUFD49104      | PPI Final Demand less Foods & Energy              |
+
+### Employment Cost Index (ECI)
+| Series ID       | Description                                       |
+|-----------------|---------------------------------------------------|
+| CIU1010000000000A | ECI Total Compensation, All Civilians           |
+
+### Occupational Employment & Wage Statistics (OEWS)
+| Series ID Pattern | Description                                     |
+|-------------------|-------------------------------------------------|
+| OEUM003342000000011-0000 | Example: specific occupation/area combo  |
+
+OEWS series IDs are complex. Use the BLS Series ID finder: https://data.bls.gov/cgi-bin/srgate
+
+## Series ID Structure
+
+BLS series IDs encode survey, seasonal adjustment, area, industry, and item information. Key survey prefixes:
+
+| Prefix | Survey                                          |
+|--------|------------------------------------------------|
+| CU     | Consumer Price Index                            |
+| LN     | Current Population Survey (Labor Force)         |
+| CE     | Current Employment Statistics                   |
+| WP     | Producer Price Index                            |
+| EI     | Employment Cost Index / National Compensation   |
+| OE     | Occupational Employment & Wage Statistics       |
+| LA     | Local Area Unemployment Statistics              |
+| SM     | State and Metro Area Employment (CES)           |
+| JT     | Job Openings and Labor Turnover (JOLTS)         |
+
+## Response Format
+
+### Standard response
+```json
+{
+  "status": "REQUEST_SUCCEEDED",
+  "responseTime": 85,
+  "message": [],
+  "Results": {
+    "series": [
+      {
+        "seriesID": "CUUR0000SA0",
+        "catalog": {
+          "series_title": "All items in U.S. city average, all urban consumers, not seasonally adjusted",
+          "series_id": "CUUR0000SA0",
+          "seasonality": "Not Seasonally Adjusted",
+          "survey_name": "Consumer Price Index - All Urban Consumers",
+          "survey_abbreviation": "CU",
+          "measure_data_type": "All items",
+          "area": "U.S. city average",
+          "item": "All items"
+        },
+        "data": [
+          {
+            "year": "2024",
+            "period": "M01",
+            "periodName": "January",
+            "latest": "true",
+            "value": "308.417",
+            "footnotes": [{}],
+            "calculations": {
+              "net_changes": {
+                "1": "0.5",
+                "3": "1.2",
+                "6": "2.1",
+                "12": "3.1"
+              },
+              "pct_changes": {
+                "1": "0.2",
+                "3": "0.4",
+                "6": "0.7",
+                "12": "3.1"
+              }
+            }
+          },
+          {
+            "year": "2023",
+            "period": "M12",
+            "periodName": "December",
+            "value": "306.746",
+            "footnotes": [{}]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Key fields in data objects
+- `year`: 4-digit year string
+- `period`: `M01`-`M12` (monthly), `Q01`-`Q05` (quarterly), `A01` (annual), `S01`-`S03` (semi-annual)
+- `periodName`: Human-readable period name
+- `value`: String (convert to float for calculations)
+- `latest`: `"true"` on the most recent observation only
+- `calculations`: Only present when `calculations: true` in request (V2). Contains `net_changes` and `pct_changes` over 1, 3, 6, 12 month spans.
+- `footnotes`: Array of footnote objects
+
+### Error response
+```json
+{
+  "status": "REQUEST_NOT_PROCESSED",
+  "responseTime": 10,
+  "message": ["No data available for the given series and date range."],
+  "Results": {
+    "series": []
+  }
+}
+```
+
+## Rate Limits
+
+| Feature             | V1 (no key)     | V2 (with key)    |
+|---------------------|-----------------|------------------|
+| Daily query limit   | 25 requests     | 500 requests     |
+| Series per query    | 25              | 50               |
+| Years per query     | 10              | 20               |
+| Catalog data        | No              | Yes              |
+| Calculations        | No              | Yes              |
+| Annual averages     | No              | Yes              |
+| Net/pct changes     | No              | Yes              |
+
+## Notes
+
+- BLS strongly prefers POST requests for data retrieval. The GET endpoint is a convenience wrapper.
+- Period `M13` represents the annual average (only present when `annualaverage: true`).
+- All `value` fields are strings. Missing data is typically omitted (the observation simply won't appear).
+- For CPI percent change (inflation rate), you can either calculate from raw index values or use the V2 `calculations` feature which provides pre-computed 12-month percent changes.
+- The BLS website has a Series ID finder tool for constructing IDs: https://data.bls.gov/cgi-bin/srgate
+- Bulk data is available for download at https://download.bls.gov/pub/time.series/ organized by survey prefix.

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

@@ -0,0 +1,71 @@
+# BRENDA Enzyme Database (SOAP API)
+
+## Important: BRENDA uses SOAP, not REST. Requires Python with `zeep` library.
+
+## SOAP Endpoint
+```
+https://www.brenda-enzymes.org/soap/brenda_zeep.wsdl
+```
+
+## Auth
+Free registration required at https://www.brenda-enzymes.org/register.php
+Credentials (email + SHA-256 hashed password) passed with every call.
+
+## Key SOAP Methods
+
+All methods take `email`, `password` (SHA-256), and `ecNumber` as base parameters.
+
+| Method | Description |
+|--------|-------------|
+| `getKmValue` | Michaelis constant (Km) |
+| `getTurnoverNumber` | Turnover number (kcat) |
+| `getKcatKmValue` | Catalytic efficiency (kcat/Km) |
+| `getKiValue` | Inhibition constant (Ki) |
+| `getIc50Value` | IC50 values |
+| `getSpecificActivity` | Specific activity |
+| `getPhOptimum` | pH optimum |
+| `getTemperatureOptimum` | Temperature optimum |
+| `getSubstrate` | Substrates |
+| `getProduct` | Products |
+| `getInhibitors` | Inhibitors |
+| `getCofactor` | Cofactors |
+| `getOrganism` | Source organisms |
+| `getReaction` | Reaction equations |
+| `getSequence` | Protein sequences |
+| `getDisease` | Associated diseases |
+
+## Parameter Syntax
+`fieldName*value` format. Empty value = return all.
+
+```
+ecNumber*1.1.1.1           # Required: EC number
+organism*Homo sapiens      # Optional: filter by organism
+substrate*ethanol          # Optional: filter by substrate
+kmValue*                   # Return field (empty = all)
+```
+
+## Python Example
+```python
+import hashlib
+from zeep import Client
+
+client = Client("https://www.brenda-enzymes.org/soap/brenda_zeep.wsdl")
+email = "your@email.com"
+password = hashlib.sha256("your_password".encode()).hexdigest()
+
+# Get Km values for alcohol dehydrogenase
+result = client.service.getKmValue(
+    email, password,
+    "ecNumber*1.1.1.1", "organism*Homo sapiens",
+    "kmValue*", "substrate*", "literature*"
+)
+```
+
+## Response Format
+Returns string parsed with `!` (record separator) and `#`/`*` (field separators). Must be parsed manually.
+
+## Rate Limits
+No published limits. SOAP responses can take 1-5 seconds. Be respectful — free academic service.
+
+## Note for this skill
+Since BRENDA uses SOAP (not REST), making calls requires writing and executing a Python script with `zeep`. Use Bash to run the script rather than WebFetch.