feat(clients): deepseek: chat, beta, responses, anthropic, files, search, fetch, spec checker, demo

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-24 07:40:33 +02:00
co-authored by Claude Sonnet 5.5
parent 2e0270c043
commit 927e4e5a2f
42 changed files with 6219 additions and 3 deletions
+563 -3
View File
@@ -1,13 +1,573 @@
#include "../AiDemos.hpp"
#include <functional>
#include "../../fw/Router.hpp"
#include "../../fw/Templates.hpp"
#include "deepseek/account.h"
#include "deepseek/anthropic.h"
#include "deepseek/calls.h"
#include "deepseek/caps.h"
#include "deepseek/chat.h"
#include "deepseek/errors.h"
#include "deepseek/files.h"
#include "deepseek/fim.h"
#include "deepseek/platform.h"
#include "deepseek/responses.h"
#include "deepseek/web.h"
#include "security/crypto/Base64.h"
namespace molo::example::app {
// DeepSeek API. Stub: the module agent fills this in.
// DeepSeek API platform over the real src/deepseek part. GET routes need no
// credential. Every route that calls DeepSeek is a POST: 422 on bad input,
// 503 deepseek_not_configured without DEEPSEEK_API_KEY. Routes that cost
// money (completions, search, fetch) or change resources (upload, delete) are
// dry runs that show the exact request unless the body has "confirm":true.
namespace {
namespace ds = deepseek;
using Json = clients::body::Json;
constexpr std::size_t kMaxBody = 8 * 1024 * 1024; // uploads travel as base64
const char kPage[] = R"DEEPSEEK({% extends "base.html" %}
{% block content %}
<h1>DeepSeek API</h1>
<p class="hint">Chat, streaming, thinking, tools, JSON, beta (prefix, FIM, strict), Responses,
Anthropic-compatible, files, search, fetch, models, balance. Paid and destructive calls
are dry runs until the body says <code>"confirm":true</code>.</p>
<p id="ds-config" class="hint">Checking credential...</p>
<section class="ds">
<label>Route
<select id="ds-route"></select></label>
<label>Body (JSON object) <textarea id="ds-body" rows="8"></textarea></label>
<div class="ds-actions">
<button id="ds-send" type="button" class="primary">Send</button>
<button id="ds-confirm" type="button">Send with confirm</button>
</div>
<p id="ds-error" class="error" role="alert"></p>
<pre id="ds-out" class="ds-out"></pre>
</section>
<style>
.ds label{display:block;margin:.5rem 0}
.ds select,.ds textarea{width:100%;box-sizing:border-box}
.ds-actions{display:flex;flex-wrap:wrap;gap:.5rem;margin:.5rem 0}
.ds-out{overflow:auto;max-height:24rem;white-space:pre-wrap;word-break:break-word}
</style>
<script src="/embedded/ai_deepseek.js"></script>
{% endblock %}
)DEEPSEEK";
[[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<int> 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<int>(v->as_int());
}
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::vector<std::string> strings(const Json& b, const char* key) {
std::vector<std::string> 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 usage_json(const ds::TokenUsage& u) {
Json o = Json::object();
o.set("input_tokens", Json(u.input_tokens));
o.set("output_tokens", Json(u.output_tokens));
o.set("total_tokens", Json(u.total_tokens));
o.set("cache_hit_tokens", Json(u.cache_hit_tokens));
o.set("cache_miss_tokens", Json(u.cache_miss_tokens));
o.set("reasoning_tokens", Json(u.reasoning_tokens));
return o;
}
Json chat_json(const ds::ChatResult& r) {
Json o = Json::object();
o.set("id", Json(r.id));
o.set("model", Json(r.model));
if (!r.choices.empty()) {
const ds::ChatChoice& c = r.first();
o.set("finish_reason", Json(c.finish_reason));
o.set("content", Json(c.content));
o.set("reasoning_content", Json(c.reasoning_content));
Json calls = Json::array();
for (const ds::ToolCallRecord& t : c.tool_calls) {
Json x = Json::object();
x.set("id", Json(t.id));
x.set("name", Json(t.name));
x.set("arguments", Json(t.arguments));
x.set("arguments_valid", Json(t.arguments_valid()));
calls.push(x);
}
o.set("tool_calls", calls);
}
o.set("usage", usage_json(r.usage));
return o;
}
Json dry_run(const Json& request, const char* 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;
}
ds::ChatParams chat_params(const Json& b) {
ds::ChatParams p;
std::string model = text(b, "model");
if (!model.empty()) p.model = model;
std::string system = text(b, "system");
if (!system.empty()) p.add(ds::Messages::system(system));
p.add(ds::Messages::user(text(b, "prompt", true)));
std::string thinking = text(b, "thinking");
if (thinking == "enabled") p.thinking = ds::Thinking::kEnabled;
else if (thinking == "disabled") p.thinking = ds::Thinking::kDisabled;
else if (!thinking.empty()) bad("thinking must be enabled or disabled");
p.reasoning_effort = text(b, "effort");
p.max_tokens = number(b, "max_tokens");
p.json_mode = flag(b, "json");
p.stop = strings(b, "stop");
p.user_id = text(b, "user_id");
if (const Json* t = b.find("temperature"); t && t->is_number()) p.temperature = t->as_number();
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)
const char* path = ""; // for the dry-run message
bool needs_confirm = false; // paid or changes a resource
std::function<Json()> call;
};
class DeepseekRoutes {
public:
explicit DeepseekRoutes(ds::Platform platform) : p_(std::move(platform)) {}
const ds::Platform& platform() const { return p_; }
using Planner = std::function<Plan(const Json&)>;
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 chat(const Json& b) const {
ds::ChatParams params = chat_params(b);
Plan pl{params.to_json(), "/chat/completions", true, nullptr};
auto chat = std::make_shared<ds::Chat>(p_.openai);
pl.call = [chat, params] { return chat_json(chat->create(params)); };
return pl;
}
Plan stream(const Json& b) const {
ds::ChatParams params = chat_params(b);
Plan pl{params.to_json(true), "/chat/completions", true, nullptr};
auto chat = std::make_shared<ds::Chat>(p_.openai);
pl.call = [chat, params] {
std::size_t events = 0;
std::string content, reasoning;
ds::ChatResult r = chat->stream(params, [&](const ds::StreamDelta& d) {
content += d.content;
reasoning += d.reasoning;
return ++events < ds::DeepseekCaps::kMaxStreamEvents;
});
Json o = chat_json(r);
o.set("chunks", Json(static_cast<int>(events)));
return o;
};
return pl;
}
Plan prefix(const Json& b) const {
ds::ChatParams params = chat_params(b);
std::string prefix = text(b, "prefix", true);
params.add(ds::Messages::assistant_prefix(prefix, text(b, "reasoning")));
Plan pl{params.to_json(), "/beta/chat/completions", true, nullptr};
auto chat = std::make_shared<ds::Chat>(p_.openai);
pl.call = [chat, params] { return chat_json(chat->create(params)); };
return pl;
}
Plan tools(const Json& b) const {
ds::ChatParams params = chat_params(b);
ds::ToolDef t;
t.name = "get_weather";
t.description = "Get weather of a location, the user should supply a location first.";
t.strict = flag(b, "strict");
t.parameters = Json::parse(
"{\"type\":\"object\",\"properties\":{\"location\":{\"type\":\"string\",\"description\":\"The city and state\"}},"
"\"required\":[\"location\"],\"additionalProperties\":false}");
params.tools.push_back(t);
Plan pl{params.to_json(), t.strict ? "/beta/chat/completions" : "/chat/completions", true, nullptr};
auto chat = std::make_shared<ds::Chat>(p_.openai);
pl.call = [chat, params] { return chat_json(chat->create(params)); };
return pl;
}
Plan fim(const Json& b) const {
ds::FimParams params;
std::string model = text(b, "model");
if (!model.empty()) params.model = model;
params.prompt = text(b, "prompt", true);
params.suffix = text(b, "suffix");
params.max_tokens = number(b, "max_tokens");
params.stop = strings(b, "stop");
Plan pl{params.to_json(), "/beta/completions", true, nullptr};
auto api = std::make_shared<ds::Fim>(p_.openai);
pl.call = [api, params] {
ds::FimResult r = api->create(params);
Json o = Json::object();
o.set("id", Json(r.id));
o.set("text", Json(r.choices.empty() ? "" : r.first().text));
o.set("finish_reason", Json(r.choices.empty() ? "" : r.first().finish_reason));
o.set("usage", usage_json(r.usage));
return o;
};
return pl;
}
Plan responses(const Json& b) const {
ds::ResponsesParams params;
std::string model = text(b, "model");
if (!model.empty()) params.model = model;
std::string input = text(b, "input");
if (!input.empty()) params.input_text = input;
params.instructions = text(b, "instructions");
params.effort = text(b, "effort");
params.max_output_tokens = number(b, "max_output_tokens");
if (flag(b, "json")) params.format = ds::TextFormat::kJsonObject;
Plan pl{params.to_json(), "/responses", true, nullptr};
auto api = std::make_shared<ds::Responses>(p_.openai);
pl.call = [api, params] {
ds::ResponsesResult r = api->create(params);
Json o = Json::object();
o.set("id", Json(r.id));
o.set("status", Json(r.status));
o.set("output_text", Json(r.output_text()));
o.set("reasoning_text", Json(r.reasoning_text()));
o.set("usage", usage_json(r.usage));
return o;
};
return pl;
}
Plan anthropic(const Json& b) const {
ds::MessagesParams params;
std::string model = text(b, "model");
if (!model.empty()) params.model = model;
if (auto n = number(b, "max_tokens")) params.max_tokens = *n;
params.system = text(b, "system");
params.add(ds::AnthropicBlocks::message_text("user", text(b, "prompt", true)));
std::string thinking = text(b, "thinking");
if (thinking == "enabled") params.thinking = true;
else if (thinking == "disabled") params.thinking = false;
params.effort = text(b, "effort");
Plan pl{params.to_json(), "/anthropic/v1/messages", true, nullptr};
auto api = std::make_shared<ds::AnthropicMessages>(p_.anthropic);
pl.call = [api, params] {
ds::MessagesResult r = api->create(params);
Json o = Json::object();
o.set("id", Json(r.id));
o.set("model", Json(r.model));
o.set("stop_reason", Json(r.stop_reason));
o.set("text", Json(r.text()));
o.set("thinking", Json(r.thinking_text()));
o.set("usage", usage_json(r.usage));
return o;
};
return pl;
}
Plan models(const Json&) const {
auto api = std::make_shared<ds::Account>(p_.openai);
return Plan{Json::object(), "/models", false, [api] {
ds::ModelList l = api->models();
Json arr = Json::array();
for (const ds::ModelInfo& m : l.models) {
Json x = Json::object();
x.set("id", Json(m.id));
x.set("name", Json(m.name));
x.set("context_window", Json(static_cast<int>(m.context_window)));
x.set("max_output_tokens", Json(static_cast<int>(m.max_output_tokens)));
x.set("images", Json(m.accepts_images()));
arr.push(x);
}
Json o = Json::object();
o.set("models", arr);
return o;
}};
}
Plan balance(const Json&) const {
auto api = std::make_shared<ds::Account>(p_.openai);
return Plan{Json::object(), "/user/balance", false, [api] {
ds::Balance bal = api->balance();
Json arr = Json::array();
for (const ds::BalanceEntry& e : bal.entries) {
Json x = Json::object();
x.set("currency", Json(e.currency));
x.set("total", Json(e.total));
x.set("granted", Json(e.granted));
x.set("topped_up", Json(e.topped_up));
arr.push(x);
}
Json o = Json::object();
o.set("is_available", Json(bal.available));
o.set("balances", arr);
return o;
}};
}
Plan files(const Json& b) const {
std::string action = text(b, "action", true);
auto api = std::make_shared<ds::Files>(p_.openai);
auto file_json = [](const ds::FileInfo& f) {
Json x = Json::object();
x.set("id", Json(f.id));
x.set("bytes", Json(static_cast<int>(f.bytes)));
x.set("filename", Json(f.filename));
x.set("created_at", Json(static_cast<int>(f.created_at)));
return x;
};
if (action == "list") {
ds::FileListParams lp;
if (auto n = number(b, "limit")) lp.limit = *n;
lp.order = text(b, "order");
lp.after = text(b, "after");
lp.validate();
return Plan{Json::object(), "/files", false, [api, lp, file_json] {
ds::FileList l = api->list(lp);
Json arr = Json::array();
for (const ds::FileInfo& 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 == "get" || action == "delete") {
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, "/files/{id}", false, [api, id, file_json] { return file_json(api->get(id)); }};
return Plan{req, "DELETE /files/{id}", true, [api, id] {
ds::FileDeleted d = api->remove(id);
Json o = Json::object();
o.set("id", Json(d.id));
o.set("deleted", Json(d.deleted));
return o;
}};
}
if (action == "upload") {
ds::UploadParams up;
up.filename = text(b, "filename", true);
if (!security::crypto::Base64::decode(text(b, "data_base64", true), up.data))
bad("data_base64 is not valid base64");
if (auto n = number(b, "expires_after_seconds")) up.expires_after_seconds = *n;
up.validate();
Json req = Json::object();
req.set("filename", Json(up.filename));
req.set("bytes", Json(static_cast<int>(up.data.size())));
req.set("format", Json(ds::UploadParams::sniff(up.data)));
return Plan{req, "POST /files", true, [api, up, file_json] { return file_json(api->upload(up)); }};
}
bad("action must be list, get, upload or delete");
}
Plan search(const Json& b) const {
ds::SearchParams sp;
sp.query = text(b, "query", true);
if (auto n = number(b, "count")) sp.count = *n;
sp.need_content = flag(b, "need_content");
Plan pl{sp.to_json(), "/v1/tools/search", true, nullptr};
auto api = std::make_shared<ds::Web>(p_.openai);
pl.call = [api, sp] {
ds::SearchResults r = api->search(sp);
Json arr = Json::array();
for (const ds::SearchHit& h : r.hits) {
Json x = Json::object();
x.set("title", Json(h.title));
x.set("url", Json(h.url));
x.set("snippet", Json(h.snippet));
x.set("rerank_score", Json(h.rerank_score));
arr.push(x);
}
Json o = Json::object();
o.set("results", arr);
return o;
};
return pl;
}
Plan fetch(const Json& b) const {
std::string url = text(b, "url", true);
ds::Web::validate_url(url);
Json req = Json::object();
req.set("url", Json(url));
auto api = std::make_shared<ds::Web>(p_.openai);
return Plan{req, "/v1/tools/fetch", true, [api, url] {
ds::FetchResult f = api->fetch(url);
Json o = Json::object();
o.set("title", Json(f.title));
o.set("content", Json(f.content.substr(0, 20000)));
return o;
}};
}
private:
[[noreturn]] static void map(const llm::ApiError& e) {
if (e.http_status() == 503 && e.type() == "NOT_CONFIGURED")
throw fw::HttpError(503, "deepseek_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, "deepseek_error", ds::Errors::explain(e) + " | " + e.type() + ": " + e.message());
}
ds::Platform p_;
};
} // namespace
void register_ai_deepseek_demo(fw::Router& router, Services& services) {
(void)router;
(void)services;
auto routes = std::make_shared<DeepseekRoutes>(ds::Platform::from_env());
fw::Environment* env = services.templates.get();
services.templates->add_template("ai_deepseek.html", kPage);
services.add_feature("ai-deepseek", "/ai/deepseek");
router.get("/ai/deepseek", "ai-deepseek-page", [env](fw::Request req) {
(void)req;
fw::TemplateCtx ctx;
ctx["title"] = std::string("DeepSeek API");
return fw::Response(200, env->render("ai_deepseek.html", ctx), "text/html; charset=utf-8");
});
router.get("/ai/deepseek/status", "ai-deepseek-status", [routes](fw::Request req) {
(void)req;
Json o = Json::object();
o.set("configured", Json(routes->platform().configured()));
o.set("credential_env", Json(ds::Platform::kKeyEnv));
o.set("base_url", Json(ds::Platform::kHost));
o.set("calls", Json(static_cast<int>(ds::Calls::count())));
Json models = Json::array();
for (std::size_t i = 0; i < ds::ModelCatalog::count(); ++i) {
Json m = Json::object();
m.set("id", Json(ds::ModelCatalog::at(i).id));
m.set("note", Json(ds::ModelCatalog::at(i).note));
models.push(m);
}
o.set("models", models);
o.set("max_tokens_ceiling", Json(ds::DeepseekCaps::kMaxTokensCeiling));
o.set("max_images", Json(static_cast<int>(ds::DeepseekCaps::kMaxImages)));
return json_out(o);
});
router.get("/ai/deepseek/calls", "ai-deepseek-calls", [](fw::Request req) {
(void)req;
Json arr = Json::array();
for (std::size_t i = 0; i < ds::Calls::count(); ++i) {
const ds::CallSpec& s = ds::Calls::at(i);
Json row = Json::object();
row.set("http", Json(s.http_method));
row.set("path", Json(s.path));
row.set("doc", Json(s.doc));
arr.push(row);
}
Json o = Json::object();
o.set("calls", arr);
return json_out(o);
});
router.get("/ai/deepseek/errors", "ai-deepseek-errors", [](fw::Request req) {
(void)req;
Json arr = Json::array();
for (std::size_t i = 0; i < ds::Errors::count(); ++i) {
const ds::ErrorInfo& e = ds::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));
row.set("surface", Json(e.surface));
arr.push(row);
}
Json o = Json::object();
o.set("errors", arr);
return json_out(o);
});
using Member = DeepseekRoutes::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); });
};
DeepseekRoutes* r = routes.get();
auto bind = [r](Plan (DeepseekRoutes::*m)(const Json&) const) {
return Member([r, m](const Json& b) { return (r->*m)(b); });
};
add("/ai/deepseek/chat", "ai-deepseek-chat", bind(&DeepseekRoutes::chat));
add("/ai/deepseek/stream", "ai-deepseek-stream", bind(&DeepseekRoutes::stream));
add("/ai/deepseek/prefix", "ai-deepseek-prefix", bind(&DeepseekRoutes::prefix));
add("/ai/deepseek/tools", "ai-deepseek-tools", bind(&DeepseekRoutes::tools));
add("/ai/deepseek/fim", "ai-deepseek-fim", bind(&DeepseekRoutes::fim));
add("/ai/deepseek/responses", "ai-deepseek-responses", bind(&DeepseekRoutes::responses));
add("/ai/deepseek/anthropic", "ai-deepseek-anthropic", bind(&DeepseekRoutes::anthropic));
add("/ai/deepseek/models", "ai-deepseek-models", bind(&DeepseekRoutes::models));
add("/ai/deepseek/balance", "ai-deepseek-balance", bind(&DeepseekRoutes::balance));
add("/ai/deepseek/files", "ai-deepseek-files", bind(&DeepseekRoutes::files));
add("/ai/deepseek/search", "ai-deepseek-search", bind(&DeepseekRoutes::search));
add("/ai/deepseek/fetch", "ai-deepseek-fetch", bind(&DeepseekRoutes::fetch));
}
} // namespace molo::example::app