@pikaa-ai/pikaa 0.2.4 → 0.3.0

package/skills/database-lookup/references/clinicaltrials.md

@@ -0,0 +1,86 @@
+# ClinicalTrials.gov (v2 API)
+
+## Base URL
+```
+https://clinicaltrials.gov/api/v2/
+```
+
+## Auth
+No API key required. Fully public.
+
+## Key Endpoints
+
+### API version and data freshness
+```
+GET /version
+```
+
+Check `dataTimestamp` before time-sensitive retrievals to confirm the daily refresh has completed. ClinicalTrials.gov notes that data is generally refreshed Monday through Friday by 9 a.m. ET / 14:00 UTC.
+
+ClinicalTrials.gov modernized its data ingest on August 26, 2025. For reproducible comparisons against older exports, note that some rich text markup fields and location/geopoint data may differ from the legacy pipeline.
+
+### Search studies
+```
+GET /studies
+```
+
+Key parameters:
+- `query.cond` — condition/disease (e.g. `breast cancer`)
+- `query.intr` — intervention/treatment (e.g. `pembrolizumab`)
+- `query.term` — general search terms
+- `query.spons` — sponsor
+- `query.id` — NCT ID
+- `filter.overallStatus` — pipe-delimited: `RECRUITING|COMPLETED|ACTIVE_NOT_RECRUITING|...`
+- `filter.phase` — `PHASE1|PHASE2|PHASE3|PHASE4|NA`
+- `filter.geo` — `distance(lat,lon,dist)` e.g. `distance(38.89,-77.03,50mi)`
+- `fields` — comma-separated field list to reduce payload
+- `sort` — e.g. `LastUpdatePostDate:desc`
+- `pageSize` — results per page (default 10, max 1000)
+- `pageToken` — cursor for next page (from `nextPageToken` in response)
+- `countTotal=true` — include total count
+
+Example — recruiting Phase 3 breast cancer trials:
+```
+/studies?query.cond=breast+cancer&filter.overallStatus=RECRUITING&filter.phase=PHASE3&pageSize=5&countTotal=true
+```
+
+Response structure:
+```json
+{
+  "totalCount": 1234,
+  "studies": [
+    {
+      "protocolSection": {
+        "identificationModule": {"nctId": "NCT05123456", "briefTitle": "..."},
+        "statusModule": {"overallStatus": "RECRUITING"},
+        "designModule": {"phases": ["PHASE3"], "enrollmentInfo": {"count": 500}},
+        "conditionsModule": {"conditions": ["Breast Cancer"]},
+        "eligibilityModule": {"minimumAge": "18 Years", "sex": "ALL"}
+      }
+    }
+  ],
+  "nextPageToken": "CAYQAg"
+}
+```
+
+### Single study by NCT ID
+```
+GET /studies/{nctId}
+```
+Example: `/studies/NCT05123456`
+
+### Study count
+```
+GET /stats/size?query.cond={condition}&filter.overallStatus=RECRUITING
+```
+
+### Field metadata
+```
+GET /studies/metadata
+```
+
+## Pagination
+Uses cursor-based pagination via `pageToken` (NOT numeric offsets). Include `countTotal=true` on first request to get total.
+
+## Rate Limits
+No API key. Be reasonable — a few requests per second. Bulk: https://clinicaltrials.gov/AllAPIJSON.zip

package/skills/database-lookup/references/clinpgx.md

