feat(perplexity): deprecate chat completions helpers

[andrewmadson-pplx]

Why

The Python integrations perplexity.LLM and openai.LLM.with_perplexity() still use Sonar Chat Completions. Users need an actionable migration path to the existing perplexity.responses.LLM Agent API client before Sonar is retired.

The OpenAI helper also defaults to llama-3.1-sonar-small-128k-chat, which is no longer served, so its zero-configuration path fails before users can migrate.

What changed

• Emit actionable DeprecationWarnings from both Python Chat Completions entry points.
• Add pdoc deprecation directives so both migration paths appear in generated API reference documentation.
• Restore openai.LLM.with_perplexity() to a working sonar-pro default and replace its retired model type literals with current Sonar model IDs.
• Make the Agent API client the primary Perplexity README example and document migration from both legacy entry points.
• Update the package module description to distinguish the recommended Responses client from the legacy client.
• Correct the stale Responses default-model assertion from sonar-pro to perplexity/sonar.
• Exercise the OpenAI helper without a model override so the retired-default regression cannot be masked again, and explicitly handle the warning in existing legacy-client tests.

Behavior and scope

This is a soft deprecation: existing explicit Chat Completions configurations continue to construct, while callers receive a standard Python deprecation warning with the replacement API. Zero-configuration with_perplexity() callers temporarily regain a supported Sonar default and receive the same migration warning.

The generated pdoc output renders both directives as deprecation callouts. The native Responses client remains unchanged: it defaults to perplexity/sonar, selects HTTP at https://api.perplexity.ai/v1/, reads PERPLEXITY_API_KEY, and sets the LiveKit attribution header.

Coordinated Node change: livekit/agents-js#2392.

Coordinated Perplexity guide: ppl-ai/api-docs#807.

Tracking: Sonar to Agent migration, API-3590, and API-3389.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}