# helallao/perplexity-ai architecture

> Architecture diagram of the GitHub repository helallao/perplexity-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/helallao/perplexity-ai
- Repository: https://github.com/helallao/perplexity-ai

## Overview

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`](https://github.com/helallao/perplexity-ai/blob/main/perplexity/client.py) (Synchronous Query Client), [`perplexity_async/client.py`](https://github.com/helallao/perplexity-ai/blob/main/perplexity_async/client.py) (Asynchronous Query Client), [`perplexity/driver.py`](https://github.com/helallao/perplexity-ai/blob/main/perplexity/driver.py) (Browser Automation Driver), [`perplexity/emailnator.py`](https://github.com/helallao/perplexity-ai/blob/main/perplexity/emailnator.py) (Synchronous Emailnator Helper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query_api["Query and Account API"]
  node_sync_query["Synchronous Query Client<br/>[client.py]"]
  node_sync_files["Synchronous File Ingestion<br/>[client.py]"]
  node_sync_account["Synchronous Account Enrollment<br/>account service"]
  node_async_query["Asynchronous Query Client<br/>async client"]
  node_validation_decoder["Validation and Event Decoder<br/>[utils.py]"]
end

subgraph group_email_flow["Disposable Email Flow"]
  node_sync_email["Synchronous Emailnator Helper<br/>email helper"]
  node_async_email["Asynchronous Emailnator Helper<br/>async email helper"]
end

subgraph group_labs_channel["Labs Query Channel"]
  node_sync_labs["Synchronous Labs Client<br/>[labs.py]"]
  node_async_labs["Asynchronous Labs Client<br/>async Labs client"]
end

subgraph group_entry_points["Interactive and MCP Entry Points"]
  node_browser_driver["Browser Automation Driver<br/>browser driver"]
  node_mcp_server["MCP Tool Server<br/>MCP server"]
end

subgraph group_external_systems["External Systems"]
  node_app_developer(("Python Application Developer<br/>external actor"))
  node_mcp_client(("MCP Client<br/>external actor"))
  node_perplexity_web["Perplexity Web Interface<br/>external service"]
  node_emailnator_service["Emailnator Service<br/>external service"]
  node_object_storage["Returned Object Storage<br/>external storage"]
  node_chrome_runtime["Chrome / Patchright / Playwright Runtime<br/>external runtime"]
end

node_app_developer -->|"invokes search"| node_sync_query
node_sync_query -->|"validates and parses"| node_validation_decoder
node_sync_query -.->|"processes files"| node_sync_files
node_sync_files -->|"requests upload metadata"| node_perplexity_web
node_sync_files -->|"uploads file bytes"| node_object_storage
node_sync_query -->|"queries via SSE"| node_perplexity_web
node_app_developer -->|"creates account"| node_sync_account
node_sync_account -->|"uses mailbox"| node_sync_email
node_sync_account -->|"signs in"| node_perplexity_web
node_sync_email -->|"reads mailbox"| node_emailnator_service
node_app_developer -->|"awaits search"| node_async_query
node_async_query -->|"uses mailbox"| node_async_email
node_async_query -->|"performs async query"| node_perplexity_web
node_async_email -->|"polls mailbox"| node_emailnator_service
node_app_developer -->|"invokes ask"| node_sync_labs
node_sync_labs -->|"uses Labs channel"| node_perplexity_web
node_app_developer -->|"awaits Labs workflow"| node_async_labs
node_async_labs -->|"uses Labs channel"| node_perplexity_web
node_app_developer -->|"runs automation"| node_browser_driver
node_browser_driver -->|"controls browser"| node_chrome_runtime
node_browser_driver -->|"captures cookies"| node_perplexity_web
node_mcp_client -->|"starts or connects"| node_mcp_server
node_mcp_server -.->|"backs search tools"| node_perplexity_web

click node_sync_query "https://github.com/helallao/perplexity-ai/blob/main/perplexity/client.py"
click node_sync_files "https://github.com/helallao/perplexity-ai/blob/main/perplexity/client.py"
click node_sync_account "https://github.com/helallao/perplexity-ai/blob/main/perplexity/client.py"
click node_async_query "https://github.com/helallao/perplexity-ai/blob/main/perplexity_async/client.py"
click node_validation_decoder "https://github.com/helallao/perplexity-ai/blob/main/perplexity/utils.py"
click node_sync_email "https://github.com/helallao/perplexity-ai/blob/main/perplexity/emailnator.py"
click node_async_email "https://github.com/helallao/perplexity-ai/blob/main/perplexity_async/emailnator.py"
click node_sync_labs "https://github.com/helallao/perplexity-ai/blob/main/perplexity/labs.py"
click node_async_labs "https://github.com/helallao/perplexity-ai/blob/main/perplexity_async/labs.py"
click node_browser_driver "https://github.com/helallao/perplexity-ai/blob/main/perplexity/driver.py"
click node_mcp_server "https://github.com/helallao/perplexity-ai/blob/main/perplexity/mcp.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sync_query,node_sync_files,node_sync_account,node_async_query,node_validation_decoder toneBlue
class node_sync_email,node_async_email toneAmber
class node_sync_labs,node_async_labs toneMint
class node_browser_driver,node_mcp_server toneRose
class node_app_developer,node_mcp_client,node_perplexity_web,node_emailnator_service,node_object_storage,node_chrome_runtime toneIndigo
```