@@ -0,0 +1,64 @@
+# PharmGKB (Clinical Pharmacogenomics)
+
+## Base URL
+```
+https://api.pharmgkb.org/v1/data/
+```
+
+## Auth
+No API key required for read-only access.
+
+## Key Endpoints
+
+### General search
+```
+GET https://api.pharmgkb.org/v1/search?q={term}&page=0&size=10
+```
+
+### Gene data
+```
+GET /gene?symbol={symbol}
+```
+Example: `/gene?symbol=CYP2D6`
+
+Response includes: id, symbol, chromosome, hasGuideline, hasClinicalAnnotation, cpicGene
+
+### Drug data
+```
+GET /drug?name={name}
+```
+Example: `/drug?name=warfarin`
+
+Response includes: id, name, genericNames, tradeNames, rxNormId, atcCodes
+
+### Clinical annotations (drug-gene interactions)
+```
+GET /clinicalAnnotation?gene={symbol}&drug={name}&level={level}
+```
+
+Evidence levels: `1A`, `1B`, `2A`, `2B`, `3`, `4`
+
+Example:
+```
+/clinicalAnnotation?gene=CYP2C19&drug=clopidogrel&level=1A
+```
+
+Response includes: level, gene, drug, phenotype, significance, variants, url
+
+### CPIC/DPWG guidelines
+```
+GET /guideline?gene={symbol}&drug={name}&source=CPIC
+```
+
+### Pharmacokinetic pathways
+```
+GET /pathway?drug={name}
+```
+
+### Drug labels (FDA, EMA)
+```
+GET /drugLabel?drug={name}&source=FDA
+```
+
+## Rate Limits
+No hard published limit. Be reasonable. Bulk data via PharmGKB download page.

package/skills/database-lookup/references/clinvar.md

@@ -0,0 +1,91 @@
+# ClinVar API Reference
+
+## Base URLs
+- **NCBI E-utilities**: `https://eutils.ncbi.nlm.nih.gov/entrez/eutils`
+- **ClinVar web API (VCV)**: `https://www.ncbi.nlm.nih.gov/clinvar`
+- **NCBI Variation Services**: `https://api.ncbi.nlm.nih.gov/variation/v0`
+
+## Authentication
+- E-utilities: No key required, but **strongly recommended**. Register at https://www.ncbi.nlm.nih.gov/account/ to get an `api_key`.
+- Without key: 3 requests/second. With key: 10 requests/second.
+- Append `&api_key=YOUR_KEY` to all E-utility requests.
+
+## Rate Limits
+- Without API key: 3 req/sec
+- With API key: 10 req/sec
+
+## Key Endpoints
+
+### 1. Search ClinVar (esearch)
+```
+GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=clinvar&term={query}&retmode=json
+```
+Example — search for BRCA1 pathogenic variants:
+```
+GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=clinvar&term=BRCA1[gene]+AND+pathogenic[clinical_significance]&retmode=json&retmax=10
+```
+Returns JSON with `idlist` of ClinVar Variation IDs.
+
+### 2. Fetch ClinVar Records (esummary)
+```
+GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=clinvar&id={id_list}&retmode=json
+```
+Example:
+```
+GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=clinvar&id=37088,37087&retmode=json
+```
+Returns JSON with clinical significance, variant name, gene, conditions, review status.
+
+### 3. Full Record (efetch)
+```
+GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=clinvar&id={id}&rettype=vcv&is_variationid&retmode=xml
+```
+Note: ClinVar efetch returns **XML only** (no JSON for efetch).
+
+### 4. Variation Services API — SPDI/HGVS Lookup
+```
+GET https://api.ncbi.nlm.nih.gov/variation/v0/spdi/{spdi_expression}/clinvar
+GET https://api.ncbi.nlm.nih.gov/variation/v0/hgvs/{hgvs_expression}/clinvar
+```
+Example:
+```
+GET https://api.ncbi.nlm.nih.gov/variation/v0/hgvs/NM_007294.4%3Ac.5266dupC/clinvar
+```
+
+### 5. ClinVar VCV/RCV Direct Access
+```
+GET https://www.ncbi.nlm.nih.gov/clinvar/variation/{variation_id}/?redir=vcv
+```
+This returns HTML. For programmatic access, use E-utilities or the Variation Services API.
+
+## Useful Search Qualifiers
+- `[gene]` — gene symbol (e.g., `BRCA1[gene]`)
+- `[clinical_significance]` — pathogenic, likely_pathogenic, benign, uncertain_significance
+- `[molecular_consequence]` — missense, nonsense, frameshift, etc.
+- `[review_status]` — criteria_provided_single_submitter, reviewed_by_expert_panel, etc.
+- `[condition]` — disease name
+
+## Response Format
+- esearch/esummary: JSON (with `retmode=json`)
+- efetch: XML only for ClinVar
+- Variation Services: JSON
+
+## esummary Response Key Fields
+```json
+{
+  "result": {
+    "37088": {
+      "uid": "37088",
+      "title": "NM_007294.4(BRCA1):c.5266dupC (p.Gln1756Profs*74)",
+      "clinical_significance": { "description": "Pathogenic" },
+      "genes": [{"symbol": "BRCA1", "geneid": 672}],
+      "variation_set": [...],
+      "trait_set": [{"trait_name": "Hereditary breast and ovarian cancer syndrome"}]
+    }
+  }
+}
+```
+
+## Notes
+- Combine esearch + esummary for search-then-fetch workflows.
+- For bulk downloads, use ClinVar FTP: https://ftp.ncbi.nlm.nih.gov/pub/clinvar/

