# pi-exa-api

Web search and content fetching for [pi](https://pi.dev) via the [Exa API](https://exa.ai/).

## Installation

Install as a pi package:

```bash
pi install npm:@jarcelao/pi-exa-api
```

## Configuration

You can configure your Exa API key using either method below. File-based auth takes priority over the environment variable.

### Option 1 — Auth file (recommended)

Create `~/.pi/agent/exa-auth.json`:

```json
{
  "exaApiKey": "your-api-key-here"
}
```

### Option 2 — Environment variable

Set your Exa API key as an environment variable before starting pi:

```bash
export EXA_API_KEY="your-api-key-here"
pi
```

Or add to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) for persistence.

### Check Configuration

Run the `/exa-status` command in pi to verify your API key is configured and see which source it was loaded from:

```
/exa-status
```

## Usage

### Web Search

The agent can use `exa_search` to find information on the web:

```
Search for recent developments in quantum computing
```

**Parameters:**

- `query` (required) - Natural language search query
- `contentType` (optional) - Type of content to retrieve:
  - `highlights` (default) - Key excerpts from each result
  - `text` - Full text content (may be truncated)
  - `summary` - AI-generated summary
  - `none` - Metadata only (title, URL, date, author)
- `numResults` (optional) - Number of results (1-100, default: 10)

### Fetch URL Content

The agent can use `exa_fetch` to extract content from a specific URL:

```
Fetch the content from https://example.com/article
```

**Parameters:**

- `url` (required) - URL to fetch
- `contentType` (optional) - Type of content:
  - `text` (default) - Full page text
  - `highlights` - Key excerpts
  - `summary` - AI-generated summary
- `maxCharacters` (optional) - Maximum characters to return (1000-100000)

## Development

Refer to the [jarcelao/pi-extensions](https://github.com/jarcelao/pi-extensions) repo for development guidelines.

## License

MIT