Merge branch 'worktree-agent-a1d8c9d17ebff3c74'

This commit is contained in:
2026-10-25 15:24:27 +01:00
52 changed files with 7201 additions and 3 deletions
+271
View File
@@ -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.
+151
View File
@@ -0,0 +1,151 @@
#include "vendors/perplexity/account.h"
#include "vendors/perplexity/calls.h"
#include "vendors/perplexity/caps.h"
#include "vendors/perplexity/rules.h"
namespace molo::perplexity {
namespace {
void add(std::string& q, const std::string& k, const std::string& v) { Rules::add_query(q, k, v); }
std::string enc(const std::string& s) { return s; } // add() encodes
void check_common(const UsageQuery& q) {
Rules::require(q.start_time >= 0, "start_time must be unix seconds");
if (q.end_time) Rules::require(*q.end_time >= q.start_time, "end_time must not be before start_time");
Rules::require(q.page.size() <= 1024, "page cursor over 1024 characters");
for (char c : q.page) Rules::require(static_cast<unsigned char>(c) > 0x20 && c != 0x7f, "page cursor has invalid characters");
}
} // namespace
void UsageQuery::validate_v1() const {
Rules::one_of(dataset,
{"credit_usage", "connectors", "artifacts", "skills", "spaces", "workflows", "task_durations",
"query_volume", "daily_active_users"},
"dataset");
check_common(*this);
if (!bucket_width.empty()) Rules::one_of(bucket_width, {"1d", "1h"}, "bucket_width");
bool hourly = bucket_width == "1h";
bool daily_org = dataset == "query_volume" || dataset == "daily_active_users";
Rules::require(!(daily_org && hourly), "query_volume and daily_active_users reject bucket_width=1h");
Rules::require(!(daily_org && !user_email.empty()), "query_volume and daily_active_users reject user_email");
if (limit) Rules::require(*limit >= 1 && *limit <= (hourly ? 168 : 31), "limit must be 1..31 (1d) or 1..168 (1h)");
if (!user_email.empty())
Rules::require(user_email.size() <= 254 && user_email.find('@') != std::string::npos &&
user_email.find_first_of(" \t\r\n&?#") == std::string::npos,
"user_email must be an email address");
Rules::require(group_by.empty(), "group_by is a v2 parameter");
}
void UsageQuery::validate_v2() const {
Rules::one_of(dataset, {"credit_usage", "query_volume"}, "dataset");
Rules::one_of(group_by, {"user_email"}, "group_by");
check_common(*this);
Rules::require(bucket_width.empty() && user_email.empty(), "bucket_width and user_email are v1 parameters");
if (limit) Rules::require(*limit >= 1, "limit must be at least 1");
}
std::string UsageQuery::query_v1() const {
validate_v1();
std::string q;
add(q, "dataset", dataset);
add(q, "start_time", std::to_string(start_time));
if (end_time) add(q, "end_time", std::to_string(*end_time));
if (!bucket_width.empty()) add(q, "bucket_width", bucket_width);
if (limit) add(q, "limit", std::to_string(*limit));
if (!page.empty()) add(q, "page", enc(page));
if (!user_email.empty()) add(q, "user_email", enc(user_email));
return q;
}
std::string UsageQuery::query_v2() const {
validate_v2();
std::string q;
add(q, "dataset", dataset);
add(q, "group_by", group_by);
add(q, "start_time", std::to_string(start_time));
if (end_time) add(q, "end_time", std::to_string(*end_time));
if (limit) add(q, "limit", std::to_string(*limit));
if (!page.empty()) add(q, "page", enc(page));
return q;
}
UsageReport UsageReport::parse_v1(const Json& doc) {
UsageReport r;
r.raw = doc;
r.categories = J::strings(doc, "categories");
r.has_more = J::flag(doc, "has_more");
r.next_page = J::str(doc, "next_page");
if (const Json* d = J::arr(doc, "data"))
for (const Json& b : d->as_array()) {
if (r.buckets.size() >= PerplexityCaps::kMaxItemsReturned) {
r.truncated = true;
break;
}
UsageBucket u;
u.start_time = J::num(b, "start_time");
u.end_time = J::num(b, "end_time");
u.count = J::num(b, "count");
if (const Json* c = J::obj(b, "by_categories")) u.by_categories = *c;
r.buckets.push_back(std::move(u));
}
return r;
}
UsageReport UsageReport::parse_v2(const Json& doc) {
UsageReport r;
r.raw = doc;
r.categories = J::strings(doc, "categories");
r.has_more = J::flag(doc, "has_more");
r.next_page = J::str(doc, "next_page");
if (const Json* d = J::arr(doc, "data"))
for (const Json& day : d->as_array())
if (const Json* rs = J::arr(day, "results"))
for (const Json& m : rs->as_array()) {
if (r.buckets.size() >= PerplexityCaps::kMaxItemsReturned) {
r.truncated = true;
return r;
}
UsageBucket u;
u.start_time = J::num(day, "start_time");
u.end_time = J::num(day, "end_time");
u.user_email = J::str(m, "user_email");
u.count = J::num(m, "count");
if (const Json* c = J::obj(m, "by_categories")) u.by_categories = *c;
r.buckets.push_back(std::move(u));
}
return r;
}
ModelList Account::models() { return ModelList::parse(client_->get(Calls::render(Call::kModels))); }
UsageReport Account::usage(const UsageQuery& q) {
return UsageReport::parse_v1(client_->get(Calls::render(Call::kUsageV1) + q.query_v1()));
}
UsageReport Account::usage_per_member(const UsageQuery& q) {
return UsageReport::parse_v2(client_->get(Calls::render(Call::kUsageV2) + q.query_v2()));
}
AuthToken Account::generate_token(const std::string& token_name) {
Json body = Json::object();
if (!token_name.empty()) {
Rules::require(token_name.size() <= 128, "token_name over 128 characters");
body.set("token_name", Json(token_name));
}
Json doc = client_->post(Calls::render(Call::kAuthGenerate), body);
AuthToken t;
t.auth_token = J::str(doc, "auth_token");
t.created_at_epoch_seconds = J::dbl(doc, "created_at_epoch_seconds");
t.token_name = J::str(doc, "token_name");
return t;
}
Json Account::revoke_token(const std::string& auth_token) {
Rules::require(!auth_token.empty() && auth_token.size() <= 512, "auth_token must be 1..512 characters");
Json body = Json::object();
body.set("auth_token", Json(auth_token));
return client_->post(Calls::render(Call::kAuthRevoke), body);
}
} // namespace molo::perplexity
+73
View File
@@ -0,0 +1,73 @@
#pragma once
// Account-level calls: the Agent API model list (GET /v1/models), the usage
// analytics (v1 time series, v2 per member; org-scoped, free) and the auth
// token endpoints (generate, revoke). A generated token is a secret: it is
// returned to the caller once and never logged or echoed by this module.
#include <optional>
#include <string>
#include <vector>
#include "llm/api_client.h"
#include "vendors/perplexity/types.h"
namespace molo::perplexity {
struct UsageQuery {
std::string dataset; // v1: credit_usage, connectors, artifacts, skills, spaces, workflows, task_durations,
// query_volume, daily_active_users; v2: credit_usage, query_volume
long start_time = 0; // unix seconds, required
std::optional<long> end_time;
std::string bucket_width; // v1: "", 1d, 1h
std::optional<int> limit; // 1d: max 31, 1h: max 168
std::string page; // opaque cursor from next_page
std::string user_email; // v1 only
std::string group_by; // v2 only: user_email (required in v2)
void validate_v1() const;
void validate_v2() const;
std::string query_v1() const; // "?a=b&..."
std::string query_v2() const;
};
struct UsageCount {
std::string category;
long count = 0;
};
struct UsageBucket {
long start_time = 0, end_time = 0, count = 0;
std::string user_email; // v2 rows only
Json by_categories; // label -> [{category, count}]
};
struct UsageReport {
std::vector<std::string> categories;
std::vector<UsageBucket> buckets; // v2: one entry per member per day
bool has_more = false;
std::string next_page;
bool truncated = false;
Json raw;
static UsageReport parse_v1(const Json& doc);
static UsageReport parse_v2(const Json& doc);
};
struct AuthToken {
std::string auth_token; // SECRET
double created_at_epoch_seconds = 0;
std::string token_name;
};
class Account : public llm::Service {
public:
explicit Account(std::shared_ptr<llm::ApiClient> client) : llm::Service(std::move(client)) {}
ModelList models();
UsageReport usage(const UsageQuery& query);
UsageReport usage_per_member(const UsageQuery& query);
AuthToken generate_token(const std::string& token_name = "");
// Destructive: no default. Revokes the given token.
Json revoke_token(const std::string& auth_token);
};
} // namespace molo::perplexity
+83
View File
@@ -0,0 +1,83 @@
#include "vendors/perplexity/agent.h"
#include <chrono>
#include <thread>
#include "vendors/perplexity/calls.h"
#include "vendors/perplexity/caps.h"
#include "vendors/perplexity/rules.h"
namespace molo::perplexity {
AgentResult Agent::create(const AgentParams& params) {
return AgentResult::parse(client_->post(Calls::render(Call::kAgentCreate), params.to_json(false)));
}
AgentResult Agent::stream(const AgentParams& params, const EventSink& on_event) {
Json body = params.to_json(true);
AgentStreamFolder folder;
bool stopped = false;
client_->stream(Calls::render(Call::kAgentCreate), body, [&](const llm::SseEvent& ev) {
if (folder.events() >= PerplexityCaps::kMaxStreamEvents) {
stopped = true;
return false;
}
AgentDelta d = folder.feed(ev);
if (on_event && !on_event(d)) {
stopped = true;
return false;
}
return true;
});
if (!stopped && !folder.done())
throw llm::ApiError("perplexity", 502, "STREAM_TRUNCATED", "stream ended without response.completed");
return folder.result();
}
AgentResult Agent::create_background(AgentParams params) {
params.background = true;
return create(params);
}
AgentResult Agent::get(const std::string& response_id) {
check_id("response", response_id);
return AgentResult::parse(client_->get(Calls::render(Call::kAgentGet, response_id)));
}
AgentResult Agent::wait(const std::string& response_id, int interval_seconds, int max_wait_seconds,
const std::function<void(int)>& sleeper) {
Rules::require(interval_seconds >= PerplexityCaps::kMinPollIntervalSeconds, "poll interval must be at least 1 second");
Rules::require(max_wait_seconds >= 1 && max_wait_seconds <= PerplexityCaps::kMaxPollSeconds,
"max wait must be 1..600 seconds");
int waited = 0;
for (;;) {
AgentResult r = get(response_id);
if (r.finished()) return r;
if (waited + interval_seconds > max_wait_seconds)
throw llm::ApiError("perplexity", 504, "WAIT_TIMEOUT", "response still running after the wait ceiling");
if (sleeper) sleeper(interval_seconds);
else std::this_thread::sleep_for(std::chrono::seconds(interval_seconds));
waited += interval_seconds;
}
}
Json Agent::cancel(const std::string& response_id) {
check_id("response", response_id);
Json empty = Json::object();
return client_->post(Calls::render(Call::kAgentCancel, response_id), empty);
}
AgentFileList Agent::files(const std::string& response_id) {
check_id("response", response_id);
return AgentFileList::parse(client_->get(Calls::render(Call::kAgentFiles, response_id)));
}
FileBytes Agent::file_content(const std::string& response_id, const std::string& file_id) {
check_id("response", response_id);
check_id("file", file_id);
llm::RawResponse raw = client_->request_raw(
Calls::method_of(Call::kAgentFileContent), Calls::render(Call::kAgentFileContent, std::vector<std::string>{response_id, file_id}));
return FileBytes{raw.body, raw.content_type};
}
} // namespace molo::perplexity
+45
View File
@@ -0,0 +1,45 @@
#pragma once
// Agent API: POST /v1/agent (create, stream, background), GET /v1/agent/{id}
// (snapshot), cancel, and the files a run delivered with share_file. The SDKs
// call the same operations at /v1/responses (alias, see SPEC).
#include <functional>
#include <string>
#include "llm/api_client.h"
#include "vendors/perplexity/agent_params.h"
#include "vendors/perplexity/agent_result.h"
namespace molo::perplexity {
struct FileBytes {
std::string data;
std::string content_type;
};
class Agent : public llm::Service {
public:
explicit Agent(std::shared_ptr<llm::ApiClient> client) : llm::Service(std::move(client)) {}
AgentResult create(const AgentParams& params);
using EventSink = std::function<bool(const AgentDelta&)>; // false: stop early
// Streams events; returns the folded result. A stream that ends without
// response.completed / response.failed (and was not stopped by the sink)
// throws 502 STREAM_TRUNCATED.
AgentResult stream(const AgentParams& params, const EventSink& on_event);
// background:true create; returns the queued response to poll.
AgentResult create_background(AgentParams params);
AgentResult get(const std::string& response_id);
// Polls get() until the status is final. Interval floor 1 s, ceiling 600 s; throws 504 WAIT_TIMEOUT.
AgentResult wait(const std::string& response_id, int interval_seconds = 5, int max_wait_seconds = 300,
const std::function<void(int)>& sleeper = nullptr);
// Cancels a run (explicit, no default). Returns the response_id and status of the reply.
Json cancel(const std::string& response_id);
AgentFileList files(const std::string& response_id);
FileBytes file_content(const std::string& response_id, const std::string& file_id);
};
} // namespace molo::perplexity
+401
View File
@@ -0,0 +1,401 @@
#include "vendors/perplexity/agent_params.h"
#include <cctype>
#include "vendors/perplexity/caps.h"
#include "vendors/perplexity/rules.h"
namespace molo::perplexity {
namespace {
Json str_array(const std::vector<std::string>& v) {
Json a = Json::array();
for (const std::string& s : v) a.push(Json(s));
return a;
}
} // namespace
Json AgentInput::message(const std::string& role, const std::string& text) {
Rules::one_of(role, {"user", "assistant", "system", "developer"}, "role");
Json m = Json::object();
m.set("type", Json("message"));
m.set("role", Json(role));
m.set("content", Json(text));
return m;
}
Json AgentInput::message_parts(const std::string& role, const std::vector<Json>& parts) {
Rules::one_of(role, {"user", "assistant", "system", "developer"}, "role");
Rules::require(!parts.empty(), "a message needs at least one content part");
Json arr = Json::array();
for (const Json& p : parts) arr.push(p);
Json m = Json::object();
m.set("type", Json("message"));
m.set("role", Json(role));
m.set("content", arr);
return m;
}
Json AgentInput::text_part(const std::string& text) {
Json p = Json::object();
p.set("type", Json("input_text"));
p.set("text", Json(text));
return p;
}
Json AgentInput::image_part(const std::string& url) {
bool data = url.rfind("data:image/", 0) == 0 && url.find(";base64,") != std::string::npos;
Rules::require(data || (url.rfind("https://", 0) == 0 && Rules::is_http_url(url)), "image url must be https or a data:image/...;base64, URL");
Json p = Json::object();
p.set("type", Json("input_image"));
p.set("image_url", Json(url));
return p;
}
Json AgentInput::file_part(const std::string& file_data, const std::string& file_url, const std::string& filename) {
Rules::require(file_data.empty() != file_url.empty(), "exactly one of file_data and file_url is required");
if (!file_url.empty()) Rules::https_url(file_url, "file_url");
Json p = Json::object();
p.set("type", Json("input_file"));
if (!file_data.empty()) p.set("file_data", Json(file_data));
if (!file_url.empty()) p.set("file_url", Json(file_url));
if (!filename.empty()) {
Rules::require(filename.size() <= PerplexityCaps::kMaxFilenameBytes, "filename over 255 bytes");
p.set("filename", Json(filename));
}
return p;
}
Json AgentInput::function_call_output(const std::string& call_id, const std::string& output) {
Rules::require(!call_id.empty(), "call_id is required");
Json o = Json::object();
o.set("type", Json("function_call_output"));
o.set("call_id", Json(call_id));
o.set("output", Json(output));
return o;
}
Json AgentInput::function_call(const std::string& call_id, const std::string& name, const std::string& arguments) {
Rules::require(!call_id.empty() && !name.empty(), "call_id and name are required");
Json o = Json::object();
o.set("type", Json("function_call"));
o.set("call_id", Json(call_id));
o.set("name", Json(name));
o.set("arguments", Json(arguments));
return o;
}
Json AgentInput::mcp_approval_response(const std::string& approval_request_id, bool approve,
const std::string& reason) {
Rules::require(!approval_request_id.empty(), "approval_request_id is required");
Rules::require(!(approve && !reason.empty()), "a reason is rejected when approve is true");
Json o = Json::object();
o.set("type", Json("mcp_approval_response"));
o.set("approval_request_id", Json(approval_request_id));
o.set("approve", Json(approve));
if (!reason.empty()) o.set("reason", Json(reason));
return o;
}
Json AgentTools::web_search(const WebSearchToolOptions& o) {
Json t = Json::object();
t.set("type", Json("web_search"));
if (!o.search_type.empty()) {
Rules::one_of(o.search_type, {"web", "fast"}, "search_type");
t.set("search_type", Json(o.search_type));
}
if (o.max_results) {
Rules::require(*o.max_results >= 1 && *o.max_results <= PerplexityCaps::kWebToolMaxResults, "max_results must be 1..50");
t.set("max_results", Json(*o.max_results));
}
if (o.max_tokens) {
Rules::require(*o.max_tokens >= 1, "max_tokens must be at least 1");
t.set("max_tokens", Json(*o.max_tokens));
}
if (o.max_tokens_per_page) {
Rules::require(*o.max_tokens_per_page >= 1, "max_tokens_per_page must be at least 1");
t.set("max_tokens_per_page", Json(*o.max_tokens_per_page));
}
Json filters = Json::object();
if (!o.search_domain_filter.empty()) {
Rules::domains(o.search_domain_filter, PerplexityCaps::kSearchDomainFilter, "search_domain_filter");
filters.set("search_domain_filter", str_array(o.search_domain_filter));
}
if (!o.search_recency_filter.empty()) {
Rules::one_of(o.search_recency_filter, {"hour", "day", "week", "month", "year"}, "search_recency_filter");
filters.set("search_recency_filter", Json(o.search_recency_filter));
}
if (filters.as_object().size()) t.set("filters", filters);
if (!o.country.empty()) {
Rules::country(o.country);
Json loc = Json::object();
loc.set("country", Json(o.country));
t.set("user_location", loc);
}
return t;
}
Json AgentTools::image_search(int max_results, const std::vector<std::string>& domains,
const std::vector<std::string>& formats, std::optional<bool> safe_search) {
Json t = Json::object();
t.set("type", Json("image_search"));
if (max_results) {
Rules::require(max_results >= 1 && max_results <= PerplexityCaps::kImageToolMaxResults, "max_results must be 1..30");
t.set("max_results", Json(max_results));
}
Json f = Json::object();
if (!domains.empty()) {
Rules::require(domains.size() <= PerplexityCaps::kImageFilterEntries, "at most 10 domain filters");
Rules::domains(domains, PerplexityCaps::kImageFilterEntries, "domain_filter");
f.set("domain_filter", str_array(domains));
}
if (!formats.empty()) {
Rules::require(formats.size() <= PerplexityCaps::kImageFilterEntries, "at most 10 format filters");
for (const std::string& x : formats) Rules::one_of(x, {"bmp", "gif", "jpeg", "png", "webp", "svg"}, "format_filter entry");
f.set("format_filter", str_array(formats));
}
if (safe_search) f.set("safe_search", Json(*safe_search));
if (f.as_object().size()) t.set("filters", f);
return t;
}
Json AgentTools::finance_search() {
Json t = Json::object();
t.set("type", Json("finance_search"));
return t;
}
Json AgentTools::people_search() {
Json t = Json::object();
t.set("type", Json("people_search"));
return t;
}
Json AgentTools::sandbox() {
Json t = Json::object();
t.set("type", Json("sandbox"));
return t;
}
Json AgentTools::fetch_url(int max_urls) {
Json t = Json::object();
t.set("type", Json("fetch_url"));
if (max_urls) {
Rules::require(max_urls >= 1 && max_urls <= PerplexityCaps::kFetchToolMaxUrls, "max_urls must be 1..10");
t.set("max_urls", Json(max_urls));
}
return t;
}
Json AgentTools::function(const std::string& name, const std::string& description, const Json& parameters,
std::optional<bool> strict) {
Rules::name_token(name, 64, "function name");
Rules::require(parameters.is_object(), "function parameters must be a JSON Schema object");
Json t = Json::object();
t.set("type", Json("function"));
t.set("name", Json(name));
if (!description.empty()) t.set("description", Json(description));
t.set("parameters", parameters);
if (strict) t.set("strict", Json(*strict));
return t;
}
namespace {
void approval(Json& t, const std::string& require_approval) {
if (require_approval.empty()) return;
Rules::one_of(require_approval, {"always", "never"}, "require_approval");
t.set("require_approval", Json(require_approval));
}
} // namespace
Json AgentTools::mcp(const std::string& server_label, const std::string& server_url, const std::string& authorization,
const std::vector<std::string>& allowed_tools, const std::string& require_approval) {
Rules::name_token(server_label, 64, "server_label");
Rules::https_url(server_url, "server_url");
Json t = Json::object();
t.set("type", Json("mcp"));
t.set("server_label", Json(server_label));
t.set("server_url", Json(server_url));
if (!authorization.empty()) t.set("authorization", Json(authorization));
if (!allowed_tools.empty()) t.set("allowed_tools", str_array(allowed_tools));
approval(t, require_approval);
return t;
}
Json AgentTools::connector(const std::string& id, const std::string& server_label,
const std::vector<std::string>& allowed_tools, const std::string& require_approval) {
Rules::require(!id.empty(), "connector id is required");
Rules::name_token(server_label, 64, "server_label");
Json t = Json::object();
t.set("type", Json("connector"));
t.set("id", Json(id));
t.set("server_label", Json(server_label));
if (!allowed_tools.empty()) t.set("allowed_tools", str_array(allowed_tools));
approval(t, require_approval);
return t;
}
Json AgentTools::choice(const std::string& mode) {
Rules::one_of(mode, {"none", "auto", "required"}, "tool_choice");
return Json(mode);
}
Json AgentTools::choice_tool(const std::string& type) {
Rules::require(!type.empty(), "tool type is required");
Json o = Json::object();
o.set("type", Json(type));
return o;
}
Json AgentSkills::builtin(const std::string& name) {
Rules::one_of(name, {"office", "office/docx", "office/pdf", "office/pptx", "office/xlsx"}, "builtin skill");
Json s = Json::object();
s.set("type", Json("builtin"));
s.set("name", Json(name));
return s;
}
Json AgentSkills::inline_skill(const std::string& name, const std::string& description,
const std::string& instructions) {
Rules::require(!name.empty() && name.size() <= 128, "inline skill name must be 1..128 characters");
for (char c : name)
Rules::require((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-', "inline skill name is lowercase ASCII separated by hyphens");
Rules::require(name.front() != '-' && name.back() != '-' && name.find("--") == std::string::npos,
"inline skill name uses single hyphens between words");
Rules::require(!description.empty() && description.size() <= PerplexityCaps::kInlineSkillDescription,
"description must be 1..1024 bytes");
Rules::require(!instructions.empty() && instructions.size() <= PerplexityCaps::kInlineSkillInstructions,
"instructions must be 1..65536 bytes");
Json s = Json::object();
s.set("type", Json("inline"));
s.set("name", Json(name));
s.set("description", Json(description));
s.set("instructions", Json(instructions));
return s;
}
Json AgentSkills::custom(const std::string& id, const std::string& version) {
Rules::require(id.rfind("skill_", 0) == 0 && id.size() > 6, "custom skill id has the form skill_<id>");
Json s = Json::object();
s.set("type", Json("custom"));
s.set("id", Json(id));
if (!version.empty()) s.set("version", Json(version));
return s;
}
AgentParams AgentParams::prompt(const std::string& text, const std::string& model) {
AgentParams p;
p.input = Json(text);
p.model = model;
return p;
}
AgentParams AgentParams::with_effort(const std::string& text, const std::string& effort) {
AgentParams p;
p.input = Json(text);
p.effort = effort;
return p;
}
Json AgentParams::json_schema(const std::string& name, const Json& schema, bool strict, const std::string& description) {
Rules::name_token(name, 64, "schema name");
Rules::require(schema.is_object(), "json schema must be an object");
Json js = Json::object();
js.set("name", Json(name));
js.set("schema", schema);
js.set("strict", Json(strict));
if (!description.empty()) js.set("description", Json(description));
Json o = Json::object();
o.set("type", Json("json_schema"));
o.set("json_schema", js);
return o;
}
void AgentParams::validate() const {
Rules::require(input.is_string() || input.is_array(), "input must be a string or an array of input items");
if (input.is_string()) Rules::require(!input.as_string().empty(), "input must not be empty");
else {
Rules::require(!input.as_array().empty(), "input items must not be empty");
Rules::require(input.as_array().size() <= PerplexityCaps::kMaxInputItems, "too many input items");
for (const Json& i : input.as_array()) Rules::require(i.is_object() && i.has("type"), "every input item needs a type");
}
if (!model.empty()) Rules::model(model);
Rules::require(models.size() <= PerplexityCaps::kAgentModels, "at most 5 fallback models");
for (const std::string& m : models) Rules::model(m);
if (!effort.empty()) {
Rules::require(effort.size() <= 128, "effort over 128 characters");
for (char c : effort)
Rules::require(std::isalnum(static_cast<unsigned char>(c)) || c == '-' || c == '_' || c == '.' || c == '@',
"effort has invalid characters");
}
Rules::require(profile_id.empty() || effort.empty(), "profile cannot be combined with effort");
Rules::require(profile_version.empty() || !profile_id.empty(), "profile_version needs profile_id");
if (max_output_tokens) Rules::require(*max_output_tokens >= 1, "max_output_tokens must be at least 1");
bool anthropic = model.rfind("anthropic/", 0) == 0;
for (const std::string& m : models) anthropic = anthropic || m.rfind("anthropic/", 0) == 0;
Rules::require(!anthropic || max_output_tokens.has_value(), "max_output_tokens is required for anthropic/* models");
if (max_steps) Rules::require(*max_steps >= 1 && *max_steps <= PerplexityCaps::kAgentMaxSteps, "max_steps must be 1..100");
if (!reasoning_effort.empty())
Rules::one_of(reasoning_effort, {"minimal", "low", "medium", "high", "xhigh", "max"}, "reasoning effort");
if (!language_preference.empty()) Rules::language(language_preference, "language_preference");
if (!response_format.is_null()) {
Rules::require(J::str(response_format, "type") == "json_schema" && J::obj(response_format, "json_schema"),
"response_format must be {type:json_schema, json_schema:{name, schema}}");
const Json* js = J::obj(response_format, "json_schema");
Rules::require(!J::str(*js, "name").empty() && J::obj(*js, "schema"), "json_schema needs name and schema");
}
Rules::require(tools.size() <= PerplexityCaps::kMaxTools, "too many tools");
for (const Json& t : tools) Rules::require(t.is_object() && t.has("type"), "every tool needs a type");
Rules::require(skills.size() <= PerplexityCaps::kAgentSkills, "at most 16 skills");
std::size_t inline_bytes = 0;
for (const Json& s : skills) {
Rules::require(s.is_object() && s.has("type"), "every skill needs a type");
if (J::str(s, "type") == "inline") inline_bytes += J::str(s, "instructions").size();
}
Rules::require(inline_bytes <= PerplexityCaps::kInlineSkillsTotal, "inline skill instructions over 262144 bytes in total");
if (temperature) Rules::temperature(*temperature);
if (top_p) Rules::top_p(*top_p);
}
Json AgentParams::to_json(bool stream) const {
validate();
Json b = Json::object();
b.set("input", input);
if (!model.empty()) b.set("model", Json(model));
if (!models.empty()) b.set("models", str_array(models));
if (!effort.empty()) b.set("effort", Json(effort));
if (!profile_id.empty()) {
Json p = Json::object();
p.set("type", Json("custom"));
p.set("id", Json(profile_id));
if (!profile_version.empty()) p.set("version", Json(profile_version));
b.set("profile", p);
}
if (!instructions.empty()) b.set("instructions", Json(instructions));
if (!language_preference.empty()) b.set("language_preference", Json(language_preference));
if (max_output_tokens) b.set("max_output_tokens", Json(*max_output_tokens));
if (max_steps) b.set("max_steps", Json(*max_steps));
if (!previous_response_id.empty()) b.set("previous_response_id", Json(previous_response_id));
if (!reasoning_effort.empty()) {
Json r = Json::object();
r.set("effort", Json(reasoning_effort));
b.set("reasoning", r);
}
if (!response_format.is_null()) b.set("response_format", response_format);
if (store) b.set("store", Json(*store));
if (background) b.set("background", Json(*background));
if (stream) b.set("stream", Json(true));
if (!tools.empty()) {
Json a = Json::array();
for (const Json& t : tools) a.push(t);
b.set("tools", a);
}
if (!tool_choice.is_null()) b.set("tool_choice", tool_choice);
if (!skills.empty()) {
Json a = Json::array();
for (const Json& s : skills) a.push(s);
b.set("skills", a);
}
if (temperature) b.set("temperature", Json(*temperature));
if (top_p) b.set("top_p", Json(*top_p));
return b;
}
} // namespace molo::perplexity
+95
View File
@@ -0,0 +1,95 @@
#pragma once
// Request side of the Agent API (POST /v1/agent, ResponsesRequest): input
// items, tools, skills, and AgentParams which validates before any traffic.
#include <optional>
#include <string>
#include <vector>
#include "vendors/perplexity/types.h"
namespace molo::perplexity {
// InputItem builders.
struct AgentInput {
// role: user, assistant, system, developer
static Json message(const std::string& role, const std::string& text);
static Json message_parts(const std::string& role, const std::vector<Json>& parts);
static Json text_part(const std::string& text);
// https URL or data:image/...;base64, URL
static Json image_part(const std::string& url);
// Exactly one of file_data (base64 or data URI) and file_url (public https URL).
static Json file_part(const std::string& file_data, const std::string& file_url, const std::string& filename = "");
static Json function_call_output(const std::string& call_id, const std::string& output);
static Json function_call(const std::string& call_id, const std::string& name, const std::string& arguments);
static Json mcp_approval_response(const std::string& approval_request_id, bool approve,
const std::string& reason = "");
};
struct WebSearchToolOptions {
std::string search_type; // "", web, fast
std::optional<int> max_results; // 1..50
std::optional<int> max_tokens, max_tokens_per_page;
std::vector<std::string> search_domain_filter; // max 20
std::string search_recency_filter; // hour..year
std::string country; // user_location.country
};
// Tool builders (the `tools` array).
struct AgentTools {
static Json web_search(const WebSearchToolOptions& options = {});
static Json image_search(int max_results = 0, const std::vector<std::string>& domains = {},
const std::vector<std::string>& formats = {}, std::optional<bool> safe_search = std::nullopt);
static Json finance_search();
static Json people_search();
static Json fetch_url(int max_urls = 0);
static Json sandbox();
static Json function(const std::string& name, const std::string& description, const Json& parameters,
std::optional<bool> strict = std::nullopt);
// require_approval: "", always, never
static Json mcp(const std::string& server_label, const std::string& server_url, const std::string& authorization = "",
const std::vector<std::string>& allowed_tools = {}, const std::string& require_approval = "");
static Json connector(const std::string& id, const std::string& server_label,
const std::vector<std::string>& allowed_tools = {}, const std::string& require_approval = "");
// tool_choice: none, auto, required (strings) or {"type":"image_search"} style objects.
static Json choice(const std::string& mode);
static Json choice_tool(const std::string& type);
};
// Skill builders (the `skills` array).
struct AgentSkills {
// name: office, office/docx, office/pdf, office/pptx, office/xlsx
static Json builtin(const std::string& name);
static Json inline_skill(const std::string& name, const std::string& description, const std::string& instructions);
static Json custom(const std::string& id, const std::string& version = "");
};
struct AgentParams {
Json input; // string or array of input items
std::string model; // provider/model
std::vector<std::string> models; // fallback chain, 1..5; takes precedence over model
std::string effort; // name, name@latest, name@<version>
std::string profile_id, profile_version; // saved profile (cannot be combined with effort)
std::string instructions;
std::string language_preference; // ISO 639-1
std::optional<int> max_output_tokens; // required for anthropic/* models
std::optional<int> max_steps; // 1..100
std::string previous_response_id;
std::string reasoning_effort; // minimal, low, medium, high, xhigh, max
Json response_format; // null: omit; use AgentParams::json_schema
std::optional<bool> store, background;
std::vector<Json> tools;
Json tool_choice; // null: omit
std::vector<Json> skills; // max 16
std::optional<double> temperature, top_p;
static AgentParams prompt(const std::string& text, const std::string& model);
static AgentParams with_effort(const std::string& text, const std::string& effort);
static Json json_schema(const std::string& name, const Json& schema, bool strict = true,
const std::string& description = "");
void validate() const;
Json to_json(bool stream = false) const;
};
} // namespace molo::perplexity
+228
View File
@@ -0,0 +1,228 @@
#include "vendors/perplexity/agent_result.h"
#include "vendors/perplexity/caps.h"
namespace molo::perplexity {
AgentUsage AgentUsage::parse(const Json* usage) {
AgentUsage u;
if (!usage || !usage->is_object()) return u;
u.present = true;
u.input_tokens = J::num(*usage, "input_tokens");
u.output_tokens = J::num(*usage, "output_tokens");
u.total_tokens = J::num(*usage, "total_tokens");
if (const Json* d = J::obj(*usage, "input_tokens_details")) u.cached_tokens = J::num(*d, "cached_tokens");
if (const Json* d = J::obj(*usage, "output_tokens_details")) u.reasoning_tokens = J::num(*d, "reasoning_tokens");
if (const Json* c = J::obj(*usage, "cost")) {
u.cost.input = J::dbl(*c, "input_cost");
u.cost.output = J::dbl(*c, "output_cost");
u.cost.tool_calls = J::dbl(*c, "tool_calls_cost");
u.cost.cache_creation = J::dbl(*c, "cache_creation_cost");
u.cost.cache_read = J::dbl(*c, "cache_read_cost");
u.cost.total = J::dbl(*c, "total_cost");
u.cost.currency = J::str(*c, "currency");
}
return u;
}
bool AgentFunctionCall::arguments_valid() const {
try {
return Json::parse(arguments).is_object();
} catch (const std::exception&) {
return false;
}
}
Json AgentFunctionCall::parsed() const { return Json::parse(arguments); }
AgentResult AgentResult::parse(const Json& doc) {
AgentResult r;
r.raw = doc;
r.id = J::str(doc, "id");
r.object = J::str(doc, "object");
r.status = J::str(doc, "status");
r.model = J::str(doc, "model");
r.effort = J::str(doc, "effort");
r.created_at = J::num(doc, "created_at");
if (const Json* e = J::obj(doc, "error")) {
r.error.type = J::str(*e, "type");
r.error.code = J::str(*e, "code");
r.error.message = J::str(*e, "message");
}
if (const Json* o = J::arr(doc, "output"))
for (const Json& item : o->as_array()) {
if (r.output.size() >= PerplexityCaps::kMaxItemsReturned) {
r.truncated = true;
break;
}
r.output.push_back(item);
}
r.usage = AgentUsage::parse(J::obj(doc, "usage"));
if (const Json* p = J::obj(doc, "paused")) {
r.has_pause = true;
r.pause.reason = J::str(*p, "reason");
r.pause.window = J::str(*p, "window");
r.pause.estimated_resume_at = J::num(*p, "estimated_resume_at");
}
return r;
}
bool AgentResult::finished() const {
return status == "completed" || status == "failed" || status == "incomplete" || status == "cancelled";
}
std::vector<Json> AgentResult::items_of_type(const std::string& type) const {
std::vector<Json> out;
for (const Json& i : output)
if (J::str(i, "type") == type) out.push_back(i);
return out;
}
std::string AgentResult::output_text() const {
std::string out;
for (const Json& i : output) {
if (J::str(i, "type") != "message") continue;
if (const Json* c = J::arr(i, "content"))
for (const Json& part : c->as_array())
if (J::str(part, "type") == "output_text") out += J::str(part, "text");
}
return out;
}
std::vector<AgentCitation> AgentResult::citations() const {
std::vector<AgentCitation> out;
for (const Json& i : output) {
if (J::str(i, "type") != "message") continue;
if (const Json* c = J::arr(i, "content"))
for (const Json& part : c->as_array())
if (const Json* an = J::arr(part, "annotations"))
for (const Json& a : an->as_array()) {
AgentCitation ct;
ct.url = J::str(a, "url");
ct.title = J::str(a, "title");
ct.start_index = J::num(a, "start_index");
ct.end_index = J::num(a, "end_index");
out.push_back(ct);
}
}
return out;
}
namespace {
AgentSearchResult search_result_of(const Json& r) {
AgentSearchResult s;
s.id = J::num(r, "id");
s.url = J::str(r, "url");
s.title = J::str(r, "title");
s.snippet = J::str(r, "snippet");
s.date = J::str(r, "date");
s.last_updated = J::str(r, "last_updated");
s.source = J::str(r, "source");
return s;
}
} // namespace
std::vector<AgentSearchResult> AgentResult::search_results() const {
std::vector<AgentSearchResult> out;
for (const Json& i : output) {
if (J::str(i, "type") != "search_results") continue;
if (const Json* rs = J::arr(i, "results"))
for (const Json& r : rs->as_array()) out.push_back(search_result_of(r));
}
return out;
}
std::vector<std::string> AgentResult::queries() const {
std::vector<std::string> out;
for (const Json& i : output)
for (const std::string& q : J::strings(i, "queries")) out.push_back(q);
return out;
}
std::vector<AgentFunctionCall> AgentResult::function_calls() const {
std::vector<AgentFunctionCall> out;
for (const Json& i : output) {
if (J::str(i, "type") != "function_call") continue;
AgentFunctionCall c;
c.id = J::str(i, "id");
c.call_id = J::str(i, "call_id");
c.name = J::str(i, "name");
c.arguments = J::str(i, "arguments");
out.push_back(c);
}
return out;
}
std::vector<Json> AgentResult::approval_requests() const { return items_of_type("mcp_approval_request"); }
AgentFileList AgentFileList::parse(const Json& doc) {
AgentFileList l;
if (const Json* d = J::arr(doc, "data"))
for (const Json& f : d->as_array()) {
if (l.files.size() >= PerplexityCaps::kMaxItemsReturned) {
l.truncated = true;
break;
}
AgentFile af;
af.id = J::str(f, "id");
af.filename = J::str(f, "filename");
af.bytes = J::num(f, "bytes");
af.created_at = J::num(f, "created_at");
l.files.push_back(af);
}
return l;
}
AgentDelta AgentStreamFolder::feed(const llm::SseEvent& event) {
++events_;
AgentDelta d;
const Json& data = event.data;
d.type = J::str(data, "type");
if (d.type.empty()) d.type = event.event;
long seq = J::num(data, "sequence_number", -1);
if (seq > last_sequence_) last_sequence_ = seq;
if (d.type == "response.created" || d.type == "response.in_progress") {
if (const Json* r = J::obj(data, "response")) started_ = AgentResult::parse(*r);
} else if (d.type == "response.output_text.delta") {
d.text = J::str(data, "delta");
text_ += d.text;
} else if (d.type == "response.output_item.done") {
if (const Json* it = J::obj(data, "item")) items_.push_back(*it);
} else if (d.type.rfind("response.reasoning.", 0) == 0) {
d.thought = J::str(data, "thought");
d.queries = J::strings(data, "queries");
if (const Json* rs = J::arr(data, "results"))
for (const Json& r : rs->as_array()) d.results.push_back(search_result_of(r));
} else if (d.type == "response.paused") {
d.paused = true;
} else if (d.type == "response.completed") {
if (const Json* r = J::obj(data, "response")) {
final_ = AgentResult::parse(*r);
have_final_ = true;
}
d.terminal = true;
done_ = true;
} else if (d.type == "response.failed") {
AgentResult f = started_;
f.status = "failed";
if (const Json* e = J::obj(data, "error")) {
f.error.type = J::str(*e, "type");
f.error.code = J::str(*e, "code");
f.error.message = J::str(*e, "message");
}
final_ = f;
have_final_ = true;
d.terminal = true;
done_ = true;
}
return d;
}
AgentResult AgentStreamFolder::result() const {
if (have_final_) return final_;
AgentResult r = started_;
if (r.output.empty()) r.output = items_;
return r;
}
} // namespace molo::perplexity
+121
View File
@@ -0,0 +1,121 @@
#pragma once
// Response side of the Agent API: ResponsesResponse (output items, usage,
// cost), typed accessors over the output items, and the SSE event folder.
#include <string>
#include <vector>
#include "llm/sse.h"
#include "vendors/perplexity/types.h"
namespace molo::perplexity {
struct AgentCost {
double input = 0, output = 0, tool_calls = 0, cache_creation = 0, cache_read = 0, total = 0;
std::string currency;
};
struct AgentUsage {
long input_tokens = 0, output_tokens = 0, total_tokens = 0, cached_tokens = 0, reasoning_tokens = 0;
AgentCost cost;
bool present = false;
static AgentUsage parse(const Json* usage);
};
struct AgentError {
std::string type, code, message;
bool present() const { return !message.empty() || !type.empty() || !code.empty(); }
};
struct AgentSearchResult { // SearchResult: numeric id, [n] markers in the text map to it
long id = 0;
std::string url, title, snippet, date, last_updated, source;
};
struct AgentFunctionCall {
std::string id, call_id, name, arguments;
bool arguments_valid() const;
Json parsed() const;
};
struct AgentCitation {
std::string url, title;
long start_index = 0, end_index = 0;
};
struct AgentFile { // ResponseFile
std::string id, filename;
long bytes = 0, created_at = 0;
};
struct AgentPause { // present while token limits pause a background run
std::string reason, window;
long estimated_resume_at = 0;
};
struct AgentResult {
std::string id, object, status, model, effort;
long created_at = 0;
AgentError error;
std::vector<Json> output; // OutputItem documents, as sent
AgentUsage usage;
bool has_pause = false;
AgentPause pause;
bool truncated = false;
Json raw;
static AgentResult parse(const Json& doc);
// queued / in_progress: poll again. completed / failed / incomplete / cancelled: final.
bool finished() const;
bool succeeded() const { return status == "completed"; }
std::string output_text() const; // all assistant message text
std::vector<AgentCitation> citations() const; // url_citation annotations
std::vector<AgentSearchResult> search_results() const; // every search_results item, one id space
std::vector<std::string> queries() const; // search queries across items
std::vector<AgentFunctionCall> function_calls() const;
std::vector<Json> items_of_type(const std::string& type) const;
// Pending mcp_approval_request items (answer with AgentInput::mcp_approval_response).
std::vector<Json> approval_requests() const;
};
struct AgentFileList {
std::vector<AgentFile> files;
bool truncated = false;
static AgentFileList parse(const Json& doc);
};
// One decoded stream event, reduced to what a consumer needs.
struct AgentDelta {
std::string type; // response.output_text.delta, response.reasoning.started, ...
std::string text; // output_text.delta text
std::string thought; // reasoning.* thought
std::vector<std::string> queries;
std::vector<AgentSearchResult> results;
bool terminal = false; // response.completed / response.failed
bool paused = false; // response.paused (does not end the stream)
};
class AgentStreamFolder {
public:
AgentDelta feed(const llm::SseEvent& event);
bool done() const { return done_; }
std::size_t events() const { return events_; }
const std::string& text() const { return text_; }
// The final response when response.completed carried one, else a result built from the deltas.
AgentResult result() const;
// Highest sequence_number seen (reconnect cursor).
long last_sequence() const { return last_sequence_; }
private:
AgentResult final_;
bool have_final_ = false;
AgentResult started_;
std::string text_;
std::vector<Json> items_;
bool done_ = false;
std::size_t events_ = 0;
long last_sequence_ = -1;
};
} // namespace molo::perplexity
+209
View File
@@ -0,0 +1,209 @@
#include "vendors/perplexity/batches.h"
#include "clients/body/form.h"
#include "vendors/perplexity/calls.h"
#include "vendors/perplexity/caps.h"
#include "vendors/perplexity/rules.h"
namespace molo::perplexity {
BatchFileInfo BatchFileInfo::parse(const Json& doc) {
BatchFileInfo f;
f.id = J::str(doc, "id");
f.filename = J::str(doc, "filename");
f.purpose = J::str(doc, "purpose");
f.bytes = J::num(doc, "bytes");
f.created_at = J::num(doc, "created_at");
f.expires_at = J::num(doc, "expires_at");
f.deleted = J::flag(doc, "deleted");
return f;
}
BatchInfo BatchInfo::parse(const Json& doc) {
BatchInfo b;
b.raw = doc;
b.id = J::str(doc, "id");
b.endpoint = J::str(doc, "endpoint");
b.input_file_id = J::str(doc, "input_file_id");
b.output_file_id = J::str(doc, "output_file_id");
b.error_file_id = J::str(doc, "error_file_id");
b.completion_window = J::str(doc, "completion_window");
b.status = J::str(doc, "status");
b.created_at = J::num(doc, "created_at");
b.in_progress_at = J::num(doc, "in_progress_at");
b.expires_at = J::num(doc, "expires_at");
b.finalizing_at = J::num(doc, "finalizing_at");
b.completed_at = J::num(doc, "completed_at");
b.failed_at = J::num(doc, "failed_at");
b.expired_at = J::num(doc, "expired_at");
b.cancelling_at = J::num(doc, "cancelling_at");
b.cancelled_at = J::num(doc, "cancelled_at");
if (const Json* c = J::obj(doc, "request_counts")) {
b.total = J::num(*c, "total");
b.completed = J::num(*c, "completed");
b.failed = J::num(*c, "failed");
}
if (const Json* u = J::obj(doc, "usage")) {
b.input_tokens = J::num(*u, "input_tokens");
b.output_tokens = J::num(*u, "output_tokens");
b.total_tokens = J::num(*u, "total_tokens");
}
if (const Json* e = J::obj(doc, "errors"))
if (const Json* d = J::arr(*e, "data"))
for (const Json& x : d->as_array()) {
if (b.errors.size() >= PerplexityCaps::kMaxItemsReturned) break;
b.errors.push_back({J::str(x, "code"), J::str(x, "message"), J::num(x, "line")});
}
if (const Json* m = J::obj(doc, "metadata"))
for (const auto& [k, v] : m->as_object())
if (v.is_string()) b.metadata[k] = v.as_string();
return b;
}
bool BatchInfo::finished() const {
return status == "completed" || status == "expired" || status == "cancelled" || status == "failed";
}
void BatchInput::validate() const {
Rules::filename(filename);
Rules::require(!jsonl.empty(), "the batch input is empty");
Rules::require(jsonl.size() <= PerplexityCaps::kBatchFileBytes, "batch input over 200 MB");
std::size_t lines = 0, pos = 0;
while (pos < jsonl.size()) {
std::size_t end = jsonl.find('\n', pos);
if (end == std::string::npos) end = jsonl.size();
std::string line = jsonl.substr(pos, end - pos);
pos = end + 1;
if (line.find_first_not_of(" \t\r") == std::string::npos) continue;
++lines;
Rules::require(lines <= PerplexityCaps::kBatchFileLines, "batch input over 50,000 lines");
try {
Rules::require(Json::parse(line).is_object(), "line " + std::to_string(lines) + " is not a JSON object");
} catch (const clients::body::JsonError&) {
Rules::fail("line " + std::to_string(lines) + " is not valid JSON");
}
}
Rules::require(lines > 0, "the batch input has no request lines");
}
namespace {
std::string page_query(int limit, const std::string& after) {
std::string q;
if (limit) {
Rules::require(limit >= 1 && limit <= PerplexityCaps::kPageLimitMax, "limit must be 1..100");
Rules::add_query(q, "limit", std::to_string(limit));
}
if (!after.empty()) {
Rules::require(llm::Service::valid_id(after), "bad after cursor");
Rules::add_query(q, "after", after);
}
return q;
}
} // namespace
BatchFileInfo BatchFiles::upload(const BatchInput& input) {
input.validate();
clients::body::MultipartBody form;
form.add_text("purpose", "batch");
form.add_file("file", input.filename, "application/jsonl", input.jsonl);
return BatchFileInfo::parse(client_->post_multipart(Calls::render(Call::kFileCreate), form));
}
BatchFileList BatchFiles::list(int limit, const std::string& after, const std::string& order,
const std::string& purpose) {
std::string q = page_query(limit, after);
if (!order.empty()) {
Rules::one_of(order, {"asc", "desc"}, "order");
Rules::add_query(q, "order", order);
}
if (!purpose.empty()) {
Rules::one_of(purpose, {"batch", "batch_output"}, "purpose");
Rules::add_query(q, "purpose", purpose);
}
Json doc = client_->get(Calls::render(Call::kFileList) + q);
BatchFileList l;
l.first_id = J::str(doc, "first_id");
l.last_id = J::str(doc, "last_id");
l.has_more = J::flag(doc, "has_more");
if (const Json* d = J::arr(doc, "data"))
for (const Json& f : d->as_array()) {
if (l.files.size() >= PerplexityCaps::kMaxItemsReturned) {
l.truncated = true;
break;
}
l.files.push_back(BatchFileInfo::parse(f));
}
return l;
}
BatchFileInfo BatchFiles::get(const std::string& file_id) {
check_id("file", file_id);
return BatchFileInfo::parse(client_->get(Calls::render(Call::kFileGet, file_id)));
}
BatchFileInfo BatchFiles::remove(const std::string& file_id) {
check_id("file", file_id);
return BatchFileInfo::parse(client_->del(Calls::render(Call::kFileDelete, file_id)));
}
std::string BatchFiles::content(const std::string& file_id) {
check_id("file", file_id);
return client_->request_raw(Calls::method_of(Call::kFileContent), Calls::render(Call::kFileContent, file_id)).body;
}
BatchInfo Batches::create(const std::string& input_file_id, const std::map<std::string, std::string>& metadata,
const std::string& idempotency_key) {
check_id("input file", input_file_id);
Json body = Json::object();
body.set("input_file_id", Json(input_file_id));
body.set("endpoint", Json("/v1/responses"));
body.set("completion_window", Json("24h"));
if (!metadata.empty()) {
Rules::require(metadata.size() <= PerplexityCaps::kBatchMetadataPairs, "at most 16 metadata pairs");
Json m = Json::object();
for (const auto& [k, v] : metadata) {
Rules::require(!k.empty() && k.size() <= PerplexityCaps::kBatchMetadataKey, "metadata keys are 1..64 characters");
Rules::require(v.size() <= PerplexityCaps::kBatchMetadataValue, "metadata values are at most 512 characters");
m.set(k, Json(v));
}
body.set("metadata", m);
}
llm::Headers extra;
if (!idempotency_key.empty()) {
Rules::require(idempotency_key.size() <= PerplexityCaps::kIdempotencyKey, "Idempotency-Key over 200 characters");
for (char c : idempotency_key)
Rules::require(static_cast<unsigned char>(c) > 0x20 && c != 0x7f, "Idempotency-Key has invalid characters");
extra["Idempotency-Key"] = idempotency_key;
}
return BatchInfo::parse(client_->post(Calls::render(Call::kBatchCreate), body, extra));
}
BatchList Batches::list(int limit, const std::string& after) {
Json doc = client_->get(Calls::render(Call::kBatchList) + page_query(limit, after));
BatchList l;
l.first_id = J::str(doc, "first_id");
l.last_id = J::str(doc, "last_id");
l.has_more = J::flag(doc, "has_more");
if (const Json* d = J::arr(doc, "data"))
for (const Json& b : d->as_array()) {
if (l.batches.size() >= PerplexityCaps::kMaxItemsReturned) {
l.truncated = true;
break;
}
l.batches.push_back(BatchInfo::parse(b));
}
return l;
}
BatchInfo Batches::get(const std::string& batch_id) {
check_id("batch", batch_id);
return BatchInfo::parse(client_->get(Calls::render(Call::kBatchGet, batch_id)));
}
BatchInfo Batches::cancel(const std::string& batch_id) {
check_id("batch", batch_id);
Json empty = Json::object();
return BatchInfo::parse(client_->post(Calls::render(Call::kBatchCancel, batch_id), empty));
}
} // namespace molo::perplexity
+90
View File
@@ -0,0 +1,90 @@
#pragma once
// Batch API for the Agent API: upload a JSONL file (purpose=batch), create a
// batch against /v1/responses, poll it, download the output / error files.
// 24h completion window is the only value. Batches and files are separate
// services because the files also carry the output and error files.
#include <map>
#include <string>
#include <vector>
#include "llm/api_client.h"
#include "vendors/perplexity/types.h"
namespace molo::perplexity {
struct BatchFileInfo {
std::string id, filename, purpose; // purpose: batch | batch_output
long bytes = 0, created_at = 0, expires_at = 0;
bool deleted = false; // only set by remove()
static BatchFileInfo parse(const Json& doc);
};
struct BatchFileList {
std::vector<BatchFileInfo> files;
std::string first_id, last_id;
bool has_more = false;
bool truncated = false; // a walk cap stopped the listing
};
struct BatchInfo {
std::string id, endpoint, input_file_id, output_file_id, error_file_id, completion_window, status;
long created_at = 0, in_progress_at = 0, expires_at = 0, finalizing_at = 0, completed_at = 0, failed_at = 0,
expired_at = 0, cancelling_at = 0, cancelled_at = 0;
long total = 0, completed = 0, failed = 0; // request_counts
long input_tokens = 0, output_tokens = 0, total_tokens = 0;
struct Error {
std::string code, message;
long line = 0;
};
std::vector<Error> errors;
std::map<std::string, std::string> metadata;
Json raw;
static BatchInfo parse(const Json& doc);
// validating, in_progress, finalizing, cancelling are active; the rest are final.
bool finished() const;
};
struct BatchList {
std::vector<BatchInfo> batches;
std::string first_id, last_id;
bool has_more = false;
bool truncated = false;
};
// One request line of a batch input file: {"custom_id", "method", "url", "body"}
// is the OpenAI-compatible shape; the exact line schema is not in the OpenAPI
// document (see SPEC Unverified), so lines are only checked to be JSON objects.
struct BatchInput {
std::string filename = "batch.jsonl";
std::string jsonl;
void validate() const; // <= 200 MB, <= 50,000 lines, each line a JSON object
};
class BatchFiles : public llm::Service {
public:
explicit BatchFiles(std::shared_ptr<llm::ApiClient> client) : llm::Service(std::move(client)) {}
BatchFileInfo upload(const BatchInput& input);
// order: "", asc, desc; purpose: "", batch, batch_output; after: cursor id.
BatchFileList list(int limit = 0, const std::string& after = "", const std::string& order = "",
const std::string& purpose = "");
BatchFileInfo get(const std::string& file_id);
// Destructive, no default. Batches already created from the file are not affected.
BatchFileInfo remove(const std::string& file_id);
std::string content(const std::string& file_id);
};
class Batches : public llm::Service {
public:
explicit Batches(std::shared_ptr<llm::ApiClient> client) : llm::Service(std::move(client)) {}
// idempotency_key: "" omits the header (<= 200 chars). metadata: <= 16 pairs, keys <= 64, values <= 512.
BatchInfo create(const std::string& input_file_id, const std::map<std::string, std::string>& metadata = {},
const std::string& idempotency_key = "");
BatchList list(int limit = 0, const std::string& after = "");
BatchInfo get(const std::string& batch_id);
// Destructive, no default: moves the batch to cancelling.
BatchInfo cancel(const std::string& batch_id);
};
} // namespace molo::perplexity
+185
View File
@@ -0,0 +1,185 @@
#include "vendors/perplexity/calls.h"
#include <cstring>
#include "llm/api_client.h"
#include "llm/error.h"
namespace molo::perplexity {
// CALLS-BEGIN (parsed by tools/check_spec.py; one row per line, strings in order:
// http method, path, spec document, operationId, body fields, query params, response schema)
static const CallSpec kCalls[] = {
{Call::kSonar, "POST", "/v1/sonar", "openapi", "chat_completions_chat_completions_post", "max_tokens,model,stream,stop,temperature,top_p,response_format,messages,web_search_options,search_mode,return_images,return_related_questions,enable_search_classifier,disable_search,search_domain_filter,search_language_filter,search_recency_filter,search_after_date_filter,search_before_date_filter,last_updated_before_filter,last_updated_after_filter,image_format_filter,image_domain_filter,stream_mode,reasoning_effort,language_preference", "", "CompletionResponse"},
{Call::kAsyncCreate, "POST", "/v1/async/sonar", "openapi", "create_async_chat_completions_async_chat_completions_post", "request,idempotency_key", "", "AsyncApiChatCompletionsResponse"},
{Call::kAsyncList, "GET", "/v1/async/sonar", "openapi", "list_async_chat_completions_async_chat_completions_get", "", "", "ListAsyncApiChatCompletionsResponse"},
{Call::kAsyncGet, "GET", "/v1/async/sonar/{api_request}", "openapi", "get_async_chat_completion_response_async_chat_completions__api_request__get", "", "", "AsyncApiChatCompletionsResponse"},
{Call::kSearch, "POST", "/search", "openapi", "search_search_post", "query,country,max_results,search_type,max_tokens,max_tokens_per_page,search_language_filter,search_domain_filter,last_updated_after_filter,last_updated_before_filter,search_after_date_filter,search_before_date_filter,search_recency_filter", "", "ApiSearchResponse"},
{Call::kEmbeddings, "POST", "/v1/embeddings", "openapi", "embeddings_v1_embeddings_post", "input,model,dimensions,encoding_format", "", "EmbeddingsResponse"},
{Call::kContextEmbeddings, "POST", "/v1/contextualizedembeddings", "openapi", "contextualized_embeddings_v1_contextualizedembeddings_post", "input,model,dimensions,encoding_format", "", "ContextualizedEmbeddingsResponse"},
{Call::kAgentCreate, "POST", "/v1/agent", "openapi", "createAgent", "input,background,instructions,language_preference,max_output_tokens,max_steps,model,models,effort,profile,previous_response_id,reasoning,response_format,store,stream,tools,tool_choice,skills,temperature,top_p", "", "ResponsesResponse"},
{Call::kAgentGet, "GET", "/v1/agent/{id}", "openapi", "retrieveAgent", "", "", "ResponsesResponse"},
{Call::kAgentFiles, "GET", "/v1/agent/{id}/files", "openapi", "listAgentFiles", "", "", "ResponseFileList"},
{Call::kAgentFileContent, "GET", "/v1/agent/{id}/files/{file_id}/content", "openapi", "downloadAgentFile", "", "", "binary"},
{Call::kAgentCancel, "POST", "/v1/agent/{id}/cancel", "openapi", "cancelAgentResponse", "", "", "-"},
{Call::kModels, "GET", "/v1/models", "openapi", "listModels", "", "", "ListModelsResponse"},
{Call::kDecisions, "POST", "/v1/decisions", "openapi", "decisions_v1_decisions_post", "model,state,questions", "", "DecisionsResponse"},
{Call::kUsageV1, "GET", "/v1/analytics/computer/usage", "openapi", "getComputerUsageAnalytics", "", "dataset,start_time,end_time,bucket_width,limit,page,user_email", "ComputerUsageResponse"},
{Call::kUsageV2, "GET", "/v2/analytics/computer/usage", "openapi", "getComputerUsageAnalyticsV2", "", "dataset,group_by,start_time,end_time,limit,page", "ComputerUsageV2Response"},
{Call::kSkillList, "GET", "/v1/skills", "openapi", "listSkills", "", "limit,page_token", "SkillList"},
{Call::kSkillCreate, "POST", "/v1/skills", "openapi", "createSkill", "file", "", "ManagedSkill"},
{Call::kSkillGet, "GET", "/v1/skills/{skill_id}", "openapi", "getSkill", "", "revision", "ManagedSkill"},
{Call::kSkillUpdate, "PUT", "/v1/skills/{skill_id}", "openapi", "updateSkill", "file", "expected_revision", "ManagedSkill"},
{Call::kSkillDelete, "DELETE", "/v1/skills/{skill_id}", "openapi", "deleteSkill", "", "expected_revision", "-"},
{Call::kSkillRevisions, "GET", "/v1/skills/{skill_id}/revisions", "openapi", "listSkillRevisions", "", "limit,page_token", "SkillRevisionList"},
{Call::kSkillDownload, "GET", "/v1/skills/{skill_id}/download", "openapi", "downloadSkill", "", "revision", "SkillDownload"},
{Call::kBatchCreate, "POST", "/v1/batches", "openapi", "createBatch", "input_file_id,endpoint,completion_window,metadata", "", "Batch"},
{Call::kBatchList, "GET", "/v1/batches", "openapi", "listBatches", "", "limit,after", "BatchList"},
{Call::kBatchGet, "GET", "/v1/batches/{batch_id}", "openapi", "getBatch", "", "", "Batch"},
{Call::kBatchCancel, "POST", "/v1/batches/{batch_id}/cancel", "openapi", "cancelBatch", "", "", "Batch"},
{Call::kFileList, "GET", "/v1/files", "openapi", "listFiles", "", "limit,after,order,purpose", "BatchFileList"},
{Call::kFileCreate, "POST", "/v1/files", "openapi", "createFile", "file,purpose", "", "BatchFile"},
{Call::kFileGet, "GET", "/v1/files/{file_id}", "openapi", "getFile", "", "", "BatchFile"},
{Call::kFileDelete, "DELETE", "/v1/files/{file_id}", "openapi", "deleteFile", "", "", "BatchFileDeleted"},
{Call::kFileContent, "GET", "/v1/files/{file_id}/content", "openapi", "getFileContent", "", "", "binary"},
{Call::kAuthGenerate, "POST", "/generate_auth_token", "auth", "generate_auth_token", "token_name", "", "GenerateAuthTokenResponse"},
{Call::kAuthRevoke, "POST", "/revoke_auth_token", "auth", "revoke_auth_token", "auth_token", "", "-"},
{Call::kOrchChat, "POST", "/orchestrator/v1/chat/completions", "gateway-chat", "gateway_create_chat_completion", "metadata,temperature,top_p,user,safety_identifier,prompt_cache_key,service_tier,prompt_cache_retention,prompt_cache_options,messages,model,reasoning_effort,max_completion_tokens,response_format,stream,stop,max_tokens,stream_options,tools,tool_choice,parallel_tool_calls", "", "CreateChatCompletionResponse"},
{Call::kOrchMessages, "POST", "/orchestrator/v1/messages", "gateway-messages", "gateway_create_message", "model,max_tokens,messages,system,temperature,top_p,top_k,stop_sequences,stream,tools,tool_choice,metadata,thinking,service_tier,cache_control,output_config,context_management,speed", "", "-"},
{Call::kOrchResponses, "POST", "/orchestrator/v1/responses", "gateway-responses", "gateway_create_response", "model,input,include,tools,tool_choice,metadata,text,temperature,top_p,parallel_tool_calls,stream,max_output_tokens,reasoning,safety_identifier,prompt_cache_key,truncation,instructions,service_tier", "", "-"},
{Call::kOrchModels, "GET", "/orchestrator/v1/models", "gateway-chat", "gateway_list_models", "", "", "ModelList"},
{Call::kOrchModel, "GET", "/orchestrator/v1/models/{model}", "gateway-chat", "gateway_retrieve_model", "", "", "Model"},
};
// CALLS-END
// SCHEMAS-BEGIN (parsed by tools/check_spec.py; one row per line: schema, spec, fields we read)
static const SchemaFields kSchemas[] = {
{"CompletionResponse", "openapi", "id,model,created,usage,object,choices,citations,search_results,images,related_questions"},
{"Choice", "openapi", "index,finish_reason,message,delta"},
{"ChatMessage-Output", "openapi", "role,content"},
{"UsageInfo", "openapi", "prompt_tokens,completion_tokens,total_tokens,search_context_size,citation_tokens,num_search_queries,reasoning_tokens,cost"},
{"Cost", "openapi", "input_tokens_cost,output_tokens_cost,reasoning_tokens_cost,request_cost,citation_tokens_cost,search_queries_cost,total_cost"},
{"ApiPublicSearchResult", "openapi", "title,url,date,last_updated,snippet,source"},
{"ImageResult", "openapi", "image_url,origin_url,height,width,title"},
{"AsyncApiChatCompletionsResponse", "openapi", "id,model,created_at,started_at,completed_at,response,failed_at,error_message,status"},
{"AsyncApiChatCompletionsResponseSummary", "openapi", "id,created_at,started_at,completed_at,failed_at,model,status"},
{"ListAsyncApiChatCompletionsResponse", "openapi", "next_token,requests"},
{"ApiSearchResponse", "openapi", "results,id,server_time"},
{"ApiSearchPage", "openapi", "title,url,snippet,date,last_updated"},
{"EmbeddingsResponse", "openapi", "object,data,model,usage"},
{"EmbeddingObject", "openapi", "object,index,embedding"},
{"EmbeddingsUsage", "openapi", "prompt_tokens,total_tokens,cost"},
{"ContextualizedEmbeddingsResponse", "openapi", "object,data,model,usage"},
{"ContextualizedEmbeddingObject", "openapi", "object,index,data"},
{"ResponsesResponse", "openapi", "created_at,error,id,model,effort,object,output,status,usage"},
{"ErrorInfo", "openapi", "code,message,type"},
{"ResponsesUsage", "openapi", "cost,input_tokens,input_tokens_details,output_tokens,total_tokens"},
{"ResponsesCost", "openapi", "cache_creation_cost,cache_read_cost,currency,input_cost,output_cost,tool_calls_cost,total_cost"},
{"InputTokensDetails", "openapi", "cached_tokens"},
{"OutputTokensDetails", "openapi", "reasoning_tokens"},
{"MessageOutputItem", "openapi", "content,id,role,status,type"},
{"ContentPart", "openapi", "annotations,text,type"},
{"Annotation", "openapi", "end_index,start_index,title,type,url"},
{"SearchResultsOutputItem", "openapi", "queries,results,type"},
{"SearchResult", "openapi", "date,id,last_updated,snippet,source,title,url"},
{"FunctionCallOutputItem", "openapi", "arguments,call_id,id,name,status,type"},
{"ResponseFile", "openapi", "id,object,filename,bytes,created_at"},
{"ResponseFileList", "openapi", "object,data"},
{"TextDeltaEvent", "openapi", "delta,sequence_number,type"},
{"ResponseCompletedEvent", "openapi", "response,sequence_number,type"},
{"ResponseFailedEvent", "openapi", "error,sequence_number,type"},
{"ListModelsResponse", "openapi", "object,data"},
{"Model", "openapi", "id,object,created,owned_by"},
{"DecisionsResponse", "openapi", "model,answers,usage"},
{"Usage", "openapi", "input_tokens,output_tokens"},
{"ChoiceAnswer", "openapi", "type,choice,confidence,probabilities"},
{"NoulAnswer", "openapi", "type,noul"},
{"ScoreAnswer", "openapi", "type,score,confidence,legend,probabilities"},
{"ComputerUsageResponse", "openapi", "categories,data,has_more,next_page"},
{"ComputerUsageBucket", "openapi", "start_time,end_time,count,by_categories"},
{"ComputerUsageV2Response", "openapi", "categories,data,has_more,next_page"},
{"ComputerUsageV2Bucket", "openapi", "start_time,end_time,results"},
{"ComputerUsageV2Result", "openapi", "user_email,count,by_categories"},
{"SkillList", "openapi", "skills,next_page_token"},
{"SkillSummary", "openapi", "skill_id,name,revision,created_at,updated_at"},
{"ManagedSkill", "openapi", "skill_id,name,description,revision,latest_revision,created_at,updated_at"},
{"SkillRevisionList", "openapi", "revisions,next_page_token"},
{"SkillRevision", "openapi", "revision,name,created_at"},
{"SkillDownload", "openapi", "revision,name,download_url"},
{"Batch", "openapi", "id,object,endpoint,errors,input_file_id,completion_window,status,output_file_id,error_file_id,created_at,in_progress_at,expires_at,finalizing_at,completed_at,failed_at,expired_at,cancelling_at,cancelled_at,request_counts,usage,metadata"},
{"BatchList", "openapi", "object,data,first_id,last_id,has_more"},
{"BatchErrors", "openapi", "object,data"},
{"BatchError", "openapi", "code,message,line"},
{"BatchRequestCounts", "openapi", "total,completed,failed"},
{"BatchUsage", "openapi", "input_tokens,output_tokens,total_tokens"},
{"BatchFile", "openapi", "id,object,bytes,created_at,expires_at,filename,purpose"},
{"BatchFileList", "openapi", "object,data,first_id,last_id,has_more"},
{"BatchFileDeleted", "openapi", "id,object,deleted"},
{"GenerateAuthTokenResponse", "auth", "auth_token,created_at_epoch_seconds,token_name"},
{"ModelList", "gateway-chat", "object,data"},
{"Model", "gateway-chat", "id,object,created,owned_by,pricing"},
{"ModelPricing", "gateway-chat", "input,output,cache_write,cache_read,unit"},
};
// SCHEMAS-END
std::size_t Calls::schema_count() { return sizeof(kSchemas) / sizeof(kSchemas[0]); }
const SchemaFields& Calls::schema_at(std::size_t index) {
if (index >= schema_count()) throw llm::ApiError::invalid("perplexity", "schema index out of range");
return kSchemas[index];
}
const CallSpec& Calls::spec_of(Call call) {
for (const CallSpec& s : kCalls)
if (s.call == call) return s;
throw llm::ApiError::invalid("perplexity", "unknown call");
}
clients::Method Calls::method_of(Call call) {
const char* m = spec_of(call).http_method;
if (!std::strcmp(m, "GET")) return clients::Method::kGet;
if (!std::strcmp(m, "POST")) return clients::Method::kPost;
if (!std::strcmp(m, "PUT")) return clients::Method::kPut;
return clients::Method::kDelete;
}
std::size_t Calls::count() { return sizeof(kCalls) / sizeof(kCalls[0]); }
const CallSpec& Calls::at(std::size_t index) {
if (index >= count()) throw llm::ApiError::invalid("perplexity", "call index out of range");
return kCalls[index];
}
namespace {
// A segment is one valid id; a model id may be "creator/name" (two segments).
bool valid_segment_id(const std::string& id, bool allow_slash) {
if (!allow_slash) return llm::Service::valid_id(id);
std::size_t slash = id.find('/');
if (slash == std::string::npos) return llm::Service::valid_id(id);
return llm::Service::valid_id(id.substr(0, slash)) && llm::Service::valid_id(id.substr(slash + 1));
}
} // namespace
std::string Calls::render(Call call, const std::vector<std::string>& ids) {
std::string path = spec_of(call).path;
std::size_t used = 0;
for (std::size_t open = path.find('{'); open != std::string::npos; open = path.find('{')) {
std::size_t close = path.find('}', open);
if (close == std::string::npos) break;
std::string name = path.substr(open + 1, close - open - 1);
if (used >= ids.size() || !valid_segment_id(ids[used], name == "model"))
throw llm::ApiError::invalid("perplexity", "bad " + name);
path.replace(open, close - open + 1, ids[used]);
++used;
}
if (used != ids.size()) throw llm::ApiError::invalid("perplexity", "unexpected path id");
return path;
}
std::string Calls::render(Call call) { return render(call, std::vector<std::string>{}); }
std::string Calls::render(Call call, const std::string& id) {
return render(call, std::vector<std::string>{id});
}
} // namespace molo::perplexity
+68
View File
@@ -0,0 +1,68 @@
#pragma once
// The ONE table of REST calls this module makes. tools/check_spec.py checks
// every row against Perplexity's published OpenAPI documents (five of them)
// and the request-field lists against their schemas. Code builds every path
// from this table, never from a literal.
#include <cstddef>
#include <string>
#include <vector>
#include "clients/request.h"
namespace molo::perplexity {
enum class Call {
// Sonar (chat completions) and async
kSonar, kAsyncCreate, kAsyncList, kAsyncGet,
// Search and embeddings
kSearch, kEmbeddings, kContextEmbeddings,
// Agent API
kAgentCreate, kAgentGet, kAgentFiles, kAgentFileContent, kAgentCancel,
// Models, decisions, analytics
kModels, kDecisions, kUsageV1, kUsageV2,
// Skills
kSkillList, kSkillCreate, kSkillGet, kSkillUpdate, kSkillDelete, kSkillRevisions, kSkillDownload,
// Batch API (batches and the files they use)
kBatchCreate, kBatchList, kBatchGet, kBatchCancel,
kFileList, kFileCreate, kFileGet, kFileDelete, kFileContent,
// Auth tokens
kAuthGenerate, kAuthRevoke,
// Orchestrator API (OpenAI / Anthropic compatible gateway)
kOrchChat, kOrchMessages, kOrchResponses, kOrchModels, kOrchModel,
};
struct CallSpec {
Call call;
const char* http_method; // GET POST PUT DELETE
const char* path; // full path from the host, "{name}" placeholders
const char* spec; // OpenAPI document: openapi, auth, gateway-chat, gateway-messages, gateway-responses
const char* operation_id; // operationId in that document
const char* body_fields; // comma list: top-level request body fields we send
const char* query_params; // comma list: query parameters we send
const char* response; // response schema name in that document ("-" none, "binary" raw bytes)
};
// Fields of a response schema that this module reads (checked against the spec).
struct SchemaFields {
const char* schema;
const char* spec;
const char* fields; // comma list
};
struct Calls {
static std::size_t schema_count();
static const SchemaFields& schema_at(std::size_t index);
static const CallSpec& spec_of(Call call);
static clients::Method method_of(Call call);
static std::size_t count();
static const CallSpec& at(std::size_t index);
// Path with each "{name}" replaced, in order, by a validated id
// (llm::Service::valid_id; a model id may be "creator/name").
static std::string render(Call call, const std::vector<std::string>& ids);
static std::string render(Call call);
static std::string render(Call call, const std::string& id);
};
} // namespace molo::perplexity
+65
View File
@@ -0,0 +1,65 @@
#pragma once
// Static ceilings for the Perplexity module. Never autotuned. "Documented"
// numbers come from the OpenAPI documents (see SPEC.md ## Sources), "ours"
// are hard caps we add.
#include <cstddef>
namespace molo::perplexity {
struct PerplexityCaps {
// Documented limits.
static constexpr int kSearchMaxResults = 20; // web / fast search
static constexpr int kSearchMaxResultsPeople = 50; // people search only
static constexpr int kSearchMaxTokens = 1000000; // max_tokens, max_tokens_per_page
static constexpr std::size_t kSearchDomainFilter = 20;
static constexpr std::size_t kSearchLanguageFilter = 20;
static constexpr std::size_t kEmbedTexts = 512; // texts / documents per request
static constexpr int kEmbedMinDims = 128;
static constexpr int kEmbedMaxDims = 2560; // 4b models
static constexpr int kEmbedMaxDims06 = 1024; // 0.6b models
static constexpr std::size_t kAgentModels = 5; // fallback chain
static constexpr int kAgentMaxSteps = 100;
static constexpr std::size_t kAgentSkills = 16;
static constexpr int kWebToolMaxResults = 50;
static constexpr int kImageToolMaxResults = 30;
static constexpr int kFetchToolMaxUrls = 10;
static constexpr std::size_t kImageFilterEntries = 10;
static constexpr std::size_t kInlineSkillDescription = 1024;
static constexpr std::size_t kInlineSkillInstructions = 65536;
static constexpr std::size_t kInlineSkillsTotal = 262144;
static constexpr std::size_t kDecisionQuestions = 128;
static constexpr std::size_t kChoiceOptions = 255;
static constexpr std::size_t kScoreLevels = 10;
static constexpr int kPageLimitMax = 100; // batches, files lists
static constexpr int kSkillPageLimitMax = 200;
static constexpr std::size_t kBatchMetadataPairs = 16;
static constexpr std::size_t kBatchMetadataKey = 64;
static constexpr std::size_t kBatchMetadataValue = 512;
static constexpr std::size_t kIdempotencyKey = 200;
static constexpr std::size_t kBatchFileLines = 50000;
static constexpr std::size_t kBatchFileBytes = 200u * 1024u * 1024u;
// Our own caps.
static constexpr std::size_t kMaxMessages = 4096;
static constexpr std::size_t kMaxStop = 16;
static constexpr std::size_t kMaxFilterEntries = 20;
static constexpr std::size_t kMaxTools = 128;
static constexpr std::size_t kMaxInputItems = 4096;
static constexpr std::size_t kMaxStreamEvents = 200000;
static constexpr std::size_t kMaxChoices = 8;
static constexpr std::size_t kMaxPageWalk = 20; // list walks
static constexpr std::size_t kMaxItemsReturned = 5000;
static constexpr std::size_t kMaxModelsReturned = 1024;
static constexpr std::size_t kMaxQueryChars = 8192;
static constexpr std::size_t kMaxModelChars = 128;
static constexpr std::size_t kMaxUploadBytes = 200u * 1024u * 1024u;
static constexpr std::size_t kMaxSkillBundleBytes = 64u * 1024u * 1024u;
static constexpr std::size_t kMaxFilenameBytes = 255;
static constexpr int kMaxPollSeconds = 600; // helper wait ceiling
static constexpr int kMinPollIntervalSeconds = 1; // floor: tier 0 is 1 request per second
static constexpr std::size_t kMaxEmbedDecodedBytes = 64u * 1024u * 1024u;
static constexpr std::size_t kMaxGatewayFields = 64;
};
} // namespace molo::perplexity
+121
View File
@@ -0,0 +1,121 @@
#include "vendors/perplexity/chat_model.h"
#include "security/crypto/Base64.h"
#include "vendors/perplexity/platform.h"
#include "vendors/perplexity/rules.h"
namespace molo::perplexity {
PerplexityChatModel::PerplexityChatModel(std::shared_ptr<Sonar> sonar, std::string default_model)
: sonar_(std::move(sonar)), default_model_(std::move(default_model)) {}
std::shared_ptr<PerplexityChatModel> PerplexityChatModel::from_env(const std::string& default_model) {
Platform p = Platform::from_env();
return std::make_shared<PerplexityChatModel>(std::make_shared<Sonar>(p.client), default_model);
}
namespace {
Json image_part_of(const llm::ImageData& img) {
if (!img.url.empty()) return Messages::image_part(img.url);
Rules::require(!img.bytes.empty(), "image has neither url nor bytes");
Rules::require(!img.mime.empty(), "image bytes need a mime type");
return Messages::image_part("data:" + img.mime + ";base64," + security::crypto::Base64::encode(img.bytes));
}
const char* role_of(llm::Role r) {
switch (r) {
case llm::Role::kSystem: return "system";
case llm::Role::kUser: return "user";
case llm::Role::kAssistant: return "assistant";
case llm::Role::kTool: return "tool";
}
return "user";
}
void append(SonarParams& params, const llm::Message& m) {
bool has_image = false;
for (const llm::ContentPart& p : m.parts) {
Rules::require(!p.tool_call && !p.tool_result,
"Sonar has no function calling; tool-call and tool-result parts are not supported");
has_image = has_image || p.image.has_value();
}
Rules::require(m.role != llm::Role::kTool, "Sonar has no function calling; tool messages are not supported");
if (!has_image) {
params.add(Messages::make(role_of(m.role), m.text()));
return;
}
std::vector<Json> parts;
for (const llm::ContentPart& p : m.parts) {
if (!p.text.empty()) parts.push_back(Messages::text_part(p.text));
if (p.image) parts.push_back(image_part_of(*p.image));
}
params.add(Messages::with_parts(role_of(m.role), parts));
}
llm::Usage usage_of(const SonarUsage& u) {
llm::Usage out;
out.input_tokens = u.prompt_tokens;
out.output_tokens = u.completion_tokens;
out.total_tokens = u.total_tokens;
out.reasoning_tokens = u.reasoning_tokens;
return out;
}
} // namespace
SonarParams PerplexityChatModel::to_params(const llm::ChatRequest& r) const {
Rules::require(r.tools.empty() && r.tool_choice.empty(),
"Sonar has no function calling; use the Agent API for tools");
Rules::require(!r.json_mode, "json_mode is not supported by Sonar; use response_schema");
SonarParams p;
p.model = r.model.empty() ? default_model_ : r.model;
if (!r.system.empty()) p.add(Messages::system(r.system));
for (const llm::Message& m : r.messages) append(p, m);
p.max_tokens = r.max_tokens;
p.temperature = r.temperature;
p.top_p = r.top_p;
p.stop = r.stop;
p.reasoning_effort = r.reasoning_effort;
if (!r.response_schema.is_null()) p.response_format = StructuredOutput::json_schema(r.response_schema);
if (r.extra.is_object()) p.extra = r.extra;
return p;
}
llm::ChatResponse PerplexityChatModel::to_response(const SonarResult& result) {
const SonarChoice& c = result.first();
llm::ChatResponse out;
out.id = result.id;
out.model = result.model;
out.message.role = llm::Role::kAssistant;
out.message.parts.push_back(llm::ContentPart::of_text(c.content));
out.finish_reason = c.finish_reason;
out.usage = usage_of(result.usage);
out.raw = result.raw;
return out;
}
llm::ChatResponse PerplexityChatModel::generate(const llm::ChatRequest& request) {
return to_response(sonar_->create(to_params(request)));
}
void PerplexityChatModel::stream(const llm::ChatRequest& request,
const std::function<bool(const llm::ChatChunk&)>& on_chunk) {
SonarParams params = to_params(request);
sonar_->stream(params, [&](const SonarDelta& d) {
if (!d.content.empty()) {
llm::ChatChunk c;
c.text_delta = d.content;
if (!on_chunk(c)) return false;
}
if (!d.finish_reason.empty() || d.has_usage) {
llm::ChatChunk c;
c.finish_reason = d.finish_reason;
if (d.has_usage) c.usage = usage_of(d.usage);
return on_chunk(c);
}
return true;
});
}
} // namespace molo::perplexity
+48
View File
@@ -0,0 +1,48 @@
#pragma once
// PerplexityChatModel: the llm::ChatModel seam over Sonar chat completions.
//
// Mapping notes (each one is a decision, not a guess):
// - ChatRequest.system becomes a leading system message.
// - Images become image_url parts (https or data: URLs; raw bytes are
// base64 encoded into a data URL).
// - Sonar has no function calling in its schema: ChatRequest.tools,
// tool_choice and tool-call / tool-result parts are rejected loudly (use
// the Agent API for tools).
// - json_mode is rejected (Sonar only has json_schema); response_schema maps
// to response_format json_schema.
// - reasoning_effort goes to reasoning_effort (minimal, low, medium, high).
// - ChatRequest.extra may carry Sonar fields (search_mode,
// search_domain_filter, web_search_options, ...); unknown names are rejected.
// - finish_reason passes through (stop, length). Citations, search results,
// images and related questions stay in ChatResponse.raw.
// - Usage: prompt_tokens -> input, completion_tokens -> output,
// reasoning_tokens -> reasoning; cached_tokens is not reported by Sonar.
#include <memory>
#include "llm/chat_types.h"
#include "vendors/perplexity/sonar.h"
namespace molo::perplexity {
class PerplexityChatModel : public llm::ChatModel {
public:
explicit PerplexityChatModel(std::shared_ptr<Sonar> sonar, std::string default_model = "sonar");
static std::shared_ptr<PerplexityChatModel> from_env(const std::string& default_model = "sonar");
std::string vendor() const override { return "perplexity"; }
llm::ChatResponse generate(const llm::ChatRequest& request) override;
void stream(const llm::ChatRequest& request,
const std::function<bool(const llm::ChatChunk&)>& on_chunk) override;
// The wire parameters a neutral request maps to (also used by tests).
SonarParams to_params(const llm::ChatRequest& request) const;
static llm::ChatResponse to_response(const SonarResult& result);
private:
std::shared_ptr<Sonar> sonar_;
std::string default_model_;
};
} // namespace molo::perplexity
+102
View File
@@ -0,0 +1,102 @@
#include "vendors/perplexity/decisions.h"
#include "vendors/perplexity/calls.h"
#include "vendors/perplexity/caps.h"
#include "vendors/perplexity/rules.h"
namespace molo::perplexity {
Json DecisionQuestions::noul(const std::string& instructions, const std::string& yes, const std::string& no) {
Rules::require(!instructions.empty() || !yes.empty() || !no.empty(), "a noul question needs instructions or criteria");
Json q = Json::object();
q.set("type", Json("noul"));
if (!instructions.empty()) q.set("instructions", Json(instructions));
if (!yes.empty() || !no.empty()) {
Json c = Json::object();
if (!yes.empty()) c.set("true", Json(yes));
if (!no.empty()) c.set("false", Json(no));
q.set("criteria", c);
}
return q;
}
Json DecisionQuestions::choice(const std::map<std::string, std::string>& options, const std::string& instructions) {
Rules::require(!options.empty() && options.size() <= PerplexityCaps::kChoiceOptions, "a choice question needs 1..255 options");
Json c = Json::object();
for (const auto& [name, desc] : options) {
Rules::require(!name.empty(), "option names must not be empty");
c.set(name, desc.empty() ? Json(nullptr) : Json(desc));
}
Json q = Json::object();
q.set("type", Json("choice"));
q.set("criteria", c);
if (!instructions.empty()) q.set("instructions", Json(instructions));
return q;
}
Json DecisionQuestions::score(const std::vector<std::string>& levels, const std::string& instructions) {
Rules::require(!levels.empty() && levels.size() <= PerplexityCaps::kScoreLevels, "a score question needs 1..10 levels");
Json a = Json::array();
for (const std::string& l : levels) a.push(Json(l));
Json q = Json::object();
q.set("type", Json("score"));
q.set("criteria", a);
if (!instructions.empty()) q.set("instructions", Json(instructions));
return q;
}
void DecisionsParams::validate() const {
Rules::model(model);
Rules::require(state.is_string() || state.is_object() || state.is_array(), "state must be a string, object or array");
if (state.is_string()) Rules::require(!state.as_string().empty(), "state must not be empty");
Rules::require(!questions.empty() && questions.size() <= PerplexityCaps::kDecisionQuestions, "1..128 questions are required");
for (const auto& [name, q] : questions) {
Rules::require(!name.empty() && name.size() <= 256, "question names must be 1..256 characters");
Rules::require(q.is_object(), "a question must be an object");
Rules::one_of(J::str(q, "type"), {"noul", "choice", "score"}, "question type");
}
}
Json DecisionsParams::to_json() const {
validate();
Json b = Json::object();
b.set("model", Json(model));
b.set("state", state);
Json qs = Json::object();
for (const auto& [name, q] : questions) qs.set(name, q);
b.set("questions", qs);
return b;
}
DecisionsResult DecisionsResult::parse(const Json& doc) {
DecisionsResult r;
r.raw = doc;
r.model = J::str(doc, "model");
if (const Json* a = J::obj(doc, "answers"))
for (const auto& [name, ans] : a->as_object()) {
DecisionAnswer d;
d.type = J::str(ans, "type");
d.noul = J::dbl(ans, "noul");
d.choice = J::str(ans, "choice");
d.score = J::dbl(ans, "score");
d.confidence = J::dbl(ans, "confidence");
if (const Json* p = J::obj(ans, "probabilities"))
for (const auto& [k, v] : p->as_object())
if (v.is_number()) d.probabilities[k] = v.as_number();
if (const Json* l = J::obj(ans, "legend"))
for (const auto& [k, v] : l->as_object())
if (v.is_string()) d.legend[k] = v.as_string();
r.answers[name] = std::move(d);
}
if (const Json* u = J::obj(doc, "usage")) {
r.input_tokens = J::num(*u, "input_tokens");
r.output_tokens = J::num(*u, "output_tokens");
}
return r;
}
DecisionsResult Decisions::answer(const DecisionsParams& params) {
return DecisionsResult::parse(client_->post(Calls::render(Call::kDecisions), params.to_json()));
}
} // namespace molo::perplexity
+57
View File
@@ -0,0 +1,57 @@
#pragma once
// Decisions API: POST /v1/decisions answers named questions about `state`
// with probabilities (noul: yes/no, choice: one of options, score: ordered
// levels) instead of text.
#include <map>
#include <string>
#include <vector>
#include "llm/api_client.h"
#include "vendors/perplexity/types.h"
namespace molo::perplexity {
struct DecisionQuestions {
// noul: needs instructions and/or criteria (yes/no definitions; "" omits).
static Json noul(const std::string& instructions, const std::string& yes = "", const std::string& no = "");
// choice: option name -> description of when it applies ("" sends null).
static Json choice(const std::map<std::string, std::string>& options, const std::string& instructions = "");
// score: ordered level descriptions; the index is the level's score from 0.
static Json score(const std::vector<std::string>& levels, const std::string& instructions = "");
};
struct DecisionsParams {
std::string model = "pplx-decider-flash-latest"; // pplx-decider(-flash)-v1.2 or the -latest aliases
Json state; // string, object or array: the content to judge
std::map<std::string, Json> questions; // 1..128
void validate() const;
Json to_json() const;
};
struct DecisionAnswer {
std::string type; // noul | choice | score
double noul = 0; // probability of yes
std::string choice;
double score = 0;
double confidence = 0;
std::map<std::string, double> probabilities;
std::map<std::string, std::string> legend; // score: level index -> criteria entry text
};
struct DecisionsResult {
std::string model;
std::map<std::string, DecisionAnswer> answers;
long input_tokens = 0, output_tokens = 0;
Json raw;
static DecisionsResult parse(const Json& doc);
};
class Decisions : public llm::Service {
public:
explicit Decisions(std::shared_ptr<llm::ApiClient> client) : llm::Service(std::move(client)) {}
DecisionsResult answer(const DecisionsParams& params);
};
} // namespace molo::perplexity
+164
View File
@@ -0,0 +1,164 @@
#include "vendors/perplexity/embeddings.h"
#include <cmath>
#include "security/crypto/Base64.h"
#include "vendors/perplexity/calls.h"
#include "vendors/perplexity/caps.h"
#include "vendors/perplexity/rules.h"
namespace molo::perplexity {
namespace {
void check_common(const std::string& model, bool context, int dimensions, const std::string& format) {
if (context) {
Rules::require(EmbedModels::is_context(model), "model must be pplx-embed-context-v1-0.6b or pplx-embed-context-v1-4b");
} else {
Rules::require(EmbedModels::is_standard(model), "model must be pplx-embed-v1-0.6b or pplx-embed-v1-4b");
}
if (dimensions != 0) {
int ceiling = EmbedModels::is_small(model) ? PerplexityCaps::kEmbedMaxDims06 : PerplexityCaps::kEmbedMaxDims;
Rules::require(dimensions >= PerplexityCaps::kEmbedMinDims && dimensions <= ceiling,
"dimensions must be 128..1024 (0.6b) or 128..2560 (4b)");
}
if (!format.empty()) Rules::one_of(format, {"base64_int8", "base64_binary"}, "encoding_format");
}
void set_common(Json& b, const std::string& model, int dimensions, const std::string& format) {
b.set("model", Json(model));
if (dimensions) b.set("dimensions", Json(dimensions));
if (!format.empty()) b.set("encoding_format", Json(format));
}
} // namespace
void EmbedParams::validate() const {
check_common(model, false, dimensions, encoding_format);
Rules::require(!input.empty() && input.size() <= PerplexityCaps::kEmbedTexts, "input needs 1..512 texts");
for (const std::string& t : input) Rules::require(!t.empty(), "texts must not be empty");
}
Json EmbedParams::to_json() const {
validate();
Json b = Json::object();
if (input.size() == 1) {
b.set("input", Json(input[0]));
} else {
Json a = Json::array();
for (const std::string& t : input) a.push(Json(t));
b.set("input", a);
}
set_common(b, model, dimensions, encoding_format);
return b;
}
void ContextEmbedParams::validate() const {
check_common(model, true, dimensions, encoding_format);
Rules::require(!input.empty() && input.size() <= PerplexityCaps::kEmbedTexts, "input needs 1..512 documents");
for (const auto& doc : input) {
Rules::require(!doc.empty(), "a document needs at least one chunk");
for (const std::string& c : doc) Rules::require(!c.empty(), "chunks must not be empty");
}
}
Json ContextEmbedParams::to_json() const {
validate();
Json b = Json::object();
Json docs = Json::array();
for (const auto& d : input) {
Json chunks = Json::array();
for (const std::string& c : d) chunks.push(Json(c));
docs.push(chunks);
}
b.set("input", docs);
set_common(b, model, dimensions, encoding_format);
return b;
}
std::string Vector::bytes() const {
std::string out;
if (!security::crypto::Base64::decode(base64, out)) return "";
if (out.size() > PerplexityCaps::kMaxEmbedDecodedBytes) return "";
return out;
}
bool Vector::decodable() const {
std::string out;
return !base64.empty() && security::crypto::Base64::decode(base64, out);
}
std::vector<std::int8_t> Vector::int8() const {
std::string raw = bytes();
std::vector<std::int8_t> v(raw.size());
for (std::size_t i = 0; i < raw.size(); ++i) v[i] = static_cast<std::int8_t>(static_cast<unsigned char>(raw[i]));
return v;
}
double cosine(const std::vector<std::int8_t>& a, const std::vector<std::int8_t>& b) {
if (a.size() != b.size() || a.empty()) return 0.0;
double dot = 0, na = 0, nb = 0;
for (std::size_t i = 0; i < a.size(); ++i) {
dot += static_cast<double>(a[i]) * b[i];
na += static_cast<double>(a[i]) * a[i];
nb += static_cast<double>(b[i]) * b[i];
}
if (na == 0 || nb == 0) return 0.0;
return dot / (std::sqrt(na) * std::sqrt(nb));
}
namespace {
EmbedUsage usage_of(const Json& doc) {
EmbedUsage u;
if (const Json* us = J::obj(doc, "usage")) {
u.prompt_tokens = J::num(*us, "prompt_tokens");
u.total_tokens = J::num(*us, "total_tokens");
if (const Json* c = J::obj(*us, "cost")) u.cost_total = J::dbl(*c, "total_cost");
}
return u;
}
Vector vector_of(const Json& v) {
Vector out;
out.index = static_cast<int>(J::num(v, "index"));
out.base64 = J::str(v, "embedding");
return out;
}
} // namespace
EmbedResult EmbedResult::parse(const Json& doc) {
EmbedResult r;
r.raw = doc;
r.model = J::str(doc, "model");
if (const Json* d = J::arr(doc, "data"))
for (const Json& v : d->as_array()) {
if (r.vectors.size() >= PerplexityCaps::kEmbedTexts) break;
r.vectors.push_back(vector_of(v));
}
r.usage = usage_of(doc);
return r;
}
ContextEmbedResult ContextEmbedResult::parse(const Json& doc) {
ContextEmbedResult r;
r.raw = doc;
r.model = J::str(doc, "model");
if (const Json* d = J::arr(doc, "data"))
for (const Json& group : d->as_array()) {
if (r.documents.size() >= PerplexityCaps::kEmbedTexts) break;
std::vector<Vector> chunks;
if (const Json* inner = J::arr(group, "data"))
for (const Json& v : inner->as_array()) chunks.push_back(vector_of(v));
r.documents.push_back(std::move(chunks));
}
r.usage = usage_of(doc);
return r;
}
EmbedResult Embeddings::create(const EmbedParams& params) {
return EmbedResult::parse(client_->post(Calls::render(Call::kEmbeddings), params.to_json()));
}
ContextEmbedResult Embeddings::create_contextualized(const ContextEmbedParams& params) {
return ContextEmbedResult::parse(client_->post(Calls::render(Call::kContextEmbeddings), params.to_json()));
}
} // namespace molo::perplexity
+88
View File
@@ -0,0 +1,88 @@
#pragma once
// Embeddings API: POST /v1/embeddings (independent texts) and
// POST /v1/contextualizedembeddings (chunks that share a document). Vectors
// arrive base64 encoded: base64_int8 (signed int8 per dimension, default) or
// base64_binary (packed bits). Matryoshka dimensions 128..1024 (0.6b) or
// 128..2560 (4b).
#include <cstdint>
#include <string>
#include <vector>
#include "llm/api_client.h"
#include "vendors/perplexity/types.h"
namespace molo::perplexity {
struct EmbedModels {
// Models the schema enumerates.
static constexpr const char* kStandard06 = "pplx-embed-v1-0.6b";
static constexpr const char* kStandard4 = "pplx-embed-v1-4b";
static constexpr const char* kContext06 = "pplx-embed-context-v1-0.6b";
static constexpr const char* kContext4 = "pplx-embed-context-v1-4b";
static bool is_standard(const std::string& m) { return m == kStandard06 || m == kStandard4; }
static bool is_context(const std::string& m) { return m == kContext06 || m == kContext4; }
static bool is_small(const std::string& m) { return m == kStandard06 || m == kContext06; }
};
struct EmbedParams {
std::string model = EmbedModels::kStandard06;
std::vector<std::string> input; // standard: 1..512 texts
int dimensions = 0; // 0: model default
std::string encoding_format; // "", base64_int8, base64_binary
void validate() const;
Json to_json() const;
};
struct ContextEmbedParams {
std::string model = EmbedModels::kContext06;
std::vector<std::vector<std::string>> input; // 1..512 documents, each a list of chunks
int dimensions = 0;
std::string encoding_format;
void validate() const;
Json to_json() const;
};
struct Vector {
int index = 0;
std::string base64;
// base64_int8: one value per dimension. Empty on decode failure.
std::vector<std::int8_t> int8() const;
// base64_binary: packed bits, 8 dimensions per byte, MSB first (unverified bit order).
std::string bytes() const;
bool decodable() const;
};
struct EmbedUsage {
long prompt_tokens = 0, total_tokens = 0;
double cost_total = 0; // usage.cost is an untyped object; total_cost when present
};
struct EmbedResult {
std::string model;
std::vector<Vector> vectors;
EmbedUsage usage;
Json raw;
static EmbedResult parse(const Json& doc);
};
struct ContextEmbedResult {
std::string model;
std::vector<std::vector<Vector>> documents; // documents[i] holds the chunk vectors of input[i]
EmbedUsage usage;
Json raw;
static ContextEmbedResult parse(const Json& doc);
};
// Cosine similarity of two int8 vectors of equal length (0 when either is zero).
double cosine(const std::vector<std::int8_t>& a, const std::vector<std::int8_t>& b);
class Embeddings : public llm::Service {
public:
explicit Embeddings(std::shared_ptr<llm::ApiClient> client) : llm::Service(std::move(client)) {}
EmbedResult create(const EmbedParams& params);
ContextEmbedResult create_contextualized(const ContextEmbedParams& params);
};
} // namespace molo::perplexity
+79
View File
@@ -0,0 +1,79 @@
#include "vendors/perplexity/errors.h"
namespace molo::perplexity {
namespace {
constexpr ErrorInfo kErrors[] = {
{400, ErrorKind::kBadRequest, "Bad Request", "Invalid request body or parameters.",
"Fix the request according to the message; do not retry unchanged.", false, 0},
{401, ErrorKind::kAuth, "Unauthorized",
"Missing, wrong or deleted API key (error.type invalid_api_key).",
"Send a current key as Authorization: Bearer; create one in the API portal.", false, 0},
{402, ErrorKind::kPayment, "Payment Required", "The account ran out of credits.",
"Add credits on the Billing page.", false, 0},
{403, ErrorKind::kForbidden, "Forbidden", "The key may not use this resource (or a safety block).",
"Do not retry without changing the request or the key.", false, 0},
{404, ErrorKind::kNotFound, "Not Found", "Unknown id (response, batch, file, skill, model).",
"Check the id; responses and files expire.", false, 0},
{409, ErrorKind::kConflict, "Conflict",
"Skill revision mismatch or a batch/skill in the wrong state.",
"Re-read the resource and use its current revision.", false, 0},
{413, ErrorKind::kTooLarge, "Payload Too Large", "Body or upload over the limit.",
"Send less (batch file: 50,000 lines and 200 MB).", false, 0},
{422, ErrorKind::kInvalidParams, "Unprocessable Entity",
"Schema validation failed (FastAPI style body {\"detail\":[...]}).",
"Fix the fields named in the detail.", false, 0},
{429, ErrorKind::kRateLimit, "Too Many Requests",
"Request limit (QPS), token limit (TPM / TPH), or upstream overloaded.",
"Wait the Retry-After interval, then retry with backoff and jitter.", true, 1},
{500, ErrorKind::kServer, "Server Error", "Transient server-side issue.",
"Retry with exponential backoff; log X-Request-ID for support.", true, 2},
{502, ErrorKind::kBadGateway, "Bad Gateway", "Upstream problem.", "Retry with backoff.", true, 2},
{503, ErrorKind::kOverloaded, "Service Unavailable", "Overloaded or batch capacity.",
"Retry with backoff.", true, 2},
{504, ErrorKind::kGatewayTimeout, "Gateway Timeout", "Upstream timed out.", "Retry with backoff.", true, 2},
};
} // namespace
std::size_t Errors::count() { return sizeof(kErrors) / sizeof(kErrors[0]); }
const ErrorInfo& Errors::at(std::size_t index) {
if (index >= count()) throw llm::ApiError::invalid("perplexity", "error index out of range");
return kErrors[index];
}
const ErrorInfo* Errors::find(int status) {
for (const ErrorInfo& e : kErrors)
if (e.status == status) return &e;
return nullptr;
}
ErrorKind Errors::kind_of(int status) {
if (status >= 200 && status < 300) return ErrorKind::kNone;
if (const ErrorInfo* e = find(status)) return e->kind;
return ErrorKind::kOther;
}
bool Errors::retryable(int status) {
const ErrorInfo* e = find(status);
return e && e->retryable;
}
int Errors::wait_seconds(int status) {
const ErrorInfo* e = find(status);
if (!e || !e->retryable) return 0;
return e->min_wait_seconds > kMaxWaitSeconds ? kMaxWaitSeconds : e->min_wait_seconds;
}
bool Errors::is_rate_limit_type(const std::string& type) {
return type == "request_rate_limit_exceeded" || type == "token_rate_limit_exceeded" ||
type == "too_many_requests" || type == "overloaded";
}
std::string Errors::explain(const llm::ApiError& e) {
const ErrorInfo* info = find(e.http_status());
if (!info) return std::to_string(e.http_status()) + " " + e.type() + ": " + e.message();
return std::to_string(info->status) + " " + info->name + ": " + info->action;
}
} // namespace molo::perplexity
+46
View File
@@ -0,0 +1,46 @@
#pragma once
// Perplexity error statuses and what to do about them. Sources: the OpenAPI
// error responses, the FAQ ("Errors & Troubleshooting") and the Rate Limits
// page. Waits are static advice; nothing here sleeps or retries on its own.
// A 429 carries Retry-After, which llm::ApiError drops (src/llm gap): the
// static floor below is used instead.
#include <string>
#include "llm/error.h"
namespace molo::perplexity {
enum class ErrorKind {
kNone, kBadRequest, kAuth, kPayment, kForbidden, kNotFound, kConflict, kTooLarge,
kInvalidParams, kRateLimit, kServer, kBadGateway, kOverloaded, kGatewayTimeout, kTransport, kOther,
};
struct ErrorInfo {
int status;
ErrorKind kind;
const char* name;
const char* cause;
const char* action;
bool retryable; // wait and retry the same request
int min_wait_seconds; // floor before a retry; 0 when not retryable
};
class Errors {
public:
static std::size_t count();
static const ErrorInfo& at(std::size_t index);
static const ErrorInfo* find(int status);
static ErrorKind kind_of(int status);
static bool retryable(int status);
// Static wait before a retry (0: do not retry). Hard cap kMaxWaitSeconds.
static int wait_seconds(int status);
static constexpr int kMaxWaitSeconds = 30;
// The documented 429 error.type values.
static bool is_rate_limit_type(const std::string& type);
// One line for humans: "402 Payment Required: add credits ...".
static std::string explain(const llm::ApiError& e);
};
} // namespace molo::perplexity
+141
View File
@@ -0,0 +1,141 @@
#include "vendors/perplexity/orchestrator.h"
#include <set>
#include <sstream>
#include "vendors/perplexity/caps.h"
#include "vendors/perplexity/rules.h"
namespace molo::perplexity {
namespace {
std::set<std::string> fields_of(const char* list) {
std::set<std::string> out;
std::stringstream ss(list);
std::string item;
while (std::getline(ss, item, ',')) out.insert(item);
return out;
}
void check_model(const Json& body) {
const Json* m = body.find("model");
Rules::require(m && m->is_string(), "model is required");
Rules::model(m->as_string());
Rules::require(m->as_string().find('/') != std::string::npos, "model must be a creator/name id such as perplexity/kimi-k3");
}
} // namespace
Json Orchestrator::chat_request(const std::string& model, const std::string& user_text) {
Json b = Json::object();
b.set("model", Json(model));
Json msgs = Json::array();
Json m = Json::object();
m.set("role", Json("user"));
m.set("content", Json(user_text));
msgs.push(m);
b.set("messages", msgs);
return b;
}
Json Orchestrator::messages_request(const std::string& model, const std::string& user_text, int max_tokens) {
Json b = chat_request(model, user_text);
b.set("max_tokens", Json(max_tokens));
return b;
}
Json Orchestrator::responses_request(const std::string& model, const std::string& input_text) {
Json b = Json::object();
b.set("model", Json(model));
b.set("input", Json(input_text));
return b;
}
void Orchestrator::validate(Call call, const Json& body) {
Rules::require(call == Call::kOrchChat || call == Call::kOrchMessages || call == Call::kOrchResponses,
"not an orchestrator generation call");
Rules::require(body.is_object(), "the request body must be a JSON object");
Rules::require(body.as_object().size() <= PerplexityCaps::kMaxGatewayFields, "too many top-level fields");
std::set<std::string> allowed = fields_of(Calls::spec_of(call).body_fields);
for (const auto& [k, v] : body.as_object()) {
(void)v;
if (call == Call::kOrchMessages &&
(k == "container" || k == "inference_geo" || k == "mcp_servers" || k == "fallbacks" || k == "fallback_credit_token"))
Rules::fail("Perplexity rejects '" + k + "' on /orchestrator/v1/messages");
Rules::require(allowed.count(k) > 0, "unknown field '" + k + "' for this call");
}
check_model(body);
if (call == Call::kOrchResponses) {
const Json* in = body.find("input");
Rules::require(in && (in->is_string() || in->is_array()), "input must be a string or an array of items");
if (in->is_array()) Rules::require(in->as_array().size() <= PerplexityCaps::kMaxInputItems, "too many input items");
} else {
const Json* msgs = body.find("messages");
Rules::require(msgs && msgs->is_array() && !msgs->as_array().empty(), "messages must be a non-empty array");
Rules::require(msgs->as_array().size() <= PerplexityCaps::kMaxMessages, "too many messages");
for (const Json& m : msgs->as_array()) Rules::require(m.is_object() && m.has("role"), "every message needs a role");
}
if (call == Call::kOrchMessages) {
const Json* mt = body.find("max_tokens");
Rules::require(mt && mt->is_number() && mt->as_int() >= 1, "max_tokens is required by the Messages schema");
}
if (const Json* t = body.find("temperature"); t && t->is_number()) Rules::temperature(t->as_number());
if (const Json* p = body.find("top_p"); p && p->is_number()) Rules::top_p(p->as_number());
if (const Json* s = body.find("stream"); s) Rules::require(s->is_bool(), "stream must be a boolean");
}
Json Orchestrator::chat(const Json& body) {
validate(Call::kOrchChat, body);
Rules::require(!J::flag(body, "stream"), "use stream() for streamed requests");
return client_->post(Calls::render(Call::kOrchChat), body);
}
Json Orchestrator::messages(const Json& body) {
validate(Call::kOrchMessages, body);
Rules::require(!J::flag(body, "stream"), "use stream() for streamed requests");
return client_->post(Calls::render(Call::kOrchMessages), body);
}
Json Orchestrator::responses(const Json& body) {
validate(Call::kOrchResponses, body);
Rules::require(!J::flag(body, "stream"), "use stream() for streamed requests");
return client_->post(Calls::render(Call::kOrchResponses), body);
}
void Orchestrator::stream(Call call, const Json& body, const EventSink& sink) {
validate(call, body);
Rules::require(J::flag(body, "stream"), "stream() needs stream:true in the body");
std::size_t events = 0;
client_->stream(Calls::render(call), body, [&](const llm::SseEvent& ev) {
if (++events > PerplexityCaps::kMaxStreamEvents) return false;
return sink ? sink(ev) : true;
});
}
ModelList Orchestrator::models() { return ModelList::parse(client_->get(Calls::render(Call::kOrchModels))); }
ModelInfo Orchestrator::model(const std::string& model_id) {
return ModelInfo::parse(client_->get(Calls::render(Call::kOrchModel, model_id)));
}
std::string Orchestrator::text_of(Call call, const Json& reply) {
std::string out;
if (call == Call::kOrchChat) {
if (const Json* cs = J::arr(reply, "choices"); cs && !cs->as_array().empty())
if (const Json* m = J::obj(cs->as_array()[0], "message")) return J::str(*m, "content");
return "";
}
const char* key = call == Call::kOrchMessages ? "content" : "output";
if (const Json* a = J::arr(reply, key))
for (const Json& item : a->as_array()) {
if (call == Call::kOrchMessages) {
if (J::str(item, "type") == "text") out += J::str(item, "text");
} else if (J::str(item, "type") == "message") {
if (const Json* c = J::arr(item, "content"))
for (const Json& part : c->as_array())
if (J::str(part, "type") == "output_text") out += J::str(part, "text");
}
}
return out;
}
} // namespace molo::perplexity
+46
View File
@@ -0,0 +1,46 @@
#pragma once
// Orchestrator API: Perplexity's gateway to open-weight models through the
// OpenAI Chat Completions, OpenAI Responses and Anthropic Messages schemas
// under /orchestrator/v1. Requests are passed through as JSON documents (the
// three schemas belong to OpenAI and Anthropic and are large); this class
// validates what Perplexity states about them: top-level fields come from the
// call table, required fields are present, the model is "creator/name", and
// the Messages fields Perplexity rejects are rejected locally.
#include <functional>
#include <string>
#include "llm/api_client.h"
#include "vendors/perplexity/calls.h"
#include "vendors/perplexity/types.h"
namespace molo::perplexity {
class Orchestrator : public llm::Service {
public:
explicit Orchestrator(std::shared_ptr<llm::ApiClient> client) : llm::Service(std::move(client)) {}
// Minimal request documents.
static Json chat_request(const std::string& model, const std::string& user_text);
static Json messages_request(const std::string& model, const std::string& user_text, int max_tokens);
static Json responses_request(const std::string& model, const std::string& input_text);
// Validates a request document for a call (kOrchChat, kOrchMessages, kOrchResponses).
static void validate(Call call, const Json& body);
Json chat(const Json& body);
Json messages(const Json& body);
Json responses(const Json& body);
// Streams the SSE events of any of the three calls; `body` must carry stream:true.
using EventSink = std::function<bool(const llm::SseEvent&)>;
void stream(Call call, const Json& body, const EventSink& sink);
ModelList models();
ModelInfo model(const std::string& model_id); // "creator/name"
// Text of the first assistant message in a chat / responses / messages reply ("" when none).
static std::string text_of(Call call, const Json& reply);
};
} // namespace molo::perplexity
+26
View File
@@ -0,0 +1,26 @@
#include "vendors/perplexity/platform.h"
namespace molo::perplexity {
llm::ApiClientConfig Platform::config() {
llm::ApiClientConfig c;
c.vendor = "perplexity";
c.base_url = kHost;
c.key_env = kKeyEnv;
c.auth = llm::AuthStyle::kBearer;
return c;
}
Platform Platform::from_env() {
Platform p;
p.client = llm::ApiClient::from_env(config());
return p;
}
Platform Platform::with(std::unique_ptr<clients::Transport> transport, const std::string& key) {
Platform p;
p.client = std::make_shared<llm::ApiClient>(std::move(transport), config(), key);
return p;
}
} // namespace molo::perplexity
+27
View File
@@ -0,0 +1,27 @@
#pragma once
// Wires api.perplexity.ai: one host, one Bearer credential, PERPLEXITY_API_KEY,
// read through llm::Config (environment, then the .env.json files).
#include <memory>
#include "llm/api_client.h"
namespace molo::perplexity {
struct Platform {
static constexpr const char* kHost = "https://api.perplexity.ai";
static constexpr const char* kKeyEnv = "PERPLEXITY_API_KEY";
static constexpr const char* kKeyPage = "https://console.perplexity.ai/";
std::shared_ptr<llm::ApiClient> client;
static llm::ApiClientConfig config();
// Real HTTPS transport; a missing key leaves the client "not configured".
static Platform from_env();
// Same key, any transport (tests).
static Platform with(std::unique_ptr<clients::Transport> transport, const std::string& key);
bool configured() const { return client && client->configured(); }
};
} // namespace molo::perplexity
+132
View File
@@ -0,0 +1,132 @@
#include "vendors/perplexity/rules.h"
#include <cctype>
#include "vendors/perplexity/caps.h"
namespace molo::perplexity {
void Rules::fail(const std::string& why) { throw llm::ApiError::invalid("perplexity", why); }
namespace {
bool word_char(char c) { return std::isalnum(static_cast<unsigned char>(c)) || c == '_' || c == '-'; }
bool digit(char c) { return c >= '0' && c <= '9'; }
bool alpha(char c) { return std::isalpha(static_cast<unsigned char>(c)) != 0; }
} // namespace
void Rules::model(const std::string& name) {
require(!name.empty() && name.size() <= PerplexityCaps::kMaxModelChars, "model must be 1..128 characters");
for (char c : name)
require(word_char(c) || c == '.' || c == ':' || c == '/', "model has invalid characters");
}
void Rules::range(double v, double lo, double hi, const char* what) {
require(v >= lo && v <= hi, std::string(what) + " must be " + std::to_string(lo) + ".." + std::to_string(hi));
}
void Rules::top_p(double v) { range(v, 0.0, 1.0, "top_p"); }
void Rules::temperature(double v) { range(v, 0.0, 2.0, "temperature"); }
void Rules::date(const std::string& v, const char* what) {
bool ok = v.size() >= 8 && v.size() <= 10;
std::size_t a = v.find('/');
std::size_t b = a == std::string::npos ? a : v.find('/', a + 1);
ok = ok && a != std::string::npos && b != std::string::npos && v.find('/', b + 1) == std::string::npos;
if (ok) {
std::string m = v.substr(0, a), d = v.substr(a + 1, b - a - 1), y = v.substr(b + 1);
auto all_digits = [](const std::string& s, std::size_t lo, std::size_t hi) {
if (s.size() < lo || s.size() > hi) return false;
for (char c : s)
if (!digit(c)) return false;
return true;
};
ok = all_digits(m, 1, 2) && all_digits(d, 1, 2) && all_digits(y, 4, 4);
if (ok) {
int mi = std::stoi(m), di = std::stoi(d);
ok = mi >= 1 && mi <= 12 && di >= 1 && di <= 31;
}
}
require(ok, std::string(what) + " must be MM/DD/YYYY");
}
void Rules::language(const std::string& code, const char* what) {
require(code.size() == 2 && alpha(code[0]) && alpha(code[1]),
std::string(what) + " must be a two-letter ISO 639-1 code");
}
void Rules::country(const std::string& code) {
require(code.size() == 2 && alpha(code[0]) && alpha(code[1]), "country must be a two-letter ISO 3166-1 code");
}
void Rules::domains(const std::vector<std::string>& list, std::size_t max, const char* what) {
require(list.size() <= max, std::string(what) + " has too many entries (max " + std::to_string(max) + ")");
for (const std::string& d : list) {
require(!d.empty() && d.size() <= 253, std::string(what) + " entries must be 1..253 characters");
for (char c : d)
require(static_cast<unsigned char>(c) > 0x20 && c != 0x7f && c != '/', std::string(what) + " entry has invalid characters");
}
}
void Rules::one_of(const std::string& value, std::initializer_list<const char*> allowed, const char* what) {
for (const char* a : allowed)
if (value == a) return;
std::string list;
for (const char* a : allowed) list += (list.empty() ? "" : ", ") + std::string(a);
fail(std::string(what) + " must be one of: " + list);
}
bool Rules::is_http_url(const std::string& url, bool allow_userinfo) {
std::size_t scheme = url.rfind("http://", 0) == 0 ? 7 : url.rfind("https://", 0) == 0 ? 8 : 0;
if (!scheme) return false;
std::size_t end = url.find_first_of("/?#", scheme);
std::string authority = url.substr(scheme, end == std::string::npos ? end : end - scheme);
if (authority.empty()) return false;
if (!allow_userinfo && authority.find('@') != std::string::npos) return false;
for (char c : url)
if (static_cast<unsigned char>(c) <= 0x20 || c == 0x7f) return false;
return true;
}
void Rules::https_url(const std::string& url, const char* what) {
require(url.rfind("https://", 0) == 0 && is_http_url(url), std::string(what) + " must be an https URL");
}
void Rules::name_token(const std::string& v, std::size_t max, const char* what) {
require(!v.empty() && v.size() <= max, std::string(what) + " must be 1.." + std::to_string(max) + " characters");
for (char c : v) require(word_char(c), std::string(what) + " allows only A-Z a-z 0-9 - _");
}
std::string Rules::url_encode(const std::string& s) {
static const char* hex = "0123456789ABCDEF";
std::string out;
for (unsigned char c : s) {
if (std::isalnum(c) || c == '-' || c == '_' || c == '.' || c == '~') {
out += static_cast<char>(c);
} else {
out += '%';
out += hex[c >> 4];
out += hex[c & 15];
}
}
return out;
}
void Rules::add_query(std::string& query, const std::string& key, const std::string& value) {
query += (query.empty() ? "?" : "&") + key + "=" + url_encode(value);
}
void Rules::opaque_token(const std::string& v, const char* what) {
require(!v.empty() && v.size() <= 512, std::string(what) + " must be 1..512 characters");
for (char c : v)
require(std::isalnum(static_cast<unsigned char>(c)) || c == '-' || c == '_' || c == '.' || c == '=' || c == ':' ||
c == '+' || c == '/',
std::string(what) + " has invalid characters");
}
void Rules::filename(const std::string& name) {
require(!name.empty() && name.size() <= PerplexityCaps::kMaxFilenameBytes, "filename must be 1..255 bytes");
for (char c : name)
require(c != '"' && c != '\r' && c != '\n' && c != '\\' && c != '/', "filename has invalid characters");
}
} // namespace molo::perplexity
+45
View File
@@ -0,0 +1,45 @@
#pragma once
// Input rules shared by every request type. All throw llm::ApiError::invalid
// (HTTP 400 INVALID_ARGUMENT, vendor "perplexity") before any network traffic.
#include <string>
#include <vector>
#include "llm/error.h"
namespace molo::perplexity {
struct Rules {
[[noreturn]] static void fail(const std::string& why);
static void require(bool ok, const std::string& why) {
if (!ok) fail(why);
}
// 1..128 of [A-Za-z0-9._:/-]. New and provider-prefixed names pass; the server decides.
static void model(const std::string& name);
static void range(double v, double lo, double hi, const char* what);
static void top_p(double v); // [0, 1]
static void temperature(double v); // [0, 2]
// MM/DD/YYYY
static void date(const std::string& value, const char* what);
// ISO 639-1: exactly two letters
static void language(const std::string& code, const char* what);
// ISO 3166-1 alpha-2: exactly two letters
static void country(const std::string& code);
// 1..max entries, each non-empty without whitespace; "-domain" allowed (deny list)
static void domains(const std::vector<std::string>& list, std::size_t max, const char* what);
static void one_of(const std::string& value, std::initializer_list<const char*> allowed, const char* what);
static bool is_http_url(const std::string& url, bool allow_userinfo = false);
static void https_url(const std::string& url, const char* what);
// Letters, digits, '-' '_' : 1..max chars
static void name_token(const std::string& value, std::size_t max, const char* what);
static void filename(const std::string& name);
// Percent-encodes everything but unreserved characters.
static std::string url_encode(const std::string& text);
// Appends "?k=v" or "&k=v" (value encoded) to a path.
static void add_query(std::string& query, const std::string& key, const std::string& value);
// Opaque server tokens (revisions, cursors): 1..512 printable characters without URL metacharacters.
static void opaque_token(const std::string& value, const char* what);
};
} // namespace molo::perplexity
+102
View File
@@ -0,0 +1,102 @@
#include "vendors/perplexity/search.h"
#include "vendors/perplexity/calls.h"
#include "vendors/perplexity/caps.h"
#include "vendors/perplexity/rules.h"
namespace molo::perplexity {
SearchParams SearchParams::of(const std::string& q, int max_results) {
SearchParams p;
p.query.push_back(q);
if (max_results > 0) p.max_results = max_results;
return p;
}
void SearchParams::validate() const {
Rules::require(!query.empty() && query.size() <= kMaxQueries, "query needs 1..5 entries");
for (const std::string& q : query) {
Rules::require(q.find_first_not_of(" \t\r\n") != std::string::npos, "query must not be blank");
Rules::require(q.size() <= PerplexityCaps::kMaxQueryChars, "query over 8192 characters");
}
if (!country.empty()) Rules::country(country);
if (!search_type.empty()) Rules::one_of(search_type, {"web", "fast", "people"}, "search_type");
if (max_results) {
bool people = search_type == "people";
int ceiling = people ? PerplexityCaps::kSearchMaxResultsPeople : PerplexityCaps::kSearchMaxResults;
Rules::require(*max_results >= 1 && *max_results <= ceiling,
people ? "max_results must be 1..50" : "max_results must be 1..20 (up to 50 needs search_type=people)");
}
for (const std::optional<int>* t : {&max_tokens, &max_tokens_per_page})
if (*t) Rules::require(**t >= 1 && **t <= PerplexityCaps::kSearchMaxTokens, "token limits must be 1..1000000");
Rules::require(search_language_filter.size() <= PerplexityCaps::kSearchLanguageFilter, "at most 20 language filters");
for (const std::string& l : search_language_filter) Rules::language(l, "search_language_filter entry");
Rules::domains(search_domain_filter, PerplexityCaps::kSearchDomainFilter, "search_domain_filter");
for (const std::string* d : {&last_updated_after_filter, &last_updated_before_filter, &search_after_date_filter,
&search_before_date_filter})
if (!d->empty()) Rules::date(*d, "date filter");
if (!search_recency_filter.empty())
Rules::one_of(search_recency_filter, {"hour", "day", "week", "month", "year"}, "search_recency_filter");
}
Json SearchParams::to_json() const {
validate();
Json b = Json::object();
if (query.size() == 1) {
b.set("query", Json(query[0]));
} else {
Json a = Json::array();
for (const std::string& q : query) a.push(Json(q));
b.set("query", a);
}
if (!country.empty()) b.set("country", Json(country));
if (max_results) b.set("max_results", Json(*max_results));
if (!search_type.empty()) b.set("search_type", Json(search_type));
if (max_tokens) b.set("max_tokens", Json(*max_tokens));
if (max_tokens_per_page) b.set("max_tokens_per_page", Json(*max_tokens_per_page));
auto list = [&](const char* key, const std::vector<std::string>& v) {
if (v.empty()) return;
Json a = Json::array();
for (const std::string& s : v) a.push(Json(s));
b.set(key, a);
};
list("search_language_filter", search_language_filter);
list("search_domain_filter", search_domain_filter);
auto str = [&](const char* key, const std::string& v) {
if (!v.empty()) b.set(key, Json(v));
};
str("last_updated_after_filter", last_updated_after_filter);
str("last_updated_before_filter", last_updated_before_filter);
str("search_after_date_filter", search_after_date_filter);
str("search_before_date_filter", search_before_date_filter);
str("search_recency_filter", search_recency_filter);
return b;
}
SearchResponse SearchResponse::parse(const Json& doc) {
SearchResponse r;
r.raw = doc;
r.id = J::str(doc, "id");
r.server_time = J::str(doc, "server_time");
if (const Json* rs = J::arr(doc, "results"))
for (const Json& p : rs->as_array()) {
if (r.results.size() >= PerplexityCaps::kMaxItemsReturned) {
r.truncated = true;
break;
}
SearchPage s;
s.title = J::str(p, "title");
s.url = J::str(p, "url");
s.snippet = J::str(p, "snippet");
s.date = J::str(p, "date");
s.last_updated = J::str(p, "last_updated");
r.results.push_back(std::move(s));
}
return r;
}
SearchResponse Search::run(const SearchParams& params) {
return SearchResponse::parse(client_->post(Calls::render(Call::kSearch), params.to_json()));
}
} // namespace molo::perplexity
+51
View File
@@ -0,0 +1,51 @@
#pragma once
// Search API: POST /search returns ranked web results (no generated answer).
// Multi-query (up to 5 queries) consumes one rate-limit unit per query.
#include <optional>
#include <string>
#include <vector>
#include "llm/api_client.h"
#include "vendors/perplexity/types.h"
namespace molo::perplexity {
struct SearchParams {
static constexpr std::size_t kMaxQueries = 5; // documented ("up to 5 queries")
std::vector<std::string> query; // one entry is sent as a string, several as an array
std::string country; // ISO 3166-1 alpha-2
std::optional<int> max_results; // 1..20; up to 50 only with search_type=people
std::string search_type; // "", web, fast, people
std::optional<int> max_tokens, max_tokens_per_page; // 1..1,000,000
std::vector<std::string> search_language_filter; // ISO 639-1, max 20
std::vector<std::string> search_domain_filter; // max 20, "-domain" denies
std::string last_updated_after_filter, last_updated_before_filter, search_after_date_filter,
search_before_date_filter; // MM/DD/YYYY
std::string search_recency_filter; // "", hour, day, week, month, year
static SearchParams of(const std::string& query, int max_results = 0);
void validate() const;
Json to_json() const;
};
struct SearchPage {
std::string title, url, snippet, date, last_updated;
};
struct SearchResponse {
std::string id, server_time;
std::vector<SearchPage> results;
bool truncated = false;
Json raw;
static SearchResponse parse(const Json& doc);
};
class Search : public llm::Service {
public:
explicit Search(std::shared_ptr<llm::ApiClient> client) : llm::Service(std::move(client)) {}
SearchResponse run(const SearchParams& params);
};
} // namespace molo::perplexity
+141
View File
@@ -0,0 +1,141 @@
#include "vendors/perplexity/skills.h"
#include "clients/body/form.h"
#include "vendors/perplexity/calls.h"
#include "vendors/perplexity/caps.h"
#include "vendors/perplexity/rules.h"
namespace molo::perplexity {
namespace {
// Opaque tokens (revisions, cursors): printable, no URL metacharacters.
void opaque(const std::string& v, const char* what) { Rules::opaque_token(v, what); }
void add(std::string& q, const std::string& k, const std::string& v) { Rules::add_query(q, k, v); }
Json parse_body(const std::string& body) {
if (body.find_first_not_of(" \t\r\n") == std::string::npos) return Json::object();
try {
return Json::parse(body);
} catch (const std::exception& e) {
throw llm::ApiError("perplexity", 502, "BAD_RESPONSE", e.what());
}
}
std::string paging(int limit, const std::string& token, int max) {
std::string q;
if (limit) {
Rules::require(limit >= 1 && limit <= max, "limit must be 1.." + std::to_string(max));
add(q, "limit", std::to_string(limit));
}
if (!token.empty()) {
opaque(token, "page_token");
add(q, "page_token", token);
}
return q;
}
} // namespace
SkillInfo SkillInfo::parse(const Json& doc) {
SkillInfo s;
s.skill_id = J::str(doc, "skill_id");
s.name = J::str(doc, "name");
s.description = J::str(doc, "description");
s.revision = J::str(doc, "revision");
s.latest_revision = J::str(doc, "latest_revision");
s.created_at = J::str(doc, "created_at");
s.updated_at = J::str(doc, "updated_at");
return s;
}
void SkillBundle::validate() const {
Rules::filename(filename);
Rules::require(!data.empty(), "the skill bundle is empty");
Rules::require(data.size() <= PerplexityCaps::kMaxSkillBundleBytes, "skill bundle over 64 MiB");
Rules::require(data.compare(0, 4, "PK\x03\x04", 4) == 0, "the skill bundle must be a zip archive");
}
SkillList Skills::list(int limit, const std::string& page_token) {
Json doc = client_->get(Calls::render(Call::kSkillList) + paging(limit, page_token, PerplexityCaps::kSkillPageLimitMax));
SkillList l;
l.next_page_token = J::str(doc, "next_page_token");
if (const Json* a = J::arr(doc, "skills"))
for (const Json& s : a->as_array()) {
if (l.skills.size() >= PerplexityCaps::kMaxItemsReturned) {
l.truncated = true;
break;
}
l.skills.push_back(SkillInfo::parse(s));
}
return l;
}
SkillInfo Skills::create(const SkillBundle& bundle) {
bundle.validate();
clients::body::MultipartBody form;
form.add_file("file", bundle.filename, "application/zip", bundle.data);
return SkillInfo::parse(client_->post_multipart(Calls::render(Call::kSkillCreate), form));
}
SkillInfo Skills::get(const std::string& skill_id, const std::string& revision) {
check_id("skill", skill_id);
std::string q;
if (!revision.empty()) {
opaque(revision, "revision");
add(q, "revision", revision);
}
return SkillInfo::parse(client_->get(Calls::render(Call::kSkillGet, skill_id) + q));
}
SkillInfo Skills::update(const std::string& skill_id, const std::string& expected_revision, const SkillBundle& bundle) {
check_id("skill", skill_id);
opaque(expected_revision, "expected_revision");
bundle.validate();
clients::body::MultipartBody form;
form.add_file("file", bundle.filename, "application/zip", bundle.data);
std::string body = form.encode();
std::string q;
add(q, "expected_revision", expected_revision);
// The foundation's post_multipart is POST-only; PUT goes through request_raw.
llm::RawResponse raw = client_->request_raw(Calls::method_of(Call::kSkillUpdate),
Calls::render(Call::kSkillUpdate, skill_id) + q, &body,
form.content_type());
return SkillInfo::parse(parse_body(raw.body));
}
void Skills::remove(const std::string& skill_id, const std::string& expected_revision) {
check_id("skill", skill_id);
opaque(expected_revision, "expected_revision");
std::string q;
add(q, "expected_revision", expected_revision);
client_->request_raw(Calls::method_of(Call::kSkillDelete), Calls::render(Call::kSkillDelete, skill_id) + q);
}
SkillRevisionList Skills::revisions(const std::string& skill_id, int limit, const std::string& page_token) {
check_id("skill", skill_id);
Json doc = client_->get(Calls::render(Call::kSkillRevisions, skill_id) +
paging(limit, page_token, PerplexityCaps::kSkillPageLimitMax));
SkillRevisionList l;
l.next_page_token = J::str(doc, "next_page_token");
if (const Json* a = J::arr(doc, "revisions"))
for (const Json& r : a->as_array()) {
if (l.revisions.size() >= PerplexityCaps::kMaxItemsReturned) {
l.truncated = true;
break;
}
l.revisions.push_back({J::str(r, "revision"), J::str(r, "name"), J::str(r, "created_at")});
}
return l;
}
SkillDownload Skills::download(const std::string& skill_id, const std::string& revision) {
check_id("skill", skill_id);
std::string q;
if (!revision.empty()) {
opaque(revision, "revision");
add(q, "revision", revision);
}
Json doc = client_->get(Calls::render(Call::kSkillDownload, skill_id) + q);
return {J::str(doc, "revision"), J::str(doc, "name"), J::str(doc, "download_url")};
}
} // namespace molo::perplexity
+62
View File
@@ -0,0 +1,62 @@
#pragma once
// Managed skills: zip bundles containing SKILL.md, stored per project and
// loaded by Agent API requests as {type:custom, id:skill_...}. Updates and
// deletes need expected_revision = the skill's latest_revision (409 otherwise).
#include <optional>
#include <string>
#include <vector>
#include "llm/api_client.h"
#include "vendors/perplexity/types.h"
namespace molo::perplexity {
struct SkillInfo {
std::string skill_id, name, description, revision, latest_revision, created_at, updated_at;
static SkillInfo parse(const Json& doc);
};
struct SkillList {
std::vector<SkillInfo> skills;
std::string next_page_token;
bool truncated = false;
};
struct SkillRevision {
std::string revision, name, created_at;
};
struct SkillRevisionList {
std::vector<SkillRevision> revisions;
std::string next_page_token;
bool truncated = false;
};
struct SkillDownload {
std::string revision, name, download_url; // short-lived signed URL; the zip is not fetched here
};
struct SkillBundle {
std::string filename = "skill.zip";
std::string data; // zip bytes, <= 64 MiB, must start with the zip signature
void validate() const;
};
class Skills : public llm::Service {
public:
explicit Skills(std::shared_ptr<llm::ApiClient> client) : llm::Service(std::move(client)) {}
SkillList list(int limit = 0, const std::string& page_token = "");
SkillInfo create(const SkillBundle& bundle);
SkillInfo get(const std::string& skill_id, const std::string& revision = "");
// Adds a revision; expected_revision is the skill's current latest_revision.
SkillInfo update(const std::string& skill_id, const std::string& expected_revision, const SkillBundle& bundle);
// Destructive, no default. Succeeds with 204 (no body).
void remove(const std::string& skill_id, const std::string& expected_revision);
SkillRevisionList revisions(const std::string& skill_id, int limit = 0, const std::string& page_token = "");
SkillDownload download(const std::string& skill_id, const std::string& revision = "");
};
} // namespace molo::perplexity
+129
View File
@@ -0,0 +1,129 @@
#include "vendors/perplexity/sonar.h"
#include <chrono>
#include <thread>
#include "vendors/perplexity/calls.h"
#include "vendors/perplexity/caps.h"
#include "vendors/perplexity/rules.h"
namespace molo::perplexity {
const char* async_status_name(AsyncStatus s) {
switch (s) {
case AsyncStatus::kCreated: return "CREATED";
case AsyncStatus::kInProgress: return "IN_PROGRESS";
case AsyncStatus::kCompleted: return "COMPLETED";
case AsyncStatus::kFailed: return "FAILED";
default: return "UNKNOWN";
}
}
AsyncSummary AsyncSummary::parse(const Json& doc) {
AsyncSummary s;
s.id = J::str(doc, "id");
s.model = J::str(doc, "model");
s.status = J::str(doc, "status");
s.created_at = J::num(doc, "created_at");
s.started_at = J::num(doc, "started_at");
s.completed_at = J::num(doc, "completed_at");
s.failed_at = J::num(doc, "failed_at");
return s;
}
AsyncStatus AsyncSummary::state() const {
if (status == "CREATED") return AsyncStatus::kCreated;
if (status == "IN_PROGRESS") return AsyncStatus::kInProgress;
if (status == "COMPLETED") return AsyncStatus::kCompleted;
if (status == "FAILED") return AsyncStatus::kFailed;
return AsyncStatus::kUnknown;
}
AsyncJob AsyncJob::parse(const Json& doc) {
AsyncJob j;
static_cast<AsyncSummary&>(j) = AsyncSummary::parse(doc);
j.raw = doc;
j.error_message = J::str(doc, "error_message");
if (const Json* r = J::obj(doc, "response")) {
j.has_response = true;
j.response = SonarResult::parse(*r);
}
return j;
}
SonarResult Sonar::create(const SonarParams& params) {
Json doc = client_->post(Calls::render(Call::kSonar), params.to_json(false));
return SonarResult::parse(doc);
}
SonarResult Sonar::stream(const SonarParams& params, const DeltaSink& on_delta) {
Json body = params.to_json(true);
SonarStreamFolder folder;
bool stopped = false;
std::size_t events = 0;
client_->stream(Calls::render(Call::kSonar), body, [&](const llm::SseEvent& ev) {
if (++events > PerplexityCaps::kMaxStreamEvents) {
stopped = true;
return false;
}
SonarDelta d = folder.feed(ev.data);
if (on_delta && !on_delta(d)) {
stopped = true;
return false;
}
return true;
});
if (!stopped && !folder.done())
throw llm::ApiError("perplexity", 502, "STREAM_TRUNCATED", "stream ended without a finish_reason");
return folder.result();
}
AsyncJob Sonar::create_async(const SonarParams& params, const std::string& idempotency_key) {
Json req = Json::object();
req.set("request", params.to_json(false));
if (!idempotency_key.empty()) {
Rules::require(idempotency_key.size() <= PerplexityCaps::kIdempotencyKey, "idempotency_key over 200 characters");
req.set("idempotency_key", Json(idempotency_key));
}
return AsyncJob::parse(client_->post(Calls::render(Call::kAsyncCreate), req));
}
AsyncList Sonar::list_async() {
Json doc = client_->get(Calls::render(Call::kAsyncList));
AsyncList l;
l.raw = doc;
l.next_token = J::str(doc, "next_token");
if (const Json* rs = J::arr(doc, "requests"))
for (const Json& r : rs->as_array()) {
if (l.requests.size() >= PerplexityCaps::kMaxItemsReturned) {
l.truncated = true;
break;
}
l.requests.push_back(AsyncSummary::parse(r));
}
return l;
}
AsyncJob Sonar::get_async(const std::string& request_id) {
check_id("async request", request_id);
return AsyncJob::parse(client_->get(Calls::render(Call::kAsyncGet, request_id)));
}
AsyncJob Sonar::wait_async(const std::string& request_id, int interval_seconds, int max_wait_seconds,
const std::function<void(int)>& sleeper) {
Rules::require(interval_seconds >= PerplexityCaps::kMinPollIntervalSeconds, "poll interval must be at least 1 second");
Rules::require(max_wait_seconds >= 1 && max_wait_seconds <= PerplexityCaps::kMaxPollSeconds,
"max wait must be 1..600 seconds");
int waited = 0;
for (;;) {
AsyncJob job = get_async(request_id);
if (job.finished()) return job;
if (waited + interval_seconds > max_wait_seconds)
throw llm::ApiError("perplexity", 504, "WAIT_TIMEOUT", "async request still running after the wait ceiling");
if (sleeper) sleeper(interval_seconds);
else std::this_thread::sleep_for(std::chrono::seconds(interval_seconds));
waited += interval_seconds;
}
}
} // namespace molo::perplexity
+65
View File
@@ -0,0 +1,65 @@
#pragma once
// Sonar chat completions: POST /v1/sonar (create, stream) and the async
// variant (POST/GET /v1/async/sonar). The SDKs call the same operations at
// /chat/completions and /async/chat/completions (aliases, see SPEC).
#include <functional>
#include <string>
#include <vector>
#include "llm/api_client.h"
#include "vendors/perplexity/sonar_params.h"
#include "vendors/perplexity/sonar_result.h"
namespace molo::perplexity {
enum class AsyncStatus { kCreated, kInProgress, kCompleted, kFailed, kUnknown };
const char* async_status_name(AsyncStatus s);
struct AsyncSummary {
std::string id, model, status;
long created_at = 0, started_at = 0, completed_at = 0, failed_at = 0;
static AsyncSummary parse(const Json& doc);
AsyncStatus state() const;
};
struct AsyncJob : AsyncSummary {
std::string error_message;
bool has_response = false;
SonarResult response;
Json raw;
static AsyncJob parse(const Json& doc);
bool finished() const { return state() == AsyncStatus::kCompleted || state() == AsyncStatus::kFailed; }
};
struct AsyncList {
std::vector<AsyncSummary> requests;
std::string next_token; // the spec documents no request parameter to send it back
bool truncated = false;
Json raw;
};
class Sonar : public llm::Service {
public:
explicit Sonar(std::shared_ptr<llm::ApiClient> client) : llm::Service(std::move(client)) {}
SonarResult create(const SonarParams& params);
using DeltaSink = std::function<bool(const SonarDelta&)>; // false: stop early
// Streams chunks; returns the folded result. A stream that ends without a
// finish_reason / end_of_stream (and was not stopped by the sink) throws 502
// STREAM_TRUNCATED.
SonarResult stream(const SonarParams& params, const DeltaSink& on_delta);
// Async chat completions. idempotency_key: "" omits it (1..200 chars otherwise).
AsyncJob create_async(const SonarParams& params, const std::string& idempotency_key = "");
AsyncList list_async();
AsyncJob get_async(const std::string& request_id);
// Polls get_async until COMPLETED or FAILED. interval floor 1 s, wait ceiling 600 s;
// throws 504 WAIT_TIMEOUT when the ceiling passes. `sleeper` is injectable for tests.
AsyncJob wait_async(const std::string& request_id, int interval_seconds = 5, int max_wait_seconds = 300,
const std::function<void(int)>& sleeper = nullptr);
};
} // namespace molo::perplexity
+292
View File
@@ -0,0 +1,292 @@
#include "vendors/perplexity/sonar_params.h"
#include "llm/chat_types.h"
#include "vendors/perplexity/calls.h"
#include "vendors/perplexity/caps.h"
#include "vendors/perplexity/rules.h"
namespace molo::perplexity {
Json Messages::make(const std::string& role, const std::string& text) {
Json m = Json::object();
m.set("role", Json(role));
m.set("content", Json(text));
return m;
}
Json Messages::system(const std::string& t) { return make("system", t); }
Json Messages::user(const std::string& t) { return make("user", t); }
Json Messages::assistant(const std::string& t) { return make("assistant", t); }
Json Messages::tool(const std::string& t) { return make("tool", t); }
Json Messages::with_parts(const std::string& role, const std::vector<Json>& parts) {
Rules::require(!parts.empty(), "a message needs at least one content part");
Json arr = Json::array();
for (const Json& p : parts) arr.push(p);
Json m = Json::object();
m.set("role", Json(role));
m.set("content", arr);
return m;
}
Json Messages::text_part(const std::string& text) {
Json p = Json::object();
p.set("type", Json("text"));
p.set("text", Json(text));
return p;
}
Json Messages::image_part(const std::string& url) {
bool data = url.rfind("data:image/", 0) == 0 && url.find(";base64,") != std::string::npos;
Rules::require(data || Rules::is_http_url(url, true), "image url must be http(s) or a data:image/...;base64, URL");
Json u = Json::object();
u.set("url", Json(url));
Json p = Json::object();
p.set("type", Json("image_url"));
p.set("image_url", u);
return p;
}
Json Messages::file_part(const std::string& url, const std::string& file_name) {
Rules::require(!url.empty(), "file url must not be empty");
Json u = Json::object();
u.set("url", Json(url));
Json p = Json::object();
p.set("type", Json("file_url"));
p.set("file_url", u);
if (!file_name.empty()) {
Rules::filename(file_name);
p.set("file_name", Json(file_name));
}
return p;
}
Json Messages::pdf_part(const std::string& url) {
Rules::require(!url.empty(), "pdf url must not be empty");
Json u = Json::object();
u.set("url", Json(url));
Json p = Json::object();
p.set("type", Json("pdf_url"));
p.set("pdf_url", u);
return p;
}
Json Messages::video_part(const std::string& url, int frame_interval) {
Rules::require(Rules::is_http_url(url, true), "video url must be http(s)");
Rules::require(frame_interval >= 0, "frame_interval must not be negative");
Json u = Json::object();
u.set("url", Json(url));
if (frame_interval > 0) u.set("frame_interval", Json(frame_interval));
Json p = Json::object();
p.set("type", Json("video_url"));
p.set("video_url", u);
return p;
}
bool UserLocation::empty() const {
return !latitude && !longitude && country.empty() && city.empty() && region.empty();
}
void UserLocation::validate() const {
if (latitude) Rules::range(*latitude, -90.0, 90.0, "latitude");
if (longitude) Rules::range(*longitude, -180.0, 180.0, "longitude");
Rules::require(latitude.has_value() == longitude.has_value(), "latitude and longitude go together");
if (!country.empty()) Rules::country(country);
Rules::require(city.size() <= 256 && region.size() <= 256, "city and region must be at most 256 characters");
}
Json UserLocation::to_json() const {
Json o = Json::object();
if (latitude) o.set("latitude", Json(*latitude));
if (longitude) o.set("longitude", Json(*longitude));
if (!country.empty()) o.set("country", Json(country));
if (!city.empty()) o.set("city", Json(city));
if (!region.empty()) o.set("region", Json(region));
return o;
}
bool WebSearchOptions::empty() const {
return search_context_size.empty() && search_type.empty() && user_location.empty() &&
!image_results_enhanced_relevance;
}
void WebSearchOptions::validate() const {
if (!search_context_size.empty()) Rules::one_of(search_context_size, {"low", "medium", "high"}, "search_context_size");
if (!search_type.empty()) Rules::one_of(search_type, {"fast", "pro", "auto"}, "search_type");
user_location.validate();
}
Json WebSearchOptions::to_json() const {
Json o = Json::object();
if (!search_context_size.empty()) o.set("search_context_size", Json(search_context_size));
if (!search_type.empty()) o.set("search_type", Json(search_type));
if (!user_location.empty()) o.set("user_location", user_location.to_json());
if (image_results_enhanced_relevance) o.set("image_results_enhanced_relevance", Json(*image_results_enhanced_relevance));
return o;
}
Json StructuredOutput::text() {
Json o = Json::object();
o.set("type", Json("text"));
return o;
}
Json StructuredOutput::json_schema(const Json& schema, const std::string& name, bool strict,
const std::string& description) {
Rules::require(schema.is_object(), "json schema must be an object");
Json js = Json::object();
js.set("schema", schema);
if (!name.empty()) {
Rules::name_token(name, 64, "schema name");
js.set("name", Json(name));
}
js.set("strict", Json(strict));
if (!description.empty()) js.set("description", Json(description));
Json o = Json::object();
o.set("type", Json("json_schema"));
o.set("json_schema", js);
return o;
}
SonarParams SonarParams::prompt(const std::string& text, const std::string& model) {
SonarParams p;
p.model = model;
p.messages.push_back(Messages::user(text));
return p;
}
SonarParams& SonarParams::add(const Json& message) {
messages.push_back(message);
return *this;
}
namespace {
void check_message(const Json& m) {
Rules::require(m.is_object(), "a message must be an object");
std::string role = J::str(m, "role");
Rules::one_of(role, {"system", "user", "assistant", "tool"}, "message role");
const Json* content = m.find("content");
Rules::require(content && (content->is_string() || content->is_array() || content->is_null()),
"message content must be a string or an array of parts");
if (content->is_array()) {
Rules::require(!content->as_array().empty(), "message content parts must not be empty");
for (const Json& p : content->as_array()) {
Rules::require(p.is_object(), "a content part must be an object");
Rules::one_of(J::str(p, "type"), {"text", "image_url", "file_url", "pdf_url", "video_url"}, "content part type");
}
}
}
} // namespace
void SonarParams::validate() const {
Rules::model(model);
Rules::require(!messages.empty(), "messages must not be empty");
Rules::require(messages.size() <= PerplexityCaps::kMaxMessages, "too many messages");
for (const Json& m : messages) check_message(m);
if (max_tokens) Rules::require(*max_tokens >= 1, "max_tokens must be at least 1");
if (temperature) Rules::temperature(*temperature);
if (top_p) Rules::top_p(*top_p);
Rules::require(stop.size() <= PerplexityCaps::kMaxStop, "at most 16 stop sequences");
for (const std::string& s : stop) Rules::require(!s.empty(), "stop sequences must not be empty");
if (!response_format.is_null()) {
Rules::require(response_format.is_object(), "response_format must be an object");
std::string type = J::str(response_format, "type");
Rules::one_of(type, {"text", "json_schema"}, "response_format.type");
if (type == "json_schema") {
const Json* js = J::obj(response_format, "json_schema");
Rules::require(js && J::obj(*js, "schema"), "response_format.json_schema.schema is required");
}
}
web_search_options.validate();
if (!search_mode.empty()) Rules::one_of(search_mode, {"web", "academic", "sec"}, "search_mode");
Rules::domains(search_domain_filter, PerplexityCaps::kMaxFilterEntries, "search_domain_filter");
Rules::require(search_language_filter.size() <= PerplexityCaps::kMaxFilterEntries, "too many language filters");
for (const std::string& l : search_language_filter) Rules::language(l, "search_language_filter entry");
if (!search_recency_filter.empty())
Rules::one_of(search_recency_filter, {"hour", "day", "week", "month", "year"}, "search_recency_filter");
auto date = [](const std::string& d, const char* n) {
if (!d.empty()) Rules::date(d, n);
};
date(search_after_date_filter, "search_after_date_filter");
date(search_before_date_filter, "search_before_date_filter");
date(last_updated_before_filter, "last_updated_before_filter");
date(last_updated_after_filter, "last_updated_after_filter");
Rules::require(image_format_filter.size() <= PerplexityCaps::kMaxFilterEntries, "too many image format filters");
for (const std::string& f : image_format_filter) Rules::name_token(f, 16, "image_format_filter entry");
Rules::domains(image_domain_filter, PerplexityCaps::kMaxFilterEntries, "image_domain_filter");
if (!stream_mode.empty()) Rules::one_of(stream_mode, {"full", "concise"}, "stream_mode");
if (!reasoning_effort.empty())
Rules::one_of(reasoning_effort, {"minimal", "low", "medium", "high"}, "reasoning_effort");
if (!language_preference.empty()) Rules::language(language_preference, "language_preference");
}
namespace {
Json string_array(const std::vector<std::string>& v) {
Json a = Json::array();
for (const std::string& s : v) a.push(Json(s));
return a;
}
} // namespace
Json SonarParams::to_json(bool stream) const {
validate();
Json b = Json::object();
b.set("model", Json(model));
Json msgs = Json::array();
for (const Json& m : messages) msgs.push(m);
b.set("messages", msgs);
if (stream) b.set("stream", Json(true));
if (max_tokens) b.set("max_tokens", Json(*max_tokens));
if (temperature) b.set("temperature", Json(*temperature));
if (top_p) b.set("top_p", Json(*top_p));
if (stop.size() == 1) b.set("stop", Json(stop[0]));
else if (!stop.empty()) b.set("stop", string_array(stop));
if (!response_format.is_null()) b.set("response_format", response_format);
if (!web_search_options.empty()) b.set("web_search_options", web_search_options.to_json());
if (!search_mode.empty()) b.set("search_mode", Json(search_mode));
if (return_images) b.set("return_images", Json(*return_images));
if (return_related_questions) b.set("return_related_questions", Json(*return_related_questions));
if (enable_search_classifier) b.set("enable_search_classifier", Json(*enable_search_classifier));
if (disable_search) b.set("disable_search", Json(*disable_search));
if (!search_domain_filter.empty()) b.set("search_domain_filter", string_array(search_domain_filter));
if (!search_language_filter.empty()) b.set("search_language_filter", string_array(search_language_filter));
if (!search_recency_filter.empty()) b.set("search_recency_filter", Json(search_recency_filter));
if (!search_after_date_filter.empty()) b.set("search_after_date_filter", Json(search_after_date_filter));
if (!search_before_date_filter.empty()) b.set("search_before_date_filter", Json(search_before_date_filter));
if (!last_updated_before_filter.empty()) b.set("last_updated_before_filter", Json(last_updated_before_filter));
if (!last_updated_after_filter.empty()) b.set("last_updated_after_filter", Json(last_updated_after_filter));
if (!image_format_filter.empty()) b.set("image_format_filter", string_array(image_format_filter));
if (!image_domain_filter.empty()) b.set("image_domain_filter", string_array(image_domain_filter));
if (!stream_mode.empty()) b.set("stream_mode", Json(stream_mode));
if (!reasoning_effort.empty()) b.set("reasoning_effort", Json(reasoning_effort));
if (!language_preference.empty()) b.set("language_preference", Json(language_preference));
if (extra.is_object()) {
std::string known = std::string(",") + Calls::spec_of(Call::kSonar).body_fields + ",";
for (const auto& [k, v] : extra.as_object()) {
Rules::require(known.find("," + k + ",") != std::string::npos, "extra field '" + k + "' is not in the Sonar request schema");
if (!b.has(k)) b.set(k, v);
}
}
return b;
}
namespace {
constexpr SonarModel kModels[] = {
{"sonar", "lightweight search-grounded model"},
{"sonar-pro", "advanced search model for complex queries"},
{"sonar-reasoning-pro", "chain-of-thought reasoning with search"},
{"sonar-deep-research", "exhaustive multi-step research; slow, usually used via async"},
};
} // namespace
std::size_t SonarModels::count() { return sizeof(kModels) / sizeof(kModels[0]); }
const SonarModel& SonarModels::at(std::size_t i) {
if (i >= count()) throw llm::ApiError::invalid("perplexity", "model index out of range");
return kModels[i];
}
bool SonarModels::known(const std::string& id) {
for (const SonarModel& m : kModels)
if (id == m.id) return true;
return false;
}
} // namespace molo::perplexity
+99
View File
@@ -0,0 +1,99 @@
#pragma once
// Request side of Sonar chat completions (POST /v1/sonar, ApiChatCompletionsRequest):
// message builders, search options, structured output, and SonarParams which
// validates every field against the schema before any network traffic.
#include <optional>
#include <string>
#include <vector>
#include "vendors/perplexity/types.h"
namespace molo::perplexity {
// ChatMessage-Input builders. Content is a string or an array of typed parts.
struct Messages {
static Json make(const std::string& role, const std::string& text);
static Json system(const std::string& text);
static Json user(const std::string& text);
static Json assistant(const std::string& text);
static Json tool(const std::string& text);
static Json with_parts(const std::string& role, const std::vector<Json>& parts);
static Json text_part(const std::string& text);
// image_url: https URL or data:image/...;base64, URL
static Json image_part(const std::string& url);
static Json file_part(const std::string& url, const std::string& file_name = "");
static Json pdf_part(const std::string& url);
// frame_interval: frames per sampled frame ("25" default server side); 0 = omit
static Json video_part(const std::string& url, int frame_interval = 0);
};
struct UserLocation {
std::optional<double> latitude, longitude;
std::string country, city, region;
bool empty() const;
void validate() const;
Json to_json() const;
};
struct WebSearchOptions {
std::string search_context_size; // "", low, medium, high
std::string search_type; // "", fast, pro, auto
UserLocation user_location;
std::optional<bool> image_results_enhanced_relevance;
bool empty() const;
void validate() const;
Json to_json() const;
};
// response_format builders.
struct StructuredOutput {
static Json text();
// json_schema.schema must be a JSON object; name defaults to "schema" server side.
static Json json_schema(const Json& schema, const std::string& name = "", bool strict = true,
const std::string& description = "");
};
struct SonarParams {
std::string model = "sonar";
std::vector<Json> messages;
std::optional<int> max_tokens;
std::optional<double> temperature, top_p;
std::vector<std::string> stop; // one string or an array on the wire
Json response_format; // null: omit
WebSearchOptions web_search_options;
std::string search_mode; // "", web, academic, sec
std::optional<bool> return_images, return_related_questions, enable_search_classifier, disable_search;
std::vector<std::string> search_domain_filter, search_language_filter;
std::string search_recency_filter; // "", hour, day, week, month, year
std::string search_after_date_filter, search_before_date_filter, last_updated_before_filter,
last_updated_after_filter; // MM/DD/YYYY
std::vector<std::string> image_format_filter, image_domain_filter;
std::string stream_mode; // "", full, concise
std::string reasoning_effort; // "", minimal, low, medium, high
std::string language_preference; // ISO 639-1
// Raw top-level fields merged into the body. Only names of the Sonar request
// schema are accepted, and a field set through a typed member wins.
Json extra;
static SonarParams prompt(const std::string& text, const std::string& model = "sonar");
SonarParams& add(const Json& message);
void validate() const;
// `stream` is set by the caller (Sonar::stream); it is false/omitted otherwise.
Json to_json(bool stream = false) const;
};
// Catalog of the models the schema enumerates (and what the docs say about them).
struct SonarModel {
const char* id;
const char* note;
};
struct SonarModels {
static std::size_t count();
static const SonarModel& at(std::size_t index);
static bool known(const std::string& id);
static const char* default_model() { return "sonar"; }
};
} // namespace molo::perplexity
+112
View File
@@ -0,0 +1,112 @@
#include "vendors/perplexity/sonar_result.h"
#include "llm/error.h"
#include "vendors/perplexity/caps.h"
namespace molo::perplexity {
namespace {
// content is a string or an array of typed parts; only text parts are text.
std::string flatten(const Json* content) {
if (!content) return "";
if (content->is_string()) return content->as_string();
std::string out;
if (content->is_array())
for (const Json& p : content->as_array())
if (J::str(p, "type") == "text") out += J::str(p, "text");
return out;
}
void read_extras(SonarResult& r, const Json& doc) {
if (J::arr(doc, "citations")) r.citations = J::strings(doc, "citations");
if (const Json* sr = J::arr(doc, "search_results")) r.search_results = WebResult::parse_list(sr);
if (const Json* im = J::arr(doc, "images")) {
r.images.clear();
for (const Json& i : im->as_array()) r.images.push_back(ImageResult::parse(i));
}
if (J::arr(doc, "related_questions")) r.related_questions = J::strings(doc, "related_questions");
if (const Json* u = J::obj(doc, "usage")) r.usage = SonarUsage::parse(u);
}
} // namespace
SonarResult SonarResult::parse(const Json& doc) {
SonarResult r;
r.raw = doc;
r.id = J::str(doc, "id");
r.model = J::str(doc, "model");
r.object = J::str(doc, "object");
r.created = J::num(doc, "created");
if (const Json* cs = J::arr(doc, "choices"))
for (const Json& c : cs->as_array()) {
if (r.choices.size() >= PerplexityCaps::kMaxChoices) {
r.truncated = true;
break;
}
SonarChoice ch;
ch.index = static_cast<int>(J::num(c, "index"));
ch.finish_reason = J::str(c, "finish_reason");
if (const Json* m = J::obj(c, "message")) {
ch.message = *m;
ch.role = J::str(*m, "role");
ch.content = flatten(m->find("content"));
}
r.choices.push_back(std::move(ch));
}
read_extras(r, doc);
return r;
}
const SonarChoice& SonarResult::first() const {
if (choices.empty()) throw llm::ApiError("perplexity", 502, "BAD_RESPONSE", "response has no choices");
return choices[0];
}
std::string SonarResult::citation_url(int n) const {
if (n < 1 || static_cast<std::size_t>(n) > citations.size()) return "";
return citations[static_cast<std::size_t>(n) - 1];
}
SonarDelta SonarStreamFolder::feed(const Json& chunk) {
++chunks_;
SonarDelta d;
if (acc_.id.empty()) acc_.id = J::str(chunk, "id");
if (acc_.model.empty()) acc_.model = J::str(chunk, "model");
if (acc_.object.empty()) acc_.object = J::str(chunk, "object");
if (!acc_.created) acc_.created = J::num(chunk, "created");
read_extras(acc_, chunk);
d.has_usage = J::obj(chunk, "usage") != nullptr;
if (d.has_usage) d.usage = acc_.usage;
if (const Json* cs = J::arr(chunk, "choices"))
for (const Json& c : cs->as_array()) {
if (static_cast<int>(J::num(c, "index")) != 0) continue; // only the first choice is folded
if (const Json* delta = J::obj(c, "delta")) {
if (role_.empty()) role_ = J::str(*delta, "role");
d.content += flatten(delta->find("content"));
}
std::string fr = J::str(c, "finish_reason");
if (!fr.empty()) {
d.finish_reason = fr;
finish_ = fr;
}
}
content_ += d.content;
// The schema also names a chunk type end_of_stream (CompletionResponseType).
if (J::str(chunk, "type") == "end_of_stream") d.final_chunk = true;
if (!d.finish_reason.empty()) d.final_chunk = true;
if (d.final_chunk) done_ = true;
return d;
}
SonarResult SonarStreamFolder::result() const {
SonarResult r = acc_;
SonarChoice c;
c.index = 0;
c.finish_reason = finish_;
c.role = role_.empty() ? "assistant" : role_;
c.content = content_;
r.choices.clear();
r.choices.push_back(c);
return r;
}
} // namespace molo::perplexity
+69
View File
@@ -0,0 +1,69 @@
#pragma once
// Response side of Sonar chat completions: CompletionResponse (id, model,
// created, choices, citations, search_results, images, related_questions,
// usage) and the stream folder.
#include <string>
#include <vector>
#include "vendors/perplexity/types.h"
namespace molo::perplexity {
struct SonarChoice {
int index = 0;
std::string finish_reason; // stop | length | "" (null)
std::string role;
std::string content; // text, parts flattened
Json message; // the complete message (non-streaming)
};
struct SonarResult {
std::string id, model, object;
long created = 0;
std::vector<SonarChoice> choices;
std::vector<std::string> citations; // URLs; [n] markers in the text are 1-based indices
std::vector<WebResult> search_results;
std::vector<ImageResult> images;
std::vector<std::string> related_questions;
SonarUsage usage;
bool truncated = false; // more choices than the cap kept
Json raw;
static SonarResult parse(const Json& doc);
const SonarChoice& first() const;
std::string text() const { return choices.empty() ? "" : choices[0].content; }
// URL for a citation marker "[n]" (1-based); "" when out of range.
std::string citation_url(int n) const;
};
// One decoded stream chunk, reduced to what a consumer needs.
struct SonarDelta {
std::string content;
std::string finish_reason;
SonarUsage usage; // set when has_usage
bool has_usage = false;
bool final_chunk = false; // carries finish_reason or the documented end_of_stream type
};
// Folds chunks into one SonarResult. Perplexity chunks are CompletionResponse
// documents whose choices carry `delta`; citations, search_results, images,
// related_questions and usage arrive on later chunks and the latest wins.
class SonarStreamFolder {
public:
SonarDelta feed(const Json& chunk);
bool done() const { return done_; }
std::size_t chunks() const { return chunks_; }
SonarResult result() const;
private:
SonarResult acc_;
std::string content_;
std::string finish_;
std::string role_;
bool done_ = false;
std::size_t chunks_ = 0;
};
} // namespace molo::perplexity
+225
View File
@@ -0,0 +1,225 @@
#!/usr/bin/env python3
"""Check src/vendors/perplexity/calls.cpp against Perplexity's published OpenAPI documents.
Perplexity publishes five OpenAPI documents (linked from llms.txt):
openapi https://docs.perplexity.ai/openapi.json
auth https://docs.perplexity.ai/openapi-auth.json
gateway-chat https://docs.perplexity.ai/openapi-gateway-chat.json
gateway-messages https://docs.perplexity.ai/openapi-gateway-messages.json
gateway-responses https://docs.perplexity.ai/openapi-gateway-responses.json
and the official Python SDK pins a sixth (Stainless) document in .stats.yml.
This checker fetches them and fails (exit 1) when:
row a declared call is absent from its document (method, path, operationId);
field a request body field or query parameter we send, or a response field we
read, is not a field of the schema / operation;
response a declared response schema does not exist;
coverage an operation of the five documents is neither a table row nor in
EXCLUDED_OPERATIONS, or a request field / query parameter of a table row's
operation is neither declared nor in EXCLUDED_FIELDS;
sdk an operation of the SDK document is neither an alias of a table row
(SDK_ALIASES) nor in SDK_EXCLUDED.
Python 3 stdlib only, no credentials, network required.
python3 -I src/vendors/perplexity/tools/check_spec.py [alternative calls.cpp]
"""
import json
import os
import re
import sys
import urllib.request
HERE = os.path.dirname(os.path.abspath(__file__))
CALLS = os.path.join(HERE, "..", "calls.cpp")
BASE = "https://docs.perplexity.ai/"
DOCS = {
"openapi": "openapi.json",
"auth": "openapi-auth.json",
"gateway-chat": "openapi-gateway-chat.json",
"gateway-messages": "openapi-gateway-messages.json",
"gateway-responses": "openapi-gateway-responses.json",
}
STATS = "https://raw.githubusercontent.com/perplexityai/perplexity-py/main/.stats.yml"
STR = re.compile(r'"([^"]*)"')
# Operations deliberately not wrapped: none today (every operation is a table row).
EXCLUDED_OPERATIONS = {}
# Request fields / query params of wrapped operations that we deliberately never send.
EXCLUDED_FIELDS = {
("gateway-messages", "POST", "/orchestrator/v1/messages"): {
"container": "rejected by Perplexity validation (no code-execution containers)",
"inference_geo": "rejected by Perplexity validation",
"mcp_servers": "rejected by Perplexity validation",
"fallbacks": "rejected by Perplexity validation",
"fallback_credit_token": "rejected by Perplexity validation",
},
}
# SDK paths that are aliases of a table row (same operation, older path).
SDK_ALIASES = {
("POST", "/chat/completions"): "/v1/sonar",
("POST", "/async/chat/completions"): "/v1/async/sonar",
("GET", "/async/chat/completions"): "/v1/async/sonar",
("GET", "/async/chat/completions/{api_request}"): "/v1/async/sonar/{api_request}",
("POST", "/v1/responses"): "/v1/agent",
("GET", "/v1/responses/{response_id}"): "/v1/agent/{id}",
("GET", "/v1/responses/{response_id}/files"): "/v1/agent/{id}/files",
("GET", "/v1/responses/{response_id}/files/{file_id}/content"): "/v1/agent/{id}/files/{file_id}/content",
("POST", "/v1/responses/{response_id}/cancel"): "/v1/agent/{id}/cancel",
("POST", "/search"): "/search",
("POST", "/v1/embeddings"): "/v1/embeddings",
("POST", "/v1/contextualizedembeddings"): "/v1/contextualizedembeddings",
}
SDK_EXCLUDED = {
("POST", "/v1/browser/sessions"): "in the SDK document only; api.perplexity.ai answers 404 (probe 2026-10-25)",
("DELETE", "/v1/browser/sessions/{session_id}"): "in the SDK document only; same host answers 404 for the family",
}
def fetch(url):
req = urllib.request.Request(url, headers={"User-Agent": "molo-perplexity-spec-check/1"})
with urllib.request.urlopen(req, timeout=90) as r:
return r.read().decode("utf-8", "replace")
def rows(text, begin, end):
a, b = text.index(begin), text.index(end)
out = []
for line in text[a:b].splitlines()[1:]:
s = line.strip()
if s.startswith("{") and '"' in s:
out.append(STR.findall(s))
return out
class Doc:
def __init__(self, data):
self.d = data
self.schemas = data.get("components", {}).get("schemas", {})
self.params = data.get("components", {}).get("parameters", {})
self.bodies = data.get("components", {}).get("requestBodies", {})
def ops(self):
for path, item in self.d["paths"].items():
for method, op in item.items():
if isinstance(op, dict) and "responses" in op:
yield method.upper(), path, op, item
def resolve(self, s):
while isinstance(s, dict) and "$ref" in s:
s = self.schemas[s["$ref"].split("/")[-1]]
return s
def props(self, s):
"""Flattened property names of a schema (allOf / $ref resolved)."""
s = self.resolve(s)
out = set(s.get("properties", {}))
for sub in s.get("allOf", []):
out |= self.props(sub)
return out
def op_params(self, op, item):
out = []
for p in op.get("parameters", []) + item.get("parameters", []):
if "$ref" in p:
p = self.params[p["$ref"].split("/")[-1]]
out.append(p)
return out
def body_fields(self, op):
rb = op.get("requestBody")
if not rb:
return set()
if "$ref" in rb:
rb = self.bodies[rb["$ref"].split("/")[-1]]
for ct, c in rb.get("content", {}).items():
return self.props(c.get("schema", {}))
return set()
def norm(path):
return re.sub(r"\{[^}]*\}", "{}", path)
def main():
text = open(sys.argv[1] if len(sys.argv) > 1 else CALLS).read()
calls = rows(text, "// CALLS-BEGIN", "// CALLS-END")
schemas = rows(text, "// SCHEMAS-BEGIN", "// SCHEMAS-END")
docs = {k: Doc(json.loads(fetch(BASE + v))) for k, v in DOCS.items()}
bad = []
seen_ops = set()
for method, path, spec, opid, body, query, response in calls:
doc = docs[spec]
found = None
for m, p, op, item in doc.ops():
if m == method and p == path:
found = (op, item)
if not found:
bad.append("%s %s: not in %s" % (method, path, spec))
continue
op, item = found
seen_ops.add((spec, method, path))
if op.get("operationId") != opid:
bad.append("%s %s: operationId %r, table says %r" % (method, path, op.get("operationId"), opid))
have_body = doc.body_fields(op)
have_query = {p["name"] for p in doc.op_params(op, item) if p.get("in") == "query"}
excluded = EXCLUDED_FIELDS.get((spec, method, path), {})
mine_body = set(filter(None, body.split(",")))
mine_query = set(filter(None, query.split(",")))
for f in sorted(mine_body - have_body):
bad.append("%s %s: body field %s absent in %s" % (method, path, f, spec))
for q in sorted(mine_query - have_query):
bad.append("%s %s: query parameter %s absent in %s" % (method, path, q, spec))
for f in sorted(have_body - mine_body - set(excluded)):
bad.append("%s %s: spec body field %s is neither sent nor excluded" % (method, path, f))
for q in sorted(have_query - mine_query - set(excluded)):
bad.append("%s %s: spec query parameter %s is neither sent nor excluded" % (method, path, q))
if response not in ("-", "binary") and response not in doc.schemas:
bad.append("%s %s: response schema %s absent in %s" % (method, path, response, spec))
for name, spec, fields in schemas:
doc = docs[spec]
if name not in doc.schemas:
bad.append("schema %s absent in %s" % (name, spec))
continue
have = doc.props(doc.schemas[name])
for f in filter(None, fields.split(",")):
if f not in have:
bad.append("schema %s: field %s absent in %s" % (name, f, spec))
total_ops = 0
for spec, doc in docs.items():
for m, p, op, item in doc.ops():
total_ops += 1
if (spec, m, p) not in seen_ops and (spec, m, p) not in EXCLUDED_OPERATIONS:
bad.append("unwrapped operation %s %s %s (%s)" % (spec, m, p, op.get("operationId")))
# SDK document pinned by the official Python SDK
stats = fetch(STATS)
url = re.search(r"openapi_spec_url:\s*(\S+)", stats).group(1)
sdk = Doc(json.loads(fetch(url)))
table_paths = {(c[0], c[1]) for c in calls}
sdk_ops = 0
for m, p, op, item in sdk.ops():
sdk_ops += 1
if (m, p) in table_paths:
continue
if (m, p) in SDK_ALIASES:
alias = SDK_ALIASES[(m, p)]
if (m, alias) not in table_paths:
bad.append("sdk alias %s %s points at %s which is not a table row" % (m, p, alias))
continue
if (m, p) in SDK_EXCLUDED:
continue
bad.append("sdk operation %s %s is neither a table row, an alias nor excluded" % (m, p))
if bad:
print("SPEC CHECK FAILED")
for b in bad:
print(" " + b)
return 1
print("perplexity spec ok: %d calls, %d schemas, %d operations in %d documents all covered "
"(exclusions: %d operations, %d field groups), sdk document: %d operations (%d aliases, %d excluded)"
% (len(calls), len(schemas), total_ops, len(docs), len(EXCLUDED_OPERATIONS), len(EXCLUDED_FIELDS),
sdk_ops, len(SDK_ALIASES), len(SDK_EXCLUDED)))
return 0
if __name__ == "__main__":
sys.exit(main())
+139
View File
@@ -0,0 +1,139 @@
#include "vendors/perplexity/types.h"
#include "vendors/perplexity/caps.h"
namespace molo::perplexity {
std::string J::str(const Json& doc, const char* key, const std::string& fallback) {
const Json* v = doc.is_object() ? doc.find(key) : nullptr;
return v && v->is_string() ? v->as_string() : fallback;
}
long J::num(const Json& doc, const char* key, long fallback) {
const Json* v = doc.is_object() ? doc.find(key) : nullptr;
return v && v->is_number() ? v->as_int() : fallback;
}
double J::dbl(const Json& doc, const char* key, double fallback) {
const Json* v = doc.is_object() ? doc.find(key) : nullptr;
return v && v->is_number() ? v->as_number() : fallback;
}
bool J::flag(const Json& doc, const char* key, bool fallback) {
const Json* v = doc.is_object() ? doc.find(key) : nullptr;
return v && v->is_bool() ? v->as_bool() : fallback;
}
const Json* J::obj(const Json& doc, const char* key) {
const Json* v = doc.is_object() ? doc.find(key) : nullptr;
return v && v->is_object() ? v : nullptr;
}
const Json* J::arr(const Json& doc, const char* key) {
const Json* v = doc.is_object() ? doc.find(key) : nullptr;
return v && v->is_array() ? v : nullptr;
}
std::vector<std::string> J::strings(const Json& doc, const char* key) {
std::vector<std::string> out;
if (const Json* a = arr(doc, key))
for (const Json& v : a->as_array())
if (v.is_string()) out.push_back(v.as_string());
return out;
}
Cost Cost::parse(const Json* cost) {
Cost c;
if (!cost || !cost->is_object()) return c;
c.input_tokens = J::dbl(*cost, "input_tokens_cost");
c.output_tokens = J::dbl(*cost, "output_tokens_cost");
c.reasoning_tokens = J::dbl(*cost, "reasoning_tokens_cost");
c.request = J::dbl(*cost, "request_cost");
c.citation_tokens = J::dbl(*cost, "citation_tokens_cost");
c.search_queries = J::dbl(*cost, "search_queries_cost");
c.total = J::dbl(*cost, "total_cost");
return c;
}
SonarUsage SonarUsage::parse(const Json* usage) {
SonarUsage u;
if (!usage || !usage->is_object()) return u;
u.present = true;
u.prompt_tokens = static_cast<int>(J::num(*usage, "prompt_tokens"));
u.completion_tokens = static_cast<int>(J::num(*usage, "completion_tokens"));
u.total_tokens = static_cast<int>(J::num(*usage, "total_tokens"));
u.citation_tokens = static_cast<int>(J::num(*usage, "citation_tokens"));
u.reasoning_tokens = static_cast<int>(J::num(*usage, "reasoning_tokens"));
u.num_search_queries = static_cast<int>(J::num(*usage, "num_search_queries"));
u.search_context_size = J::str(*usage, "search_context_size");
u.cost = Cost::parse(J::obj(*usage, "cost"));
return u;
}
WebResult WebResult::parse(const Json& doc) {
WebResult r;
r.title = J::str(doc, "title");
r.url = J::str(doc, "url");
r.date = J::str(doc, "date");
r.last_updated = J::str(doc, "last_updated");
r.snippet = J::str(doc, "snippet");
r.source = J::str(doc, "source");
return r;
}
std::vector<WebResult> WebResult::parse_list(const Json* list) {
std::vector<WebResult> out;
if (!list || !list->is_array()) return out;
for (const Json& v : list->as_array()) {
if (out.size() >= PerplexityCaps::kMaxItemsReturned) break;
out.push_back(parse(v));
}
return out;
}
ImageResult ImageResult::parse(const Json& doc) {
ImageResult r;
r.image_url = J::str(doc, "image_url");
r.origin_url = J::str(doc, "origin_url");
r.title = J::str(doc, "title");
r.height = J::num(doc, "height");
r.width = J::num(doc, "width");
return r;
}
ModelInfo ModelInfo::parse(const Json& doc) {
ModelInfo m;
m.id = J::str(doc, "id");
m.owned_by = J::str(doc, "owned_by");
m.created = J::num(doc, "created");
if (const Json* p = J::obj(doc, "pricing")) {
m.pricing.present = true;
m.pricing.input = J::dbl(*p, "input");
m.pricing.output = J::dbl(*p, "output");
m.pricing.cache_write = J::dbl(*p, "cache_write");
m.pricing.cache_read = J::dbl(*p, "cache_read");
m.pricing.unit = J::str(*p, "unit");
}
return m;
}
std::string ModelInfo::provider() const {
std::size_t slash = id.find('/');
return slash == std::string::npos ? "" : id.substr(0, slash);
}
ModelList ModelList::parse(const Json& doc) {
ModelList l;
l.raw = doc;
if (const Json* data = J::arr(doc, "data"))
for (const Json& m : data->as_array()) {
if (l.models.size() >= PerplexityCaps::kMaxModelsReturned) {
l.truncated = true;
break;
}
l.models.push_back(ModelInfo::parse(m));
}
return l;
}
const ModelInfo* ModelList::find(const std::string& id) const {
for (const ModelInfo& m : models)
if (m.id == id) return &m;
return nullptr;
}
} // namespace molo::perplexity
+81
View File
@@ -0,0 +1,81 @@
#pragma once
// Typed views of Perplexity documents shared by several services: usage and
// cost, search results, images, models. Every parser reads only fields the
// OpenAPI schemas declare; the full document stays available as `raw`.
#include <optional>
#include <string>
#include <vector>
#include "clients/body/json.h"
namespace molo::perplexity {
using Json = clients::body::Json;
// Tolerant readers: a missing or mistyped field gives the fallback.
struct J {
static std::string str(const Json& doc, const char* key, const std::string& fallback = "");
static long num(const Json& doc, const char* key, long fallback = 0);
static double dbl(const Json& doc, const char* key, double fallback = 0.0);
static bool flag(const Json& doc, const char* key, bool fallback = false);
static const Json* obj(const Json& doc, const char* key);
static const Json* arr(const Json& doc, const char* key);
static std::vector<std::string> strings(const Json& doc, const char* key);
};
// Sonar usage.cost (USD).
struct Cost {
double input_tokens = 0, output_tokens = 0, reasoning_tokens = 0, request = 0, citation_tokens = 0,
search_queries = 0, total = 0;
static Cost parse(const Json* cost);
};
// Sonar / async usage (UsageInfo).
struct SonarUsage {
int prompt_tokens = 0, completion_tokens = 0, total_tokens = 0, citation_tokens = 0, reasoning_tokens = 0,
num_search_queries = 0;
std::string search_context_size;
Cost cost;
bool present = false;
static SonarUsage parse(const Json* usage);
};
// ApiPublicSearchResult (Sonar search_results, fetch contents).
struct WebResult {
std::string title, url, date, last_updated, snippet, source;
static WebResult parse(const Json& doc);
static std::vector<WebResult> parse_list(const Json* list);
};
struct ImageResult {
std::string image_url, origin_url, title;
long height = 0, width = 0;
static ImageResult parse(const Json& doc);
};
struct ModelPricing {
double input = 0, output = 0, cache_write = 0, cache_read = 0;
std::string unit;
bool present = false;
};
struct ModelInfo {
std::string id, owned_by;
long created = 0;
ModelPricing pricing; // Orchestrator models only
static ModelInfo parse(const Json& doc);
// "provider/name" -> "provider"; "" when the id has no prefix.
std::string provider() const;
};
struct ModelList {
std::vector<ModelInfo> models;
bool truncated = false;
Json raw;
static ModelList parse(const Json& doc);
const ModelInfo* find(const std::string& id) const;
};
} // namespace molo::perplexity