Prism Perplexity for Python

Perplexity's Search API, embeddings and Agent API: the parts of Perplexity that Prism core does not carry. The Python port of particle-academy/prism-perplexity.

Zero runtime dependencies. Python 3.10+.

pip install prism-ai-perplexity

import os

from prism_perplexity import AgentClient, search, urllib_transport

http = urllib_transport(os.environ["PERPLEXITY_API_KEY"])

for result in search(http, "what changed in the MCP 2026-07-28 revision"):
    print(result["title"], result["url"])

agent = AgentClient(http)
run = agent.create("Summarise this week's changes to the OpenAI Responses API.")
done = agent.wait(run.id)

print(done.text())

urllib_transport(api_key, base_url, timeout) uses the standard library. Any callable that takes an HttpRequest (method, path, body) and returns an HttpResponse (status, json) works in its place, so tests need no network.

Search

search(http, query, options) returns web results with no model call: the sources, without paying for an answer. query can be a string or a list of strings. Results are plain dicts, because Perplexity documents the payload as open-ended.

Embeddings

embeddings(http, model, inputs, contextualized=False) calls /embeddings, which embeds each input on its own. With contextualized=True it calls /contextualized-embeddings, which treats the inputs as chunks of one document and embeds each with the others in view.

Agent API

AgentClient starts a long-running run, polls it and cancels it.

• create(input, options) starts a run in the background by default, so no request is held open for minutes.
• retrieve(run_id) gets a snapshot; cancel(run_id) acknowledges a request. cancelling is neither terminal nor successful.
• wait(run_id, max_attempts=300, interval_seconds=1.0) polls until the run finishes, and raises agent_wait_timed_out if it does not. Five minutes, because the reference measured a routine deep-research call at 57-59 seconds — a one-minute ceiling reports a failure that did not happen.
• AgentResponse.text() joins the text parts of the output. is_successful() is true only for a completed run.
• incomplete_reason() returns the string incomplete_details.reason, including an empty string, or None when absent or malformed.

A cancellation acknowledgement's response_id (or legacy id, only when response_id is absent) must match the requested ID exactly. A malformed or mismatched acknowledgement raises invalid_response; cancellation state is uncertain, so call retrieve(run_id) to check it. The client does not retry cancellation automatically. create() and retrieve() still use their own id field, and raw retains the provider body.

Errors

Every failure is a PerplexityError with a stable code: unreadable_response, provider_error, invalid_response, agent_wait_timed_out, invalid_argument. Match on the code, not the message.

Parity

prism-parity's perplexity-agent-response corpus compares how Agent API responses are read. This port and the TypeScript port agree on all forty-five cases; the original seventeen rows are unchanged. The PHP reference differs on most of them:

• an empty usage is a list in PHP and a dict here;
• a JSON array body is invalid_response in PHP and unreadable_response here;
• a numeric-string created_at becomes a number in PHP and None here;
• a refusal carries no machine-readable code in PHP.

Status handling, polling and citations agree in all three.

License

MIT. See LICENSE.