## Components

### Query and Account API

- [Synchronous Query Client](https://github.com/helallao/perplexity-ai/blob/main/perplexity/client.py): client · Owns synchronous search lifecycle and response handling. · `perplexity/client.py`
- [Synchronous File Ingestion](https://github.com/helallao/perplexity-ai/blob/main/perplexity/client.py): ingestion · Uploads supplied documents before querying. · `perplexity/client.py`
- [Synchronous Account Enrollment](https://github.com/helallao/perplexity-ai/blob/main/perplexity/client.py): account service · Enrolls accounts through disposable email sign-in. · `perplexity/client.py`
- [Asynchronous Query Client](https://github.com/helallao/perplexity-ai/blob/main/perplexity_async/client.py): async client · Async session, account, upload, and SSE handling. · `perplexity_async/client.py`
- [Validation and Event Decoder](https://github.com/helallao/perplexity-ai/blob/main/perplexity/utils.py): utility · Validates inputs and parses nested JSON events. · `perplexity/utils.py`

### Disposable Email Flow

- [Synchronous Emailnator Helper](https://github.com/helallao/perplexity-ai/blob/main/perplexity/emailnator.py): email helper · Creates addresses and polls disposable mailboxes. · `perplexity/emailnator.py`
- [Asynchronous Emailnator Helper](https://github.com/helallao/perplexity-ai/blob/main/perplexity_async/emailnator.py): async email helper · Async address generation and mailbox polling. · `perplexity_async/emailnator.py`

### Labs Query Channel

- [Synchronous Labs Client](https://github.com/helallao/perplexity-ai/blob/main/perplexity/labs.py): Labs client · Maintains Labs history and WebSocket answers. · `perplexity/labs.py`
- [Asynchronous Labs Client](https://github.com/helallao/perplexity-ai/blob/main/perplexity_async/labs.py): async Labs client · Async Labs polling and WebSocket state. · `perplexity_async/labs.py`

### Interactive and MCP Entry Points

- [Browser Automation Driver](https://github.com/helallao/perplexity-ai/blob/main/perplexity/driver.py): browser driver · Controls browsers and captures service cookies. · `perplexity/driver.py`
- [MCP Tool Server](https://github.com/helallao/perplexity-ai/blob/main/perplexity/mcp.py): MCP server · Exposes four Perplexity query modes over stdio or HTTP. · `perplexity/mcp.py`

### External Systems

- **Python Application Developer**: external actor · Imports the package and invokes client APIs.
- **MCP Client**: external actor · Starts or connects to the MCP server.
- **Perplexity Web Interface**: external service · Provides web query, sign-in, upload, and Labs endpoints.
- **Emailnator Service**: external service · Generates disposable addresses and serves mailboxes.
- **Returned Object Storage**: external storage · Receives uploaded multipart file bytes.
- **Chrome / Patchright / Playwright Runtime**: external runtime · Hosts the controlled browser context.

## Connections

- 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.
