fix(openai): capture Perplexity Responses extensions - #437

What changed

Keep Perplexity on the existing OpenAI Responses integration; do not add or retire a provider package.

• Observe the Responses request body the SDK actually sends: shallow-merge extra_body over the normal body, honor Omit, and exclude headers/query options. This captures Perplexity's effort and preserves overrides without mutating the SDK options.
• Map optional search_results items to retrieval.documents on the existing LLM span, without synthetic retrieval spans. Capture reported numeric usage.cost values and supplied currency; omit missing, malformed, negative and non-finite costs.
• Apply output masking before extracting search documents, including with published core 1.1.0. Hide invocation parameters with hide_inputs on that older core as well. Keep token/cost attributes available when content is hidden.
• Handle optional Responses token-detail objects independently.
• Pin the Perplexity recipe to already-published traceAI-openai==0.1.11, require provider perplexity at the documented host, and replace the README's QA diary with a working customer guide. The README explicitly describes the published pin, not the unreleased extensions.
• Add floor/current SDK and source/published-core extension checks to CI.

Why

Perplexity officially supports /v1/responses as the OpenAI-compatible alias for /v1/agent, and documents extra_body effort, search_results, and usage.cost:
https://docs.perplexity.ai/docs/agent-api/openai-compatibility

The former recipe pin 0.1.10 labels the provider as OpenAI. Version 0.1.11 is already on PyPI; provider attribution alone needs no new release:
https://pypi.org/project/traceAI-openai/0.1.11/

The independent extension regression was reproduced on base d6a9966dd4d5d5fb344f7f5ab11b7483c2c2a6bc: the initial 18-case regression suite had 8 failures and 10 passes on both openai 1.69.0 and 3.42.0. The transmitted body contained effort, while invocation attributes did not; structured costs/retrieval were absent.

Verification

All local tests ran under a macOS sandbox denying outbound network except loopback, using synthetic credentials and payloads. No model/vendor API calls.

• Python 3.12, openai 1.69.0, source core: 277 passed (full OpenAI package tests plus Perplexity recipe).
• Python 3.12, openai 3.42.0, source core: 277 passed.
• New extension contracts on published core 1.1.0: 27 passed at each SDK version.
• Exact recipe pins (openai 3.24.0, traceAI-openai 0.1.11, core 1.1.0): 188 passed.
• Real OTLP exporter serialization is decoded from protobuf before the HTTP transport is intercepted. Existing recipe tests also export to a loopback OTLP receiver; the README Python example is executed through that receiver.
• Sync/async and non-stream/stream paths, request overrides, malformed extensions, error paths, no duplicate spans, output/input/invocation privacy, optional token details, and published provider attribution are covered.
• New Python files pass Ruff; touched legacy files add no lint findings. git diff --check passes.

Scope and release ordering

Existing OpenAIInstrumentor entry points and returned SDK objects remain unchanged. The new extra_body capture contract is limited to Responses; Chat Completions parameter capture is unchanged. Targeted Doubleword, OrcaRouter and PrismML compatibility tests passed on both SDK versions (5 cases per version). This does not add native perplexity SDK/Search/Embeddings coverage, background polling, or new provider packages. No version or changelog bump; release-please owns the shared package release.

PR #364 adds a recipe traffic header and does not solve these issues; this PR leaves its src/app.py work alone. Other provider-attribution/audio PRs remain separate.

No docs-site PR is opened against an unreleased capability. A corrected extension guide is held for after the shared package release; the repository README runs against published packages now.

E2E coverage

not applicable (no e2e/ harness) · flows hit: n/a · marker: n/a · verdict: not applicable

🤖 Generated with Claude Code