package/skills/database-lookup/references/cod.md

@@ -0,0 +1,121 @@
+# Crystallography Open Database (COD) API
+
+## Base URL
+
+```
+https://www.crystallography.net/cod
+```
+
+## Authentication
+
+**None required.** COD is fully open-access with no API key needed.
+
+## Key Endpoints
+
+### Search by formula
+
+```
+GET /result?formula=Fe2%20O3&format=json
+```
+
+Formula format uses spaces between elements: `Fe2 O3`, `Si O2`, `C6 H12 O6`. URL-encode spaces as `%20`.
+
+### Search by elements
+
+```
+GET /result?el1=Fe&el2=O&format=json
+```
+
+Use `el1`, `el2`, `el3`, etc. for element filters. Use `nel=2` to restrict to exactly 2 elements.
+
+### Search by cell parameters
+
+```
+GET /result?a_min=5.0&a_max=6.0&b_min=5.0&b_max=6.0&c_min=5.0&c_max=6.0&format=json
+```
+
+Cell parameter filters:
+- `a_min`, `a_max` — a-axis length (Angstroms)
+- `b_min`, `b_max` — b-axis length
+- `c_min`, `c_max` — c-axis length
+- `alpha_min`, `alpha_max` — alpha angle (degrees)
+- `beta_min`, `beta_max` — beta angle
+- `gamma_min`, `gamma_max` — gamma angle
+- `vol_min`, `vol_max` — unit cell volume (A^3)
+
+### Search by space group
+
+```
+GET /result?sg=F%20m%20-3%20m&format=json
+```
+
+### Search by text (author, journal, title)
+
+```
+GET /result?text=perovskite&format=json
+```
+
+### Combined search example
+
+```
+GET /result?el1=Ti&el2=O&nel=2&sg=P%2042/m%20n%20m&format=json
+```
+
+### Retrieve a specific CIF file
+
+```
+GET /1000000.cif
+```
+
+COD IDs are 7-digit integers. Append `.cif` for the crystallographic information file, or `.html` for the web page.
+
+### Retrieve entry metadata as JSON
+
+```
+GET /result?id=1000000&format=json
+```
+
+### Output formats
+
+- `format=json` — JSON array of matching entries
+- `format=csv` — CSV output
+- `format=lst` — list of COD IDs only
+- Default (no format) — HTML page
+
+## Response Format
+
+```json
+[
+  {
+    "file": "1526463",
+    "a": "4.759",
+    "b": "4.759",
+    "c": "12.992",
+    "alpha": "90",
+    "beta": "90",
+    "gamma": "120",
+    "vol": "254.94",
+    "sg": "R -3 c",
+    "formula": "Fe2 O3",
+    "title": "Refinement of the crystal structure of ...",
+    "journal": "Zeitschrift fuer Kristallographie",
+    "year": "1966",
+    "authors": "Blake, R.L.; et al."
+  }
+]
+```
+
+The `file` field is the COD ID. Use it to fetch the CIF: `https://www.crystallography.net/cod/{file}.cif`
+
+## Rate Limits
+
+- No formal rate limits documented
+- Be courteous: avoid bulk-downloading thousands of entries rapidly
+- For bulk access, COD provides downloadable database dumps at https://www.crystallography.net/cod/archives/
+
+## Notes
+
+- COD contains ~500,000+ crystal structures from published literature
+- All data is open-access under public domain / open licenses
+- The search API returns metadata; use the CIF endpoint for full structural data
+- Alternative access: MySQL database dumps and SVN access are available for bulk use

