How helallao/perplexity-ai works
1. Purpose and principal workflow. This is an unofficial Python client for Perplexity’s web-facing query and Labs interfaces, with optional disposable-email account enrollment, browser automation, and MCP tool serving. The principal workflow is initiated by a Python application developer calling Client.search: the client validates parameters, optionally uploads supplied files, submits a web-interface query, then returns a final parsed response or a stream of parsed SSE chunks.
2. Components
Query and account API
• Synchronous Query Client — perplexity/client.py: Owns the synchronous HTTP session, cookies, timestamp, account/query counters, search request lifecycle, and final-or-streaming response handling.
• Synchronous File Ingestion — perplexity/client.py: Obtains upload information, constructs multipart MIME content, and uploads each supplied document to the returned storage URL before query use.
• Synchronous Account Enrollment — perplexity/client.py: Uses a disposable address to initiate Perplexity sign-in, waits for the email link, redeems it, and resets the pro-query counter.
• Asynchronous Query Client — perplexity_async/client.py: Async-await equivalent of session setup, account enrollment, file upload, and SSE response consumption.
• Validation and Event Decoder — perplexity/utils.py: Supplies query/file/limit validation and nested JSON response parsing used by both query clients.
Disposable-email identity flow
• Synchronous Emailnator Helper — perplexity/emailnator.py: Creates a disposable address, tracks inbox and advertisement message IDs, polls for new mail, and opens selected messages.
• Asynchronous Emailnator Helper — perplexity_async/emailnator.py: Provides the same address-generation and mailbox workflow through async HTTP and polling.
Labs query channel
• Synchronous Labs Client — perplexity/labs.py: Establishes a Socket.IO polling session and authenticated WebSocket, maintains conversational history and latest answer, and submits Labs prompts.
• Asynchronous Labs Client — perplexity_async/labs.py: Async construction and polling around the same Labs WebSocket protocol, with history and streaming/final-answer state.
Interactive and MCP entry points
• Browser Automation Driver — perplexity/driver.py: Runs or attaches to Chrome, intercepts browser traffic to capture Perplexity and Emailnator cookies, and maintains a background account-creation loop.
• MCP Tool Server — perplexity/mcp.py: Documented MCP entry point exposing four Perplexity query modes over stdio or HTTP; its implementation was not included in the sampled source.
• Python Application Developer — external, repository path: null: Imports the package and invokes synchronous or asynchronous client methods.
• MCP Client — external, repository path: null: Spawns the stdio server or connects to its HTTP /mcp endpoint.
• Perplexity Web Interface — external, repository path: null: Supplies session, sign-in, upload-authorization, SSE query, and Labs socket endpoints.
• Emailnator Service — external, repository path: null: Generates disposable email addresses and serves their mailbox contents.
• Returned Object Storage — external, repository path: null: Receives multipart file bytes at the upload URL returned by the Perplexity upload flow.
• Chrome / Patchright / Playwright Runtime — external, repository path: null: Hosts the browser context controlled by the Driver.
3. Relationships
• Python Application Developer -> Synchronous Query Client: invokes Client.search; documented public synchronous API.
• Synchronous Query Client -> Validation and Event Decoder: validates search/file/limit inputs and parses nested SSE JSON; imported utility calls.
• Synchronous Query Client -> Synchronous File Ingestion: conditionally processes supplied files; documented search contract and upload code in the client.
• Synchronous File Ingestion -> Perplexity Web Interface: requests upload metadata; posts to the configured upload endpoint.
• Synchronous File Ingestion -> Returned Object Storage: uploads multipart MIME data; posts to returned s3_bucket_url.
• Synchronous Query Client -> Perplexity Web Interface: performs session handshake and consumes configured SSE query responses; session setup, endpoint imports, and SSE parsing.
• Python Application Developer -> Synchronous Account Enrollment: invokes Client.create_account; documented public API.
• Synchronous Account Enrollment -> Synchronous Emailnator Helper: creates an address, polls for the sign-in message, and opens it.
• Synchronous Account Enrollment -> Perplexity Web Interface: posts sign-in initiation and redeems the extracted callback link.
• Synchronous Emailnator Helper -> Emailnator Service: generates an address and reads mailbox/message content through HTTP endpoints.
• Python Application Developer -> Asynchronous Query Client: awaits async client construction and search/account methods; documented async API.
• Asynchronous Query Client -> Asynchronous Emailnator Helper: awaits disposable-address and mailbox operations during account creation.
• Asynchronous Query Client -> Perplexity Web Interface: performs async session/sign-in/upload/query HTTP operations and parses streamed events.
• Asynchronous Emailnator Helper -> Emailnator Service: asynchronously generates addresses and polls/opens messages.
• Python Application Developer -> Synchronous Labs Client: invokes ask as an alternative query workflow.
• Synchronous Labs Client -> Perplexity Web Interface: polls, authenticates, and exchanges Labs messages over WebSocket.
• Python Application Developer -> Asynchronous Labs Client: awaits the alternative async Labs workflow.
• Asynchronous Labs Client -> Perplexity Web Interface: establishes and uses the Labs Socket.IO/WebSocket channel.
• Python Application Developer -> Browser Automation Driver: invokes browser-driven account automation.
• Browser Automation Driver -> Chrome / Patchright / Playwright Runtime: launches a persistent Chrome context or attaches through CDP.
• Browser Automation Driver -> Perplexity Web Interface: intercepts fetched browser requests and captures session cookies.
• MCP Client -> MCP Tool Server: starts it over stdio or calls its HTTP MCP endpoint; README-documented transport behavior.
• MCP Tool Server -> Perplexity Web Interface: provides documented search tools backed by the reverse-engineered web interface; direct implementation wiring is unverified because this source file was not sampled.
4. Coverage limits. The sampled excerpts omit the bodies of synchronous/async search request construction, portions of account retry behavior, and all MCP implementation code. The repository documents a GUI-oriented browser workflow, but no standalone web-server/UI entry point beyond the browser Driver and MCP HTTP transport could be established.
Main entry points: perplexity/client.py Synchronous Query Client · perplexity_async/client.py Asynchronous Query Client · driver.py Browser Automation Driver · emailnator.py Synchronous Emailnator Helper
Components 17
Query and Account API
- Synchronous Query Client · Owns synchronous search lifecycle and response handling.
perplexity/client.py - Synchronous File Ingestion · Uploads supplied documents before querying.
perplexity/client.py - Synchronous Account Enrollment · Enrolls accounts through disposable email sign-in.
perplexity/client.py - Asynchronous Query Client · Async session, account, upload, and SSE handling.
perplexity_async/client.py - Validation and Event Decoder · Validates inputs and parses nested JSON events.
perplexity/utils.py
Disposable Email Flow
- Synchronous Emailnator Helper · Creates addresses and polls disposable mailboxes.
perplexity/emailnator.py - Asynchronous Emailnator Helper · Async address generation and mailbox polling.
perplexity_async/emailnator.py
Labs Query Channel
- Synchronous Labs Client · Maintains Labs history and WebSocket answers.
perplexity/labs.py - Asynchronous Labs Client · Async Labs polling and WebSocket state.
perplexity_async/labs.py
Interactive and MCP Entry Points
- Browser Automation Driver · Controls browsers and captures service cookies.
perplexity/driver.py - MCP Tool Server · Exposes four Perplexity query modes over stdio or HTTP.
perplexity/mcp.py
External Systems
- Python Application Developer · Imports the package and invokes client APIs.
- MCP Client · Starts or connects to the MCP server.
- Perplexity Web Interface · Provides web query, sign-in, upload, and Labs endpoints.
- Emailnator Service · Generates disposable addresses and serves mailboxes.
- Returned Object Storage · Receives uploaded multipart file bytes.
- Chrome / Patchright / Playwright Runtime · Hosts the controlled browser context.
Connections 23
- Python Application Developer → Synchronous Query Client: invokes search · Documented public synchronous API.
- Synchronous Query Client → Validation and Event Decoder: validates and parses
- Synchronous Query Client → Synchronous File Ingestion: processes files · Conditional file-upload path.
- Synchronous File Ingestion → Perplexity Web Interface: requests upload metadata
- Synchronous File Ingestion → Returned Object Storage: uploads file bytes
- Synchronous Query Client → Perplexity Web Interface: queries via SSE
- Python Application Developer → Synchronous Account Enrollment: creates account · Documented public API.
- Synchronous Account Enrollment → Synchronous Emailnator Helper: uses mailbox
- Synchronous Account Enrollment → Perplexity Web Interface: signs in
- Synchronous Emailnator Helper → Emailnator Service: reads mailbox
- Python Application Developer → Asynchronous Query Client: awaits search · Documented async API.
- Asynchronous Query Client → Asynchronous Emailnator Helper: uses mailbox
- Asynchronous Query Client → Perplexity Web Interface: performs async query
- Asynchronous Emailnator Helper → Emailnator Service: polls mailbox
- Python Application Developer → Synchronous Labs Client: invokes ask · Alternative query workflow.
- Synchronous Labs Client → Perplexity Web Interface: uses Labs channel
- Python Application Developer → Asynchronous Labs Client: awaits Labs workflow · Alternative async workflow.
- Asynchronous Labs Client → Perplexity Web Interface: uses Labs channel
- Python Application Developer → Browser Automation Driver: runs automation
- Browser Automation Driver → Chrome / Patchright / Playwright Runtime: controls browser
- Browser Automation Driver → Perplexity Web Interface: captures cookies
- MCP Client → MCP Tool Server: starts or connects · Uses stdio or HTTP MCP transport.
- MCP Tool Server → Perplexity Web Interface: backs search tools · Direct implementation wiring is unverified because the source was not sampled.