pi-web-kit

library0.1.6jsnpmunverified

pi-web-kit (v0.1.6, active development) provides web_search and web_fetch tools for the Pi agent framework. It supports multiple provider backends (Exa MCP, Exa API, TinyFish, Brave Search, Firecrawl, markdown.new) with bounded output, chunked reads, URL validation, and an in-memory fetch cache. Released weekly via npm, it is ESM-only, requires Node >=20.6.0, and depends on Pi core packages (@earendil-works/pi-ai, @earendil-works/pi-coding-agent, @earendil-works/pi-tui) and typebox. Differentiators: provider-tailored schemas, configurable caching, and concurrency control.

ai-ml search

npm install pi-web-kit

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PI-WEB-KIT

pi-web-kit

ai-mljavascriptv0.1.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

web_search

✓ import { web_search } from 'pi-web-kit'

✗ const web_search = require('pi-web-kit')

ESM-only; no CommonJS wrapper. Must be imported as named export.

web_fetch

✓ import { web_fetch } from 'pi-web-kit'

✗ const webFetch = require('pi-web-kit').web_fetch

ESM-only; named export, not default.

web_search as search

✓ import { web_search as search } from 'pi-web-kit'

✗ import search from 'pi-web-kit'

Default import does not exist; must use named import with alias.

type WebSearchResult

✓ import type { WebSearchResult } from 'pi-web-kit'

✗ import { WebSearchResult } from 'pi-web-kit'

Use type-only import for TypeScript type safety; runtime import will fail.

Demonstrates basic web_search and web_fetch usage with named imports, including chunked fetch via offset/limit.

import { web_search, web_fetch } from 'pi-web-kit'; async function quickstart() { // Search the web using configured provider const searchResults = await web_search('latest Node.js release'); console.log('Search results:', searchResults); // Fetch a single URL const fetchResult = await web_fetch('https://example.com'); console.log('Fetched content:', fetchResult); // Fetch with chunk offset/limit for long pages const partial = await web_fetch('https://example.com/long-doc', { offset: 0, limit: 8000 }); console.log('Partial content:', partial); } quickstart().catch(console.error);

Debug

Known issues

breakingRequires Node >=20.6.0; will fail on older versions.

fix

Upgrade Node to >=20.6.0.

affects: <=20.5.9

breakingESM-only package; cannot be used with require().

fix

Use static import syntax: import { ... } from 'pi-web-kit'.

affects: >=0.1.0

breakingPeer dependencies not installed automatically. Missing @earendil-works/pi-ai, @earendil-works/pi-coding-agent, @earendil-works/pi-tui, or typebox will cause runtime errors.

fix

Install peer deps: pi install @earendil-works/pi-ai @earendil-works/pi-coding-agent @earendil-works/pi-tui typebox

affects: >=0.1.0

deprecatedThe 'exa' provider (non-MCP) may be deprecated in favor of 'exa_mcp' in future releases.

fix

Switch to provider 'exa_mcp' if possible.

affects: 0.1.x

gotchaProvider config changes (e.g., via CLI flags) require a Pi restart/reload to take effect for tool schemas.

fix

After changing provider, restart or reload Pi with: pi reload

affects: >=0.1.0

gotchaURLs with embedded credentials (user:pass@host) are rejected by default.

fix

Remove credentials from URL before passing to web_fetch.

affects: >=0.1.0

gotchaIn-memory fetch cache uses provider/config/fetch-affecting options as part of the cache key. Changing provider at runtime without clearing cache may serve stale results.

fix

Clear cache on provider change or disable caching if needed.

affects: >=0.1.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/pi-web-kit/index.js from /path/to/your/code.js not supported.

Using CommonJS require() on an ESM-only package.

fix

Convert your project to ESM or use dynamic import(): const { web_search } = await import('pi-web-kit');

TypeError: Cannot read properties of undefined (reading 'web_search')

Default import assumed: import kit from 'pi-web-kit'; kit.web_search.

fix

Use named import: import { web_search } from 'pi-web-kit';

Error: Cannot find module 'typebox'

Missing peer dependency typebox.

fix

Install peer dependency: npm install typebox

TypeError: web_fetch is not a function

Provider not configured correctly or API key missing.

fix

Ensure EXA_API_KEY or other required env var is set. Check provider config with: echo $EXA_API_KEY

Error: Invalid URL: http://user:pass@example.com

URL contains embedded credentials which are blocked by validation.

fix

Remove user:pass from URL. If authentication is needed, use a different mechanism such as headers.

Upgrade

Version history

0.1.6latest on npm

Audit

Dependencies

@earendil-works/pi-airequiredPeer dependency for Pi AI integration

@earendil-works/pi-coding-agentrequiredPeer dependency for Pi coding agent integration

@earendil-works/pi-tuirequiredPeer dependency for Pi TUI integration

typeboxrequiredPeer dependency for TypeBox type provider

Agent activity

45 hits · last 30 days

node

Resources

githubhttps://github.com/jvm/pi-mono ↗

packagepi-web-kit ↗

homepagehttps://github.com/jvm/pi-mono/tree/main/packages/pi-web-kit#readme ↗