Summary

Adds Perplexity as the default web search backend in Hermes Agent, and registers a Perplexity LLM provider plugin so users can route chat completion through the Perplexity Agent API (OpenAI-compatible).

Two integration paths, both opt-in via a single API key:

Why default to Perplexity for web search?

• Drop-in normalized results — same {title, url, snippet} shape
• Single key, single endpoint — PERPLEXITY_API_KEY (or legacy PPLX_API_KEY) and one POST /search call.
• Backward compatible — if web.backend is set in ~/.hermes/config.yaml, that wins. If any of the existing keys (FIRECRAWL_*, PARALLEL_*, TAVILY_*, EXA_*, etc.) is set without web.backend, those still resolve to their existing backends. The only behavior change for an existing user is "no key configured" → now defaults to Perplexity instead of Firecrawl (which would also have failed at client init).

Changes

Web search backend

• New tools/web_providers/perplexity.py — PerplexitySearchProvider exposing .search(query, limit), plus perplexity_search() / _perplexity_search_request() / _normalize_perplexity_results() / _get_perplexity_api_key(). Bearer auth, X-Pplx-Integration: hermes-agent/1.0 attribution header, limit clamped to [1, 20].
• Modified tools/web_tools.py:
  • _get_backend() validates "perplexity" in the configured set, places perplexity first in the auto-detect candidate list, and returns "perplexity" as the shipped default when no keys are present.
  • _is_backend_available() resolves "perplexity" via PERPLEXITY_API_KEY or PPLX_API_KEY.
  • _web_requires_env() advertises both env vars.
  • web_search_tool dispatches to the perplexity branch first.
  • check_web_api_key() and the __main__ debug block both learn the new backend.
• Modified hermes_cli/tools_config.py — Perplexity is now the first option under web providers in the hermes tools wizard with the ★ recommended badge. Firecrawl is demoted to paid.

LLM provider plugin

• New plugins/model-providers/perplexity/__init__.py and plugin.yaml — ProviderProfile(name="perplexity", aliases=("pplx",), env_vars=("PERPLEXITY_API_KEY","PPLX_API_KEY"), base_url="https://api.perplexity.ai", fallback_models=("openai/gpt-5.4", "anthropic/claude-sonnet-4-6", "google/gemini-3-1-pro")). All fallback models are reachable through the Perplexity Agent API.

Docs

• website/docs/user-guide/features/web-search.md — Backends table gains a Perplexity (default) row, full section, updated config snippet, and refreshed auto-detect priority table.
• website/docs/integrations/providers.md — Inference Providers table gains a Perplexity row (Agent API, OpenAI-compatible).
• website/docs/integrations/index.md — default backend updated to Perplexity.
• website/docs/reference/environment-variables.md — PERPLEXITY_API_KEY and PPLX_API_KEY rows added under Tool APIs.
• website/docs/user-guide/features/mcp.md — new ### Perplexity MCP server for live web research example using server-perplexity-ask.

Tests

• New tests/tools/test_web_tools_perplexity.py — 21 tests across 5 classes covering API-key resolution (PERPLEXITY_API_KEY wins over PPLX_API_KEY, whitespace stripping, raises when neither is set), request shape (Bearer auth + X-Pplx-Integration header + payload), result normalization (snippet/content fallback, missing fields), limit clamping (0 → 1, 100 → 20), backend selection (configured / auto-detected / PPLX_API_KEY alias / no-keys default), _is_backend_available(), and end-to-end web_search_tool dispatch through the perplexity branch.
• Modified tests/tools/test_web_tools_config.py — _ENV_KEYS lists include PERPLEXITY_API_KEY / PPLX_API_KEY (so the env-clearing setup works as intended), test_fallback_no_keys_defaults_to_firecrawl becomes test_fallback_no_keys_defaults_to_perplexity, plus two new tests (test_fallback_perplexity_only_key, test_fallback_perplexity_takes_priority_over_firecrawl).
• Modified tests/providers/test_plugin_discovery.py — bump expected profile count (33 → 34) and spot-check "perplexity".

Test plan

uv run --extra dev pytest \
  tests/tools/test_web_tools_perplexity.py \
  tests/tools/test_web_tools_config.py \
  tests/tools/test_web_tools_tavily.py \
  tests/tools/test_web_providers.py \
  tests/tools/test_web_providers_brave_free.py \
  tests/tools/test_web_providers_ddgs.py \
  tests/tools/test_web_providers_searxng.py \
  tests/tools/test_tool_backend_helpers.py \
  tests/providers/test_plugin_discovery.py -q

→ 215 passed in 6.32s locally.

Manual verification

export PERPLEXITY_API_KEY=pplx-...
python -c "from tools.web_tools import _get_backend, _is_backend_available; \
print(_get_backend(), _is_backend_available('perplexity'))"
# perplexity True

python -c "import asyncio, json; from tools.web_tools import web_search_tool; \
print(json.dumps(asyncio.run(web_search_tool('what happened in AI this week', limit=3)), indent=2)[:600])"

Notes / non-goals

• No Sonar models referenced. Per Perplexity's current direction, the Perplexity provider profile lists only Agent API–routed models. This PR doesn't touch any other backend's logic.
• Backward compatible. Existing users with FIRECRAWL_API_KEY / PARALLEL_API_KEY / TAVILY_API_KEY / EXA_API_KEY set will continue to resolve to their existing backend with no config change.
• Attribution header. Outbound POST /search requests carry X-Pplx-Integration: hermes-agent/1.0 so Perplexity can attribute traffic for monitoring & rate-limit hygiene.

Happy to iterate on any of this — naming, default-backend choice, fallback model list, doc placement, etc.