# pi-web-search

`pi-web-search` is a Pi extension package that adds Exa-backed `web_search` and `web_fetch` tools.

## Install

Local path:

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

Git:

```bash
pi install https://gitea.rwiesner.com/pi/pi-web-search
```

## Resources

- Extension: `./index.ts`

## Configuration

Set `EXA_API_KEY`, or create `~/.pi/agent/web-search.json`:

```json
{
  "apiKey": "exa_...",
  "baseUrl": "https://api.exa.ai"
}
```

Notes:
- `apiKey` is required unless `EXA_API_KEY` is set.
- `baseUrl` is optional.
- Older multi-provider configs are no longer supported.

## Tool behavior

### `web_search`

Maps directly to Exa `search(query, options)`.

Notes:
- Exa search returns text contents by default.
- Pass `contents: false` for metadata-only search results.
- `additionalQueries` is only valid for deep search types: `deep-lite`, `deep`, `deep-reasoning`.
- `includeText` and `excludeText` currently support at most one phrase of up to 5 words.

Example:

```json
{
  "query": "Who leads OpenAI's safety team?",
  "type": "deep",
  "numResults": 5,
  "systemPrompt": "Prefer official docs",
  "outputSchema": {
    "type": "text",
    "description": "Answer in short bullets"
  },
  "contents": {
    "highlights": {
      "query": "OpenAI safety lead",
      "maxCharacters": 300
    },
    "summary": true
  }
}
```

Metadata-only search:

```json
{
  "query": "pi docs",
  "contents": false,
  "includeDomains": ["pi.dev"]
}
```

### `web_fetch`

Maps directly to Exa `getContents(urls, options)`.

Example:

```json
{
  "urls": ["https://pi.dev"],
  "text": {
    "maxCharacters": 4000,
    "verbosity": "standard"
  },
  "highlights": {
    "query": "tooling",
    "maxCharacters": 300
  },
  "summary": true,
  "livecrawl": "preferred",
  "extras": {
    "links": 20,
    "imageLinks": 10
  }
}
```

## Development

```bash
npm install
npm test
```