Skip to content

Perplexity Integration (Web Search Provider)

Status: Active
Last Verified: February 2026

Perplexity is integrated as a web search provider used by the backend’s routing/tooling layer when a user request needs current information (restaurants, news, prices, “what’s open”, etc.).

This is not the primary conversation model — the main assistant responses are generated by GPT‑5 models via app/utils/llm_client.py.

Where it lives (backend)

  • Perplexity client: app/utils/perplexity_client.py
  • Query understanding (decides whether to search): app/orchestrator/query_analyzer.py
  • Provider routing & fallback chain: app/orchestrator/smart_router.py
  • Provider adapters: app/orchestrator/providers/

Configuration

Set in Railway Variables (or local .env):

PERPLEXITY_API_KEY=pplx_...          # required to enable Perplexity provider
PERPLEXITY_MODEL=sonar-pro           # optional (defaults to sonar-pro)
USE_PERPLEXITY_HYBRID=true           # feature flag (see app/config.py)

No real keys should appear in documentation.

Routing behavior (high level)

SmartRouter uses QueryAnalyzer to classify a user query and then routes to the cheapest viable source first:

  1. Free APIs (e.g., weather)
  2. OAuth APIs (calendar/email) if connected
  3. Parallel Search (if configured) for deep/multi-hop research
  4. Perplexity (if configured) for fast web search
  5. GPT‑5 fallback (no web call)

Perplexity is used only when the analyzer recommends it and the provider is configured.

Observability

Perplexity calls are made over httpx, so tracing is manual: - app/utils/perplexity_client.py emits Keywords.AI traces via app/utils/tracing.py when tracing is enabled.