[bot] Instrument Perplexity Python SDK (perplexityai) (344,724 weekly downloads)

Start by reading the existing OpenAI and Mistral integration patchers and their tests, then inspect the perplexityai SDK’s sync and async client methods. The issue calls out py/src/braintrust/integrations/, integrations/__init__.py, integrations/versioning.py, py/noxfile.py, and py/pyproject.toml as integration points. Done means tracing chat completions, search, embeddings, agent and decisions calls for both clients, including streaming and Perplexity-specific response fields, with tests and package matrix coverage.

Summary

perplexityai is Perplexity's official, Stainless-generated Python client (GitHub: perplexityai/perplexity-py), currently at v0.46.1 (released October 23, 2026). It exposes Perplexity/AsyncPerplexity client classes with their own distinct execution surfaces: chat completions (sonar models), Search, Embeddings (including "contextualized" embeddings), an Agent API, and Decisions. This repository has zero instrumentation for any perplexityai SDK execution surface — no integration directory, no wrapper, no patcher, no auto_instrument() support, and no entry in py/pyproject.toml's [tool.braintrust.matrix].

Braintrust's own Perplexity docs only describe accessing Perplexity through the gateway/proxy approach: pointing a standard openai.OpenAI client at https://gateway.braintrust.dev/v1. This covers users of the OpenAI-compatible REST endpoint, but the native perplexityai client is not an openai.OpenAI subclass and cannot be wrapped with wrap_openai(). Users who follow Perplexity's own official documentation and pip install perplexityai get zero Braintrust tracing. This mirrors the pattern already recognized in this repo for other OpenAI-compatible-but-distinct-client providers (Mistral, OpenRouter, Groq, etc.), each of which received dedicated native integrations rather than relying on gateway-only coverage.

What needs to be instrumented

The perplexityai package exposes these execution surfaces via Perplexity/AsyncPerplexity, none of which are instrumented:

Chat completions (highest priority)

SDK Method	Description	Streaming	Return type
client.chat.completions.create(model="sonar", messages=[...])	Chat completions over Perplexity's Sonar model family, with built-in web search grounding	stream=True returns an SSE iterator of chunks	ChatCompletion
await async_client.chat.completions.create(...)	Async chat completions	Same as sync	ChatCompletion

Response shape is OpenAI-compatible (choices, usage with prompt_tokens/completion_tokens, model, id), so span metrics extraction can follow the existing OpenAI pattern, but Perplexity-specific fields (citations/search results returned alongside the completion) are not part of the OpenAI schema and would be lost without native instrumentation.

Search

SDK Method	Description
client.search.create(query=...)	Ranked web search execution, independent of chat completions

Embeddings

SDK Method	Description
client.embeddings.create(...)	Standard and "contextualized" text embeddings generation

This is a genuine embeddings execution surface with no equivalent in the OpenAI-compatible gateway path documented by Braintrust today.

Agent API / Decisions (agentic execution surfaces)

SDK Method	Description
client.agent.*	Third-party-model agent execution with web search tools and configurable effort levels, including batches/files/skills/models sub-resources
client.decisions.*	Typed answers with probabilities

Implementation notes

Stainless-generated SDK: Like OpenAI, Groq, Mistral, and Cerebras, perplexityai is Stainless-generated with sync (httpx) and async clients sharing the same method surface — the existing OpenAI/Mistral patcher pattern is a reasonable structural reference.

Perplexity-specific response fields: Chat completion responses include citations/search_results tied to the built-in web search grounding — these should be captured in span metadata since they are not representable in a generic OpenAI-shaped span.

Both sync and async clients need instrumentation (Perplexity and AsyncPerplexity).

No coverage in any instrumentation layer

• No integration directory (py/src/braintrust/integrations/perplexity/)
• No wrapper function (e.g. wrap_perplexity())
• No patcher in any existing integration
• No nox test session (test_perplexity)
• No version entry in py/src/braintrust/integrations/versioning.py
• No mention in py/src/braintrust/integrations/__init__.py
• No entry in [tool.braintrust.matrix] in py/pyproject.toml

A repo-wide case-insensitive grep for perplexity across py/src/braintrust/ and py/ returns zero matches.

Weekly downloads

Weekly downloads: 344,724 (as of 2026-10-26; https://pypistats.org/packages/perplexityai)

Braintrust docs status

not_found for native Python SDK support. Checked:

• https://www.braintrust.dev/docs/integrations/ai-providers/perplexity — describes only the gateway/proxy approach (openai.OpenAI(base_url="https://gateway.braintrust.dev/v1")); every Python code example uses the openai package, not perplexityai. No wrap_perplexity() or native SDK reference.
• https://www.braintrust.dev/docs/instrument/trace-llm-calls — Perplexity/perplexityai is absent from the Python "minimum SDK versions for tracing" table (which lists openai, anthropic, google-genai, openrouter, mistralai, openai-agents, claude-agent-sdk, litellm, google-adk, agentscope, pydantic-ai, agno, dspy, langchain-core, llama-index-core, cohere, autogen-agentchat, crewai, strands-agents, temporalio, typesafe-sdk, instructor, huggingface-hub, transformers, boto3, livekit-agents, pipecat-ai, google-cloud-discoveryengine).

Upstream sources

• perplexityai on PyPI: https://pypi.org/project/perplexityai/ (v0.46.1, October 23, 2026)
• Perplexity Python SDK on GitHub: https://github.com/perplexityai/perplexity-py
• Perplexity SDK quickstart: https://docs.perplexity.ai/docs/sdk/overview
• Perplexity API changelog: https://docs.perplexity.ai/docs/resources/changelog
• Perplexity Agent API docs: https://docs.perplexity.ai/docs/agent-api/quickstart

Local repo files inspected

• py/src/braintrust/integrations/ — no perplexity/ directory exists on main
• py/src/braintrust/wrappers/ — no Perplexity wrapper
• py/noxfile.py — no test_perplexity session
• py/src/braintrust/integrations/__init__.py — Perplexity not listed in integration registry
• py/src/braintrust/integrations/versioning.py — no Perplexity version matrix
• py/pyproject.toml [tool.braintrust.matrix] — no Perplexity entries
• Full repo grep for perplexity (case-insensitive) across py/src/braintrust/ and py/ — zero matches