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

Aberta
  • Algo errado?
#999 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
35/100
Tipo de issue
Funcionalidade
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
python
Domínio
backend-api-design, observability

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

new-integration python

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

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
Linguagem predominante
Python
Estrelas
22
Forks
30
Merge médio
9h
PRs com merge (30d)
128

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de braintrustdata/braintrust-sdk-python

Todas as issues de braintrustdata/braintrust-sdk-python

Issues semelhantes

Mais issues de Python

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.