feat: add PerplexitySearch tool

[jliounis]

Summary

Adds a PerplexitySearch tool to @kaibanjs/tools that wraps POST https://api.perplexity.ai/search and returns structured { title, url, snippet, date? } results, modeled after the existing Tavily / Exa / Serper search tools.

What's new

• New tool: packages/tools/src/perplexity-search/ (TS + JS implementations matching the existing tool pattern)
• Constructor accepts apiKey directly, or falls back to the PERPLEXITY_API_KEY / PPLX_API_KEY environment variable
• Configurable options: maxResults, searchDomainFilter (allow- or deny-list — leading - for deny), searchRecencyFilter (hour | day | week | month | year)
• Registered in src/index.ts exports, package.json subpath exports, and rollup.config.mjs build targets
• README + Storybook story added; package-level README table updated

Tests

10 Jest tests in src/perplexity-search/tool.test.js covering:

• default request shape and result normalization
• forwarding of maxResults, searchDomainFilter, searchRecencyFilter
• API-key resolution from PERPLEXITY_API_KEY and PPLX_API_KEY env vars
• error when no API key is provided
• invalid response shape, 4xx, 5xx, and network-error paths
• export equivalence between dist/perplexity-search/index.cjs.js and dist/index.cjs.js

Run:

cd packages/tools
npm install
npm run build
npx jest src/perplexity-search/tool.test.js

All 10 tests pass locally.

Reference

• API reference: https://docs.perplexity.ai/api-reference/search-post
• Domain filter docs: https://docs.perplexity.ai/docs/search/filters/domain-filter
• Date / recency filter docs: https://docs.perplexity.ai/docs/search/filters/date-time-filters

[jliounis]

Hi @darielnoel — once this PR lands, would you consider making PerplexitySearch the recommended default web search tool for KaibanJS?

I pushed a small follow-up commit on this branch (docs-only, ~20 lines) that:

• adds a "recommended for general web search" callout above the tools table in packages/tools/README.md and moves PerplexitySearch to the top row,
• adds a one-line callout in the root README.md quickstart pointing new projects at PerplexitySearch (the existing Tavily example is left intact).

Rationale for picking it as the default:

• Single API + index — no separate retrieval/embedding step; results come from the same Sonar index perplexity.ai itself uses.
• Snippets are pre-filtered for RAG (high info density per token), so agents spend fewer tokens on boilerplate.
• One env var to set up: PERPLEXITY_API_KEY (with PPLX_API_KEY as a fallback) — no enrich/re-rank gymnastics.
• Drop-in compatibility with the shape KaibanJS users already know from Tavily/Exa/Serper (query, maxResults, recency + domain filters), so no agent-loop changes are needed.
• The Perplexity API team actively maintains this integration and is committed to long-term parity with whichever default you'd ship today.

Happy to revert the docs nudge or split it into a follow-up PR if you'd rather keep this one focused on the tool itself — whichever you prefer. Either way, thanks for reviewing!

[jliounis]

Friendly bump — happy to address any feedback. Recent commit added a docs callout proposing PerplexitySearch as the recommended default web search tool; let me know if you'd prefer to keep it as one of several or position it differently.

[jliounis]

Added the Perplexity attribution header as X-Pplx-Integration: kaibanjs/<package-version> using the tools package version, and updated the mocked request test to assert the slug/version header.

Validated in packages/tools/:

• npm run build
• npm test

_{🤖 Comment from PSI}