Module livekit.plugins.perplexity
Perplexity plugin for LiveKit Agents
Wraps Perplexity's OpenAI-compatible chat completions endpoint at
https://api.perplexity.ai so it can be used as a drop-in LLM for LiveKit
voice agents.
Sub-modules
livekit.plugins.perplexity.responses
Classes
class DecisionModel (*,
model: PerplexityDecisionModels | str = 'pplx-decider-flash-v1.3',
api_key: str | None = None,
base_url: str = 'https://api.perplexity.ai/v1',
mode: "Literal['web_grounding'] | None" = None,
max_staleness: int | None = None,
http_session: aiohttp.ClientSession | None = None)-
Expand source code
class DecisionModel(llm.DecisionModel): """Perplexity's Decisions API (``POST /v1/decisions``). One request answers a batch of probability, choice, and score questions about the same input. Example:: model = perplexity.DecisionModel() response = await model.evaluate( input=chat_ctx, decisions={"handoff": llm.Probability("The caller requests a human.")}, ) Args: model: Perplexity decision model. ``pplx-decider-flash-v1.3`` is the low-latency default for in-turn decisions. ``pplx-decider-v1.3`` is the larger, more accurate model for background checks. api_key: Required for the default base URL, where it defaults to PERPLEXITY_API_KEY. Other base URLs only receive an explicit ``api_key``. base_url: Defaults to ``https://api.perplexity.ai/v1``. For Decider for Mac, use ``http://127.0.0.1:8080/v1``; it needs no API key. mode: ``"web_grounding"`` runs one web search per question and adds the results to the input before answering. Each search is billed and adds network latency, so prefer it for background decisions, not end-of-turn gating. max_staleness: Maximum age in seconds of a fetched page when the input is a single URL and ``mode="web_grounding"``. http_session: Optional caller-owned session. Otherwise uses the job's HTTP session. Outside a job, use ``async with utils.http_context.open()``. """ def __init__( self, *, model: PerplexityDecisionModels | str = "pplx-decider-flash-v1.3", api_key: str | None = None, base_url: str = _BASE_URL, mode: Literal["web_grounding"] | None = None, max_staleness: int | None = None, http_session: aiohttp.ClientSession | None = None, ) -> None: super().__init__( capabilities=DecisionCapabilities(decision_kinds=["probability", "choice", "score"]) ) hosted = urlparse(base_url).hostname == _PERPLEXITY_HOST # The environment key is for Perplexity's API; never send it to another server. key = api_key or (os.environ.get("PERPLEXITY_API_KEY") if hosted else None) if not key and hosted: raise ValueError( "PERPLEXITY_API_KEY is required, either as argument or set " "PERPLEXITY_API_KEY environmental variable" ) if max_staleness is not None and mode is None: raise ValueError("max_staleness requires mode='web_grounding'") if max_staleness is not None and max_staleness < 0: raise ValueError("max_staleness must be non-negative") self._model = model self._url = f"{base_url.rstrip('/')}/decisions" self._headers = { **_ATTRIBUTION_HEADER, **({"Authorization": f"Bearer {key}"} if key else {}), } grounding = {"mode": mode, "max_staleness": max_staleness} self._grounding: dict[str, Any] = {k: v for k, v in grounding.items() if v is not None} self._session = http_session @property def model(self) -> str: return self._model @property def provider(self) -> str: return "Perplexity" async def _evaluate_impl( self, *, input: str, decisions: Mapping[str, Decision], conn_options: APIConnectOptions, ) -> DecisionResponse: body = { "model": self._model, "state": input, "questions": {name: systemone.encode_question(d) for name, d in decisions.items()}, **self._grounding, } session = self._session or utils.http_context.http_session() try: async with session.post( self._url, headers=self._headers, json=body, timeout=aiohttp.ClientTimeout(total=conn_options.timeout), ) as response: request_id = response.headers.get("x-request-id", "") if response.status != 200: raise APIStatusError( "Perplexity decision request failed", status_code=response.status, request_id=request_id or None, body=await response.text(), retryable=response.status in (408, 429) or response.status >= 500, ) parsed = systemone.Response.model_validate(await response.json()) results, errors = systemone.decode_answers( parsed.answers, invalid="invalid Perplexity decision answer" ) return DecisionResponse( results=results, errors=errors, model=parsed.model, provider=self.provider, request_id=parsed.id or request_id, input_tokens=parsed.usage.input_tokens, output_tokens=parsed.usage.output_tokens, ) except asyncio.TimeoutError: raise APITimeoutError("Perplexity decision request timed out") from None except aiohttp.ContentTypeError: raise APIError("invalid Perplexity decision response", retryable=False) from None except (aiohttp.ClientError, OSError): raise APIConnectionError("Perplexity decision request failed") from None except ValueError: # pydantic.ValidationError and json.JSONDecodeError are both ValueErrors raise APIError("invalid Perplexity decision response", retryable=False) from NonePerplexity's Decisions API (
POST /v1/decisions).One request answers a batch of probability, choice, and score questions about the same input.
Example::
model = perplexity.DecisionModel() response = await model.evaluate( input=chat_ctx, decisions={"handoff": llm.Probability("The caller requests a human.")}, )Args
model- Perplexity decision model.
pplx-decider-flash-v1.3is the low-latency default for in-turn decisions.pplx-decider-v1.3is the larger, more accurate model for background checks. api_key- Required for the default base URL, where it defaults to
PERPLEXITY_API_KEY. Other base URLs only receive an explicit
api_key. base_url- Defaults to
https://api.perplexity.ai/v1. For Decider for Mac, usehttp://127.0.0.1:8080/v1; it needs no API key. mode"web_grounding"runs one web search per question and adds the results to the input before answering. Each search is billed and adds network latency, so prefer it for background decisions, not end-of-turn gating.max_staleness- Maximum age in seconds of a fetched page when the input is a
single URL and
mode="web_grounding". http_session- Optional caller-owned session. Otherwise uses the job's HTTP
session. Outside a job, use
async with utils.http_context.open().
Ancestors
- livekit.agents.llm.decisions.DecisionModel
- abc.ABC
- EventEmitter
- typing.Generic
Instance variables
prop model : str-
Expand source code
@property def model(self) -> str: return self._model prop provider : str-
Expand source code
@property def provider(self) -> str: return "Perplexity"
Inherited members
class LLM (*,
model: str | PerplexityChatModels = 'sonar-pro',
api_key: NotGivenOr[str] = NOT_GIVEN,
base_url: NotGivenOr[str] = 'https://api.perplexity.ai',
client: openai.AsyncClient | None = None,
user: NotGivenOr[str] = NOT_GIVEN,
temperature: NotGivenOr[float] = NOT_GIVEN,
parallel_tool_calls: NotGivenOr[bool] = NOT_GIVEN,
tool_choice: NotGivenOr[ToolChoice] = NOT_GIVEN,
top_p: NotGivenOr[float] = NOT_GIVEN,
timeout: httpx.Timeout | None = None)-
Expand source code
class LLM(OpenAILLM): def __init__( self, *, model: str | PerplexityChatModels = "sonar-pro", api_key: NotGivenOr[str] = NOT_GIVEN, base_url: NotGivenOr[str] = PERPLEXITY_BASE_URL, client: openai.AsyncClient | None = None, user: NotGivenOr[str] = NOT_GIVEN, temperature: NotGivenOr[float] = NOT_GIVEN, parallel_tool_calls: NotGivenOr[bool] = NOT_GIVEN, tool_choice: NotGivenOr[ToolChoice] = NOT_GIVEN, top_p: NotGivenOr[float] = NOT_GIVEN, timeout: httpx.Timeout | None = None, ): """ Create a new instance of Perplexity LLM. ``api_key`` must be set to your Perplexity API key, either using the argument or by setting the ``PERPLEXITY_API_KEY`` environmental variable. """ api_key = api_key if is_given(api_key) else os.environ.get("PERPLEXITY_API_KEY", "") if not api_key: raise ValueError( "PERPLEXITY_API_KEY is required, either as argument or set " "PERPLEXITY_API_KEY environmental variable" ) super().__init__( model=model, api_key=api_key, base_url=base_url, client=client, user=user, temperature=temperature, parallel_tool_calls=parallel_tool_calls, tool_choice=tool_choice, top_p=top_p, timeout=timeout, extra_headers=_ATTRIBUTION_HEADER, _strict_tool_schema=False, ) @property def model(self) -> str: return self._opts.model @property def provider(self) -> str: return "Perplexity"Helper class that provides a standard way to create an ABC using inheritance.
Create a new instance of Perplexity LLM.
api_keymust be set to your Perplexity API key, either using the argument or by setting thePERPLEXITY_API_KEYenvironmental variable.Ancestors
- livekit.plugins.openai.llm.LLM
- livekit.agents.llm.llm.LLM
- abc.ABC
- EventEmitter
- typing.Generic
Instance variables
prop model : str-
Expand source code
@property def model(self) -> str: return self._opts.modelGet the model name/identifier for this LLM instance.
Returns
The model name if available, "unknown" otherwise.
Note
Plugins should override this property to provide their model information.
prop provider : str-
Expand source code
@property def provider(self) -> str: return "Perplexity"Get the provider name/identifier for this LLM instance.
Returns
The provider name if available, "unknown" otherwise.
Note
Plugins should override this property to provide their provider information.
Inherited members