From 3404392887134107ffd64bc63beca86dc77aed4c Mon Sep 17 00:00:00 2001 From: retoor Date: Sun, 25 Oct 2026 15:01:55 +0100 Subject: [PATCH] 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 --- example/app/ai/PerplexityDemo.cpp | 897 +++++++++++++++++- example/assets/ai_perplexity.js | 58 ++ src/vendors/perplexity/SPEC.md | 271 ++++++ src/vendors/perplexity/account.cpp | 151 +++ src/vendors/perplexity/account.h | 73 ++ src/vendors/perplexity/agent.cpp | 83 ++ src/vendors/perplexity/agent.h | 45 + src/vendors/perplexity/agent_params.cpp | 401 ++++++++ src/vendors/perplexity/agent_params.h | 95 ++ src/vendors/perplexity/agent_result.cpp | 228 +++++ src/vendors/perplexity/agent_result.h | 121 +++ src/vendors/perplexity/batches.cpp | 209 ++++ src/vendors/perplexity/batches.h | 90 ++ src/vendors/perplexity/calls.cpp | 185 ++++ src/vendors/perplexity/calls.h | 68 ++ src/vendors/perplexity/caps.h | 65 ++ src/vendors/perplexity/chat_model.cpp | 121 +++ src/vendors/perplexity/chat_model.h | 48 + src/vendors/perplexity/decisions.cpp | 102 ++ src/vendors/perplexity/decisions.h | 57 ++ src/vendors/perplexity/embeddings.cpp | 164 ++++ src/vendors/perplexity/embeddings.h | 88 ++ src/vendors/perplexity/errors.cpp | 79 ++ src/vendors/perplexity/errors.h | 46 + src/vendors/perplexity/orchestrator.cpp | 141 +++ src/vendors/perplexity/orchestrator.h | 46 + src/vendors/perplexity/platform.cpp | 26 + src/vendors/perplexity/platform.h | 27 + src/vendors/perplexity/rules.cpp | 132 +++ src/vendors/perplexity/rules.h | 45 + src/vendors/perplexity/search.cpp | 102 ++ src/vendors/perplexity/search.h | 51 + src/vendors/perplexity/skills.cpp | 141 +++ src/vendors/perplexity/skills.h | 62 ++ src/vendors/perplexity/sonar.cpp | 129 +++ src/vendors/perplexity/sonar.h | 65 ++ src/vendors/perplexity/sonar_params.cpp | 292 ++++++ src/vendors/perplexity/sonar_params.h | 99 ++ src/vendors/perplexity/sonar_result.cpp | 112 +++ src/vendors/perplexity/sonar_result.h | 69 ++ src/vendors/perplexity/tools/check_spec.py | 225 +++++ src/vendors/perplexity/types.cpp | 139 +++ src/vendors/perplexity/types.h | 81 ++ tests/example/ai/perplexity/page_test.cpp | 33 + tests/example/ai/perplexity/routes_test.cpp | 105 ++ tests/src/vendors/perplexity/support.h | 52 + tests/src/vendors/perplexity/test_agent.cpp | 228 +++++ tests/src/vendors/perplexity/test_live.cpp | 75 ++ .../vendors/perplexity/test_model_tables.cpp | 194 ++++ .../src/vendors/perplexity/test_platform.cpp | 345 +++++++ .../vendors/perplexity/test_search_embed.cpp | 196 ++++ tests/src/vendors/perplexity/test_sonar.cpp | 247 +++++ 52 files changed, 7201 insertions(+), 3 deletions(-) create mode 100644 example/assets/ai_perplexity.js create mode 100644 src/vendors/perplexity/SPEC.md create mode 100644 src/vendors/perplexity/account.cpp create mode 100644 src/vendors/perplexity/account.h create mode 100644 src/vendors/perplexity/agent.cpp create mode 100644 src/vendors/perplexity/agent.h create mode 100644 src/vendors/perplexity/agent_params.cpp create mode 100644 src/vendors/perplexity/agent_params.h create mode 100644 src/vendors/perplexity/agent_result.cpp create mode 100644 src/vendors/perplexity/agent_result.h create mode 100644 src/vendors/perplexity/batches.cpp create mode 100644 src/vendors/perplexity/batches.h create mode 100644 src/vendors/perplexity/calls.cpp create mode 100644 src/vendors/perplexity/calls.h create mode 100644 src/vendors/perplexity/caps.h create mode 100644 src/vendors/perplexity/chat_model.cpp create mode 100644 src/vendors/perplexity/chat_model.h create mode 100644 src/vendors/perplexity/decisions.cpp create mode 100644 src/vendors/perplexity/decisions.h create mode 100644 src/vendors/perplexity/embeddings.cpp create mode 100644 src/vendors/perplexity/embeddings.h create mode 100644 src/vendors/perplexity/errors.cpp create mode 100644 src/vendors/perplexity/errors.h create mode 100644 src/vendors/perplexity/orchestrator.cpp create mode 100644 src/vendors/perplexity/orchestrator.h create mode 100644 src/vendors/perplexity/platform.cpp create mode 100644 src/vendors/perplexity/platform.h create mode 100644 src/vendors/perplexity/rules.cpp create mode 100644 src/vendors/perplexity/rules.h create mode 100644 src/vendors/perplexity/search.cpp create mode 100644 src/vendors/perplexity/search.h create mode 100644 src/vendors/perplexity/skills.cpp create mode 100644 src/vendors/perplexity/skills.h create mode 100644 src/vendors/perplexity/sonar.cpp create mode 100644 src/vendors/perplexity/sonar.h create mode 100644 src/vendors/perplexity/sonar_params.cpp create mode 100644 src/vendors/perplexity/sonar_params.h create mode 100644 src/vendors/perplexity/sonar_result.cpp create mode 100644 src/vendors/perplexity/sonar_result.h create mode 100644 src/vendors/perplexity/tools/check_spec.py create mode 100644 src/vendors/perplexity/types.cpp create mode 100644 src/vendors/perplexity/types.h create mode 100644 tests/example/ai/perplexity/page_test.cpp create mode 100644 tests/example/ai/perplexity/routes_test.cpp create mode 100644 tests/src/vendors/perplexity/support.h create mode 100644 tests/src/vendors/perplexity/test_agent.cpp create mode 100644 tests/src/vendors/perplexity/test_live.cpp create mode 100644 tests/src/vendors/perplexity/test_model_tables.cpp create mode 100644 tests/src/vendors/perplexity/test_platform.cpp create mode 100644 tests/src/vendors/perplexity/test_search_embed.cpp create mode 100644 tests/src/vendors/perplexity/test_sonar.cpp diff --git a/example/app/ai/PerplexityDemo.cpp b/example/app/ai/PerplexityDemo.cpp index a1e4ef2..c562289 100644 --- a/example/app/ai/PerplexityDemo.cpp +++ b/example/app/ai/PerplexityDemo.cpp @@ -1,13 +1,904 @@ #include "../AiDemos.hpp" +#include + #include "../../fw/Router.hpp" +#include "../../fw/Templates.hpp" +#include "security/crypto/Base64.h" +#include "vendors/perplexity/account.h" +#include "vendors/perplexity/agent.h" +#include "vendors/perplexity/batches.h" +#include "vendors/perplexity/calls.h" +#include "vendors/perplexity/caps.h" +#include "vendors/perplexity/decisions.h" +#include "vendors/perplexity/embeddings.h" +#include "vendors/perplexity/errors.h" +#include "vendors/perplexity/orchestrator.h" +#include "vendors/perplexity/platform.h" +#include "vendors/perplexity/rules.h" +#include "vendors/perplexity/search.h" +#include "vendors/perplexity/skills.h" +#include "vendors/perplexity/sonar.h" namespace molo::example::app { -// perplexity. Stub: the package agent fills this in. +// Perplexity API platform over the real src/vendors/perplexity part. GET routes +// need no credential. Every route that calls Perplexity is a POST: 422 on bad +// input, 503 perplexity_not_configured without PERPLEXITY_API_KEY. Routes that +// cost money (Sonar, Search, Agent, embeddings, decisions, orchestrator, batch +// create) or change resources (cancel, delete, upload) are dry runs that show +// the exact request unless the body has "confirm":true. + +namespace { + +namespace pp = perplexity; +using Json = clients::body::Json; + +constexpr std::size_t kMaxBody = 8 * 1024 * 1024; // uploads travel as base64 + +const char kPage[] = R"PERPLEXITY({% extends "base.html" %} +{% block content %} +

Perplexity API

+

Sonar chat (search options, citations, structured output, streaming, async), Search API, +embeddings, Agent API (tools, skills, background), Decisions, Orchestrator, batches, skills, models, usage. +Paid and destructive calls are dry runs until the body says "confirm":true.

+

Checking credential...

+
+ + +
+ + +
+ +