package/skills/database-lookup/references/cosmic.md

@@ -0,0 +1,59 @@
+# COSMIC (Catalogue of Somatic Mutations in Cancer)
+
+## Base URL
+```
+https://cancer.sanger.ac.uk/cosmic/api/v1/
+```
+
+## Auth
+**Registration required.** Free academic account or paid commercial license.
+
+Login to get JWT token:
+```
+POST /auth/login
+Content-Type: application/json
+{"email": "you@example.com", "password": "yourpassword"}
+```
+Pass token as: `Authorization: Bearer <token>`
+
+## Key Endpoints
+
+### Search mutations by gene
+```
+GET /mutations/search?q={gene_symbol}&page=1&page_size=5
+```
+
+### Get gene information
+```
+GET /genes/{gene_symbol}
+```
+Example: `/genes/BRAF`
+
+Response includes: gene_symbol, gene_name, chromosome, cancer_census (bool), tier, mutation_count, sample_count
+
+### Get specific mutation by COSMIC ID
+```
+GET /mutations/{cosmic_mutation_id}
+```
+Example: `/mutations/COSV56056643`
+
+Response includes: gene, cds_mutation, aa_mutation, mutation_type, fathmm_prediction, genomic_coordinates, tissue_distribution
+
+### Cancer Gene Census
+```
+GET /cancer-gene-census?tier=1&page_size=10
+```
+
+### Mutations by tissue/histology
+```
+GET /mutations/distribution/{gene_symbol}
+```
+
+## Rate Limits
+Not officially published. Bulk data requires SFTP download (licensed).
+
+## Important
+- COSMIC requires authentication for all API calls
+- Commercial use requires a paid license
+- Bulk data access via SFTP is preferred over API for large queries
+- API structure may change across COSMIC versions

package/skills/database-lookup/references/dailymed.md

@@ -0,0 +1,65 @@
+# DailyMed (NIH/NLM Drug Labels)
+
+## Base URL
+```
+https://dailymed.nlm.nih.gov/dailymed/services/
+```
+
+## Auth
+No API key required.
+
+## Key Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `v2/spls.json?drug_name={name}` | Search drug labels by name |
+| `v2/spls/{setid}.json` | Get label metadata by SetID |
+| `v2/spls/{setid}/ndcs.json` | NDC codes for a label |
+| `v2/spls/{setid}/media.json` | Images/media for a label |
+| `v2/drugnames.json?drug_name={prefix}` | Drug name autocomplete |
+| `v2/drugclasses.json?drug_class_name={name}` | Search by pharmacologic class |
+| `v2/rxcuis.json?drug_name={name}` | RxNorm CUIs for a drug |
+| `v2/ndc/{ndc_code}/spls.json` | Find labels by NDC code |
+
+## Additional filters for `/v2/spls.json`
+- `drug_class` — pharmacologic class
+- `labeler` — manufacturer name
+- `page` / `pagesize` — pagination (max 100)
+
+## Example Calls
+
+```
+# Search metformin labels
+https://dailymed.nlm.nih.gov/dailymed/services/v2/spls.json?drug_name=metformin
+
+# Drug name autocomplete
+https://dailymed.nlm.nih.gov/dailymed/services/v2/drugnames.json?drug_name=ator
+
+# Search by pharmacologic class
+https://dailymed.nlm.nih.gov/dailymed/services/v2/spls.json?drug_class=HMG-CoA+Reductase+Inhibitor
+
+# Full label XML (SPL content with sections)
+https://dailymed.nlm.nih.gov/dailymed/services/v2/spls/{setid}/packaging.xml
+```
+
+## Response Format
+```json
+{
+  "metadata": {
+    "total_elements": 12,
+    "elements_per_page": 10,
+    "current_page": 1,
+    "total_pages": 2
+  },
+  "data": [
+    {
+      "published_date": "2024-01-15",
+      "title": "METFORMIN HYDROCHLORIDE tablet",
+      "setid": "b03f295f-..."
+    }
+  ]
+}
+```
+
+## Rate Limits
+No published limits. Be reasonable.

