feat(clients): perplexity: Sonar, Search, Agent, embeddings, decisions, batches, skills, orchestrator
Package molo::perplexity covering all 39 operations of the five published OpenAPI documents, PerplexityChatModel, demo routes under /ai/perplexity, check_spec.py, SPEC.md, 46 unit cases and 111 route checks. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Vendored
+271
@@ -0,0 +1,271 @@
|
||||
# Perplexity API platform - Specification
|
||||
|
||||
Owned directory: `src/vendors/perplexity/`. Namespace `molo::perplexity`. Depends
|
||||
on the `src/llm` foundation (`ApiClient`, `Service`, `SseDecoder`, `ApiError`,
|
||||
`Config`, `ChatModel`). Plans: `plans/17-llm-vendor-platforms.md`,
|
||||
`plans/18-breadth.md`. Credential: `PERPLEXITY_API_KEY` via `llm::Config`
|
||||
(create one in the API Console, https://console.perplexity.ai/ , API Keys; the
|
||||
exact page path was not verified, see Unverified).
|
||||
|
||||
## 1. Scope
|
||||
|
||||
The whole public platform at `https://api.perplexity.ai` as published on
|
||||
2026-10-25 in five OpenAPI documents (39 operations):
|
||||
|
||||
- Sonar chat completions (`POST /v1/sonar`): search options (`search_mode`
|
||||
web / academic / sec, domain, language, recency and date filters,
|
||||
`web_search_options` with context size, search type and user location),
|
||||
citations, `search_results`, images, related questions, reasoning effort,
|
||||
structured output (`response_format` json_schema), text / image / file /
|
||||
PDF / video parts, streaming (`stream_mode`), usage with cost.
|
||||
- Async chat completions (`/v1/async/sonar`: create, list, get) with a bounded
|
||||
`wait_async`.
|
||||
- Search API (`POST /search`): single and multi query (up to 5), fast and
|
||||
people search, filters, per-page token limits.
|
||||
- Embeddings (`pplx-embed-v1-*`) and contextualized embeddings
|
||||
(`pplx-embed-context-v1-*`), Matryoshka dimensions, base64 int8 / binary.
|
||||
- Agent API (`POST /v1/agent`): models and effort levels, fallback chain,
|
||||
profiles, tools (web_search, image_search, finance_search, people_search,
|
||||
fetch_url, sandbox, function, mcp, connector), skills (builtin, inline,
|
||||
custom), structured output, streaming events, background runs, retrieve,
|
||||
cancel, files a run delivered.
|
||||
- Decisions API (`POST /v1/decisions`): noul / choice / score questions.
|
||||
- Batch API for the Agent API (`/v1/batches`, `/v1/files`).
|
||||
- Managed skills (`/v1/skills`, zip bundles, revisions, download URL).
|
||||
- Models (`GET /v1/models`), usage analytics v1 and v2, auth token generate
|
||||
and revoke.
|
||||
- Orchestrator API (`/orchestrator/v1`): OpenAI Chat Completions, OpenAI
|
||||
Responses and Anthropic Messages schemas, model list and retrieve.
|
||||
- `PerplexityChatModel : llm::ChatModel` over Sonar.
|
||||
|
||||
Not here, said plainly: the Python SDK document also lists
|
||||
`POST /v1/browser/sessions` and `DELETE /v1/browser/sessions/{id}`; no public
|
||||
OpenAPI document has them and the live host answers 404 (probe below), so they
|
||||
are not wrapped. The OpenAPI schemas `ReasoningStep-Output`, `StreamChunk`
|
||||
(SDK) and `OutputTokensDetails` are declared but unreferenced; nothing parses
|
||||
them. Pricing tables are not wrapped (docs prose only; the Orchestrator model
|
||||
list carries machine-readable pricing and is parsed). The SDK path aliases
|
||||
(`/chat/completions`, `/async/chat/completions`, `/v1/responses...`) are
|
||||
recorded (check_spec.py `SDK_ALIASES`) but the module sends the OpenAPI paths.
|
||||
|
||||
## 2. Module map
|
||||
|
||||
| File | Concern |
|
||||
|---|---|
|
||||
| `caps.h` | Static ceilings (`PerplexityCaps`) |
|
||||
| `calls.h/.cpp` | The ONE call table (39 rows) and schema table; `Calls::render` |
|
||||
| `rules.h/.cpp` | Shared input rules (`Rules`), all throw `ApiError::invalid`; URL query encoding |
|
||||
| `types.h/.cpp` | `J` readers, `SonarUsage`/`Cost`, `WebResult`, `ImageResult`, `ModelInfo`, `ModelList` |
|
||||
| `errors.h/.cpp` | `Errors`: documented statuses, retryable, static waits, `explain` |
|
||||
| `platform.h/.cpp` | `Platform`: the one `ApiClient` (Bearer) |
|
||||
| `sonar_params.h/.cpp` | `Messages` builders, `WebSearchOptions`, `StructuredOutput`, `SonarParams`, `SonarModels` |
|
||||
| `sonar_result.h/.cpp` | `SonarResult`, `SonarStreamFolder` |
|
||||
| `sonar.h/.cpp` | `Sonar : Service` (create, stream, async create / list / get / wait) |
|
||||
| `search.h/.cpp` | `SearchParams`, `SearchResponse`, `Search : Service` |
|
||||
| `embeddings.h/.cpp` | `EmbedParams`, `ContextEmbedParams`, `Vector` (decode), `Embeddings : Service` |
|
||||
| `agent_params.h/.cpp` | `AgentInput`, `AgentTools`, `AgentSkills`, `AgentParams` |
|
||||
| `agent_result.h/.cpp` | `AgentResult` (typed accessors over output items), `AgentStreamFolder` |
|
||||
| `agent.h/.cpp` | `Agent : Service` (create, stream, background, get, wait, cancel, files) |
|
||||
| `decisions.h/.cpp` | `DecisionQuestions`, `DecisionsParams`, `DecisionsResult`, `Decisions : Service` |
|
||||
| `batches.h/.cpp` | `BatchInput`, `BatchFiles : Service`, `Batches : Service` |
|
||||
| `skills.h/.cpp` | `SkillBundle`, `Skills : Service` |
|
||||
| `account.h/.cpp` | `Account : Service` (models, usage v1 / v2, auth tokens), `UsageQuery` |
|
||||
| `orchestrator.h/.cpp` | `Orchestrator : Service` (chat, messages, responses, stream, models) |
|
||||
| `chat_model.h/.cpp` | `PerplexityChatModel : llm::ChatModel` |
|
||||
| `tools/check_spec.py` | Checks the call / schema tables against the five OpenAPI documents and the SDK document |
|
||||
|
||||
## 3. Static caps
|
||||
|
||||
| Knob | Value |
|
||||
|---|---|
|
||||
| Search results | 1..20 (web, fast); 1..50 only with `search_type=people` |
|
||||
| Search queries per request | 5 (docs); domain filter 20, language filter 20 (documented) |
|
||||
| Search token limits | 1..1,000,000 |
|
||||
| Embedding texts / documents | 512 per request; dimensions 128..1024 (0.6b) or 128..2560 (4b) |
|
||||
| Agent fallback models | 5; `max_steps` 1..100; skills 16 |
|
||||
| Agent tool limits | web `max_results` 1..50, image 1..30, `fetch_url` `max_urls` 1..10, image filters 10 each |
|
||||
| Inline skill | description 1,024 B; instructions 65,536 B per skill, 262,144 B per request |
|
||||
| Decisions | 128 questions; choice 255 options; score 10 levels |
|
||||
| Batches | list limit 1..100; metadata 16 pairs, key 64, value 512; `Idempotency-Key` 200; input file 50,000 lines and 200 MB |
|
||||
| Skills | list limit 1..200; bundle 64 MiB (ours) |
|
||||
| Usage analytics | v1 `limit` 1..31 (1d) or 1..168 (1h) |
|
||||
| Messages / stop sequences / filter entries | 4096 / 16 / 20 (ours) |
|
||||
| Stream events | 200,000 (ours) |
|
||||
| List walk | 5,000 items returned, `truncated=true` beyond (ours) |
|
||||
| Wait helpers | poll interval floor 1 s (tier 0 = 1 request per second), ceiling 600 s (ours) |
|
||||
| Request / response / stream / SSE event | foundation caps: 32 MiB / 64 MiB / 64 MiB / 4 MiB |
|
||||
|
||||
## 4. Contracts
|
||||
|
||||
- Every path comes from the call table. Input is validated before any network
|
||||
traffic (HTTP 400 `INVALID_ARGUMENT`, vendor `perplexity`); no credential:
|
||||
`NotConfiguredError` 503 before traffic. The key travels in the
|
||||
`Authorization: Bearer` header only, never in a URL or an error.
|
||||
- Ids go through `Service::valid_id` before they are placed in a path; an
|
||||
Orchestrator model id may be `creator/name` (two valid segments).
|
||||
- Citations: `[n]` markers in Sonar text map to `citations[n-1]` and to
|
||||
`search_results`; in the Agent API a marker maps to the `search_results`
|
||||
item whose numeric `id` is `n`, one id space across all search items.
|
||||
- Destructive calls are explicit methods without defaults: `Agent::cancel`,
|
||||
`Batches::cancel`, `BatchFiles::remove`, `Skills::remove` (needs
|
||||
`expected_revision`), `Account::revoke_token`.
|
||||
- A generated auth token is a secret returned once; the module never logs or
|
||||
echoes it.
|
||||
- Streams: comment lines (keep-alives) are ignored by the foundation decoder;
|
||||
a stream that ends without `finish_reason` / `response.completed` /
|
||||
`response.failed` and was not stopped by the consumer throws 502
|
||||
`STREAM_TRUNCATED`. `response.paused` events (token limit pause) do not
|
||||
end the stream.
|
||||
- Background and async runs: poll with `wait` / `wait_async` (bounded);
|
||||
`Agent` status `in_progress` with a `paused` object means a token limit
|
||||
pause: keep polling, do not resubmit.
|
||||
- Errors (`Errors`): 400, 401 (`invalid_api_key`), 402 (credits), 403, 404,
|
||||
409, 413, 422, 429 (`request_rate_limit_exceeded`,
|
||||
`token_rate_limit_exceeded`, `overloaded`), 5xx. Retryable: 429, 500-504
|
||||
with static waits of 1..2 s, cap 30 s. A 429 carries `Retry-After`, which
|
||||
`ApiError` drops (foundation gap), so the static floor is the advice.
|
||||
- Rate limits (docs): Search 50 query units per second (one per query);
|
||||
Agent API 1..33 QPS by tier plus per-model TPM / TPH token limits;
|
||||
embeddings 85..335 QPS; batch and file calls follow the tier request limit.
|
||||
- Skill updates are PUT multipart: the foundation `post_multipart` is
|
||||
POST-only, so the module encodes the form itself and sends it through
|
||||
`request_raw`.
|
||||
- Orchestrator: requests are JSON documents validated for what Perplexity
|
||||
states: top-level fields from the call table, `model` is `creator/name`,
|
||||
Messages requires `max_tokens`, and `container`, `inference_geo`,
|
||||
`mcp_servers`, `fallbacks`, `fallback_credit_token` are rejected locally
|
||||
(Perplexity rejects them).
|
||||
- `PerplexityChatModel`: `tools`, `tool_choice`, tool parts and `json_mode`
|
||||
are rejected (Sonar has no function calling; use the Agent API);
|
||||
`response_schema` maps to json_schema; `extra` may carry Sonar request
|
||||
fields (unknown names rejected); citations stay in `ChatResponse.raw`.
|
||||
|
||||
## 5. Example routes (`/ai/perplexity`)
|
||||
|
||||
GET `/ai/perplexity` (page), `/status`, `/calls`, `/errors`. POST `/sonar`,
|
||||
`/stream`, `/async` (create, get, list), `/search`, `/embeddings` (plain or
|
||||
`documents` for contextualized), `/agent` (create, get, cancel, files),
|
||||
`/orchestrator` (chat, messages, responses), `/decisions`, `/models` (agent or
|
||||
orchestrator), `/usage` (v1 or per member), `/batches` (list, get, create,
|
||||
cancel, files, file_get, file_delete, upload), `/skills` (list, get,
|
||||
revisions, download, delete, create, update). 422 on bad input first;
|
||||
Sonar, stream, async create, search, embeddings, agent create / cancel,
|
||||
orchestrator, decisions, batch create / cancel, file delete, uploads and
|
||||
skill delete / create / update are dry runs showing the exact request unless
|
||||
the body has `"confirm":true`; then 503 `perplexity_not_configured` without a
|
||||
key; oversize body 413. Reads (models, usage, list, get) answer 503 without a
|
||||
key.
|
||||
|
||||
## Required keys
|
||||
|
||||
| Env var | Page |
|
||||
|---|---|
|
||||
| `PERPLEXITY_API_KEY` | https://console.perplexity.ai/ (API Keys; unverified path, the Console blocks automated fetches) |
|
||||
|
||||
## Sources
|
||||
|
||||
Fetched 2026-10-25:
|
||||
- OpenAPI documents (all five served by docs.perplexity.ai and listed in
|
||||
`llms.txt`): `openapi.json` (32 operations), `openapi-auth.json`
|
||||
(2), `openapi-gateway-chat.json` (3), `openapi-gateway-messages.json` (1),
|
||||
`openapi-gateway-responses.json` (1).
|
||||
- Official Python SDK (`perplexityai/perplexity-py`): `api.md` and
|
||||
`.stats.yml`, which pins the Stainless OpenAPI document (14 operations,
|
||||
older paths such as `/chat/completions`, plus browser sessions).
|
||||
- Docs text: `llms.txt` and `llms-full.txt` (Rate Limits & Usage Tiers, FAQ,
|
||||
Batch API, Decisions recipes, Search overview, Agent API pages).
|
||||
- Unauthenticated probes of the live host (below).
|
||||
- Cross-checks: every path, method, operationId, body field and query
|
||||
parameter is stated by an OpenAPI document and by the generated call table
|
||||
check; the SDK document is a second source for 12 of the operations.
|
||||
|
||||
## Verified against spec
|
||||
|
||||
`python3 -I src/vendors/perplexity/tools/check_spec.py`, run 2026-10-25:
|
||||
`perplexity spec ok: 39 calls, 65 schemas, 39 operations in 5 documents all
|
||||
covered (exclusions: 0 operations, 1 field groups), sdk document: 14
|
||||
operations (12 aliases, 2 excluded)`. It checks method, path and operationId
|
||||
of every row, that each body field and query parameter we send exists, that
|
||||
every field of a wrapped operation is either sent or excluded (the five
|
||||
Messages fields Perplexity rejects), that each response schema and each field
|
||||
we read exists, that every operation of the five documents is a row, and that
|
||||
every SDK operation is a row, an alias or excluded (browser sessions). A
|
||||
mutated table (unknown field, wrong path) fails the check.
|
||||
|
||||
## Verified live
|
||||
|
||||
2026-10-25, no key, unauthenticated, from this host (full list in
|
||||
`tests/src/vendors/perplexity/test_live.cpp` and this table):
|
||||
|
||||
| Probe | Result |
|
||||
|---|---|
|
||||
| DNS and TLS `api.perplexity.ai` | resolves, TLS verifies |
|
||||
| `POST` without a key: `/v1/sonar`, `/chat/completions`, `/search`, `/v1/embeddings`, `/v1/contextualizedembeddings`, `/v1/async/sonar`, `/async/chat/completions`, `/v1/agent`, `/v1/responses`, `/v1/decisions`, `/v1/batches`, `/v1/files`, `/v1/skills`, `/generate_auth_token`, `/revoke_auth_token`, `/orchestrator/v1/{chat/completions,messages,responses}` | 401 `{"error":{"message":"Invalid API key provided. Ensure your API key is correct and active.","type":"invalid_api_key","code":401}}` |
|
||||
| `GET` without a key: `/v1/models` (spec says no auth, host disagrees), `/v1/async/sonar[/x]`, `/v1/agent/x[/files]`, `/v1/analytics/computer/usage`, `/v2/analytics/computer/usage`, `/v1/skills`, `/v1/batches`, `/v1/files`, `/v1/responses/x`, `/orchestrator/v1/models[/perplexity%2Fx]` | 401, same envelope |
|
||||
| `POST /v1/browser/sessions` | 404 HTML (openresty): not a public route |
|
||||
| `POST /nonexistent` | 404 (empty body), so 401 versus 404 does prove a path exists on this host |
|
||||
| invalid key via `ApiClient` (`perplexity_live.invalid_key_answers_401_with_the_error_envelope`, `MOLO_LIVE_NET=1`) | 401, `type=invalid_api_key` |
|
||||
|
||||
Everything else is verified by the published documents only. Rerun the live
|
||||
tests with `MOLO_LIVE_NET=1 PERPLEXITY_API_KEY=... make ai-test` (read-only:
|
||||
models; with `MOLO_LIVE_PAID=1` one Search of 1 result and one Sonar
|
||||
completion of at most 8 tokens).
|
||||
|
||||
## Unverified
|
||||
|
||||
- Every success response shape comes from OpenAPI schemas or docs examples,
|
||||
never from a live reply (no key). Test fixtures labelled SCHEMA have
|
||||
invented values; FIXTURE ones are verbatim from the docs or OpenAPI
|
||||
examples (search results, decisions, batch, usage analytics, models).
|
||||
- Sonar stream: chunks are assumed to be `CompletionResponse` documents whose
|
||||
`choices[].delta` carries the increment, with `citations`, `search_results`,
|
||||
`usage` on later chunks; the end marker is assumed to be a `finish_reason`
|
||||
(the schema also names a `type` of `end_of_stream`, handled). No stream
|
||||
transcript was published. Whether a trailing `data: [DONE]` is sent is
|
||||
unknown (handled either way).
|
||||
- Agent stream event payloads beyond the keys the OpenAPI event schemas list;
|
||||
`response.paused` / `response.resumed` shapes come from the Rate Limits page
|
||||
only. `stream_options.include_token_pause_events` is documented in prose
|
||||
but absent from the OpenAPI request schema, so it is not sent.
|
||||
- `GET /v1/agent/{id}?stream=true&starting_after=` (stream reconnect) is in
|
||||
the docs only and needs a GET stream (foundation gap): not wrapped.
|
||||
- `usage.output_tokens_details.reasoning_tokens` on Agent responses: the
|
||||
schema `ResponsesUsage` does not list it (an unreferenced
|
||||
`OutputTokensDetails` exists); read tolerantly, may stay 0.
|
||||
- Embedding `base64_binary` bit order (read as raw bytes only).
|
||||
- The batch input line schema (`custom_id`, `method`, `url`, `body`) is not in
|
||||
the OpenAPI documents; lines are only checked to be JSON objects.
|
||||
- Multi-query Search response shape: assumed one flat `results` array (the
|
||||
docs loop reads `search.results` once); not confirmed.
|
||||
- Whether the SDK alias paths (`/chat/completions` ...) behave identically to
|
||||
`/v1/sonar`; both answer 401 unauthenticated.
|
||||
- The console page for creating keys (blocked for automated fetches).
|
||||
- `ListAsyncApiChatCompletionsResponse.next_token` has no request parameter
|
||||
in the spec, so listing cannot page.
|
||||
- Error bodies other than the 401 envelope (402, 409, 422 FastAPI style
|
||||
`{"detail":[...]}` is from the schema; not seen).
|
||||
|
||||
## Gaps
|
||||
|
||||
- `src/llm`: `ApiClient::stream` is POST-only (no stream reconnect with GET);
|
||||
`ApiError` drops `Retry-After`; no unauthenticated request mode; no PUT
|
||||
multipart (worked around with `request_raw`); `tests/src/llm/test_llm.cpp`
|
||||
calls `unsetenv("MOLO_LIVE_NET")` mid-run, so live tests of later packages
|
||||
skip in a whole-suite run (this package reads the variable at static-init
|
||||
time instead).
|
||||
- No retry helper: `Errors::wait_seconds` is advice, not a loop.
|
||||
- Async list cannot page (`next_token` has no request parameter).
|
||||
- The Agent `Conversation` helper (history replay, tool loop) is not built:
|
||||
`AgentInput::function_call_output` and `AgentResult::function_calls` are the
|
||||
parts; owner `agent.cpp`.
|
||||
- Orchestrator request / response documents are passed through as `Json`
|
||||
(OpenAI / Anthropic schemas, owner `orchestrator.cpp`).
|
||||
- Pricing prose (per-token tables, request fees) is not wrapped.
|
||||
|
||||
## Tests
|
||||
|
||||
`make ai-test`: 46 perplexity cases (344 passed, 0 failed in the whole ai
|
||||
suite on 2026-10-25), 3 of them live (the invalid-key probe ran and passed with
|
||||
`MOLO_LIVE_NET=1`; the two key-gated ones print a loud SKIP). Example suite:
|
||||
`tests/example/ai/perplexity/{page,routes}_test.cpp`, 111 route checks;
|
||||
`make -f example/example.mk example-test`: 207 passed, 0 failed.
|
||||
Reference in New Issue
Block a user