@wentorai/research-plugins 1.3.1 → 1.4.0

package/src/tools/opencitations.ts

@@ -0,0 +1,103 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+
+const BASE = "https://api.opencitations.net";
+
+/**
+ * Extract DOI from OpenCitations multi-identifier string.
+ * Format: "omid:br/... doi:10.1038/nature12373 openalex:W..."
+ */
+function extractDoi(multiId: string): string | undefined {
+  const match = multiId.match(/doi:(10\.\S+)/);
+  return match ? match[1] : undefined;
+}
+
+export function createOpenCitationsTools(
+  _ctx: OpenClawPluginToolContext,
+  _api: OpenClawPluginApi,
+) {
+  return [
+    {
+      name: "get_citations_open",
+      label: "Get Citations (OpenCitations)",
+      description:
+        "Get all papers citing a given DOI using OpenCitations (2B+ open citation links). Works across all disciplines.",
+      parameters: Type.Object({
+        doi: Type.String({
+          description: "DOI of the paper, e.g. '10.1038/nature12373'",
+        }),
+      }),
+      execute: async (input: { doi: string }) => {
+        const doi = input.doi.replace(/^https?:\/\/doi\.org\//, "");
+        const tracked = await trackedFetch("opencitations", `${BASE}/index/v2/citations/doi:${encodeURIComponent(doi)}`);
+        if (isTrackedError(tracked)) return tracked;
+        const data = await tracked.res.json();
+
+        if (!Array.isArray(data)) return toolResult({ error: "Unexpected response format" });
+
+        return toolResult({
+          total_citations: data.length,
+          citations: data.slice(0, 100).map((c: Record<string, string>) => ({
+            citing_doi: extractDoi(c.citing ?? ""),
+            cited_doi: extractDoi(c.cited ?? ""),
+            creation_date: c.creation,
+          })),
+          _source_health: { source: "opencitations", latency_ms: tracked.latency_ms },
+        });
+      },
+    },
+    {
+      name: "get_references_open",
+      label: "Get References (OpenCitations)",
+      description:
+        "Get all references of a paper by DOI. Shows what a paper cites.",
+      parameters: Type.Object({
+        doi: Type.String({
+          description: "DOI of the paper, e.g. '10.1038/nature12373'",
+        }),
+      }),
+      execute: async (input: { doi: string }) => {
+        const doi = input.doi.replace(/^https?:\/\/doi\.org\//, "");
+        const tracked = await trackedFetch("opencitations", `${BASE}/index/v2/references/doi:${encodeURIComponent(doi)}`);
+        if (isTrackedError(tracked)) return tracked;
+        const data = await tracked.res.json();
+
+        if (!Array.isArray(data)) return toolResult({ error: "Unexpected response format" });
+
+        return toolResult({
+          total_references: data.length,
+          references: data.slice(0, 100).map((r: Record<string, string>) => ({
+            cited_doi: extractDoi(r.cited ?? ""),
+            citing_doi: extractDoi(r.citing ?? ""),
+            creation_date: r.creation,
+          })),
+          _source_health: { source: "opencitations", latency_ms: tracked.latency_ms },
+        });
+      },
+    },
+    {
+      name: "get_citation_count",
+      label: "Get Citation Count (OpenCitations)",
+      description:
+        "Get the total citation count for a DOI from OpenCitations open data.",
+      parameters: Type.Object({
+        doi: Type.String({
+          description: "DOI of the paper, e.g. '10.1038/nature12373'",
+        }),
+      }),
+      execute: async (input: { doi: string }) => {
+        const doi = input.doi.replace(/^https?:\/\/doi\.org\//, "");
+        const tracked = await trackedFetch("opencitations", `${BASE}/index/v2/citation-count/doi:${encodeURIComponent(doi)}`);
+        if (isTrackedError(tracked)) return tracked;
+        const data = await tracked.res.json();
+
+        const count = Array.isArray(data) && data[0]?.count
+          ? parseInt(data[0].count, 10)
+          : 0;
+
+        return toolResult({ doi, citation_count: count, _source_health: { source: "opencitations", latency_ms: tracked.latency_ms } });
+      },
+    },
+  ];
+}

package/src/tools/orcid.ts

@@ -0,0 +1,136 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+
+const BASE = "https://pub.orcid.org/v3.0";
+
+const HEADERS: Record<string, string> = {
+  Accept: "application/json",
+};
+
+export function createOrcidTools(
+  _ctx: OpenClawPluginToolContext,
+  _api: OpenClawPluginApi,
+) {
+  return [
+    {
+      name: "search_orcid",
+      label: "Search Researchers (ORCID)",
+      description:
+        "Search the ORCID registry for researchers by name, affiliation, or keyword. Returns ORCID iDs that can be used with get_orcid_works.",
+      parameters: Type.Object({
+        query: Type.String({
+          description:
+            "Lucene-style query. Supports fields: family-name, given-names, affiliation-org-name, keyword, orcid, ringgold-org-id. E.g. 'family-name:Smith AND affiliation-org-name:MIT'",
+        }),
+        limit: Type.Optional(
+          Type.Number({ description: "Max results (default 10, max 100)" }),
+        ),
+      }),
+      execute: async (input: { query: string; limit?: number }) => {
+        const params = new URLSearchParams({
+          q: input.query,
+          rows: String(Math.min(input.limit ?? 10, 100)),
+        });
+
+        const result = await trackedFetch(
+          "orcid",
+          `${BASE}/search/?${params}`,
+          { headers: HEADERS },
+          10_000,
+        );
+        if (isTrackedError(result)) return result;
+        const data = await result.res.json();
+
+        const researchers = (data.result ?? []).map(
+          (r: Record<string, unknown>) => {
+            const oi = r["orcid-identifier"] as Record<string, string> | undefined;
+            return {
+              orcid: oi?.path,
+              uri: oi?.uri,
+              source: "orcid",
+            };
+          },
+        );
+
+        return toolResult({
+          total_results: data["num-found"],
+          source: "orcid",
+          researchers,
+          _latency_ms: result.latency_ms,
+        });
+      },
+    },
+    {
+      name: "get_orcid_works",
+      label: "Get Works by ORCID (ORCID)",
+      description:
+        "Get the publication list for a researcher by their ORCID iD. Returns titles, DOIs, publication years, and work types.",
+      parameters: Type.Object({
+        orcid: Type.String({
+          description: "ORCID iD, e.g. '0000-0002-1825-0097'",
+        }),
+      }),
+      execute: async (input: { orcid: string }) => {
+        const orcid = input.orcid.replace(/^https?:\/\/orcid\.org\//, "");
+
+        const result = await trackedFetch(
+          "orcid",
+          `${BASE}/${encodeURIComponent(orcid)}/works`,
+          { headers: HEADERS },
+          10_000,
+        );
+        if (isTrackedError(result)) return result;
+        const data = await result.res.json();
+
+        const groups = data.group as Array<Record<string, unknown>> | undefined;
+
+        const works = (groups ?? []).map((g) => {
+          const summaries = g["work-summary"] as Array<Record<string, unknown>> | undefined;
+          const first = summaries?.[0];
+          if (!first) return null;
+
+          // Extract title
+          const titleObj = first.title as Record<string, unknown> | undefined;
+          const title = (titleObj?.title as Record<string, string> | undefined)?.value;
+
+          // Extract publication date
+          const pubDate = first["publication-date"] as Record<string, unknown> | undefined;
+          const year = (pubDate?.year as Record<string, string> | undefined)?.value;
+          const month = (pubDate?.month as Record<string, string> | undefined)?.value;
+
+          // Extract DOI from external-ids
+          const extIds = first["external-ids"] as Record<string, unknown> | undefined;
+          const extIdList = extIds?.["external-id"] as Array<Record<string, unknown>> | undefined;
+          const doiEntry = extIdList?.find(
+            (e) => e["external-id-type"] === "doi" && e["external-id-relationship"] === "self",
+          );
+          const doi = doiEntry?.["external-id-value"] as string | undefined;
+
+          // Extract journal title
+          const journalTitle = first["journal-title"] as Record<string, string> | undefined;
+
+          return {
+            title,
+            doi,
+            year,
+            month,
+            type: first.type,
+            journal: journalTitle?.value,
+            url: doi ? `https://doi.org/${doi}` : undefined,
+            authors: undefined as string[] | undefined, // ORCID works endpoint does not include author lists
+            source: "orcid",
+          };
+        }).filter(Boolean);
+
+        return toolResult({
+          orcid,
+          total_works: works.length,
+          source: "orcid",
+          works,
+          _latency_ms: result.latency_ms,
+        });
+      },
+    },
+  ];
+}

package/src/tools/osf-preprints.ts

@@ -0,0 +1,104 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+
+const BASE = "https://api.osf.io/v2";
+
+export function createOsfPreprintsTools(
+  _ctx: OpenClawPluginToolContext,
+  _api: OpenClawPluginApi,
+) {
+  return [
+    {
+      name: "search_osf_preprints",
+      label: "Search Preprints (OSF)",
+      description:
+        "Search OSF Preprints, an aggregator covering 180K+ preprints across multiple providers including SocArXiv, PsyArXiv, EarthArXiv, EngrXiv, and NutriXiv. Covers social sciences, psychology, earth sciences, engineering, and more.",
+      parameters: Type.Object({
+        provider: Type.Optional(
+          Type.String({
+            description:
+              "Preprint provider filter: 'osf', 'socarxiv', 'psyarxiv', 'engrxiv', 'eartharxiv', 'nutrixiv'. Omit for all providers.",
+          }),
+        ),
+        size: Type.Optional(
+          Type.Number({ description: "Max results (default 10, max 100)" }),
+        ),
+        page: Type.Optional(
+          Type.Number({ description: "Page number (default 1)" }),
+        ),
+      }),
+      execute: async (input: {
+        provider?: string;
+        size?: number;
+        page?: number;
+      }) => {
+        const params = new URLSearchParams({
+          "page[size]": String(Math.min(input.size ?? 10, 100)),
+        });
+        if (input.provider) params.set("filter[provider]", input.provider);
+        if (input.page) params.set("page", String(input.page));
+
+        const result = await trackedFetch(
+          "osf_preprints",
+          `${BASE}/preprints/?${params}`,
+          {
+            headers: {
+              Accept: "application/vnd.api+json",
+            },
+          },
+          20_000,
+        );
+        if (isTrackedError(result)) return result;
+        const data = await result.res.json();
+
+        const items = data.data as Array<Record<string, unknown>> | undefined;
+        const linksMeta = (data.links as Record<string, unknown>)?.meta as Record<string, unknown> | undefined;
+
+        return toolResult({
+          total_results: linksMeta?.total,
+          page: input.page ?? 1,
+          source: "osf_preprints",
+          preprints: (items ?? []).map((item) => {
+            const attrs = item.attributes as Record<string, unknown> | undefined;
+            const relationships = item.relationships as Record<string, unknown> | undefined;
+            const providerData = (
+              relationships?.provider as Record<string, unknown> | undefined
+            )?.data as Record<string, string> | undefined;
+            const subjects = attrs?.subjects as Array<Array<{ id: string; text: string }>> | undefined;
+
+            // Flatten nested subject arrays
+            const subjectNames = subjects
+              ?.flat()
+              .map((s) => s.text)
+              .filter(Boolean);
+
+            return {
+              id: item.id,
+              title: attrs?.title,
+              description: attrs?.description
+                ? String(attrs.description).slice(0, 500)
+                : undefined,
+              doi: attrs?.doi ?? undefined,
+              date_created: attrs?.date_created,
+              date_published: attrs?.date_published,
+              year: attrs?.date_published
+                ? String(attrs.date_published).slice(0, 4)
+                : attrs?.date_created
+                  ? String(attrs.date_created).slice(0, 4)
+                  : undefined,
+              provider: providerData?.id,
+              tags: attrs?.tags,
+              subjects: subjectNames,
+              is_published: attrs?.is_published,
+              authors: undefined as string[] | undefined, // OSF preprint list does not embed contributor names
+              url: `https://osf.io/preprints/${providerData?.id ?? "osf"}/${String(item.id).replace(/_v\d+$/, "")}`,
+              source: "osf_preprints",
+            };
+          }),
+          _latency_ms: result.latency_ms,
+        });
+      },
+    },
+  ];
+}

package/src/tools/pubmed.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
 
 const EUTILS = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
 
@@ -53,23 +53,27 @@ export function createPubMedTools(
         if (input.max_date) searchParams.set("maxdate", input.max_date);
         if (input.min_date || input.max_date) searchParams.set("datetype", "pdat");
 
-        const searchRes = await fetch(`${EUTILS}/esearch.fcgi?${searchParams}`);
-        if (!searchRes.ok)
-          return toolResult({ error: `Search error: ${searchRes.status} ${searchRes.statusText}` });
-        const searchData = await searchRes.json();
+        const searchTracked = await trackedFetch("pubmed", `${EUTILS}/esearch.fcgi?${searchParams}`);
+        if (isTrackedError(searchTracked)) return searchTracked;
+        const searchData = await searchTracked.res.json();
         const ids: string[] = searchData.esearchresult?.idlist ?? [];
 
-        if (ids.length === 0) return toolResult({ total_count: searchData.esearchresult?.count ?? 0, articles: [] });
+        if (ids.length === 0) {
+          return toolResult({
+            total_count: searchData.esearchresult?.count ?? 0,
+            articles: [],
+            _source_health: { source: "pubmed", latency_ms: searchTracked.latency_ms },
+          });
+        }
 
         const summaryParams = new URLSearchParams({
           db: "pubmed",
           id: ids.join(","),
           retmode: "json",
         });
-        const summaryRes = await fetch(`${EUTILS}/esummary.fcgi?${summaryParams}`);
-        if (!summaryRes.ok)
-          return toolResult({ error: `Summary error: ${summaryRes.status} ${summaryRes.statusText}` });
-        const summaryData = await summaryRes.json();
+        const summaryTracked = await trackedFetch("pubmed", `${EUTILS}/esummary.fcgi?${summaryParams}`);
+        if (isTrackedError(summaryTracked)) return summaryTracked;
+        const summaryData = await summaryTracked.res.json();
 
         const articles = ids.map((id) => {
           const doc = summaryData.result?.[id];
@@ -92,6 +96,7 @@ export function createPubMedTools(
         return toolResult({
           total_count: parseInt(searchData.esearchresult?.count ?? "0", 10),
           articles,
+          _source_health: { source: "pubmed", latency_ms: summaryTracked.latency_ms },
         });
       },
     },
@@ -109,9 +114,9 @@ export function createPubMedTools(
           id: input.pmid,
           retmode: "xml",
         });
-        const res = await fetch(`${EUTILS}/efetch.fcgi?${params}`);
-        if (!res.ok) return toolResult({ error: `API error: ${res.status} ${res.statusText}` });
-        const xml = await res.text();
+        const tracked = await trackedFetch("pubmed", `${EUTILS}/efetch.fcgi?${params}`);
+        if (isTrackedError(tracked)) return tracked;
+        const xml = await tracked.res.text();
 
         const getText = (tag: string) => {
           const m = xml.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`));
@@ -162,6 +167,7 @@ export function createPubMedTools(
           pmc,
           mesh_terms: getMesh(),
           url: `https://pubmed.ncbi.nlm.nih.gov/${input.pmid}/`,
+          _source_health: { source: "pubmed", latency_ms: tracked.latency_ms },
         });
       },
     },

package/src/tools/ror.ts

@@ -0,0 +1,118 @@
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
+
+const BASE = "https://api.ror.org/v2";
+
+export function createRorTools(
+  _ctx: OpenClawPluginToolContext,
+  _api: OpenClawPluginApi,
+) {
+  return [
+    {
+      name: "search_ror",
+      label: "Search Research Organizations (ROR)",
+      description:
+        "Search the Research Organization Registry (ROR) for institutions, universities, labs, and funders. Returns canonical identifiers, locations, types, and links. Useful for affiliation disambiguation and finding institution metadata.",
+      parameters: Type.Object({
+        query: Type.String({
+          description: "Organization name or acronym to search, e.g. 'MIT', 'Max Planck', 'CNRS'",
+        }),
+        max_results: Type.Optional(
+          Type.Number({ description: "Max results (default 10, max 50)" }),
+        ),
+      }),
+      execute: async (input: { query: string; max_results?: number }) => {
+        const params = new URLSearchParams({
+          query: input.query,
+        });
+
+        const tracked = await trackedFetch("ror", `${BASE}/organizations?${params}`, undefined, 10_000);
+        if (isTrackedError(tracked)) return tracked;
+        const data = await tracked.res.json();
+
+        const maxResults = Math.min(input.max_results ?? 10, 50);
+        const items = (data.items ?? []).slice(0, maxResults).map(
+          (org: Record<string, unknown>) => {
+            const names = org.names as Array<{
+              value: string;
+              types: string[];
+              lang: string | null;
+            }> | undefined;
+            const locations = org.locations as Array<{
+              geonames_details: {
+                name: string;
+                country_name: string;
+                country_code: string;
+                country_subdivision_name?: string;
+                lat: number;
+                lng: number;
+              };
+            }> | undefined;
+            const links = org.links as Array<{
+              type: string;
+              value: string;
+            }> | undefined;
+            const externalIds = org.external_ids as Array<{
+              type: string;
+              all: string[];
+              preferred: string | null;
+            }> | undefined;
+
+            // Extract the display name (ror_display type preferred, then first label)
+            const displayName = names?.find(
+              (n) => n.types.includes("ror_display"),
+            )?.value;
+            const acronym = names?.find(
+              (n) => n.types.includes("acronym"),
+            )?.value;
+            const aliases = names
+              ?.filter((n) => n.types.includes("alias"))
+              .map((n) => n.value);
+            const labels = names
+              ?.filter((n) => n.types.includes("label") && !n.types.includes("ror_display"))
+              .map((n) => ({ name: n.value, lang: n.lang }));
+
+            const location = locations?.[0]?.geonames_details;
+            const website = links?.find((l) => l.type === "website")?.value;
+            const wikipedia = links?.find((l) => l.type === "wikipedia")?.value;
+
+            // Extract GRID and other IDs
+            const gridId = externalIds?.find((e) => e.type === "grid")?.preferred;
+            const wikidataId = externalIds?.find((e) => e.type === "wikidata")?.preferred;
+
+            return {
+              ror_id: org.id,
+              name: displayName ?? names?.[0]?.value,
+              acronym,
+              aliases: aliases?.length ? aliases : undefined,
+              labels: labels?.length ? labels : undefined,
+              types: org.types,
+              status: org.status,
+              established: org.established,
+              location: location
+                ? {
+                    city: location.name,
+                    country: location.country_name,
+                    country_code: location.country_code,
+                    region: location.country_subdivision_name,
+                  }
+                : undefined,
+              website,
+              wikipedia,
+              domains: org.domains,
+              grid_id: gridId,
+              wikidata_id: wikidataId,
+            };
+          },
+        );
+
+        return toolResult({
+          total_results: data.number_of_results,
+          organizations: items,
+          _source_health: { source: "ror", latency_ms: tracked.latency_ms },
+        });
+      },
+    },
+  ];
+}

package/src/tools/unpaywall.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
-import { toolResult } from "./util.js";
+import { toolResult, trackedFetch, isTrackedError } from "./util.js";
 
 const BASE = "https://api.unpaywall.org/v2";
 
@@ -23,14 +23,19 @@ export function createUnpaywallTools(
       }),
       execute: async (input: { doi: string }) => {
         const doi = input.doi.replace(/^https?:\/\/doi\.org\//, "");
-        const res = await fetch(
+        const tracked = await trackedFetch(
+          "unpaywall",
           `${BASE}/${encodeURIComponent(doi)}?email=${email}`,
         );
-        if (!res.ok) {
-          if (res.status === 404) return toolResult({ error: "DOI not found in Unpaywall" });
-          return toolResult({ error: `API error: ${res.status} ${res.statusText}` });
+        if (isTrackedError(tracked)) {
+          // Special handling for 404 (DOI not found)
+          if (tracked.details && typeof tracked.details === "object" && "error" in (tracked.details as Record<string, unknown>)) {
+            const errMsg = String((tracked.details as Record<string, string>).error);
+            if (errMsg.includes("404")) return toolResult({ error: "DOI not found in Unpaywall" });
+          }
+          return tracked;
         }
-        const data = await res.json();
+        const data = await tracked.res.json();
 
         const oaLocations = (
           data.oa_locations as Record<string, unknown>[] | undefined
@@ -53,6 +58,7 @@ export function createUnpaywallTools(
           publisher: data.publisher,
           published_date: data.published_date,
           oa_locations: oaLocations,
+          _source_health: { source: "unpaywall", latency_ms: tracked.latency_ms },
         });
       },
     },