package/skills/database-lookup/references/database_selection_guide.md

@@ -0,0 +1,166 @@
+# Database Selection Guide
+
+Which database answers which question, grouped by domain: physics and astronomy, earth and
+environmental sciences, chemistry and drugs, materials science and crystallography,
+biology and genomics, disease and clinical, patents and regulatory, economics and finance,
+social sciences and demographics, and cross-domain queries.
+
+## Database Selection Guide
+
+Match the user's intent to the right database(s). Many queries benefit from hitting multiple databases.
+
+### Physics & Astronomy
+| User is asking about... | Primary database(s) | Also consider |
+|---|---|---|
+| Near-Earth objects, asteroids | NASA (NeoWs) | — |
+| Mars rover images | NASA (Mars Rover Photos) | — |
+| Exoplanets, orbital parameters | NASA Exoplanet Archive | — |
+| Astronomical objects by name/coordinates | SIMBAD | SDSS |
+| Galaxy/star spectra, photometry | SDSS | SIMBAD |
+| Physical constants | NIST | — |
+| Atomic spectra, spectral lines | NIST (ASD) | — |
+
+### Earth & Environmental Sciences
+| User is asking about... | Primary database(s) | Also consider |
+|---|---|---|
+| Earthquakes, seismic events | USGS Earthquakes | — |
+| Water data, streamflow, groundwater | USGS Water Services | — |
+| Weather (current, forecast, historical) | OpenWeatherMap | NOAA |
+| Climate data, historical weather stations | NOAA (CDO) | — |
+| Air quality, toxic releases | EPA (Envirofacts) | — |
+
+### Chemistry & Drugs
+| User is asking about... | Primary database(s) | Also consider |
+|---|---|---|
+| Chemical compounds, molecules | PubChem | ChEMBL |
+| Molecular properties (weight, formula, SMILES) | PubChem | — |
+| Drug synonyms, CAS numbers | PubChem (synonyms) | DrugBank |
+| Bioactivity data, IC50, binding assays | ChEMBL | BindingDB, PubChem |
+| Drug binding affinities (Ki, IC50, Kd) | ChEMBL, BindingDB | PubChem |
+| Drug-target interactions | ChEMBL, DrugBank | BindingDB, Open Targets |
+| Ligands for a protein target (by UniProt) | BindingDB | ChEMBL |
+| Target identification from compound structure | BindingDB (SMILES similarity) | ChEMBL |
+| Drug labels, adverse events, recalls | FDA (OpenFDA) | DailyMed |
+| Drug labels (structured product labels) | DailyMed | FDA (OpenFDA) |
+| Drug pharmacology, indications | DrugBank | FDA |
+| Chemical cross-referencing | PubChem (xrefs) | ChEMBL |
+| Commercially available compounds for screening | ZINC | PubChem |
+| Similarity/substructure search (purchasable) | ZINC | PubChem, ChEMBL |
+| Drug-like compound libraries, building blocks | ZINC | — |
+| FDA-approved drug structures | ZINC (fda subset) | PubChem, FDA |
+| Compound purchasability, vendor catalogs | ZINC | — |
+
+### Materials Science & Crystallography
+| User is asking about... | Primary database(s) | Also consider |
+|---|---|---|
+| Materials by formula or elements | Materials Project | COD |
+| Band gap, electronic structure | Materials Project | — |
+| Crystal structures, CIF files | COD | Materials Project |
+| Elastic/mechanical properties | Materials Project | — |
+| Formation energy, thermodynamics | Materials Project | — |
+| Cell parameters, space groups | COD | Materials Project |
+
+### Biology & Genomics
+| User is asking about... | Primary database(s) | Also consider |
+|---|---|---|
+| Biological pathways | Reactome, KEGG | — |
+| What pathways a gene/protein is in | Reactome (mapping), KEGG | — |
+| Enzyme kinetics, catalytic activity | BRENDA | KEGG |
+| Metabolomics studies, metabolite profiles | Metabolomics Workbench | PubChem |
+| m/z or exact mass lookup | Metabolomics Workbench (moverz/exactmass) | PubChem |
+| Protein sequence, function, annotation | UniProt | Ensembl |
+| Protein-protein interactions | STRING | BioGRID |
+| Gene information, genomic location | NCBI Gene | Ensembl |
+| Genome sequences, variants, transcripts | Ensembl | NCBI Gene |
+| Gene expression datasets | GEO (NCBI E-utilities) | — |
+| Gene expression across tissues | GTEx | Human Protein Atlas |
+| Gene expression signatures (CMap/L1000) | LINCS L1000 | GEO |
+| Gene set enrichment vs GEO | RummaGEO | GEO |
+| Protein sequences (NCBI) | NCBI Protein | UniProt |
+| Taxonomic classification | NCBI Taxonomy | — |
+| SNP/variant data (dbSNP) | dbSNP | ClinVar, gnomAD |
+| Population variant frequencies | gnomAD | dbSNP |
+| Sequencing run metadata | SRA | ENA, GEO |
+| Nucleotide sequences (European archive) | ENA | SRA, NCBI Gene |
+| Genome assemblies, raw reads (European) | ENA | SRA, Ensembl |
+| Cross-references from sequence accessions | ENA (xref) | NCBI Gene, UniProt |
+| Viral sequence datasets with NCBI Virus-style filters | `gget virus` deterministic layer | SRA, ENA, NCBI Protein |
+| Genome annotations, tracks | UCSC Genome Browser | Ensembl |
+| 3D protein structures (experimental) | PDB (RCSB) | EMDB |
+| 3D protein structures (predicted) | AlphaFold DB | PDB |
+| EM maps, cryo-EM structures | EMDB | PDB |
+| Protein families, domains | InterPro | UniProt |
+| Chemical entities (biological) | ChEBI | PubChem |
+| Protein/genetic interactions | BioGRID | STRING |
+| Gene function annotations (GO terms) | QuickGO | Gene Ontology |
+| Regulatory elements, ChIP-seq, ATAC-seq | ENCODE | — |
+| TF binding profiles/motifs | JASPAR | ENCODE |
+| Protein expression across tissues | Human Protein Atlas | UniProt |
+| Single-cell atlas projects | Human Cell Atlas | — |
+| Proteomics datasets | PRIDE | — |
+| Mouse gene data | MouseMine | NCBI Gene |
+| Plasmid repository | Addgene | — |
+
+**Organism/species matters.** Most biology databases cover multiple organisms. If the user's query is about a specific organism, pass it explicitly — don't assume human. Common patterns: Ensembl uses `{species}` in the URL path (e.g. `homo_sapiens`), STRING/BioGRID/QuickGO use NCBI taxon IDs (`species=9606` for human, `10090` for mouse), UniProt uses `organism_id:9606` in search queries, KEGG uses organism codes (`hsa`, `mmu`). GTEx and Human Protein Atlas are human-only. Check the reference file for each database's specific parameter.
+
+**Viral sequence retrieval is high risk.** For NCBI Virus-style requests with filters such as host, geography, collection dates, sequence length, completeness, ambiguous bases, segment, lab passage, source database, or protein annotation, prefer the `gget` skill's `gget virus` deterministic retrieval layer over hand-assembling browser or API workflows. If you must use SRA/ENA/NCBI APIs directly, document which filters were enforced server-side and which were validated locally, then reconcile final accession counts.
+
+### Disease & Clinical
+| User is asking about... | Primary database(s) | Also consider |
+|---|---|---|
+| Somatic mutations in cancer | COSMIC | Open Targets, cBioPortal |
+| Cancer genomics (TCGA) | GDC (TCGA) | COSMIC, cBioPortal |
+| Cancer study mutations, CNA, expression | cBioPortal | GDC (TCGA), COSMIC |
+| Tumor clinical data (survival, staging) | cBioPortal | GDC (TCGA) |
+| Drug-target-disease associations | Open Targets | ChEMBL |
+| Gene-disease associations | DisGeNET | Open Targets, Monarch |
+| Mendelian disease-gene relationships | OMIM | NCBI Gene |
+| Variant clinical significance | ClinVar (NCBI) | OMIM |
+| GWAS SNP-trait associations | GWAS Catalog | — |
+| Disease-phenotype-gene links | Monarch Initiative | HPO |
+| Phenotype ontology, HPO terms | HPO | Monarch |
+| Pharmacogenomics, drug-gene interactions | ClinPGx (PharmGKB) | DrugBank |
+| Clinical trials for a drug/disease | ClinicalTrials.gov | FDA |
+| Disease-related expression data | GEO | Open Targets |
+
+### Patents & Regulatory
+| User is asking about... | Primary database(s) | Also consider |
+|---|---|---|
+| Patents by keyword or technology | USPTO (PatentsView) | — |
+| Patents by inventor or assignee | USPTO (PatentsView) | — |
+| Patent prosecution status | USPTO (PEDS) | — |
+| Trademark lookup | USPTO (TSDR) | — |
+| SEC company filings, 10-K, 10-Q | SEC EDGAR | — |
+
+### Economics & Finance
+| User is asking about... | Primary database(s) | Also consider |
+|---|---|---|
+| US economic time series (GDP, CPI, rates) | FRED | BEA |
+| Employment, wages, labor statistics | BLS | FRED |
+| GDP, national accounts | BEA | FRED, World Bank |
+| International development indicators | World Bank | FRED |
+| Interest rates, money supply | Federal Reserve | FRED |
+| Euro exchange rates, ECB monetary stats | ECB | — |
+| US debt, yield curves, fiscal data | US Treasury | FRED |
+| Stock prices, forex, crypto | Alpha Vantage | — |
+| Statistical data across many topics | Data Commons | — |
+
+### Social Sciences & Demographics
+| User is asking about... | Primary database(s) | Also consider |
+|---|---|---|
+| US population, housing, income data | US Census | Data Commons |
+| EU statistics (economy, trade, health) | Eurostat | World Bank |
+| Global health indicators (mortality, disease) | WHO GHO | World Bank |
+
+### Cross-domain queries
+| User is asking about... | Primary database(s) | Also consider |
+|---|---|---|
+| Everything about a compound | PubChem + ChEMBL + DrugBank | BindingDB, ZINC, Reactome, FDA |
+| Everything about a gene | NCBI Gene + UniProt + Ensembl | Reactome, STRING, COSMIC, cBioPortal, ENA |
+| Everything about a variant | dbSNP + ClinVar + gnomAD | GWAS Catalog, COSMIC, cBioPortal |
+| Drug target pathways | ChEMBL + Reactome | Open Targets, GEO |
+| Prior art for a chemical invention | USPTO + PubChem | ChEMBL |
+| Everything about a material | Materials Project + COD | — |
+| US economic overview | FRED + BLS + BEA | Federal Reserve |
+
+When the user's query spans multiple domains (e.g. "what do we know about aspirin" or "find everything about BRCA1"), rank sources by authority and start with the 2-3 databases most likely to answer the question. Add more databases only when the first pass leaves a specific gap. Keep at most 5 independent API requests in flight at once.