@sisu-ai/tool-wikipedia 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# @sisu-ai/tool-wikipedia
+
+Wikipedia lookup tool using the REST API. Fetch a page summary, HTML, or related pages given an approximate title. The REST API performs redirects and normalization, so near-matches often resolve.
+
+Install
+```bash
+npm i @sisu-ai/tool-wikipedia
+```
+
+Environment / Flags
+- Language: `WIKIPEDIA_LANG` or `WIKI_LANG` (e.g., `en`, `sv`). CLI flags follow kebab-case, e.g., `--wikipedia-lang=sv`.
+- Base URL override: `WIKIPEDIA_BASE_URL` or `WIKI_BASE_URL` (e.g., `https://en.wikipedia.org/api/rest_v1`). CLI flag `--wikipedia-base-url=...`.
+- Defaults to `https://en.wikipedia.org/api/rest_v1`.
+
+Usage
+```ts
+import { Agent } from '@sisu-ai/core';
+import { registerTools } from '@sisu-ai/mw-register-tools';
+import { toolCalling } from '@sisu-ai/mw-tool-calling';
+import { wikipedia } from '@sisu-ai/tool-wikipedia';
+
+const app = new Agent()
+  .use(registerTools([wikipedia]))
+  .use(toolCalling);
+```
+
+Tool
+- Name: `wikipediaLookup`
+- Args:
+  - `title: string` — approximate page title
+  - `format?: 'summary'|'html'|'related'` — default `summary`
+  - `lang?: string` — language code; otherwise from env/flags
+
+Returns
+- `summary`: `{ type?, title, description?, extract?, url?, thumbnailUrl? }`
+- `html`: `string` HTML
+- `related`: `Array<{ title, description?, extract?, url?, thumbnailUrl? }>`
+
+Notes
+- For search-like behavior, consider calling `related` first and then fetching the best candidate's `summary`.
+

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { Tool } from '@sisu-ai/core';
+export type WikipediaFormat = 'summary' | 'html' | 'related';
+export interface WikipediaArgs {
+    title: string;
+    format?: WikipediaFormat;
+    lang?: string;
+}
+export type WikipediaSummaryResult = {
+    type?: string;
+    title: string;
+    description?: string;
+    extract?: string;
+    url?: string;
+    thumbnailUrl?: string;
+};
+export type WikipediaRelatedResult = Array<{
+    title: string;
+    description?: string;
+    extract?: string;
+    url?: string;
+    thumbnailUrl?: string;
+}>;
+export declare const wikipedia: Tool<WikipediaArgs>;
+export default wikipedia;

package/dist/index.js

@@ -0,0 +1,72 @@
+import { firstConfigValue } from '@sisu-ai/core';
+import { z } from 'zod';
+export const wikipedia = {
+    name: 'wikipediaLookup',
+    description: 'Fetch a Wikipedia page summary, HTML, or related pages given an approximate title. Defaults to summary.',
+    schema: z.object({
+        title: z.string().min(1),
+        format: z.enum(['summary', 'html', 'related']).optional(),
+        lang: z.string().min(2).max(10).optional(),
+    }),
+    handler: async ({ title, format = 'summary', lang }, ctx) => {
+        const base = resolveBaseUrl(ctx, lang);
+        if (format === 'html')
+            return fetchHtml(base, title);
+        if (format === 'related')
+            return fetchRelated(base, title);
+        return fetchSummary(base, title);
+    }
+};
+export default wikipedia;
+function resolveBaseUrl(ctx, lang) {
+    // Precedence: CLI flags (via core helpers) > env vars; allow overriding full base or just language
+    const baseFromFlags = firstConfigValue(['WIKIPEDIA_BASE_URL', 'WIKI_BASE_URL']);
+    const langFromFlags = firstConfigValue(['WIKIPEDIA_LANG', 'WIKI_LANG']) || lang;
+    if (baseFromFlags)
+        return baseFromFlags.replace(/\/$/, '');
+    const chosenLang = (langFromFlags || 'en').toLowerCase();
+    return `https://${chosenLang}.wikipedia.org/api/rest_v1`;
+}
+async function fetchSummary(baseUrl, title) {
+    const url = `${baseUrl}/page/summary/${encodeURIComponent(title)}`;
+    const res = await fetch(url, { headers: { Accept: 'application/json' } });
+    const raw = await res.text();
+    if (!res.ok)
+        throw new Error(`Wikipedia summary failed: ${res.status} ${res.statusText}`);
+    const json = raw ? JSON.parse(raw) : {};
+    return {
+        type: json.type,
+        title: String(json.displaytitle || json.title || title),
+        description: json.description,
+        extract: json.extract,
+        url: json.content_urls?.desktop?.page || json.content_urls?.mobile?.page,
+        thumbnailUrl: json.thumbnail?.source,
+    };
+}
+async function fetchHtml(baseUrl, title) {
+    const url = `${baseUrl}/page/html/${encodeURIComponent(title)}`;
+    const res = await fetch(url, { headers: { Accept: 'text/html' } });
+    const raw = await res.text();
+    const ct = res.headers?.get?.('content-type') || '';
+    if (!res.ok)
+        throw new Error(`Wikipedia html failed: ${res.status} ${res.statusText}`);
+    if (!ct.toLowerCase().includes('text/html'))
+        throw new Error(`Wikipedia html returned non-HTML content (content-type: ${ct})`);
+    return raw;
+}
+async function fetchRelated(baseUrl, title) {
+    const url = `${baseUrl}/page/related/${encodeURIComponent(title)}`;
+    const res = await fetch(url, { headers: { Accept: 'application/json' } });
+    const raw = await res.text();
+    if (!res.ok)
+        throw new Error(`Wikipedia related failed: ${res.status} ${res.statusText}`);
+    const json = raw ? JSON.parse(raw) : {};
+    const pages = Array.isArray(json.pages) ? json.pages : [];
+    return pages.map(p => ({
+        title: String(p.title || ''),
+        description: p.description,
+        extract: p.extract,
+        url: p.content_urls?.desktop?.page,
+        thumbnailUrl: p.thumbnail?.source,
+    })).filter(r => r.title);
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@sisu-ai/tool-wikipedia",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "@sisu-ai/core": "0.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/finger-gun/sisu",
+    "directory": "packages/tools/wikipedia"
+  },
+  "homepage": "https://github.com/finger-gun/sisu#readme",
+  "bugs": {
+    "url": "https://github.com/finger-gun/sisu/issues"
+  }
+}