+
+ + +{% endblock %} +)PERPLEXITY"; + +[[noreturn]] void bad(const std::string& why) { throw fw::HttpError(422, "validation_error", why); } + +fw::Response json_out(const Json& j, int status = 200) { + fw::Response res = fw::JsonResponse(j.dump(), status); + res.headers.set("Cache-Control", "no-store"); + return res; +} + +Json parse_body(const fw::Request& req) { + if (req.body.size() > kMaxBody) throw fw::HttpError(413, "payload_too_large", "body too large"); + if (req.body.empty()) return Json::object(); + try { + Json j = Json::parse(req.body); + if (!j.is_object()) bad("body must be a JSON object"); + return j; + } catch (const clients::body::JsonError&) { + bad("body is not valid JSON"); + } +} + +std::string text(const Json& b, const char* key, bool required = false) { + const Json* v = b.find(key); + if (!v || v->is_null()) { + if (required) bad(std::string(key) + " is required"); + return ""; + } + if (!v->is_string()) bad(std::string(key) + " must be a string"); + return v->as_string(); +} + +std::optional number(const Json& b, const char* key) { + const Json* v = b.find(key); + if (!v || v->is_null()) return std::nullopt; + if (!v->is_number()) bad(std::string(key) + " must be a number"); + return static_cast(v->as_int()); +} + +std::optional real(const Json& b, const char* key) { + const Json* v = b.find(key); + if (!v || v->is_null()) return std::nullopt; + if (!v->is_number()) bad(std::string(key) + " must be a number"); + return v->as_number(); +} + +bool flag(const Json& b, const char* key) { + const Json* v = b.find(key); + if (!v || v->is_null()) return false; + if (!v->is_bool()) bad(std::string(key) + " must be true or false"); + return v->as_bool(); +} + +std::optional opt_flag(const Json& b, const char* key) { + const Json* v = b.find(key); + if (!v || v->is_null()) return std::nullopt; + if (!v->is_bool()) bad(std::string(key) + " must be true or false"); + return v->as_bool(); +} + +std::vector strings(const Json& b, const char* key) { + std::vector out; + const Json* v = b.find(key); + if (!v || v->is_null()) return out; + if (!v->is_array()) bad(std::string(key) + " must be an array of strings"); + for (const Json& s : v->as_array()) { + if (!s.is_string()) bad(std::string(key) + " must be an array of strings"); + out.push_back(s.as_string()); + } + return out; +} + +Json strs(const std::vector& v) { + Json a = Json::array(); + for (const std::string& s : v) a.push(Json(s)); + return a; +} + +Json sonar_json(const pp::SonarResult& r) { + Json o = Json::object(); + o.set("id", Json(r.id)); + o.set("model", Json(r.model)); + if (!r.choices.empty()) { + o.set("finish_reason", Json(r.first().finish_reason)); + o.set("content", Json(r.first().content)); + } + o.set("citations", strs(r.citations)); + Json results = Json::array(); + for (const pp::WebResult& w : r.search_results) { + Json x = Json::object(); + x.set("title", Json(w.title)); + x.set("url", Json(w.url)); + x.set("date", Json(w.date)); + results.push(x); + } + o.set("search_results", results); + o.set("related_questions", strs(r.related_questions)); + Json u = Json::object(); + u.set("prompt_tokens", Json(r.usage.prompt_tokens)); + u.set("completion_tokens", Json(r.usage.completion_tokens)); + u.set("total_tokens", Json(r.usage.total_tokens)); + u.set("reasoning_tokens", Json(r.usage.reasoning_tokens)); + u.set("num_search_queries", Json(r.usage.num_search_queries)); + u.set("total_cost_usd", Json(r.usage.cost.total)); + o.set("usage", u); + return o; +} + +Json agent_json(const pp::AgentResult& r) { + Json o = Json::object(); + o.set("id", Json(r.id)); + o.set("status", Json(r.status)); + o.set("model", Json(r.model)); + o.set("output_text", Json(r.output_text())); + o.set("queries", strs(r.queries())); + Json results = Json::array(); + for (const pp::AgentSearchResult& s : r.search_results()) { + Json x = Json::object(); + x.set("id", Json(static_cast(s.id))); + x.set("title", Json(s.title)); + x.set("url", Json(s.url)); + results.push(x); + } + o.set("search_results", results); + Json calls = Json::array(); + for (const pp::AgentFunctionCall& c : r.function_calls()) { + Json x = Json::object(); + x.set("call_id", Json(c.call_id)); + x.set("name", Json(c.name)); + x.set("arguments", Json(c.arguments)); + calls.push(x); + } + o.set("function_calls", calls); + if (r.error.present()) o.set("error", Json(r.error.message)); + if (r.has_pause) o.set("paused", Json(r.pause.window)); + Json u = Json::object(); + u.set("input_tokens", Json(static_cast(r.usage.input_tokens))); + u.set("output_tokens", Json(static_cast(r.usage.output_tokens))); + u.set("total_cost_usd", Json(r.usage.cost.total)); + o.set("usage", u); + return o; +} + +Json dry_run(const Json& request, const std::string& path) { + Json o = Json::object(); + o.set("dry_run", Json(true)); + o.set("would_send_to", Json(path)); + o.set("request", request); + o.set("hint", Json("send confirm:true to run it")); + return o; +} + +pp::SonarParams sonar_params(const Json& b) { + pp::SonarParams p; + std::string model = text(b, "model"); + if (!model.empty()) p.model = model; + std::string system = text(b, "system"); + if (!system.empty()) p.add(pp::Messages::system(system)); + p.add(pp::Messages::user(text(b, "prompt", true))); + p.max_tokens = number(b, "max_tokens"); + p.temperature = real(b, "temperature"); + p.top_p = real(b, "top_p"); + p.search_mode = text(b, "search_mode"); + p.search_domain_filter = strings(b, "search_domain_filter"); + p.search_language_filter = strings(b, "search_language_filter"); + p.search_recency_filter = text(b, "search_recency_filter"); + p.search_after_date_filter = text(b, "search_after_date_filter"); + p.search_before_date_filter = text(b, "search_before_date_filter"); + p.return_images = opt_flag(b, "return_images"); + p.return_related_questions = opt_flag(b, "return_related_questions"); + p.disable_search = opt_flag(b, "disable_search"); + p.reasoning_effort = text(b, "reasoning_effort"); + p.language_preference = text(b, "language_preference"); + p.web_search_options.search_context_size = text(b, "search_context_size"); + p.web_search_options.search_type = text(b, "search_type"); + p.web_search_options.user_location.country = text(b, "country"); + if (const Json* schema = b.find("json_schema"); schema && !schema->is_null()) { + if (!schema->is_object()) bad("json_schema must be a JSON Schema object"); + p.response_format = pp::StructuredOutput::json_schema(*schema, text(b, "schema_name")); + } + return p; +} + +// One route = validate into a Plan, then the generic runner decides dry run, +// credential, call and error mapping. +struct Plan { + Json request; // what would be sent (shown in a dry run) + std::string path; // for the dry-run message + bool needs_confirm = false; // paid or changes a resource + std::function call; +}; + +class PerplexityRoutes { + public: + explicit PerplexityRoutes(pp::Platform platform) : p_(std::move(platform)) {} + const pp::Platform& platform() const { return p_; } + + using Planner = std::function; + + fw::Response run(const fw::Request& req, const Planner& planner) const { + Json body = parse_body(req); + Plan plan; + try { + plan = planner(body); + } catch (const llm::ApiError& e) { + map(e); + } + if (plan.needs_confirm && !flag(body, "confirm")) return json_out(dry_run(plan.request, plan.path)); + try { + return json_out(plan.call()); + } catch (const llm::ApiError& e) { + map(e); + } + } + + // ---- planners ----------------------------------------------------------- + Plan sonar(const Json& b) const { + pp::SonarParams params = sonar_params(b); + Plan pl{params.to_json(false), "/v1/sonar", true, nullptr}; + auto api = std::make_shared(p_.client); + pl.call = [api, params] { return sonar_json(api->create(params)); }; + return pl; + } + Plan stream(const Json& b) const { + pp::SonarParams params = sonar_params(b); + Plan pl{params.to_json(true), "/v1/sonar", true, nullptr}; + auto api = std::make_shared(p_.client); + pl.call = [api, params] { + std::size_t chunks = 0; + pp::SonarResult r = api->stream(params, [&](const pp::SonarDelta&) { return ++chunks < pp::PerplexityCaps::kMaxStreamEvents; }); + Json o = sonar_json(r); + o.set("chunks", Json(static_cast(chunks))); + return o; + }; + return pl; + } + Plan async(const Json& b) const { + std::string action = text(b, "action", true); + auto api = std::make_shared(p_.client); + auto job_json = [](const pp::AsyncJob& j) { + Json o = Json::object(); + o.set("id", Json(j.id)); + o.set("status", Json(j.status)); + o.set("model", Json(j.model)); + if (!j.error_message.empty()) o.set("error_message", Json(j.error_message)); + if (j.has_response) o.set("response", sonar_json(j.response)); + return o; + }; + if (action == "create") { + pp::SonarParams params = sonar_params(b); + std::string key = text(b, "idempotency_key"); + Json req = Json::object(); + req.set("request", params.to_json(false)); + return Plan{req, "/v1/async/sonar", true, [api, params, key, job_json] { return job_json(api->create_async(params, key)); }}; + } + if (action == "get") { + std::string id = text(b, "id", true); + if (!llm::Service::valid_id(id)) bad("id has invalid characters"); + Json req = Json::object(); + req.set("id", Json(id)); + return Plan{req, "/v1/async/sonar/{id}", false, [api, id, job_json] { return job_json(api->get_async(id)); }}; + } + if (action == "list") { + return Plan{Json::object(), "/v1/async/sonar", false, [api] { + pp::AsyncList l = api->list_async(); + Json arr = Json::array(); + for (const pp::AsyncSummary& s : l.requests) { + Json x = Json::object(); + x.set("id", Json(s.id)); + x.set("status", Json(s.status)); + x.set("model", Json(s.model)); + arr.push(x); + } + Json o = Json::object(); + o.set("requests", arr); + o.set("next_token", Json(l.next_token)); + return o; + }}; + } + bad("action must be create, get or list"); + } + Plan search(const Json& b) const { + pp::SearchParams sp; + std::string q = text(b, "query"); + if (!q.empty()) sp.query.push_back(q); + for (const std::string& extra : strings(b, "queries")) sp.query.push_back(extra); + sp.max_results = number(b, "max_results"); + sp.country = text(b, "country"); + sp.search_type = text(b, "search_type"); + sp.max_tokens_per_page = number(b, "max_tokens_per_page"); + sp.search_domain_filter = strings(b, "search_domain_filter"); + sp.search_language_filter = strings(b, "search_language_filter"); + sp.search_recency_filter = text(b, "search_recency_filter"); + Plan pl{sp.to_json(), "/search", true, nullptr}; + auto api = std::make_shared(p_.client); + pl.call = [api, sp] { + pp::SearchResponse r = api->run(sp); + Json arr = Json::array(); + for (const pp::SearchPage& s : r.results) { + Json x = Json::object(); + x.set("title", Json(s.title)); + x.set("url", Json(s.url)); + x.set("snippet", Json(s.snippet)); + x.set("date", Json(s.date)); + arr.push(x); + } + Json o = Json::object(); + o.set("id", Json(r.id)); + o.set("results", arr); + return o; + }; + return pl; + } + Plan embeddings(const Json& b) const { + auto api = std::make_shared(p_.client); + auto summarize = [](const pp::EmbedResult& r) { + Json arr = Json::array(); + for (const pp::Vector& v : r.vectors) { + Json x = Json::object(); + x.set("index", Json(v.index)); + x.set("dimensions", Json(static_cast(v.int8().size()))); + arr.push(x); + } + Json o = Json::object(); + o.set("model", Json(r.model)); + o.set("vectors", arr); + o.set("prompt_tokens", Json(static_cast(r.usage.prompt_tokens))); + return o; + }; + if (const Json* docs = b.find("documents"); docs && !docs->is_null()) { + if (!docs->is_array()) bad("documents must be an array of arrays of strings"); + pp::ContextEmbedParams cp; + std::string model = text(b, "model"); + if (!model.empty()) cp.model = model; + for (const Json& d : docs->as_array()) { + if (!d.is_array()) bad("documents must be an array of arrays of strings"); + std::vector chunks; + for (const Json& c : d.as_array()) { + if (!c.is_string()) bad("documents must be an array of arrays of strings"); + chunks.push_back(c.as_string()); + } + cp.input.push_back(chunks); + } + cp.dimensions = number(b, "dimensions").value_or(0); + cp.encoding_format = text(b, "encoding_format"); + Plan pl{cp.to_json(), "/v1/contextualizedembeddings", true, nullptr}; + pl.call = [api, cp] { + pp::ContextEmbedResult r = api->create_contextualized(cp); + Json arr = Json::array(); + for (const auto& doc : r.documents) arr.push(Json(static_cast(doc.size()))); + Json o = Json::object(); + o.set("model", Json(r.model)); + o.set("chunks_per_document", arr); + o.set("prompt_tokens", Json(static_cast(r.usage.prompt_tokens))); + return o; + }; + return pl; + } + pp::EmbedParams ep; + std::string model = text(b, "model"); + if (!model.empty()) ep.model = model; + ep.input = strings(b, "input"); + ep.dimensions = number(b, "dimensions").value_or(0); + ep.encoding_format = text(b, "encoding_format"); + Plan pl{ep.to_json(), "/v1/embeddings", true, nullptr}; + pl.call = [api, ep, summarize] { return summarize(api->create(ep)); }; + return pl; + } + Plan agent(const Json& b) const { + std::string action = text(b, "action"); + if (action.empty()) action = "create"; + auto api = std::make_shared(p_.client); + if (action == "get" || action == "cancel" || action == "files") { + std::string id = text(b, "id", true); + if (!llm::Service::valid_id(id)) bad("id has invalid characters"); + Json req = Json::object(); + req.set("id", Json(id)); + if (action == "get") return Plan{req, "/v1/agent/{id}", false, [api, id] { return agent_json(api->get(id)); }}; + if (action == "files") + return Plan{req, "/v1/agent/{id}/files", false, [api, id] { + pp::AgentFileList l = api->files(id); + Json arr = Json::array(); + for (const pp::AgentFile& f : l.files) { + Json x = Json::object(); + x.set("id", Json(f.id)); + x.set("filename", Json(f.filename)); + x.set("bytes", Json(static_cast(f.bytes))); + arr.push(x); + } + Json o = Json::object(); + o.set("files", arr); + return o; + }}; + return Plan{req, "POST /v1/agent/{id}/cancel", true, [api, id] { return api->cancel(id); }}; + } + if (action != "create") bad("action must be create, get, cancel or files"); + pp::AgentParams p; + p.input = Json(text(b, "input", true)); + p.model = text(b, "model"); + p.effort = text(b, "effort"); + p.models = strings(b, "models"); + p.instructions = text(b, "instructions"); + p.max_output_tokens = number(b, "max_output_tokens"); + p.max_steps = number(b, "max_steps"); + p.reasoning_effort = text(b, "reasoning_effort"); + p.background = opt_flag(b, "background"); + for (const std::string& t : strings(b, "tools")) { + if (t == "web_search") p.tools.push_back(pp::AgentTools::web_search()); + else if (t == "fetch_url") p.tools.push_back(pp::AgentTools::fetch_url()); + else if (t == "image_search") p.tools.push_back(pp::AgentTools::image_search()); + else if (t == "finance_search") p.tools.push_back(pp::AgentTools::finance_search()); + else if (t == "people_search") p.tools.push_back(pp::AgentTools::people_search()); + else if (t == "sandbox") p.tools.push_back(pp::AgentTools::sandbox()); + else bad("tools entries are web_search, fetch_url, image_search, finance_search, people_search or sandbox"); + } + for (const std::string& s : strings(b, "skills")) p.skills.push_back(pp::AgentSkills::builtin(s)); + if (p.model.empty() && p.effort.empty() && p.models.empty()) p.effort = "fast"; + Plan pl{p.to_json(false), "/v1/agent", true, nullptr}; + pl.call = [api, p] { return agent_json(api->create(p)); }; + return pl; + } + Plan orchestrator(const Json& b) const { + std::string api_name = text(b, "api"); + if (api_name.empty()) api_name = "chat"; + pp::Call call; + if (api_name == "chat") call = pp::Call::kOrchChat; + else if (api_name == "messages") call = pp::Call::kOrchMessages; + else if (api_name == "responses") call = pp::Call::kOrchResponses; + else bad("api must be chat, messages or responses"); + const Json* request = b.find("request"); + Json body; + if (request && request->is_object()) { + body = *request; + } else { + std::string model = text(b, "model", true); + std::string prompt = text(b, "prompt", true); + if (call == pp::Call::kOrchChat) body = pp::Orchestrator::chat_request(model, prompt); + else if (call == pp::Call::kOrchMessages) body = pp::Orchestrator::messages_request(model, prompt, number(b, "max_tokens").value_or(256)); + else body = pp::Orchestrator::responses_request(model, prompt); + } + pp::Orchestrator::validate(call, body); + auto api = std::make_shared(p_.client); + Plan pl{body, pp::Calls::spec_of(call).path, true, nullptr}; + pl.call = [api, call, body] { + Json reply = call == pp::Call::kOrchChat ? api->chat(body) + : call == pp::Call::kOrchMessages ? api->messages(body) + : api->responses(body); + Json o = Json::object(); + o.set("text", Json(pp::Orchestrator::text_of(call, reply))); + o.set("id", Json(pp::J::str(reply, "id"))); + return o; + }; + return pl; + } + Plan decisions(const Json& b) const { + pp::DecisionsParams p; + std::string model = text(b, "model"); + if (!model.empty()) p.model = model; + p.state = Json(text(b, "state", true)); + const Json* qs = b.find("questions"); + if (!qs || !qs->is_object()) bad("questions must be an object of name -> {type, ...}"); + for (const auto& [name, q] : qs->as_object()) p.questions[name] = q; + Plan pl{p.to_json(), "/v1/decisions", true, nullptr}; + auto api = std::make_shared(p_.client); + pl.call = [api, p] { + pp::DecisionsResult r = api->answer(p); + Json answers = Json::object(); + for (const auto& [name, a] : r.answers) { + Json x = Json::object(); + x.set("type", Json(a.type)); + if (a.type == "noul") x.set("noul", Json(a.noul)); + if (a.type == "choice") x.set("choice", Json(a.choice)); + if (a.type == "score") x.set("score", Json(a.score)); + answers.set(name, x); + } + Json o = Json::object(); + o.set("model", Json(r.model)); + o.set("answers", answers); + return o; + }; + return pl; + } + Plan models(const Json& b) const { + std::string kind = text(b, "kind"); + if (kind.empty()) kind = "agent"; + if (kind != "agent" && kind != "orchestrator") bad("kind must be agent or orchestrator"); + bool orch = kind == "orchestrator"; + auto account = std::make_shared(p_.client); + auto orchestrator = std::make_shared(p_.client); + return Plan{Json::object(), orch ? "/orchestrator/v1/models" : "/v1/models", false, [account, orchestrator, orch] { + pp::ModelList l = orch ? orchestrator->models() : account->models(); + Json arr = Json::array(); + for (const pp::ModelInfo& m : l.models) { + Json x = Json::object(); + x.set("id", Json(m.id)); + x.set("owned_by", Json(m.owned_by)); + if (m.pricing.present) { + x.set("input_per_1m", Json(m.pricing.input)); + x.set("output_per_1m", Json(m.pricing.output)); + } + arr.push(x); + } + Json o = Json::object(); + o.set("models", arr); + o.set("truncated", Json(l.truncated)); + return o; + }}; + } + Plan usage(const Json& b) const { + pp::UsageQuery q; + q.dataset = text(b, "dataset", true); + q.start_time = number(b, "start_time").value_or(0); + if (auto e = number(b, "end_time")) q.end_time = *e; + q.bucket_width = text(b, "bucket_width"); + q.limit = number(b, "limit"); + q.page = text(b, "page"); + q.user_email = text(b, "user_email"); + bool per_member = flag(b, "per_member"); + if (per_member) q.group_by = "user_email"; + if (per_member) q.query_v2(); + else q.query_v1(); + auto api = std::make_shared(p_.client); + return Plan{Json::object(), per_member ? "/v2/analytics/computer/usage" : "/v1/analytics/computer/usage", false, + [api, q, per_member] { + pp::UsageReport r = per_member ? api->usage_per_member(q) : api->usage(q); + Json arr = Json::array(); + for (const pp::UsageBucket& u : r.buckets) { + Json x = Json::object(); + x.set("start_time", Json(static_cast(u.start_time))); + x.set("count", Json(static_cast(u.count))); + if (!u.user_email.empty()) x.set("user_email", Json(u.user_email)); + arr.push(x); + } + Json o = Json::object(); + o.set("buckets", arr); + o.set("has_more", Json(r.has_more)); + o.set("next_page", Json(r.next_page)); + return o; + }}; + } + Plan batches(const Json& b) const { + std::string action = text(b, "action", true); + auto batches = std::make_shared(p_.client); + auto files = std::make_shared(p_.client); + auto id_of = [&](const char* key) { + std::string id = text(b, key, true); + if (!llm::Service::valid_id(id)) bad(std::string(key) + " has invalid characters"); + return id; + }; + auto batch_json = [](const pp::BatchInfo& x) { + Json o = Json::object(); + o.set("id", Json(x.id)); + o.set("status", Json(x.status)); + o.set("output_file_id", Json(x.output_file_id)); + o.set("error_file_id", Json(x.error_file_id)); + o.set("total", Json(static_cast(x.total))); + o.set("completed", Json(static_cast(x.completed))); + o.set("failed", Json(static_cast(x.failed))); + return o; + }; + auto file_json = [](const pp::BatchFileInfo& f) { + Json o = Json::object(); + o.set("id", Json(f.id)); + o.set("filename", Json(f.filename)); + o.set("purpose", Json(f.purpose)); + o.set("bytes", Json(static_cast(f.bytes))); + o.set("deleted", Json(f.deleted)); + return o; + }; + if (action == "list") { + int limit = number(b, "limit").value_or(0); + std::string after = text(b, "after"); + return Plan{Json::object(), "/v1/batches", false, [batches, limit, after, batch_json] { + pp::BatchList l = batches->list(limit, after); + Json arr = Json::array(); + for (const pp::BatchInfo& x : l.batches) arr.push(batch_json(x)); + Json o = Json::object(); + o.set("batches", arr); + o.set("has_more", Json(l.has_more)); + return o; + }}; + } + if (action == "get") { + std::string id = id_of("id"); + Json req = Json::object(); + req.set("id", Json(id)); + return Plan{req, "/v1/batches/{id}", false, [batches, id, batch_json] { return batch_json(batches->get(id)); }}; + } + if (action == "create") { + std::string file_id = id_of("input_file_id"); + std::map meta; + if (const Json* m = b.find("metadata"); m && m->is_object()) + for (const auto& [k, v] : m->as_object()) { + if (!v.is_string()) bad("metadata values must be strings"); + meta[k] = v.as_string(); + } + std::string key = text(b, "idempotency_key"); + Json req = Json::object(); + req.set("input_file_id", Json(file_id)); + req.set("endpoint", Json("/v1/responses")); + return Plan{req, "POST /v1/batches", true, [batches, file_id, meta, key, batch_json] { return batch_json(batches->create(file_id, meta, key)); }}; + } + if (action == "cancel") { + std::string id = id_of("id"); + Json req = Json::object(); + req.set("id", Json(id)); + return Plan{req, "POST /v1/batches/{id}/cancel", true, [batches, id, batch_json] { return batch_json(batches->cancel(id)); }}; + } + if (action == "files") { + int limit = number(b, "limit").value_or(0); + std::string purpose = text(b, "purpose"); + return Plan{Json::object(), "/v1/files", false, [files, limit, purpose, file_json] { + pp::BatchFileList l = files->list(limit, "", "", purpose); + Json arr = Json::array(); + for (const pp::BatchFileInfo& f : l.files) arr.push(file_json(f)); + Json o = Json::object(); + o.set("files", arr); + o.set("has_more", Json(l.has_more)); + return o; + }}; + } + if (action == "file_get" || action == "file_delete") { + std::string id = id_of("id"); + Json req = Json::object(); + req.set("id", Json(id)); + if (action == "file_get") return Plan{req, "/v1/files/{id}", false, [files, id, file_json] { return file_json(files->get(id)); }}; + return Plan{req, "DELETE /v1/files/{id}", true, [files, id, file_json] { return file_json(files->remove(id)); }}; + } + if (action == "upload") { + pp::BatchInput in; + in.jsonl = text(b, "jsonl", true); + std::string fname = text(b, "filename"); + if (!fname.empty()) in.filename = fname; + in.validate(); + Json req = Json::object(); + req.set("filename", Json(in.filename)); + req.set("bytes", Json(static_cast(in.jsonl.size()))); + return Plan{req, "POST /v1/files", true, [files, in, file_json] { return file_json(files->upload(in)); }}; + } + bad("action must be list, get, create, cancel, files, file_get, file_delete or upload"); + } + Plan skills(const Json& b) const { + std::string action = text(b, "action", true); + auto api = std::make_shared(p_.client); + auto skill_json = [](const pp::SkillInfo& s) { + Json o = Json::object(); + o.set("skill_id", Json(s.skill_id)); + o.set("name", Json(s.name)); + o.set("revision", Json(s.revision)); + o.set("latest_revision", Json(s.latest_revision)); + return o; + }; + auto id_of = [&]() { + std::string id = text(b, "id", true); + if (!llm::Service::valid_id(id)) bad("id has invalid characters"); + return id; + }; + if (action == "list") { + int limit = number(b, "limit").value_or(0); + return Plan{Json::object(), "/v1/skills", false, [api, limit, skill_json] { + pp::SkillList l = api->list(limit); + Json arr = Json::array(); + for (const pp::SkillInfo& s : l.skills) arr.push(skill_json(s)); + Json o = Json::object(); + o.set("skills", arr); + o.set("next_page_token", Json(l.next_page_token)); + return o; + }}; + } + if (action == "get") { + std::string id = id_of(); + std::string rev = text(b, "revision"); + Json req = Json::object(); + req.set("id", Json(id)); + return Plan{req, "/v1/skills/{id}", false, [api, id, rev, skill_json] { return skill_json(api->get(id, rev)); }}; + } + if (action == "revisions") { + std::string id = id_of(); + Json req = Json::object(); + req.set("id", Json(id)); + return Plan{req, "/v1/skills/{id}/revisions", false, [api, id] { + pp::SkillRevisionList l = api->revisions(id); + Json arr = Json::array(); + for (const pp::SkillRevision& r : l.revisions) arr.push(Json(r.revision)); + Json o = Json::object(); + o.set("revisions", arr); + return o; + }}; + } + if (action == "download") { + std::string id = id_of(); + std::string rev = text(b, "revision"); + Json req = Json::object(); + req.set("id", Json(id)); + return Plan{req, "/v1/skills/{id}/download", false, [api, id, rev] { + pp::SkillDownload d = api->download(id, rev); + Json o = Json::object(); + o.set("revision", Json(d.revision)); + o.set("download_url", Json(d.download_url)); + return o; + }}; + } + if (action == "delete") { + std::string id = id_of(); + std::string rev = text(b, "expected_revision", true); + Rules_opaque(rev); + Json req = Json::object(); + req.set("id", Json(id)); + req.set("expected_revision", Json(rev)); + return Plan{req, "DELETE /v1/skills/{id}", true, [api, id, rev] { + api->remove(id, rev); + Json o = Json::object(); + o.set("deleted", Json(true)); + return o; + }}; + } + if (action == "create" || action == "update") { + pp::SkillBundle bundle; + if (!security::crypto::Base64::decode(text(b, "data_base64", true), bundle.data)) bad("data_base64 is not valid base64"); + std::string fname = text(b, "filename"); + if (!fname.empty()) bundle.filename = fname; + bundle.validate(); + Json req = Json::object(); + req.set("bytes", Json(static_cast(bundle.data.size()))); + if (action == "create") + return Plan{req, "POST /v1/skills", true, [api, bundle, skill_json] { return skill_json(api->create(bundle)); }}; + std::string id = id_of(); + std::string rev = text(b, "expected_revision", true); + Rules_opaque(rev); + return Plan{req, "PUT /v1/skills/{id}", true, [api, id, rev, bundle, skill_json] { return skill_json(api->update(id, rev, bundle)); }}; + } + bad("action must be list, get, revisions, download, delete, create or update"); + } + + private: + static void Rules_opaque(const std::string& v) { pp::Rules::opaque_token(v, "expected_revision"); } + + [[noreturn]] static void map(const llm::ApiError& e) { + if (e.http_status() == 503 && e.type() == "NOT_CONFIGURED") + throw fw::HttpError(503, "perplexity_not_configured", e.message()); + if (e.type() == "INVALID_ARGUMENT" && e.http_status() == 400 && e.request_id().empty()) + throw fw::HttpError(422, "validation_error", e.message()); + throw fw::HttpError(502, "perplexity_error", pp::Errors::explain(e) + " | " + e.type() + ": " + e.message()); + } + pp::Platform p_; +}; + +} // namespace + void register_ai_perplexity_demo(fw::Router& router, Services& services) { - (void)router; - (void)services; + auto routes = std::make_shared(pp::Platform::from_env()); + fw::Environment* env = services.templates.get(); + services.templates->add_template("ai_perplexity.html", kPage); + services.add_feature("ai-perplexity", "/ai/perplexity"); + + router.get("/ai/perplexity", "ai-perplexity-page", [env](fw::Request req) { + (void)req; + fw::TemplateCtx ctx; + ctx["title"] = std::string("Perplexity API"); + return fw::Response(200, env->render("ai_perplexity.html", ctx), "text/html; charset=utf-8"); + }); + + router.get("/ai/perplexity/status", "ai-perplexity-status", [routes](fw::Request req) { + (void)req; + Json o = Json::object(); + o.set("configured", Json(routes->platform().configured())); + o.set("credential_env", Json(pp::Platform::kKeyEnv)); + o.set("base_url", Json(pp::Platform::kHost)); + o.set("key_page", Json(pp::Platform::kKeyPage)); + o.set("calls", Json(static_cast(pp::Calls::count()))); + Json models = Json::array(); + for (std::size_t i = 0; i < pp::SonarModels::count(); ++i) { + Json m = Json::object(); + m.set("id", Json(pp::SonarModels::at(i).id)); + m.set("note", Json(pp::SonarModels::at(i).note)); + models.push(m); + } + o.set("sonar_models", models); + o.set("search_max_results", Json(pp::PerplexityCaps::kSearchMaxResults)); + o.set("embed_max_texts", Json(static_cast(pp::PerplexityCaps::kEmbedTexts))); + return json_out(o); + }); + + router.get("/ai/perplexity/calls", "ai-perplexity-calls", [](fw::Request req) { + (void)req; + Json arr = Json::array(); + for (std::size_t i = 0; i < pp::Calls::count(); ++i) { + const pp::CallSpec& s = pp::Calls::at(i); + Json row = Json::object(); + row.set("http", Json(s.http_method)); + row.set("path", Json(s.path)); + row.set("operation", Json(s.operation_id)); + row.set("spec", Json(s.spec)); + arr.push(row); + } + Json o = Json::object(); + o.set("calls", arr); + return json_out(o); + }); + + router.get("/ai/perplexity/errors", "ai-perplexity-errors", [](fw::Request req) { + (void)req; + Json arr = Json::array(); + for (std::size_t i = 0; i < pp::Errors::count(); ++i) { + const pp::ErrorInfo& e = pp::Errors::at(i); + Json row = Json::object(); + row.set("status", Json(e.status)); + row.set("name", Json(e.name)); + row.set("action", Json(e.action)); + row.set("retryable", Json(e.retryable)); + arr.push(row); + } + Json o = Json::object(); + o.set("errors", arr); + return json_out(o); + }); + + using Member = PerplexityRoutes::Planner; + auto add = [&](const char* path, const char* name, Member planner) { + router.post(path, name, [routes, planner](fw::Request req) { return routes->run(req, planner); }); + }; + PerplexityRoutes* r = routes.get(); + auto bind = [r](Plan (PerplexityRoutes::*m)(const Json&) const) { + return Member([r, m](const Json& b) { return (r->*m)(b); }); + }; + add("/ai/perplexity/sonar", "ai-perplexity-sonar", bind(&PerplexityRoutes::sonar)); + add("/ai/perplexity/stream", "ai-perplexity-stream", bind(&PerplexityRoutes::stream)); + add("/ai/perplexity/async", "ai-perplexity-async", bind(&PerplexityRoutes::async)); + add("/ai/perplexity/search", "ai-perplexity-search", bind(&PerplexityRoutes::search)); + add("/ai/perplexity/embeddings", "ai-perplexity-embeddings", bind(&PerplexityRoutes::embeddings)); + add("/ai/perplexity/agent", "ai-perplexity-agent", bind(&PerplexityRoutes::agent)); + add("/ai/perplexity/orchestrator", "ai-perplexity-orchestrator", bind(&PerplexityRoutes::orchestrator)); + add("/ai/perplexity/decisions", "ai-perplexity-decisions", bind(&PerplexityRoutes::decisions)); + add("/ai/perplexity/models", "ai-perplexity-models", bind(&PerplexityRoutes::models)); + add("/ai/perplexity/usage", "ai-perplexity-usage", bind(&PerplexityRoutes::usage)); + add("/ai/perplexity/batches", "ai-perplexity-batches", bind(&PerplexityRoutes::batches)); + add("/ai/perplexity/skills", "ai-perplexity-skills", bind(&PerplexityRoutes::skills)); } } // namespace molo::example::app diff --git a/example/assets/ai_perplexity.js b/example/assets/ai_perplexity.js new file mode 100644 index 0000000..7a5f288 --- /dev/null +++ b/example/assets/ai_perplexity.js @@ -0,0 +1,58 @@ +// Perplexity page: thin client over /ai/perplexity/* (all limits server side). +(function () { + "use strict"; + var $ = function (id) { return document.getElementById(id); }; + var out = $("pp-out"), err = $("pp-error"); + var templates = { + "sonar": { prompt: "What changed in the latest Mars rover mission?", model: "sonar", search_recency_filter: "month", return_related_questions: true, max_tokens: 256 }, + "stream": { prompt: "Explain quantum computing in two sentences.", model: "sonar", max_tokens: 128 }, + "async": { action: "create", prompt: "Compare solid-state battery makers.", model: "sonar-deep-research" }, + "search": { query: "Perplexity Search API", max_results: 5, max_tokens_per_page: 512 }, + "embeddings": { input: ["first text", "second text"], model: "pplx-embed-v1-0.6b", dimensions: 256 }, + "agent": { input: "Summarize today's top AI news.", effort: "fast", tools: ["web_search"], max_steps: 5 }, + "orchestrator": { api: "chat", model: "perplexity/kimi-k3", prompt: "Say hello." }, + "decisions": { state: "The battery stopped charging.", questions: { defect: { type: "noul", instructions: "Does this report a defect?" } } }, + "models": { kind: "agent" }, + "usage": { dataset: "credit_usage", start_time: 1746057600, limit: 7 }, + "batches": { action: "list", limit: 20 }, + "skills": { action: "list", limit: 20 } + }; + var sel = $("pp-route"); + Object.keys(templates).forEach(function (k) { + var o = document.createElement("option"); + o.value = k; o.textContent = k; + sel.appendChild(o); + }); + function fill() { $("pp-body").value = JSON.stringify(templates[sel.value], null, 1); } + sel.onchange = fill; + fill(); + + function send(confirm) { + var body; + try { body = JSON.parse($("pp-body").value || "{}"); } + catch (e) { err.textContent = "Body is not valid JSON"; return; } + if (confirm) body.confirm = true; + err.textContent = ""; + out.textContent = "..."; + fetch("/ai/perplexity/" + sel.value, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(body) + }).then(function (res) { + return res.text().then(function (t) { + var j; + try { j = JSON.parse(t); } catch (e) { j = { message: t }; } + if (!res.ok) { err.textContent = j.message || ("HTTP " + res.status); out.textContent = ""; } + else { out.textContent = JSON.stringify(j, null, 2); } + }); + }).catch(function (e) { err.textContent = String(e); out.textContent = ""; }); + } + $("pp-send").onclick = function () { send(false); }; + $("pp-confirm").onclick = function () { send(true); }; + + fetch("/ai/perplexity/status").then(function (r) { return r.json(); }).then(function (s) { + $("pp-config").textContent = s.configured + ? "PERPLEXITY_API_KEY found. Calls are real; paid ones need confirm." + : "No PERPLEXITY_API_KEY (create one at " + s.key_page + "): calls answer 503 until one is configured; dry runs still work."; + }); +})(); diff --git a/src/vendors/perplexity/SPEC.md b/src/vendors/perplexity/SPEC.md new file mode 100644 index 0000000..4cb957d --- /dev/null +++ b/src/vendors/perplexity/SPEC.md @@ -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. diff --git a/src/vendors/perplexity/account.cpp b/src/vendors/perplexity/account.cpp new file mode 100644 index 0000000..5656572 --- /dev/null +++ b/src/vendors/perplexity/account.cpp @@ -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(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 diff --git a/src/vendors/perplexity/account.h b/src/vendors/perplexity/account.h new file mode 100644 index 0000000..4a0a3c6 --- /dev/null +++ b/src/vendors/perplexity/account.h @@ -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 +#include +#include + +#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 end_time; + std::string bucket_width; // v1: "", 1d, 1h + std::optional 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 categories; + std::vector 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 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 diff --git a/src/vendors/perplexity/agent.cpp b/src/vendors/perplexity/agent.cpp new file mode 100644 index 0000000..2f267d3 --- /dev/null +++ b/src/vendors/perplexity/agent.cpp @@ -0,0 +1,83 @@ +#include "vendors/perplexity/agent.h" + +#include +#include + +#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& 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{response_id, file_id})); + return FileBytes{raw.body, raw.content_type}; +} + +} // namespace molo::perplexity diff --git a/src/vendors/perplexity/agent.h b/src/vendors/perplexity/agent.h new file mode 100644 index 0000000..9ecc12a --- /dev/null +++ b/src/vendors/perplexity/agent.h @@ -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 +#include + +#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 client) : llm::Service(std::move(client)) {} + + AgentResult create(const AgentParams& params); + + using EventSink = std::function; // 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& 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 diff --git a/src/vendors/perplexity/agent_params.cpp b/src/vendors/perplexity/agent_params.cpp new file mode 100644 index 0000000..994753e --- /dev/null +++ b/src/vendors/perplexity/agent_params.cpp @@ -0,0 +1,401 @@ +#include "vendors/perplexity/agent_params.h" + +#include + +#include "vendors/perplexity/caps.h" +#include "vendors/perplexity/rules.h" + +namespace molo::perplexity { + +namespace { +Json str_array(const std::vector& 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& 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& domains, + const std::vector& formats, std::optional 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 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& 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& 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_"); + 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(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 diff --git a/src/vendors/perplexity/agent_params.h b/src/vendors/perplexity/agent_params.h new file mode 100644 index 0000000..e4ec688 --- /dev/null +++ b/src/vendors/perplexity/agent_params.h @@ -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 +#include +#include + +#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& 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 max_results; // 1..50 + std::optional max_tokens, max_tokens_per_page; + std::vector 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& domains = {}, + const std::vector& formats = {}, std::optional 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 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& allowed_tools = {}, const std::string& require_approval = ""); + static Json connector(const std::string& id, const std::string& server_label, + const std::vector& 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 models; // fallback chain, 1..5; takes precedence over model + std::string effort; // name, name@latest, name@ + 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 max_output_tokens; // required for anthropic/* models + std::optional 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 store, background; + std::vector tools; + Json tool_choice; // null: omit + std::vector skills; // max 16 + std::optional 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 diff --git a/src/vendors/perplexity/agent_result.cpp b/src/vendors/perplexity/agent_result.cpp new file mode 100644 index 0000000..c8ea192 --- /dev/null +++ b/src/vendors/perplexity/agent_result.cpp @@ -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 AgentResult::items_of_type(const std::string& type) const { + std::vector 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 AgentResult::citations() const { + std::vector 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 AgentResult::search_results() const { + std::vector 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 AgentResult::queries() const { + std::vector out; + for (const Json& i : output) + for (const std::string& q : J::strings(i, "queries")) out.push_back(q); + return out; +} + +std::vector AgentResult::function_calls() const { + std::vector 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 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 diff --git a/src/vendors/perplexity/agent_result.h b/src/vendors/perplexity/agent_result.h new file mode 100644 index 0000000..47cbd52 --- /dev/null +++ b/src/vendors/perplexity/agent_result.h @@ -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 +#include + +#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 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 citations() const; // url_citation annotations + std::vector search_results() const; // every search_results item, one id space + std::vector queries() const; // search queries across items + std::vector function_calls() const; + std::vector items_of_type(const std::string& type) const; + // Pending mcp_approval_request items (answer with AgentInput::mcp_approval_response). + std::vector approval_requests() const; +}; + +struct AgentFileList { + std::vector 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 queries; + std::vector 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 items_; + bool done_ = false; + std::size_t events_ = 0; + long last_sequence_ = -1; +}; + +} // namespace molo::perplexity diff --git a/src/vendors/perplexity/batches.cpp b/src/vendors/perplexity/batches.cpp new file mode 100644 index 0000000..386a2e0 --- /dev/null +++ b/src/vendors/perplexity/batches.cpp @@ -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& 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(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 diff --git a/src/vendors/perplexity/batches.h b/src/vendors/perplexity/batches.h new file mode 100644 index 0000000..137eef6 --- /dev/null +++ b/src/vendors/perplexity/batches.h @@ -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 +#include +#include + +#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 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 errors; + std::map 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 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 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 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& 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 diff --git a/src/vendors/perplexity/calls.cpp b/src/vendors/perplexity/calls.cpp new file mode 100644 index 0000000..b3964a8 --- /dev/null +++ b/src/vendors/perplexity/calls.cpp @@ -0,0 +1,185 @@ +#include "vendors/perplexity/calls.h" + +#include + +#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& 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 Calls::render(Call call, const std::string& id) { + return render(call, std::vector{id}); +} + +} // namespace molo::perplexity diff --git a/src/vendors/perplexity/calls.h b/src/vendors/perplexity/calls.h new file mode 100644 index 0000000..00c696f --- /dev/null +++ b/src/vendors/perplexity/calls.h @@ -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 +#include +#include + +#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& ids); + static std::string render(Call call); + static std::string render(Call call, const std::string& id); +}; + +} // namespace molo::perplexity diff --git a/src/vendors/perplexity/caps.h b/src/vendors/perplexity/caps.h new file mode 100644 index 0000000..7674824 --- /dev/null +++ b/src/vendors/perplexity/caps.h @@ -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 + +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 diff --git a/src/vendors/perplexity/chat_model.cpp b/src/vendors/perplexity/chat_model.cpp new file mode 100644 index 0000000..67b374d --- /dev/null +++ b/src/vendors/perplexity/chat_model.cpp @@ -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, std::string default_model) + : sonar_(std::move(sonar)), default_model_(std::move(default_model)) {} + +std::shared_ptr PerplexityChatModel::from_env(const std::string& default_model) { + Platform p = Platform::from_env(); + return std::make_shared(std::make_shared(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 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& 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 diff --git a/src/vendors/perplexity/chat_model.h b/src/vendors/perplexity/chat_model.h new file mode 100644 index 0000000..4a51d47 --- /dev/null +++ b/src/vendors/perplexity/chat_model.h @@ -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 + +#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, std::string default_model = "sonar"); + static std::shared_ptr 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& 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_; + std::string default_model_; +}; + +} // namespace molo::perplexity diff --git a/src/vendors/perplexity/decisions.cpp b/src/vendors/perplexity/decisions.cpp new file mode 100644 index 0000000..2e229ee --- /dev/null +++ b/src/vendors/perplexity/decisions.cpp @@ -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& 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& 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 diff --git a/src/vendors/perplexity/decisions.h b/src/vendors/perplexity/decisions.h new file mode 100644 index 0000000..f2da3f4 --- /dev/null +++ b/src/vendors/perplexity/decisions.h @@ -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 +#include +#include + +#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& options, const std::string& instructions = ""); + // score: ordered level descriptions; the index is the level's score from 0. + static Json score(const std::vector& 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 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 probabilities; + std::map legend; // score: level index -> criteria entry text +}; + +struct DecisionsResult { + std::string model; + std::map 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 client) : llm::Service(std::move(client)) {} + DecisionsResult answer(const DecisionsParams& params); +}; + +} // namespace molo::perplexity diff --git a/src/vendors/perplexity/embeddings.cpp b/src/vendors/perplexity/embeddings.cpp new file mode 100644 index 0000000..b48a728 --- /dev/null +++ b/src/vendors/perplexity/embeddings.cpp @@ -0,0 +1,164 @@ +#include "vendors/perplexity/embeddings.h" + +#include + +#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 Vector::int8() const { + std::string raw = bytes(); + std::vector v(raw.size()); + for (std::size_t i = 0; i < raw.size(); ++i) v[i] = static_cast(static_cast(raw[i])); + return v; +} + +double cosine(const std::vector& a, const std::vector& 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(a[i]) * b[i]; + na += static_cast(a[i]) * a[i]; + nb += static_cast(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(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 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 diff --git a/src/vendors/perplexity/embeddings.h b/src/vendors/perplexity/embeddings.h new file mode 100644 index 0000000..ff505d3 --- /dev/null +++ b/src/vendors/perplexity/embeddings.h @@ -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 +#include +#include + +#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 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> 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 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 vectors; + EmbedUsage usage; + Json raw; + static EmbedResult parse(const Json& doc); +}; + +struct ContextEmbedResult { + std::string model; + std::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& a, const std::vector& b); + +class Embeddings : public llm::Service { + public: + explicit Embeddings(std::shared_ptr client) : llm::Service(std::move(client)) {} + EmbedResult create(const EmbedParams& params); + ContextEmbedResult create_contextualized(const ContextEmbedParams& params); +}; + +} // namespace molo::perplexity diff --git a/src/vendors/perplexity/errors.cpp b/src/vendors/perplexity/errors.cpp new file mode 100644 index 0000000..5bfd49a --- /dev/null +++ b/src/vendors/perplexity/errors.cpp @@ -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 diff --git a/src/vendors/perplexity/errors.h b/src/vendors/perplexity/errors.h new file mode 100644 index 0000000..c6c03c7 --- /dev/null +++ b/src/vendors/perplexity/errors.h @@ -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 + +#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 diff --git a/src/vendors/perplexity/orchestrator.cpp b/src/vendors/perplexity/orchestrator.cpp new file mode 100644 index 0000000..ec5fe65 --- /dev/null +++ b/src/vendors/perplexity/orchestrator.cpp @@ -0,0 +1,141 @@ +#include "vendors/perplexity/orchestrator.h" + +#include +#include + +#include "vendors/perplexity/caps.h" +#include "vendors/perplexity/rules.h" + +namespace molo::perplexity { + +namespace { +std::set fields_of(const char* list) { + std::set 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 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 diff --git a/src/vendors/perplexity/orchestrator.h b/src/vendors/perplexity/orchestrator.h new file mode 100644 index 0000000..51275b0 --- /dev/null +++ b/src/vendors/perplexity/orchestrator.h @@ -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 +#include + +#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 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; + 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 diff --git a/src/vendors/perplexity/platform.cpp b/src/vendors/perplexity/platform.cpp new file mode 100644 index 0000000..1a3df09 --- /dev/null +++ b/src/vendors/perplexity/platform.cpp @@ -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 transport, const std::string& key) { + Platform p; + p.client = std::make_shared(std::move(transport), config(), key); + return p; +} + +} // namespace molo::perplexity diff --git a/src/vendors/perplexity/platform.h b/src/vendors/perplexity/platform.h new file mode 100644 index 0000000..50e3626 --- /dev/null +++ b/src/vendors/perplexity/platform.h @@ -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 + +#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 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 transport, const std::string& key); + bool configured() const { return client && client->configured(); } +}; + +} // namespace molo::perplexity diff --git a/src/vendors/perplexity/rules.cpp b/src/vendors/perplexity/rules.cpp new file mode 100644 index 0000000..3ffc5d0 --- /dev/null +++ b/src/vendors/perplexity/rules.cpp @@ -0,0 +1,132 @@ +#include "vendors/perplexity/rules.h" + +#include + +#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(c)) || c == '_' || c == '-'; } +bool digit(char c) { return c >= '0' && c <= '9'; } +bool alpha(char c) { return std::isalpha(static_cast(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& 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(c) > 0x20 && c != 0x7f && c != '/', std::string(what) + " entry has invalid characters"); + } +} + +void Rules::one_of(const std::string& value, std::initializer_list 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(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(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(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 diff --git a/src/vendors/perplexity/rules.h b/src/vendors/perplexity/rules.h new file mode 100644 index 0000000..ddb28f9 --- /dev/null +++ b/src/vendors/perplexity/rules.h @@ -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 +#include + +#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& list, std::size_t max, const char* what); + static void one_of(const std::string& value, std::initializer_list 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 diff --git a/src/vendors/perplexity/search.cpp b/src/vendors/perplexity/search.cpp new file mode 100644 index 0000000..f84c50f --- /dev/null +++ b/src/vendors/perplexity/search.cpp @@ -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* 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& 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 diff --git a/src/vendors/perplexity/search.h b/src/vendors/perplexity/search.h new file mode 100644 index 0000000..382bdcd --- /dev/null +++ b/src/vendors/perplexity/search.h @@ -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 +#include +#include + +#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 query; // one entry is sent as a string, several as an array + std::string country; // ISO 3166-1 alpha-2 + std::optional max_results; // 1..20; up to 50 only with search_type=people + std::string search_type; // "", web, fast, people + std::optional max_tokens, max_tokens_per_page; // 1..1,000,000 + std::vector search_language_filter; // ISO 639-1, max 20 + std::vector 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 results; + bool truncated = false; + Json raw; + static SearchResponse parse(const Json& doc); +}; + +class Search : public llm::Service { + public: + explicit Search(std::shared_ptr client) : llm::Service(std::move(client)) {} + SearchResponse run(const SearchParams& params); +}; + +} // namespace molo::perplexity diff --git a/src/vendors/perplexity/skills.cpp b/src/vendors/perplexity/skills.cpp new file mode 100644 index 0000000..afb3a37 --- /dev/null +++ b/src/vendors/perplexity/skills.cpp @@ -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 diff --git a/src/vendors/perplexity/skills.h b/src/vendors/perplexity/skills.h new file mode 100644 index 0000000..7ef6abf --- /dev/null +++ b/src/vendors/perplexity/skills.h @@ -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 +#include +#include + +#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 skills; + std::string next_page_token; + bool truncated = false; +}; + +struct SkillRevision { + std::string revision, name, created_at; +}; + +struct SkillRevisionList { + std::vector 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 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 diff --git a/src/vendors/perplexity/sonar.cpp b/src/vendors/perplexity/sonar.cpp new file mode 100644 index 0000000..5553b41 --- /dev/null +++ b/src/vendors/perplexity/sonar.cpp @@ -0,0 +1,129 @@ +#include "vendors/perplexity/sonar.h" + +#include +#include + +#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(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& 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 diff --git a/src/vendors/perplexity/sonar.h b/src/vendors/perplexity/sonar.h new file mode 100644 index 0000000..a865d1b --- /dev/null +++ b/src/vendors/perplexity/sonar.h @@ -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 +#include +#include + +#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 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 client) : llm::Service(std::move(client)) {} + + SonarResult create(const SonarParams& params); + + using DeltaSink = std::function; // 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& sleeper = nullptr); +}; + +} // namespace molo::perplexity diff --git a/src/vendors/perplexity/sonar_params.cpp b/src/vendors/perplexity/sonar_params.cpp new file mode 100644 index 0000000..0c69f4f --- /dev/null +++ b/src/vendors/perplexity/sonar_params.cpp @@ -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& 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& 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 diff --git a/src/vendors/perplexity/sonar_params.h b/src/vendors/perplexity/sonar_params.h new file mode 100644 index 0000000..86d80c8 --- /dev/null +++ b/src/vendors/perplexity/sonar_params.h @@ -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 +#include +#include + +#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& 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 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 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 messages; + std::optional max_tokens; + std::optional temperature, top_p; + std::vector 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 return_images, return_related_questions, enable_search_classifier, disable_search; + std::vector 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 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 diff --git a/src/vendors/perplexity/sonar_result.cpp b/src/vendors/perplexity/sonar_result.cpp new file mode 100644 index 0000000..8292541 --- /dev/null +++ b/src/vendors/perplexity/sonar_result.cpp @@ -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(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(n) > citations.size()) return ""; + return citations[static_cast(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(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 diff --git a/src/vendors/perplexity/sonar_result.h b/src/vendors/perplexity/sonar_result.h new file mode 100644 index 0000000..33eac36 --- /dev/null +++ b/src/vendors/perplexity/sonar_result.h @@ -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 +#include + +#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 choices; + std::vector citations; // URLs; [n] markers in the text are 1-based indices + std::vector search_results; + std::vector images; + std::vector 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 diff --git a/src/vendors/perplexity/tools/check_spec.py b/src/vendors/perplexity/tools/check_spec.py new file mode 100644 index 0000000..9985fc7 --- /dev/null +++ b/src/vendors/perplexity/tools/check_spec.py @@ -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()) diff --git a/src/vendors/perplexity/types.cpp b/src/vendors/perplexity/types.cpp new file mode 100644 index 0000000..1cebe63 --- /dev/null +++ b/src/vendors/perplexity/types.cpp @@ -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 J::strings(const Json& doc, const char* key) { + std::vector 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(J::num(*usage, "prompt_tokens")); + u.completion_tokens = static_cast(J::num(*usage, "completion_tokens")); + u.total_tokens = static_cast(J::num(*usage, "total_tokens")); + u.citation_tokens = static_cast(J::num(*usage, "citation_tokens")); + u.reasoning_tokens = static_cast(J::num(*usage, "reasoning_tokens")); + u.num_search_queries = static_cast(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::parse_list(const Json* list) { + std::vector 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 diff --git a/src/vendors/perplexity/types.h b/src/vendors/perplexity/types.h new file mode 100644 index 0000000..cd229f4 --- /dev/null +++ b/src/vendors/perplexity/types.h @@ -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 +#include +#include + +#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 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 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 models; + bool truncated = false; + Json raw; + static ModelList parse(const Json& doc); + const ModelInfo* find(const std::string& id) const; +}; + +} // namespace molo::perplexity diff --git a/tests/example/ai/perplexity/page_test.cpp b/tests/example/ai/perplexity/page_test.cpp new file mode 100644 index 0000000..2efc9f4 --- /dev/null +++ b/tests/example/ai/perplexity/page_test.cpp @@ -0,0 +1,33 @@ +// Routes: GET /ai/perplexity (page), /status, /calls, /errors (no credential needed) +#include + +#include "support/Assert.hpp" + +using namespace molo::example::test; + +int main() { + setenv("MOLO_ENV_FILES", "off", 1); + unsetenv("PERPLEXITY_API_KEY"); + Fixture f; + auto page = f.client->get("/ai/perplexity"); + check(page.status == 200, "page 200"); + check(contains(page.headers.get("Content-Type"), "text/html"), "html"); + check(contains(page.body, "Perplexity API") && contains(page.body, "viewport"), "title and mobile viewport"); + check(contains(page.body, "/embedded/ai_perplexity.js"), "script wired"); + check(f.client->post("/ai/perplexity", "{}", "application/json").status == 405, "post page is 405"); + + auto st = f.client->get("/ai/perplexity/status"); + check(st.status == 200 && contains(st.body, "\"configured\":false"), "status without a key"); + check(contains(st.body, "PERPLEXITY_API_KEY") && contains(st.body, "sonar-pro") && contains(st.body, "sonar-deep-research"), + "status names credential env and models"); + check(f.client->post("/ai/perplexity/status", "{}", "application/json").status == 405, "post status is 405"); + + auto calls = f.client->get("/ai/perplexity/calls"); + check(calls.status == 200 && contains(calls.body, "/v1/sonar") && contains(calls.body, "/search") && + contains(calls.body, "/v1/agent") && contains(calls.body, "/orchestrator/v1/chat/completions"), + "call table listed"); + auto errors = f.client->get("/ai/perplexity/errors"); + check(errors.status == 200 && contains(errors.body, "Payment Required") && contains(errors.body, "\"retryable\":true"), + "error table listed"); + return finish("ai/perplexity/page"); +} diff --git a/tests/example/ai/perplexity/routes_test.cpp b/tests/example/ai/perplexity/routes_test.cpp new file mode 100644 index 0000000..f5b6833 --- /dev/null +++ b/tests/example/ai/perplexity/routes_test.cpp @@ -0,0 +1,105 @@ +// Routes: POST /ai/perplexity/* (405, 422, dry runs, 503 without a credential) +#include + +#include "support/Assert.hpp" + +using namespace molo::example::test; + +int main() { + setenv("MOLO_ENV_FILES", "off", 1); + unsetenv("PERPLEXITY_API_KEY"); + Fixture f; + auto post = [&](const std::string& route, const std::string& body) { + return f.client->post("/ai/perplexity/" + route, body, "application/json"); + }; + const char* all[] = {"sonar", "stream", "async", "search", "embeddings", "agent", "orchestrator", + "decisions", "models", "usage", "batches", "skills"}; + for (const char* r : all) { + std::string route = std::string("/ai/perplexity/") + r; + check(f.client->get(route).status == 405, route + " get is 405"); + check(post(r, "not json").status == 422, route + " bad json is 422"); + check(post(r, "[1]").status == 422, route + " non-object is 422"); + } + // 422: input rules run before anything else + check(post("sonar", "{}").status == 422, "sonar needs prompt"); + check(post("sonar", "{\"prompt\":\"hi\",\"max_tokens\":0}").status == 422, "max_tokens 0"); + check(post("sonar", "{\"prompt\":\"hi\",\"temperature\":3}").status == 422, "temperature over 2"); + check(post("sonar", "{\"prompt\":\"hi\",\"search_mode\":\"dark\"}").status == 422, "bad search_mode"); + check(post("sonar", "{\"prompt\":\"hi\",\"search_after_date_filter\":\"2025-01-01\"}").status == 422, "bad date format"); + check(post("sonar", "{\"prompt\":\"hi\",\"json_schema\":[1]}").status == 422, "schema must be object"); + check(post("async", "{\"action\":\"fly\"}").status == 422, "bad async action"); + check(post("async", "{\"action\":\"get\",\"id\":\"../x\"}").status == 422, "bad async id"); + check(post("search", "{\"query\":\" \"}").status == 422, "blank query"); + check(post("search", "{\"query\":\"x\",\"max_results\":21}").status == 422, "max_results over 20"); + check(post("search", "{\"queries\":[\"1\",\"2\",\"3\",\"4\",\"5\",\"6\"]}").status == 422, "more than 5 queries"); + check(post("embeddings", "{}").status == 422, "embeddings need input"); + check(post("embeddings", "{\"input\":[\"x\"],\"dimensions\":64}").status == 422, "dimensions under 128"); + check(post("embeddings", "{\"documents\":[[]]}").status == 422, "empty document"); + check(post("agent", "{}").status == 422, "agent needs input"); + check(post("agent", "{\"input\":\"x\",\"model\":\"anthropic/claude-sonnet-5-5\"}").status == 422, "anthropic models need max_output_tokens"); + check(post("agent", "{\"input\":\"x\",\"tools\":[\"telepathy\"]}").status == 422, "unknown tool"); + check(post("agent", "{\"action\":\"get\",\"id\":\"a/b\"}").status == 422, "bad agent id"); + check(post("orchestrator", "{\"model\":\"kimi\",\"prompt\":\"x\"}").status == 422, "model needs a creator prefix"); + check(post("orchestrator", "{\"api\":\"graphql\",\"model\":\"a/b\",\"prompt\":\"x\"}").status == 422, "bad orchestrator api"); + check(post("decisions", "{\"state\":\"x\"}").status == 422, "decisions need questions"); + check(post("models", "{\"kind\":\"other\"}").status == 422, "bad models kind"); + check(post("usage", "{}").status == 422, "usage needs dataset"); + check(post("usage", "{\"dataset\":\"query_volume\",\"bucket_width\":\"1h\",\"start_time\":1}").status == 422, "daily-only dataset rejects 1h"); + check(post("batches", "{\"action\":\"upload\",\"jsonl\":\"not json\"}").status == 422, "bad jsonl"); + check(post("batches", "{\"action\":\"get\",\"id\":\"../x\"}").status == 422, "bad batch id"); + check(post("skills", "{\"action\":\"delete\",\"id\":\"skill_1\"}").status == 422, "delete needs expected_revision"); + check(post("skills", "{\"action\":\"create\",\"data_base64\":\"aGVsbG8=\"}").status == 422, "not a zip"); + check(post("skills", "{\"action\":\"create\",\"data_base64\":\"@@\"}").status == 422, "bad base64"); + + // dry runs: paid or resource-changing routes show the exact request + auto dry = post("sonar", "{\"prompt\":\"hi\",\"model\":\"sonar-pro\",\"search_mode\":\"academic\"}"); + check(dry.status == 200 && contains(dry.body, "\"dry_run\":true") && contains(dry.body, "\"model\":\"sonar-pro\"") && + contains(dry.body, "/v1/sonar") && contains(dry.body, "\"search_mode\":\"academic\""), + "sonar is a dry run without confirm"); + check(contains(post("stream", "{\"prompt\":\"hi\"}").body, "\"stream\":true"), "stream preview"); + check(contains(post("async", "{\"action\":\"create\",\"prompt\":\"hi\",\"model\":\"sonar-deep-research\"}").body, "/v1/async/sonar"), + "async create is a dry run"); + check(contains(post("search", "{\"query\":\"x\"}").body, "\"dry_run\":true"), "search is a dry run"); + check(contains(post("embeddings", "{\"input\":[\"x\"]}").body, "/v1/embeddings"), "embeddings dry run"); + check(contains(post("embeddings", "{\"documents\":[[\"a\",\"b\"]]}").body, "/v1/contextualizedembeddings"), "contextualized dry run"); + check(contains(post("agent", "{\"input\":\"x\",\"tools\":[\"web_search\"]}").body, "\"type\":\"web_search\""), "agent dry run shows tools"); + check(contains(post("agent", "{\"action\":\"cancel\",\"id\":\"resp_1\"}").body, "\"dry_run\":true"), "cancel is a dry run"); + check(contains(post("orchestrator", "{\"model\":\"perplexity/kimi-k3\",\"prompt\":\"x\"}").body, "/orchestrator/v1/chat/completions"), + "orchestrator dry run"); + check(contains(post("decisions", "{\"state\":\"x\",\"questions\":{\"q\":{\"type\":\"noul\",\"instructions\":\"?\"}}}").body, "\"dry_run\":true"), + "decisions dry run"); + check(contains(post("batches", "{\"action\":\"create\",\"input_file_id\":\"file_1\"}").body, "\"dry_run\":true"), "batch create dry run"); + check(contains(post("batches", "{\"action\":\"cancel\",\"id\":\"batch_1\"}").body, "\"dry_run\":true"), "batch cancel dry run"); + check(contains(post("batches", "{\"action\":\"file_delete\",\"id\":\"file_1\"}").body, "\"dry_run\":true"), "file delete dry run"); + check(contains(post("batches", "{\"action\":\"upload\",\"jsonl\":\"{\\\"custom_id\\\":\\\"1\\\"}\"}").body, "\"dry_run\":true"), "upload dry run"); + check(contains(post("skills", "{\"action\":\"delete\",\"id\":\"skill_1\",\"expected_revision\":\"r1\"}").body, "\"dry_run\":true"), "skill delete dry run"); + check(contains(post("skills", "{\"action\":\"create\",\"data_base64\":\"UEsDBHJlc3Q=\"}").body, "\"dry_run\":true"), "skill create dry run"); + + // 503: free calls and confirmed calls need the credential + const char* reads[] = {"{}", "{\"kind\":\"orchestrator\"}"}; + for (const char* body : reads) { + auto res = post("models", body); + check(res.status == 503 && contains(res.body, "perplexity_not_configured"), "models without key is 503"); + } + check(post("usage", "{\"dataset\":\"credit_usage\",\"start_time\":1}").status == 503, "usage without key is 503"); + check(post("usage", "{\"dataset\":\"credit_usage\",\"start_time\":1,\"per_member\":true}").status == 503, "per member usage without key is 503"); + check(post("async", "{\"action\":\"list\"}").status == 503, "async list without key is 503"); + check(post("async", "{\"action\":\"get\",\"id\":\"req_1\"}").status == 503, "async get without key is 503"); + check(post("agent", "{\"action\":\"get\",\"id\":\"resp_1\"}").status == 503, "agent get without key is 503"); + check(post("agent", "{\"action\":\"files\",\"id\":\"resp_1\"}").status == 503, "agent files without key is 503"); + check(post("batches", "{\"action\":\"list\"}").status == 503, "batches list without key is 503"); + check(post("batches", "{\"action\":\"files\"}").status == 503, "batch files without key is 503"); + check(post("skills", "{\"action\":\"list\"}").status == 503, "skills list without key is 503"); + check(post("sonar", "{\"prompt\":\"hi\",\"confirm\":true}").status == 503, "confirmed sonar without key is 503"); + check(post("stream", "{\"prompt\":\"hi\",\"confirm\":true}").status == 503, "confirmed stream without key is 503"); + check(post("search", "{\"query\":\"x\",\"confirm\":true}").status == 503, "confirmed search without key is 503"); + check(post("embeddings", "{\"input\":[\"x\"],\"confirm\":true}").status == 503, "confirmed embeddings without key is 503"); + check(post("agent", "{\"input\":\"x\",\"confirm\":true}").status == 503, "confirmed agent without key is 503"); + check(post("orchestrator", "{\"model\":\"a/b\",\"prompt\":\"x\",\"confirm\":true}").status == 503, "confirmed orchestrator without key is 503"); + check(post("decisions", "{\"state\":\"x\",\"questions\":{\"q\":{\"type\":\"noul\",\"instructions\":\"?\"}},\"confirm\":true}").status == 503, + "confirmed decisions without key is 503"); + check(post("skills", "{\"action\":\"delete\",\"id\":\"skill_1\",\"expected_revision\":\"r1\",\"confirm\":true}").status == 503, + "confirmed skill delete without key is 503"); + check(post("batches", "{\"action\":\"cancel\",\"id\":\"b1\",\"confirm\":true}").status == 503, "confirmed batch cancel without key is 503"); + return finish("ai/perplexity/routes"); +} diff --git a/tests/src/vendors/perplexity/support.h b/tests/src/vendors/perplexity/support.h new file mode 100644 index 0000000..493cbe5 --- /dev/null +++ b/tests/src/vendors/perplexity/support.h @@ -0,0 +1,52 @@ +#pragma once + +// Shared rig for the Perplexity tests: a Platform over a MockTransport with a +// fake key. The mock only records the requests the real client builds; replies +// are fixtures labelled where they appear: FIXTURE (verbatim from the +// Perplexity docs) or SCHEMA (shape taken from the OpenAPI schema, values +// invented). Nothing here verifies vendor behavior (see +// src/vendors/perplexity/SPEC.md ## Unverified). + +#include +#include + +#include "clients/transports/mock_transport.h" +#include "framework.h" +#include "vendors/perplexity/platform.h" + +namespace perplexity_test { + +using molo::clients::ClientResponse; +using molo::clients::HeaderMap; +using molo::clients::Method; +using molo::clients::transports::MockExpectation; +using molo::clients::transports::MockTransport; +using Json = molo::clients::body::Json; + +inline ClientResponse reply(const std::string& body, int status = 200, + const std::string& type = "application/json") { + HeaderMap h; + h.set("Content-Type", type); + return ClientResponse(status, h, body); +} + +inline ClientResponse sse(const std::string& body) { return reply(body, 200, "text/event-stream"); } + +inline bool has(const std::string& hay, const std::string& needle) { return hay.find(needle) != std::string::npos; } + +inline const char* kKey = "pplx-TESTKEY-DO-NOT-LEAK"; + +struct Rig { + MockTransport* transport = nullptr; + molo::perplexity::Platform platform; + + explicit Rig(const std::string& key = kKey) { + auto t = std::make_unique(); + transport = t.get(); + platform = molo::perplexity::Platform::with(std::move(t), key); + } + std::shared_ptr client() const { return platform.client; } + MockTransport::SeenRequest last() const { return transport->seen().back(); } +}; + +} // namespace perplexity_test diff --git a/tests/src/vendors/perplexity/test_agent.cpp b/tests/src/vendors/perplexity/test_agent.cpp new file mode 100644 index 0000000..a98b30f --- /dev/null +++ b/tests/src/vendors/perplexity/test_agent.cpp @@ -0,0 +1,228 @@ +// Agent API: create, stream, background, retrieve, cancel, files, tools. +#include "support.h" +#include "vendors/perplexity/agent.h" + +using namespace molo::perplexity; +using namespace perplexity_test; +using molo::llm::ApiError; + +namespace { +// SCHEMA: ResponsesResponse with message (annotations), search_results, function_call, usage.cost +const char* kResponse = + "{\"id\":\"resp_1\",\"object\":\"response\",\"created_at\":1760000000,\"status\":\"completed\",\"model\":\"openai/gpt-5.6-terra\",\"effort\":\"fast@2026-09-29.0\"," + "\"output\":[" + "{\"type\":\"search_results\",\"queries\":[\"capital of france\"],\"results\":[{\"id\":1,\"url\":\"https://example.com/a\",\"title\":\"A\",\"snippet\":\"s\",\"source\":\"web\",\"date\":\"2025-01-01\"}]}," + "{\"type\":\"message\",\"id\":\"msg_1\",\"status\":\"completed\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Paris [1].\"," + "\"annotations\":[{\"type\":\"url_citation\",\"url\":\"https://example.com/a\",\"title\":\"A\",\"start_index\":6,\"end_index\":9}]}]}," + "{\"type\":\"function_call\",\"id\":\"fc_1\",\"status\":\"completed\",\"call_id\":\"call_1\",\"name\":\"get_time\",\"arguments\":\"{\\\"tz\\\":\\\"UTC\\\"}\"}]," + "\"usage\":{\"input_tokens\":100,\"output_tokens\":20,\"total_tokens\":120,\"input_tokens_details\":{\"cached_tokens\":40}," + "\"cost\":{\"currency\":\"USD\",\"input_cost\":0.001,\"output_cost\":0.002,\"tool_calls_cost\":0.005,\"total_cost\":0.008}}}"; + +// Event names from the OpenAPI EventType enum; payload keys from the event schemas. +const char* kStream = + "event: response.created\ndata: {\"type\":\"response.created\",\"sequence_number\":0,\"response\":{\"id\":\"resp_s\",\"object\":\"response\",\"status\":\"in_progress\",\"model\":\"m\",\"created_at\":1,\"output\":[]}}\n\n" + ": keep-alive\n\n" + "event: response.reasoning.search_queries\ndata: {\"type\":\"response.reasoning.search_queries\",\"sequence_number\":1,\"queries\":[\"q1\"],\"thought\":\"searching\"}\n\n" + "event: response.reasoning.search_results\ndata: {\"type\":\"response.reasoning.search_results\",\"sequence_number\":2,\"results\":[{\"id\":1,\"url\":\"https://example.com/a\",\"title\":\"A\",\"snippet\":\"s\"}]}\n\n" + "event: response.output_text.delta\ndata: {\"type\":\"response.output_text.delta\",\"sequence_number\":3,\"item_id\":\"msg_1\",\"output_index\":0,\"content_index\":0,\"delta\":\"Hel\"}\n\n" + "event: response.output_text.delta\ndata: {\"type\":\"response.output_text.delta\",\"sequence_number\":4,\"item_id\":\"msg_1\",\"output_index\":0,\"content_index\":0,\"delta\":\"lo\"}\n\n" + "event: response.completed\ndata: {\"type\":\"response.completed\",\"sequence_number\":5,\"response\":{\"id\":\"resp_s\",\"object\":\"response\",\"status\":\"completed\",\"model\":\"m\",\"created_at\":1," + "\"output\":[{\"type\":\"message\",\"id\":\"msg_1\",\"status\":\"completed\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello\"}]}]," + "\"usage\":{\"input_tokens\":5,\"output_tokens\":2,\"total_tokens\":7}}}\n\n" + "data: [DONE]\n\n"; +} // namespace + +TEST(perplexity_agent, create_with_tools_skills_and_parse_every_accessor) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/agent", reply(kResponse)); + Agent agent(rig.client()); + AgentParams p = AgentParams::prompt("Capital of France?", "openai/gpt-5.6-terra"); + p.instructions = "Be brief."; + WebSearchToolOptions ws; + ws.max_results = 5; + ws.search_recency_filter = "week"; + ws.search_domain_filter = {"example.com"}; + p.tools = {AgentTools::web_search(ws), AgentTools::fetch_url(3), AgentTools::sandbox(), + AgentTools::function("get_time", "time", Json::parse("{\"type\":\"object\",\"properties\":{}}"), true)}; + p.tool_choice = AgentTools::choice("auto"); + p.skills = {AgentSkills::builtin("office/pdf"), AgentSkills::custom("skill_abc", "latest")}; + p.max_steps = 12; + p.reasoning_effort = "high"; + AgentResult r = agent.create(p); + ASSERT_EQ(r.id, "resp_1"); + ASSERT_EQ(r.status, "completed"); + ASSERT_TRUE(r.finished()); + ASSERT_TRUE(r.succeeded()); + ASSERT_EQ(r.effort, "fast@2026-09-29.0"); + ASSERT_EQ(r.output_text(), "Paris [1]."); + ASSERT_EQ(r.citations().size(), 1u); + ASSERT_EQ(r.citations()[0].end_index, 9L); + ASSERT_EQ(r.search_results().size(), 1u); + ASSERT_EQ(r.search_results()[0].id, 1L); + ASSERT_EQ(r.queries()[0], "capital of france"); + ASSERT_EQ(r.function_calls().size(), 1u); + ASSERT_TRUE(r.function_calls()[0].arguments_valid()); + ASSERT_EQ(r.function_calls()[0].parsed().find("tz")->as_string(), "UTC"); + ASSERT_EQ(r.usage.input_tokens, 100L); + ASSERT_EQ(r.usage.cached_tokens, 40L); + ASSERT_EQ(r.usage.cost.tool_calls, 0.005); + ASSERT_EQ(r.usage.cost.currency, "USD"); + auto s = rig.last(); + ASSERT_TRUE(has(s.body, "\"model\":\"openai/gpt-5.6-terra\"")); + ASSERT_TRUE(has(s.body, "\"type\":\"web_search\"")); + ASSERT_TRUE(has(s.body, "\"filters\":{\"search_domain_filter\":[\"example.com\"],\"search_recency_filter\":\"week\"}")); + ASSERT_TRUE(has(s.body, "\"max_urls\":3")); + ASSERT_TRUE(has(s.body, "{\"type\":\"sandbox\"}")); + ASSERT_TRUE(has(s.body, "\"skills\":[{\"name\":\"office/pdf\",\"type\":\"builtin\"},{\"id\":\"skill_abc\",\"type\":\"custom\",\"version\":\"latest\"}]")); + ASSERT_TRUE(has(s.body, "\"reasoning\":{\"effort\":\"high\"}")); + ASSERT_TRUE(has(s.body, "\"tool_choice\":\"auto\"")); + ASSERT_FALSE(has(s.body, "\"stream\"")); +} + +TEST(perplexity_agent, effort_profile_and_fallback_rules) { + Rig rig; + Agent agent(rig.client()); + AgentParams p = AgentParams::with_effort("hi", "fast@latest"); + p.to_json(); + p.profile_id = "prof_1"; + ASSERT_THROW(agent.create(p), ApiError); // profile + effort + p.effort.clear(); + p.model = "openai/gpt-5.6-terra"; + Json b = p.to_json(); + ASSERT_EQ(b.find("profile")->find("type")->as_string(), "custom"); + p.models = {"a/1", "a/2", "a/3", "a/4", "a/5", "a/6"}; + ASSERT_THROW(agent.create(p), ApiError); // more than 5 fallbacks + AgentParams anth = AgentParams::prompt("hi", "anthropic/claude-sonnet-5-5"); + ASSERT_THROW(agent.create(anth), ApiError); // max_output_tokens required + anth.max_output_tokens = 1024; + anth.to_json(); + ASSERT_EQ(rig.transport->send_count(), 0u); +} + +TEST(perplexity_agent, builders_validate_their_inputs) { + WebSearchToolOptions deep; + deep.search_type = "deep"; + ASSERT_THROW(AgentTools::web_search(deep), ApiError); + WebSearchToolOptions many; + many.max_results = 51; + ASSERT_THROW(AgentTools::web_search(many), ApiError); + ASSERT_THROW(AgentTools::image_search(31), ApiError); + ASSERT_THROW(AgentTools::fetch_url(11), ApiError); + ASSERT_THROW(AgentTools::mcp("lbl", "http://insecure.example.com"), ApiError); + ASSERT_THROW(AgentTools::mcp("bad label", "https://example.com/mcp"), ApiError); + ASSERT_THROW(AgentTools::choice("sometimes"), ApiError); + ASSERT_THROW(AgentSkills::builtin("office/odt"), ApiError); + ASSERT_THROW(AgentSkills::custom("abc"), ApiError); + ASSERT_THROW(AgentSkills::inline_skill("Bad_Name", "d", "i"), ApiError); + ASSERT_THROW(AgentSkills::inline_skill("ok-name", std::string(1025, 'd'), "i"), ApiError); + ASSERT_THROW(AgentInput::file_part("", ""), ApiError); + ASSERT_THROW(AgentInput::file_part("AAAA", "https://example.com/a.pdf"), ApiError); + ASSERT_THROW(AgentInput::mcp_approval_response("id", true, "because"), ApiError); + AgentTools::mcp("lbl", "https://example.com/mcp", "tok", {"search"}, "always"); + AgentParams p = AgentParams::prompt("x", "a/b"); + p.skills.assign(17, AgentSkills::builtin("office")); + ASSERT_THROW(p.to_json(), ApiError); +} + +TEST(perplexity_agent, stream_folds_events_and_returns_the_completed_response) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/agent", sse(kStream)); + Agent agent(rig.client()); + std::string text; + std::vector types, queries; + AgentResult r = agent.stream(AgentParams::prompt("Hi", "a/b"), [&](const AgentDelta& d) { + text += d.text; + types.push_back(d.type); + for (const std::string& q : d.queries) queries.push_back(q); + return true; + }); + ASSERT_EQ(text, "Hello"); + ASSERT_EQ(types.size(), 6u); // the keep-alive comment and [DONE] produce no event + ASSERT_EQ(types.front(), "response.created"); + ASSERT_EQ(types.back(), "response.completed"); + ASSERT_EQ(queries.size(), 1u); + ASSERT_EQ(r.id, "resp_s"); + ASSERT_EQ(r.output_text(), "Hello"); + ASSERT_EQ(r.usage.total_tokens, 7L); + ASSERT_TRUE(has(rig.last().body, "\"stream\":true")); +} + +TEST(perplexity_agent, stream_failure_event_and_truncation) { + Rig rig; + rig.transport->expect_response( + Method::kPost, "/v1/agent", + sse("event: response.failed\ndata: {\"type\":\"response.failed\",\"sequence_number\":1,\"error\":{\"type\":\"server_error\",\"code\":\"x\",\"message\":\"boom\"}}\n\n")); + AgentResult r = Agent(rig.client()).stream(AgentParams::prompt("Hi", "a/b"), nullptr); + ASSERT_EQ(r.status, "failed"); + ASSERT_EQ(r.error.message, "boom"); + ASSERT_FALSE(r.succeeded()); + Rig cut; + cut.transport->expect_response( + Method::kPost, "/v1/agent", + sse("event: response.output_text.delta\ndata: {\"type\":\"response.output_text.delta\",\"sequence_number\":1,\"delta\":\"par\"}\n\n")); + try { + Agent(cut.client()).stream(AgentParams::prompt("Hi", "a/b"), nullptr); + FAIL("expected STREAM_TRUNCATED"); + } catch (const ApiError& e) { + ASSERT_EQ(e.type(), "STREAM_TRUNCATED"); + } +} + +TEST(perplexity_agent, background_get_wait_cancel_and_files) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/agent", + reply("{\"id\":\"resp_b\",\"object\":\"response\",\"status\":\"queued\",\"model\":\"m\",\"created_at\":1,\"output\":[]}")); + Agent agent(rig.client()); + AgentResult q = agent.create_background(AgentParams::prompt("long task", "a/b")); + ASSERT_EQ(q.status, "queued"); + ASSERT_FALSE(q.finished()); + ASSERT_TRUE(has(rig.last().body, "\"background\":true")); + + Rig poll; + poll.transport->expect_response(Method::kGet, "/v1/agent/resp_b", + reply("{\"id\":\"resp_b\",\"object\":\"response\",\"status\":\"in_progress\",\"model\":\"m\",\"created_at\":1,\"output\":[]," + "\"paused\":{\"reason\":\"token_rate_limit\",\"window\":\"TPM\",\"estimated_resume_at\":1791302400}}")); + poll.transport->expect_response(Method::kGet, "/v1/agent/resp_b", reply(kResponse)); + Agent pagent(poll.client()); + int slept = 0; + AgentResult r = pagent.wait("resp_b", 1, 10, [&](int s) { slept += s; }); + ASSERT_TRUE(r.succeeded()); + ASSERT_EQ(slept, 1); + + Rig p2; + p2.transport->expect_response(Method::kGet, "/v1/agent/resp_b", + reply("{\"id\":\"resp_b\",\"object\":\"response\",\"status\":\"in_progress\",\"model\":\"m\",\"created_at\":1,\"output\":[]," + "\"paused\":{\"reason\":\"token_rate_limit\",\"window\":\"TPM\",\"estimated_resume_at\":1791302400}}")); + AgentResult paused = Agent(p2.client()).get("resp_b"); + ASSERT_TRUE(paused.has_pause); + ASSERT_EQ(paused.pause.window, "TPM"); + ASSERT_EQ(paused.pause.estimated_resume_at, 1791302400L); + + Rig c; + c.transport->expect_response(Method::kPost, "/v1/agent/resp_b/cancel", reply("{\"response_id\":\"resp_b\",\"status\":\"cancelling\"}")); + Json cj = Agent(c.client()).cancel("resp_b"); + ASSERT_EQ(cj.find("status")->as_string(), "cancelling"); + + Rig f; + f.transport->expect_response(Method::kGet, "/v1/agent/resp_b/files", + reply("{\"object\":\"list\",\"data\":[{\"id\":\"file_1\",\"object\":\"file\",\"filename\":\"out.csv\",\"bytes\":12,\"created_at\":5}]}")); + f.transport->expect_response(Method::kGet, "/v1/agent/resp_b/files/file_1/content", reply("a,b\n1,2\n", 200, "application/octet-stream")); + Agent fagent(f.client()); + AgentFileList fl = fagent.files("resp_b"); + ASSERT_EQ(fl.files.size(), 1u); + ASSERT_EQ(fl.files[0].filename, "out.csv"); + FileBytes fb = fagent.file_content("resp_b", "file_1"); + ASSERT_EQ(fb.data, "a,b\n1,2\n"); + ASSERT_EQ(fb.content_type, "application/octet-stream"); +} + +TEST(perplexity_agent, ids_are_validated_and_wait_has_bounds) { + Rig rig; + Agent agent(rig.client()); + ASSERT_THROW(agent.get("../etc"), ApiError); + ASSERT_THROW(agent.cancel("a/b"), ApiError); + ASSERT_THROW(agent.file_content("resp_1", "x?y"), ApiError); + ASSERT_THROW(agent.wait("resp_1", 0, 10), ApiError); + ASSERT_THROW(agent.wait("resp_1", 1, 601), ApiError); + ASSERT_EQ(rig.transport->send_count(), 0u); +} diff --git a/tests/src/vendors/perplexity/test_live.cpp b/tests/src/vendors/perplexity/test_live.cpp new file mode 100644 index 0000000..90b4e92 --- /dev/null +++ b/tests/src/vendors/perplexity/test_live.cpp @@ -0,0 +1,75 @@ +// Opt-in live checks. MOLO_LIVE_NET=1 enables the network; PERPLEXITY_API_KEY +// (via llm::Config) enables the read-only calls. MOLO_LIVE_PAID=1 additionally +// allows ONE smallest-possible Sonar completion and one Search. Without them +// each test prints a loud SKIP. Nothing is created or deleted. +#include +#include + +#include "clients/transports/http_transport.h" +#include "support.h" +#include "vendors/perplexity/account.h" +#include "vendors/perplexity/search.h" +#include "vendors/perplexity/sonar.h" + +using namespace molo::perplexity; +using molo::llm::ApiError; + +namespace { +// Read at static-init time: tests/src/llm/test_llm.cpp unsetenv()s MOLO_LIVE_NET mid-run (suite gap). +const bool g_net = std::getenv("MOLO_LIVE_NET") != nullptr; +const bool g_paid = std::getenv("MOLO_LIVE_PAID") != nullptr; +bool net() { return g_net; } +bool paid() { return g_paid; } +} // namespace + +// No key needed: a deliberately invalid key must answer 401 with the +// documented error envelope (type invalid_api_key). Recorded 2026-10-25. +TEST(perplexity_live, invalid_key_answers_401_with_the_error_envelope) { + if (!net()) { + std::cout << "SKIP perplexity_live.invalid_key_answers_401_with_the_error_envelope (set MOLO_LIVE_NET=1)\n"; + return; + } + auto client = std::make_shared( + std::make_unique(), Platform::config(), "pplx-invalid-molo-probe"); + Account acct(client); + try { + acct.models(); + FAIL("expected 401"); + } catch (const ApiError& e) { + std::cout << " GET /v1/models with an invalid key: " << e.http_status() << " " << e.type() << "\n"; + ASSERT_EQ(e.http_status(), 401); + ASSERT_EQ(e.type(), "invalid_api_key"); + } +} + +TEST(perplexity_live, models_and_usage_are_read_only) { + Platform p = Platform::from_env(); + if (!net() || !p.configured()) { + std::cout << "SKIP perplexity_live.models_and_usage_are_read_only (set MOLO_LIVE_NET=1 and PERPLEXITY_API_KEY)\n"; + return; + } + Account acct(p.client); + ModelList models = acct.models(); + std::cout << " agent models: " << models.models.size() << "\n"; + ASSERT_TRUE(!models.models.empty()); +} + +TEST(perplexity_live, one_smallest_search_and_one_sonar_completion) { + Platform p = Platform::from_env(); + if (!net() || !p.configured() || !paid()) { + std::cout << "SKIP perplexity_live.one_smallest_search_and_one_sonar_completion " + "(set MOLO_LIVE_NET=1, MOLO_LIVE_PAID=1 and PERPLEXITY_API_KEY)\n"; + return; + } + SearchParams sp = SearchParams::of("perplexity api", 1); + sp.max_tokens_per_page = 64; + SearchResponse sr = Search(p.client).run(sp); + std::cout << " search results: " << sr.results.size() << "\n"; + ASSERT_TRUE(!sr.id.empty()); + SonarParams params = SonarParams::prompt("Reply with the single word: ok"); + params.max_tokens = 8; + params.disable_search = true; + SonarResult r = Sonar(p.client).create(params); + std::cout << " completion finish=" << r.first().finish_reason << " tokens=" << r.usage.total_tokens << "\n"; + ASSERT_TRUE(r.usage.present); +} diff --git a/tests/src/vendors/perplexity/test_model_tables.cpp b/tests/src/vendors/perplexity/test_model_tables.cpp new file mode 100644 index 0000000..1a15cbc --- /dev/null +++ b/tests/src/vendors/perplexity/test_model_tables.cpp @@ -0,0 +1,194 @@ +// PerplexityChatModel (neutral seam), the call table, error table and rules. +#include + +#include "support.h" +#include "vendors/perplexity/calls.h" +#include "vendors/perplexity/chat_model.h" +#include "vendors/perplexity/errors.h" +#include "vendors/perplexity/rules.h" + +using namespace molo::perplexity; +using namespace perplexity_test; +using molo::llm::ApiError; + +namespace { +const char* kReply = + "{\"id\":\"c1\",\"model\":\"sonar\",\"created\":1,\"choices\":[{\"index\":0,\"finish_reason\":\"length\",\"message\":{\"role\":\"assistant\",\"content\":\"4\"},\"delta\":{\"role\":\"assistant\",\"content\":\"\"}}]," + "\"citations\":[\"https://example.com/a\"],\"usage\":{\"prompt_tokens\":3,\"completion_tokens\":1,\"total_tokens\":4,\"reasoning_tokens\":1,\"cost\":{\"input_tokens_cost\":0,\"output_tokens_cost\":0,\"total_cost\":0}}}"; +const char* kStream = + "data: {\"id\":\"s\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"4\"},\"finish_reason\":null}]}\n\n" + "data: {\"id\":\"s\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\"},\"finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":3,\"completion_tokens\":1,\"total_tokens\":4,\"cost\":{\"input_tokens_cost\":0,\"output_tokens_cost\":0,\"total_cost\":0}}}\n\n" + "data: [DONE]\n\n"; +} // namespace + +TEST(perplexity_chat_model, generate_maps_request_and_response) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/sonar", reply(kReply)); + PerplexityChatModel model(std::make_shared(rig.client())); + molo::llm::ChatRequest req; + req.system = "Be terse."; + req.messages.push_back(molo::llm::Message::user("2+2?")); + req.max_tokens = 5; + req.temperature = 0.2; + req.reasoning_effort = "low"; + req.extra = Json::parse("{\"search_mode\":\"academic\",\"disable_search\":true}"); + molo::llm::ChatResponse res = model.generate(req); + ASSERT_EQ(model.vendor(), "perplexity"); + ASSERT_EQ(res.text(), "4"); + ASSERT_EQ(res.finish_reason, "length"); + ASSERT_EQ(res.usage.input_tokens, 3); + ASSERT_EQ(res.usage.reasoning_tokens, 1); + ASSERT_EQ(res.raw.find("citations")->as_array().size(), 1u); + auto s = rig.last(); + ASSERT_TRUE(has(s.body, "\"model\":\"sonar\"")); + ASSERT_TRUE(has(s.body, "{\"content\":\"Be terse.\",\"role\":\"system\"}")); + ASSERT_TRUE(has(s.body, "\"max_tokens\":5")); + ASSERT_TRUE(has(s.body, "\"search_mode\":\"academic\"")); + ASSERT_TRUE(has(s.body, "\"disable_search\":true")); +} + +TEST(perplexity_chat_model, response_schema_and_images) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/sonar", reply(kReply)); + PerplexityChatModel model(std::make_shared(rig.client()), "sonar-pro"); + molo::llm::ChatRequest req; + molo::llm::Message m; + m.role = molo::llm::Role::kUser; + m.parts.push_back(molo::llm::ContentPart::of_text("what is this")); + molo::llm::ImageData img; + img.mime = "image/png"; + img.bytes = "abc"; + m.parts.push_back(molo::llm::ContentPart::of_image(img)); + req.messages.push_back(m); + req.response_schema = Json::parse("{\"type\":\"object\"}"); + model.generate(req); + auto s = rig.last(); + ASSERT_TRUE(has(s.body, "\"model\":\"sonar-pro\"")); + ASSERT_TRUE(has(s.body, "\"image_url\":{\"url\":\"data:image/png;base64,YWJj\"}")); + ASSERT_TRUE(has(s.body, "\"response_format\":{\"json_schema\":")); +} + +TEST(perplexity_chat_model, unsupported_features_are_rejected_loudly) { + Rig rig; + PerplexityChatModel model(std::make_shared(rig.client())); + molo::llm::ChatRequest req; + req.messages.push_back(molo::llm::Message::user("hi")); + molo::llm::ToolSpec t; + t.name = "f"; + req.tools.push_back(t); + ASSERT_THROW(model.generate(req), ApiError); + req.tools.clear(); + req.json_mode = true; + ASSERT_THROW(model.generate(req), ApiError); + req.json_mode = false; + req.extra = Json::parse("{\"temperature_typo\":1}"); + ASSERT_THROW(model.generate(req), ApiError); + req.extra = Json(); + molo::llm::Message tool; + tool.role = molo::llm::Role::kTool; + tool.parts.push_back(molo::llm::ContentPart::of_result({"c", "r", false})); + req.messages.push_back(tool); + ASSERT_THROW(model.generate(req), ApiError); + ASSERT_EQ(rig.transport->send_count(), 0u); +} + +TEST(perplexity_chat_model, stream_emits_text_finish_and_usage) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/sonar", sse(kStream)); + PerplexityChatModel model(std::make_shared(rig.client())); + molo::llm::ChatRequest req; + req.messages.push_back(molo::llm::Message::user("2+2?")); + std::string text, finish; + int total = 0; + model.stream(req, [&](const molo::llm::ChatChunk& c) { + text += c.text_delta; + if (!c.finish_reason.empty()) finish = c.finish_reason; + if (c.usage) total = c.usage->total_tokens; + return true; + }); + ASSERT_EQ(text, "4"); + ASSERT_EQ(finish, "stop"); + ASSERT_EQ(total, 4); +} + +TEST(perplexity_calls, table_is_consistent) { + std::set seen; + for (std::size_t i = 0; i < Calls::count(); ++i) { + const CallSpec& s = Calls::at(i); + ASSERT_TRUE(std::string(s.path).front() == '/'); + ASSERT_TRUE(seen.insert(std::string(s.http_method) + " " + s.path).second); // no duplicate rows + ASSERT_EQ(&Calls::spec_of(s.call) == &s, true); + } + ASSERT_EQ(Calls::count(), 39u); + ASSERT_TRUE(Calls::schema_count() > 40); +} + +TEST(perplexity_calls, render_validates_every_id) { + ASSERT_EQ(Calls::render(Call::kSonar), "/v1/sonar"); + ASSERT_EQ(Calls::render(Call::kAgentGet, "resp_1"), "/v1/agent/resp_1"); + ASSERT_EQ(Calls::render(Call::kAgentFileContent, std::vector{"r", "f"}), "/v1/agent/r/files/f/content"); + ASSERT_EQ(Calls::render(Call::kOrchModel, "perplexity/kimi-k3"), "/orchestrator/v1/models/perplexity/kimi-k3"); + ASSERT_THROW(Calls::render(Call::kAgentGet, "../x"), ApiError); + ASSERT_THROW(Calls::render(Call::kAgentGet, ""), ApiError); + ASSERT_THROW(Calls::render(Call::kAgentGet), ApiError); // missing id + ASSERT_THROW(Calls::render(Call::kSonar, "extra"), ApiError); // unexpected id + ASSERT_THROW(Calls::render(Call::kBatchGet, "a/b"), ApiError); // only models may carry a slash + ASSERT_EQ(Calls::method_of(Call::kSkillUpdate) == molo::clients::Method::kPut, true); + ASSERT_EQ(Calls::method_of(Call::kFileDelete) == molo::clients::Method::kDelete, true); +} + +TEST(perplexity_errors, table_and_advice) { + ASSERT_TRUE(Errors::kind_of(401) == ErrorKind::kAuth); + ASSERT_TRUE(Errors::kind_of(402) == ErrorKind::kPayment); + ASSERT_TRUE(Errors::kind_of(429) == ErrorKind::kRateLimit); + ASSERT_TRUE(Errors::kind_of(204) == ErrorKind::kNone); + ASSERT_TRUE(Errors::kind_of(418) == ErrorKind::kOther); + ASSERT_TRUE(Errors::retryable(429)); + ASSERT_TRUE(Errors::retryable(503)); + ASSERT_FALSE(Errors::retryable(400)); + ASSERT_FALSE(Errors::retryable(401)); + ASSERT_EQ(Errors::wait_seconds(400), 0); + ASSERT_TRUE(Errors::wait_seconds(429) >= 1 && Errors::wait_seconds(429) <= Errors::kMaxWaitSeconds); + ASSERT_TRUE(Errors::is_rate_limit_type("token_rate_limit_exceeded")); + ASSERT_FALSE(Errors::is_rate_limit_type("invalid_api_key")); + ApiError e("perplexity", 402, "x", "no credits"); + ASSERT_TRUE(has(Errors::explain(e), "Payment Required")); + ASSERT_TRUE(has(Errors::explain(ApiError("perplexity", 599, "weird", "m")), "weird")); +} + +TEST(perplexity_rules, formats) { + Rules::date("01/31/2025", "d"); + Rules::date("1/2/2025", "d"); + ASSERT_THROW(Rules::date("2025-01-31", "d"), ApiError); + ASSERT_THROW(Rules::date("13/01/2025", "d"), ApiError); + ASSERT_THROW(Rules::date("01/32/2025", "d"), ApiError); + ASSERT_THROW(Rules::date("01/01/25", "d"), ApiError); + Rules::language("en", "l"); + ASSERT_THROW(Rules::language("english", "l"), ApiError); + ASSERT_THROW(Rules::language("e1", "l"), ApiError); + Rules::model("perplexity/kimi-k3"); + ASSERT_THROW(Rules::model(""), ApiError); + ASSERT_THROW(Rules::model("a b"), ApiError); + ASSERT_THROW(Rules::model(std::string(129, 'a')), ApiError); + ASSERT_THROW(Rules::https_url("http://example.com", "u"), ApiError); + ASSERT_THROW(Rules::https_url("https://user@example.com", "u"), ApiError); + Rules::https_url("https://example.com/mcp", "u"); + ASSERT_EQ(Rules::url_encode("a b&c"), "a%20b%26c"); + ASSERT_THROW(Rules::filename("a/b"), ApiError); + ASSERT_THROW(Rules::top_p(1.5), ApiError); + Rules::top_p(0.0); + Rules::temperature(2.0); + ASSERT_THROW(Rules::temperature(-0.1), ApiError); +} + +TEST(perplexity_platform, key_travels_in_the_header_only) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/sonar", reply(kReply)); + Sonar(rig.client()).create(SonarParams::prompt("hi")); + auto s = rig.last(); + ASSERT_EQ(s.headers.get_or("Authorization", ""), std::string("Bearer ") + kKey); + ASSERT_EQ(s.target.find(kKey), std::string::npos); + ASSERT_EQ(s.body.find(kKey), std::string::npos); + ASSERT_EQ(std::string(Platform::kKeyEnv), "PERPLEXITY_API_KEY"); + ASSERT_EQ(std::string(Platform::config().base_url), "https://api.perplexity.ai"); +} diff --git a/tests/src/vendors/perplexity/test_platform.cpp b/tests/src/vendors/perplexity/test_platform.cpp new file mode 100644 index 0000000..7f7c76a --- /dev/null +++ b/tests/src/vendors/perplexity/test_platform.cpp @@ -0,0 +1,345 @@ +// Decisions, batches and batch files, skills, models, usage analytics, auth +// tokens and the Orchestrator API. +#include "support.h" +#include "vendors/perplexity/account.h" +#include "vendors/perplexity/batches.h" +#include "vendors/perplexity/decisions.h" +#include "vendors/perplexity/orchestrator.h" +#include "vendors/perplexity/skills.h" + +using namespace molo::perplexity; +using namespace perplexity_test; +using molo::llm::ApiError; + +namespace { +// FIXTURE: docs, Decisions "ledger" recipe: "This is what it returned on 2026-10-15". +const char* kDecisions = + "{\"model\":\"pplx-decider-latest\",\"answers\":{" + "\"on_policy\":{\"type\":\"noul\",\"noul\":2.2697375997445083e-05}," + "\"matches_records\":{\"type\":\"noul\",\"noul\":2.8507326485291256e-05}," + "\"reversible\":{\"type\":\"noul\",\"noul\":0.015321437622110887}}," + "\"usage\":{\"input_tokens\":1113,\"output_tokens\":3}}"; +// SCHEMA: ChoiceAnswer and ScoreAnswer +const char* kDecisionsMixed = + "{\"model\":\"pplx-decider-v1.2\",\"answers\":{" + "\"kind\":{\"type\":\"choice\",\"choice\":\"bug\",\"confidence\":0.8,\"probabilities\":{\"bug\":0.9,\"feature\":0.1}}," + "\"urgency\":{\"type\":\"score\",\"score\":1.4,\"confidence\":0.5,\"legend\":{\"0\":\"low\",\"1\":\"high\"},\"probabilities\":{\"0\":0.6,\"1\":0.4}}}," + "\"usage\":{\"input_tokens\":10,\"output_tokens\":2}}"; +// FIXTURE: docs, Batch API "Response (abbreviated)" +const char* kBatch = + "{\"id\":\"batch_01M4RFGZENVEQTVVJ2222M2JD6\",\"object\":\"batch\",\"status\":\"validating\",\"input_file_id\":\"file_01M4RFGV5DQFAZY29N9C2624A6\"," + "\"created_at\":1791822953,\"expires_at\":1791995753,\"output_file_id\":null,\"error_file_id\":null," + "\"request_counts\":{\"completed\":0,\"failed\":0,\"total\":3},\"metadata\":{\"job\":\"nightly-eval\"}}"; +// SCHEMA: BatchFile, BatchFileList, BatchFileDeleted +const char* kBatchFile = + "{\"id\":\"file_1\",\"object\":\"file\",\"bytes\":120,\"created_at\":5,\"expires_at\":99,\"filename\":\"in.jsonl\",\"purpose\":\"batch\"}"; +// SCHEMA: ManagedSkill, SkillList +const char* kSkill = + "{\"skill_id\":\"skill_abc\",\"name\":\"pdf-notes\",\"description\":\"d\",\"revision\":\"r1\",\"latest_revision\":\"r2\",\"created_at\":\"2026-10-01T00:00:00Z\",\"updated_at\":\"2026-10-02T00:00:00Z\"}"; +const std::string kZip = std::string("PK\x03\x04", 4) + "rest-of-the-archive"; +// FIXTURE: OpenAPI example for GET /v1/analytics/computer/usage +const char* kUsageV1 = + "{\"categories\":[\"Model\",\"Credit Source\"],\"data\":[{\"start_time\":1746057600,\"end_time\":1746144000,\"count\":350,\"by_categories\":{\"Model\":[{\"category\":\"claude-opus-5-5\",\"count\":210},{\"category\":\"claude-sonnet-5-5\",\"count\":120}],\"Credit Source\":[{\"category\":\"paid\",\"count\":250},{\"category\":\"promo\",\"count\":80}]}}],\"has_more\":false,\"next_page\":null}"; +// FIXTURE: OpenAPI example for GET /v2/analytics/computer/usage +const char* kUsageV2 = + "{\"categories\":[\"Model\",\"Credit Source\"],\"data\":[{\"start_time\":1746057600,\"end_time\":1746144000,\"results\":[{\"user_email\":\"alice@example.com\",\"count\":900,\"by_categories\":{\"Model\":[{\"category\":\"claude-opus-5-5\",\"count\":900}],\"Credit Source\":[{\"category\":\"paid\",\"count\":900}]}},{\"user_email\":\"bob@example.com\",\"count\":500,\"by_categories\":{}}]}],\"has_more\":true,\"next_page\":\"eyJwayI6ICJPUkcjLi4uIn0=\"}"; +// FIXTURE: OpenAPI example for GET /v1/models (first entries) +const char* kModels = + "{\"object\":\"list\",\"data\":[{\"id\":\"anthropic/claude-opus-5\",\"object\":\"model\",\"created\":0,\"owned_by\":\"anthropic\"},{\"id\":\"openai/gpt-6-astra\",\"object\":\"model\",\"created\":0,\"owned_by\":\"openai\"}]}"; +// SCHEMA: gateway Model with pricing +const char* kOrchModels = + "{\"object\":\"list\",\"data\":[{\"id\":\"perplexity/kimi-k3\",\"object\":\"model\",\"created\":1,\"owned_by\":\"perplexity\",\"pricing\":{\"input\":0.6,\"output\":2.5,\"cache_read\":0.15,\"unit\":\"usd_per_1m_tokens\"}}]}"; +} // namespace + +TEST(perplexity_decisions, documented_fixture_parses_and_request_is_built) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/decisions", reply(kDecisions)); + Decisions api(rig.client()); + DecisionsParams p; + p.model = "pplx-decider-latest"; + p.state = Json("Invoice 77 for account 4471"); + p.questions["on_policy"] = DecisionQuestions::noul("Is the payment allowed by the policy?"); + p.questions["reversible"] = DecisionQuestions::noul("", "undoable", "permanent"); + DecisionsResult r = api.answer(p); + ASSERT_EQ(r.model, "pplx-decider-latest"); + ASSERT_EQ(r.answers.size(), 3u); + ASSERT_EQ(r.answers["reversible"].type, "noul"); + ASSERT_TRUE(r.answers["reversible"].noul > 0.015 && r.answers["reversible"].noul < 0.016); + ASSERT_EQ(r.input_tokens, 1113L); + auto s = rig.last(); + ASSERT_TRUE(has(s.body, "\"questions\":{\"on_policy\":{\"instructions\":\"Is the payment allowed by the policy?\",\"type\":\"noul\"}")); + ASSERT_TRUE(has(s.body, "\"criteria\":{\"false\":\"permanent\",\"true\":\"undoable\"}")); +} + +TEST(perplexity_decisions, choice_and_score_answers_and_limits) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/decisions", reply(kDecisionsMixed)); + Decisions api(rig.client()); + DecisionsParams p; + p.state = Json::parse("{\"title\":\"crash\"}"); + p.questions["kind"] = DecisionQuestions::choice({{"bug", "something broke"}, {"feature", ""}}); + p.questions["urgency"] = DecisionQuestions::score({"low", "high"}, "How urgent?"); + DecisionsResult r = api.answer(p); + ASSERT_EQ(r.answers["kind"].choice, "bug"); + ASSERT_EQ(r.answers["kind"].probabilities["feature"], 0.1); + ASSERT_EQ(r.answers["urgency"].legend["1"], "high"); + ASSERT_EQ(r.answers["urgency"].score, 1.4); + ASSERT_TRUE(has(rig.last().body, "\"feature\":null")); + DecisionsParams bad; + ASSERT_THROW(api.answer(bad), ApiError); + bad.state = Json("x"); + ASSERT_THROW(api.answer(bad), ApiError); // no questions + for (int i = 0; i < 129; ++i) bad.questions["q" + std::to_string(i)] = DecisionQuestions::noul("?"); + ASSERT_THROW(api.answer(bad), ApiError); + ASSERT_THROW(DecisionQuestions::noul(""), ApiError); + ASSERT_THROW(DecisionQuestions::score(std::vector(11, "l")), ApiError); + ASSERT_THROW(DecisionQuestions::choice({}), ApiError); + ASSERT_EQ(rig.transport->send_count(), 1u); +} + +TEST(perplexity_batches, documented_batch_fixture_and_requests) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/files", reply(kBatchFile)); + rig.transport->expect_response(Method::kPost, "/v1/batches", reply(kBatch)); + BatchFiles files(rig.client()); + BatchInput in; + in.jsonl = "{\"custom_id\":\"1\",\"method\":\"POST\",\"url\":\"/v1/responses\",\"body\":{\"model\":\"a/b\",\"input\":\"hi\"}}\n\n{\"custom_id\":\"2\"}\n"; + BatchFileInfo f = files.upload(in); + ASSERT_EQ(f.id, "file_1"); + ASSERT_EQ(f.purpose, "batch"); + auto up = rig.last(); + ASSERT_TRUE(has(up.headers.get_or("Content-Type", ""), "multipart/form-data")); + ASSERT_TRUE(has(up.body, "name=\"purpose\"")); + ASSERT_TRUE(has(up.body, "filename=\"batch.jsonl\"")); + Batches batches(rig.client()); + BatchInfo b = batches.create("file_01M4RFGV5DQFAZY29N9C2624A6", {{"job", "nightly-eval"}}, "key-1"); + ASSERT_EQ(b.id, "batch_01M4RFGZENVEQTVVJ2222M2JD6"); + ASSERT_EQ(b.status, "validating"); + ASSERT_FALSE(b.finished()); + ASSERT_EQ(b.total, 3L); + ASSERT_EQ(b.metadata["job"], "nightly-eval"); + ASSERT_EQ(b.output_file_id, ""); + auto s = rig.last(); + ASSERT_TRUE(has(s.body, "\"endpoint\":\"/v1/responses\"")); + ASSERT_TRUE(has(s.body, "\"completion_window\":\"24h\"")); + ASSERT_EQ(s.headers.get_or("Idempotency-Key", ""), "key-1"); +} + +TEST(perplexity_batches, list_get_cancel_files_and_limits) { + Rig rig; + rig.transport->expect_response(Method::kGet, "/v1/batches", + reply(std::string("{\"object\":\"list\",\"data\":[") + kBatch + "],\"first_id\":\"a\",\"last_id\":\"b\",\"has_more\":true}")); + rig.transport->expect_response(Method::kPost, "/v1/batches/batch_1/cancel", + reply("{\"id\":\"batch_1\",\"object\":\"batch\",\"status\":\"cancelling\",\"input_file_id\":\"f\"}")); + rig.transport->expect_response(Method::kGet, "/v1/files", + reply(std::string("{\"object\":\"list\",\"data\":[") + kBatchFile + "],\"has_more\":false}")); + rig.transport->expect_response(Method::kDelete, "/v1/files/file_1", reply("{\"id\":\"file_1\",\"object\":\"file\",\"deleted\":true}")); + rig.transport->expect_response(Method::kGet, "/v1/files/file_2/content", reply("{\"line\":1}\n", 200, "application/octet-stream")); + Batches batches(rig.client()); + BatchList l = batches.list(10, "batch_0"); + ASSERT_EQ(l.batches.size(), 1u); + ASSERT_TRUE(l.has_more); + ASSERT_TRUE(has(rig.last().target, "limit=10")); + ASSERT_TRUE(has(rig.last().target, "after=batch_0")); + ASSERT_EQ(batches.cancel("batch_1").status, "cancelling"); + BatchFiles files(rig.client()); + BatchFileList fl = files.list(5, "", "asc", "batch_output"); + ASSERT_EQ(fl.files.size(), 1u); + ASSERT_TRUE(has(rig.last().target, "order=asc")); + ASSERT_TRUE(has(rig.last().target, "purpose=batch_output")); + ASSERT_TRUE(files.remove("file_1").deleted); + ASSERT_EQ(files.content("file_2"), "{\"line\":1}\n"); + size_t before = rig.transport->send_count(); + ASSERT_THROW(batches.list(101), ApiError); + ASSERT_THROW(batches.get("a/b"), ApiError); + ASSERT_THROW(files.list(0, "", "sideways"), ApiError); + ASSERT_THROW(files.list(0, "", "", "other"), ApiError); + std::map big; + for (int i = 0; i < 17; ++i) big["k" + std::to_string(i)] = "v"; + ASSERT_THROW(batches.create("file_1", big), ApiError); + ASSERT_THROW(batches.create("file_1", {}, std::string(201, 'k')), ApiError); + BatchInput bad; + ASSERT_THROW(files.upload(bad), ApiError); + bad.jsonl = "not json\n"; + ASSERT_THROW(files.upload(bad), ApiError); + bad.jsonl = "[1]\n"; + ASSERT_THROW(files.upload(bad), ApiError); + ASSERT_EQ(rig.transport->send_count(), before); +} + +TEST(perplexity_skills, create_get_update_remove_and_revision_guard) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/skills", reply(kSkill, 201)); + rig.transport->expect_response(Method::kGet, "/v1/skills/skill_abc", reply(kSkill)); + rig.transport->expect_response(Method::kPut, "/v1/skills/skill_abc", reply(kSkill)); + rig.transport->expect_response(Method::kDelete, "/v1/skills/skill_abc", reply("", 204)); + rig.transport->expect_response(Method::kGet, "/v1/skills", + reply(std::string("{\"skills\":[{\"skill_id\":\"skill_abc\",\"name\":\"n\",\"revision\":\"r\"}],\"next_page_token\":\"nxt\"}"))); + rig.transport->expect_response(Method::kGet, "/v1/skills/skill_abc/revisions", + reply("{\"revisions\":[{\"revision\":\"r2\",\"name\":\"n\",\"created_at\":\"t\"}]}")); + rig.transport->expect_response(Method::kGet, "/v1/skills/skill_abc/download", + reply("{\"revision\":\"r2\",\"name\":\"n\",\"download_url\":\"https://files.example/skill.zip\"}")); + Skills skills(rig.client()); + SkillBundle bundle; + bundle.data = kZip; + SkillInfo created = skills.create(bundle); + ASSERT_EQ(created.skill_id, "skill_abc"); + ASSERT_EQ(created.latest_revision, "r2"); + ASSERT_TRUE(has(rig.last().body, "filename=\"skill.zip\"")); + ASSERT_EQ(skills.get("skill_abc", "r1").name, "pdf-notes"); + ASSERT_TRUE(has(rig.last().target, "revision=r1")); + SkillInfo upd = skills.update("skill_abc", "r2", bundle); + ASSERT_EQ(upd.skill_id, "skill_abc"); + ASSERT_EQ(rig.last().method, "PUT"); + ASSERT_TRUE(has(rig.last().target, "expected_revision=r2")); + ASSERT_TRUE(has(rig.last().headers.get_or("Content-Type", ""), "multipart/form-data")); + skills.remove("skill_abc", "r2"); + ASSERT_EQ(rig.last().method, "DELETE"); + ASSERT_TRUE(has(rig.last().target, "expected_revision=r2")); + SkillList l = skills.list(20); + ASSERT_EQ(l.skills.size(), 1u); + ASSERT_EQ(l.next_page_token, "nxt"); + ASSERT_EQ(skills.revisions("skill_abc").revisions[0].revision, "r2"); + ASSERT_EQ(skills.download("skill_abc").download_url, "https://files.example/skill.zip"); + size_t before = rig.transport->send_count(); + ASSERT_THROW(skills.remove("skill_abc", ""), ApiError); // revision is required + ASSERT_THROW(skills.update("skill_abc", "bad rev", bundle), ApiError); + ASSERT_THROW(skills.list(201), ApiError); + SkillBundle notzip; + notzip.data = "not a zip"; + ASSERT_THROW(skills.create(notzip), ApiError); + ASSERT_THROW(skills.get("../x"), ApiError); + ASSERT_EQ(rig.transport->send_count(), before); +} + +TEST(perplexity_account, models_usage_and_auth_tokens) { + Rig rig; + rig.transport->expect_response(Method::kGet, "/v1/models", reply(kModels)); + rig.transport->expect_response(Method::kGet, "/v1/analytics/computer/usage", reply(kUsageV1)); + rig.transport->expect_response(Method::kGet, "/v2/analytics/computer/usage", reply(kUsageV2)); + rig.transport->expect_response(Method::kPost, "/generate_auth_token", + reply("{\"auth_token\":\"pplx-NEW\",\"created_at_epoch_seconds\":1735689600,\"token_name\":\"ci\"}")); + rig.transport->expect_response(Method::kPost, "/revoke_auth_token", reply("{}")); + Account acct(rig.client()); + ModelList m = acct.models(); + ASSERT_EQ(m.models.size(), 2u); + ASSERT_EQ(m.find("openai/gpt-6-astra")->provider(), "openai"); + UsageQuery q; + q.dataset = "credit_usage"; + q.start_time = 1746057600; + q.limit = 7; + UsageReport u = acct.usage(q); + ASSERT_EQ(u.categories.size(), 2u); + ASSERT_EQ(u.buckets.size(), 1u); + ASSERT_EQ(u.buckets[0].count, 350L); + ASSERT_FALSE(u.has_more); + ASSERT_TRUE(has(rig.last().target, "dataset=credit_usage")); + ASSERT_TRUE(has(rig.last().target, "start_time=1746057600")); + UsageQuery q2; + q2.dataset = "query_volume"; + q2.group_by = "user_email"; + q2.start_time = 1; + UsageReport v2 = acct.usage_per_member(q2); + ASSERT_EQ(v2.buckets.size(), 2u); + ASSERT_EQ(v2.buckets[0].user_email, "alice@example.com"); + ASSERT_TRUE(v2.has_more); + ASSERT_EQ(v2.next_page, "eyJwayI6ICJPUkcjLi4uIn0="); + AuthToken t = acct.generate_token("ci"); + ASSERT_EQ(t.auth_token, "pplx-NEW"); + ASSERT_EQ(t.token_name, "ci"); + acct.revoke_token("pplx-NEW"); + ASSERT_TRUE(has(rig.last().body, "\"auth_token\":\"pplx-NEW\"")); +} + +TEST(perplexity_account, usage_query_rules) { + Rig rig; + Account acct(rig.client()); + UsageQuery q; + ASSERT_THROW(acct.usage(q), ApiError); // no dataset + q.dataset = "query_volume"; + q.bucket_width = "1h"; + ASSERT_THROW(acct.usage(q), ApiError); // daily-only dataset + q.bucket_width = "1d"; + q.user_email = "a@example.com"; + ASSERT_THROW(acct.usage(q), ApiError); + q = UsageQuery(); + q.dataset = "credit_usage"; + q.limit = 32; + ASSERT_THROW(acct.usage(q), ApiError); // 1d: max 31 + q.bucket_width = "1h"; + q.limit = 168; + q.query_v1(); // 1h: 168 is the maximum + q.end_time = -5; + q.start_time = 10; + ASSERT_THROW(acct.usage(q), ApiError); + UsageQuery v2; + v2.dataset = "skills"; + v2.group_by = "user_email"; + ASSERT_THROW(acct.usage_per_member(v2), ApiError); // v2 knows two datasets + v2.dataset = "credit_usage"; + v2.group_by = ""; + ASSERT_THROW(acct.usage_per_member(v2), ApiError); // group_by required + ASSERT_THROW(acct.revoke_token(""), ApiError); + ASSERT_EQ(rig.transport->send_count(), 0u); +} + +TEST(perplexity_orchestrator, chat_messages_responses_and_models) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/orchestrator/v1/chat/completions", + reply("{\"id\":\"c\",\"choices\":[{\"index\":0,\"message\":{\"role\":\"assistant\",\"content\":\"hi\"},\"finish_reason\":\"stop\"}]}")); + rig.transport->expect_response(Method::kPost, "/orchestrator/v1/messages", + reply("{\"id\":\"m\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"hey\"}]}")); + rig.transport->expect_response(Method::kPost, "/orchestrator/v1/responses", + reply("{\"id\":\"r\",\"output\":[{\"type\":\"message\",\"content\":[{\"type\":\"output_text\",\"text\":\"yo\"}]}]}")); + rig.transport->expect_response(Method::kGet, "/orchestrator/v1/models", reply(kOrchModels)); + rig.transport->expect_response(Method::kGet, "/orchestrator/v1/models/perplexity/kimi-k3", + reply("{\"id\":\"perplexity/kimi-k3\",\"object\":\"model\",\"created\":1,\"owned_by\":\"perplexity\",\"pricing\":{\"input\":0.6,\"output\":2.5,\"unit\":\"usd_per_1m_tokens\"}}")); + Orchestrator o(rig.client()); + ASSERT_EQ(Orchestrator::text_of(Call::kOrchChat, o.chat(Orchestrator::chat_request("perplexity/kimi-k3", "hi"))), "hi"); + ASSERT_EQ(Orchestrator::text_of(Call::kOrchMessages, o.messages(Orchestrator::messages_request("perplexity/kimi-k3", "hi", 64))), "hey"); + ASSERT_EQ(Orchestrator::text_of(Call::kOrchResponses, o.responses(Orchestrator::responses_request("perplexity/kimi-k3", "hi"))), "yo"); + ModelList ml = o.models(); + ASSERT_EQ(ml.models.size(), 1u); + ASSERT_TRUE(ml.models[0].pricing.present); + ASSERT_EQ(ml.models[0].pricing.output, 2.5); + ASSERT_EQ(o.model("perplexity/kimi-k3").pricing.input, 0.6); +} + +TEST(perplexity_orchestrator, request_rules_are_enforced_before_traffic) { + Rig rig; + Orchestrator o(rig.client()); + Json b = Orchestrator::chat_request("kimi-k3", "hi"); // no creator prefix + ASSERT_THROW(o.chat(b), ApiError); + b = Orchestrator::chat_request("perplexity/kimi-k3", "hi"); + b.set("surprise", Json(1)); + ASSERT_THROW(o.chat(b), ApiError); + Json m = Orchestrator::messages_request("perplexity/kimi-k3", "hi", 10); + m.set("mcp_servers", Json::array()); + ASSERT_THROW(o.messages(m), ApiError); // rejected by Perplexity + Json nomax = Orchestrator::chat_request("perplexity/kimi-k3", "hi"); + ASSERT_THROW(o.messages(nomax), ApiError); // max_tokens required by the Messages schema + Json r = Orchestrator::responses_request("perplexity/kimi-k3", "hi"); + r.set("stream", Json(true)); + ASSERT_THROW(o.responses(r), ApiError); // use stream() + Json notstream = Orchestrator::responses_request("perplexity/kimi-k3", "hi"); + ASSERT_THROW(o.stream(Call::kOrchResponses, notstream, nullptr), ApiError); + ASSERT_THROW(o.model("a/b/c"), ApiError); + ASSERT_THROW(o.model("../x"), ApiError); + ASSERT_THROW(o.chat(Json::array()), ApiError); + ASSERT_EQ(rig.transport->send_count(), 0u); +} + +TEST(perplexity_orchestrator, stream_passes_events_through) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/orchestrator/v1/chat/completions", + sse("data: {\"choices\":[{\"index\":0,\"delta\":{\"content\":\"a\"}}]}\n\ndata: {\"choices\":[{\"index\":0,\"delta\":{\"content\":\"b\"}}]}\n\ndata: [DONE]\n\n")); + Orchestrator o(rig.client()); + Json b = Orchestrator::chat_request("perplexity/kimi-k3", "hi"); + b.set("stream", Json(true)); + std::string text; + o.stream(Call::kOrchChat, b, [&](const molo::llm::SseEvent& e) { + text += J::str(*e.data.find("choices")->as_array()[0].find("delta"), "content"); + return true; + }); + ASSERT_EQ(text, "ab"); +} diff --git a/tests/src/vendors/perplexity/test_search_embed.cpp b/tests/src/vendors/perplexity/test_search_embed.cpp new file mode 100644 index 0000000..14aab78 --- /dev/null +++ b/tests/src/vendors/perplexity/test_search_embed.cpp @@ -0,0 +1,196 @@ +// Search API and Embeddings (standard and contextualized). +#include "security/crypto/Base64.h" +#include "support.h" +#include "vendors/perplexity/embeddings.h" +#include "vendors/perplexity/search.h" + +using namespace molo::perplexity; +using namespace perplexity_test; +using molo::llm::ApiError; + +namespace { +// FIXTURE: docs "Search API Overview" example response (results with title, url, snippet, date, last_updated), +// completed with the schema's required id. +const char* kSearch = + "{\"results\":[{\"title\":\"Example Article Title\",\"url\":\"https://example.com/article\"," + "\"snippet\":\"A short excerpt from the article relevant to the query...\",\"date\":\"2025-01-23\",\"last_updated\":\"2025-09-25\"}," + "{\"title\":\"Another Relevant Source\",\"url\":\"https://example.org/source\"," + "\"snippet\":\"Another excerpt showing the structured result format.\",\"date\":\"2024-11-15\",\"last_updated\":\"2025-08-12\"}]," + "\"id\":\"search-1\",\"server_time\":\"2026-10-25T10:00:00Z\"}"; + +std::string b64(const std::string& raw) { return molo::security::crypto::Base64::encode(raw); } +} // namespace + +TEST(perplexity_search, request_body_and_parsing) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/search", reply(kSearch)); + Search search(rig.client()); + SearchParams p = SearchParams::of("quantum computing", 5); + p.country = "US"; + p.search_domain_filter = {"arxiv.org"}; + p.search_language_filter = {"en"}; + p.search_recency_filter = "week"; + p.search_after_date_filter = "01/02/2025"; + p.max_tokens_per_page = 2048; + SearchResponse r = search.run(p); + ASSERT_EQ(r.id, "search-1"); + ASSERT_EQ(r.results.size(), 2u); + ASSERT_EQ(r.results[0].title, "Example Article Title"); + ASSERT_EQ(r.results[0].last_updated, "2025-09-25"); + ASSERT_EQ(r.results[1].url, "https://example.org/source"); + auto s = rig.last(); + ASSERT_TRUE(has(s.body, "\"query\":\"quantum computing\"")); + ASSERT_TRUE(has(s.body, "\"max_results\":5")); + ASSERT_TRUE(has(s.body, "\"search_domain_filter\":[\"arxiv.org\"]")); + ASSERT_TRUE(has(s.body, "\"search_after_date_filter\":\"01/02/2025\"")); + ASSERT_TRUE(has(s.body, "\"max_tokens_per_page\":2048")); + ASSERT_EQ(s.headers.get_or("Authorization", ""), std::string("Bearer ") + kKey); +} + +TEST(perplexity_search, multi_query_is_an_array_capped_at_five) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/search", reply(kSearch)); + Search search(rig.client()); + SearchParams p; + p.query = {"a", "b", "c"}; + search.run(p); + ASSERT_TRUE(has(rig.last().body, "\"query\":[\"a\",\"b\",\"c\"]")); + p.query = {"1", "2", "3", "4", "5", "6"}; + ASSERT_THROW(search.run(p), ApiError); +} + +TEST(perplexity_search, limits_are_enforced_before_any_traffic) { + Rig rig; + Search search(rig.client()); + SearchParams p; + ASSERT_THROW(search.run(p), ApiError); // no query + p = SearchParams::of(" "); + ASSERT_THROW(search.run(p), ApiError); // blank + p = SearchParams::of("x", 21); + ASSERT_THROW(search.run(p), ApiError); // >20 needs people + p.search_type = "people"; + p.max_results = 50; + p.to_json(); // 50 is fine for people + p.max_results = 51; + ASSERT_THROW(p.to_json(), ApiError); + p = SearchParams::of("x"); + p.search_type = "deep"; + ASSERT_THROW(search.run(p), ApiError); + p = SearchParams::of("x"); + p.search_domain_filter.assign(21, "example.com"); + ASSERT_THROW(search.run(p), ApiError); + p = SearchParams::of("x"); + p.search_language_filter = {"eng"}; + ASSERT_THROW(search.run(p), ApiError); + p = SearchParams::of("x"); + p.max_tokens = 0; + ASSERT_THROW(search.run(p), ApiError); + p = SearchParams::of("x"); + p.country = "USA"; + ASSERT_THROW(search.run(p), ApiError); + ASSERT_EQ(rig.transport->send_count(), 0u); +} + +TEST(perplexity_search, rate_limit_error_keeps_its_type) { + Rig rig; + // Shape documented on the Rate Limits page. + rig.transport->expect_response( + Method::kPost, "/search", + reply("{\"error\":{\"message\":\"Request rate limit exceeded, please try again later.\",\"type\":\"request_rate_limit_exceeded\",\"code\":429}}", 429)); + try { + Search(rig.client()).run(SearchParams::of("x")); + FAIL("expected"); + } catch (const ApiError& e) { + ASSERT_EQ(e.http_status(), 429); + ASSERT_EQ(e.type(), "request_rate_limit_exceeded"); + } +} + +TEST(perplexity_embeddings, standard_request_and_int8_decoding) { + Rig rig; + // SCHEMA: EmbeddingsResponse; the vector is 4 signed int8 values. + std::string vec = b64(std::string("\x01\xFF\x7F\x80", 4)); + rig.transport->expect_response( + Method::kPost, "/v1/embeddings", + reply("{\"object\":\"list\",\"data\":[{\"object\":\"embedding\",\"index\":0,\"embedding\":\"" + vec + + "\"}],\"model\":\"pplx-embed-v1-0.6b\",\"usage\":{\"prompt_tokens\":3,\"total_tokens\":3,\"cost\":{\"total_cost\":0.00001}}}")); + Embeddings api(rig.client()); + EmbedParams p; + p.input = {"hello"}; + p.dimensions = 128; + EmbedResult r = api.create(p); + ASSERT_EQ(r.vectors.size(), 1u); + ASSERT_TRUE(r.vectors[0].decodable()); + std::vector v = r.vectors[0].int8(); + ASSERT_EQ(v.size(), 4u); + ASSERT_EQ(static_cast(v[0]), 1); + ASSERT_EQ(static_cast(v[1]), -1); + ASSERT_EQ(static_cast(v[2]), 127); + ASSERT_EQ(static_cast(v[3]), -128); + ASSERT_EQ(r.usage.prompt_tokens, 3L); + ASSERT_EQ(r.usage.cost_total, 0.00001); + auto s = rig.last(); + ASSERT_TRUE(has(s.body, "\"input\":\"hello\"")); + ASSERT_TRUE(has(s.body, "\"dimensions\":128")); + ASSERT_TRUE(has(s.body, "\"model\":\"pplx-embed-v1-0.6b\"")); + ASSERT_EQ(cosine(v, v) > 0.999999, true); + ASSERT_EQ(cosine(v, std::vector{0, 0, 0, 0}), 0.0); +} + +TEST(perplexity_embeddings, contextualized_groups_chunks_per_document) { + Rig rig; + std::string a = b64(std::string("\x01\x02", 2)), b = b64(std::string("\x03\x04", 2)); + rig.transport->expect_response( + Method::kPost, "/v1/contextualizedembeddings", + reply("{\"object\":\"list\",\"model\":\"pplx-embed-context-v1-4b\",\"data\":[{\"object\":\"list\",\"index\":0,\"data\":[" + "{\"object\":\"embedding\",\"index\":0,\"embedding\":\"" + a + "\"},{\"object\":\"embedding\",\"index\":1,\"embedding\":\"" + b + + "\"}]}],\"usage\":{\"prompt_tokens\":9,\"total_tokens\":9,\"cost\":{}}}")); + Embeddings api(rig.client()); + ContextEmbedParams p; + p.model = EmbedModels::kContext4; + p.input = {{"chunk one", "chunk two"}}; + p.dimensions = 2560; + p.encoding_format = "base64_int8"; + ContextEmbedResult r = api.create_contextualized(p); + ASSERT_EQ(r.documents.size(), 1u); + ASSERT_EQ(r.documents[0].size(), 2u); + ASSERT_EQ(r.documents[0][1].int8()[1], 4); + ASSERT_TRUE(has(rig.last().body, "\"input\":[[\"chunk one\",\"chunk two\"]]")); + ASSERT_TRUE(has(rig.last().body, "\"encoding_format\":\"base64_int8\"")); +} + +TEST(perplexity_embeddings, limits_and_model_families_are_enforced) { + Rig rig; + Embeddings api(rig.client()); + EmbedParams p; + ASSERT_THROW(api.create(p), ApiError); // empty input + p.input.assign(513, "x"); + ASSERT_THROW(api.create(p), ApiError); + p.input = {"x"}; + p.dimensions = 127; + ASSERT_THROW(api.create(p), ApiError); + p.dimensions = 1025; // above the 0.6b ceiling + ASSERT_THROW(api.create(p), ApiError); + p.model = EmbedModels::kStandard4; + p.dimensions = 2560; + p.to_json(); // allowed for 4b + p.dimensions = 2561; + ASSERT_THROW(p.to_json(), ApiError); + p.dimensions = 0; + p.model = "pplx-embed-context-v1-0.6b"; // context model on the standard call + ASSERT_THROW(api.create(p), ApiError); + p.model = EmbedModels::kStandard06; + p.encoding_format = "float"; + ASSERT_THROW(api.create(p), ApiError); + ContextEmbedParams c; + c.input = {{}}; + ASSERT_THROW(api.create_contextualized(c), ApiError); + ASSERT_EQ(rig.transport->send_count(), 0u); +} + +TEST(perplexity_embeddings, undecodable_vector_is_reported_not_guessed) { + Vector v; + v.base64 = "!!not base64!!"; + ASSERT_FALSE(v.decodable()); + ASSERT_EQ(v.int8().size(), 0u); +} diff --git a/tests/src/vendors/perplexity/test_sonar.cpp b/tests/src/vendors/perplexity/test_sonar.cpp new file mode 100644 index 0000000..66cb6f3 --- /dev/null +++ b/tests/src/vendors/perplexity/test_sonar.cpp @@ -0,0 +1,247 @@ +// Sonar chat completions and async chat completions over the real ApiClient +// with a recording transport. Replies are SCHEMA fixtures (shape from the +// OpenAPI document, values invented); assertions are on what WE send and on +// how WE parse. +#include "support.h" +#include "vendors/perplexity/sonar.h" + +using namespace molo::perplexity; +using namespace perplexity_test; +using molo::llm::ApiError; + +namespace { +// SCHEMA: CompletionResponse with citations, search_results, images, related_questions, usage.cost +const char* kSonarReply = + "{\"id\":\"c1\",\"model\":\"sonar-pro\",\"created\":1760000000,\"object\":\"chat.completion\"," + "\"choices\":[{\"index\":0,\"finish_reason\":\"stop\",\"message\":{\"role\":\"assistant\",\"content\":\"Paris is the capital [1][2].\"}," + "\"delta\":{\"role\":\"assistant\",\"content\":\"\"}}]," + "\"citations\":[\"https://example.com/a\",\"https://example.org/b\"]," + "\"search_results\":[{\"title\":\"A\",\"url\":\"https://example.com/a\",\"date\":\"2025-01-02\",\"last_updated\":\"2025-02-03\",\"snippet\":\"s\",\"source\":\"web\"}]," + "\"images\":[{\"image_url\":\"https://img/1.png\",\"origin_url\":\"https://example.com/a\",\"height\":10,\"width\":20,\"title\":\"t\"}]," + "\"related_questions\":[\"What else?\"]," + "\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":7,\"total_tokens\":17,\"search_context_size\":\"low\",\"citation_tokens\":3," + "\"num_search_queries\":1,\"reasoning_tokens\":2,\"cost\":{\"input_tokens_cost\":0.001,\"output_tokens_cost\":0.002,\"request_cost\":0.005,\"total_cost\":0.008}}}"; + +// SCHEMA: stream chunks are CompletionResponse documents whose choices carry delta +const char* kStream = + "data: {\"id\":\"s1\",\"model\":\"sonar\",\"created\":1,\"object\":\"chat.completion\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"Hel\"},\"message\":{\"role\":\"assistant\",\"content\":\"Hel\"},\"finish_reason\":null}]}\n\n" + ": keep-alive\n\n" + "data: {\"id\":\"s1\",\"model\":\"sonar\",\"created\":1,\"choices\":[{\"index\":0,\"delta\":{\"content\":\"lo\"},\"message\":{\"role\":\"assistant\",\"content\":\"Hello\"},\"finish_reason\":null}],\"citations\":[\"https://example.com/a\"]}\n\n" + "data: {\"id\":\"s1\",\"model\":\"sonar\",\"created\":1,\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\"},\"message\":{\"role\":\"assistant\",\"content\":\"Hello\"},\"finish_reason\":\"stop\"}]," + "\"usage\":{\"prompt_tokens\":4,\"completion_tokens\":2,\"total_tokens\":6,\"cost\":{\"input_tokens_cost\":0,\"output_tokens_cost\":0,\"total_cost\":0.001}},\"search_results\":[{\"title\":\"A\",\"url\":\"https://example.com/a\"}]}\n\n" + "data: [DONE]\n\n"; + +// SCHEMA: AsyncApiChatCompletionsResponse +const char* kAsyncCreated = + "{\"id\":\"req_1\",\"model\":\"sonar-deep-research\",\"created_at\":1760000000,\"status\":\"CREATED\"}"; +const char* kAsyncRunning = + "{\"id\":\"req_1\",\"model\":\"sonar-deep-research\",\"created_at\":1760000000,\"started_at\":1760000001,\"status\":\"IN_PROGRESS\"}"; +std::string async_done() { + return std::string("{\"id\":\"req_1\",\"model\":\"sonar-deep-research\",\"created_at\":1760000000,\"started_at\":1760000001,\"completed_at\":1760000100," + "\"status\":\"COMPLETED\",\"response\":") + kSonarReply + "}"; +} +// SCHEMA: ListAsyncApiChatCompletionsResponse +const char* kAsyncList = + "{\"next_token\":\"tok\",\"requests\":[{\"id\":\"req_1\",\"created_at\":1,\"model\":\"sonar-deep-research\",\"status\":\"COMPLETED\",\"completed_at\":5}," + "{\"id\":\"req_2\",\"created_at\":2,\"model\":\"sonar-deep-research\",\"status\":\"FAILED\",\"failed_at\":6}]}"; +} // namespace + +TEST(perplexity_sonar, create_sends_bearer_json_and_parses_every_field) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/sonar", reply(kSonarReply)); + Sonar sonar(rig.client()); + SonarParams p = SonarParams::prompt("Capital of France?", "sonar-pro"); + p.add(Messages::system("Be brief.")); + p.search_mode = "academic"; + p.search_domain_filter = {"nature.com", "-pinterest.com"}; + p.search_recency_filter = "month"; + p.web_search_options.search_context_size = "high"; + p.web_search_options.user_location.country = "FR"; + p.return_images = true; + p.return_related_questions = true; + p.reasoning_effort = "low"; + SonarResult r = sonar.create(p); + ASSERT_EQ(r.text(), "Paris is the capital [1][2]."); + ASSERT_EQ(r.first().finish_reason, "stop"); + ASSERT_EQ(r.model, "sonar-pro"); + ASSERT_EQ(r.created, 1760000000L); + ASSERT_EQ(r.citations.size(), 2u); + ASSERT_EQ(r.citation_url(2), "https://example.org/b"); + ASSERT_EQ(r.citation_url(3), ""); + ASSERT_EQ(r.search_results.size(), 1u); + ASSERT_EQ(r.search_results[0].last_updated, "2025-02-03"); + ASSERT_EQ(r.images.size(), 1u); + ASSERT_EQ(r.images[0].width, 20L); + ASSERT_EQ(r.related_questions[0], "What else?"); + ASSERT_EQ(r.usage.prompt_tokens, 10); + ASSERT_EQ(r.usage.reasoning_tokens, 2); + ASSERT_EQ(r.usage.num_search_queries, 1); + ASSERT_EQ(r.usage.cost.total, 0.008); + ASSERT_EQ(r.usage.cost.request, 0.005); + auto s = rig.last(); + ASSERT_EQ(s.method, "POST"); + ASSERT_EQ(s.headers.get_or("Authorization", ""), std::string("Bearer ") + kKey); + ASSERT_TRUE(has(s.body, "\"model\":\"sonar-pro\"")); + ASSERT_TRUE(has(s.body, "\"search_mode\":\"academic\"")); + ASSERT_TRUE(has(s.body, "\"search_domain_filter\":[\"nature.com\",\"-pinterest.com\"]")); + ASSERT_TRUE(has(s.body, "\"web_search_options\":{\"search_context_size\":\"high\",\"user_location\":{\"country\":\"FR\"}}")); + ASSERT_TRUE(has(s.body, "\"reasoning_effort\":\"low\"")); + ASSERT_FALSE(has(s.body, "\"stream\"")); + ASSERT_EQ(s.target.find(kKey), std::string::npos); +} + +TEST(perplexity_sonar, structured_output_and_multimodal_parts_are_in_the_body) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/sonar", reply(kSonarReply)); + Sonar sonar(rig.client()); + SonarParams p; + p.add(Messages::with_parts("user", {Messages::text_part("describe"), Messages::image_part("https://example.com/x.png"), + Messages::pdf_part("https://example.com/x.pdf"), Messages::video_part("https://example.com/x.mp4", 30)})); + p.response_format = StructuredOutput::json_schema(Json::parse("{\"type\":\"object\",\"properties\":{\"a\":{\"type\":\"string\"}}}"), "answer"); + p.stop = {"END"}; + sonar.create(p); + auto s = rig.last(); + ASSERT_TRUE(has(s.body, "\"image_url\":{\"url\":\"https://example.com/x.png\"}")); + ASSERT_TRUE(has(s.body, "\"pdf_url\":{\"url\":\"https://example.com/x.pdf\"}")); + ASSERT_TRUE(has(s.body, "\"video_url\":{\"frame_interval\":30,\"url\":\"https://example.com/x.mp4\"}")); + ASSERT_TRUE(has(s.body, "\"response_format\":{\"json_schema\":{\"name\":\"answer\"")); + ASSERT_TRUE(has(s.body, "\"stop\":\"END\"")); +} + +TEST(perplexity_sonar, invalid_input_never_reaches_the_network) { + Rig rig; + Sonar sonar(rig.client()); + SonarParams empty; + ASSERT_THROW(sonar.create(empty), ApiError); + SonarParams p = SonarParams::prompt("x"); + p.temperature = 2.5; + ASSERT_THROW(sonar.create(p), ApiError); + p = SonarParams::prompt("x"); + p.search_after_date_filter = "2025-01-01"; + ASSERT_THROW(sonar.create(p), ApiError); + p = SonarParams::prompt("x"); + p.search_mode = "dark"; + ASSERT_THROW(sonar.stream(p, nullptr), ApiError); + p = SonarParams::prompt("x"); + p.extra = Json::parse("{\"not_a_field\":1}"); + ASSERT_THROW(sonar.create(p), ApiError); + ASSERT_THROW(sonar.get_async("../x"), ApiError); + ASSERT_EQ(rig.transport->send_count(), 0u); +} + +TEST(perplexity_sonar, not_configured_has_no_traffic) { + Rig rig(""); + Sonar sonar(rig.client()); + try { + sonar.create(SonarParams::prompt("hi")); + FAIL("expected"); + } catch (const molo::llm::NotConfiguredError& e) { + ASSERT_EQ(e.http_status(), 503); + ASSERT_TRUE(has(e.message(), "PERPLEXITY_API_KEY")); + } + ASSERT_EQ(rig.transport->send_count(), 0u); + ASSERT_FALSE(rig.platform.configured()); +} + +TEST(perplexity_sonar, stream_folds_chunks_citations_and_usage) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/sonar", sse(kStream)); + Sonar sonar(rig.client()); + std::string text; + int chunks = 0; + SonarResult r = sonar.stream(SonarParams::prompt("Hi"), [&](const SonarDelta& d) { + text += d.content; + ++chunks; + return true; + }); + ASSERT_EQ(text, "Hello"); + ASSERT_EQ(chunks, 3); // the keep-alive comment produces no chunk + ASSERT_EQ(r.text(), "Hello"); + ASSERT_EQ(r.first().finish_reason, "stop"); + ASSERT_EQ(r.id, "s1"); + ASSERT_EQ(r.citations.size(), 1u); + ASSERT_EQ(r.search_results.size(), 1u); + ASSERT_EQ(r.usage.total_tokens, 6); + ASSERT_EQ(r.usage.cost.total, 0.001); + auto s = rig.last(); + ASSERT_TRUE(has(s.body, "\"stream\":true")); + ASSERT_EQ(s.headers.get_or("Accept", ""), "text/event-stream"); +} + +TEST(perplexity_sonar, stream_stop_early_and_truncation_is_loud) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/sonar", sse(kStream)); + Sonar sonar(rig.client()); + SonarResult r = sonar.stream(SonarParams::prompt("Hi"), [&](const SonarDelta& d) { return d.content != "Hel"; }); + ASSERT_EQ(r.text(), "Hel"); // stopped by the sink: no truncation error + Rig cut; + cut.transport->expect_response(Method::kPost, "/v1/sonar", + sse("data: {\"id\":\"x\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"par\"},\"finish_reason\":null}]}\n\n")); + try { + Sonar(cut.client()).stream(SonarParams::prompt("Hi"), nullptr); + FAIL("expected STREAM_TRUNCATED"); + } catch (const ApiError& e) { + ASSERT_EQ(e.type(), "STREAM_TRUNCATED"); + } +} + +TEST(perplexity_sonar, error_envelope_keeps_vendor_type_and_status) { + Rig rig; + // Shape documented on the Rate Limits page. + rig.transport->expect_response(Method::kPost, "/v1/sonar", + reply("{\"error\":{\"message\":\"Invalid API key provided. Ensure your API key is correct and active.\",\"type\":\"invalid_api_key\",\"code\":401}}", 401)); + try { + Sonar(rig.client()).create(SonarParams::prompt("hi")); + FAIL("expected"); + } catch (const ApiError& e) { + ASSERT_EQ(e.http_status(), 401); + ASSERT_EQ(e.type(), "invalid_api_key"); + ASSERT_EQ(std::string(e.what()).find(kKey), std::string::npos); + } +} + +TEST(perplexity_sonar, async_create_get_list_and_wait) { + Rig rig; + rig.transport->expect_response(Method::kPost, "/v1/async/sonar", reply(kAsyncCreated)); + Sonar sonar(rig.client()); + AsyncJob job = sonar.create_async(SonarParams::prompt("research", "sonar-deep-research"), "idem-1"); + ASSERT_EQ(job.id, "req_1"); + ASSERT_TRUE(job.state() == AsyncStatus::kCreated); + ASSERT_FALSE(job.finished()); + auto s = rig.last(); + ASSERT_TRUE(has(s.body, "\"request\":{")); + ASSERT_TRUE(has(s.body, "\"idempotency_key\":\"idem-1\"")); + + Rig poll; + poll.transport->expect_response(Method::kGet, "/v1/async/sonar/req_1", reply(kAsyncRunning)); + poll.transport->expect_response(Method::kGet, "/v1/async/sonar/req_1", reply(async_done())); + Sonar psonar(poll.client()); + int slept = 0; + AsyncJob done = psonar.wait_async("req_1", 2, 10, [&](int sec) { slept += sec; }); + ASSERT_TRUE(done.state() == AsyncStatus::kCompleted); + ASSERT_TRUE(done.has_response); + ASSERT_EQ(done.response.text(), "Paris is the capital [1][2]."); + ASSERT_EQ(slept, 2); + + Rig list; + list.transport->expect_response(Method::kGet, "/v1/async/sonar", reply(kAsyncList)); + AsyncList l = Sonar(list.client()).list_async(); + ASSERT_EQ(l.requests.size(), 2u); + ASSERT_TRUE(l.requests[1].state() == AsyncStatus::kFailed); + ASSERT_EQ(l.next_token, "tok"); +} + +TEST(perplexity_sonar, wait_async_has_a_floor_and_a_ceiling) { + Rig rig; + Sonar sonar(rig.client()); + ASSERT_THROW(sonar.wait_async("req_1", 0, 10), ApiError); + ASSERT_THROW(sonar.wait_async("req_1", 1, 601), ApiError); + rig.transport->expect(MockExpectation{Method::kGet, "/v1/async/sonar/req_1", {}, "", nullptr, reply(kAsyncRunning), nullptr, 100, 0, ""}); + try { + sonar.wait_async("req_1", 5, 10, [](int) {}); + FAIL("expected WAIT_TIMEOUT"); + } catch (const ApiError& e) { + ASSERT_EQ(e.type(), "WAIT_TIMEOUT"); + ASSERT_EQ(e.http_status(), 504); + } +}