clearai-dsh 0.1.0

package/presets/clearai/template/skills/paper-lookup/references/medrxiv.md

@@ -0,0 +1,104 @@
+# medRxiv API
+
+medRxiv is a preprint server for health sciences. The API is identical to bioRxiv's API -- same endpoints, same response format -- just use `medrxiv` as the server parameter.
+
+**Important:** Like bioRxiv, there is **no keyword search**. Use Semantic Scholar, OpenAlex, or PubMed for keyword searches of medRxiv content.
+
+## Base URL
+
+```
+https://api.biorxiv.org
+```
+
+(Same base URL as bioRxiv -- the server is specified in the path.)
+
+## Authentication
+
+None required. Fully public API.
+
+## Key Endpoints
+
+### 1. Content Detail -- Browse by date range
+
+```
+GET /details/medrxiv/{interval}/{cursor}/{format}
+```
+
+| Parameter | Values | Description |
+|-----------|--------|-------------|
+| `interval` | `YYYY-MM-DD/YYYY-MM-DD` | Date range (inclusive) |
+| | `N` (integer) | N most recent preprints |
+| | `Nd` (integer + "d") | Last N days |
+| `cursor` | Integer (default `0`) | Pagination offset (100 per page) |
+| `format` | `json` (default), `xml` | Response format |
+
+Optional: `?category=cardiovascular%20medicine` (use URL-encoding for spaces)
+
+**Examples:**
+```
+https://api.biorxiv.org/details/medrxiv/2024-01-01/2024-01-31/0
+https://api.biorxiv.org/details/medrxiv/5
+https://api.biorxiv.org/details/medrxiv/10d
+```
+
+### 2. Content Detail -- DOI lookup
+
+```
+GET /details/medrxiv/{doi}/na/{format}
+```
+
+**Example:**
+```
+https://api.biorxiv.org/details/medrxiv/10.1101/2021.04.29.21256344/na/json
+```
+
+### 3. Published Article Links
+
+```
+GET /pubs/medrxiv/{interval}/{cursor}
+GET /pubs/medrxiv/{doi}/na
+```
+
+Links preprints to their published journal versions. Accepts both preprint DOI and published DOI.
+
+## Response Format
+
+Same as bioRxiv:
+
+```json
+{
+  "messages": [{
+    "status": "ok",
+    "count": 100,
+    "total": "502",
+    "cursor": 0
+  }],
+  "collection": [{
+    "title": "Paper title...",
+    "authors": "Surname, A.; Surname, B.",
+    "author_corresponding": "Full Name",
+    "author_corresponding_institution": "Institution",
+    "doi": "10.1101/2021.04.29.21256344",
+    "date": "2021-05-03",
+    "version": "1",
+    "type": "PUBLISHAHEADOFPRINT",
+    "license": "cc_by_nc_nd",
+    "category": "cardiovascular medicine",
+    "abstract": "Full abstract text...",
+    "published": "10.1371/journal.pone.0256482",
+    "server": "medRxiv"
+  }]
+}
+```
+
+## Pagination
+
+100 results per page. Use `cursor` parameter to paginate.
+
+## Rate Limits
+
+No documented rate limits. No authentication required.
+
+## Categories
+
+`addiction-medicine`, `allergy-and-immunology`, `anesthesia`, `cardiovascular-medicine`, `dentistry-and-oral-medicine`, `dermatology`, `emergency-medicine`, `endocrinology`, `epidemiology`, `forensic-medicine`, `gastroenterology`, `genetic-and-genomic-medicine`, `geriatric-medicine`, `health-economics`, `health-informatics`, `health-policy`, `health-systems-and-quality-improvement`, `hematology`, `hiv-aids`, `infectious-diseases`, `intensive-care-and-critical-care-medicine`, `medical-education`, `medical-ethics`, `nephrology`, `neurology`, `nursing`, `nutrition`, `obstetrics-and-gynecology`, `occupational-and-environmental-health`, `oncology`, `ophthalmology`, `orthopedics`, `otolaryngology`, `pain-medicine`, `palliative-medicine`, `pathology`, `pediatrics`, `pharmacology-and-therapeutics`, `primary-care-research`, `psychiatry-and-clinical-psychology`, `public-and-global-health`, `radiology-and-imaging`, `rehabilitation-medicine-and-physical-therapy`, `respiratory-medicine`, `rheumatology`, `sexual-and-reproductive-health`, `sports-medicine`, `surgery`, `toxicology`, `transplantation`, `urology`

