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