nicobailon/pi-web-access

Pi Web Access – what it is

Pi Web Access is an npm package that gives the Pi AI‑agent a rich set of web‑search, content‑fetching, and video‑understanding capabilities. It bundles dozens of public search APIs (OpenAI, Exa, Brave, Kagi, Perplexity, etc.) and a fallback routing system so the agent can retrieve information even when some providers are unavailable. In addition to plain web pages it can:

Clone GitHub repositories locally (so the agent can read real files)
Pull YouTube videos and generate transcripts, visual descriptions, and frame extracts via Gemini or other video models
Process local video recordings, PDFs, and images
Cache fetched content for fast reuse and provide utilities for searching inside that cache.

All of this is exposed through a small TypeScript API (web_search, fetch_content, get_search_content, source_check) that the Pi runtime can call.

Quick‑start installation & first use

# Install the package (Pi’s own package manager forwards to npm)
pi install npm:pi-web-access

The default configuration works out‑of‑the‑box because it uses Exa MCP, a zero‑config search backend that needs no API key. If you are logged into Pi with a Codex subscription, OpenAI search works automatically as well.

// Simple web search
web_search({ query: "TypeScript best practices 2025" })

// Fetch a page (markdown‑ified)
fetch_content({ url: "https://docs.example.com/guide" })

// Clone a GitHub repo (real files, not scraped HTML)
fetch_content({ url: "https://github.com/owner/repo" })

// Ask a question about a YouTube video
fetch_content({
  url: "https://youtube.com/watch?v=abc",
  prompt: "What libraries are shown?"
})

If you want to use other providers, drop the relevant API keys into ~/.pi/web-search.json (see the README for the exact JSON shape).

Core features (jargon‑light)

Feature	What it does	Why it matters
Zero‑config search	Uses Exa MCP by default; falls back to the Pi model’s built‑in OpenAI search if you have a Codex login.	You can start searching immediately without signing up for any API.
Multi‑provider routing	Supports >30 search back‑ends (OpenAI, Brave, Kagi, Perplexity, etc.) with a configurable fallback chain.	Guarantees results even when a service is down or you hit a quota.
Video understanding	Sends YouTube URLs or local video files to Gemini (or other video models) to get transcripts, visual descriptions, and frame images.	Lets the agent answer questions about code demos, UI walkthroughs, or error messages shown on screen.
GitHub cloning	Detects GitHub repo URLs and clones them locally (or uses the GitHub CLI for PR/issue rendering).	The agent works with real source files, enabling `read`/`bash` commands on the code.
PDF conversion	Converts PDFs to markdown via a tiered engine (Datalab → Gemini → local pdf.js).	Preserves tables, headings, and math when possible, while still offering a free offline fallback.
Cache & retrieval	Stores fetched pages and videos in a private `web-search-cache` (1‑hour TTL, 128 MiB limit). Helper `get_search_content` can slice or search the cache.	Reduces duplicate network calls and lets the agent reference earlier results.
Source‑check tool	Given a claim, runs a search‑fetch‑summarise pipeline and returns a structured artifact with citation offsets and a confidence label (`supported`, `contradicted`, etc.).	Enables fact‑checking inside a Pi conversation.
Fine‑grained control	Parameters for `numResults`, `recencyFilter`, `domainFilter`, `includeContent`, `workflow`, etc., plus routing JSON to force specific providers.	Lets developers tailor cost, latency, and relevance.

How it fits into the AI‑agent ecosystem

Pi agents call web_search / fetch_content as tools; the responses are automatically turned into citations that the language model can reference.
The package abstracts away the messy parts of dealing with many different search APIs, handling authentication, rate‑limits, and SSRF safety.
By cloning GitHub repos and exposing raw file paths, it bridges the gap between “search the web” and “run code locally”, a common need for coding assistants.
Video and PDF support extends the agent beyond plain text, enabling richer multimodal reasoning.

Typical configuration snippet

{
  "openaiApiKey": "sk-...",
  "braveApiKey": "BSA_...",
  "exaApiKey": "exa-...",
  "githubClone": { "enabled": true },
  "searchRouting": {
    "providers": ["openai", "tavily"],
    "useCurrentModel": true,
    "fallbackOn": ["quota", "network"]
  },
  "pdf": {
    "provider": "auto",
    "datalabMode": "balanced"
  }
}

Place this file at ~/.pi/web-search.json and the Pi runtime will pick it up automatically.

When you might not need it

If you only require a single search API and have no need for video or GitHub cloning, a lighter‑weight library could suffice. Pi Web Access shines when you want a single, unified tool that can fall back across many providers and handle multimodal content.

Bottom line: Pi Web Access is a production‑grade, plug‑and‑play toolkit that equips the Pi AI‑agent with robust, multi‑source web search, content extraction, and video understanding, all controllable through a concise TypeScript API and a simple JSON config.