package/presets/clearai/template/skills/paper-lookup/references/openalex.md

@@ -0,0 +1,174 @@
+# OpenAlex API
+
+OpenAlex is a comprehensive index of 250M+ scholarly works, authors, institutions, sources, and topics. It's the broadest multidisciplinary database in this skill.
+
+## Base URL
+
+```
+https://api.openalex.org
+```
+
+## Authentication
+
+- **API key recommended** (free). Get one at https://openalex.org/settings/api
+- Pass as: `?api_key=YOUR_KEY`
+- Legacy polite pool still works: add `?mailto=you@example.com` for better rate limits
+
+## Rate Limits
+
+- **100 requests/second** max
+- Usage-based pricing with $1/day free allowance
+- Single entity lookups by ID/DOI are free (unlimited)
+- List + filter queries: ~$0.0001 each (~10,000/day free)
+- Search queries: ~$0.001 each (~1,000/day free)
+
+## Key Endpoints
+
+### 1. Get a single work
+
+```
+GET /works/{id}
+```
+
+Accepts multiple ID formats:
+```
+/works/W2741809807                              (OpenAlex ID)
+/works/doi:10.7717/peerj.4375                  (DOI)
+/works/pmid:29456894                            (PMID)
+/works/https://doi.org/10.7717/peerj.4375      (full DOI URL)
+```
+
+### 2. Search works
+
+```
+GET /works?search={query}&per_page={n}&page={n}
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `search` | -- | Full-text search (title, abstract, fulltext). Supports boolean: `AND`, `OR`, `NOT` (uppercase) |
+| `search.exact` | -- | No stemming |
+| `search.semantic` | -- | AI embedding search (beta, 1 req/s, max 50 results) |
+| `filter` | -- | Comma-separated `field:value` pairs |
+| `sort` | relevance | `cited_by_count:desc`, `publication_date:desc`, `relevance_score:desc` |
+| `per_page` | 25 | Results per page (max 100) |
+| `page` | 1 | Page number (max `page * per_page` = 10,000) |
+| `cursor` | -- | Use `*` for first page of deep pagination |
+| `select` | -- | Comma-separated fields to return |
+| `group_by` | -- | Aggregate by field |
+
+**Advanced search:** Supports wildcards (`machin*`), fuzzy (`machin~1`), proximity (`"climate change"~5`), boolean grouping.
+
+**Example:**
+```
+https://api.openalex.org/works?search=CRISPR+gene+therapy&filter=from_publication_date:2023-01-01&sort=cited_by_count:desc&per_page=10
+```
+
+### 3. Filter works
+
+```
+GET /works?filter={filters}
+```
+
+Key filter fields:
+| Filter | Example | Description |
+|--------|---------|-------------|
+| `from_publication_date` | `2023-01-01` | Published after date |
+| `to_publication_date` | `2024-12-31` | Published before date |
+| `publication_year` | `2024` | Exact year |
+| `type` | `article` | Work type |
+| `cited_by_count` | `>100` | Citation threshold |
+| `is_oa` | `true` | Open access only |
+| `has_abstract` | `true` | Has abstract |
+| `authorships.author.id` | `A5048491430` | By author ID |
+| `primary_location.source.id` | `S137773608` | By journal/source |
+| `institutions.country_code` | `us` | By country |
+| `concepts.id` | `C41008148` | By concept/topic |
+| `doi` | `10.1038/nature12373` | By DOI |
+
+**Operators:** `>`, `<`, `!` (negation), `|` (OR within filter)
+
+**Example:**
+```
+https://api.openalex.org/works?filter=from_publication_date:2024-01-01,type:article,is_oa:true,cited_by_count:>50
+```
+
+### 4. Other entities
+
+```
+GET /authors?search={name}
+GET /authors/{id}
+GET /sources?search={name}          (journals, repositories)
+GET /sources/{id}
+GET /institutions?search={name}
+GET /institutions/{id}
+GET /topics/{id}
+```
+
+Authors and institutions accept similar filter/sort/pagination parameters.
+
+### 5. Cursor pagination (for >10,000 results)
+
+```
+GET /works?filter=publication_year:2024&cursor=*&per_page=100
+```
+
+Response includes `meta.next_cursor`. Pass it as `cursor={value}` in the next request. Stop when `next_cursor` is null.
+
+## Response Format
+
+### Work object (key fields)
+
+```json
+{
+  "id": "https://openalex.org/W2741809807",
+  "doi": "https://doi.org/10.7717/peerj.4375",
+  "title": "The state of OA",
+  "publication_year": 2018,
+  "publication_date": "2018-02-13",
+  "type": "article",
+  "language": "en",
+  "is_retracted": false,
+  "cited_by_count": 1169,
+  "open_access": {
+    "is_oa": true,
+    "oa_status": "gold",
+    "oa_url": "https://doi.org/10.7717/peerj.4375"
+  },
+  "authorships": [{
+    "author": {"id": "https://openalex.org/A5048491430", "display_name": "Heather Piwowar"},
+    "institutions": [{"display_name": "Impactstory"}]
+  }],
+  "primary_location": {
+    "source": {"display_name": "PeerJ", "issn_l": "2167-8359"}
+  },
+  "abstract_inverted_index": {"Despite": [0], "growing": [1], "interest": [2], ...},
+  "referenced_works": ["https://openalex.org/W123...", ...],
+  "ids": {"openalex": "...", "doi": "...", "pmid": "..."}
+}
+```
+
+### Abstract inverted index
+
+Abstracts are stored as `{word: [positions]}`. To reconstruct:
+```python
+def reconstruct(inverted_index):
+    positions = {}
+    for word, indices in inverted_index.items():
+        for idx in indices:
+            positions[idx] = word
+    return ' '.join(positions[i] for i in sorted(positions.keys()))
+```
+
+### List response
+
+```json
+{
+  "meta": {"count": 3771834, "page": 1, "per_page": 10},
+  "results": [...]
+}
+```
+
+## Error Format
+
+HTTP 403 for invalid API key, 429 for rate limit exceeded. Error responses include a message field.

package/presets/clearai/template/skills/paper-lookup/references/pmc.md

@@ -0,0 +1,152 @@
+# PMC (PubMed Central)
+
+PMC is a **full-text archive** of biomedical and life sciences articles. It is separate from PubMed -- PubMed has citations/abstracts, PMC has full text. Not all PubMed articles are in PMC, and vice versa.
+
+## E-utilities for PMC
+
+### Base URL
+
+```
+https://eutils.ncbi.nlm.nih.gov/entrez/eutils/
+```
+
+Same E-utilities as PubMed, but with `db=pmc`.
+
+### eSearch -- Search PMC
+
+```
+GET /esearch.fcgi?db=pmc&term={query}&retmode=json
+```
+
+Same parameters as PubMed eSearch. Returns PMC UIDs (numeric, e.g., `13033346`). You need to prepend "PMC" to get a PMCID (e.g., `PMC13033346`).
+
+### eFetch -- Get Full Text XML
+
+```
+GET /efetch.fcgi?db=pmc&id={pmcid}&retmode=xml
+```
+
+| rettype | retmode | Returns |
+|---------|---------|---------|
+| *(omit)* | `xml` | **Full text JATS XML** (body, figures, references) |
+| `medline` | `text` | MEDLINE format |
+
+**Example:**
+```
+https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=pmc&id=7029759&retmode=xml
+```
+
+The XML uses JATS (Journal Article Tag Suite) format:
+- `<front>` -- journal metadata, article metadata, author info
+- `<body>` -- full article text with `<sec>` sections, `<p>` paragraphs, `<fig>` figures
+- `<back>` -- `<ref-list>` with all references
+
+Pass numeric IDs only (not "PMC7029759", just "7029759").
+
+## BioC API -- Structured Full Text
+
+An alternative way to get full text in a structured passage format.
+
+### Base URL
+
+```
+https://www.ncbi.nlm.nih.gov/research/bionlp/RESTful/pmcoa.cgi/
+```
+
+### Endpoint
+
+```
+GET /BioC_{format}/{id}/{encoding}
+```
+
+| Parameter | Values |
+|-----------|--------|
+| `format` | `json` or `xml` |
+| `id` | PMID (e.g., `17299597`) or PMCID (e.g., `PMC7029759`) |
+| `encoding` | `unicode` or `ascii` |
+
+**Example:**
+```
+https://www.ncbi.nlm.nih.gov/research/bionlp/RESTful/pmcoa.cgi/BioC_json/PMC7029759/unicode
+```
+
+**Response structure (JSON):**
+```json
+{
+  "source": "PMC",
+  "documents": [{
+    "id": "PMC7029759",
+    "infons": {"license": "...", "doi": "..."},
+    "passages": [
+      {
+        "offset": 0,
+        "infons": {"section_type": "TITLE"},
+        "text": "Article title..."
+      },
+      {
+        "offset": 42,
+        "infons": {"section_type": "ABSTRACT"},
+        "text": "Abstract text..."
+      },
+      {
+        "offset": 500,
+        "infons": {"section_type": "INTRO"},
+        "text": "Introduction text..."
+      }
+    ]
+  }]
+}
+```
+
+Section types: `TITLE`, `ABSTRACT`, `INTRO`, `METHODS`, `RESULTS`, `DISCUSS`, `CONCL`, `REF`, `SUPPL`, `FIG`, `TABLE`
+
+**Coverage:** ~3 million articles from the PMC Open Access Subset.
+
+## PMC ID Converter API
+
+Converts between PMID, PMCID, DOI, and Manuscript ID.
+
+### Base URL
+
+```
+https://pmc.ncbi.nlm.nih.gov/tools/idconv/api/v1/articles/
+```
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `ids` | Yes | Up to 200 comma-separated IDs |
+| `idtype` | No | `pmcid`, `pmid`, `mid`, `doi` (default: auto-detect) |
+| `format` | No | `json`, `xml`, `csv` (default: xml) |
+| `tool` | Recommended | Your application name |
+| `email` | Recommended | Your contact email |
+
+**Example:**
+```
+https://pmc.ncbi.nlm.nih.gov/tools/idconv/api/v1/articles/?ids=PMC7029759&format=json
+```
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "records": [{
+    "pmcid": "PMC7029759",
+    "pmid": "32117569",
+    "doi": "10.12688/f1000research.22211.2"
+  }]
+}
+```
+
+Only returns results for articles that are in PMC. If an article is in PubMed but not PMC, no PMCID will be returned.
+
+## Rate Limits
+
+| Service | Limit |
+|---------|-------|
+| E-utilities (`db=pmc`) | 3/sec without key, 10/sec with key |
+| BioC API | Follow general NCBI policy (3/sec without key) |
+| ID Converter | Follow general NCBI policy |
+
+Include `tool` and `email` parameters on E-utility requests. Large batch jobs should run outside peak hours (Mon-Fri 5AM-9PM ET).

