124 lines
2.7 KiB
Markdown
124 lines
2.7 KiB
Markdown
# @jmcombs/pi-tavily-search
|
|
|
|
A [Pi coding agent](https://pi.dev) extension that adds real-time web search via the
|
|
[Tavily API](https://tavily.com).
|
|
|
|
## Install
|
|
|
|
```bash
|
|
# Globally (recommended)
|
|
pi install npm:@jmcombs/pi-tavily-search
|
|
|
|
# For a single session, without installing
|
|
pi -e npm:@jmcombs/pi-tavily-search
|
|
```
|
|
|
|
A Tavily API key is required. [Sign up at tavily.com](https://tavily.com) (free tier
|
|
available) to get one, then configure it using one of the methods below.
|
|
|
|
## What It Adds
|
|
|
|
- **Tool**: `tavily_search` — performs an advanced Tavily web search and returns up to
|
|
five formatted results (title, URL, content) plus the raw API response under
|
|
`details.raw`. The tool is callable by the LLM whenever it needs current
|
|
information from the public web.
|
|
|
|
## Configuration
|
|
|
|
You must configure a Tavily API key. Pi resolves the key in this order:
|
|
|
|
1. `AuthStorage` under the `tavily` key (`~/.pi/agent/auth.json`) — **recommended**.
|
|
2. The `TAVILY_API_KEY` environment variable.
|
|
|
|
### Option 1 — `~/.pi/agent/auth.json` (recommended)
|
|
|
|
#### Plain key
|
|
|
|
```json
|
|
{
|
|
"tavily": {
|
|
"type": "api_key",
|
|
"key": "tvly-..."
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Shell-resolved key (macOS Keychain)
|
|
|
|
```json
|
|
{
|
|
"tavily": {
|
|
"type": "api_key",
|
|
"key": "!security find-generic-password -ws tavily"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Shell-resolved key (1Password)
|
|
|
|
```json
|
|
{
|
|
"tavily": {
|
|
"type": "api_key",
|
|
"key": "!op read 'op://Personal/tavily/credential'"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Shell-resolved key (`pass`)
|
|
|
|
```json
|
|
{
|
|
"tavily": {
|
|
"type": "api_key",
|
|
"key": "!pass show tavily"
|
|
}
|
|
}
|
|
```
|
|
|
|
The `!`-prefixed value is executed by your shell at lookup time, so no secret is
|
|
ever stored on disk in plaintext.
|
|
|
|
### Option 2 — environment variable
|
|
|
|
```bash
|
|
export TAVILY_API_KEY="tvly-..."
|
|
```
|
|
|
|
## Behavior Notes
|
|
|
|
- Search depth: `advanced`
|
|
- Max results returned: 5
|
|
- The tool honors Pi's abort signal — pressing **Esc** during a search cancels the
|
|
HTTP request.
|
|
- If the API key is missing the tool returns an error result with a helpful
|
|
configuration hint instead of throwing.
|
|
- Non-2xx responses from Tavily surface as tool errors (with status, status text,
|
|
and response body) rather than throwing.
|
|
|
|
## Requirements
|
|
|
|
- Pi `>= 0.72.0` (uses `AuthStorage` and `ExtensionAPI`)
|
|
- Node `>= 20.6.0`
|
|
- A Tavily API key
|
|
|
|
## Development
|
|
|
|
This package lives in the [pi-extensions monorepo](https://github.com/jmcombs/pi-extensions).
|
|
|
|
```bash
|
|
# From the repo root
|
|
npm ci
|
|
npm run check # full quality gate
|
|
|
|
# Try local changes against a real pi session
|
|
pi -e ./packages/tavily-search
|
|
```
|
|
|
|
The smoke test in `index.test.ts` does **not** mock the Tavily API; it only
|
|
verifies registration shape. Real end-to-end behavior is exercised via `pi -e`.
|
|
|
|
## License
|
|
|
|
[MIT](./LICENSE) © Jeremy Combs
|