@wentorai/research-plugins 1.0.0 → 1.2.0

package/skills/literature/metadata/ror-organization-api/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: ror-organization-api
+description: "Identify and link research organizations via the ROR registry API"
+metadata:
+  openclaw:
+    emoji: "🏢"
+    category: "literature"
+    subcategory: "metadata"
+    keywords: ["ROR", "research organizations", "institution registry", "affiliation", "organization identifiers", "ISNI"]
+    source: "https://ror.org/"
+---
+
+# ROR (Research Organization Registry) API
+
+## Overview
+
+ROR is the community-led registry of open persistent identifiers for research organizations worldwide — 110,000+ entries covering universities, research institutes, government agencies, hospitals, and companies. The API enables affiliation disambiguation, institutional search, and metadata retrieval. Essential for bibliometrics, funder compliance, and research analytics. Free, no authentication required.
+
+## API Endpoints
+
+### Base URL
+
+```
+https://api.ror.org/v2
+```
+
+### Search Organizations
+
+```bash
+# Text search
+curl "https://api.ror.org/v2/organizations?query=MIT"
+
+# Affiliation matching (fuzzy match for messy affiliation strings)
+curl "https://api.ror.org/v2/organizations?affiliation=Dept+of+CS,+Massachusetts+Inst+of+Technology"
+
+# Filter by country
+curl "https://api.ror.org/v2/organizations?query=university&filter=locations.geonames_details.country_code:US"
+
+# Filter by organization type
+curl "https://api.ror.org/v2/organizations?query=research&filter=types:facility"
+```
+
+### Get Organization by ROR ID
+
+```bash
+# Retrieve full record
+curl "https://api.ror.org/v2/organizations/https://ror.org/042nb2s44"
+
+# Also works with just the ID portion
+curl "https://api.ror.org/v2/organizations/042nb2s44"
+```
+
+### Query Parameters
+
+| Parameter | Description | Example |
+|-----------|-------------|---------|
+| `query` | Text search | `query=Harvard` |
+| `affiliation` | Fuzzy affiliation match | `affiliation=MIT Cambridge MA` |
+| `filter` | Faceted filtering | `filter=types:education` |
+| `page` | Page number (1-based) | `page=2` |
+
+### Organization Types
+
+| Type | Description |
+|------|-------------|
+| `education` | Universities, colleges |
+| `facility` | Research facilities, labs |
+| `healthcare` | Hospitals, medical centers |
+| `company` | Companies with research activities |
+| `government` | Government agencies |
+| `nonprofit` | Non-profit research organizations |
+| `funder` | Funding agencies |
+| `archive` | Archives, libraries |
+
+## Response Structure
+
+```json
+{
+  "number_of_results": 3,
+  "items": [
+    {
+      "id": "https://ror.org/042nb2s44",
+      "names": [
+        {"value": "Massachusetts Institute of Technology", "types": ["ror_display"]},
+        {"value": "MIT", "types": ["acronym"]}
+      ],
+      "types": ["education"],
+      "locations": [
+        {
+          "geonames_details": {
+            "country_code": "US",
+            "country_name": "United States",
+            "name": "Cambridge"
+          }
+        }
+      ],
+      "external_ids": [
+        {"type": "isni", "all": ["0000 0001 2341 2786"]},
+        {"type": "grid", "all": ["grid.116068.8"]},
+        {"type": "wikidata", "all": ["Q49108"]}
+      ],
+      "links": [{"type": "website", "value": "https://www.mit.edu/"}],
+      "relationships": [
+        {"id": "https://ror.org/01a8ajp77", "label": "Lincoln Laboratory", "type": "child"}
+      ],
+      "status": "active",
+      "established": 1861
+    }
+  ]
+}
+```
+
+## Python Usage
+
+```python
+import requests
+
+BASE_URL = "https://api.ror.org/v2/organizations"
+
+
+def search_organizations(query: str,
+                         country: str = None,
+                         org_type: str = None) -> list:
+    """Search ROR for research organizations."""
+    params = {"query": query}
+    filters = []
+    if country:
+        filters.append(
+            f"locations.geonames_details.country_code:{country}")
+    if org_type:
+        filters.append(f"types:{org_type}")
+    if filters:
+        params["filter"] = ",".join(filters)
+
+    resp = requests.get(BASE_URL, params=params)
+    resp.raise_for_status()
+    data = resp.json()
+
+    results = []
+    for org in data.get("items", []):
+        display_name = next(
+            (n["value"] for n in org.get("names", [])
+             if "ror_display" in n.get("types", [])),
+            org.get("names", [{}])[0].get("value", ""),
+        )
+        acronyms = [n["value"] for n in org.get("names", [])
+                     if "acronym" in n.get("types", [])]
+        loc = org.get("locations", [{}])[0].get("geonames_details", {})
+
+        results.append({
+            "ror_id": org.get("id"),
+            "name": display_name,
+            "acronyms": acronyms,
+            "types": org.get("types", []),
+            "country": loc.get("country_name"),
+            "city": loc.get("name"),
+            "established": org.get("established"),
+        })
+    return results
+
+
+def match_affiliation(affiliation_string: str) -> dict:
+    """Disambiguate a messy affiliation string to a ROR record."""
+    resp = requests.get(
+        BASE_URL,
+        params={"affiliation": affiliation_string},
+    )
+    resp.raise_for_status()
+    items = resp.json().get("items", [])
+    if items and items[0].get("chosen"):
+        return items[0].get("organization", {})
+    return items[0] if items else {}
+
+
+def get_organization(ror_id: str) -> dict:
+    """Get full ROR record for an organization."""
+    resp = requests.get(f"{BASE_URL}/{ror_id}")
+    resp.raise_for_status()
+    return resp.json()
+
+
+# Example: find German research institutes
+orgs = search_organizations("Max Planck", country="DE",
+                            org_type="facility")
+for o in orgs:
+    print(f"{o['name']} ({', '.join(o['acronyms'])}) "
+          f"— {o['city']}, {o['country']} (est. {o['established']})")
+
+# Example: disambiguate messy affiliations
+result = match_affiliation(
+    "Dept. of Computer Sci., Stanford Univ., CA, USA")
+print(f"Matched: {result.get('id')} — "
+      f"{result.get('names', [{}])[0].get('value')}")
+```
+
+## Use Cases
+
+1. **Affiliation disambiguation**: Clean messy author affiliation strings
+2. **Bibliometric analysis**: Aggregate publications by institution
+3. **Funder compliance**: Link outputs to institutional identifiers
+4. **Research profiling**: Map institutional research portfolios
+5. **Collaboration networks**: Trace inter-institutional partnerships
+
+## References
+
+- [ROR](https://ror.org/)
+- [ROR API Documentation](https://ror.readme.io/)
+- [ROR Data Dump](https://doi.org/10.5281/zenodo.6347574)

package/skills/literature/metadata/sophosia-reference-guide/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: sophosia-reference-guide
+description: "Reference manager with PDF viewer and Markdown note support"
+metadata:
+  openclaw:
+    emoji: "📚"
+    category: "literature"
+    subcategory: "metadata"
+    keywords: ["reference manager", "PDF viewer", "Markdown notes", "Excalidraw", "paper organization", "open source"]
+    source: "https://github.com/sophosia/sophosia"
+---
+
+# Sophosia Reference Manager Guide
+
+## Overview
+
+Sophosia is an open-source reference manager that combines PDF viewing, Markdown note-taking, and Excalidraw visual notes in a single application. Unlike traditional reference managers, it treats each paper as a rich workspace with typed annotations, linked notes, and visual diagrams. Built with modern web technologies (Electron + Vue), it runs on all desktop platforms.
+
+## Installation
+
+```bash
+# Download from GitHub releases (Windows/macOS/Linux)
+# Or build from source:
+git clone https://github.com/sophosia/sophosia.git
+cd sophosia
+npm install && npm run build
+```
+
+## Features
+
+```markdown
+### Core Capabilities
+- **PDF Viewer**: Built-in reader with annotations
+- **Markdown Notes**: Rich note editor per paper
+- **Excalidraw**: Visual whiteboard for diagrams
+- **Tags & Collections**: Flexible organization
+- **BibTeX Support**: Import/export bibliography
+- **Full-text Search**: Search across all papers
+- **Citation Graph**: Visual paper relationships
+
+### Note Types
+1. **Text notes** — Markdown with LaTeX math
+2. **Visual notes** — Excalidraw canvas
+3. **Annotation notes** — Linked to PDF highlights
+4. **Outline notes** — Structured paper summaries
+```
+
+## Workspace Structure
+
+```markdown
+### Per-Paper Workspace
+Paper: "Attention Is All You Need"
+├── PDF (with highlights and annotations)
+├── Notes/
+│   ├── summary.md (structured summary)
+│   ├── ideas.md (research ideas sparked)
+│   └── architecture.excalidraw (visual diagram)
+├── Metadata (title, authors, year, DOI, tags)
+└── Links (related papers, concept connections)
+```
+
+## Note-Taking Features
+
+```markdown
+### Markdown Notes Support
+- Standard Markdown formatting
+- LaTeX math: $E = mc^2$ and display equations
+- Code blocks with syntax highlighting
+- Tables and checklists
+- Wikilinks: [[other-paper]] for cross-referencing
+- Embeds: ![[figure.png]] for inline images
+- Templates for consistent note structure
+
+### Excalidraw Integration
+- Draw architecture diagrams
+- Mind maps for paper concepts
+- Comparison charts between methods
+- Hand-drawn style for informal notes
+- Export as SVG/PNG for presentations
+```
+
+## Import/Export
+
+```markdown
+### Import Sources
+- BibTeX (.bib)
+- RIS format
+- DOI lookup (auto-fetch metadata)
+- PDF drag-and-drop (auto-extract metadata)
+- Zotero export files
+
+### Export Formats
+- BibTeX for LaTeX
+- Markdown bibliography
+- CSV metadata export
+- HTML reading lists
+```
+
+## Use Cases
+
+1. **Reading workflow**: PDF + notes in single workspace
+2. **Visual thinking**: Excalidraw diagrams alongside papers
+3. **Literature review**: Linked notes across paper collection
+4. **Presentation prep**: Visual notes exportable as diagrams
+5. **Research journal**: Rich per-paper documentation
+
+## References
+
+- [Sophosia GitHub](https://github.com/sophosia/sophosia)
+- [Excalidraw](https://excalidraw.com/)

package/skills/literature/metadata/viaf-authority-api/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: viaf-authority-api
+description: "Disambiguate author identities via the VIAF authority file API"
+metadata:
+  openclaw:
+    emoji: "👤"
+    category: "literature"
+    subcategory: "metadata"
+    keywords: ["VIAF", "authority control", "author disambiguation", "name authority", "OCLC", "library catalog"]
+    source: "https://viaf.org/"
+---
+
+# VIAF (Virtual International Authority File) API
+
+## Overview
+
+VIAF clusters authority records from 50+ national libraries worldwide, linking different forms of an author's name into a single canonical identity. It covers 50M+ personal, corporate, and geographic name entries. Essential for author disambiguation in bibliometric research — resolving "J. Smith", "John Smith", and "Smith, J.A." to the same person. Free, no authentication.
+
+## API Endpoints
+
+### Base URL
+
+```
+https://viaf.org
+```
+
+### Search
+
+```bash
+# Search by name (AutoSuggest)
+curl "https://viaf.org/viaf/AutoSuggest?query=einstein+albert"
+
+# Search via SRU (structured query)
+curl "https://viaf.org/viaf/search?query=local.personalNames+all+\"hinton+geoffrey\"&\
+sortKeys=holdingscount&httpAccept=application/json"
+
+# Search corporate names
+curl "https://viaf.org/viaf/search?query=local.corporateNames+all+\"MIT\"&\
+httpAccept=application/json"
+```
+
+### Get Record by VIAF ID
+
+```bash
+# JSON format
+curl "https://viaf.org/viaf/75121530/viaf.json"
+
+# Linked data formats
+curl -H "Accept: application/json" "https://viaf.org/viaf/75121530"
+
+# Cluster data (all linked identities)
+curl "https://viaf.org/viaf/75121530/justlinks.json"
+```
+
+### Cross-Reference by External ID
+
+```bash
+# Look up by Library of Congress ID
+curl "https://viaf.org/viaf/lccn/n79021164/viaf.json"
+
+# Look up by ISNI
+curl "https://viaf.org/viaf/isni/0000000121174331/viaf.json"
+
+# Look up by ORCID
+curl "https://viaf.org/viaf/sourceID/ORCID|0000-0002-1825-0097/viaf.json"
+
+# Look up by Wikidata QID
+curl "https://viaf.org/viaf/sourceID/WKP|Q937/viaf.json"
+```
+
+### Source Codes
+
+| Code | Library/Source |
+|------|---------------|
+| `LC` | Library of Congress |
+| `DNB` | German National Library |
+| `BNF` | Bibliothèque nationale de France |
+| `NLA` | National Library of Australia |
+| `NDL` | National Diet Library (Japan) |
+| `NKC` | National Library of Czech Republic |
+| `WKP` | Wikidata |
+| `ISNI` | ISNI |
+
+## Response Structure
+
+```json
+{
+  "viafID": "75121530",
+  "nameType": "Personal",
+  "mainHeadings": {
+    "data": [
+      {
+        "text": "Einstein, Albert, 1879-1955",
+        "sources": {"s": ["LC", "DNB", "BNF"]}
+      }
+    ]
+  },
+  "x400s": {
+    "x400": [
+      {"datafield": {"subfield": [{"text": "Albert Einstein"}]}}
+    ]
+  },
+  "birthDate": "1879",
+  "deathDate": "1955",
+  "sources": {
+    "source": [
+      {"nsid": "n79022889", "sid": "LC|n79022889"},
+      {"nsid": "118529579", "sid": "DNB|118529579"}
+    ]
+  }
+}
+```
+
+## Python Usage
+
+```python
+import requests
+
+BASE_URL = "https://viaf.org/viaf"
+
+
+def search_person(name: str, limit: int = 10) -> list:
+    """Search VIAF for personal name authorities."""
+    resp = requests.get(
+        f"{BASE_URL}/AutoSuggest",
+        params={"query": name},
+    )
+    resp.raise_for_status()
+    data = resp.json()
+
+    results = []
+    for item in data.get("result", [])[:limit]:
+        results.append({
+            "viaf_id": item.get("viafid"),
+            "name": item.get("displayForm"),
+            "name_type": item.get("nametype"),
+            "source_count": len(item.get("sources", "").split("|")),
+        })
+    return results
+
+
+def get_authority(viaf_id: str) -> dict:
+    """Get full VIAF authority record."""
+    resp = requests.get(f"{BASE_URL}/{viaf_id}/viaf.json")
+    resp.raise_for_status()
+    data = resp.json()
+
+    name_forms = []
+    for heading in data.get("mainHeadings", {}).get("data", []):
+        if isinstance(heading, dict):
+            name_forms.append({
+                "text": heading.get("text"),
+                "sources": heading.get("sources", {}).get("s", []),
+            })
+
+    external_ids = {}
+    for src in data.get("sources", {}).get("source", []):
+        sid = src.get("sid", "")
+        if "|" in sid:
+            prefix, local_id = sid.split("|", 1)
+            external_ids[prefix] = local_id
+
+    return {
+        "viaf_id": data.get("viafID"),
+        "name_forms": name_forms,
+        "birth": data.get("birthDate"),
+        "death": data.get("deathDate"),
+        "external_ids": external_ids,
+    }
+
+
+def resolve_by_orcid(orcid: str) -> dict:
+    """Resolve ORCID to VIAF authority record."""
+    resp = requests.get(
+        f"{BASE_URL}/sourceID/ORCID|{orcid}/viaf.json"
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+# Example: disambiguate an author name
+candidates = search_person("Geoffrey Hinton")
+for c in candidates:
+    print(f"VIAF {c['viaf_id']}: {c['name']} "
+          f"({c['source_count']} libraries)")
+
+# Example: get all name forms for an author
+if candidates:
+    record = get_authority(candidates[0]["viaf_id"])
+    print(f"\nName forms for {record['viaf_id']}:")
+    for form in record["name_forms"]:
+        sources = ", ".join(form["sources"][:3])
+        print(f"  {form['text']} [{sources}]")
+    print(f"External IDs: {record['external_ids']}")
+```
+
+## Use Cases
+
+1. **Author disambiguation**: Resolve name variants to canonical identities
+2. **Cross-library linking**: Connect records across national catalogs
+3. **Bibliometric deduplication**: Merge author records from different databases
+4. **Identity verification**: Confirm author identity via multiple authority sources
+5. **Linked data enrichment**: Bridge ORCID, Wikidata, and library authorities
+
+## References
+
+- [VIAF](https://viaf.org/)
+- [VIAF API Documentation](https://www.oclc.org/developer/api/oclc-apis/viaf.en.html)
+- [VIAF Guidelines](https://www.oclc.org/research/activities/viaf.html)

package/skills/literature/metadata/wikidata-api-guide/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: wikidata-api-guide
+description: "Query Wikidata SPARQL for scholarly metadata, authors, and entities"
+metadata:
+  openclaw:
+    emoji: "🌐"
+    category: "literature"
+    subcategory: "metadata"
+    keywords: ["wikidata", "sparql", "linked-data", "metadata", "knowledge-graph", "scholarly"]
+    source: "https://www.wikidata.org/wiki/Wikidata:SPARQL_query_service"
+---
+
+# Wikidata SPARQL API Guide
+
+## Overview
+
+Wikidata is a free, collaborative, multilingual knowledge base maintained by the Wikimedia Foundation. It contains structured data about millions of entities including scholarly articles, academic journals, researchers, universities, and scientific concepts. Each entity has a unique QID and properties linking it to other entities, forming a rich knowledge graph.
+
+For academic researchers, Wikidata serves as a powerful tool for bibliometric analysis, disambiguation of author names, mapping institutional relationships, and linking scholarly outputs across different identifier systems (DOI, ORCID, PubMed ID, arXiv ID, etc.). The SPARQL query service provides a flexible, standards-based interface for complex graph queries.
+
+The Wikidata Query Service is entirely free, requires no authentication, and supports the full SPARQL 1.1 query language. It is especially powerful for cross-referencing scholarly metadata that spans multiple databases and identifier systems.
+
+## Authentication
+
+No authentication is required. The Wikidata SPARQL endpoint is free and open.
+
+```bash
+# No API key needed -- set a descriptive User-Agent header as courtesy
+curl -G "https://query.wikidata.org/sparql" \
+  --data-urlencode "query=SELECT ?item WHERE { ?item wdt:P31 wd:Q5 } LIMIT 5" \
+  -H "Accept: application/json" \
+  -H "User-Agent: ResearchClaw/1.0 (academic research tool)"
+```
+
+## Core Endpoints
+
+### SPARQL Query Endpoint
+
+```
+GET https://query.wikidata.org/sparql?query={SPARQL}&format=json
+```
+
+**Parameters:**
+- `query` (required): URL-encoded SPARQL query
+- `format`: Response format (`json`, `xml`, `csv`, `tsv`)
+
+### Query: Find Papers by a Researcher (via ORCID)
+
+```bash
+curl -G "https://query.wikidata.org/sparql" \
+  --data-urlencode 'query=
+    SELECT ?paper ?paperLabel ?doi WHERE {
+      ?author wdt:P496 "0000-0002-1825-0097" .
+      ?paper wdt:P50 ?author ;
+             wdt:P356 ?doi .
+      SERVICE wikibase:label { bd:serviceParam wikibase:language "en" . }
+    } LIMIT 20' \
+  -H "Accept: application/json" \
+  -H "User-Agent: ResearchClaw/1.0"
+```
+
+### Query: Journal Impact and Article Counts
+
+```sparql
+SELECT ?journal ?journalLabel ?issn (COUNT(?article) AS ?articleCount) WHERE {
+  ?journal wdt:P31 wd:Q5633421 ;
+           wdt:P236 ?issn .
+  ?article wdt:P1433 ?journal .
+  SERVICE wikibase:label { bd:serviceParam wikibase:language "en" . }
+}
+GROUP BY ?journal ?journalLabel ?issn
+ORDER BY DESC(?articleCount)
+LIMIT 20
+```
+
+### Python Example: Cross-Reference Author Identifiers
+
+```python
+import requests
+
+SPARQL_URL = "https://query.wikidata.org/sparql"
+HEADERS = {
+    "Accept": "application/json",
+    "User-Agent": "ResearchClaw/1.0 (academic research tool)"
+}
+
+def query_wikidata(sparql_query):
+    """Execute a SPARQL query against Wikidata."""
+    resp = requests.get(
+        SPARQL_URL,
+        params={"query": sparql_query},
+        headers=HEADERS
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    return data["results"]["bindings"]
+
+# Find all identifier mappings for a researcher
+sparql = """
+SELECT ?person ?personLabel ?orcid ?scopus ?dblp ?gscholar WHERE {
+  ?person wdt:P496 "0000-0002-1825-0097" .
+  OPTIONAL { ?person wdt:P496 ?orcid . }
+  OPTIONAL { ?person wdt:P1153 ?scopus . }
+  OPTIONAL { ?person wdt:P2456 ?dblp . }
+  OPTIONAL { ?person wdt:P1960 ?gscholar . }
+  SERVICE wikibase:label { bd:serviceParam wikibase:language "en" . }
+}
+"""
+results = query_wikidata(sparql)
+for r in results:
+    print(f"Name: {r.get('personLabel', {}).get('value', 'N/A')}")
+    print(f"  ORCID: {r.get('orcid', {}).get('value', 'N/A')}")
+    print(f"  Scopus: {r.get('scopus', {}).get('value', 'N/A')}")
+    print(f"  DBLP: {r.get('dblp', {}).get('value', 'N/A')}")
+    print(f"  Google Scholar: {r.get('gscholar', {}).get('value', 'N/A')}")
+```
+
+### Query: Institutions by Country with Coordinates
+
+```sparql
+SELECT ?uni ?uniLabel ?country ?countryLabel ?coord WHERE {
+  ?uni wdt:P31 wd:Q3918 ;
+       wdt:P17 ?country ;
+       wdt:P625 ?coord .
+  FILTER(?country = wd:Q30)
+  SERVICE wikibase:label { bd:serviceParam wikibase:language "en" . }
+}
+LIMIT 50
+```
+
+## Common Research Patterns
+
+**Author Disambiguation:** Use Wikidata to resolve author names by cross-referencing ORCID, Scopus ID, DBLP, and Google Scholar identifiers. This is particularly useful when a common name maps to multiple researchers.
+
+**Bibliometric Graph Construction:** Build citation and co-authorship networks by querying the relationships between authors, papers, journals, and institutions in the Wikidata graph.
+
+**Identifier Translation:** Convert between DOI, PubMed ID, arXiv ID, and other identifiers using Wikidata's comprehensive property mappings. This enables linking records across heterogeneous databases.
+
+**Institutional Analysis:** Map university affiliations, geographic distributions, and organizational hierarchies for researchers in a specific field.
+
+## Rate Limits and Best Practices
+
+- **Query timeout:** 60 seconds; optimize complex queries with filters and limits
+- **Request rate:** No strict published limit, but keep requests under 1 per second for sustained usage
+- **User-Agent required:** Always include a descriptive User-Agent header identifying your application
+- **LIMIT clause:** Always include a LIMIT clause to prevent accidentally fetching millions of results
+- **Label service:** Use `SERVICE wikibase:label` for human-readable labels instead of QIDs
+- **Caching:** Wikidata results are fairly stable; cache results for repeated queries
+- **Bulk queries:** For large-scale data extraction, consider using Wikidata dumps instead of the query service
+
+## References
+
+- Wikidata SPARQL Query Service: https://query.wikidata.org/
+- Wikidata SPARQL Tutorial: https://www.wikidata.org/wiki/Wikidata:SPARQL_tutorial
+- Wikidata Properties for Scholarly Articles: https://www.wikidata.org/wiki/Wikidata:WikiProject_Source_MetaData
+- Wikidata REST API: https://www.wikidata.org/wiki/Wikidata:REST_API