pi-anysearch-tools

pi-anysearch-tools is a Pi Coding Agent extension with two focused tools: anysearch for proactive general or vertical web search, and anysearch_extract for reading a selected page. Both are backed by the official AnySearch v3 endpoints:

POST https://api.anysearch.com/v1/search  (search, JSON summaries)
POST https://api.anysearch.com/mcp        (extract and capability discovery)

Use it proactively when an answer depends on current or externally verifiable information: documentation, news, prices, products, people, comparisons, fact-checking, recommendations, or vertical-domain data such as stocks, papers, legal cases, flights, drugs, code docs, and weather. It is not a replacement for Pi's local file or shell tools.

中文说明：这是一个面向 Pi Coding Agent 的 AnySearch 联网搜索扩展（官方 v3 混合接口：搜索走 /v1/search JSON，抽取/能力发现走 /mcp）。无需 API key 也可匿名使用，但匿名请求受速率和配额限制。

Core capabilities

• General web search as bounded Markdown (title, URL, and short snippet only — 500 chars per result, 12,000 chars total final cap including notices; use anysearch_extract for full page content).
• Vertical domain search via domain / sub_domain / sub_domain_params (17 domains), with capability discovery handled by the same anysearch entry.
• Parallel batch search: 1–5 queries in one call (1–5 accepted, 2–3 recommended); omitted max_results defaults to 3 per query; up to 5×10 supported but heavy — 12k cap keeps context bounded; a single failure does not block the rest.
• Full-page URL extraction as clean Markdown (server-truncated at 50,000 characters) — escalation path when snippets are insufficient.
• Domain-only calls return valid sub-domains and required parameters without executing a search; directory results are cached per session.
• Region (zone) and language passthrough; max_results is clamped to the server cap of 1–10 (default 3 per query).
• Anonymous access without initial configuration.
• Optional API-key authentication from an environment variable or Pi agent configuration.
• If the API auto-registers a new key on quota exhaustion, the extension asks once via the TUI and saves it after confirmation.
• Compact Pi TUI rendering (collapsed by default, expandable).

Installation

Install the published npm package:

pi install npm:pi-anysearch-tools

Local development and temporary use

From a checkout of this repository:

# Load the extension for the current Pi invocation only
pi -e .

# Install the local directory as a Pi package
pi install .

API key configuration

Configuration priority is:

ANYSEARCH_API_KEY environment variable
> <agent dir>/anysearch.json
> anonymous mode

Set the environment variable in your shell or CI environment:

export ANYSEARCH_API_KEY="your-api-key"

Or create ~/.pi/agent/anysearch.json:

{
  "anysearchApiKey": "your-api-key"
}

~/.pi/agent is Pi's default agent directory. If PI_CODING_AGENT_DIR is set, the extension reads anysearch.json from that directory instead.

Anonymous mode remains usable when no key is configured, but it has stricter rate and quota limits.

Auto-registered keys

When a configured key's quota is exhausted, the AnySearch API may return a new key in the response (auto_registered.api_key). The extension detects it, asks for confirmation in the TUI, and writes the key to the agent configuration file after you confirm. In headless mode it instead appends a notice to the tool result; the key can also be retrieved later from the AnySearch dashboard.

Pi commands

/anysearch-setup

Opens an interactive prompt and saves the key to the Pi agent configuration file. The new key is used by subsequent searches without restarting Pi, unless a non-empty ANYSEARCH_API_KEY remains set; the environment variable always takes precedence.

/anysearch-status

Shows the configuration path and reports only 已配置 (configured) or 匿名模式 (anonymous mode). It does not display the key or a key prefix.

postinstall behavior

The npm package includes a postinstall script:

• In an interactive terminal, it may ask for an API key when none is configured. Press Enter to keep using anonymous mode.
• In a non-interactive installation, it skips the prompt and prints setup guidance; installation still succeeds.
• If npm lifecycle scripts are disabled, for example with npm install --ignore-scripts, the script does not run.

You can always configure the extension later with /anysearch-setup or ANYSEARCH_API_KEY.

Tool reference

anysearch

Parameter	Type	Required	Description
queries	array (1–5 items)	Yes	One item is a single search; several items run in parallel after all domain inputs pass preflight.
queries[].query	string	Yes	One natural-language search intent.
queries[].domain	enum (17 values)	No	Omit for general search. Domain alone returns legal sub-domain choices without executing any search.
queries[].sub_domain	string	No	A routing key returned by an earlier domain-only call, such as finance.quote; requires domain.
queries[].sub_domain_params	object	No	String-valued parameters from the domain directory; every parameter marked required must be present.
queries[].max_results	integer	No	Results for this query, 1–10; default 3.
queries[].zone	cn | intl	No	Search region.
queries[].language	string	No	Preferred language, such as zh-CN or en.

anysearch has one explicit routing contract:

