feat(clients): openrouter: whole public API, spec-checked call table, chat model, demo

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-24 07:46:42 +02:00
co-authored by Claude Sonnet 5.5
parent 2e0270c043
commit 9a24bedc7c
54 changed files with 7109 additions and 3 deletions
+369 -3
View File
@@ -1,13 +1,379 @@
#include "../AiDemos.hpp"
#include "../../fw/Router.hpp"
#include "../../fw/Templates.hpp"
#include "llm/error.h"
#include "openrouter/call_plan.h"
#include "openrouter/chat_params.h"
#include "openrouter/chat_service.h"
#include "openrouter/gateway.h"
#include "openrouter/inference_services.h"
#include "openrouter/model_ref.h"
namespace molo::example::app {
// OpenRouter: routing, models, providers, generations, credits, keys, presets, plugins. Stub: the module agent fills this in.
// OpenRouter over the real src/openrouter module. GET routes need no
// credential. Every route that calls OpenRouter is a POST: 422 on bad input
// first, then 503 not_configured without the needed key (OPENROUTER_API_KEY
// for inference and reads, OPENROUTER_MANAGEMENT_KEY for management calls).
// Chat, responses and messages cost money and every non-GET call of the
// generic /ai/openrouter/call route can change an account: all of them are
// dry runs unless the body says "confirm":true. Secrets are never echoed.
namespace {
namespace orr = openrouter;
using Json = clients::body::Json;
constexpr std::size_t kMaxBody = 256 * 1024;
constexpr std::size_t kMaxShownBytes = 200 * 1024;
const char kPage[] = R"ORPAGE({% extends "base.html" %}
{% block content %}
<h1>OpenRouter</h1>
<p class="hint">One API for hundreds of models: routing, fallbacks, plugins, keys and usage.
Paid and account-changing calls are dry runs until you tick confirm.</p>
<p id="or-config" class="hint">Checking credentials...</p>
<section class="or">
<label>Model <input id="or-model" type="text" maxlength="128" value="openrouter/free"></label>
<label>Prompt <textarea id="or-prompt" rows="3">Say hello in one short sentence.</textarea></label>
<label>Provider preferences (JSON, optional) <textarea id="or-provider" rows="2" placeholder='{"sort":"price","allow_fallbacks":true}'></textarea></label>
<label class="or-check"><input id="or-confirm" type="checkbox"> confirm (really send)</label>
<div class="or-actions">
<button id="or-chat" type="button" class="primary">Chat</button>
<button id="or-models" type="button">List models</button>
<button id="or-providers" type="button">Providers</button>
<button id="or-key" type="button">Key info</button>
<button id="or-credits" type="button">Credits</button>
</div>
<h2>Any call</h2>
<label>Call <select id="or-call"></select></label>
<label>Path arguments (JSON) <textarea id="or-args" rows="2">{}</textarea></label>
<label>Query (JSON) <textarea id="or-query" rows="2">{}</textarea></label>
<label>Body (JSON) <textarea id="or-body" rows="4"></textarea></label>
<div class="or-actions"><button id="or-plan" type="button">Plan</button><button id="or-send" type="button">Send</button></div>
<p id="or-error" class="error" role="alert"></p>
<pre id="or-out" class="or-out"></pre>
</section>
<style>
.or label{display:block;margin:.5rem 0}
.or input[type=text],.or textarea,.or select{width:100%;box-sizing:border-box}
.or-actions{display:flex;flex-wrap:wrap;gap:.5rem;margin:.5rem 0}
.or-out{overflow:auto;max-height:24rem;white-space:pre-wrap;word-break:break-word}
</style>
<script src="/embedded/ai_openrouter.js"></script>
{% endblock %}
)ORPAGE";
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;
}
[[noreturn]] void bad(const std::string& why) { throw fw::HttpError(422, "validation_error", why); }
[[noreturn]] void rethrow(const llm::ApiError& e) {
if (e.http_status() == 503 && e.type() == "NOT_CONFIGURED")
throw fw::HttpError(503, "not_configured", e.message());
if (e.http_status() == 400 && e.type() == "INVALID_ARGUMENT")
throw fw::HttpError(422, "validation_error", e.message());
throw fw::HttpError(502, "openrouter_error", e.type() + ": " + e.message());
}
template <typename F>
auto guarded(F&& f) -> decltype(f()) {
try {
return f();
} catch (const llm::ApiError& e) {
rethrow(e);
}
}
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();
}
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();
}
Json object_of(const Json& b, const char* key) {
const Json* v = b.find(key);
if (!v || v->is_null()) return Json::object();
if (!v->is_object()) bad(std::string(key) + " must be a JSON object");
return *v;
}
Json dry_run(const std::string& what, const Json& planned) {
Json o = Json::object();
o.set("dry_run", Json(true));
o.set("would_send", Json(what));
o.set("request", planned);
o.set("hint", Json("send confirm:true to run it"));
return o;
}
// Redacts anything that could be a secret before it leaves the process.
Json redact(const Json& j) {
if (j.is_object()) {
Json o = Json::object();
for (const auto& [k, v] : j.as_object()) {
bool secret = k == "key" || k == "value" || k == "api_key" || k == "subject_token" ||
k == "code_verifier";
o.set(k, secret && v.is_string() ? Json("***") : redact(v));
}
return o;
}
if (j.is_array()) {
Json a = Json::array();
for (const Json& v : j.as_array()) a.push(redact(v));
return a;
}
return j;
}
Json shown(const Json& j) {
Json r = redact(j);
std::string d = r.dump();
if (d.size() <= kMaxShownBytes) return r;
Json o = Json::object();
o.set("truncated", Json(true));
o.set("bytes", Json(static_cast<long>(d.size())));
o.set("preview", Json(d.substr(0, 4096)));
return o;
}
Json planned_json(const orr::PlannedCall& p) {
Json o = Json::object();
o.set("call", Json(p.name()));
o.set("method", Json(p.spec->http));
o.set("target", Json(p.target()));
o.set("key", Json(p.spec->key));
if (p.has_body) o.set("body", shown(p.body));
return o;
}
orr::PathArgs path_args(const Json& b) {
orr::PathArgs a;
for (const auto& [k, v] : object_of(b, "args").as_object()) {
if (!v.is_string()) bad("args values must be strings");
a[k] = v.as_string();
}
return a;
}
orr::Query query_of(const Json& b) {
orr::Query q;
for (const auto& [k, v] : object_of(b, "query").as_object()) {
if (v.is_string()) q.add(k, v.as_string());
else if (v.is_number()) q.add(k, v.as_number());
else if (v.is_bool()) q.add(k, v.as_bool());
else bad("query values must be strings, numbers or booleans");
}
return q;
}
// Plans a table call from a request body: validation only, no credential.
orr::PlannedCall plan_from(const Json& b) {
std::string name = text(b, "call", true);
Json body = object_of(b, "body");
bool has_body = b.find("body") && !b.find("body")->is_null();
return guarded([&] {
return orr::CallPlanner::plan(name, path_args(b), query_of(b), has_body ? &body : nullptr);
});
}
orr::ChatParams chat_from(const Json& b) {
std::string model = text(b, "model", true);
std::string prompt = text(b, "prompt", true);
if (prompt.size() > 16000) bad("prompt too long");
orr::ChatParams p = orr::ChatParams::simple(model, prompt);
p.max_tokens = 64; // the demo never asks for more
if (const Json* mt = b.find("max_tokens"); mt && !mt->is_null()) {
if (!mt->is_number() || mt->as_int() < 1 || mt->as_int() > 512) bad("max_tokens must be 1..512");
p.max_tokens = static_cast<int>(mt->as_int());
}
if (const Json* pr = b.find("provider"); pr && !pr->is_null()) {
if (!pr->is_object()) bad("provider must be a JSON object");
p.provider = guarded([&] { return orr::ProviderPreferences::from_json(*pr); });
}
if (const Json* fb = b.find("models"); fb && !fb->is_null()) {
if (!fb->is_array()) bad("models must be an array");
for (const Json& m : fb->as_array()) {
if (!m.is_string()) bad("models must hold strings");
p.models.push_back(m.as_string());
}
}
guarded([&] { p.validate(); return 0; });
return p;
}
} // namespace
void register_ai_openrouter_demo(fw::Router& router, Services& services) {
(void)router;
(void)services;
auto gateway = orr::Gateway::from_env();
fw::Environment* env = services.templates.get();
services.templates->add_template("ai_openrouter.html", kPage);
services.add_feature("openrouter", "/ai/openrouter");
auto need_key = [gateway](orr::KeyKind kind) {
// Public routes also need the API key here: the demo never reaches the
// network without a credential.
if (kind == orr::KeyKind::kNone) kind = orr::KeyKind::kApi;
if (gateway->ready(kind)) return;
throw fw::HttpError(503, "not_configured",
std::string("set ") + (kind == orr::KeyKind::kManagement ? orr::kManagementKeyEnv : orr::kApiKeyEnv));
};
router.get("/ai/openrouter", "ai-openrouter-page", [env](fw::Request req) {
(void)req;
fw::TemplateCtx ctx;
ctx["title"] = std::string("OpenRouter");
return fw::Response(200, env->render("ai_openrouter.html", ctx), "text/html; charset=utf-8");
});
router.get("/ai/openrouter/status", "ai-openrouter-status", [gateway](fw::Request req) {
(void)req;
Json o = Json::object();
o.set("configured", Json(gateway->api_configured()));
o.set("management_configured", Json(gateway->management_configured()));
o.set("calls", Json(static_cast<long>(orr::kCallCount)));
o.set("api_key_env", Json(orr::kApiKeyEnv));
o.set("management_key_env", Json(orr::kManagementKeyEnv));
return json_out(o);
});
// The spec-checked call table, for humans and for the page's call picker.
router.get("/ai/openrouter/calls", "ai-openrouter-calls", [](fw::Request req) {
(void)req;
Json arr = Json::array();
for (const orr::CallSpec& s : orr::kCalls) {
Json row = Json::object();
row.set("call", Json(s.name));
row.set("http", Json(s.http));
row.set("path", Json(s.path));
row.set("key", Json(s.key));
row.set("op", Json(s.op));
arr.push(row);
}
Json o = Json::object();
o.set("calls", arr);
return json_out(o);
});
// Validation only: shows the exact request a call would send. No network.
router.post("/ai/openrouter/plan", "ai-openrouter-plan", [](fw::Request req) {
Json b = parse_body(req);
return json_out(planned_json(plan_from(b)));
});
// Any table call. GET calls run; every other method is a dry run unless
// confirm:true. The credential kind follows the table row.
router.post("/ai/openrouter/call", "ai-openrouter-call", [gateway, need_key](fw::Request req) {
Json b = parse_body(req);
orr::PlannedCall plan = plan_from(b);
bool confirm = flag(b, "confirm");
const std::string fmt = plan.fmt();
if (fmt == "multipart") bad("upload files through the module API, not this route");
if (plan.spec->http != std::string("GET") && !confirm)
return json_out(dry_run(plan.name(), planned_json(plan)));
need_key(plan.key);
return guarded([&] {
if (fmt == "raw") {
llm::RawResponse raw = gateway->call_raw(plan);
Json o = Json::object();
o.set("bytes", Json(static_cast<long>(raw.body.size())));
o.set("content_type", Json(raw.content_type));
return json_out(o);
}
return json_out(shown(gateway->call(plan)));
});
});
// Chat completion (costs money): dry run unless confirm:true.
router.post("/ai/openrouter/chat", "ai-openrouter-chat", [gateway, need_key](fw::Request req) {
Json b = parse_body(req);
orr::ChatParams params = chat_from(b);
if (!flag(b, "confirm")) return json_out(dry_run("chat", shown(params.to_json(false))));
need_key(orr::KeyKind::kApi);
return guarded([&] {
orr::ChatService chat(gateway);
orr::ChatResult r = chat.create(params);
Json o = Json::object();
o.set("id", Json(r.id));
o.set("model", Json(r.model));
o.set("provider", Json(r.provider));
o.set("text", Json(r.text()));
o.set("reasoning", Json(r.choices.empty() ? "" : r.first().reasoning));
o.set("finish_reason", Json(r.finish_reason()));
if (r.usage) {
Json u = Json::object();
u.set("input_tokens", Json(r.usage->input_tokens));
u.set("output_tokens", Json(r.usage->output_tokens));
u.set("total_tokens", Json(r.usage->total_tokens));
o.set("usage", u);
}
if (r.cost) o.set("cost_usd", Json(*r.cost));
return json_out(o);
});
});
// Responses (beta) and the Anthropic-compatible messages route: raw bodies, paid.
auto paid_raw = [gateway, need_key](const char* which) {
return [gateway, need_key, which](fw::Request req) {
Json b = parse_body(req);
Json body = object_of(b, "body");
bool is_messages = std::string(which) == "messages";
std::string call = is_messages ? "createMessages" : "createResponses";
orr::PlannedCall plan = guarded([&] { return orr::CallPlanner::plan(call, {}, {}, &body); });
if (!flag(b, "confirm")) return json_out(dry_run(call, planned_json(plan)));
need_key(orr::KeyKind::kApi);
return guarded([&] {
if (is_messages) return json_out(shown(orr::MessagesService(gateway).create(body)));
return json_out(shown(orr::ResponsesService(gateway).create(body)));
});
};
};
router.post("/ai/openrouter/responses", "ai-openrouter-responses", paid_raw("responses"));
router.post("/ai/openrouter/messages", "ai-openrouter-messages", paid_raw("messages"));
// Model variants: pure local parsing, no network.
router.post("/ai/openrouter/model-ref", "ai-openrouter-model-ref", [](fw::Request req) {
Json b = parse_body(req);
orr::ModelRef m = guarded([&] { return orr::ModelRef::parse(text(b, "model", true)); });
Json o = Json::object();
o.set("base", Json(m.base()));
o.set("request_id", Json(m.str()));
o.set("catalog_id", Json(m.catalog_id()));
o.set("catalog_variant", Json(m.catalog_variant()));
Json rv = Json::array();
for (const std::string& v : m.routing_variants()) rv.push(Json(v));
o.set("routing_variants", rv);
o.set("deprecated_variant", Json(m.uses_deprecated_variant()));
return json_out(o);
});
}
} // namespace molo::example::app