# pi-web-research

Web search and page extraction tools for [Pi](https://pi.dev).

## Why I built this

I used Claude's web research when I needed context on a topic. Questions like "best onboarding practices for iOS apps" or "how do I set up Swift Testing with async support" — I'd get sources back, then pull the relevant pieces into a dev plan or notes.

When I started using Pi for daily coding, that capability was missing. I didn't want to copy-paste search results into chat. I wanted the agent to handle the research: run parallel searches, evaluate what it finds, scope to authoritative domains when needed, and surface only what matters.

This extension adds `web_search` and `web_fetch` to Pi, along with a prompt template that guides that workflow.

Other tools I tried had too much overhead — complex configs, nested skills, features I never used. I just needed web research to work.

## Tools

| Tool | Purpose |
|------|---------|
| `web_search` | Search the web via [Brave Search API](https://brave.com/search/api) and return ranked results |
| `web_fetch` | Fetch a URL, strip HTML, and extract content relevant to a specific prompt |

## Examples

**Research a specific technical topic:**

> "How do I migrate from XCTest to Swift Testing?"

Pi runs parallel searches, fetches the most relevant guide, and returns a summary with key steps and source links.

**Check current best practices:**

> "What are the recommended error handling patterns for Swift concurrency?"

Useful when documentation is scattered across blog posts, WWDC videos, and release notes.

**Evaluate a library before adoption:**

> "Is SwiftData production-ready? What are people saying about it in production apps?"

Pi searches for recent experience reports, fetches a few, and surfaces common issues and workarounds.

## Install

Install from npm (simplest):

```bash
pi install @bcuev/pi-web-research
```

Or install directly from GitHub:

```bash
pi install git:github.com/bcuev/pi-web-research
```

Or clone and install locally:

```bash
git clone https://github.com/bcuev/pi-web-research.git
cd pi-web-research
pi install .
```

## Setup

Sign up for a [Brave Search API key](https://brave.com/search/api), then export it in your shell:

```bash
export BRAVE_API_KEY=<your-key>
```

## Features

- **Search via Brave API** — rate-limit errors include retry-after headers
- **Caching** — 15-minute TTL on raw and extracted content so you don't re-fetch the same page in a session
- **Content-type guards** — only extracts from `text/*`, JSON, XML, and XHTML; rejects binary or unknown types
- **HTTPS → HTTP redirect guard** — blocks cross-origin downgrades before reading the response body
- **Truncation** — truncates large results to fit context limits using Pi's built-in `truncateHead`
- **Timeouts** — 30-second network timeouts via `AbortSignal`; respects Pi's cancellation

## Prompt template

The `research.md` prompt template tells Pi to:
1. Run 2 parallel broad searches
2. Evaluate quality before falling back to domain-scoped searches
3. Summarize findings with citations

## Requirements

- Pi ≥ 0.70.0
- Node.js ≥ 20
- `BRAVE_API_KEY` environment variable

## License

MIT