1. Omit domain for general web search.
2. Provide only domain to receive valid sub-domains and required parameters. No REST search runs for that item; in a mixed batch, domain-only items return a one-line capability summary while other queries execute normally.
3. Call anysearch again with domain, a returned sub_domain, and every required sub_domain_params key. The extension validates the selection against the cached directory before searching (bare suffixes like quote for finance.quote are normalized when unambiguous).

General search:

{
  "queries": [
    { "query": "latest Pi Coding Agent extension documentation", "max_results": 3 }
  ]
}

Discover finance capabilities through the same tool:

{
  "queries": [
    { "query": "AAPL price", "domain": "finance" }
  ]
}

Then run the selected vertical search:

{
  "queries": [
    {
      "query": "AAPL",
      "domain": "finance",
      "sub_domain": "finance.quote",
      "sub_domain_params": { "type": "stock", "symbol": "AAPL", "cn_code": "" },
      "max_results": 3
    }
  ]
}

anysearch_extract

Parameter	Type	Required	Description
url	string	Yes	Page URL (must start with http:// or https://). HTML pages only; content truncated at 50,000 characters.

Use when search snippets are too short to answer, when the user provides a URL, or to verify a claim against the original source.

Returned results

Search uses POST https://api.anysearch.com/v1/search (JSON summaries) and returns bounded Markdown containing the exact title, URL, and a whitespace-normalized snippet of at most 500 characters. The REST content field is discarded before the Pi tool result is built. Each query defaults to 3 results; explicit values from 1–10 are accepted. Batch output is fairly allocated and capped at 12,000 characters including notices. Domain-selection responses come from POST https://api.anysearch.com/mcp, execute no search, and remain intact so the returned parameter contract is usable. Use anysearch_extract for full-page content when snippets are insufficient.

Search results are deduplicated before being returned — high-duplication items are filtered out and never reach the agent's context (structured dedupe; batch dedupes globally across queries). An item is dropped when its normalized URL (scheme, www, tracking params, trailing slash, case-insensitive) matches an earlier item, OR its normalized title (case/punctuation-insensitive, leading arXiv id stripped, >= 12 chars) is >= 0.85 similar to an earlier title (char-bigram overlap; empirical split: real duplicates >= 0.93, distinct papers <= 0.72). Kept items are renumbered, and the ## Search Results count is rewritten. anysearch_extract and internal domain-directory text pass through untouched via POST https://api.anysearch.com/mcp.

Each tool returns Markdown plus structured details containing the response request_id when present and the auth mode (anonymous or configured). Search details additionally expose outcome: "search_results" | "needs_subdomain_selection"; selection details list the affected zero-based query indexes and legal sub-domains. Details never contain the API key. API and network failures are thrown so Pi can mark the tool result as an error.

In the TUI, both general and vertical calls appear under the same anysearch tool. Search responses render as a numbered list; domain selection and extraction render their Markdown directly.

Coexisting with pi-web-access

This package can be installed alongside pi-web-access. It registers only anysearch and anysearch_extract, so it does not replace tools such as web_search.

Use anysearch for routine direct lookup, current facts, and vertical-domain data. Use web_search only when the task requires independent multi-provider synthesis or corroboration, or when AnySearch fails. source_check and other pi-web-access features remain complementary.

Security

• Never commit API keys to Git, source files, examples, or issue reports.
• Prefer ANYSEARCH_API_KEY for CI and managed environments.
• The configuration file stores the key locally as plain JSON; protect access to your Pi agent directory.
• Pi extensions execute with the user's permissions. Review the source before installation.
• This extension performs network requests to https://api.anysearch.com/v1/search (search) and https://api.anysearch.com/mcp (extract and capability discovery) when one of the tools is called. It does not make a network request merely by loading the extension.

Development and verification

npm install --ignore-scripts
npm test
ANYSEARCH_E2E_API_KEY=as_sk_... npm run test:e2e  # optional real endpoints
npm pack --dry-run

npm test runs the deterministic mocked-fetch suite; real network checks are explicit so quota, registration, and connectivity cannot make the default test command flaky:

• test/anysearch.test.ts — deterministic mocked-fetch coverage for the two-tool registration surface, Pi prompt metadata, domain selection, fail-closed vertical validation, REST/MCP request assembly, bounded output, error paths, caching, and deduplication.
• test/e2e.test.ts — explicit real-endpoint checks for general search, unified domain selection followed by finance search, batch search, and extraction. It uses ANYSEARCH_E2E_API_KEY when provided and otherwise runs anonymously. Each passing scenario stores raw evidence under .evidence/; unreachable networks are skipped with an explicit reason.

Final Pi routing acceptance is performed in a fresh Pi session driven through Herdr so the real system prompt, active-tool list, and two-step domain interaction are exercised together.

For a temporary local Pi run:

pi -e .

Links

• GitHub repository
• npm package
• Pi package page
• AnySearch documentation
• Pi Coding Agent

License

MIT, as declared in package.json.