# pi-search

[![npm version](https://img.shields.io/npm/v/%40blessium/pi-search.svg?label=npm)](https://www.npmjs.com/package/@blessium/pi-search)
[![License: MIT](https://img.shields.io/badge/license-MIT-0b6e4f.svg)](LICENSE)

> Free web research for [pi](https://github.com/earendil-works/pi-coding-agent) that works out of the box. Install it once, ask a question, and pi can search the web, read pages, or find papers with no provider setup or API key.

`pi-search` is a compact pi extension for finding current material without flooding an agent's
context window. After installation, it needs no provider configuration or API key. It combines
hosted [Exa](https://exa.ai/docs/reference/exa-mcp) and [Parallel](https://parallel.ai) MCP
services, returns answer-ready excerpts first, and lets pi fetch source pages only when the
details matter.

## Why pi-search?

- **Works immediately, for free.** Install one package and pi is ready to search. Exa and Parallel both offer API-key-free access; add a key only when you need higher rate limits.
- **Keep research focused.** Search results are excerpt-first, so pi can answer from the useful parts before reading a full page.
- **Go beyond general search.** Find research papers, preprints, and journal articles through Exa's publication index.
- **Stay model-agnostic.** The same tools work with any model you run through pi.

## Install

```bash
pi install npm:@blessium/pi-search
```

Try it once without installing:

```bash
pi -e npm:@blessium/pi-search
```

Install a local checkout:

```bash
pi install /path/to/pi-search
```

## Ask pi

The extension registers its tools automatically. Ask pi for research in natural language:

| Ask pi | Tool used |
| --- | --- |
| "Find current documentation for the WebAuthn conditional UI API." | `web_search` |
| "Read https://example.com/article and extract the rollout dates." | `web_fetch` |
| "Find reporting from the last 24 hours about this release, limited to official sources." | `web_search_advanced` |
| "Find recent papers on retrieval-augmented generation and summarize the tradeoffs." | `search_papers` |

Describe the ideal source rather than listing bare keywords. Start with `web_search`, then use
`web_fetch` only for exact wording, a full-page analysis, or conflicting excerpts.

## Tools at a glance

| Tool | Best for | What it returns |
| --- | --- | --- |
| `web_search` | Everyday discovery: facts, documentation, news, people, and companies | Clean excerpts from the top results |
| `web_fetch` | Reading a public page when snippets are not enough | Clean markdown or focused excerpts from up to 20 URLs |
| `web_search_advanced` | Precise or time-sensitive research | Exa results filtered by category, domain, date, freshness, and context budget |
| `search_papers` | Literature reviews and paper discovery | Scholarly publications, preprints, and journal articles with excerpts or summaries |

For broad questions, pi can send two or three concise search angles to Parallel. For complex
research, the advanced and paper tools support `type: "deep"`; for breaking news,
`maxAgeHours: 0` forces a live crawl.

## Providers and configuration

`web_search` and `web_fetch` choose Exa or Parallel deterministically for each pi session, so a
conversation stays with one backend. Pin the basic tools to one provider when you need to:

```bash
PI_SEARCH_PROVIDER=exa pi
PI_SEARCH_PROVIDER=parallel pi
```

`web_search_advanced` and `search_papers` always use Exa because Parallel does not offer the
equivalent filters or publication index.

Both providers have a free tier. Optional keys raise rate limits:

```bash
EXA_API_KEY=your-key pi
PARALLEL_API_KEY=your-key pi
```

Some controls are provider-specific. Parallel honors `web_search.queries` plus
`web_fetch.objective` and `web_fetch.fullContent`; Exa searches `query` alone and uses
`maxCharacters` to cap fetch output. Unsupported controls are safely ignored.

## Privacy and security

Each tool call sends its query or URL to the selected Exa or Parallel service over HTTPS.
Parallel's basic tools also receive the current pi session ID and active model name. The extension
makes no filesystem writes, runs no shell commands, and stores no credentials locally. An optional
`EXA_API_KEY` or `PARALLEL_API_KEY` is sent only to its matching provider.

## Verify a checkout

```bash
npm run check
```

## License

[MIT](LICENSE)