package/presets/clearai/template/skills/paper-lookup/references/pubmed.md

@@ -0,0 +1,124 @@
+# PubMed (NCBI E-utilities)
+
+PubMed provides citations, abstracts, and metadata for 37M+ biomedical and life science articles. It does NOT contain full text -- for that, use PMC.
+
+## Base URL
+
+```
+https://eutils.ncbi.nlm.nih.gov/entrez/eutils/
+```
+
+## Authentication
+
+- **API key optional** but recommended. Without: 3 req/sec. With: 10 req/sec.
+- Pass as: `&api_key=YOUR_KEY`
+- Also include `&tool=your_app_name&email=your@email.com` on all requests.
+
+## Key Endpoints
+
+### 1. eSearch -- Search and get PMIDs
+
+```
+GET /esearch.fcgi?db=pubmed&term={query}&retmode=json
+```
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `db` | Yes | -- | `pubmed` |
+| `term` | Yes | -- | Search query. Supports PubMed syntax: field tags `[AU]`, `[TI]`, `[TA]`, `[MH]` (MeSH), boolean AND/OR/NOT |
+| `retmax` | No | 20 | Max PMIDs returned (max 10,000) |
+| `retstart` | No | 0 | Pagination offset |
+| `retmode` | No | `xml` | `json` or `xml` |
+| `rettype` | No | `uilist` | `uilist` (IDs) or `count` (count only) |
+| `sort` | No | `relevance` | `relevance`, `pub_date`, `Author`, `JournalName` |
+| `datetype` | No | -- | `pdat` (publication), `mdat` (modification), `edat` (entrez) |
+| `mindate` / `maxdate` | No | -- | Date range `YYYY/MM/DD` |
+| `reldate` | No | -- | Items from last N days |
+| `usehistory` | No | -- | `y` to store on History Server for large result sets |
+
+**Example:**
+```
+https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=CRISPR+gene+therapy&retmode=json&retmax=5&sort=pub_date
+```
+
+**Response:**
+```json
+{
+  "esearchresult": {
+    "count": "224107",
+    "retmax": "5",
+    "retstart": "0",
+    "idlist": ["39984857", "39984678", "39984543", "39984210", "39983901"]
+  }
+}
+```
+
+### 2. eSummary -- Get document summaries
+
+```
+GET /esummary.fcgi?db=pubmed&id={pmids}&retmode=json
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `db` | Yes | `pubmed` |
+| `id` | Yes | Comma-separated PMIDs (max 10,000) |
+| `retmode` | No | `json` or `xml` |
+
+**Example:**
+```
+https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=pubmed&id=39984857,39984678&retmode=json
+```
+
+**Response fields:** `uid`, `pubdate`, `source` (journal), `authors`, `title`, `volume`, `issue`, `pages`, `fulljournalname`, `elocationid` (DOI), `articleids` (PMC, DOI, etc.), `pubtype`, `pmcrefcount`
+
+### 3. eFetch -- Retrieve full records (abstracts, MEDLINE)
+
+```
+GET /efetch.fcgi?db=pubmed&id={pmids}&rettype={type}&retmode={mode}
+```
+
+| rettype | retmode | Returns |
+|---------|---------|---------|
+| *(omit)* | `xml` | Full PubMed XML (citation + abstract) |
+| `medline` | `text` | MEDLINE format |
+| `abstract` | `text` | Plain text abstract |
+| `uilist` | `text` | PMID list |
+
+**Example -- get abstracts as XML:**
+```
+https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=pubmed&id=39984857&retmode=xml
+```
+
+The XML contains `<PubmedArticle>` with `<MedlineCitation>` (title, abstract, MeSH terms, authors) and `<PubmedData>` (article IDs, publication history).
+
+### 4. eLink -- Find related articles
+
+```
+GET /elink.fcgi?dbfrom=pubmed&db=pubmed&id={pmid}&cmd=neighbor_score&retmode=json
+```
+
+Returns related PMIDs with relevance scores.
+
+## Search Syntax Tips
+
+- **Field tags:** `aspirin[TI]` (title), `Smith J[AU]` (author), `Nature[TA]` (journal), `neoplasms[MH]` (MeSH heading)
+- **Boolean:** `CRISPR AND (therapy OR treatment)`
+- **Date range:** `2020/01/01:2024/12/31[PDAT]`
+- **Publication type:** `review[PT]`, `clinical trial[PT]`
+- **Organism:** `humans[MH]`, `mice[MH]`
+
+## Rate Limits
+
+- **3 requests/second** without API key
+- **10 requests/second** with API key
+- Include `tool` and `email` parameters on every request
+- Large batch jobs should run outside peak hours (Mon-Fri 5AM-9PM ET)
+
+## Error Format
+
+```json
+{"error": "API rate limit exceeded", "count": "11"}
+```
+
+HTTP 400 for bad requests, 429 for rate limiting.