helallao/perplexity-ai

Perplexity‑AI (unofficial Python wrapper)

What it is – A Python library that talks to the public Perplexity.ai web UI (no official API key needed). It lets you run the same search/reasoning queries the website offers, either synchronously or asynchronously, and also includes a small driver that can automate a Chrome browser to create fresh Gmail accounts via Emailnator so you can keep getting the free‑tier “5 pro queries” limit.

Key capabilities

• Search & reasoning – call client.search() with a query and choose a mode (auto, pro, reasoning, deep research). The response contains an answer field (plain‑text).
• Streaming – set stream=True to receive partial answer chunks as they appear.
• File upload – attach a dict of {filename: data} to let Perplexity analyse documents.
• Sync & async APIs – perplexity.Client (blocking) and perplexity_async.Client (awaitable).
• MCP server – a Model Context Protocol server (perplexity-mcp) that exposes the wrapper as a tool for Claude Code or any MCP‑compatible client, with optional HTTP transport for remote sharing.
• Account generation – client.create_account(emailnator_cookies) uses the Emailnator temporary‑mail service to register a new Gmail, giving you another set of free pro queries.
• Rate‑limit handling, retries, typed interfaces, structured logging, and custom exception hierarchy for robust integration.

Installation (requires Python 3.10+ and the uv package manager, but pip works as a drop‑in):

# core library
uv sync               # or: pip install -e .

# optional MCP server
uv sync --extra mcp   # or: pip install .[mcp]

# optional web‑driver for account creation
uv sync --extra driver
uv run patchright install chromium   # installs a headless Chromium for the driver

Quick usage example (sync)

import perplexity

client = perplexity.Client()                     # anonymous, free‑tier only
resp = client.search("What is artificial intelligence?")
print(resp["answer"])                           # → plain‑text answer

With your own Perplexity account (provide cookies obtained from the browser):

cookies = {
    "next-auth.session-token": "…",
    "next-auth.csrf-token": "…",
}
client = perplexity.Client(cookies)
resp = client.search(
    "Explain quantum computing",
    mode="reasoning",
    model="gpt-5.2-thinking",
    sources=["web", "scholar"],
    stream=True,
)
for chunk in resp:
    if "answer" in chunk:
        print(chunk["answer"], end="", flush=True)

Async variant – replace perplexity with perplexity_async and await the calls.

MCP server – run perplexity-mcp (default stdio transport) or MCP_TRANSPORT=http perplexity-mcp for an HTTP endpoint. Claude Code can then add it as a tool (claude mcp add perplexity -- perplexity-mcp). The server forwards queries to the wrapper, using either anonymous mode or the cookies supplied via the PERPLEXITY_COOKIES environment variable.

Limitations (as documented)

• No multi‑message messages array – only a single query string per call.
• No advanced search filters (recency, domain, context size, reasoning effort, etc.).
• Returns plain‑text answers; no structured citations, images, or rich result objects.
• Requires fresh Emailnator cookies for account creation because they expire quickly.

Where to find more – examples in examples/, full API reference in the README, changelog and roadmap in docs/, and the test suite under tests/.

Legal note – This is an unofficial wrapper. Use it responsibly and respect Perplexity.ai’s terms of service.