# Seltz.ai Search Extension

This directory contains a Pi extension that registers two tools for web-grounded search and Q&A via the Seltz.ai API: `seltz_search` and `seltz_answer`.

## Available Tools

### `seltz_search`
Search the live web and return structured documents with URLs, content, and publication dates. Use when you need full document context — code samples, API docs, multi-step guides, comparisons, or any data that may have changed since your training cutoff.

### `seltz_answer`
Get a direct, natural-language answer with source citations. Use for quick factual lookups — "who", "what", "when", "where" queries, pricing, current events, or yes/no questions.

## When to Use Which

- **Use `seltz_answer`** for simple factual queries that need a direct answer with citations.
- **Use `seltz_search`** when you need deeper document context, code examples, or structured information.
- Prefer `seltz_answer` over `seltz_search` for simple factual queries.

## Tool Parameters

**`seltz_search`:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | string | The search query (keep it short) |
| `max_results` | number | Max results (default: 10) |
| `include_domains` | string[] | Only include these domains |
| `exclude_domains` | string[] | Exclude these domains |
| `scope` | "news" | Limit to news |
| `from_date` | string | Results on or after (ISO 8601) |
| `to_date` | string | Results on or before (ISO 8601) |
| `api_key` | string | Overrides all other key sources |

**`seltz_answer`:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | string | The question to answer |
| `model` | string | Tier selector (e.g. "seltz-base") |
| `include_content` | boolean | Include source content in citations |
| `scope` | "news" | Limit grounding search to news |
| `api_key` | string | Overrides all other key sources |

## API Key Resolution

The extension resolves the API key in this order (first match wins):

1. **Tool parameter** — pass `api_key` directly in the tool call
2. **Environment variable** — `SELTZ_API_KEY`
3. **Global config** — `~/.seltz/config.json` containing `{ "api_key": "..." }`
4. **Project config** — `<cwd>/.seltz/config.json` containing `{ "api_key": "..." }`

### Option 1: Environment variable
```bash
export SELTZ_API_KEY="your-api-key"
```

### Option 2: Global config file (recommended)
```bash
mkdir -p ~/.seltz
cp .seltz/config.json.example ~/.seltz/config.json
# Edit with your real API key
```

### Option 3: Project config file
```bash
cp .seltz/config.json.example .seltz/config.json
# Edit with your real API key
```

Get your API key at https://console.seltz.ai/api-keys

## Installation

### npm

```bash
pi install npm:pi-seltz-search
```

### Git

```bash
pi install git:codeberg.org/iobear/pi-seltz-search
```

### Local

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

### Manual install

```bash
# Global (all projects)
cp seltz.ts ~/.pi/agent/extensions/seltz.ts

# Project-local
mkdir -p .pi/extensions && cp seltz.ts .pi/extensions/seltz.ts

# Quick test
pi -e ./seltz.ts
```

## Links

- [Seltz.ai](https://seltz.ai)
- [Seltz API Docs](https://docs.seltz.ai/api-reference/)
- [Seltz Console](https://console.seltz.ai/)