wotann 0.5.0 → 0.5.39

package/skills/scientific/paper-lookup/references/core.md

@@ -0,0 +1,150 @@
+# CORE API
+
+CORE aggregates open access research from 15,000+ repositories worldwide. It provides **full text** for 37M+ articles and metadata for 368M+ papers.
+
+## Base URL
+
+```
+https://api.core.ac.uk/v3
+```
+
+**Important:** GET search paths require a **trailing slash** (e.g., `/v3/search/works/` not `/v3/search/works`).
+
+## Authentication
+
+- **Header:** `Authorization: Bearer YOUR_API_KEY`
+- **Query param:** `?api_key=YOUR_API_KEY`
+- Register at: https://core.ac.uk/services/api
+
+**Without auth:** Basic metadata queries work, but full text is NOT available (returns "Not available for public API users").
+
+## Rate Limits (token-based)
+
+| User Type | Daily Tokens | Per-Minute Max |
+|-----------|-------------|----------------|
+| Unauthenticated | 100/day | 10/min |
+| Registered Personal | 1,000/day | 25/min |
+| Registered Academic | 5,000/day | 10/min |
+
+Simple queries cost 1 token. Downloads and scroll pagination cost 3-5 tokens.
+
+## Key Endpoints
+
+### 1. Search works
+
+```
+GET /v3/search/works/?q={query}&limit={n}&offset={n}
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `q` | required | Search query (supports field lookups, boolean operators) |
+| `limit` | 10 | Results per page (max 100) |
+| `offset` | 0 | Pagination offset |
+| `scroll` | false | Enable scroll pagination for >10,000 results |
+| `sort` | relevance | `relevance` or `recency` |
+
+**POST alternative** (for complex queries):
+```
+POST /v3/search/works
+Content-Type: application/json
+
+{"q": "machine learning", "limit": 10, "offset": 0}
+```
+
+**Example:**
+```
+https://api.core.ac.uk/v3/search/works/?q=CRISPR+gene+therapy&limit=10
+```
+
+### 2. Query language
+
+| Operator | Example | Description |
+|----------|---------|-------------|
+| AND | `title:"AI" AND authors:"Smith"` | Both conditions |
+| OR | `title:"AI" OR fullText:"Deep Learning"` | Either condition |
+| Grouping | `(title:"AI" OR title:"ML") AND yearPublished>"2020"` | Precedence |
+| Field lookup | `title:"Machine Learning"` | Search specific field |
+| Range | `yearPublished>2018` | Numeric comparison |
+| Exists | `_exists_:fullText` | Field must exist |
+| Phrase | `title:"Attention is all you need"` | Exact phrase |
+
+**Searchable fields:** `abstract`, `arxivId`, `authors`, `contributors`, `createdDate`, `dataProviders`, `depositedDate`, `documentType`, `doi`, `fullText`, `id`, `language`, `license`, `oai`, `title`, `yearPublished`
+
+### 3. Get work by ID
+
+```
+GET /v3/works/{id}
+```
+
+`id` is a CORE Work ID (integer). Example: `/v3/works/267312`
+
+### 4. Get output by ID
+
+```
+GET /v3/outputs/{id}
+```
+
+### 5. Download full text
+
+```
+GET /v3/outputs/{id}/download
+```
+
+Returns binary PDF. Requires authentication.
+
+```
+GET /v3/works/tei/{id}
+```
+
+Returns TEI XML format.
+
+### 6. Search outputs
+
+```
+GET /v3/search/outputs/?q={query}&limit={n}&offset={n}
+```
+
+Search by DOI: `q=doi:10.1038/nature12373`
+
+## Response Format
+
+### Search response
+```json
+{
+  "totalHits": 2281337,
+  "limit": 10,
+  "offset": 0,
+  "scrollId": null,
+  "results": [...]
+}
+```
+
+### Work object (key fields)
+```json
+{
+  "id": 8848131,
+  "title": "Attention Is All You Need",
+  "authors": [{"name": "Ashish Vaswani"}, ...],
+  "abstract": "The dominant sequence...",
+  "doi": "10.48550/arXiv.1706.03762",
+  "arxivId": "1706.03762",
+  "yearPublished": 2017,
+  "downloadUrl": "https://core.ac.uk/download/...",
+  "fullText": "Full text content (when authenticated)...",
+  "language": {"code": "en", "name": "English"},
+  "documentType": "research",
+  "citationCount": 145678,
+  "dataProviders": [{"name": "arXiv"}],
+  "links": [{"type": "download", "url": "..."}]
+}
+```
+
+## Pagination
+
+- **Standard:** `offset` + `limit` (max 10,000 results)
+- **Scroll:** Set `scroll=true`. Response includes `scrollId`. Use in subsequent requests to page beyond 10,000 (costs more tokens).
+
+## Error Handling
+
+Under heavy load, the API may return partial shard failure messages. These are transient -- retry after a brief wait.

package/skills/scientific/paper-lookup/references/crossref.md

@@ -0,0 +1,181 @@
+# Crossref API
+
+Crossref is the DOI registration agency for scholarly content. It provides metadata for 150M+ works including journal articles, books, conference papers, datasets, and preprints.
+
+## Base URL
+
+```
+https://api.crossref.org
+```
+
+## Authentication
+
+None required. Add `mailto=you@example.com` to get into the **polite pool** (2x faster rate limits).
+
+## Rate Limits
+
+| Pool | Rate | Concurrency |
+|------|------|-------------|
+| Public (no mailto) | 5 req/sec | 1 concurrent |
+| Polite (with mailto) | 10 req/sec | 3 concurrent |
+
+HTTP 429 = temporarily blocked.
+
+## Key Endpoints
+
+### 1. Search works
+
+```
+GET /works?query={text}&rows={n}&mailto=you@example.com
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `query` | -- | Free-text search across all fields |
+| `query.author` | -- | Search author names |
+| `query.bibliographic` | -- | Search titles, authors, ISSNs, years |
+| `query.affiliation` | -- | Search affiliations |
+| `query.container-title` | -- | Search journal names |
+| `filter` | -- | Comma-separated `name:value` pairs |
+| `sort` | `score` | `score`, `published`, `issued`, `deposited`, `updated`, `is-referenced-by-count`, `references-count` |
+| `order` | `desc` | `asc` or `desc` |
+| `rows` | 20 | Results per page (max 1000) |
+| `offset` | 0 | Skip N results (max 10,000) |
+| `cursor` | -- | Use `*` for cursor-based deep pagination |
+| `select` | -- | Comma-separated field names to return |
+| `facet` | -- | Facet counts, e.g. `type-name:10` |
+| `sample` | -- | Return N random items (max 100) |
+
+**Example:**
+```
+https://api.crossref.org/works?query=CRISPR+gene+therapy&filter=from-pub-date:2024-01-01,type:journal-article,has-abstract:true&rows=5&sort=published&order=desc&mailto=you@example.com
+```
+
+### 2. Get work by DOI
+
+```
+GET /works/{doi}?mailto=you@example.com
+```
+
+URL-encode the DOI: `10.1038/nature12373` becomes `10.1038%2Fnature12373`
+
+**Example:**
+```
+https://api.crossref.org/works/10.1038%2Fnature12373?mailto=you@example.com
+```
+
+### 3. Journals
+
+```
+GET /journals?query={name}&rows={n}
+GET /journals/{issn}
+GET /journals/{issn}/works?query={text}&rows={n}
+```
+
+### 4. Funders
+
+```
+GET /funders?query={name}
+GET /funders/{id}
+GET /funders/{id}/works?rows={n}
+```
+
+Funder IDs are from the Funder Registry (e.g., `100000001` for NSF).
+
+### 5. Members (publishers)
+
+```
+GET /members?query={name}
+GET /members/{id}/works?rows={n}
+```
+
+## Key Filters
+
+### Date filters (accept `YYYY`, `YYYY-MM`, `YYYY-MM-DD`)
+| Filter | Description |
+|--------|-------------|
+| `from-pub-date` / `until-pub-date` | Publication date |
+| `from-print-pub-date` / `until-print-pub-date` | Print publication date |
+| `from-online-pub-date` / `until-online-pub-date` | Online publication date |
+| `from-posted-date` / `until-posted-date` | Posted date (preprints) |
+
+### Boolean filters
+| Filter | Description |
+|--------|-------------|
+| `has-abstract` | Has an abstract |
+| `has-orcid` | Has ORCID IDs |
+| `has-funder` | Has funder info |
+| `has-full-text` | Has full-text links |
+| `has-references` | Has reference list |
+| `has-license` | Has license info |
+
+### Value filters
+| Filter | Description |
+|--------|-------------|
+| `type` | `journal-article`, `posted-content`, `book-chapter`, `proceedings-article`, etc. |
+| `issn` | Journal ISSN |
+| `doi` | Specific DOI |
+| `orcid` | Contributor ORCID |
+| `funder` | Funder Registry ID |
+| `member` | Crossref member ID |
+| `prefix` | DOI prefix |
+| `license.url` | License URL |
+| `update-type` | `correction`, `retraction` |
+
+**Syntax:** `filter=name1:value1,name2:value2`
+
+## Pagination
+
+### Offset-based (max 10,000)
+```
+/works?query=cancer&rows=100&offset=200
+```
+
+### Cursor-based (unlimited)
+1. First request: `?cursor=*&rows=100`
+2. Response includes `next-cursor`
+3. Next request: `?cursor={next-cursor-value}&rows=100`
+4. Cursors expire after 5 minutes
+
+## Response Format
+
+### List response
+```json
+{
+  "status": "ok",
+  "message-type": "work-list",
+  "message": {
+    "total-results": 2779116,
+    "items-per-page": 20,
+    "next-cursor": "...",
+    "items": [...]
+  }
+}
+```
+
+### Work object (key fields)
+```json
+{
+  "DOI": "10.1038/nature12373",
+  "title": ["Nanometre-scale thermometry in a living cell"],
+  "author": [{"given": "G.", "family": "Kucsko", "sequence": "first"}],
+  "publisher": "Springer Science and Business Media LLC",
+  "type": "journal-article",
+  "published": {"date-parts": [[2013, 7, 31]]},
+  "container-title": ["Nature"],
+  "ISSN": ["0028-0836", "1476-4687"],
+  "volume": "500",
+  "issue": "7460",
+  "page": "54-58",
+  "is-referenced-by-count": 1745,
+  "references-count": 30,
+  "abstract": "<p>Abstract text with HTML tags...</p>",
+  "license": [{"URL": "...", "content-version": "vor"}],
+  "link": [{"URL": "...", "content-type": "application/pdf"}],
+  "reference": [{"key": "...", "doi-asserted-by": "crossref", "DOI": "..."}],
+  "subject": ["Multidisciplinary"],
+  "language": "en"
+}
+```
+
+Note: `title` and `container-title` are arrays. `published.date-parts` is `[[year, month, day]]`. Abstract may contain HTML tags.

package/skills/scientific/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/skills/scientific/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.