# pi-anysearch

An intentionally small [Pi](https://pi.dev) package that exposes AnySearch as `web_search`, plus `get_sub_domains` for discovering the provider's current vertical-search capabilities. It does not fetch pages and it does not route to other providers.

## Install

```sh
pi install npm:pi-anysearch
```

For local development, start Pi with `pi -e ./extensions/index.ts` from this repository.

## Configure

Set an API key before starting Pi:

```sh
export ANYSEARCH_API_KEY="your-key"
```

The package also supports AnySearch anonymous mode: leave `ANYSEARCH_API_KEY` unset and it sends no `Authorization` header. Availability and limits then depend on AnySearch. The API host is fixed to `https://api.anysearch.com`; this package does not accept a custom base URL.

## Use

```text
web_search({ query: "TypeScript decorators", max_results: 5 })
web_search({ queries: ["NVIDIA earnings", "AMD earnings"], zone: "intl" })
get_sub_domains({ domains: ["finance", "academic"] })
```

For vertical searches, call `get_sub_domains` first. It returns AnySearch's current Markdown capability table; use its returned sub-domain as `web_search.tag` and its documented parameters in `web_search.params`. Do not invent a tag or parameter names.

`web_search` accepts exactly one of `query` or `queries` (one to four values). It accepts `max_results` from 1 to 20 (default 5), `zone` (`cn` or `intl`), `language`, `tag`, `params`, `include_content`, and `fresh`. Results are formatted as Markdown. Snippets are capped at 500 characters; content is opt-in and capped at 2,000; total output is capped and marked when truncated.

## Safety and reliability

- API keys are read only from `ANYSEARCH_API_KEY`, are never emitted in results or errors, and are sent only as a Bearer header to AnySearch.
- Search responses are cached in-process for 60 seconds (up to 100 successful entries); pass `fresh: true` to bypass that cache. Sub-domain discovery uses a longer in-process cache.
- Requests time out after 15 seconds per attempt. Network failures and HTTP 500/503/504 retry once with jitter. Validation, authentication, quota, permission, and rate-limit errors do not retry.
- Tool details contain only safe summary metadata, never response bodies or credentials.

## Develop

```sh
npm install
npm run typecheck
npm test
npm run pack
```

The normal test suite never calls AnySearch. To opt into a single live smoke test, explicitly set both the gate and a key:

```sh
ANYSEARCH_LIVE_TEST=1 ANYSEARCH_API_KEY="your-key" npm run test:live
```