From 927e4e5a2f61a9a15ae6eb62acc870a02655c2d2 Mon Sep 17 00:00:00 2001 From: retoor Date: Sat, 24 Oct 2026 07:40:33 +0200 Subject: [PATCH] feat(clients): deepseek: chat, beta, responses, anthropic, files, search, fetch, spec checker, demo Co-Authored-By: Claude Sonnet 5.5 --- example/app/ai/DeepseekDemo.cpp | 566 ++++++++++++++++++- example/assets/ai_deepseek.js | 58 ++ src/deepseek/SPEC.md | 205 +++++++ src/deepseek/account.cpp | 51 ++ src/deepseek/account.h | 46 ++ src/deepseek/anthropic.cpp | 383 +++++++++++++ src/deepseek/anthropic.h | 99 ++++ src/deepseek/calls.cpp | 92 +++ src/deepseek/calls.h | 58 ++ src/deepseek/caps.h | 41 ++ src/deepseek/chat.cpp | 87 +++ src/deepseek/chat.h | 67 +++ src/deepseek/chat_model.cpp | 199 +++++++ src/deepseek/chat_model.h | 44 ++ src/deepseek/chat_params.cpp | 430 ++++++++++++++ src/deepseek/chat_params.h | 94 +++ src/deepseek/chat_result.cpp | 180 ++++++ src/deepseek/chat_result.h | 89 +++ src/deepseek/errors.cpp | 82 +++ src/deepseek/errors.h | 48 ++ src/deepseek/files.cpp | 143 +++++ src/deepseek/files.h | 68 +++ src/deepseek/fim.cpp | 123 ++++ src/deepseek/fim.h | 55 ++ src/deepseek/platform.cpp | 38 ++ src/deepseek/platform.h | 31 + src/deepseek/responses.cpp | 358 ++++++++++++ src/deepseek/responses.h | 99 ++++ src/deepseek/rules.cpp | 87 +++ src/deepseek/rules.h | 38 ++ src/deepseek/tools/check_spec.py | 168 ++++++ src/deepseek/types.cpp | 216 +++++++ src/deepseek/types.h | 123 ++++ src/deepseek/web.cpp | 60 ++ src/deepseek/web.h | 35 ++ tests/example/ai/deepseek/page_test.cpp | 35 ++ tests/example/ai/deepseek/routes_test.cpp | 69 +++ tests/src/deepseek/support.h | 59 ++ tests/src/deepseek/test_chat_flow.cpp | 428 ++++++++++++++ tests/src/deepseek/test_endpoints.cpp | 659 ++++++++++++++++++++++ tests/src/deepseek/test_live.cpp | 60 ++ tests/src/deepseek/test_params.cpp | 351 ++++++++++++ 42 files changed, 6219 insertions(+), 3 deletions(-) create mode 100644 example/assets/ai_deepseek.js create mode 100644 src/deepseek/SPEC.md create mode 100644 src/deepseek/account.cpp create mode 100644 src/deepseek/account.h create mode 100644 src/deepseek/anthropic.cpp create mode 100644 src/deepseek/anthropic.h create mode 100644 src/deepseek/calls.cpp create mode 100644 src/deepseek/calls.h create mode 100644 src/deepseek/caps.h create mode 100644 src/deepseek/chat.cpp create mode 100644 src/deepseek/chat.h create mode 100644 src/deepseek/chat_model.cpp create mode 100644 src/deepseek/chat_model.h create mode 100644 src/deepseek/chat_params.cpp create mode 100644 src/deepseek/chat_params.h create mode 100644 src/deepseek/chat_result.cpp create mode 100644 src/deepseek/chat_result.h create mode 100644 src/deepseek/errors.cpp create mode 100644 src/deepseek/errors.h create mode 100644 src/deepseek/files.cpp create mode 100644 src/deepseek/files.h create mode 100644 src/deepseek/fim.cpp create mode 100644 src/deepseek/fim.h create mode 100644 src/deepseek/platform.cpp create mode 100644 src/deepseek/platform.h create mode 100644 src/deepseek/responses.cpp create mode 100644 src/deepseek/responses.h create mode 100644 src/deepseek/rules.cpp create mode 100644 src/deepseek/rules.h create mode 100644 src/deepseek/tools/check_spec.py create mode 100644 src/deepseek/types.cpp create mode 100644 src/deepseek/types.h create mode 100644 src/deepseek/web.cpp create mode 100644 src/deepseek/web.h create mode 100644 tests/example/ai/deepseek/page_test.cpp create mode 100644 tests/example/ai/deepseek/routes_test.cpp create mode 100644 tests/src/deepseek/support.h create mode 100644 tests/src/deepseek/test_chat_flow.cpp create mode 100644 tests/src/deepseek/test_endpoints.cpp create mode 100644 tests/src/deepseek/test_live.cpp create mode 100644 tests/src/deepseek/test_params.cpp diff --git a/example/app/ai/DeepseekDemo.cpp b/example/app/ai/DeepseekDemo.cpp index 282860b..b7ae5c5 100644 --- a/example/app/ai/DeepseekDemo.cpp +++ b/example/app/ai/DeepseekDemo.cpp @@ -1,13 +1,573 @@ #include "../AiDemos.hpp" +#include + #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 %} +

DeepSeek API

+

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 "confirm":true.

+

Checking credential...

+
+ + +
+ + +
+ +

+
+ + +{% 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 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()); +} + +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 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 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 call; +}; + +class DeepseekRoutes { + public: + explicit DeepseekRoutes(ds::Platform platform) : p_(std::move(platform)) {} + + const ds::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 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(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(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(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(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(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(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(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(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(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(m.context_window))); + x.set("max_output_tokens", Json(static_cast(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(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(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(f.bytes))); + x.set("filename", Json(f.filename)); + x.set("created_at", Json(static_cast(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(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(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(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(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(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(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 diff --git a/example/assets/ai_deepseek.js b/example/assets/ai_deepseek.js new file mode 100644 index 0000000..01abcd5 --- /dev/null +++ b/example/assets/ai_deepseek.js @@ -0,0 +1,58 @@ +// DeepSeek page: thin client over /ai/deepseek/* (all limits server side). +(function () { + "use strict"; + var $ = function (id) { return document.getElementById(id); }; + var out = $("ds-out"), err = $("ds-error"); + var templates = { + "chat": { prompt: "Hello!", thinking: "enabled", effort: "high", max_tokens: 256 }, + "stream": { prompt: "Count to five.", thinking: "disabled", max_tokens: 128 }, + "prefix": { prompt: "Write quick sort", prefix: "```python\n", stop: ["```"], thinking: "disabled" }, + "tools": { prompt: "Weather in Hangzhou?", strict: false, thinking: "disabled" }, + "fim": { prompt: "def fib(a):", suffix: " return fib(a-1) + fib(a-2)", max_tokens: 128 }, + "responses": { input: "Hi, how are you?", instructions: "Be brief.", effort: "low" }, + "anthropic": { prompt: "Hi", max_tokens: 256, thinking: "disabled" }, + "models": {}, + "balance": {}, + "files": { action: "list", limit: 20 }, + "search": { query: "DeepSeek V4 release", count: 5 }, + "fetch": { url: "https://example.com" } + }; + var sel = $("ds-route"); + Object.keys(templates).forEach(function (k) { + var o = document.createElement("option"); + o.value = k; o.textContent = k; + sel.appendChild(o); + }); + function fill() { $("ds-body").value = JSON.stringify(templates[sel.value], null, 1); } + sel.onchange = fill; + fill(); + + function send(confirm) { + var body; + try { body = JSON.parse($("ds-body").value || "{}"); } + catch (e) { err.textContent = "Body is not valid JSON"; return; } + if (confirm) body.confirm = true; + err.textContent = ""; + out.textContent = "..."; + fetch("/ai/deepseek/" + 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 = ""; }); + } + $("ds-send").onclick = function () { send(false); }; + $("ds-confirm").onclick = function () { send(true); }; + + fetch("/ai/deepseek/status").then(function (r) { return r.json(); }).then(function (s) { + $("ds-config").textContent = s.configured + ? "DEEPSEEK_API_KEY found. Calls are real; paid ones need confirm." + : "No DEEPSEEK_API_KEY: calls answer 503 until one is configured; dry runs still work."; + }); +})(); diff --git a/src/deepseek/SPEC.md b/src/deepseek/SPEC.md new file mode 100644 index 0000000..1be28e1 --- /dev/null +++ b/src/deepseek/SPEC.md @@ -0,0 +1,205 @@ +# DeepSeek API platform - Specification + +Owned directory: `src/deepseek/`. Namespace `molo::deepseek`. Depends on the +`src/llm` foundation (`ApiClient`, `Service`, `SseDecoder`, `ApiError`, +`Config`, `ChatModel`). Plan: `plans/17-llm-vendor-platforms.md`. Credential: +`DEEPSEEK_API_KEY` via `llm::Config`. + +## 1. Scope + +The whole public platform at `https://api.deepseek.com` as documented on +2026-10-24 (models `deepseek-flash`, `deepseek-v4-pro`): + +- Chat Completions: thinking toggle and effort, `reasoning_content` in + responses and streams, tool calls, JSON output, logprobs, vision parts + (`image_url`, `file`), `user_id`, streaming with the usage on the last chunk. +- Beta (same host, `/beta/...`): chat prefix completion, strict tool mode, FIM. +- Responses API (stateless): items, tools (`function`, `custom` apply_patch, + `web_search` on v4-pro), `text.format`, streaming events. +- Anthropic-compatible `POST /anthropic/v1/messages` (x-api-key) and its + Files endpoints. +- Files API (images, `file-api-...` ids), models list, user balance, + Search API and Fetch API, context caching usage fields, error codes and + retry semantics, `DeepseekChatModel : llm::ChatModel`. + +Not here, said plainly: no embeddings, audio, image generation, batch, fine +tuning or admin/billing API exists on this platform (none is documented). +`/v1/chat/completions` and the non-beta `/completions` were not documented and +are not wrapped. Pricing tables are not wrapped (the pricing page was not +readable as text, see Gaps). + +## 2. Module map + +| File | Concern | +|---|---| +| `caps.h` | Static ceilings (`DeepseekCaps`) | +| `calls.h/.cpp` | The ONE call table (17 rows) and schema table; `Calls::render` | +| `rules.h/.cpp` | Shared input rules (`Rules`), all throw `ApiError::invalid` | +| `types.h/.cpp` | `TokenUsage` (cache hit/miss, reasoning), `ModelInfo`, `Balance`, `FileInfo`, `SearchResults`, `FetchResult` | +| `errors.h/.cpp` | `Errors`: documented codes, retryable, static waits, `explain` | +| `platform.h/.cpp` | `Platform`: the two `ApiClient`s (Bearer, x-api-key) | +| `chat_params.h/.cpp` | `Messages` builders, `ToolDef`, `StrictSchema`, `ChatParams` (validate, body, reasoning rule) | +| `chat_result.h/.cpp` | `ChatResult`, `ChatStreamAccumulator`, `StreamDelta` | +| `chat.h/.cpp` | `Chat : Service` (create, stream, prefix), `Conversation` (history, tool loop) | +| `fim.h/.cpp` | `Fim : Service` (beta FIM) | +| `responses.h/.cpp` | `Responses : Service`, `ResponseItems`, `ResponsesParams` | +| `anthropic.h/.cpp` | `AnthropicMessages : Service`, `AnthropicBlocks`, `MessagesParams` | +| `files.h/.cpp` | `Files`, `AnthropicFiles` (explicit `remove`) | +| `web.h/.cpp` | `Web : Service` (search, fetch) | +| `account.h/.cpp` | `Account : Service` (models, balance), `ModelCatalog` | +| `chat_model.h/.cpp` | `DeepseekChatModel : llm::ChatModel` | +| `tools/check_spec.py` | Checks the call/schema tables against the published reference | + +## 3. Static caps + +| Knob | Value | +|---|---| +| max_tokens / max_output_tokens | 1..393216; FIM 1..4096 | +| stop sequences | 16 | +| top_logprobs / logprobs | 0..20 | +| temperature / top_p | 0..2 / (0,1] | +| tool name | `[A-Za-z0-9_-]{1,128}`, unique; tools per request 128 (ours) | +| user_id | `[A-Za-z0-9_-]{1,512}` | +| messages 4096 (ours), images per request 600, image URL 8192 chars | +| upload | 64 MiB, filename 512 bytes, JPEG/PNG/GIF/WebP by magic bytes, expiry 3600..2592000 s | +| file list | limit 1..1000; walk 20 pages, 5000 files, then `truncated=true` | +| search | query 128 chars, count 1..50; fetch URL 8192 chars, http(s), no userinfo | +| stream events | 200000 (ours); tool rounds 16 (ours) | +| schema depth (strict) | 16 (ours) | + +## 4. Contracts + +- Every path comes from the call table. Input is validated before any network + traffic (HTTP 400 `INVALID_ARGUMENT`, vendor `deepseek`); no credential: + `NotConfiguredError` 503 before traffic. +- Reasoning rule (Thinking Mode guide): `reasoning_content` of earlier turns is + sent back ONLY when the request has tools (the API answers 400 otherwise); + without tools it is dropped from the body (the API ignores it). The beta + prefix message keeps its `reasoning_content` as CoT input. `Conversation` + appends `ChatChoice::history_message()` as returned. +- Thinking is on by default. `tool_choice` `required` or a named tool needs + thinking off (400 otherwise); rejected locally. `temperature` has no effect + in thinking mode; `frequency_penalty`/`presence_penalty` are deprecated and + never sent. +- Strict tools: all functions strict, schema subset checked locally + (`StrictSchema`), routed to `/beta/chat/completions` automatically. +- JSON output needs the word "json" in a message (else the model may stream + whitespace); enforced locally. +- Streams: `: keep-alive` comments and blank lines are ignored by the + foundation decoder; the usage rides on the last content chunk; a stream + that ends without `finish_reason` / terminal event / `message_stop` and was + not stopped by the consumer throws 502 `STREAM_TRUNCATED`. Finish reasons + `insufficient_system_resource` and `aborted` are passed through + (`ChatChoice::interrupted`). +- Tool call arguments may be invalid JSON: `ToolCallRecord::arguments_valid`; + `DeepseekChatModel` hands them over as `{"_invalid_json": ""}`. +- Errors (`Errors`): 400 format, 401 auth, 402 balance, 422 params, 429 rate, + 500, 503 overloaded; Search/Fetch add 403, 404, 408, 413, 504. Retryable + (wait, then retry): 408, 429, 500, 503, 504 with static waits of 1..2 s, + cap 30 s. The foundation client retries idempotent requests (GET) on + 429/5xx; POSTs are not retried after the body was sent, the caller decides. + Concurrency limits are per account (flash 2500, v4-pro 500, per `user_id` + for raised quotas); Search 100 QPS, Fetch 25 QPS plus per-domain. +- Server keep-alive: empty lines (non-stream) or `: keep-alive` (stream); the + server closes after 10 minutes without starting inference. +- Responses is stateless: `previous_response_id`, `conversation`, `store`, + `background`, `include`, `metadata`, `truncation` are not sent. Unknown + input item types are rejected locally (the server would ignore them). +- Anthropic surface: `top_k`, `service_tier`, `container`, `mcp_servers`, + `budget_tokens`, `cache_control` are never sent; unsupported block types are + rejected locally; a `file` image source adds + `anthropic-beta: files-api-2025-04-14`. Claude names map: `claude-opus*` to + `deepseek-v4-pro`, other `claude*` to `deepseek-flash`. +- Model names: legacy `deepseek-v4-flash` and `deepseek-v4-flash-vision-exp` + are accepted by the server and served by `deepseek-flash`; + `deepseek-chat` / `deepseek-reasoner` were announced for discontinuation on + 2026-07-24 (`ModelCatalog`). The live `/models` list is the truth. +- `DeepseekChatModel`: `response_schema` is rejected (use `json_mode`); + `extra.thinking` and `extra.user_id` are lifted into typed fields. +- Deleting a file is `Files::remove`/`AnthropicFiles::remove`, no default. + +## 5. Example routes (`/ai/deepseek`) + +GET `/ai/deepseek` (page), `/status`, `/calls`, `/errors`. POST `/chat`, +`/stream`, `/prefix`, `/tools` (strict optional), `/fim`, `/responses`, +`/anthropic`, `/models`, `/balance`, `/files` (action list, get, upload, +delete), `/search`, `/fetch`. 422 on bad input first; completions, search, +fetch, upload and delete are dry runs showing the exact request unless the body +has `"confirm":true`; then 503 `deepseek_not_configured` without a key; oversize +body 413. + +## Sources + +Fetched 2026-10-24: +- Reference pages (rendered from DeepSeek's private `openapi/openapi.yaml`; the + file itself is not served, `/openapi.json` answers HTML): + `api-docs.deepseek.com/api/{create-chat-completion,create-completion,create-response,list-models,get-user-balance,create-file,list-files,retrieve-file,delete-file,search,fetch}`. +- Guides: `guides/{thinking_mode,tool_calls,json_mode,chat_prefix_completion,fim_completion,kv_cache,multi_round_chat,responses_api,anthropic_api,files_api,vision,search}`, + `quick_start/{error_codes,rate_limit,your_first_api_call,token_usage}`, + `updates` (changelog), site map `sitemap.xml`. +- Unauthenticated probes of the live host (below). +- Cross-check for field names: the reference pages and the guides state each + field twice (request tables and samples); no SDK source was read (Unverified). + +## Verified against spec + +`python3 -I src/deepseek/tools/check_spec.py`, run 2026-10-24: +`deepseek spec ok: 17 calls, 14 schemas, 11 reference pages all covered +(exclusion list: 1)`. Checks that each row's method and path are shown on its +page (beta rows against the non-beta twin plus the beta base URL), that every +body field, query parameter and response field we use is a field of the page, +and that every `/api/*` page found in the site map or the sidebar is a row or +excluded (`api/deepseek-api`, the overview). A mutated table (unknown field, +wrong path) fails the check. The site map lacked `api/search` while its page +was live, so the sidebar links are the second source. Anthropic rows are +checked against the guides' compatibility prose, not against Anthropic's spec. + +## Verified live + +2026-10-24, no key, unauthenticated, from this host: + +| Probe | Result | +|---|---| +| DNS and TLS `api.deepseek.com` | resolves (CloudFront IPs), TLS verifies, HTTP/2 | +| `POST /chat/completions`, `/beta/chat/completions`, `/beta/completions`, `/responses`, `/files`, `/v1/tools/search`, `/v1/tools/fetch`, `/anthropic/v1/messages`, `/anthropic/v1/messages/count_tokens` without a key | 401 (plain text `Authentication Fails (governor)` when no Authorization header) | +| `GET /models`, `/user/balance`, `/files`, `/anthropic/v1/files` without a key | 401 | +| the same GET with a JSON body (`curl -X GET -d`) | 403 CloudFront HTML (a GET with a body is rejected) | +| invalid key on `POST /chat/completions`, `GET /models`, `GET /user/balance`, `POST /anthropic/v1/messages` (x-api-key), `POST /v1/tools/search` | 401 `{"error":{"message":"Authentication Fails, Your api key: ****alid is invalid (request_id: ...)","type":"authentication_error","param":null,"code":"invalid_request_error"}}` (test `deepseek_live.invalid_key_answers_401_with_the_error_envelope`) | +| `POST /nonexistent` | 401 as well: authentication runs before routing, so 401-versus-404 does not prove a path exists | + +Everything else is verified by the published reference only. Rerun the live +tests with `MOLO_LIVE_NET=1 DEEPSEEK_API_KEY=... make ai-test` (read-only: +models, balance, one completion of at most 16 tokens). + +## Unverified + +- Every success response shape was taken from the docs' examples, never seen + live (no key). Tests that feed those fixtures prove our parsing and our + requests, not vendor behavior. +- The Anthropic-compatible response and stream shapes: assumed to be the + standard Anthropic Messages format (the docs only list the compatibility + table). Fixtures for it in the tests are labelled invented. +- Whether a `Bearer` header is also accepted on `/anthropic`; we send `x-api-key`. +- `/anthropic/v1/messages/count_tokens` and `/anthropic/v1/models`: not + documented, not wrapped (probes cannot tell, see the 401 note above). +- Image parts in tool messages: the chat reference allows them in `tool` + messages, the Vision guide says "user messages only". We allow user and tool. +- Strict-mode schema subset beyond the guide's list (for example `format` + values, `$defs` spelling: the guide writes `$def`; both are accepted). +- Error body of 402/422/429/503 (only the 401 body was seen); non-JSON bodies + map to type `UNKNOWN`. +- Exact semantics of `reasoning_effort` aliases (`minimal`, `medium`, `xhigh`, + `ultra`); we only forward them. +- Behavior of a stream interrupted mid-way (no error event is documented). +- The `user_id` field name on chat (docs) versus `user` on Responses (docs). + +## Gaps + +- Pricing and peak/off-peak tables are not wrapped (owner: `account.cpp`, once + a machine-readable source exists). +- No SDK source or OpenAPI file was available to cross-check (DeepSeek ships + neither publicly); the owner of a closing check is `tools/check_spec.py`. +- `Conversation` has no Responses or Anthropic variant; those APIs are + stateless and the caller builds history from `history_items()` / blocks. +- No retry helper: `Errors::wait_seconds` is advice, not a loop. +- `DeepseekChatModel` does not use the Responses API (no `response_schema`). diff --git a/src/deepseek/account.cpp b/src/deepseek/account.cpp new file mode 100644 index 0000000..a28005e --- /dev/null +++ b/src/deepseek/account.cpp @@ -0,0 +1,51 @@ +#include "deepseek/account.h" + +#include "deepseek/calls.h" + +namespace molo::deepseek { + +ModelList Account::models() { + return ModelList::parse(client_->get(Calls::render(Call::kModels))); +} + +Balance Account::balance() { + return Balance::parse(client_->get(Calls::render(Call::kBalance))); +} + +namespace { +constexpr ModelName kModels[] = { + {"deepseek-flash", ModelStatus::kCurrent, "DeepSeek-V4.1-Flash (1017); text and image input", "deepseek-flash"}, + {"deepseek-v4-pro", ModelStatus::kCurrent, "DeepSeek-V4-Pro; text input; server-side web_search in Responses", "deepseek-v4-pro"}, + {"deepseek-v4-flash", ModelStatus::kLegacyAlias, "retired, still accepted, served by deepseek-flash", "deepseek-flash"}, + {"deepseek-v4-flash-vision-exp", ModelStatus::kLegacyAlias, "retired, still accepted, served by deepseek-flash", "deepseek-flash"}, + {"deepseek-chat", ModelStatus::kRetired, "discontinued 2026-07-24 per changelog (was deepseek-v4-flash non-thinking)", "deepseek-flash"}, + {"deepseek-reasoner", ModelStatus::kRetired, "discontinued 2026-07-24 per changelog (was deepseek-v4-flash thinking)", "deepseek-flash"}, +}; +} // namespace + +std::size_t ModelCatalog::count() { return sizeof(kModels) / sizeof(kModels[0]); } + +const ModelName& ModelCatalog::at(std::size_t index) { + if (index >= count()) throw llm::ApiError::invalid("deepseek", "model index out of range"); + return kModels[index]; +} + +ModelStatus ModelCatalog::status_of(const std::string& id) { + for (const ModelName& m : kModels) + if (id == m.id) return m.status; + return ModelStatus::kUnknown; +} + +std::string ModelCatalog::served_as(const std::string& id) { + for (const ModelName& m : kModels) + if (id == m.id) return m.routed_to; + return id; +} + +std::string ModelCatalog::anthropic_mapped(const std::string& id) { + if (id.rfind("claude-opus", 0) == 0) return "deepseek-v4-pro"; + if (id.rfind("claude", 0) == 0) return "deepseek-flash"; + return id; +} + +} // namespace molo::deepseek diff --git a/src/deepseek/account.h b/src/deepseek/account.h new file mode 100644 index 0000000..de91757 --- /dev/null +++ b/src/deepseek/account.h @@ -0,0 +1,46 @@ +#pragma once + +// Read-only account calls (GET /models, GET /user/balance) and the model +// names the docs and the changelog state. The live /models list is the truth; +// the static catalogue only explains names. + +#include + +#include "deepseek/types.h" +#include "llm/api_client.h" + +namespace molo::deepseek { + +class Account : public llm::Service { + public: + explicit Account(std::shared_ptr client) : llm::Service(std::move(client)) {} + ModelList models(); + Balance balance(); +}; + +enum class ModelStatus { kCurrent, kLegacyAlias, kRetired, kUnknown }; + +struct ModelName { + const char* id; + ModelStatus status; + const char* note; + const char* routed_to; // for aliases and retired names +}; + +// Names from the docs (2026-10-24): current deepseek-flash and +// deepseek-v4-pro; deepseek-v4-flash and deepseek-v4-flash-vision-exp still +// accepted but retired (served by deepseek-flash); deepseek-chat and +// deepseek-reasoner announced for discontinuation on 2026-07-24. +struct ModelCatalog { + static std::size_t count(); + static const ModelName& at(std::size_t index); + static ModelStatus status_of(const std::string& id); + // Name the request is served by (alias target), or the id itself. + static std::string served_as(const std::string& id); + // Anthropic-compatible mapping: claude-opus* -> deepseek-v4-pro, other claude* -> + // deepseek-flash, anything else unchanged (the server rejects unknown non-claude names). + static std::string anthropic_mapped(const std::string& id); + static const char* default_model() { return "deepseek-flash"; } +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/anthropic.cpp b/src/deepseek/anthropic.cpp new file mode 100644 index 0000000..745614b --- /dev/null +++ b/src/deepseek/anthropic.cpp @@ -0,0 +1,383 @@ +#include "deepseek/anthropic.h" + +#include + +#include "deepseek/calls.h" +#include "deepseek/caps.h" +#include "deepseek/rules.h" + +namespace molo::deepseek { + +// ---- builders -------------------------------------------------------------- + +Json AnthropicBlocks::text(const std::string& t) { + Json b = Json::object(); + b.set("type", Json("text")); + b.set("text", Json(t)); + return b; +} +static Json image_with(const Json& source) { + Json b = Json::object(); + b.set("type", Json("image")); + b.set("source", source); + return b; +} +Json AnthropicBlocks::image_base64(const std::string& media_type, const std::string& data) { + Json s = Json::object(); + s.set("type", Json("base64")); + s.set("media_type", Json(media_type)); + s.set("data", Json(data)); + return image_with(s); +} +Json AnthropicBlocks::image_url(const std::string& url) { + Json s = Json::object(); + s.set("type", Json("url")); + s.set("url", Json(url)); + return image_with(s); +} +Json AnthropicBlocks::image_file(const std::string& file_id) { + Json s = Json::object(); + s.set("type", Json("file")); + s.set("file_id", Json(file_id)); + return image_with(s); +} +Json AnthropicBlocks::thinking(const std::string& t, const std::string& signature) { + Json b = Json::object(); + b.set("type", Json("thinking")); + b.set("thinking", Json(t)); + if (!signature.empty()) b.set("signature", Json(signature)); + return b; +} +Json AnthropicBlocks::tool_use(const std::string& id, const std::string& name, const Json& input) { + Json b = Json::object(); + b.set("type", Json("tool_use")); + b.set("id", Json(id)); + b.set("name", Json(name)); + b.set("input", input); + return b; +} +Json AnthropicBlocks::tool_result(const std::string& tool_use_id, const std::string& content) { + Json b = Json::object(); + b.set("type", Json("tool_result")); + b.set("tool_use_id", Json(tool_use_id)); + b.set("content", Json(content)); + return b; +} +Json AnthropicBlocks::message(const std::string& role, const std::vector& blocks) { + Json arr = Json::array(); + for (const Json& b : blocks) arr.push(b); + Json m = Json::object(); + m.set("role", Json(role)); + m.set("content", arr); + return m; +} +Json AnthropicBlocks::message_text(const std::string& role, const std::string& t) { + Json m = Json::object(); + m.set("role", Json(role)); + m.set("content", Json(t)); + return m; +} +Json AnthropicBlocks::tool(const std::string& name, const std::string& description, + const Json& input_schema) { + Json t = Json::object(); + t.set("name", Json(name)); + if (!description.empty()) t.set("description", Json(description)); + t.set("input_schema", input_schema); + return t; +} + +// ---- params ---------------------------------------------------------------- + +namespace { +const std::set& supported_blocks() { + static const std::set s = {"text", "image", "thinking", "tool_use", "tool_result", + "server_tool_use", "web_search_tool_result"}; + return s; +} +const std::set& unsupported_blocks() { + static const std::set s = {"document", "search_result", "redacted_thinking", + "code_execution_tool_result", "mcp_tool_use", + "mcp_tool_result", "container_upload"}; + return s; +} +bool media_ok(const std::string& m) { + return m == "image/jpeg" || m == "image/png" || m == "image/gif" || m == "image/webp"; +} + +void check_block(const Json& b) { + Rules::require(b.is_object(), "content block must be an object"); + std::string type = J::str(b, "type"); + Rules::require(unsupported_blocks().count(type) == 0, + "content block '" + type + "' is not supported by the DeepSeek Anthropic endpoint"); + Rules::require(supported_blocks().count(type) == 1, "unknown content block type '" + type + "'"); + if (type == "image") { + const Json* s = J::obj(b, "source"); + Rules::require(s, "image block needs a source"); + std::string st = J::str(*s, "type"); + if (st == "base64") { + Rules::require(media_ok(J::str(*s, "media_type")), "image media_type must be jpeg, png, gif or webp"); + Rules::require(!J::str(*s, "data").empty(), "image data is empty"); + } else if (st == "url") { + Rules::image_url(J::str(*s, "url")); + } else if (st == "file") { + Rules::require(!J::str(*s, "file_id").empty(), "image file_id is empty"); + } else { + Rules::fail("image source type must be base64, url or file"); + } + } else if (type == "tool_use") { + Rules::require(!J::str(b, "id").empty(), "tool_use needs id"); + Rules::tool_name(J::str(b, "name")); + } else if (type == "tool_result") { + Rules::require(!J::str(b, "tool_use_id").empty(), "tool_result needs tool_use_id"); + } +} +} // namespace + +bool MessagesParams::uses_file_image() const { + for (const Json& m : messages.as_array()) { + const Json* c = m.find("content"); + if (!c || !c->is_array()) continue; + for (const Json& b : c->as_array()) + if (J::str(b, "type") == "image") + if (const Json* s = J::obj(b, "source")) + if (J::str(*s, "type") == "file") return true; + } + return false; +} + +void MessagesParams::validate() const { + Rules::model(model); + Rules::require(max_tokens >= 1 && max_tokens <= DeepseekCaps::kMaxTokensCeiling, + "max_tokens must be 1..393216"); + Rules::require(messages.is_array() && !messages.as_array().empty(), "messages must not be empty"); + Rules::require(messages.as_array().size() <= DeepseekCaps::kMaxMessages, "too many messages"); + std::size_t images = 0; + for (const Json& m : messages.as_array()) { + Rules::require(m.is_object(), "message must be an object"); + std::string role = J::str(m, "role"); + Rules::require(role == "user" || role == "assistant", "message role must be user or assistant"); + const Json* c = m.find("content"); + Rules::require(c && (c->is_string() || c->is_array()), "message content must be a string or blocks"); + if (c->is_array()) + for (const Json& b : c->as_array()) { + check_block(b); + if (J::str(b, "type") == "image") ++images; + } + } + Rules::require(images <= DeepseekCaps::kMaxImages, "at most 600 images per request"); + if (!effort.empty()) + Rules::require(effort == "low" || effort == "high" || effort == "max", "effort must be low, high or max"); + if (temperature) Rules::range(*temperature, 0, 2, "temperature"); + if (top_p) Rules::top_p(*top_p); + Rules::stop(stop_sequences); + if (!user_id.empty()) Rules::user_id(user_id); + Rules::require(tools.is_array() && tools.as_array().size() <= DeepseekCaps::kMaxTools, "too many tools"); + std::set names; + for (const Json& t : tools.as_array()) { + Rules::tool_name(J::str(t, "name")); + Rules::require(names.insert(J::str(t, "name")).second, "tool names must be unique"); + Rules::require(J::obj(t, "input_schema"), "tool needs input_schema"); + } + if (!tool_choice.empty()) { + bool mode = tool_choice == "none" || tool_choice == "auto" || tool_choice == "any"; + if (!mode) { + Rules::tool_name(tool_choice); + Rules::require(names.count(tool_choice) == 1, "tool_choice names a tool that is not defined"); + } else if (tool_choice == "any") { + Rules::require(!names.empty(), "tool_choice any needs tools"); + } + } +} + +Json MessagesParams::to_json(bool stream) const { + validate(); + Json b = Json::object(); + b.set("model", Json(model)); + b.set("max_tokens", Json(max_tokens)); + if (!system.empty()) b.set("system", Json(system)); + b.set("messages", messages); + if (thinking) { + Json t = Json::object(); + t.set("type", Json(*thinking ? "enabled" : "disabled")); + b.set("thinking", t); + } + if (!effort.empty()) { + Json o = Json::object(); + o.set("effort", Json(effort)); + b.set("output_config", o); + } + if (!tools.as_array().empty()) b.set("tools", tools); + if (!tool_choice.empty()) { + Json tc = Json::object(); + if (tool_choice == "none" || tool_choice == "auto" || tool_choice == "any") { + tc.set("type", Json(tool_choice)); + } else { + tc.set("type", Json("tool")); + tc.set("name", Json(tool_choice)); + } + b.set("tool_choice", tc); + } + if (!stop_sequences.empty()) { + Json s = Json::array(); + for (const std::string& v : stop_sequences) s.push(Json(v)); + b.set("stop_sequences", s); + } + if (stream) b.set("stream", Json(true)); + if (temperature) b.set("temperature", Json(*temperature)); + if (top_p) b.set("top_p", Json(*top_p)); + if (!user_id.empty()) { + Json m = Json::object(); + m.set("user_id", Json(user_id)); + b.set("metadata", m); + } + return b; +} + +// ---- results --------------------------------------------------------------- + +std::string MessagesResult::text() const { + std::string out; + for (const Json& b : content.as_array()) + if (J::str(b, "type") == "text") out += J::str(b, "text"); + return out; +} +std::string MessagesResult::thinking_text() const { + std::string out; + for (const Json& b : content.as_array()) + if (J::str(b, "type") == "thinking") out += J::str(b, "thinking"); + return out; +} +std::vector MessagesResult::tool_uses() const { + std::vector out; + for (const Json& b : content.as_array()) + if (J::str(b, "type") == "tool_use") { + ToolUse u; + u.id = J::str(b, "id"); + u.name = J::str(b, "name"); + if (const Json* in = b.find("input")) u.input = *in; + out.push_back(u); + } + return out; +} + +MessagesResult MessagesResult::parse(const Json& doc) { + if (!doc.is_object()) throw llm::ApiError("deepseek", 502, "BAD_RESPONSE", "response is not an object"); + MessagesResult r; + r.raw = doc; + r.id = J::str(doc, "id"); + r.type = J::str(doc, "type"); + r.role = J::str(doc, "role"); + r.model = J::str(doc, "model"); + r.stop_reason = J::str(doc, "stop_reason"); + r.stop_sequence = J::str(doc, "stop_sequence"); + if (const Json* c = J::arr(doc, "content")) r.content = *c; + r.usage = TokenUsage::from_anthropic(doc.find("usage")); + return r; +} + +std::string MessagesStreamAccumulator::feed(const llm::SseEvent& ev) { + if (++events_ > DeepseekCaps::kMaxStreamEvents) + throw llm::ApiError("deepseek", 502, "BAD_RESPONSE", "stream over the event cap"); + const Json& d = ev.data; + std::string type = J::str(d, "type", ev.event); + std::string text; + if (type == "message_start") { + if (const Json* m = J::obj(d, "message")) { + MessagesResult head = MessagesResult::parse(*m); + head.content = Json::array(); + result_ = head; + } + } else if (type == "content_block_start") { + std::size_t idx = static_cast(J::num(d, "index")); + if (idx >= DeepseekCaps::kMaxMessages) throw llm::ApiError("deepseek", 502, "BAD_RESPONSE", "block index out of range"); + const Json* b = J::obj(d, "content_block"); + if (b) { + auto& arr = result_.content.as_array(); + while (arr.size() <= idx) arr.push_back(Json::object()); + arr[idx] = *b; + if (partial_json_.size() <= idx) partial_json_.resize(idx + 1); + } + } else if (type == "content_block_delta") { + std::size_t idx = static_cast(J::num(d, "index")); + auto& arr = result_.content.as_array(); + const Json* delta = J::obj(d, "delta"); + if (delta && idx < arr.size() && arr[idx].is_object()) { + Json& block = arr[idx]; + std::string dt = J::str(*delta, "type"); + if (dt == "text_delta") { + text = J::str(*delta, "text"); + block.set("text", Json(J::str(block, "text") + text)); + } else if (dt == "thinking_delta") { + block.set("thinking", Json(J::str(block, "thinking") + J::str(*delta, "thinking"))); + } else if (dt == "signature_delta") { + block.set("signature", Json(J::str(*delta, "signature"))); + } else if (dt == "input_json_delta") { + if (partial_json_.size() <= idx) partial_json_.resize(idx + 1); + partial_json_[idx] += J::str(*delta, "partial_json"); + } + } + } else if (type == "content_block_stop") { + std::size_t idx = static_cast(J::num(d, "index")); + auto& arr = result_.content.as_array(); + if (idx < arr.size() && idx < partial_json_.size() && !partial_json_[idx].empty()) { + try { + arr[idx].set("input", Json::parse(partial_json_[idx])); + } catch (const std::exception&) { + arr[idx].set("input_invalid_json", Json(partial_json_[idx])); + } + } + } else if (type == "message_delta") { + if (const Json* delta = J::obj(d, "delta")) { + std::string sr = J::str(*delta, "stop_reason"); + if (!sr.empty()) result_.stop_reason = sr; + std::string ss = J::str(*delta, "stop_sequence"); + if (!ss.empty()) result_.stop_sequence = ss; + } + if (const Json* u = J::obj(d, "usage")) { + TokenUsage add = TokenUsage::from_anthropic(u); + if (add.output_tokens) result_.usage.output_tokens = add.output_tokens; + if (add.input_tokens) result_.usage.input_tokens = add.input_tokens; + result_.usage.total_tokens = result_.usage.input_tokens + result_.usage.output_tokens; + result_.usage.present = true; + } + } else if (type == "message_stop") { + done_ = true; + } else if (type == "error") { + const Json* e = J::obj(d, "error"); + throw llm::ApiError("deepseek", 502, e ? J::str(*e, "type", "stream_error") : "stream_error", + e ? J::str(*e, "message") : "stream error event"); + } + return text; +} + +MessagesResult MessagesStreamAccumulator::result() const { return result_; } + +MessagesResult AnthropicMessages::create(const MessagesParams& params) { + Json body = params.to_json(false); + llm::Headers extra; + if (params.uses_file_image()) extra["anthropic-beta"] = Calls::anthropic_files_beta(); + return MessagesResult::parse(client_->post(Calls::render(Call::kMessages), body, extra)); +} + +MessagesResult AnthropicMessages::stream( + const MessagesParams& params, + const std::function& on_event) { + Json body = params.to_json(true); + llm::Headers extra; + if (params.uses_file_image()) extra["anthropic-beta"] = Calls::anthropic_files_beta(); + MessagesStreamAccumulator acc; + bool stopped = false; + client_->stream(Calls::render(Call::kMessages), body, [&](const llm::SseEvent& ev) { + std::string text = acc.feed(ev); + if (on_event && !on_event(ev, text)) { + stopped = true; + return false; + } + return true; + }, extra); + if (!acc.done() && !stopped) + throw llm::ApiError("deepseek", 502, "STREAM_TRUNCATED", "stream ended without message_stop"); + return acc.result(); +} + +} // namespace molo::deepseek diff --git a/src/deepseek/anthropic.h b/src/deepseek/anthropic.h new file mode 100644 index 0000000..d55b0ae --- /dev/null +++ b/src/deepseek/anthropic.h @@ -0,0 +1,99 @@ +#pragma once + +// Anthropic-compatible endpoint: POST /anthropic/v1/messages, auth header +// x-api-key. The compatibility table of the Anthropic API guide decides what +// is sent: top_k, service_tier, container, mcp_servers are ignored (not sent); +// document, search_result, redacted_thinking, code_execution_tool_result, +// mcp_tool_use, mcp_tool_result and container_upload blocks are not supported +// (rejected locally); thinking.budget_tokens is ignored (never sent); +// output_config carries only effort; metadata carries only user_id. An image +// block with source.type "file" needs anthropic-beta: files-api-2025-04-14 +// (added automatically). Claude model names are mapped by the server. + +#include +#include +#include +#include + +#include "deepseek/types.h" +#include "llm/api_client.h" + +namespace molo::deepseek { + +struct AnthropicBlocks { + static Json text(const std::string& text); + // media_type: image/jpeg, image/png, image/gif, image/webp + static Json image_base64(const std::string& media_type, const std::string& base64_data); + static Json image_url(const std::string& url); + static Json image_file(const std::string& file_id); + static Json thinking(const std::string& thinking, const std::string& signature = ""); + static Json tool_use(const std::string& id, const std::string& name, const Json& input); + static Json tool_result(const std::string& tool_use_id, const std::string& content); + static Json message(const std::string& role, const std::vector& blocks); + static Json message_text(const std::string& role, const std::string& text); + static Json tool(const std::string& name, const std::string& description, const Json& input_schema); +}; + +struct MessagesParams { + std::string model = "deepseek-flash"; // claude-opus* -> deepseek-v4-pro, claude-* -> deepseek-flash + int max_tokens = 1024; // required by the Anthropic format + std::string system; + Json messages = Json::array(); + std::optional thinking; // enabled / disabled; budget_tokens ignored upstream + std::string effort; // output_config.effort: low, high, max + Json tools = Json::array(); // {name, description, input_schema} + std::string tool_choice; // "", none, auto, any, or a tool name + std::vector stop_sequences; + std::optional temperature; // 0..2 + std::optional top_p; + std::string user_id; // metadata.user_id + + void add(const Json& message) { messages.push(message); } + void validate() const; + bool uses_file_image() const; + Json to_json(bool stream = false) const; +}; + +struct MessagesResult { + std::string id, type, role, model, stop_reason, stop_sequence; + Json content = Json::array(); + TokenUsage usage; + Json raw; + std::string text() const; + std::string thinking_text() const; + struct ToolUse { + std::string id, name; + Json input; + }; + std::vector tool_uses() const; + static MessagesResult parse(const Json& doc); +}; + +// Folds Anthropic stream events (message_start, content_block_start / +// delta / stop, message_delta, message_stop, ping, error) into a result. +class MessagesStreamAccumulator { + public: + // Returns the text delta of this event (empty for non-text events). Throws + // ApiError on an `error` event. + std::string feed(const llm::SseEvent& event); + bool done() const { return done_; } + MessagesResult result() const; + + private: + MessagesResult result_; + std::vector partial_json_; // per content block index + std::size_t events_ = 0; + bool done_ = false; +}; + +class AnthropicMessages : public llm::Service { + public: + explicit AnthropicMessages(std::shared_ptr client) + : llm::Service(std::move(client)) {} + MessagesResult create(const MessagesParams& params); + // on_event sees every decoded event (false stops); returns the folded result. + MessagesResult stream(const MessagesParams& params, + const std::function& on_event); +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/calls.cpp b/src/deepseek/calls.cpp new file mode 100644 index 0000000..eecb194 --- /dev/null +++ b/src/deepseek/calls.cpp @@ -0,0 +1,92 @@ +#include "deepseek/calls.h" + +#include + +#include "llm/api_client.h" +#include "llm/error.h" + +namespace molo::deepseek { + +// CALLS-BEGIN (parsed by tools/check_spec.py; one row per line, strings in order: +// http method, path, doc page, body fields, query params, response schema) +static const CallSpec kCalls[] = { + {Call::kChat, Surface::kOpenai, "POST", "/chat/completions", "api/create-chat-completion", "messages,model,thinking,reasoning_effort,max_tokens,response_format,stop,stream,stream_options,temperature,top_p,tools,tool_choice,logprobs,top_logprobs,user_id", "", "ChatCompletion"}, + {Call::kChatBeta, Surface::kOpenai, "POST", "/beta/chat/completions", "api/create-chat-completion", "messages,model,thinking,reasoning_effort,max_tokens,response_format,stop,stream,stream_options,temperature,top_p,tools,tool_choice,logprobs,top_logprobs,user_id,prefix,reasoning_content,strict", "", "ChatCompletion"}, + {Call::kFim, Surface::kOpenai, "POST", "/beta/completions", "api/create-completion", "model,prompt,echo,logprobs,max_tokens,stop,stream,stream_options,suffix,temperature,top_p", "", "Completion"}, + {Call::kResponses, Surface::kOpenai, "POST", "/responses", "api/create-response", "model,input,instructions,reasoning,max_output_tokens,stream,temperature,top_p,text,tools,tool_choice,top_logprobs,user", "", "Response"}, + {Call::kModels, Surface::kOpenai, "GET", "/models", "api/list-models", "", "", "ModelList"}, + {Call::kBalance, Surface::kOpenai, "GET", "/user/balance", "api/get-user-balance", "", "", "Balance"}, + {Call::kFileCreate, Surface::kOpenai, "POST", "/files", "api/create-file", "file,purpose,expires_after[anchor],expires_after[seconds]", "", "File"}, + {Call::kFileList, Surface::kOpenai, "GET", "/files", "api/list-files", "", "after,limit,order,purpose", "FileList"}, + {Call::kFileGet, Surface::kOpenai, "GET", "/files/{file_id}", "api/retrieve-file", "", "", "File"}, + {Call::kFileDelete, Surface::kOpenai, "DELETE", "/files/{file_id}", "api/delete-file", "", "", "FileDeleted"}, + {Call::kSearch, Surface::kOpenai, "POST", "/v1/tools/search", "api/search", "query,count,ori_question,localization,need_content", "", "SearchResults"}, + {Call::kFetch, Surface::kOpenai, "POST", "/v1/tools/fetch", "api/fetch", "url", "", "FetchResult"}, + {Call::kMessages, Surface::kAnthropic, "POST", "/anthropic/v1/messages", "guides/anthropic_api", "model,max_tokens,system,messages,stop_sequences,stream,temperature,thinking,output_config,top_p,tools,tool_choice,metadata", "", "AnthropicMessage"}, + {Call::kAnthropicFileCreate, Surface::kAnthropic, "POST", "/anthropic/v1/files", "guides/files_api", "file", "", "AnthropicFile"}, + {Call::kAnthropicFileList, Surface::kAnthropic, "GET", "/anthropic/v1/files", "guides/files_api", "", "limit,after_id,before_id", "AnthropicFileList"}, + {Call::kAnthropicFileGet, Surface::kAnthropic, "GET", "/anthropic/v1/files/{file_id}", "guides/files_api", "", "", "AnthropicFile"}, + {Call::kAnthropicFileDelete, Surface::kAnthropic, "DELETE", "/anthropic/v1/files/{file_id}", "guides/files_api", "", "", "AnthropicFileDeleted"}, +}; +// CALLS-END + +// SCHEMAS-BEGIN (parsed by tools/check_spec.py; one row per line: schema, doc, fields) +static const SchemaFields kSchemas[] = { + {"ChatCompletion", "api/create-chat-completion", "id,choices,created,model,system_fingerprint,object,usage,finish_reason,index,message,logprobs,content,reasoning_content,tool_calls,role,delta,completion_tokens,prompt_tokens,prompt_tokens_details,cached_tokens,prompt_cache_hit_tokens,prompt_cache_miss_tokens,total_tokens,completion_tokens_details,reasoning_tokens"}, + {"Completion", "api/create-completion", "id,choices,created,model,system_fingerprint,object,usage,finish_reason,index,logprobs,text,text_offset,token_logprobs,tokens,top_logprobs,prompt_cache_hit_tokens,prompt_cache_miss_tokens"}, + {"Response", "api/create-response", "id,object,created_at,status,error,incomplete_details,model,output,usage,call_id,name,arguments,content,role,input_tokens,input_tokens_details,cached_tokens,output_tokens,output_tokens_details,reasoning_tokens,total_tokens"}, + {"ModelList", "api/list-models", "object,data,id,owned_by,name,context_window,max_output_tokens,input_modalities,output_modalities,effort,supported_levels,default_level,api_capabilities,anthropic_messages,system_prompt_update"}, + {"Balance", "api/get-user-balance", "is_available,balance_infos,currency,total_balance,granted_balance,topped_up_balance"}, + {"File", "api/create-file", "id,object,bytes,created_at,filename,purpose,expires_at"}, + {"FileList", "api/list-files", "object,data,first_id,last_id,has_more"}, + {"FileDeleted", "api/delete-file", "id,object,deleted"}, + {"SearchResults", "api/search", "results,rerank_score,title,url,snippet,summary,content,site_name,site_icon,date,authority"}, + {"FetchResult", "api/fetch", "title,content"}, + {"AnthropicMessage", "guides/anthropic_api", "model,max_tokens,system,messages,stop_sequences,stream,temperature,thinking,output_config,top_p,tools,tool_choice,metadata,user_id"}, + {"AnthropicFile", "guides/files_api", "id,type,size_bytes,created_at,filename,mime_type"}, + {"AnthropicFileList", "guides/files_api", "data,first_id,last_id,has_more"}, + {"AnthropicFileDeleted", "guides/files_api", "id,type"}, +}; +// SCHEMAS-END + +const CallSpec& Calls::spec_of(Call call) { + for (const CallSpec& s : kCalls) + if (s.call == call) return s; + throw llm::ApiError::invalid("deepseek", "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; + 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("deepseek", "call index out of range"); + return kCalls[index]; +} + +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("deepseek", "schema index out of range"); + return kSchemas[index]; +} + +std::string Calls::render(Call call, const std::string& id) { + std::string path = spec_of(call).path; + auto at = path.find("{file_id}"); + if (at != std::string::npos) { + if (!llm::Service::valid_id(id)) throw llm::ApiError::invalid("deepseek", "bad file id"); + path.replace(at, std::strlen("{file_id}"), id); + } + return path; +} + +const char* Calls::anthropic_files_beta() { return "files-api-2025-04-14"; } + +} // namespace molo::deepseek diff --git a/src/deepseek/calls.h b/src/deepseek/calls.h new file mode 100644 index 0000000..b256d7d --- /dev/null +++ b/src/deepseek/calls.h @@ -0,0 +1,58 @@ +#pragma once + +// The ONE table of REST calls this module makes. tools/check_spec.py checks +// every row against DeepSeek's published API reference (the pages rendered +// from their OpenAPI document) and the guides. Code builds every path from +// this table, never from a literal. + +#include +#include + +#include "clients/request.h" + +namespace molo::deepseek { + +// Which ApiClient serves the row: OpenAI-compatible surface (Bearer) or the +// Anthropic-compatible surface (x-api-key). Beta rows live under /beta on the +// OpenAI-compatible surface. +enum class Surface { kOpenai, kAnthropic }; + +enum class Call { + kChat, kChatBeta, kFim, kResponses, kModels, kBalance, + kFileCreate, kFileList, kFileGet, kFileDelete, + kSearch, kFetch, + kMessages, + kAnthropicFileCreate, kAnthropicFileList, kAnthropicFileGet, kAnthropicFileDelete, +}; + +struct CallSpec { + Call call; + Surface surface; + const char* http_method; // GET POST DELETE + const char* path; // full path from the host, "{file_id}" placeholder + const char* doc; // reference page ("api/...") or guide ("guides/...") + const char* body_fields; // comma list: request body fields we send + const char* query_params; // comma list: query parameters we send + const char* response; // response schema name in the schema table +}; + +struct SchemaFields { + const char* schema; + const char* doc; + const char* fields; // comma list: fields we read +}; + +struct Calls { + 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); + static std::size_t schema_count(); + static const SchemaFields& schema_at(std::size_t index); + // Path with {file_id} replaced by a validated id (llm::Service::valid_id). + static std::string render(Call call, const std::string& id = ""); + // Header the Anthropic-compatible Files endpoints require. + static const char* anthropic_files_beta(); +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/caps.h b/src/deepseek/caps.h new file mode 100644 index 0000000..f779051 --- /dev/null +++ b/src/deepseek/caps.h @@ -0,0 +1,41 @@ +#pragma once + +// Static ceilings for the DeepSeek module. Never autotuned. Numbers come from +// the published reference (see SPEC.md ## Sources) or are our own hard caps. + +#include + +namespace molo::deepseek { + +struct DeepseekCaps { + // Documented limits. + static constexpr int kMaxTokensCeiling = 393216; // max_tokens 1..384K + static constexpr int kFimMaxTokens = 4096; // "max tokens of FIM completion is 4K" + static constexpr std::size_t kMaxStopSequences = 16; + static constexpr int kMaxTopLogprobs = 20; + static constexpr std::size_t kMaxToolNameChars = 128; + static constexpr std::size_t kMaxUserIdChars = 512; + static constexpr std::size_t kMaxImageUrlChars = 8192; + static constexpr std::size_t kMaxImages = 600; // per request + static constexpr std::size_t kMaxUploadBytes = 64u * 1024u * 1024u; + static constexpr std::size_t kMaxFilenameBytes = 512; + static constexpr long kExpireMinSeconds = 3600; + static constexpr long kExpireMaxSeconds = 2592000; + static constexpr int kFilesMaxLimit = 1000; + static constexpr int kAnthropicFilesDefaultLimit = 20; + static constexpr std::size_t kSearchQueryChars = 128; + static constexpr int kSearchMaxCount = 50; + static constexpr std::size_t kFetchUrlChars = 8192; + // Our own caps. + static constexpr std::size_t kMaxMessages = 4096; + static constexpr std::size_t kMaxTools = 128; + static constexpr std::size_t kMaxStreamEvents = 200000; + static constexpr std::size_t kMaxChoices = 8; + static constexpr std::size_t kMaxFilePages = 20; // list walks + static constexpr std::size_t kMaxFilesReturned = 5000; + static constexpr std::size_t kMaxModelsReturned = 256; + static constexpr std::size_t kMaxSchemaDepth = 16; + static constexpr std::size_t kMaxModelChars = 128; +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/chat.cpp b/src/deepseek/chat.cpp new file mode 100644 index 0000000..41397a1 --- /dev/null +++ b/src/deepseek/chat.cpp @@ -0,0 +1,87 @@ +#include "deepseek/chat.h" + +#include "deepseek/rules.h" + +namespace molo::deepseek { + +Call Chat::call_for(const ChatParams& params) { + return params.needs_beta() ? Call::kChatBeta : Call::kChat; +} + +ChatResult Chat::create(const ChatParams& params) { + Json body = params.to_json(false); + Json doc = client_->post(Calls::render(call_for(params)), body); + return ChatResult::parse(doc); +} + +ChatResult Chat::stream(const ChatParams& params, const DeltaSink& on_delta) { + Json body = params.to_json(true); + ChatStreamAccumulator acc; + bool stopped = false; + client_->stream(Calls::render(call_for(params)), body, [&](const llm::SseEvent& ev) { + StreamDelta d = acc.feed(ev.data); + if (on_delta && !on_delta(d)) { + stopped = true; + return false; + } + return true; + }); + if (!stopped && !acc.done()) + throw llm::ApiError("deepseek", 502, "STREAM_TRUNCATED", "stream ended without a finish_reason"); + return acc.result(); +} + +ChatResult Chat::prefix(ChatParams params, const std::string& prefix, const std::string& reasoning) { + Rules::require(!prefix.empty(), "prefix must not be empty"); + params.add(Messages::assistant_prefix(prefix, reasoning)); + return create(params); +} + +Conversation& Conversation::system(const std::string& text) { + params_.add(Messages::system(text)); + return *this; +} +Conversation& Conversation::user(const std::string& text) { + params_.add(Messages::user(text)); + return *this; +} +Conversation& Conversation::tool_result(const std::string& call_id, const std::string& content) { + params_.add(Messages::tool(call_id, content)); + return *this; +} + +void Conversation::absorb(const ChatResult& result) { + params_.add(result.first().history_message()); +} + +ChatResult Conversation::send(Chat& chat) { + ChatResult r = chat.create(params_); + absorb(r); + return r; +} + +ChatResult Conversation::send_stream(Chat& chat, const Chat::DeltaSink& on_delta) { + ChatResult r = chat.stream(params_, on_delta); + if (!r.choices.empty()) absorb(r); + return r; +} + +ChatResult Conversation::run_tools(Chat& chat, const ToolHandler& handler, int max_rounds) { + Rules::require(max_rounds >= 1 && max_rounds <= kMaxToolRounds, "max_rounds must be 1..16"); + Rules::require(!params_.tools.empty(), "run_tools needs tools"); + ChatResult r; + for (int round = 0; round < max_rounds; ++round) { + r = send(chat); + const ChatChoice& c = r.first(); + if (c.tool_calls.empty()) return r; + for (const ToolCallRecord& call : c.tool_calls) { + if (!call.arguments_valid()) + throw llm::ApiError("deepseek", 502, "BAD_TOOL_ARGUMENTS", + "tool call '" + call.name + "' has invalid JSON arguments"); + tool_result(call.id, handler(call.name, call.parsed(), call.id)); + } + } + throw llm::ApiError::invalid("deepseek", "tool loop hit the round cap with calls still pending"); +} + +} // namespace molo::deepseek diff --git a/src/deepseek/chat.h b/src/deepseek/chat.h new file mode 100644 index 0000000..9070609 --- /dev/null +++ b/src/deepseek/chat.h @@ -0,0 +1,67 @@ +#pragma once + +// Chat Completions over the OpenAI-compatible surface: POST /chat/completions, +// or POST /beta/chat/completions when the request uses a prefix message or +// strict tools (ChatParams::needs_beta). Plus Conversation, the history keeper +// that applies the reasoning_content rule across turns. + +#include + +#include "deepseek/calls.h" +#include "deepseek/chat_params.h" +#include "deepseek/chat_result.h" +#include "llm/api_client.h" + +namespace molo::deepseek { + +class Chat : public llm::Service { + public: + explicit Chat(std::shared_ptr client) : llm::Service(std::move(client)) {} + + ChatResult create(const ChatParams& params); + + using DeltaSink = std::function; // false: stop early + // Streams chunks; returns the folded result. A stream that ends without a + // finish_reason (and was not stopped by the sink) throws 502 STREAM_TRUNCATED. + ChatResult stream(const ChatParams& params, const DeltaSink& on_delta); + + // Beta chat prefix completion: appends an assistant prefix message to a copy + // of `params` and calls the beta endpoint. `stop` is usually the closing fence. + ChatResult prefix(ChatParams params, const std::string& prefix, + const std::string& reasoning = ""); + + static Call call_for(const ChatParams& params); +}; + +class Conversation { + public: + static constexpr int kMaxToolRounds = 16; // hard cap for run_tools + + explicit Conversation(ChatParams base) : params_(std::move(base)) {} + + Conversation& system(const std::string& text); + Conversation& user(const std::string& text); + // Result of a tool call the model requested. + Conversation& tool_result(const std::string& call_id, const std::string& content); + + // One request. The assistant message (with reasoning_content and tool_calls + // exactly as returned) is appended to the history; ChatParams keeps or drops + // the reasoning on later requests according to the tools rule. + ChatResult send(Chat& chat); + ChatResult send_stream(Chat& chat, const Chat::DeltaSink& on_delta); + + // handler(tool name, parsed arguments, call id) -> tool output text. Loops + // while the model asks for tools, at most `max_rounds` requests (<= kMaxToolRounds); + // throws when a call has invalid JSON arguments or the cap is hit with calls pending. + using ToolHandler = std::function; + ChatResult run_tools(Chat& chat, const ToolHandler& handler, int max_rounds = 8); + + const ChatParams& params() const { return params_; } + ChatParams& params() { return params_; } + + private: + void absorb(const ChatResult& result); + ChatParams params_; +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/chat_model.cpp b/src/deepseek/chat_model.cpp new file mode 100644 index 0000000..6d4774a --- /dev/null +++ b/src/deepseek/chat_model.cpp @@ -0,0 +1,199 @@ +#include "deepseek/chat_model.h" + +#include + +#include "deepseek/platform.h" +#include "deepseek/rules.h" +#include "security/crypto/Base64.h" + +namespace molo::deepseek { + +DeepseekChatModel::DeepseekChatModel(std::shared_ptr chat, std::string default_model) + : chat_(std::move(chat)), default_model_(std::move(default_model)) {} + +std::shared_ptr DeepseekChatModel::from_env(const std::string& default_model) { + Platform p = Platform::from_env(); + return std::make_shared(std::make_shared(p.openai), 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)); +} + +std::string call_arguments(const llm::ToolCall& call) { + return call.arguments.is_null() ? "{}" : call.arguments.dump(); +} + +void append(ChatParams& params, const llm::Message& m) { + switch (m.role) { + case llm::Role::kSystem: + params.add(Messages::system(m.text(), m.name)); + return; + case llm::Role::kUser: { + bool has_image = false; + for (const llm::ContentPart& p : m.parts) has_image = has_image || p.image.has_value(); + if (!has_image) { + params.add(Messages::user(m.text(), m.name)); + 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::user_parts(parts, m.name)); + return; + } + case llm::Role::kAssistant: { + std::string reasoning; + Json calls = Json::array(); + for (const llm::ContentPart& p : m.parts) { + reasoning += p.reasoning; + if (p.tool_call) + calls.push(Messages::tool_call(p.tool_call->id, p.tool_call->name, call_arguments(*p.tool_call))); + } + params.add(Messages::assistant(m.text(), reasoning, calls)); + return; + } + case llm::Role::kTool: { + bool any = false; + for (const llm::ContentPart& p : m.parts) + if (p.tool_result) { + params.add(Messages::tool(p.tool_result->call_id, p.tool_result->content)); + any = true; + } + Rules::require(any, "a tool message needs a tool result part"); + return; + } + } +} + +llm::Usage usage_of(const TokenUsage& u) { + llm::Usage out; + out.input_tokens = u.input_tokens; + out.output_tokens = u.output_tokens; + out.total_tokens = u.total_tokens; + out.cached_tokens = u.cache_hit_tokens; + out.reasoning_tokens = u.reasoning_tokens; + return out; +} + +Json arguments_of(const ToolCallRecord& call) { + if (call.arguments_valid()) { + Json j = call.parsed(); + if (j.is_object()) return j; + } + Json bad = Json::object(); + bad.set("_invalid_json", Json(call.arguments)); + return bad; +} + +} // namespace + +ChatParams DeepseekChatModel::to_params(const llm::ChatRequest& r) const { + Rules::require(r.response_schema.is_null(), + "response_schema is not supported on DeepSeek chat completions; use json_mode"); + ChatParams 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); + for (const llm::ToolSpec& t : r.tools) { + ToolDef d; + d.name = t.name; + d.description = t.description; + d.parameters = t.parameters; + p.tools.push_back(d); + } + p.tool_choice = r.tool_choice; + p.max_tokens = r.max_tokens; + p.temperature = r.temperature; + p.top_p = r.top_p; + p.stop = r.stop; + p.json_mode = r.json_mode; + p.reasoning_effort = r.reasoning_effort; + if (r.extra.is_object()) { + Json rest = Json::object(); + for (const auto& [k, v] : r.extra.as_object()) { + if (k == "thinking" && v.is_object()) { + std::string type = J::str(v, "type"); + Rules::require(type == "enabled" || type == "disabled", "thinking.type must be enabled or disabled"); + p.thinking = type == "enabled" ? Thinking::kEnabled : Thinking::kDisabled; + } else if (k == "user_id" && v.is_string()) { + p.user_id = v.as_string(); + } else { + rest.set(k, v); + } + } + p.extra = rest; + } + return p; +} + +llm::ChatResponse DeepseekChatModel::to_response(const ChatResult& result) { + const ChatChoice& c = result.first(); + llm::ChatResponse out; + out.id = result.id; + out.model = result.model; + out.message.role = llm::Role::kAssistant; + if (!c.reasoning_content.empty()) { + llm::ContentPart r; + r.reasoning = c.reasoning_content; + out.message.parts.push_back(r); + } + if (!c.content.empty() || c.tool_calls.empty()) + out.message.parts.push_back(llm::ContentPart::of_text(c.content)); + for (const ToolCallRecord& call : c.tool_calls) { + llm::ToolCall tc; + tc.id = call.id; + tc.name = call.name; + tc.arguments = arguments_of(call); + out.message.parts.push_back(llm::ContentPart::of_call(tc)); + } + out.finish_reason = c.finish_reason; + out.usage = usage_of(result.usage); + out.raw = result.raw; + return out; +} + +llm::ChatResponse DeepseekChatModel::generate(const llm::ChatRequest& request) { + return to_response(chat_->create(to_params(request))); +} + +void DeepseekChatModel::stream(const llm::ChatRequest& request, + const std::function& on_chunk) { + ChatParams params = to_params(request); + std::map ids; // tool index -> call id, so later fragments carry it + std::map names; + chat_->stream(params, [&](const StreamDelta& d) { + auto emit = [&](const llm::ChatChunk& c) { return on_chunk(c); }; + if (!d.content.empty() || !d.reasoning.empty()) { + llm::ChatChunk c; + c.text_delta = d.content; + c.reasoning_delta = d.reasoning; + if (!emit(c)) return false; + } + for (const StreamDelta::ToolFragment& f : d.tools) { + if (!f.id.empty()) ids[f.index] = f.id; + if (!f.name.empty()) names[f.index] = f.name; + llm::ChatChunk c; + c.tool_call_id = ids[f.index]; + c.tool_call_name = names[f.index]; + c.tool_args_delta = f.arguments_delta; + if (!emit(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); + if (!emit(c)) return false; + } + return true; + }); +} + +} // namespace molo::deepseek diff --git a/src/deepseek/chat_model.h b/src/deepseek/chat_model.h new file mode 100644 index 0000000..ed590d1 --- /dev/null +++ b/src/deepseek/chat_model.h @@ -0,0 +1,44 @@ +#pragma once + +// DeepseekChatModel: the llm::ChatModel seam over Chat Completions. +// +// Mapping notes (each one is a decision, not a guess): +// - ContentPart.reasoning of an assistant message is sent back as +// reasoning_content ONLY when the request carries tools (DeepSeek answers +// 400 otherwise); ChatParams drops it for tool-less requests. +// - ChatRequest.reasoning_effort goes to reasoning_effort ("none" turns +// thinking off); ChatRequest.extra may hold {"thinking":{"type":...}}. +// - response_schema is not supported on chat completions (strict mode lives +// on tools): the call is rejected loudly, use json_mode or Responses. +// - Tool call arguments that are not valid JSON arrive as +// {"_invalid_json": ""} instead of being dropped. +// - finish_reason is passed through (stop, length, tool_calls, content_filter, +// insufficient_system_resource, aborted). + +#include + +#include "deepseek/chat.h" +#include "llm/chat_types.h" + +namespace molo::deepseek { + +class DeepseekChatModel : public llm::ChatModel { + public: + explicit DeepseekChatModel(std::shared_ptr chat, std::string default_model = "deepseek-flash"); + static std::shared_ptr from_env(const std::string& default_model = "deepseek-flash"); + + std::string vendor() const override { return "deepseek"; } + 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). + ChatParams to_params(const llm::ChatRequest& request) const; + static llm::ChatResponse to_response(const ChatResult& result); + + private: + std::shared_ptr chat_; + std::string default_model_; +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/chat_params.cpp b/src/deepseek/chat_params.cpp new file mode 100644 index 0000000..a369516 --- /dev/null +++ b/src/deepseek/chat_params.cpp @@ -0,0 +1,430 @@ +#include "deepseek/chat_params.h" + +#include +#include + +#include "deepseek/caps.h" +#include "deepseek/rules.h" + +namespace molo::deepseek { + +// ---- message builders ------------------------------------------------------ + +static Json named(const char* role, const std::string& text, const std::string& name) { + Json m = Json::object(); + m.set("role", Json(role)); + m.set("content", Json(text)); + if (!name.empty()) m.set("name", Json(name)); + return m; +} + +Json Messages::system(const std::string& text, const std::string& name) { + return named("system", text, name); +} +Json Messages::user(const std::string& text, const std::string& name) { + return named("user", text, name); +} +Json Messages::user_parts(const std::vector& parts, const std::string& name) { + Json arr = Json::array(); + for (const Json& p : parts) arr.push(p); + Json m = Json::object(); + m.set("role", Json("user")); + m.set("content", arr); + if (!name.empty()) m.set("name", Json(name)); + 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, const std::string& detail) { + Json img = Json::object(); + img.set("url", Json(url)); + if (!detail.empty()) img.set("detail", Json(detail)); + Json p = Json::object(); + p.set("type", Json("image_url")); + p.set("image_url", img); + return p; +} +Json Messages::file_part(const std::string& file_id) { + Json p = Json::object(); + p.set("type", Json("file")); + p.set("file_id", Json(file_id)); + return p; +} +Json Messages::file_data_part(const std::string& data_url, const std::string& filename) { + Json p = Json::object(); + p.set("type", Json("file")); + p.set("file_data", Json(data_url)); + if (!filename.empty()) p.set("filename", Json(filename)); + return p; +} +Json Messages::assistant(const std::string& content, const std::string& reasoning, + const Json& tool_calls) { + Json m = Json::object(); + m.set("role", Json("assistant")); + m.set("content", Json(content)); + if (!reasoning.empty()) m.set("reasoning_content", Json(reasoning)); + if (tool_calls.is_array() && !tool_calls.as_array().empty()) m.set("tool_calls", tool_calls); + return m; +} +Json Messages::assistant_prefix(const std::string& prefix, const std::string& reasoning) { + Json m = assistant(prefix, reasoning); + m.set("prefix", Json(true)); + return m; +} +Json Messages::tool(const std::string& call_id, const std::string& content) { + Json m = Json::object(); + m.set("role", Json("tool")); + m.set("tool_call_id", Json(call_id)); + m.set("content", Json(content)); + return m; +} +Json Messages::tool_parts(const std::string& call_id, const std::vector& parts) { + Json arr = Json::array(); + for (const Json& p : parts) arr.push(p); + Json m = Json::object(); + m.set("role", Json("tool")); + m.set("tool_call_id", Json(call_id)); + m.set("content", arr); + return m; +} +Json Messages::tool_call(const std::string& id, const std::string& name, + const std::string& arguments) { + Json fn = Json::object(); + fn.set("name", Json(name)); + fn.set("arguments", Json(arguments)); + Json c = Json::object(); + c.set("id", Json(id)); + c.set("type", Json("function")); + c.set("function", fn); + return c; +} + +Json ToolDef::to_json() const { + Json fn = Json::object(); + fn.set("name", Json(name)); + if (!description.empty()) fn.set("description", Json(description)); + fn.set("parameters", parameters); + if (strict) fn.set("strict", Json(true)); + Json t = Json::object(); + t.set("type", Json("function")); + t.set("function", fn); + return t; +} + +// ---- strict schema --------------------------------------------------------- + +namespace { + +std::string check_node(const Json& node, std::size_t depth, const std::string& at); + +std::string check_object(const Json& node, std::size_t depth, const std::string& at) { + const Json* props = node.find("properties"); + std::set names; + if (props && props->is_object()) { + for (const auto& [k, v] : props->as_object()) { + names.insert(k); + std::string e = check_node(v, depth + 1, at + "." + k); + if (!e.empty()) return e; + } + } + std::set required; + if (const Json* r = node.find("required"); r && r->is_array()) + for (const Json& v : r->as_array()) + if (v.is_string()) required.insert(v.as_string()); + if (required != names) return at + ": every property must be listed in required"; + const Json* ap = node.find("additionalProperties"); + if (!ap || !ap->is_bool() || ap->as_bool()) return at + ": additionalProperties must be false"; + return ""; +} + +std::string check_node(const Json& node, std::size_t depth, const std::string& at) { + if (depth > DeepseekCaps::kMaxSchemaDepth) return at + ": schema nested too deeply"; + if (!node.is_object()) return at + ": schema must be an object"; + if (node.has("$ref")) return ""; + if (const Json* any = node.find("anyOf")) { + if (!any->is_array() || any->as_array().empty()) return at + ": anyOf must be a non-empty array"; + for (const Json& s : any->as_array()) { + std::string e = check_node(s, depth + 1, at + ".anyOf"); + if (!e.empty()) return e; + } + return ""; + } + for (const char* banned : {"minLength", "maxLength", "minItems", "maxItems"}) + if (node.has(banned)) return at + ": " + banned + " is not supported in strict mode"; + for (const char* defs : {"$def", "$defs"}) + if (const Json* d = node.find(defs); d && d->is_object()) + for (const auto& [k, v] : d->as_object()) { + std::string e = check_node(v, depth + 1, at + "." + defs + "." + k); + if (!e.empty()) return e; + } + const Json* type = node.find("type"); + if (!type) return node.has("enum") ? "" : at + ": type is required"; + if (!type->is_string()) return at + ": type must be a string"; + const std::string& t = type->as_string(); + if (t == "object") return check_object(node, depth, at); + if (t == "array") { + const Json* items = node.find("items"); + return items ? check_node(*items, depth + 1, at + "[]") : at + ": array needs items"; + } + if (t == "string" || t == "number" || t == "integer" || t == "boolean") return ""; + return at + ": type " + t + " is not supported in strict mode"; +} + +} // namespace + +std::string StrictSchema::check(const Json& schema) { + if (!schema.is_object()) return "$: schema must be an object"; + const Json* t = schema.find("type"); + if (!t || !t->is_string() || t->as_string() != "object") return "$: root type must be object"; + return check_node(schema, 0, "$"); +} + +// ---- ChatParams ------------------------------------------------------------ + +void ChatParams::add(const Json& message) { messages.push(message); } + +bool ChatParams::thinking_on() const { + if (thinking == Thinking::kDisabled) return false; + if (reasoning_effort == "none") return false; + return true; +} + +bool ChatParams::has_prefix() const { + if (!messages.is_array() || messages.as_array().empty()) return false; + const Json& last = messages.as_array().back(); + return last.is_object() && J::flag(last, "prefix"); +} + +bool ChatParams::needs_beta() const { + if (has_prefix()) return true; + return std::any_of(tools.begin(), tools.end(), [](const ToolDef& t) { return t.strict; }); +} + +namespace { + +void check_parts(const Json& content, const char* role, std::size_t& images) { + Rules::require(content.is_string() || content.is_array(), + std::string(role) + " content must be a string or an array of parts"); + if (!content.is_array()) return; + Rules::require(!content.as_array().empty(), std::string(role) + " content parts must not be empty"); + for (const Json& p : content.as_array()) { + Rules::require(p.is_object(), "content part must be an object"); + std::string type = J::str(p, "type"); + if (type == "text") { + Rules::require(p.find("text") && p.find("text")->is_string(), "text part needs text"); + } else if (type == "image_url") { + const Json* img = J::obj(p, "image_url"); + Rules::require(img, "image_url part needs an image_url object"); + Rules::image_url(J::str(*img, "url")); + Rules::detail(J::str(*img, "detail")); + ++images; + } else if (type == "file") { + bool id = p.has("file_id"), data = p.has("file_data"); + Rules::require(id != data, "file part needs exactly one of file_id and file_data"); + if (id) { + Rules::require(!p.has("filename"), "filename is not allowed together with file_id"); + std::string fid = J::str(p, "file_id"); + Rules::require(!fid.empty() && fid.size() <= 256, "file_id must be 1..256 characters"); + } else { + Rules::image_url(J::str(p, "file_data")); + Rules::require(J::str(p, "file_data").rfind("data:", 0) == 0, "file_data must be a data URL"); + Rules::require(J::str(p, "filename").size() <= DeepseekCaps::kMaxFilenameBytes, + "filename over 512 bytes"); + } + ++images; + } else { + Rules::fail("unknown content part type '" + type + "'"); + } + } +} + +} // namespace + +void ChatParams::validate() const { + Rules::model(model); + Rules::require(messages.is_array() && !messages.as_array().empty(), "messages must not be empty"); + Rules::require(messages.as_array().size() <= DeepseekCaps::kMaxMessages, "too many messages"); + std::size_t images = 0; + bool saw_json_word = false; + const auto& all = messages.as_array(); + for (std::size_t i = 0; i < all.size(); ++i) { + const Json& m = all[i]; + Rules::require(m.is_object(), "message must be an object"); + std::string role = J::str(m, "role"); + const Json* content = m.find("content"); + if (role == "system" || role == "user") { + Rules::require(content, role + " message needs content"); + if (role == "system") { + Rules::require(content->is_string(), "system content must be a string"); + } else { + check_parts(*content, "user", images); + } + } else if (role == "assistant") { + Rules::require(!content || content->is_string() || content->is_null(), + "assistant content must be a string or null"); + if (const Json* tc = m.find("tool_calls")) { + Rules::require(tc->is_array(), "tool_calls must be an array"); + for (const Json& c : tc->as_array()) { + Rules::require(c.is_object() && c.has("id") && J::obj(c, "function"), + "tool call needs id and function"); + Rules::tool_name(J::str(*J::obj(c, "function"), "name")); + } + } + if (const Json* r = m.find("reasoning_content")) + Rules::require(r->is_string() || r->is_null(), "reasoning_content must be a string"); + if (m.has("prefix")) { + Rules::require(m.find("prefix")->is_bool(), "prefix must be a boolean"); + if (J::flag(m, "prefix")) + Rules::require(i + 1 == all.size(), "only the last message may be a prefix message"); + } + } else if (role == "tool") { + Rules::require(!J::str(m, "tool_call_id").empty(), "tool message needs tool_call_id"); + Rules::require(content, "tool message needs content"); + check_parts(*content, "tool", images); + } else { + Rules::fail("message role must be system, user, assistant or tool"); + } + if (content && content->is_string() && Rules::has_json_word(content->as_string())) + saw_json_word = true; + if (content && content->is_array()) + for (const Json& p : content->as_array()) + if (Rules::has_json_word(J::str(p, "text"))) saw_json_word = true; + } + if (has_prefix()) { + Rules::require(J::str(all.back(), "role") == "assistant", + "the prefix message must have role assistant"); + } + Rules::require(images <= DeepseekCaps::kMaxImages, "at most 600 images per request"); + + if (thinking == Thinking::kEnabled) + Rules::require(reasoning_effort != "none", "thinking enabled contradicts reasoning_effort none"); + if (!reasoning_effort.empty()) Rules::effort(reasoning_effort); + if (max_tokens) + Rules::require(*max_tokens >= 1 && *max_tokens <= DeepseekCaps::kMaxTokensCeiling, + "max_tokens must be 1..393216"); + if (temperature) Rules::range(*temperature, 0, 2, "temperature"); + if (top_p) Rules::top_p(*top_p); + Rules::stop(stop); + if (json_mode) + Rules::require(saw_json_word, + "JSON output needs the word 'json' in a message (and an example of the format), " + "else the model may stream whitespace until max_tokens"); + if (top_logprobs) { + Rules::require(logprobs, "top_logprobs needs logprobs true"); + Rules::require(*top_logprobs >= 0 && *top_logprobs <= DeepseekCaps::kMaxTopLogprobs, + "top_logprobs must be 0..20"); + } + if (!user_id.empty()) Rules::user_id(user_id); + + Rules::require(tools.size() <= DeepseekCaps::kMaxTools, "too many tools"); + std::set names; + bool any_strict = false, all_strict = true; + for (const ToolDef& t : tools) { + Rules::tool_name(t.name); + Rules::require(names.insert(t.name).second, "tool names must be unique"); + Rules::require(t.parameters.is_object(), "tool parameters must be a JSON Schema object"); + any_strict = any_strict || t.strict; + all_strict = all_strict && t.strict; + if (t.strict) { + std::string problem = StrictSchema::check(t.parameters); + Rules::require(problem.empty(), "strict tool '" + t.name + "': " + problem); + } + } + Rules::require(!any_strict || all_strict, "strict mode needs strict true on every function"); + + if (!tool_choice.empty()) { + bool mode = tool_choice == "none" || tool_choice == "auto" || tool_choice == "required"; + if (!mode) Rules::tool_name(tool_choice); + if (tool_choice != "none") + Rules::require(!tools.empty(), "tool_choice needs tools"); + if (tool_choice == "required" || !mode) + Rules::require(!thinking_on(), + "tool_choice required or named is not supported in thinking mode (400); " + "disable thinking first"); + if (!mode) + Rules::require(names.count(tool_choice) == 1, "tool_choice names a tool that is not defined"); + } +} + +Json ChatParams::to_json(bool stream) const { + validate(); + Json body = Json::object(); + body.set("model", Json(model)); + + // Reasoning rule: keep reasoning_content only with tools (or on the prefix message). + Json out_messages = Json::array(); + const auto& all = messages.as_array(); + for (std::size_t i = 0; i < all.size(); ++i) { + Json m = all[i]; + bool prefix_message = J::flag(m, "prefix") && i + 1 == all.size(); + if (J::str(m, "role") == "assistant" && tools.empty() && !prefix_message) + m.as_object().erase("reasoning_content"); + out_messages.push(m); + } + body.set("messages", out_messages); + + if (thinking != Thinking::kDefault) { + Json t = Json::object(); + t.set("type", Json(thinking == Thinking::kEnabled ? "enabled" : "disabled")); + body.set("thinking", t); + } + if (!reasoning_effort.empty()) body.set("reasoning_effort", Json(reasoning_effort)); + if (max_tokens) body.set("max_tokens", Json(*max_tokens)); + if (json_mode) { + Json rf = Json::object(); + rf.set("type", Json("json_object")); + body.set("response_format", rf); + } + if (!stop.empty()) { + Json s = Json::array(); + for (const std::string& v : stop) s.push(Json(v)); + body.set("stop", s); + } + if (stream) { + body.set("stream", Json(true)); + Json so = Json::object(); + so.set("include_usage", Json(include_usage)); + body.set("stream_options", so); + } + if (temperature) body.set("temperature", Json(*temperature)); + if (top_p) body.set("top_p", Json(*top_p)); + if (!tools.empty()) { + Json arr = Json::array(); + for (const ToolDef& t : tools) arr.push(t.to_json()); + body.set("tools", arr); + } + if (!tool_choice.empty()) { + if (tool_choice == "none" || tool_choice == "auto" || tool_choice == "required") { + body.set("tool_choice", Json(tool_choice)); + } else { + Json fn = Json::object(); + fn.set("name", Json(tool_choice)); + Json tc = Json::object(); + tc.set("type", Json("function")); + tc.set("function", fn); + body.set("tool_choice", tc); + } + } + if (logprobs) body.set("logprobs", Json(true)); + if (top_logprobs) body.set("top_logprobs", Json(*top_logprobs)); + if (!user_id.empty()) body.set("user_id", Json(user_id)); + if (extra.is_object()) + for (const auto& [k, v] : extra.as_object()) { + Rules::require(!body.has(k), "extra field '" + k + "' collides with a validated field"); + body.set(k, v); + } + return body; +} + +ChatParams ChatParams::prompt(const std::string& text, const std::string& model) { + ChatParams p; + p.model = model; + p.add(Messages::user(text)); + return p; +} + +} // namespace molo::deepseek diff --git a/src/deepseek/chat_params.h b/src/deepseek/chat_params.h new file mode 100644 index 0000000..3494297 --- /dev/null +++ b/src/deepseek/chat_params.h @@ -0,0 +1,94 @@ +#pragma once + +// Chat Completions request: message builders, tool definitions, strict-mode +// schema check, validation against the published rules, and the request body. +// +// Reasoning rule (Thinking Mode guide): reasoning_content of earlier assistant +// turns is sent back ONLY when the request carries tools (the API answers 400 +// if it is missing there). Without tools it is dropped from the body, because +// the API ignores it and never concatenates it into the context. The one other +// use is the beta prefix message, whose reasoning_content is the CoT input. + +#include +#include +#include + +#include "deepseek/types.h" + +namespace molo::deepseek { + +enum class Thinking { kDefault, kEnabled, kDisabled }; + +// Builders for the message and content-part documents of the request. +struct Messages { + static Json system(const std::string& text, const std::string& name = ""); + static Json user(const std::string& text, const std::string& name = ""); + static Json user_parts(const std::vector& parts, const std::string& name = ""); + static Json text_part(const std::string& text); + // http(s) URL (<= 8192 chars) or data:image/...;base64,... URL. detail: "", low, high, original, auto. + static Json image_part(const std::string& url, const std::string& detail = ""); + static Json file_part(const std::string& file_id); + static Json file_data_part(const std::string& data_url, const std::string& filename = ""); + // content may be empty when tool_calls carry the turn (sent as ""). + static Json assistant(const std::string& content, const std::string& reasoning = "", + const Json& tool_calls = Json()); + // Beta chat prefix completion: the last message, role assistant, prefix true. + static Json assistant_prefix(const std::string& prefix, const std::string& reasoning = ""); + static Json tool(const std::string& call_id, const std::string& content); + static Json tool_parts(const std::string& call_id, const std::vector& parts); + // {"id","type":"function","function":{"name","arguments"}} with arguments as the JSON text. + static Json tool_call(const std::string& id, const std::string& name, const std::string& arguments); +}; + +// A function tool. strict is the beta strict mode (see StrictSchema). +struct ToolDef { + std::string name; // ^[A-Za-z0-9_-]{1,128}$ + std::string description; + Json parameters = Json::object(); // JSON Schema object + bool strict = false; + Json to_json() const; +}; + +// Beta strict-mode schema subset (Tool Calls guide): types object, string, +// number, integer, boolean, array, enum, anyOf, $ref / $def. Every object lists +// all its properties in required and sets additionalProperties false. Rejected: +// minLength, maxLength, minItems, maxItems. Returns an empty string when the +// schema is acceptable, else the first problem. +struct StrictSchema { + static std::string check(const Json& schema); +}; + +struct ChatParams { + std::string model = "deepseek-flash"; + Json messages = Json::array(); + Thinking thinking = Thinking::kDefault; + // "", none, low, high, max; the server also accepts minimal, medium, xhigh, ultra. + std::string reasoning_effort; + std::optional max_tokens; // 1..393216 + bool json_mode = false; // response_format {"type":"json_object"} + std::vector stop; // up to 16 + bool include_usage = true; // stream_options.include_usage (stream only) + std::optional temperature; // 0..2; no effect in thinking mode + std::optional top_p; // (0,1] + std::vector tools; + // "", none, auto, required, or a function name (required / named need thinking off). + std::string tool_choice; + bool logprobs = false; + std::optional top_logprobs; // 0..20, needs logprobs + std::string user_id; // [A-Za-z0-9_-]{1,512} + Json extra = Json::object(); // passthrough merged last, cannot replace validated fields + + void add(const Json& message); + bool thinking_on() const; // thinking is enabled unless disabled or effort none + bool has_prefix() const; // the last message is a prefix message + // Beta endpoint needed: prefix message or strict tools. + bool needs_beta() const; + // Throws llm::ApiError::invalid before any network traffic. + void validate() const; + // Validated request body. Applies the reasoning_content rule above. + Json to_json(bool stream = false) const; + + static ChatParams prompt(const std::string& text, const std::string& model = "deepseek-flash"); +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/chat_result.cpp b/src/deepseek/chat_result.cpp new file mode 100644 index 0000000..5e67ed3 --- /dev/null +++ b/src/deepseek/chat_result.cpp @@ -0,0 +1,180 @@ +#include "deepseek/chat_result.h" + +#include "deepseek/caps.h" +#include "llm/error.h" + +namespace molo::deepseek { + +bool ToolCallRecord::arguments_valid() const { + try { + Json::parse(arguments.empty() ? "{}" : arguments); + return true; + } catch (const std::exception&) { + return false; + } +} + +Json ToolCallRecord::parsed() const { + try { + return Json::parse(arguments.empty() ? "{}" : arguments); + } catch (const std::exception&) { + return Json(); + } +} + +bool ChatChoice::interrupted() const { + return finish_reason == "insufficient_system_resource" || finish_reason == "aborted"; +} + +Json ChatChoice::history_message() const { + Json m = Json::object(); + m.set("role", Json("assistant")); + m.set("content", Json(content)); + if (!reasoning_content.empty()) m.set("reasoning_content", Json(reasoning_content)); + if (!tool_calls.empty()) { + Json arr = Json::array(); + for (const ToolCallRecord& c : tool_calls) { + Json fn = Json::object(); + fn.set("name", Json(c.name)); + fn.set("arguments", Json(c.arguments)); + Json call = Json::object(); + call.set("id", Json(c.id)); + call.set("type", Json("function")); + call.set("function", fn); + arr.push(call); + } + m.set("tool_calls", arr); + } + return m; +} + +const ChatChoice& ChatResult::first() const { + if (choices.empty()) throw llm::ApiError("deepseek", 502, "BAD_RESPONSE", "response has no choices"); + return choices.front(); +} + +ChatChoice ChatResult::parse_choice(const Json& choice) { + ChatChoice c; + c.index = static_cast(J::num(choice, "index")); + c.finish_reason = J::str(choice, "finish_reason"); + if (const Json* lp = choice.find("logprobs")) c.logprobs = *lp; + if (const Json* m = J::obj(choice, "message")) { + c.content = J::str(*m, "content"); + c.reasoning_content = J::str(*m, "reasoning_content"); + if (const Json* calls = J::arr(*m, "tool_calls")) { + int n = 0; + for (const Json& call : calls->as_array()) { + if (!call.is_object()) continue; + ToolCallRecord r; + r.index = n++; + r.id = J::str(call, "id"); + if (const Json* fn = J::obj(call, "function")) { + r.name = J::str(*fn, "name"); + r.arguments = J::str(*fn, "arguments"); + } + c.tool_calls.push_back(r); + } + } + } + return c; +} + +ChatResult ChatResult::parse(const Json& doc) { + if (!doc.is_object()) throw llm::ApiError("deepseek", 502, "BAD_RESPONSE", "response is not an object"); + ChatResult r; + r.raw = doc; + r.id = J::str(doc, "id"); + r.model = J::str(doc, "model"); + r.object = J::str(doc, "object"); + r.system_fingerprint = J::str(doc, "system_fingerprint"); + r.created = J::num(doc, "created"); + if (const Json* choices = J::arr(doc, "choices")) + for (const Json& c : choices->as_array()) { + if (r.choices.size() >= DeepseekCaps::kMaxChoices) break; + if (c.is_object()) r.choices.push_back(parse_choice(c)); + } + r.usage = TokenUsage::from_completion(doc.find("usage")); + return r; +} + +ChatChoice& ChatStreamAccumulator::choice_at(int index) { + for (ChatChoice& c : result_.choices) + if (c.index == index) return c; + if (result_.choices.size() >= DeepseekCaps::kMaxChoices) + throw llm::ApiError("deepseek", 502, "BAD_RESPONSE", "stream has too many choices"); + ChatChoice c; + c.index = index; + result_.choices.push_back(c); + return result_.choices.back(); +} + +StreamDelta ChatStreamAccumulator::feed(const Json& chunk) { + if (++events_ > DeepseekCaps::kMaxStreamEvents) + throw llm::ApiError("deepseek", 502, "BAD_RESPONSE", "stream over the event cap"); + StreamDelta out; + if (!chunk.is_object()) return out; + if (result_.id.empty()) result_.id = J::str(chunk, "id"); + if (result_.model.empty()) result_.model = J::str(chunk, "model"); + if (result_.object.empty()) result_.object = J::str(chunk, "object"); + if (result_.created == 0) result_.created = J::num(chunk, "created"); + std::string fp = J::str(chunk, "system_fingerprint"); + if (!fp.empty()) result_.system_fingerprint = fp; + + if (const Json* choices = J::arr(chunk, "choices")) + for (const Json& c : choices->as_array()) { + if (!c.is_object()) continue; + ChatChoice& acc = choice_at(static_cast(J::num(c, "index"))); + out.choice = acc.index; + if (const Json* d = J::obj(c, "delta")) { + std::string text = J::str(*d, "content"); + std::string reasoning = J::str(*d, "reasoning_content"); + acc.content += text; + acc.reasoning_content += reasoning; + out.content += text; + out.reasoning += reasoning; + if (const Json* calls = J::arr(*d, "tool_calls")) + for (const Json& call : calls->as_array()) { + if (!call.is_object()) continue; + StreamDelta::ToolFragment f; + f.index = static_cast(J::num(call, "index")); + f.id = J::str(call, "id"); + if (const Json* fn = J::obj(call, "function")) { + f.name = J::str(*fn, "name"); + f.arguments_delta = J::str(*fn, "arguments"); + } + ToolCallRecord* rec = nullptr; + for (ToolCallRecord& r : acc.tool_calls) + if (r.index == f.index) rec = &r; + if (!rec) { + if (acc.tool_calls.size() >= DeepseekCaps::kMaxTools) + throw llm::ApiError("deepseek", 502, "BAD_RESPONSE", "stream has too many tool calls"); + ToolCallRecord r; + r.index = f.index; + acc.tool_calls.push_back(r); + rec = &acc.tool_calls.back(); + } + if (!f.id.empty()) rec->id = f.id; + if (!f.name.empty()) rec->name = f.name; + rec->arguments += f.arguments_delta; + out.tools.push_back(f); + } + } + std::string fr = J::str(c, "finish_reason"); + if (!fr.empty()) { + acc.finish_reason = fr; + out.finish_reason = fr; + finished_ = true; + } + if (const Json* lp = c.find("logprobs"); lp && lp->is_object()) acc.logprobs = *lp; + } + if (const Json* u = chunk.find("usage"); u && u->is_object()) { + result_.usage = TokenUsage::from_completion(u); + out.has_usage = true; + out.usage = result_.usage; + } + return out; +} + +ChatResult ChatStreamAccumulator::result() const { return result_; } + +} // namespace molo::deepseek diff --git a/src/deepseek/chat_result.h b/src/deepseek/chat_result.h new file mode 100644 index 0000000..404c88b --- /dev/null +++ b/src/deepseek/chat_result.h @@ -0,0 +1,89 @@ +#pragma once + +// Chat Completions response and the stream accumulator that folds +// chat.completion.chunk documents into the same ChatResult. + +#include +#include + +#include "deepseek/types.h" + +namespace molo::deepseek { + +struct ToolCallRecord { + int index = 0; + std::string id; + std::string name; + std::string arguments; // JSON text; the model may emit invalid JSON + bool arguments_valid() const; + // Parsed arguments, or null when invalid (check arguments_valid first). + Json parsed() const; +}; + +struct ChatChoice { + int index = 0; + // stop | length | content_filter | tool_calls | insufficient_system_resource | aborted + std::string finish_reason; + std::string content; + std::string reasoning_content; // thinking mode only + std::vector tool_calls; + Json logprobs; // null when absent + bool truncated() const { return finish_reason == "length"; } + // Interrupted by the server: insufficient_system_resource or aborted. + bool interrupted() const; + // The assistant message to append to the next request's history, exactly as + // the API returned it (content, reasoning_content, tool_calls). ChatParams + // drops reasoning_content again when the request has no tools. + Json history_message() const; +}; + +struct ChatResult { + std::string id; + std::string model; + std::string object; + std::string system_fingerprint; + long created = 0; + std::vector choices; + TokenUsage usage; + Json raw; // non-stream: the document; stream: null + + const ChatChoice& first() const; // throws ApiError BAD_RESPONSE when there is none + static ChatResult parse(const Json& doc); + static ChatChoice parse_choice(const Json& choice); +}; + +// One streamed chunk, reduced to what changed. +struct StreamDelta { + int choice = 0; + std::string content; + std::string reasoning; + struct ToolFragment { + int index = 0; + std::string id; // first fragment of a call only + std::string name; // first fragment of a call only + std::string arguments_delta; + }; + std::vector tools; + std::string finish_reason; // set on the last content chunk of a choice + bool has_usage = false; + TokenUsage usage; +}; + +class ChatStreamAccumulator { + public: + // Folds one chunk. Keep-alive comments never reach here (SSE decoder drops + // them); `usage: null` and `role: null` are tolerated. + StreamDelta feed(const Json& chunk); + // The folded result (usage from the last chunk that carried it). + ChatResult result() const; + std::size_t events() const { return events_; } + bool done() const { return finished_; } + + private: + ChatChoice& choice_at(int index); + ChatResult result_; + std::size_t events_ = 0; + bool finished_ = false; +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/errors.cpp b/src/deepseek/errors.cpp new file mode 100644 index 0000000..79165b1 --- /dev/null +++ b/src/deepseek/errors.cpp @@ -0,0 +1,82 @@ +#include "deepseek/errors.h" + +namespace molo::deepseek { + +namespace { +constexpr ErrorInfo kErrors[] = { + {400, ErrorKind::kBadRequest, "Invalid Format", + "Invalid request body format.", + "Modify the request body according to the hints in the error message.", false, 0, "all"}, + {401, ErrorKind::kAuth, "Authentication Fails", + "Wrong or missing API key.", "Check the API key; create one if none exists.", false, 0, + "all"}, + {402, ErrorKind::kBalance, "Insufficient Balance", + "The account ran out of balance.", "Check the balance (GET /user/balance) and top up.", + false, 0, "all"}, + {403, ErrorKind::kForbidden, "Rejected by security policy", + "The Fetch request was rejected by the security policy.", + "Do not retry without changing the request.", false, 0, "search/fetch"}, + {404, ErrorKind::kNotFound, "No usable page content", + "Fetch could not retrieve usable page content (unavailable URL, blocked by site policy, " + "target site error, unsupported content type, no extractable Markdown).", + "Do not retry without changing the request.", false, 0, "search/fetch"}, + {408, ErrorKind::kTimeout, "Request body timeout", + "Reading the request body timed out.", "Wait and retry.", true, 2, "search/fetch"}, + {413, ErrorKind::kTooLarge, "Request body too large", + "The request body is too large.", "Send a smaller body.", false, 0, "search/fetch"}, + {422, ErrorKind::kInvalidParams, "Invalid Parameters", + "The request contains invalid parameters.", + "Modify the parameters according to the hints in the error message.", false, 0, "all"}, + {429, ErrorKind::kRateLimit, "Rate Limit Reached", + "Requests are sent too quickly, or a concurrency / QPS limit is exceeded.", + "Pace the requests (concurrency is per account; Search 100 and Fetch 25 QPS).", true, 1, + "all"}, + {500, ErrorKind::kServer, "Server Error", "The server encountered an issue.", + "Retry after a brief wait; contact support if it persists.", true, 2, "all"}, + {503, ErrorKind::kOverloaded, "Server Overloaded", + "The server is overloaded due to high traffic.", "Retry after a brief wait.", true, 2, + "all"}, + {504, ErrorKind::kGatewayTimeout, "Downstream timeout", + "A downstream request timed out.", "Wait and retry.", true, 2, "search/fetch"}, +}; +} // 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("deepseek", "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; + // Framework statuses: 502 comes from the transport (UNAVAILABLE / BAD_RESPONSE). + if (status == 502) return ErrorKind::kTransport; + 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; +} + +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::deepseek diff --git a/src/deepseek/errors.h b/src/deepseek/errors.h new file mode 100644 index 0000000..70bf8a3 --- /dev/null +++ b/src/deepseek/errors.h @@ -0,0 +1,48 @@ +#pragma once + +// DeepSeek error codes and what to do about them. The table is the docs' +// Error Codes page plus the Search / Fetch guide. Waits are static; nothing +// here sleeps or retries on its own: the caller decides, within the floor. + +#include + +#include "llm/error.h" + +namespace molo::deepseek { + +enum class ErrorKind { + kNone, kBadRequest, kAuth, kBalance, kForbidden, kNotFound, kTimeout, kTooLarge, + kInvalidParams, kRateLimit, kServer, kOverloaded, kGatewayTimeout, kTransport, kOther, +}; + +struct ErrorInfo { + int status; + ErrorKind kind; + const char* name; // "Insufficient Balance" + 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 + const char* surface; // "all" or "search/fetch" +}; + +class Errors { + public: + static std::size_t count(); + static const ErrorInfo& at(std::size_t index); + // The row for an HTTP status, or nullptr. + 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; + // One line for humans: "402 Insufficient Balance: top up ...". + static std::string explain(const llm::ApiError& e); + // Server keep-alive: empty lines (non-stream) or ": keep-alive" comments + // (stream) arrive while a request waits; the server closes after 10 minutes + // without starting inference. + static constexpr int kKeepAliveCloseSeconds = 600; +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/files.cpp b/src/deepseek/files.cpp new file mode 100644 index 0000000..a0a4e53 --- /dev/null +++ b/src/deepseek/files.cpp @@ -0,0 +1,143 @@ +#include "deepseek/files.h" + +#include "clients/body/form.h" +#include "deepseek/calls.h" +#include "deepseek/caps.h" +#include "deepseek/rules.h" + +namespace molo::deepseek { + +std::string UploadParams::sniff(const std::string& d) { + auto starts = [&](const char* magic, std::size_t n) { return d.size() >= n && d.compare(0, n, magic, n) == 0; }; + if (starts("\xFF\xD8\xFF", 3)) return "jpeg"; + if (starts("\x89PNG\r\n\x1a\n", 8)) return "png"; + if (starts("GIF87a", 6) || starts("GIF89a", 6)) return "gif"; + if (d.size() >= 12 && d.compare(0, 4, "RIFF") == 0 && d.compare(8, 4, "WEBP") == 0) return "webp"; + return ""; +} + +void UploadParams::validate() const { + Rules::require(!filename.empty() && filename.size() <= DeepseekCaps::kMaxFilenameBytes, + "filename must be 1..512 bytes"); + for (char c : filename) + Rules::require(c != '"' && c != '\r' && c != '\n' && c != '\\' && c != '/', + "filename has invalid characters"); + Rules::require(!data.empty(), "file is empty"); + Rules::require(data.size() <= DeepseekCaps::kMaxUploadBytes, "file over 64 MiB"); + Rules::require(!sniff(data).empty(), "only JPEG, PNG, GIF and WebP images can be uploaded"); + if (expires_after_seconds) + Rules::require(*expires_after_seconds >= DeepseekCaps::kExpireMinSeconds && + *expires_after_seconds <= DeepseekCaps::kExpireMaxSeconds, + "expires_after seconds must be 3600..2592000"); +} + +void FileListParams::validate() const { + Rules::require(limit >= 1 && limit <= DeepseekCaps::kFilesMaxLimit, "limit must be 1..1000"); + Rules::require(order.empty() || order == "asc" || order == "desc", "order must be asc or desc"); + Rules::require(after.empty() || llm::Service::valid_id(after), "bad after cursor"); +} + +void AnthropicFileListParams::validate() const { + Rules::require(limit >= 1 && limit <= DeepseekCaps::kFilesMaxLimit, "limit must be 1..1000"); + Rules::require(after_id.empty() || before_id.empty(), "after_id and before_id are mutually exclusive"); + Rules::require(after_id.empty() || llm::Service::valid_id(after_id), "bad after_id cursor"); + Rules::require(before_id.empty() || llm::Service::valid_id(before_id), "bad before_id cursor"); +} + +namespace { +std::string mime_of(const std::string& kind) { return "image/" + kind; } + +clients::body::MultipartBody upload_form(const UploadParams& p, bool with_purpose) { + clients::body::MultipartBody form; + if (with_purpose) form.add_text("purpose", Files::kPurpose); + form.add_file("file", p.filename, mime_of(UploadParams::sniff(p.data)), p.data); + if (with_purpose && p.expires_after_seconds) { + form.add_text("expires_after[anchor]", "created_at"); + form.add_text("expires_after[seconds]", std::to_string(*p.expires_after_seconds)); + } + return form; +} + +FileDeleted parse_deleted(const Json& doc, bool anthropic) { + FileDeleted d; + d.id = J::str(doc, "id"); + d.deleted = anthropic ? J::str(doc, "type") == "file_deleted" : J::flag(doc, "deleted"); + return d; +} + +llm::Headers beta_header() { return {{"anthropic-beta", Calls::anthropic_files_beta()}}; } +} // namespace + +FileInfo Files::upload(const UploadParams& params) { + params.validate(); + return FileInfo::parse(client_->post_multipart(Calls::render(Call::kFileCreate), upload_form(params, true))); +} + +FileList Files::list(const FileListParams& params) { + params.validate(); + std::string path = Calls::render(Call::kFileList) + "?limit=" + std::to_string(params.limit) + + "&purpose=" + kPurpose; + if (!params.order.empty()) path += "&order=" + params.order; + if (!params.after.empty()) path += "&after=" + params.after; + return FileList::parse(client_->get(path), false); +} + +FileList Files::list_all(int page_limit) { + FileListParams p; + p.limit = page_limit; + FileList all; + for (std::size_t page = 0; page < DeepseekCaps::kMaxFilePages; ++page) { + FileList one = list(p); + for (FileInfo& f : one.files) { + if (all.files.size() >= DeepseekCaps::kMaxFilesReturned) { + all.truncated = true; + return all; + } + all.files.push_back(std::move(f)); + } + if (all.first_id.empty()) all.first_id = one.first_id; + all.last_id = one.last_id; + all.has_more = one.has_more; + if (!one.has_more || one.last_id.empty()) return all; + p.after = one.last_id; + } + all.truncated = all.has_more; + return all; +} + +FileInfo Files::get(const std::string& file_id) { + check_id("file", file_id); + return FileInfo::parse(client_->get(Calls::render(Call::kFileGet, file_id))); +} + +FileDeleted Files::remove(const std::string& file_id) { + check_id("file", file_id); + return parse_deleted(client_->del(Calls::render(Call::kFileDelete, file_id)), false); +} + +FileInfo AnthropicFiles::upload(const UploadParams& params) { + params.validate(); + return FileInfo::parse_anthropic(client_->post_multipart( + Calls::render(Call::kAnthropicFileCreate), upload_form(params, false), beta_header())); +} + +FileList AnthropicFiles::list(const AnthropicFileListParams& params) { + params.validate(); + std::string path = Calls::render(Call::kAnthropicFileList) + "?limit=" + std::to_string(params.limit); + if (!params.after_id.empty()) path += "&after_id=" + params.after_id; + if (!params.before_id.empty()) path += "&before_id=" + params.before_id; + return FileList::parse(client_->get(path, beta_header()), true); +} + +FileInfo AnthropicFiles::get(const std::string& file_id) { + check_id("file", file_id); + return FileInfo::parse_anthropic( + client_->get(Calls::render(Call::kAnthropicFileGet, file_id), beta_header())); +} + +FileDeleted AnthropicFiles::remove(const std::string& file_id) { + check_id("file", file_id); + return parse_deleted(client_->del(Calls::render(Call::kAnthropicFileDelete, file_id), beta_header()), true); +} + +} // namespace molo::deepseek diff --git a/src/deepseek/files.h b/src/deepseek/files.h new file mode 100644 index 0000000..714be24 --- /dev/null +++ b/src/deepseek/files.h @@ -0,0 +1,68 @@ +#pragma once + +// Files API: image uploads referenced by file_id (file-api-...) from chat, +// Responses and Anthropic-compatible requests. Two surfaces, two shapes: +// Files (OpenAI-compatible, /files) and AnthropicFiles (/anthropic/v1/files, +// header anthropic-beta: files-api-2025-04-14). Files are account-wide. +// Delete is an explicit method with no default and no implicit call. + +#include +#include + +#include "deepseek/types.h" +#include "llm/api_client.h" + +namespace molo::deepseek { + +struct UploadParams { + std::string filename; // 1..512 bytes + std::string data; // JPEG, PNG, GIF or WebP bytes, 1..64 MiB (magic bytes checked) + std::optional expires_after_seconds; // 3600..2592000; unset keeps the file + void validate() const; + // jpeg, png, gif, webp, or "" when the bytes are none of them + static std::string sniff(const std::string& data); +}; + +struct FileListParams { + std::string after; // file_id cursor + int limit = 1000; // 1..1000 + std::string order; // "", asc, desc + void validate() const; +}; + +struct FileDeleted { + std::string id; + bool deleted = false; +}; + +class Files : public llm::Service { + public: + static constexpr const char* kPurpose = "user_data"; + explicit Files(std::shared_ptr client) : llm::Service(std::move(client)) {} + FileInfo upload(const UploadParams& params); + FileList list(const FileListParams& params = {}); + // Follows `after` up to DeepseekCaps::kMaxFilePages pages; truncated is set + // when more remain. + FileList list_all(int page_limit = 1000); + FileInfo get(const std::string& file_id); + FileDeleted remove(const std::string& file_id); // explicit, irreversible +}; + +struct AnthropicFileListParams { + std::string after_id; // exclusive with before_id + std::string before_id; + int limit = 20; // 1..1000 + void validate() const; +}; + +class AnthropicFiles : public llm::Service { + public: + explicit AnthropicFiles(std::shared_ptr client) + : llm::Service(std::move(client)) {} + FileInfo upload(const UploadParams& params); + FileList list(const AnthropicFileListParams& params = {}); + FileInfo get(const std::string& file_id); + FileDeleted remove(const std::string& file_id); // answers {"id","type":"file_deleted"} +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/fim.cpp b/src/deepseek/fim.cpp new file mode 100644 index 0000000..424c615 --- /dev/null +++ b/src/deepseek/fim.cpp @@ -0,0 +1,123 @@ +#include "deepseek/fim.h" + +#include "deepseek/calls.h" +#include "deepseek/caps.h" +#include "deepseek/rules.h" + +namespace molo::deepseek { + +void FimParams::validate() const { + Rules::model(model); + Rules::require(!prompt.empty(), "prompt must not be empty"); + if (max_tokens) + Rules::require(*max_tokens >= 1 && *max_tokens <= DeepseekCaps::kFimMaxTokens, + "FIM max_tokens must be 1..4096"); + if (echo) { + Rules::require(suffix.empty(), "echo cannot be used together with suffix"); + Rules::require(!logprobs, "echo cannot be used together with logprobs"); + } + if (logprobs) + Rules::require(*logprobs >= 0 && *logprobs <= DeepseekCaps::kMaxTopLogprobs, "logprobs must be 0..20"); + Rules::stop(stop); + if (temperature) Rules::range(*temperature, 0, 2, "temperature"); + if (top_p) Rules::top_p(*top_p); +} + +Json FimParams::to_json(bool stream) const { + validate(); + Json b = Json::object(); + b.set("model", Json(model)); + b.set("prompt", Json(prompt)); + if (!suffix.empty()) b.set("suffix", Json(suffix)); + if (max_tokens) b.set("max_tokens", Json(*max_tokens)); + if (echo) b.set("echo", Json(true)); + if (logprobs) b.set("logprobs", Json(*logprobs)); + if (!stop.empty()) { + Json s = Json::array(); + for (const std::string& v : stop) s.push(Json(v)); + b.set("stop", s); + } + if (stream) { + b.set("stream", Json(true)); + Json so = Json::object(); + so.set("include_usage", Json(include_usage)); + b.set("stream_options", so); + } + if (temperature) b.set("temperature", Json(*temperature)); + if (top_p) b.set("top_p", Json(*top_p)); + return b; +} + +const FimChoice& FimResult::first() const { + if (choices.empty()) throw llm::ApiError("deepseek", 502, "BAD_RESPONSE", "response has no choices"); + return choices.front(); +} + +FimResult FimResult::parse(const Json& doc) { + if (!doc.is_object()) throw llm::ApiError("deepseek", 502, "BAD_RESPONSE", "response is not an object"); + FimResult r; + r.id = J::str(doc, "id"); + r.model = J::str(doc, "model"); + r.object = J::str(doc, "object"); + r.system_fingerprint = J::str(doc, "system_fingerprint"); + r.created = J::num(doc, "created"); + if (const Json* cs = J::arr(doc, "choices")) + for (const Json& c : cs->as_array()) { + if (!c.is_object() || r.choices.size() >= DeepseekCaps::kMaxChoices) continue; + FimChoice x; + x.index = static_cast(J::num(c, "index")); + x.finish_reason = J::str(c, "finish_reason"); + x.text = J::str(c, "text"); + if (const Json* lp = c.find("logprobs")) x.logprobs = *lp; + r.choices.push_back(x); + } + r.usage = TokenUsage::from_completion(doc.find("usage")); + return r; +} + +FimResult Fim::create(const FimParams& params) { + Json body = params.to_json(false); + return FimResult::parse(client_->post(Calls::render(Call::kFim), body)); +} + +FimResult Fim::stream(const FimParams& params, const std::function& on_text) { + Json body = params.to_json(true); + FimResult r; + std::size_t events = 0; + bool finished = false, stopped = false; + client_->stream(Calls::render(Call::kFim), body, [&](const llm::SseEvent& ev) { + if (++events > DeepseekCaps::kMaxStreamEvents) + throw llm::ApiError("deepseek", 502, "BAD_RESPONSE", "stream over the event cap"); + const Json& c = ev.data; + if (r.id.empty()) { + r.id = J::str(c, "id"); + r.model = J::str(c, "model"); + r.object = J::str(c, "object"); + r.created = J::num(c, "created"); + } + std::string delta; + if (const Json* cs = J::arr(c, "choices")) + for (const Json& ch : cs->as_array()) { + if (!ch.is_object()) continue; + if (r.choices.empty()) r.choices.push_back(FimChoice()); + r.choices[0].text += J::str(ch, "text"); + delta += J::str(ch, "text"); + std::string fr = J::str(ch, "finish_reason"); + if (!fr.empty()) { + r.choices[0].finish_reason = fr; + finished = true; + } + } + if (const Json* u = c.find("usage"); u && u->is_object()) r.usage = TokenUsage::from_completion(u); + if (!delta.empty() && on_text && !on_text(delta)) { + stopped = true; + return false; + } + return true; + }); + if (!finished && !stopped) + throw llm::ApiError("deepseek", 502, "STREAM_TRUNCATED", "stream ended without a finish_reason"); + return r; +} + +} // namespace molo::deepseek diff --git a/src/deepseek/fim.h b/src/deepseek/fim.h new file mode 100644 index 0000000..6461518 --- /dev/null +++ b/src/deepseek/fim.h @@ -0,0 +1,55 @@ +#pragma once + +// FIM (Fill In the Middle) completion, beta: POST /beta/completions. Prompt is +// the prefix, suffix the text after the gap; max_tokens is capped at 4K. + +#include +#include +#include +#include + +#include "deepseek/types.h" +#include "llm/api_client.h" + +namespace molo::deepseek { + +struct FimParams { + std::string model = "deepseek-flash"; + std::string prompt; + std::string suffix; + std::optional max_tokens; // 1..4096 + bool echo = false; // not with suffix or logprobs + std::optional logprobs; // 0..20 + std::vector stop; + bool include_usage = true; + std::optional temperature; + std::optional top_p; + void validate() const; + Json to_json(bool stream = false) const; +}; + +struct FimChoice { + int index = 0; + std::string finish_reason; // stop | length | content_filter | insufficient_system_resource | aborted + std::string text; + Json logprobs; +}; + +struct FimResult { + std::string id, model, object, system_fingerprint; + long created = 0; + std::vector choices; + TokenUsage usage; + const FimChoice& first() const; + static FimResult parse(const Json& doc); +}; + +class Fim : public llm::Service { + public: + explicit Fim(std::shared_ptr client) : llm::Service(std::move(client)) {} + FimResult create(const FimParams& params); + // on_text gets each text delta; false stops. Returns the folded result. + FimResult stream(const FimParams& params, const std::function& on_text); +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/platform.cpp b/src/deepseek/platform.cpp new file mode 100644 index 0000000..ab75ce8 --- /dev/null +++ b/src/deepseek/platform.cpp @@ -0,0 +1,38 @@ +#include "deepseek/platform.h" + +#include "llm/config.h" + +namespace molo::deepseek { + +llm::ApiClientConfig Platform::config(Surface surface) { + llm::ApiClientConfig c; + c.vendor = "deepseek"; + c.base_url = kHost; + c.key_env = kKeyEnv; + if (surface == Surface::kAnthropic) { + c.auth = llm::AuthStyle::kHeader; + c.auth_header = "x-api-key"; + } else { + c.auth = llm::AuthStyle::kBearer; + } + return c; +} + +Platform Platform::from_env() { + Platform p; + p.openai = llm::ApiClient::from_env(config(Surface::kOpenai)); + p.anthropic = llm::ApiClient::from_env(config(Surface::kAnthropic)); + return p; +} + +Platform Platform::with(std::unique_ptr openai_transport, + std::unique_ptr anthropic_transport, + const std::string& key) { + Platform p; + p.openai = std::make_shared(std::move(openai_transport), config(Surface::kOpenai), key); + p.anthropic = std::make_shared(std::move(anthropic_transport), + config(Surface::kAnthropic), key); + return p; +} + +} // namespace molo::deepseek diff --git a/src/deepseek/platform.h b/src/deepseek/platform.h new file mode 100644 index 0000000..d5e90f3 --- /dev/null +++ b/src/deepseek/platform.h @@ -0,0 +1,31 @@ +#pragma once + +// Wires the two HTTP surfaces of api.deepseek.com: OpenAI-compatible (Bearer) +// and Anthropic-compatible (x-api-key). One credential, DEEPSEEK_API_KEY, +// read through llm::Config (environment, then the .env.json files). + +#include + +#include "deepseek/calls.h" +#include "llm/api_client.h" + +namespace molo::deepseek { + +struct Platform { + static constexpr const char* kHost = "https://api.deepseek.com"; + static constexpr const char* kKeyEnv = "DEEPSEEK_API_KEY"; + + std::shared_ptr openai; + std::shared_ptr anthropic; + + static llm::ApiClientConfig config(Surface surface); + // Real HTTPS transports; a missing key leaves both clients "not configured". + static Platform from_env(); + // Same key, any transport (tests): one fresh transport per surface. + static Platform with(std::unique_ptr openai_transport, + std::unique_ptr anthropic_transport, + const std::string& key); + bool configured() const { return openai && openai->configured(); } +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/responses.cpp b/src/deepseek/responses.cpp new file mode 100644 index 0000000..1cbe1e4 --- /dev/null +++ b/src/deepseek/responses.cpp @@ -0,0 +1,358 @@ +#include "deepseek/responses.h" + +#include + +#include "deepseek/calls.h" +#include "deepseek/caps.h" +#include "deepseek/rules.h" + +namespace molo::deepseek { + +// ---- builders -------------------------------------------------------------- + +Json ResponseItems::message(const std::string& role, const std::string& text) { + Json m = Json::object(); + m.set("type", Json("message")); + m.set("role", Json(role)); + m.set("content", Json(text)); + return m; +} +Json ResponseItems::message_parts(const std::string& role, const std::vector& parts) { + 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 ResponseItems::input_text(const std::string& text) { + Json p = Json::object(); + p.set("type", Json("input_text")); + p.set("text", Json(text)); + return p; +} +Json ResponseItems::input_image_url(const std::string& url, const std::string& detail) { + Json p = Json::object(); + p.set("type", Json("input_image")); + p.set("image_url", Json(url)); + if (!detail.empty()) p.set("detail", Json(detail)); + return p; +} +Json ResponseItems::input_image_file(const std::string& file_id) { + Json p = Json::object(); + p.set("type", Json("input_image")); + p.set("file_id", Json(file_id)); + return p; +} +Json ResponseItems::function_call(const std::string& call_id, const std::string& name, + const std::string& arguments) { + Json m = Json::object(); + m.set("type", Json("function_call")); + m.set("call_id", Json(call_id)); + m.set("name", Json(name)); + m.set("arguments", Json(arguments)); + return m; +} +Json ResponseItems::function_call_output(const std::string& call_id, const std::string& output) { + Json m = Json::object(); + m.set("type", Json("function_call_output")); + m.set("call_id", Json(call_id)); + m.set("output", Json(output)); + return m; +} +Json ResponseItems::function_call_output_parts(const std::string& call_id, + const std::vector& parts) { + Json arr = Json::array(); + for (const Json& p : parts) arr.push(p); + Json m = Json::object(); + m.set("type", Json("function_call_output")); + m.set("call_id", Json(call_id)); + m.set("output", arr); + return m; +} +Json ResponseItems::reasoning(const std::string& text) { + Json part = Json::object(); + part.set("type", Json("reasoning_text")); + part.set("text", Json(text)); + Json content = Json::array(); + content.push(part); + Json m = Json::object(); + m.set("type", Json("reasoning")); + m.set("content", content); + return m; +} +Json ResponseItems::function_tool(const std::string& name, const std::string& description, + const Json& parameters) { + 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); + return t; +} +Json ResponseItems::web_search_tool() { + Json t = Json::object(); + t.set("type", Json("web_search")); + return t; +} +Json ResponseItems::apply_patch_tool() { + Json t = Json::object(); + t.set("type", Json("custom")); + t.set("name", Json("apply_patch")); + return t; +} + +// ---- validation ------------------------------------------------------------ + +namespace { + +void check_image(const Json& p) { + bool url = p.has("image_url"), file = p.has("file_id"); + Rules::require(url || file, "input_image must have image_url or file_id"); + Rules::require(!(url && file), "input_image cannot have both image_url and file_id"); + if (url) Rules::image_url(J::str(p, "image_url")); + if (file) Rules::require(!J::str(p, "file_id").empty(), "file_id must not be empty"); + Rules::detail(J::str(p, "detail")); +} + +void check_content(const Json& content, bool images_ok, std::size_t& images) { + if (content.is_string()) return; + Rules::require(content.is_array(), "content must be a string or an array of parts"); + for (const Json& p : content.as_array()) { + Rules::require(p.is_object(), "content part must be an object"); + std::string type = J::str(p, "type"); + if (type == "input_text" || type == "output_text") { + Rules::require(p.find("text") && p.find("text")->is_string(), "text part needs text"); + } else if (type == "input_image") { + Rules::require(images_ok, "images are allowed only in user / developer messages and tool outputs"); + check_image(p); + ++images; + } else if (type == "reasoning_text") { + Rules::require(p.find("text") && p.find("text")->is_string(), "reasoning_text part needs text"); + } else { + Rules::fail("unknown content part type '" + type + "' (file inputs are not supported)"); + } + } +} + +void check_items(const Json& items) { + Rules::require(items.as_array().size() <= DeepseekCaps::kMaxMessages, "too many input items"); + std::set calls, outputs, custom_calls, custom_outputs; + std::size_t images = 0; + for (const Json& it : items.as_array()) { + Rules::require(it.is_object(), "input item must be an object"); + std::string type = J::str(it, "type"); + if (type.empty() && it.has("role")) type = "message"; + if (type == "message") { + std::string role = J::str(it, "role"); + Rules::require(role == "user" || role == "assistant" || role == "system" || role == "developer", + "message role must be user, assistant, system or developer"); + const Json* c = it.find("content"); + Rules::require(c, "message needs content"); + check_content(*c, role == "user" || role == "developer", images); + } else if (type == "function_call" || type == "custom_tool_call") { + std::string id = J::str(it, "call_id"); + Rules::require(!id.empty(), type + " needs call_id"); + Rules::tool_name(J::str(it, "name")); + auto& set = type == "function_call" ? calls : custom_calls; + Rules::require(set.insert(id).second, "call_id values must be unique"); + } else if (type == "function_call_output" || type == "custom_tool_call_output") { + std::string id = J::str(it, "call_id"); + Rules::require(!id.empty(), type + " needs call_id"); + const Json* o = it.find("output"); + Rules::require(o, type + " needs output"); + check_content(*o, true, images); + (type == "function_call_output" ? outputs : custom_outputs).insert(id); + } else if (type == "reasoning") { + const Json* c = it.find("content"); + Rules::require(c && c->is_array(), "reasoning item needs a content array"); + check_content(*c, false, images); + } else if (type == "web_search_call") { + // restored search results of a previous response: opaque + } else { + Rules::fail("input item type '" + type + "' is not supported (the server would ignore it)"); + } + } + for (const std::string& id : calls) + Rules::require(outputs.count(id) == 1, "every function_call needs a function_call_output"); + for (const std::string& id : custom_calls) + Rules::require(custom_outputs.count(id) == 1, "every custom_tool_call needs a custom_tool_call_output"); + Rules::require(images <= DeepseekCaps::kMaxImages, "at most 600 images per request"); +} + +} // namespace + +void ResponsesParams::validate() const { + Rules::model(model); + bool has_text = input_text.has_value(); + bool has_items = input_items.is_array() && !input_items.as_array().empty(); + Rules::require(!(has_text && has_items), "give input as text or as items, not both"); + Rules::require(has_text || has_items || !instructions.empty(), + "at least one of input and instructions is required"); + if (has_items) check_items(input_items); + if (!effort.empty()) Rules::effort(effort); + if (max_output_tokens) + Rules::require(*max_output_tokens >= 1 && *max_output_tokens <= DeepseekCaps::kMaxTokensCeiling, + "max_output_tokens must be 1..393216"); + if (temperature) Rules::range(*temperature, 0, 2, "temperature"); + if (top_p) Rules::top_p(*top_p); + if (format == TextFormat::kJsonSchema) { + Rules::require(!schema_name.empty(), "json_schema needs a name"); + Rules::require(schema.is_object() && !schema.as_object().empty(), "json_schema needs a schema"); + } + if (top_logprobs) + Rules::require(*top_logprobs >= 0 && *top_logprobs <= DeepseekCaps::kMaxTopLogprobs, + "top_logprobs must be 0..20"); + if (!user.empty()) Rules::user_id(user); + + Rules::require(tools.is_array() && tools.as_array().size() <= DeepseekCaps::kMaxTools, "too many tools"); + std::set names; + for (const Json& t : tools.as_array()) { + Rules::require(t.is_object(), "tool must be an object"); + std::string type = J::str(t, "type"); + if (type == "function") { + Rules::tool_name(J::str(t, "name")); + Rules::require(names.insert(J::str(t, "name")).second, "tool names must be unique"); + } else if (type == "custom") { + Rules::require(J::str(t, "name") == "apply_patch", "the only custom tool is apply_patch"); + } else if (type != "web_search") { + Rules::fail("tool type must be function, custom or web_search"); + } + } + if (!tool_choice.empty()) { + bool mode = tool_choice == "none" || tool_choice == "auto" || tool_choice == "required"; + if (!mode) { + Rules::tool_name(tool_choice); + Rules::require(names.count(tool_choice) == 1, "tool_choice names a tool that is not defined"); + } else if (tool_choice == "required") { + Rules::require(!tools.as_array().empty(), "tool_choice required needs tools"); + } + } +} + +Json ResponsesParams::to_json(bool stream) const { + validate(); + Json b = Json::object(); + b.set("model", Json(model)); + if (input_text) b.set("input", Json(*input_text)); + else if (!input_items.as_array().empty()) b.set("input", input_items); + if (!instructions.empty()) b.set("instructions", Json(instructions)); + if (!effort.empty()) { + Json r = Json::object(); + r.set("effort", Json(effort)); + b.set("reasoning", r); + } + if (max_output_tokens) b.set("max_output_tokens", Json(*max_output_tokens)); + if (stream) b.set("stream", Json(true)); + if (temperature) b.set("temperature", Json(*temperature)); + if (top_p) b.set("top_p", Json(*top_p)); + if (format != TextFormat::kText) { + Json f = Json::object(); + if (format == TextFormat::kJsonObject) { + f.set("type", Json("json_object")); + } else { + f.set("type", Json("json_schema")); + f.set("name", Json(schema_name)); + f.set("schema", schema); + } + Json t = Json::object(); + t.set("format", f); + b.set("text", t); + } + if (!tools.as_array().empty()) b.set("tools", tools); + if (!tool_choice.empty()) { + if (tool_choice == "none" || tool_choice == "auto" || tool_choice == "required") { + b.set("tool_choice", Json(tool_choice)); + } else { + Json tc = Json::object(); + tc.set("type", Json("function")); + tc.set("name", Json(tool_choice)); + b.set("tool_choice", tc); + } + } + if (top_logprobs) b.set("top_logprobs", Json(*top_logprobs)); + if (!user.empty()) b.set("user", Json(user)); + return b; +} + +// ---- results --------------------------------------------------------------- + +namespace { +std::string join_parts(const Json& output, const char* item_type, const char* part_type) { + std::string out; + for (const Json& item : output.as_array()) { + if (J::str(item, "type") != item_type) continue; + if (const Json* c = J::arr(item, "content")) + for (const Json& p : c->as_array()) + if (J::str(p, "type") == part_type) out += J::str(p, "text"); + } + return out; +} +} // namespace + +std::string ResponsesResult::output_text() const { return join_parts(output, "message", "output_text"); } +std::string ResponsesResult::reasoning_text() const { return join_parts(output, "reasoning", "reasoning_text"); } + +std::vector ResponsesResult::function_calls() const { + std::vector out; + for (const Json& item : output.as_array()) + if (J::str(item, "type") == "function_call") + out.push_back({J::str(item, "call_id"), J::str(item, "name"), J::str(item, "arguments")}); + return out; +} + +ResponsesResult ResponsesResult::parse(const Json& doc) { + if (!doc.is_object()) throw llm::ApiError("deepseek", 502, "BAD_RESPONSE", "response is not an object"); + ResponsesResult r; + r.raw = doc; + r.id = J::str(doc, "id"); + r.model = J::str(doc, "model"); + r.status = J::str(doc, "status"); + r.created_at = J::num(doc, "created_at"); + if (const Json* e = doc.find("error"); e && e->is_object()) r.error = *e; + if (const Json* d = J::obj(doc, "incomplete_details")) r.incomplete_reason = J::str(*d, "reason"); + if (const Json* o = J::arr(doc, "output")) r.output = *o; + r.usage = TokenUsage::from_response(doc.find("usage")); + return r; +} + +std::string ResponseEvent::text_delta() const { + if (type.size() > 6 && type.compare(type.size() - 6, 6, ".delta") == 0) return J::str(data, "delta"); + return ""; +} + +ResponsesResult Responses::create(const ResponsesParams& params) { + Json body = params.to_json(false); + return ResponsesResult::parse(client_->post(Calls::render(Call::kResponses), body)); +} + +ResponsesResult Responses::stream(const ResponsesParams& params, + const std::function& on_event) { + Json body = params.to_json(true); + ResponsesResult final_result; + bool terminal = false, stopped = false; + std::size_t events = 0; + client_->stream(Calls::render(Call::kResponses), body, [&](const llm::SseEvent& ev) { + if (++events > DeepseekCaps::kMaxStreamEvents) + throw llm::ApiError("deepseek", 502, "BAD_RESPONSE", "stream over the event cap"); + ResponseEvent e; + e.type = J::str(ev.data, "type", ev.event); + e.sequence_number = J::num(ev.data, "sequence_number"); + e.data = ev.data; + if (e.type == "response.completed" || e.type == "response.incomplete" || e.type == "response.failed") { + if (const Json* r = J::obj(ev.data, "response")) final_result = ResponsesResult::parse(*r); + terminal = true; + } + if (on_event && !on_event(e)) { + stopped = true; + return false; + } + return true; + }); + if (!terminal && !stopped) + throw llm::ApiError("deepseek", 502, "STREAM_TRUNCATED", "stream ended without a terminal response event"); + return final_result; +} + +} // namespace molo::deepseek diff --git a/src/deepseek/responses.h b/src/deepseek/responses.h new file mode 100644 index 0000000..dc39e4d --- /dev/null +++ b/src/deepseek/responses.h @@ -0,0 +1,99 @@ +#pragma once + +// OpenAI Responses API format, stateless: POST /responses. The server stores +// nothing (store is always false; previous_response_id, conversation, +// background, include, metadata, truncation are NOT supported), so multi-turn +// use sends the full history in `input`. Streaming ends with +// response.completed / response.incomplete / response.failed (no [DONE]). + +#include +#include +#include +#include + +#include "deepseek/types.h" +#include "llm/api_client.h" + +namespace molo::deepseek { + +struct ResponseItems { + // Input item builders. + static Json message(const std::string& role, const std::string& text); // user|assistant|system|developer + static Json message_parts(const std::string& role, const std::vector& parts); + static Json input_text(const std::string& text); + // Exactly one of image_url (http(s) or data URL) and file_id. + static Json input_image_url(const std::string& url, const std::string& detail = ""); + static Json input_image_file(const std::string& file_id); + static Json function_call(const std::string& call_id, const std::string& name, const std::string& arguments); + static Json function_call_output(const std::string& call_id, const std::string& output); + static Json function_call_output_parts(const std::string& call_id, const std::vector& parts); + static Json reasoning(const std::string& text); + // Tool definitions. + static Json function_tool(const std::string& name, const std::string& description, + const Json& parameters = Json::object()); + static Json web_search_tool(); // deepseek-v4-pro only, runs server side + static Json apply_patch_tool(); // custom tool, name apply_patch only +}; + +enum class TextFormat { kText, kJsonObject, kJsonSchema }; + +struct ResponsesParams { + std::string model = "deepseek-flash"; + std::optional input_text; // plain string input + Json input_items = Json::array(); // or an item list (used when input_text is unset) + std::string instructions; // first system message + std::string effort; // "", none, low, high, max (+ aliases) + std::optional max_output_tokens; // includes reasoning tokens + std::optional temperature; + std::optional top_p; + TextFormat format = TextFormat::kText; + std::string schema_name; // json_schema: required + Json schema = Json::object(); // json_schema: required + Json tools = Json::array(); + std::string tool_choice; // "", none, auto, required, or a function name + std::optional top_logprobs; // 0..20 + std::string user; // [A-Za-z0-9_-]{1,512} + + void validate() const; + Json to_json(bool stream = false) const; +}; + +struct FunctionCallItem { + std::string call_id, name, arguments; +}; + +struct ResponsesResult { + std::string id, model, status; // in_progress | completed | incomplete | failed + long created_at = 0; + Json error; // null unless failed + std::string incomplete_reason; // max_output_tokens | content_filter + Json output = Json::array(); + TokenUsage usage; + Json raw; + bool completed() const { return status == "completed"; } + std::string output_text() const; // all output_text parts of message items + std::string reasoning_text() const; // all reasoning_text parts of reasoning items + std::vector function_calls() const; + // Output items to append to the next request's input (stateless history). + const Json& history_items() const { return output; } + static ResponsesResult parse(const Json& doc); +}; + +struct ResponseEvent { + std::string type; // response.output_text.delta, ... + long sequence_number = 0; + Json data; + std::string text_delta() const; // delta of *.delta events, else empty +}; + +class Responses : public llm::Service { + public: + explicit Responses(std::shared_ptr client) : llm::Service(std::move(client)) {} + ResponsesResult create(const ResponsesParams& params); + // Returns the final response carried by the last event. Throws 502 + // STREAM_TRUNCATED when no terminal event arrives and the sink did not stop. + ResponsesResult stream(const ResponsesParams& params, + const std::function& on_event); +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/rules.cpp b/src/deepseek/rules.cpp new file mode 100644 index 0000000..03f0e11 --- /dev/null +++ b/src/deepseek/rules.cpp @@ -0,0 +1,87 @@ +#include "deepseek/rules.h" + +#include + +#include "deepseek/caps.h" + +namespace molo::deepseek { + +void Rules::fail(const std::string& why) { throw llm::ApiError::invalid("deepseek", why); } + +namespace { +bool word_char(char c) { + return std::isalnum(static_cast(c)) || c == '_' || c == '-'; +} +} // namespace + +void Rules::model(const std::string& name) { + require(!name.empty() && name.size() <= DeepseekCaps::kMaxModelChars, "model must be 1..128 characters"); + for (char c : name) + require(word_char(c) || c == '.' || c == ':', "model has invalid characters"); +} + +void Rules::user_id(const std::string& id) { + require(!id.empty() && id.size() <= DeepseekCaps::kMaxUserIdChars, + "user_id must be 1..512 characters"); + for (char c : id) require(word_char(c), "user_id allows only A-Z a-z 0-9 - _"); +} + +void Rules::tool_name(const std::string& name) { + require(!name.empty() && name.size() <= DeepseekCaps::kMaxToolNameChars, + "tool name must be 1..128 characters"); + for (char c : name) require(word_char(c), "tool name allows only A-Z a-z 0-9 - _"); +} + +void Rules::stop(const std::vector& stop) { + require(stop.size() <= DeepseekCaps::kMaxStopSequences, "at most 16 stop sequences"); + for (const std::string& s : stop) require(!s.empty(), "stop sequences must not be empty"); +} + +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::image_url(const std::string& url) { + require(!url.empty() && url.size() <= DeepseekCaps::kMaxImageUrlChars, + "image url must be 1..8192 characters (use a data URL or the Files API for longer)"); + bool data = url.rfind("data:image/", 0) == 0 && url.find(";base64,") != std::string::npos; + require(data || is_http_url(url, true), "image url must be http(s) or a data:image/...;base64, URL"); +} + +void Rules::detail(const std::string& d) { + require(d.empty() || d == "low" || d == "high" || d == "original" || d == "auto", + "detail must be low, high, original or auto"); +} + +void Rules::effort(const std::string& e) { + for (const char* ok : {"none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"}) + if (e == ok) return; + fail("reasoning effort must be none, low, high or max (aliases: minimal, medium, xhigh, ultra)"); +} + +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) { require(v > 0.0 && v <= 1.0, "top_p must be greater than 0 and at most 1"); } + +bool Rules::has_json_word(const std::string& text) { + for (std::size_t i = 0; i + 4 <= text.size(); ++i) + if (std::tolower(static_cast(text[i])) == 'j' && + std::tolower(static_cast(text[i + 1])) == 's' && + std::tolower(static_cast(text[i + 2])) == 'o' && + std::tolower(static_cast(text[i + 3])) == 'n') + return true; + return false; +} + +} // namespace molo::deepseek diff --git a/src/deepseek/rules.h b/src/deepseek/rules.h new file mode 100644 index 0000000..c053c19 --- /dev/null +++ b/src/deepseek/rules.h @@ -0,0 +1,38 @@ +#pragma once + +// Input rules shared by every request type. All throw llm::ApiError::invalid +// (HTTP 400 INVALID_ARGUMENT, vendor "deepseek") before any network traffic. + +#include +#include + +#include "llm/error.h" + +namespace molo::deepseek { + +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._:-]. Legacy and future names pass; the server decides. + static void model(const std::string& name); + // [A-Za-z0-9_-]{1,512} + static void user_id(const std::string& id); + // ^[A-Za-z0-9_-]{1,128}$ + static void tool_name(const std::string& name); + // 1..16 non-empty sequences + static void stop(const std::vector& stop); + // http(s) URL or data:image/...;base64, URL, <= 8192 chars + static void image_url(const std::string& url); + // "", low, high, original, auto + static void detail(const std::string& detail); + // none, minimal, low, medium, high, xhigh, max, ultra + static void effort(const std::string& effort); + static void range(double v, double lo, double hi, const char* what); + static void top_p(double v); // (0, 1] + static bool has_json_word(const std::string& text); // case-insensitive "json" + static bool is_http_url(const std::string& url, bool allow_userinfo = false); +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/tools/check_spec.py b/src/deepseek/tools/check_spec.py new file mode 100644 index 0000000..7a80838 --- /dev/null +++ b/src/deepseek/tools/check_spec.py @@ -0,0 +1,168 @@ +#!/usr/bin/env python3 +"""Check src/deepseek/calls.cpp against DeepSeek's published API documentation. + +DeepSeek does not publish its OpenAPI file for download (the docs site is +built from a private openapi.yaml; /openapi.json answers an HTML page). What +is public is the reference rendered from that document, one page per +operation, plus the guides. This checker reads those pages as text and fails +(exit 1) when: + + row a declared call's HTTP method or path is not shown on its page + (beta rows are checked against the page of the non-beta twin and the + page must mention https://api.deepseek.com/beta); + field a request body field, query parameter or response schema field we + send or read is not a field of the page; + coverage a /api/* page of the site map is neither a declared call's page nor + in EXCLUDED_PAGES. + +Python 3 stdlib only, no credentials, network required. + + python3 -I src/deepseek/tools/check_spec.py [alternative calls.cpp] +""" +import os +import re +import sys +import urllib.request +from html.parser import HTMLParser + +HERE = os.path.dirname(os.path.abspath(__file__)) +CALLS = os.path.join(HERE, "..", "calls.cpp") +SITE = "https://api-docs.deepseek.com/" +# Pages of /api/ that are not an operation. +EXCLUDED_PAGES = {"api/deepseek-api": "overview and bearer scheme, no operation"} +STR = re.compile(r'"([^"]*)"') + + +class Text(HTMLParser): + def __init__(self): + super().__init__() + self.out, self.skip = [], 0 + + def handle_starttag(self, tag, attrs): + if tag in ("script", "style", "nav", "svg"): + self.skip += 1 + if tag in ("p", "div", "li", "tr", "h1", "h2", "h3", "h4", "br", "pre", "summary", "details"): + self.out.append("\n") + + def handle_endtag(self, tag): + if tag in ("script", "style", "nav", "svg"): + self.skip -= 1 + + def handle_data(self, data): + if not self.skip: + self.out.append(data) + + +def fetch(url): + req = urllib.request.Request(url, headers={"User-Agent": "molo-deepseek-spec-check/1"}) + with urllib.request.urlopen(req, timeout=60) as r: + return r.read().decode("utf-8", "replace") + + +_pages = {} + + +def page_lines(doc): + if doc not in _pages: + parser = Text() + parser.feed(fetch(SITE + doc)) + text = "".join(parser.out) + _pages[doc] = [l.strip() for l in text.splitlines() if l.strip()] + return _pages[doc] + + +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 + + +def has_field(lines, field, api_page): + if api_page: + return any(l == field or l.startswith(field + " ") for l in lines) + # guides: JSON keys and prose, or table rows such as "stop_sequencesFully Supported" + word = re.compile(r'(?.create + m = re.match(r"^(/anthropic)/v1/([a-z]+)$", path) + return bool(m) and ("api.deepseek.com" + m.group(1)) in joined and ("." + m.group(2) + ".create(") in joined + + +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") + bad = [] + used_pages = set() + for method, path, doc, body, query, response in calls: + api_page = doc.startswith("api/") + lines = page_lines(doc) + used_pages.add(doc) + beta = path.startswith("/beta/") + check_path = path[len("/beta"):] if beta else path + if beta and not any("api.deepseek.com/beta" in l for l in lines): + bad.append("%s %s: page %s does not mention api.deepseek.com/beta" % (method, path, doc)) + if not has_route(lines, method, check_path, api_page): + bad.append("%s %s: route not shown on %s" % (method, path, doc)) + for f in filter(None, body.split(",")): + if not has_field(lines, f, api_page): + bad.append("%s %s: body field %s absent on %s" % (method, path, f, doc)) + for q in filter(None, query.split(",")): + if not has_field(lines, q, api_page): + bad.append("%s %s: query parameter %s absent on %s" % (method, path, q, doc)) + if not any(r[4] == "" for r in calls): + pass + schema_names = {r[0] for r in schemas} + for method, path, doc, body, query, response in calls: + if response not in schema_names: + bad.append("%s %s: response schema %s not in the schema table" % (method, path, response)) + for name, doc, fields in schemas: + lines = page_lines(doc) + for f in fields.split(","): + if not has_field(lines, f, doc.startswith("api/")): + bad.append("schema %s: field %s absent on %s" % (name, f, doc)) + # coverage against the site map + sitemap = fetch(SITE + "sitemap.xml") + found = {re.sub(r"^https://api-docs\.deepseek\.com/", "", u) + for u in re.findall(r"([^<]*)", sitemap) if "/api/" in u} + # the site map lags the sidebar (api/search was live before it listed it): + # the sidebar links of a reference page are the second source. + found |= {h.lstrip("/") for h in re.findall(r'href="(/api/[a-z0-9-]+)"', fetch(SITE + "api/fetch"))} + api_pages = sorted(found) + for p in api_pages: + if p not in used_pages and p not in EXCLUDED_PAGES: + bad.append("unwrapped reference page %s (add a row or an exclusion)" % p) + for p in used_pages: + if p.startswith("api/") and p not in api_pages: + bad.append("declared page %s is not in the site map" % p) + if bad: + print("SPEC CHECK FAILED") + for b in bad: + print(" " + b) + return 1 + print("deepseek spec ok: %d calls, %d schemas, %d reference pages all covered (exclusion list: %d)" + % (len(calls), len(schemas), len(api_pages), len(EXCLUDED_PAGES))) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/src/deepseek/types.cpp b/src/deepseek/types.cpp new file mode 100644 index 0000000..b52b37b --- /dev/null +++ b/src/deepseek/types.cpp @@ -0,0 +1,216 @@ +#include "deepseek/types.h" + +#include "deepseek/caps.h" + +namespace molo::deepseek { + +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; +} +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; +} + +namespace { +int as_int(const Json& doc, const char* key) { return static_cast(J::num(doc, key)); } + +std::vector strings(const Json& doc, const char* key) { + std::vector out; + if (const Json* a = J::arr(doc, key)) + for (const Json& v : a->as_array()) + if (v.is_string()) out.push_back(v.as_string()); + return out; +} +} // namespace + +TokenUsage TokenUsage::from_completion(const Json* usage) { + TokenUsage u; + if (!usage || !usage->is_object()) return u; + u.present = true; + u.input_tokens = as_int(*usage, "prompt_tokens"); + u.output_tokens = as_int(*usage, "completion_tokens"); + u.total_tokens = as_int(*usage, "total_tokens"); + u.cache_hit_tokens = as_int(*usage, "prompt_cache_hit_tokens"); + u.cache_miss_tokens = as_int(*usage, "prompt_cache_miss_tokens"); + if (const Json* d = J::obj(*usage, "prompt_tokens_details")) + if (!usage->has("prompt_cache_hit_tokens")) u.cache_hit_tokens = as_int(*d, "cached_tokens"); + if (const Json* d = J::obj(*usage, "completion_tokens_details")) + u.reasoning_tokens = as_int(*d, "reasoning_tokens"); + return u; +} + +TokenUsage TokenUsage::from_response(const Json* usage) { + TokenUsage u; + if (!usage || !usage->is_object()) return u; + u.present = true; + u.input_tokens = as_int(*usage, "input_tokens"); + u.output_tokens = as_int(*usage, "output_tokens"); + u.total_tokens = as_int(*usage, "total_tokens"); + if (const Json* d = J::obj(*usage, "input_tokens_details")) + u.cache_hit_tokens = as_int(*d, "cached_tokens"); + u.cache_miss_tokens = u.input_tokens - u.cache_hit_tokens; + if (u.cache_miss_tokens < 0) u.cache_miss_tokens = 0; + if (const Json* d = J::obj(*usage, "output_tokens_details")) + u.reasoning_tokens = as_int(*d, "reasoning_tokens"); + return u; +} + +TokenUsage TokenUsage::from_anthropic(const Json* usage) { + TokenUsage u; + if (!usage || !usage->is_object()) return u; + u.present = true; + u.input_tokens = as_int(*usage, "input_tokens"); + u.output_tokens = as_int(*usage, "output_tokens"); + u.total_tokens = u.input_tokens + u.output_tokens; + return u; +} + +double TokenUsage::cache_hit_ratio() const { + int seen = cache_hit_tokens + cache_miss_tokens; + return seen > 0 ? static_cast(cache_hit_tokens) / seen : 0.0; +} + +bool ModelInfo::accepts_images() const { + for (const std::string& m : input_modalities) + if (m == "image") return true; + return false; +} + +ModelInfo ModelInfo::parse(const Json& doc) { + ModelInfo m; + m.id = J::str(doc, "id"); + m.owned_by = J::str(doc, "owned_by"); + m.name = J::str(doc, "name"); + m.context_window = J::num(doc, "context_window"); + m.max_output_tokens = J::num(doc, "max_output_tokens"); + m.input_modalities = strings(doc, "input_modalities"); + m.output_modalities = strings(doc, "output_modalities"); + if (const Json* e = J::obj(doc, "effort")) { + m.effort_levels = strings(*e, "supported_levels"); + m.effort_default = J::str(*e, "default_level"); + } + if (const Json* c = J::obj(doc, "api_capabilities")) + if (const Json* a = J::obj(*c, "anthropic_messages")) + m.system_prompt_update = J::str(*a, "system_prompt_update"); + return m; +} + +ModelList ModelList::parse(const Json& doc) { + ModelList out; + out.raw = doc; + if (const Json* d = J::arr(doc, "data")) + for (const Json& m : d->as_array()) { + if (out.models.size() >= DeepseekCaps::kMaxModelsReturned) { + out.truncated = true; + break; + } + if (m.is_object()) out.models.push_back(ModelInfo::parse(m)); + } + return out; +} + +const ModelInfo* ModelList::find(const std::string& id) const { + for (const ModelInfo& m : models) + if (m.id == id) return &m; + return nullptr; +} + +Balance Balance::parse(const Json& doc) { + Balance b; + b.raw = doc; + b.available = J::flag(doc, "is_available"); + if (const Json* a = J::arr(doc, "balance_infos")) + for (const Json& e : a->as_array()) { + if (!e.is_object()) continue; + BalanceEntry x; + x.currency = J::str(e, "currency"); + x.total = J::str(e, "total_balance"); + x.granted = J::str(e, "granted_balance"); + x.topped_up = J::str(e, "topped_up_balance"); + b.entries.push_back(x); + } + return b; +} + +FileInfo FileInfo::parse(const Json& doc) { + FileInfo f; + f.id = J::str(doc, "id"); + f.bytes = J::num(doc, "bytes"); + f.created_at = J::num(doc, "created_at"); + f.filename = J::str(doc, "filename"); + f.purpose = J::str(doc, "purpose"); + if (const Json* e = doc.find("expires_at"); e && e->is_number()) f.expires_at = e->as_int(); + return f; +} + +FileInfo FileInfo::parse_anthropic(const Json& doc) { + FileInfo f; + f.id = J::str(doc, "id"); + f.bytes = J::num(doc, "size_bytes"); + f.created_text = J::str(doc, "created_at"); + f.filename = J::str(doc, "filename"); + f.mime_type = J::str(doc, "mime_type"); + return f; +} + +FileList FileList::parse(const Json& doc, bool anthropic) { + FileList out; + out.first_id = J::str(doc, "first_id"); + out.last_id = J::str(doc, "last_id"); + out.has_more = J::flag(doc, "has_more"); + if (const Json* d = J::arr(doc, "data")) + for (const Json& f : d->as_array()) { + if (!f.is_object()) continue; + if (out.files.size() >= DeepseekCaps::kMaxFilesReturned) { + out.truncated = true; + break; + } + out.files.push_back(anthropic ? FileInfo::parse_anthropic(f) : FileInfo::parse(f)); + } + return out; +} + +SearchResults SearchResults::parse(const Json& doc) { + SearchResults out; + if (const Json* r = J::arr(doc, "results")) + for (const Json& h : r->as_array()) { + if (!h.is_object()) continue; + SearchHit x; + const Json* score = h.find("rerank_score"); + x.rerank_score = score && score->is_number() ? score->as_number() : 0.0; + x.title = J::str(h, "title"); + x.url = J::str(h, "url"); + x.snippet = J::str(h, "snippet"); + x.summary = J::str(h, "summary"); + x.content = J::str(h, "content"); + x.site_name = J::str(h, "site_name"); // null stays empty + x.site_icon = J::str(h, "site_icon"); + x.date = J::str(h, "date"); + x.authority = static_cast(J::num(h, "authority", -1)); + out.hits.push_back(x); + } + return out; +} + +FetchResult FetchResult::parse(const Json& doc) { + FetchResult f; + f.title = J::str(doc, "title"); + f.content = J::str(doc, "content"); + return f; +} + +} // namespace molo::deepseek diff --git a/src/deepseek/types.h b/src/deepseek/types.h new file mode 100644 index 0000000..7d76946 --- /dev/null +++ b/src/deepseek/types.h @@ -0,0 +1,123 @@ +#pragma once + +// Typed views of DeepSeek documents: usage, models, balance, files, search, +// fetch. Every parser reads only fields the call table declares; the full +// document stays available as `raw`. + +#include +#include +#include + +#include "clients/body/json.h" + +namespace molo::deepseek { + +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 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); +}; + +// One usage shape for chat, FIM, Responses and Anthropic documents. +struct TokenUsage { + int input_tokens = 0; + int output_tokens = 0; + int total_tokens = 0; + int cache_hit_tokens = 0; // prompt_cache_hit_tokens / cached_tokens + int cache_miss_tokens = 0; // prompt_cache_miss_tokens + int reasoning_tokens = 0; + bool present = false; + + // chat.completion / text_completion / chunk usage + static TokenUsage from_completion(const Json* usage); + // Responses API usage (input_tokens / output_tokens) + static TokenUsage from_response(const Json* usage); + // Anthropic-compatible usage (input_tokens / output_tokens) + static TokenUsage from_anthropic(const Json* usage); + // Share of the prompt served from the context cache, 0..1 (0 when empty). + double cache_hit_ratio() const; +}; + +struct ModelInfo { + std::string id; + std::string owned_by; + std::string name; + long context_window = 0; + long max_output_tokens = 0; + std::vector input_modalities; + std::vector output_modalities; + std::vector effort_levels; // supported_levels, thinking mode on + std::string effort_default; + std::string system_prompt_update; // anthropic_messages: leading-only | in-history + bool accepts_images() const; + static ModelInfo parse(const Json& doc); +}; + +struct ModelList { + std::vector models; + bool truncated = false; + Json raw; + static ModelList parse(const Json& doc); + const ModelInfo* find(const std::string& id) const; +}; + +struct BalanceEntry { + std::string currency; // CNY | USD + std::string total; // decimal strings, as sent + std::string granted; + std::string topped_up; +}; + +struct Balance { + bool available = false; + std::vector entries; + Json raw; + static Balance parse(const Json& doc); +}; + +struct FileInfo { + std::string id; // file-api-... + long bytes = 0; + long created_at = 0; // unix seconds (Anthropic surface: parsed from RFC 3339 is not done; see created_text) + std::string created_text; + std::string filename; + std::string purpose; + std::string mime_type; // Anthropic surface only + std::optional expires_at; + static FileInfo parse(const Json& doc); // OpenAI-compatible shape + static FileInfo parse_anthropic(const Json& doc); // size_bytes / created_at RFC 3339 +}; + +struct FileList { + std::vector files; + std::string first_id; + std::string last_id; + bool has_more = false; + bool truncated = false; // more pages exist than the walk cap allowed + static FileList parse(const Json& doc, bool anthropic); +}; + +struct SearchHit { + double rerank_score = 0; + std::string title, url, snippet, summary, content, site_name, site_icon, date; + int authority = -1; + bool high_quality() const { return rerank_score >= 1.5; } // documented threshold +}; + +struct SearchResults { + std::vector hits; + static SearchResults parse(const Json& doc); +}; + +struct FetchResult { + std::string title; + std::string content; // Markdown + static FetchResult parse(const Json& doc); +}; + +} // namespace molo::deepseek diff --git a/src/deepseek/web.cpp b/src/deepseek/web.cpp new file mode 100644 index 0000000..02978ee --- /dev/null +++ b/src/deepseek/web.cpp @@ -0,0 +1,60 @@ +#include "deepseek/web.h" + +#include "deepseek/calls.h" +#include "deepseek/caps.h" +#include "deepseek/rules.h" + +namespace molo::deepseek { + +namespace { +// Unicode characters, not bytes: count UTF-8 lead bytes. +std::size_t chars_of(const std::string& s) { + std::size_t n = 0; + for (unsigned char c : s) + if ((c & 0xC0) != 0x80) ++n; + return n; +} +bool blank(const std::string& s) { return s.find_first_not_of(" \t\r\n") == std::string::npos; } +} // namespace + +void SearchParams::validate() const { + Rules::require(!blank(query), "query must not be empty or all whitespace"); + Rules::require(chars_of(query) <= DeepseekCaps::kSearchQueryChars, "query over 128 characters"); + Rules::require(count >= 1 && count <= DeepseekCaps::kSearchMaxCount, "count must be 1..50"); + if (ori_question) { + Rules::require(!ori_question->empty(), "ori_question must not be empty when given"); + Rules::require(chars_of(*ori_question) <= DeepseekCaps::kSearchQueryChars, + "ori_question over 128 characters"); + } +} + +Json SearchParams::to_json() const { + validate(); + Json b = Json::object(); + b.set("query", Json(query)); + b.set("count", Json(count)); + if (ori_question) b.set("ori_question", Json(*ori_question)); + if (!localization.empty()) b.set("localization", Json(localization)); + if (need_content) b.set("need_content", Json(true)); + return b; +} + +void Web::validate_url(const std::string& url) { + Rules::require(!url.empty() && url.size() <= DeepseekCaps::kFetchUrlChars, "url must be 1..8192 characters"); + Rules::require(Rules::is_http_url(url, false), + "url must be http(s) with a host and without username or password"); +} + +SearchResults Web::search(const SearchParams& params) { + Json body = params.to_json(); + return SearchResults::parse(client_->post(Calls::render(Call::kSearch), body)); +} + +FetchResult Web::fetch(const std::string& url) { + validate_url(url); + Json body = Json::object(); + body.set("url", Json(url)); + return FetchResult::parse(client_->post(Calls::render(Call::kFetch), body)); +} + +} // namespace molo::deepseek diff --git a/src/deepseek/web.h b/src/deepseek/web.h new file mode 100644 index 0000000..641f6fd --- /dev/null +++ b/src/deepseek/web.h @@ -0,0 +1,35 @@ +#pragma once + +// Search and Fetch API (raw JSON, same bearer key): POST /v1/tools/search and +// POST /v1/tools/fetch. Billed per successful request ($0.75 per 1000); QPS +// limits per account: Search 100, Fetch 25 (plus a per-domain Fetch limit). +// Failed requests, empty results and timeouts are not billed. + +#include +#include + +#include "deepseek/types.h" +#include "llm/api_client.h" + +namespace molo::deepseek { + +struct SearchParams { + std::string query; // 1..128 chars, not all whitespace + int count = 10; // 1..50 + std::optional ori_question; // 1..128 chars + std::string localization; // optional IP address + bool need_content = false; + void validate() const; + Json to_json() const; +}; + +class Web : public llm::Service { + public: + explicit Web(std::shared_ptr client) : llm::Service(std::move(client)) {} + SearchResults search(const SearchParams& params); + // http(s) URL with a host, <= 8192 chars, no username or password. + FetchResult fetch(const std::string& url); + static void validate_url(const std::string& url); +}; + +} // namespace molo::deepseek diff --git a/tests/example/ai/deepseek/page_test.cpp b/tests/example/ai/deepseek/page_test.cpp new file mode 100644 index 0000000..a9c5031 --- /dev/null +++ b/tests/example/ai/deepseek/page_test.cpp @@ -0,0 +1,35 @@ +// Routes: GET /ai/deepseek (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("DEEPSEEK_API_KEY"); + Fixture f; + auto page = f.client->get("/ai/deepseek"); + check(page.status == 200, "page 200"); + check(contains(page.headers.get("Content-Type"), "text/html"), "html"); + check(contains(page.body, "DeepSeek API") && contains(page.body, "viewport"), "title and mobile viewport"); + check(contains(page.body, "/embedded/ai_deepseek.js"), "script wired"); + check(f.client->post("/ai/deepseek", "{}", "application/json").status == 405, "post page is 405"); + + auto st = f.client->get("/ai/deepseek/status"); + check(st.status == 200 && contains(st.body, "\"configured\":false"), "status without a key"); + check(contains(st.body, "DEEPSEEK_API_KEY") && contains(st.body, "deepseek-flash") && + contains(st.body, "deepseek-v4-pro"), + "status names credential env and models"); + check(f.client->post("/ai/deepseek/status", "{}", "application/json").status == 405, "post status is 405"); + + auto calls = f.client->get("/ai/deepseek/calls"); + check(calls.status == 200 && contains(calls.body, "/chat/completions") && + contains(calls.body, "/beta/completions") && contains(calls.body, "/user/balance"), + "call table listed"); + auto errors = f.client->get("/ai/deepseek/errors"); + check(errors.status == 200 && contains(errors.body, "Insufficient Balance") && + contains(errors.body, "\"retryable\":true"), + "error table listed"); + return finish("ai/deepseek/page"); +} diff --git a/tests/example/ai/deepseek/routes_test.cpp b/tests/example/ai/deepseek/routes_test.cpp new file mode 100644 index 0000000..9fcb531 --- /dev/null +++ b/tests/example/ai/deepseek/routes_test.cpp @@ -0,0 +1,69 @@ +// Routes: POST /ai/deepseek/* (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("DEEPSEEK_API_KEY"); + Fixture f; + auto post = [&](const std::string& route, const std::string& body) { + return f.client->post("/ai/deepseek/" + route, body, "application/json"); + }; + const char* all[] = {"chat", "stream", "prefix", "tools", "fim", "responses", "anthropic", + "models", "balance", "files", "search", "fetch"}; + for (const char* r : all) { + std::string route = std::string("/ai/deepseek/") + 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 || std::string(r) == "models" || std::string(r) == "balance", + route + " non-object is 422"); + } + // 422: input rules run before anything else + check(post("chat", "{}").status == 422, "chat needs prompt"); + check(post("chat", "{\"prompt\":\"hi\",\"max_tokens\":0}").status == 422, "max_tokens 0"); + check(post("chat", "{\"prompt\":\"hi\",\"effort\":\"loud\"}").status == 422, "bad effort"); + check(post("chat", "{\"prompt\":\"hi\",\"json\":true}").status == 422, "json mode needs the word json"); + check(post("chat", "{\"prompt\":\"hi\",\"thinking\":\"maybe\"}").status == 422, "bad thinking"); + check(post("prefix", "{\"prompt\":\"hi\"}").status == 422, "prefix needs prefix"); + check(post("fim", "{\"prompt\":\"x\",\"max_tokens\":5000}").status == 422, "fim max_tokens over 4096"); + check(post("responses", "{}").status == 422, "responses needs input or instructions"); + check(post("anthropic", "{\"prompt\":\"hi\",\"effort\":\"turbo\"}").status == 422, "bad anthropic effort"); + check(post("files", "{\"action\":\"fly\"}").status == 422, "bad files action"); + check(post("files", "{\"action\":\"get\",\"id\":\"../x\"}").status == 422, "bad file id"); + check(post("files", "{\"action\":\"upload\",\"filename\":\"a.png\",\"data_base64\":\"@@\"}").status == 422, "bad base64"); + check(post("files", "{\"action\":\"upload\",\"filename\":\"a.txt\",\"data_base64\":\"aGVsbG8=\"}").status == 422, "not an image"); + check(post("search", "{\"query\":\" \"}").status == 422, "blank query"); + check(post("search", "{\"query\":\"x\",\"count\":51}").status == 422, "count over 50"); + check(post("fetch", "{\"url\":\"ftp://x\"}").status == 422, "fetch needs http(s)"); + + // dry runs: paid or resource-changing routes show the exact request + auto dry = post("chat", "{\"prompt\":\"hi\",\"thinking\":\"enabled\"}"); + check(dry.status == 200 && contains(dry.body, "\"dry_run\":true") && contains(dry.body, "\"model\":\"deepseek-flash\"") && + contains(dry.body, "/chat/completions"), + "chat is a dry run without confirm"); + check(contains(post("prefix", "{\"prompt\":\"hi\",\"prefix\":\"```\"}").body, "/beta/chat/completions"), "prefix targets beta"); + check(contains(post("tools", "{\"prompt\":\"w\",\"strict\":true}").body, "\"strict\":true"), "strict tools preview"); + check(contains(post("fim", "{\"prompt\":\"def f():\"}").body, "/beta/completions"), "fim targets beta"); + check(contains(post("search", "{\"query\":\"x\"}").body, "\"dry_run\":true"), "search is a dry run"); + check(contains(post("files", "{\"action\":\"delete\",\"id\":\"file-api-1\"}").body, "\"dry_run\":true"), "delete is a dry run"); + check(contains(post("files", "{\"action\":\"upload\",\"filename\":\"a.png\",\"data_base64\":\"iVBORw0KGgo=\"}").body, "\"format\":\"png\""), + "upload is a dry run"); + + // 503: free calls and confirmed calls need the credential + for (const char* r : {"models", "balance"}) { + auto res = post(r, "{}"); + check(res.status == 503 && contains(res.body, "deepseek_not_configured"), std::string(r) + " without key is 503"); + } + check(post("files", "{\"action\":\"list\"}").status == 503, "files list without key is 503"); + check(post("files", "{\"action\":\"get\",\"id\":\"file-api-1\"}").status == 503, "files get without key is 503"); + check(post("chat", "{\"prompt\":\"hi\",\"confirm\":true}").status == 503, "confirmed chat without key is 503"); + check(post("stream", "{\"prompt\":\"hi\",\"confirm\":true}").status == 503, "confirmed stream without key is 503"); + check(post("anthropic", "{\"prompt\":\"hi\",\"confirm\":true}").status == 503, "confirmed anthropic without key is 503"); + check(post("responses", "{\"input\":\"hi\",\"confirm\":true}").status == 503, "confirmed responses without key is 503"); + check(post("fetch", "{\"url\":\"https://example.com\",\"confirm\":true}").status == 503, "confirmed fetch without key is 503"); + check(post("files", "{\"action\":\"delete\",\"id\":\"file-api-1\",\"confirm\":true}").status == 503, "confirmed delete without key is 503"); + return finish("ai/deepseek/routes"); +} diff --git a/tests/src/deepseek/support.h b/tests/src/deepseek/support.h new file mode 100644 index 0000000..d29ad2e --- /dev/null +++ b/tests/src/deepseek/support.h @@ -0,0 +1,59 @@ +#pragma once + +// Shared rig for the DeepSeek tests: a Platform over two MockTransports (one +// per surface) with a fake key. The mock only records the requests the real +// client builds; replies are documented examples taken verbatim from +// api-docs.deepseek.com and labelled FIXTURE where they appear. Nothing here +// verifies vendor behavior (see src/deepseek/SPEC.md ## Unverified). + +#include +#include + +#include "clients/transports/mock_transport.h" +#include "deepseek/platform.h" +#include "framework.h" + +namespace deepseek_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 const char* kKey = "sk-TESTKEY-DO-NOT-LEAK"; + +struct Rig { + MockTransport* openai = nullptr; + MockTransport* anthropic = nullptr; + molo::deepseek::Platform platform; + + explicit Rig(const std::string& key = kKey) { + auto a = std::make_unique(); + auto b = std::make_unique(); + openai = a.get(); + anthropic = b.get(); + platform = molo::deepseek::Platform::with(std::move(a), std::move(b), key); + } + // Allows a path to answer more than once (retried statuses). + void always(MockTransport* t, Method m, const std::string& path, ClientResponse r, int times = 5) { + MockExpectation e; + e.method = m; + e.path = path; + e.response = std::move(r); + e.times = times; + t->expect(e); + } +}; + +} // namespace deepseek_test diff --git a/tests/src/deepseek/test_chat_flow.cpp b/tests/src/deepseek/test_chat_flow.cpp new file mode 100644 index 0000000..c1c3b75 --- /dev/null +++ b/tests/src/deepseek/test_chat_flow.cpp @@ -0,0 +1,428 @@ +// DeepSeek chat over the real ApiClient with a recording transport. Replies +// are documented examples (FIXTURE, verbatim from api-docs.deepseek.com); +// the assertions are on what WE send and on how WE parse them. +#include "deepseek/chat.h" +#include "deepseek/chat_model.h" +#include "deepseek/errors.h" +#include "support.h" + +using namespace molo::deepseek; +using namespace deepseek_test; +using molo::llm::ApiError; + +namespace { +bool has(const std::string& hay, const std::string& needle) { return hay.find(needle) != std::string::npos; } + +// FIXTURE: api/create-chat-completion "Example" (200, no streaming) +const char* kChatExample = + "{\"id\":\"930c60df-bf64-41c9-a88e-3ec75f81e00e\",\"choices\":[{\"finish_reason\":\"stop\",\"index\":0," + "\"message\":{\"content\":\"Hello! How can I help you today?\",\"role\":\"assistant\"},\"logprobs\":null}]," + "\"created\":1705651092,\"model\":\"deepseek-flash\",\"object\":\"chat.completion\",\"system_fingerprint\":\"fp_7a09fdf9c2\"," + "\"usage\":{\"completion_tokens\":10,\"prompt_tokens\":16,\"total_tokens\":26,\"prompt_tokens_details\":{\"cached_tokens\":0}," + "\"prompt_cache_hit_tokens\":0,\"prompt_cache_miss_tokens\":16}}"; + +// FIXTURE: api/create-chat-completion "200 (Streaming)" example, with the +// keep-alive comment the Rate Limit guide documents (": keep-alive") added +// between events and one empty line before the first byte. +const char* kStreamExample = + ": keep-alive\n\n" + "data: {\"id\": \"1f633d8bfc032625086f14113c411638\", \"choices\": [{\"index\": 0, \"delta\": {\"content\": \"\", \"role\": \"assistant\"}, \"finish_reason\": null, \"logprobs\": null}], \"created\": 1718345013, \"model\": \"deepseek-flash\", \"system_fingerprint\": \"fp_a49d71b8a1\", \"object\": \"chat.completion.chunk\"}\n\n" + "data: {\"choices\": [{\"delta\": {\"content\": \"Hello\", \"role\": \"assistant\"}, \"finish_reason\": null, \"index\": 0, \"logprobs\": null}], \"created\": 1718345013, \"id\": \"1f633d8bfc032625086f14113c411638\", \"model\": \"deepseek-flash\", \"object\": \"chat.completion.chunk\", \"system_fingerprint\": \"fp_a49d71b8a1\"}\n\n" + ": keep-alive\n\n" + "data: {\"choices\": [{\"delta\": {\"content\": \"!\", \"role\": \"assistant\"}, \"finish_reason\": null, \"index\": 0, \"logprobs\": null}], \"created\": 1718345013, \"id\": \"1f633d8bfc032625086f14113c411638\", \"model\": \"deepseek-flash\", \"object\": \"chat.completion.chunk\", \"system_fingerprint\": \"fp_a49d71b8a1\"}\n\n" + "data: {\"choices\": [{\"delta\": {\"content\": \"\", \"role\": null}, \"finish_reason\": \"stop\", \"index\": 0, \"logprobs\": null}], \"created\": 1718345013, \"id\": \"1f633d8bfc032625086f14113c411638\", \"model\": \"deepseek-flash\", \"object\": \"chat.completion.chunk\", \"system_fingerprint\": \"fp_a49d71b8a1\", \"usage\": {\"completion_tokens\": 9, \"prompt_tokens\": 17, \"total_tokens\": 26, \"prompt_tokens_details\": {\"cached_tokens\": 0}, \"prompt_cache_hit_tokens\": 0, \"prompt_cache_miss_tokens\": 17}}\n\n" + "data: [DONE]\n\n"; + +// Thinking-mode transcript shaped like the documented sample output +// (guides/thinking_mode, "Turn 1.1": reasoning_content, content and a get_date +// tool call). Built from the guide's values; the framing is the documented +// chunk shape. LABELLED: not a recorded vendor response. +const char* kThinkingToolStream = + "data: {\"id\":\"s1\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":null,\"reasoning_content\":\"The user is asking about the weather\"},\"finish_reason\":null}],\"created\":1,\"model\":\"deepseek-flash\",\"object\":\"chat.completion.chunk\"}\n\n" + "data: {\"id\":\"s1\",\"choices\":[{\"index\":0,\"delta\":{\"reasoning_content\":\" in Hangzhou tomorrow.\"},\"finish_reason\":null}],\"created\":1,\"model\":\"deepseek-flash\",\"object\":\"chat.completion.chunk\"}\n\n" + "data: {\"id\":\"s1\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Let me check.\"},\"finish_reason\":null}],\"created\":1,\"model\":\"deepseek-flash\",\"object\":\"chat.completion.chunk\"}\n\n" + "data: {\"id\":\"s1\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"id\":\"call_00_kw66qNnNto11bSfJVIdlV5Oo\",\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"arguments\":\"\"}}]},\"finish_reason\":null}],\"created\":1,\"model\":\"deepseek-flash\",\"object\":\"chat.completion.chunk\"}\n\n" + "data: {\"id\":\"s1\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"{\\\"location\\\": \"}}]},\"finish_reason\":null}],\"created\":1,\"model\":\"deepseek-flash\",\"object\":\"chat.completion.chunk\"}\n\n" + "data: {\"id\":\"s1\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"\\\"Hangzhou\\\"}\"}}]},\"finish_reason\":null}],\"created\":1,\"model\":\"deepseek-flash\",\"object\":\"chat.completion.chunk\"}\n\n" + "data: {\"id\":\"s1\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\"},\"finish_reason\":\"tool_calls\"}],\"created\":1,\"model\":\"deepseek-flash\",\"object\":\"chat.completion.chunk\",\"usage\":{\"completion_tokens\":30,\"prompt_tokens\":100,\"total_tokens\":130,\"prompt_cache_hit_tokens\":64,\"prompt_cache_miss_tokens\":36,\"completion_tokens_details\":{\"reasoning_tokens\":12}}}\n\n" + "data: [DONE]\n\n"; +} // namespace + +TEST(deepseek_flow, create_sends_bearer_json_and_parses_the_documented_example) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/chat/completions", reply(kChatExample)); + Chat chat(rig.platform.openai); + ChatParams p = ChatParams::prompt("Hello!"); + p.add(Messages::system("You are a helpful assistant.")); + ChatResult r = chat.create(p); + ASSERT_EQ(r.first().content, "Hello! How can I help you today?"); + ASSERT_EQ(r.first().finish_reason, "stop"); + ASSERT_EQ(r.model, "deepseek-flash"); + ASSERT_EQ(r.created, 1705651092L); + ASSERT_EQ(r.usage.input_tokens, 16); + ASSERT_EQ(r.usage.output_tokens, 10); + ASSERT_EQ(r.usage.cache_miss_tokens, 16); + ASSERT_EQ(r.usage.cache_hit_tokens, 0); + ASSERT_EQ(r.usage.cache_hit_ratio(), 0.0); + auto s = rig.openai->seen()[0]; + ASSERT_EQ(s.method, "POST"); + ASSERT_EQ(s.headers.get_or("Authorization", ""), std::string("Bearer ") + kKey); + ASSERT_TRUE(has(s.headers.get_or("Content-Type", ""), "application/json")); + ASSERT_TRUE(has(s.body, "\"model\":\"deepseek-flash\"")); + ASSERT_EQ(rig.anthropic->send_count(), 0u); + ASSERT_EQ(s.target.find(kKey), std::string::npos); +} + +TEST(deepseek_flow, keep_alive_blank_lines_before_the_json_body_are_harmless) { + // Rate Limit guide: non-streaming requests may receive empty lines first. + Rig rig; + rig.openai->expect_response(Method::kPost, "/chat/completions", reply(std::string("\n\n\n") + kChatExample)); + Chat chat(rig.platform.openai); + ASSERT_EQ(chat.create(ChatParams::prompt("hi")).first().content, "Hello! How can I help you today?"); +} + +TEST(deepseek_flow, not_configured_has_no_traffic) { + Rig rig(""); + Chat chat(rig.platform.openai); + try { + chat.create(ChatParams::prompt("hi")); + FAIL("expected"); + } catch (const molo::llm::NotConfiguredError& e) { + ASSERT_EQ(e.http_status(), 503); + ASSERT_TRUE(has(e.message(), "DEEPSEEK_API_KEY")); + } + ASSERT_EQ(rig.openai->send_count(), 0u); + ASSERT_FALSE(rig.platform.configured()); +} + +TEST(deepseek_flow, invalid_input_never_reaches_the_network) { + Rig rig; + Chat chat(rig.platform.openai); + ChatParams p; + ASSERT_THROW(chat.create(p), ApiError); + ASSERT_THROW(chat.stream(p, nullptr), ApiError); + ASSERT_EQ(rig.openai->send_count(), 0u); +} + +TEST(deepseek_flow, stream_documented_transcript_with_keep_alive_comments) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/chat/completions", sse(kStreamExample)); + Chat chat(rig.platform.openai); + std::string text; + int chunks = 0; + ChatResult r = chat.stream(ChatParams::prompt("Hi"), [&](const StreamDelta& d) { + text += d.content; + ++chunks; + return true; + }); + ASSERT_EQ(text, "Hello!"); + ASSERT_EQ(chunks, 4); // the ": keep-alive" comments produce no chunk + ASSERT_EQ(r.first().content, "Hello!"); + ASSERT_EQ(r.first().finish_reason, "stop"); + ASSERT_EQ(r.id, "1f633d8bfc032625086f14113c411638"); + ASSERT_EQ(r.system_fingerprint, "fp_a49d71b8a1"); + // usage rides on the last content chunk, not a separate one + ASSERT_EQ(r.usage.input_tokens, 17); + ASSERT_EQ(r.usage.cache_miss_tokens, 17); + ASSERT_EQ(r.usage.total_tokens, 26); + auto s = rig.openai->seen()[0]; + ASSERT_TRUE(has(s.body, "\"stream\":true")); + ASSERT_TRUE(has(s.body, "\"stream_options\":{\"include_usage\":true}")); + ASSERT_EQ(s.headers.get_or("Accept", ""), "text/event-stream"); +} + +TEST(deepseek_flow, stream_stop_early_and_truncation_is_loud) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/chat/completions", sse(kStreamExample)); + Chat chat(rig.platform.openai); + ChatResult r = chat.stream(ChatParams::prompt("Hi"), [&](const StreamDelta& d) { return d.content != "Hello"; }); + ASSERT_EQ(r.first().content, "Hello"); // stopped by the sink: no truncation error + // a transcript cut before any finish_reason (and not stopped by us) throws + Rig cut; + cut.openai->expect_response(Method::kPost, "/chat/completions", + sse("data: {\"id\":\"x\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"par\"},\"finish_reason\":null}]}\n\n")); + Chat chat2(cut.platform.openai); + try { + chat2.stream(ChatParams::prompt("Hi"), nullptr); + FAIL("expected STREAM_TRUNCATED"); + } catch (const ApiError& e) { + ASSERT_EQ(e.type(), "STREAM_TRUNCATED"); + } +} + +TEST(deepseek_flow, stream_error_body_is_an_api_error) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/chat/completions", + sse("{\"error\":{\"message\":\"overloaded\",\"type\":\"server_error\"}}")); + Chat chat(rig.platform.openai); + try { + chat.stream(ChatParams::prompt("Hi"), nullptr); + FAIL("expected"); + } catch (const ApiError& e) { + ASSERT_EQ(e.type(), "server_error"); + } +} + +TEST(deepseek_flow, thinking_tool_stream_folds_reasoning_and_fragments) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/chat/completions", sse(kThinkingToolStream)); + Chat chat(rig.platform.openai); + ChatParams p = ChatParams::prompt("How's the weather in Hangzhou Tomorrow"); + ToolDef t; + t.name = "get_weather"; + p.tools.push_back(t); + std::string reasoning, content; + std::vector arg_deltas; + ChatResult r = chat.stream(p, [&](const StreamDelta& d) { + reasoning += d.reasoning; + content += d.content; + for (const auto& f : d.tools) arg_deltas.push_back(f.arguments_delta); + return true; + }); + const ChatChoice& c = r.first(); + ASSERT_EQ(reasoning, "The user is asking about the weather in Hangzhou tomorrow."); + ASSERT_EQ(c.reasoning_content, reasoning); + ASSERT_EQ(content, "Let me check."); + ASSERT_EQ(c.finish_reason, "tool_calls"); + ASSERT_EQ(c.tool_calls.size(), 1u); + ASSERT_EQ(c.tool_calls[0].id, "call_00_kw66qNnNto11bSfJVIdlV5Oo"); + ASSERT_EQ(c.tool_calls[0].name, "get_weather"); + ASSERT_EQ(c.tool_calls[0].arguments, "{\"location\": \"Hangzhou\"}"); + ASSERT_TRUE(c.tool_calls[0].arguments_valid()); + ASSERT_EQ(c.tool_calls[0].parsed().find("location")->as_string(), "Hangzhou"); + ASSERT_EQ(arg_deltas.size(), 3u); + ASSERT_EQ(r.usage.reasoning_tokens, 12); + ASSERT_EQ(r.usage.cache_hit_tokens, 64); + ASSERT_EQ(r.usage.cache_hit_ratio(), 0.64); + // the history message carries reasoning_content and tool_calls as returned + Json h = c.history_message(); + ASSERT_EQ(h.find("reasoning_content")->as_string(), reasoning); + ASSERT_EQ(h.find("tool_calls")->as_array()[0].find("function")->find("arguments")->as_string(), "{\"location\": \"Hangzhou\"}"); +} + +TEST(deepseek_flow, conversation_tool_loop_passes_reasoning_back_every_round) { + // Two turns scripted from the guide's sample output values (thinking_mode, Turn 1.1 and 1.2). + const char* turn1 = + "{\"id\":\"a\",\"object\":\"chat.completion\",\"created\":1,\"model\":\"deepseek-flash\",\"choices\":[{\"index\":0,\"finish_reason\":\"tool_calls\"," + "\"message\":{\"role\":\"assistant\",\"content\":\"Let me check tomorrow's weather in Hangzhou for you. First, let me get tomorrow's date.\"," + "\"reasoning_content\":\"The user is asking about the weather in Hangzhou tomorrow. I need to get tomorrow's date first.\"," + "\"tool_calls\":[{\"id\":\"call_00_kw66qNnNto11bSfJVIdlV5Oo\",\"type\":\"function\",\"function\":{\"name\":\"get_date\",\"arguments\":\"{}\"}}]}}]}"; + const char* turn2 = + "{\"id\":\"b\",\"object\":\"chat.completion\",\"created\":2,\"model\":\"deepseek-flash\",\"choices\":[{\"index\":0,\"finish_reason\":\"stop\"," + "\"message\":{\"role\":\"assistant\",\"content\":\"Cloudy 7~13C tomorrow.\",\"reasoning_content\":\"The weather result is in.\"}}]," + "\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":5,\"total_tokens\":15}}"; + Rig rig; + rig.openai->expect_response(Method::kPost, "/chat/completions", reply(turn1)); + rig.openai->expect_response(Method::kPost, "/chat/completions", reply(turn2)); + Chat chat(rig.platform.openai); + ChatParams base; + ToolDef t; + t.name = "get_date"; + t.description = "Get the current date"; + base.tools.push_back(t); + Conversation conv(base); + conv.user("How's the weather in Hangzhou Tomorrow"); + std::vector called; + ChatResult last = conv.run_tools(chat, [&](const std::string& name, const Json& args, const std::string& id) { + called.push_back(name + ":" + id + ":" + args.dump()); + return std::string("2026-04-19"); + }); + ASSERT_EQ(last.first().content, "Cloudy 7~13C tomorrow."); + ASSERT_EQ(called.size(), 1u); + ASSERT_EQ(called[0], "get_date:call_00_kw66qNnNto11bSfJVIdlV5Oo:{}"); + auto seen = rig.openai->seen(); + ASSERT_EQ(seen.size(), 2u); + // request 2 carries the round-1 reasoning_content, the tool_calls and the tool result + ASSERT_TRUE(has(seen[1].body, "\"reasoning_content\":\"The user is asking about the weather in Hangzhou tomorrow. I need to get tomorrow's date first.\"")); + ASSERT_TRUE(has(seen[1].body, "\"tool_call_id\":\"call_00_kw66qNnNto11bSfJVIdlV5Oo\"")); + ASSERT_TRUE(has(seen[1].body, "\"content\":\"2026-04-19\"")); + ASSERT_FALSE(has(seen[0].body, "reasoning_content")); + // history: user, assistant(tool), tool, assistant(final) + ASSERT_EQ(conv.params().messages.as_array().size(), 4u); + // the round cap is explicit and bounded + ASSERT_THROW(conv.run_tools(chat, nullptr, 0), ApiError); + ASSERT_THROW(conv.run_tools(chat, nullptr, 17), ApiError); +} + +TEST(deepseek_flow, tool_loop_stops_at_the_round_cap) { + const char* looping = + "{\"id\":\"a\",\"created\":1,\"model\":\"m\",\"choices\":[{\"index\":0,\"finish_reason\":\"tool_calls\",\"message\":{\"role\":\"assistant\",\"content\":\"\"," + "\"tool_calls\":[{\"id\":\"c1\",\"type\":\"function\",\"function\":{\"name\":\"get_date\",\"arguments\":\"{}\"}}]}}]}"; + Rig rig; + rig.always(rig.openai, Method::kPost, "/chat/completions", reply(looping)); + Chat chat(rig.platform.openai); + ChatParams base; + ToolDef t; + t.name = "get_date"; + base.tools.push_back(t); + Conversation conv(base); + conv.user("loop"); + ASSERT_THROW(conv.run_tools(chat, [](const std::string&, const Json&, const std::string&) { return std::string("x"); }, 3), ApiError); + ASSERT_EQ(rig.openai->send_count(), 3u); +} + +TEST(deepseek_flow, prefix_completion_uses_the_beta_path) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/beta/chat/completions", reply(kChatExample)); + Chat chat(rig.platform.openai); + ChatParams p = ChatParams::prompt("Please write quick sort code"); + p.stop = {"```"}; + chat.prefix(p, "```python\n"); + auto s = rig.openai->seen()[0]; + ASSERT_TRUE(has(s.body, "\"prefix\":true")); + ASSERT_TRUE(has(s.body, "\"stop\":[\"```\"]")); + ASSERT_THROW(chat.prefix(p, ""), ApiError); +} + +TEST(deepseek_flow, error_statuses_map_to_api_errors_with_the_documented_shape) { + // FIXTURE shape: the body observed from the live host for an invalid key + // (src/deepseek/SPEC.md ## Verified live): type authentication_error. + const char* body = "{\"error\":{\"message\":\"Authentication Fails, Your api key: ****alid is invalid (request_id: 7a6eb948)\",\"type\":\"authentication_error\",\"param\":null,\"code\":\"invalid_request_error\"}}"; + for (int status : {401, 402, 422}) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/chat/completions", reply(body, status)); + Chat chat(rig.platform.openai); + try { + chat.create(ChatParams::prompt("hi")); + FAIL("expected"); + } catch (const ApiError& e) { + ASSERT_EQ(e.http_status(), status); + ASSERT_EQ(e.type(), "authentication_error"); + ASSERT_TRUE(has(e.message(), "Authentication Fails")); + ASSERT_EQ(std::string(e.what()).find(kKey), std::string::npos); + ASSERT_TRUE(Errors::find(status) != nullptr); + } + } + // server busy: 503 on a POST is not retried by the client (body was sent); the error surfaces + Rig busy; + busy.always(busy.openai, Method::kPost, "/chat/completions", reply("Server Overloaded", 503, "text/plain"), 5); + Chat chat(busy.platform.openai); + try { + chat.create(ChatParams::prompt("hi")); + FAIL("expected"); + } catch (const ApiError& e) { + ASSERT_EQ(e.http_status(), 503); + ASSERT_TRUE(Errors::retryable(e.http_status())); + } +} + +TEST(deepseek_model, generate_maps_neutral_request_and_response) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/chat/completions", reply(kChatExample)); + auto model = std::make_shared(std::make_shared(rig.platform.openai)); + ASSERT_EQ(model->vendor(), "deepseek"); + molo::llm::ChatRequest req; + req.system = "Be brief."; + req.messages.push_back(molo::llm::Message::user("Hello!")); + req.max_tokens = 64; + req.reasoning_effort = "low"; + req.extra = Json::object(); + req.extra.set("thinking", Json::parse("{\"type\":\"enabled\"}")); + molo::llm::ChatResponse r = model->generate(req); + ASSERT_EQ(r.text(), "Hello! How can I help you today?"); + ASSERT_EQ(r.finish_reason, "stop"); + ASSERT_EQ(r.usage.input_tokens, 16); + ASSERT_EQ(r.usage.output_tokens, 10); + ASSERT_EQ(r.usage.total_tokens, 26); + auto s = rig.openai->seen()[0]; + ASSERT_TRUE(has(s.body, "\"reasoning_effort\":\"low\"")); + ASSERT_TRUE(has(s.body, "\"thinking\":{\"type\":\"enabled\"}")); + ASSERT_TRUE(has(s.body, "\"role\":\"system\"")); + ASSERT_TRUE(has(s.body, "\"max_tokens\":64")); + // response_schema is rejected loudly + molo::llm::ChatRequest bad = req; + bad.response_schema = Json::parse("{\"type\":\"object\"}"); + ASSERT_THROW(model->generate(bad), ApiError); + ASSERT_EQ(rig.openai->send_count(), 1u); +} + +TEST(deepseek_model, tools_and_reasoning_round_trip_through_the_neutral_types) { + const char* resp = + "{\"id\":\"a\",\"object\":\"chat.completion\",\"created\":1,\"model\":\"deepseek-flash\",\"choices\":[{\"index\":0,\"finish_reason\":\"tool_calls\"," + "\"message\":{\"role\":\"assistant\",\"content\":\"\",\"reasoning_content\":\"need the date\"," + "\"tool_calls\":[{\"id\":\"call_1\",\"type\":\"function\",\"function\":{\"name\":\"get_date\",\"arguments\":\"{\\\"tz\\\":\\\"UTC\\\"}\"}}," + "{\"id\":\"call_2\",\"type\":\"function\",\"function\":{\"name\":\"get_date\",\"arguments\":\"{not json\"}}]}}]," + "\"usage\":{\"prompt_tokens\":10,\"completion_tokens\":5,\"total_tokens\":15,\"prompt_cache_hit_tokens\":8,\"prompt_cache_miss_tokens\":2,\"completion_tokens_details\":{\"reasoning_tokens\":3}}}"; + Rig rig; + rig.openai->expect_response(Method::kPost, "/chat/completions", reply(resp)); + rig.openai->expect_response(Method::kPost, "/chat/completions", reply(kChatExample)); + DeepseekChatModel model(std::make_shared(rig.platform.openai)); + molo::llm::ChatRequest req; + req.messages.push_back(molo::llm::Message::user("date?")); + molo::llm::ToolSpec spec; + spec.name = "get_date"; + spec.description = "Get the current date"; + req.tools.push_back(spec); + molo::llm::ChatResponse r = model.generate(req); + ASSERT_EQ(r.finish_reason, "tool_calls"); + ASSERT_EQ(r.usage.cached_tokens, 8); + ASSERT_EQ(r.usage.reasoning_tokens, 3); + ASSERT_EQ(r.message.parts[0].reasoning, "need the date"); + auto calls = r.tool_calls(); + ASSERT_EQ(calls.size(), 2u); + ASSERT_EQ(calls[0].arguments.find("tz")->as_string(), "UTC"); + ASSERT_EQ(calls[1].arguments.find("_invalid_json")->as_string(), "{not json"); + // feed the assistant message back plus tool results: reasoning must be sent (tools present) + req.messages.push_back(r.message); + molo::llm::Message results; + results.role = molo::llm::Role::kTool; + results.parts.push_back(molo::llm::ContentPart::of_result({"call_1", "2026-04-19", false})); + results.parts.push_back(molo::llm::ContentPart::of_result({"call_2", "bad arguments", true})); + req.messages.push_back(results); + model.generate(req); + std::string second = rig.openai->seen()[1].body; + ASSERT_TRUE(has(second, "\"reasoning_content\":\"need the date\"")); + ASSERT_TRUE(has(second, "\"tool_call_id\":\"call_1\"")); + ASSERT_TRUE(has(second, "\"tool_call_id\":\"call_2\"")); + ASSERT_TRUE(has(second, "\"arguments\":\"{\\\"tz\\\":\\\"UTC\\\"}\"")); + // and without tools the same history drops it + req.tools.clear(); + ChatParams p = model.to_params(req); + ASSERT_FALSE(has(p.to_json().dump(), "reasoning_content")); +} + +TEST(deepseek_model, images_become_data_urls_and_stream_maps_chunks) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/chat/completions", sse(kThinkingToolStream)); + DeepseekChatModel model(std::make_shared(rig.platform.openai)); + molo::llm::ChatRequest req; + molo::llm::Message m = molo::llm::Message::user("What is this?"); + molo::llm::ImageData img; + img.mime = "image/png"; + img.bytes = "PNGBYTES"; + m.parts.push_back(molo::llm::ContentPart::of_image(img)); + req.messages.push_back(m); + molo::llm::ToolSpec spec; + spec.name = "get_weather"; + req.tools.push_back(spec); + std::string text, reasoning, args, finish; + std::string call_id, call_name; + int usage_seen = 0; + model.stream(req, [&](const molo::llm::ChatChunk& c) { + text += c.text_delta; + reasoning += c.reasoning_delta; + args += c.tool_args_delta; + if (!c.tool_call_id.empty()) call_id = c.tool_call_id; + if (!c.tool_call_name.empty()) call_name = c.tool_call_name; + if (!c.finish_reason.empty()) finish = c.finish_reason; + if (c.usage) ++usage_seen; + return true; + }); + ASSERT_EQ(text, "Let me check."); + ASSERT_EQ(reasoning, "The user is asking about the weather in Hangzhou tomorrow."); + ASSERT_EQ(args, "{\"location\": \"Hangzhou\"}"); + ASSERT_EQ(call_id, "call_00_kw66qNnNto11bSfJVIdlV5Oo"); + ASSERT_EQ(call_name, "get_weather"); + ASSERT_EQ(finish, "tool_calls"); + ASSERT_EQ(usage_seen, 1); + ASSERT_TRUE(has(rig.openai->seen()[0].body, "data:image/png;base64,UE5HQllURVM=")); + // early stop from the consumer + Rig rig2; + rig2.openai->expect_response(Method::kPost, "/chat/completions", sse(kStreamExample)); + DeepseekChatModel model2(std::make_shared(rig2.platform.openai)); + molo::llm::ChatRequest r2; + r2.messages.push_back(molo::llm::Message::user("Hi")); + int n = 0; + model2.stream(r2, [&](const molo::llm::ChatChunk&) { return ++n < 2; }); + ASSERT_EQ(n, 2); +} diff --git a/tests/src/deepseek/test_endpoints.cpp b/tests/src/deepseek/test_endpoints.cpp new file mode 100644 index 0000000..8859169 --- /dev/null +++ b/tests/src/deepseek/test_endpoints.cpp @@ -0,0 +1,659 @@ +// DeepSeek: models, balance, files, search, fetch, FIM, Responses and the +// Anthropic-compatible surface. Replies are documented examples (FIXTURE, +// verbatim from api-docs.deepseek.com); assertions are on our requests and +// on our parsing. +#include "deepseek/account.h" +#include "deepseek/anthropic.h" +#include "deepseek/files.h" +#include "deepseek/fim.h" +#include "deepseek/responses.h" +#include "deepseek/web.h" +#include "support.h" + +using namespace molo::deepseek; +using namespace deepseek_test; +using molo::llm::ApiError; + +namespace { +bool has(const std::string& hay, const std::string& needle) { return hay.find(needle) != std::string::npos; } + +// FIXTURE: api/list-models "Example" +const char* kModels = + "{\"object\":\"list\",\"data\":[{\"id\":\"deepseek-flash\",\"object\":\"model\",\"owned_by\":\"deepseek\",\"name\":\"DeepSeek-V4.1-Flash\"," + "\"context_window\":1048576,\"max_output_tokens\":393216,\"input_modalities\":[\"text\",\"image\"],\"output_modalities\":[\"text\"]," + "\"effort\":{\"supported_levels\":[\"low\",\"high\",\"max\"],\"default_level\":\"high\"}," + "\"api_capabilities\":{\"anthropic_messages\":{\"system_prompt_update\":\"in-history\"}}}," + "{\"id\":\"deepseek-v4-pro\",\"object\":\"model\",\"owned_by\":\"deepseek\",\"name\":\"DeepSeek-V4-Pro\",\"context_window\":1048576," + "\"max_output_tokens\":393216,\"input_modalities\":[\"text\"],\"output_modalities\":[\"text\"]," + "\"effort\":{\"supported_levels\":[\"low\",\"high\",\"max\"],\"default_level\":\"high\"}," + "\"api_capabilities\":{\"anthropic_messages\":{\"system_prompt_update\":\"leading-only\"}}}]}"; +// FIXTURE: api/get-user-balance "Example" +const char* kBalance = + "{\"is_available\":true,\"balance_infos\":[{\"currency\":\"CNY\",\"total_balance\":\"110.00\",\"granted_balance\":\"10.00\",\"topped_up_balance\":\"100.00\"}]}"; +// FIXTURE: api/create-file "Example" +const char* kFile = + "{\"id\":\"file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9\",\"object\":\"file\",\"bytes\":102400,\"created_at\":1700000000,\"filename\":\"image.jpg\",\"purpose\":\"user_data\"}"; +// FIXTURE: api/list-files "Example" +const char* kFileList = + "{\"object\":\"list\",\"data\":[{\"id\":\"file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9\",\"object\":\"file\",\"bytes\":102400,\"created_at\":1700000000,\"filename\":\"image.jpg\",\"purpose\":\"user_data\"}]," + "\"first_id\":\"file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9\",\"last_id\":\"file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9\",\"has_more\":false}"; +// FIXTURE: api/delete-file "Example" +const char* kFileDeleted = "{\"id\":\"file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9\",\"object\":\"file\",\"deleted\":true}"; +// FIXTURE: guides/files_api (Anthropic-compatible file object and list) +const char* kAnthropicFile = + "{\"id\":\"file-api-xxxxxxxxxxxxxxxx\",\"type\":\"file\",\"size_bytes\":102400,\"created_at\":\"2026-01-01T00:00:00+00:00\",\"filename\":\"image.jpg\",\"mime_type\":\"image/jpeg\"}"; +// FIXTURE: api/search "Example" +const char* kSearch = + "{\"results\":[{\"rerank_score\":2.4,\"title\":\"DeepSeek V4 model released\",\"url\":\"https://example.com/deepseek-v4\"," + "\"snippet\":\"DeepSeek V4 is now available, with tool calling and long-context support.\"," + "\"summary\":\"DeepSeek has released the V4 model. The release adds improved tool calling and long-context support for agent workflows.\"," + "\"content\":\"DeepSeek V4 is now generally available...\",\"site_name\":\"Example News\",\"site_icon\":\"https://example.com/favicon.ico\"," + "\"date\":\"2026-06-01T00:00:00+00:00\",\"authority\":3}]}"; +// FIXTURE: api/fetch "Example" +const char* kFetch = "{\"title\":\"Example article\",\"content\":\"# Example article\\n\\nArticle content.\"}"; +// FIXTURE: api/create-response "Example" (200 no streaming) +const char* kResponse = + "{\"id\":\"24778070-1c36-4ae0-a4bd-870afc7fc13e\",\"object\":\"response\",\"created_at\":1753000000,\"status\":\"completed\",\"model\":\"deepseek-flash\"," + "\"output\":[{\"type\":\"reasoning\",\"id\":\"rs_1\",\"status\":\"completed\",\"content\":[{\"type\":\"reasoning_text\",\"text\":\"The user greets me. I should reply politely.\"}],\"summary\":[]}," + "{\"type\":\"message\",\"id\":\"msg_1\",\"status\":\"completed\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello! How can I help you today?\",\"annotations\":[]}]}]," + "\"usage\":{\"input_tokens\":22,\"input_tokens_details\":{\"cached_tokens\":0},\"output_tokens\":29,\"output_tokens_details\":{\"reasoning_tokens\":27},\"total_tokens\":51}," + "\"store\":false,\"parallel_tool_calls\":true,\"previous_response_id\":null,\"error\":null,\"incomplete_details\":null}"; +// FIXTURE shape: api/create-response streaming example (event names and payload keys), +// values completed to a full terminal event. LABELLED: abbreviated transcript. +const char* kResponseStream = + "event: response.created\ndata: {\"type\": \"response.created\", \"sequence_number\": 0, \"response\": {\"id\": \"r1\", \"object\": \"response\", \"status\": \"in_progress\"}}\n\n" + ": keep-alive\n\n" + "event: response.reasoning_text.delta\ndata: {\"type\": \"response.reasoning_text.delta\", \"sequence_number\": 4, \"item_id\": \"rs_1\", \"output_index\": 0, \"content_index\": 0, \"delta\": \"The user\"}\n\n" + "event: response.output_text.delta\ndata: {\"type\": \"response.output_text.delta\", \"sequence_number\": 11, \"item_id\": \"msg_1\", \"output_index\": 1, \"content_index\": 0, \"delta\": \"Hello\"}\n\n" + "event: response.output_text.delta\ndata: {\"type\": \"response.output_text.delta\", \"sequence_number\": 12, \"item_id\": \"msg_1\", \"output_index\": 1, \"content_index\": 0, \"delta\": \"!\"}\n\n" + "event: response.completed\ndata: {\"type\": \"response.completed\", \"sequence_number\": 20, \"response\": {\"id\": \"r1\", \"object\": \"response\", \"status\": \"completed\", \"model\": \"deepseek-flash\"," + " \"output\": [{\"type\":\"message\",\"id\":\"msg_1\",\"status\":\"completed\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello!\"}]}]," + " \"usage\": {\"input_tokens\": 5, \"input_tokens_details\": {\"cached_tokens\": 2}, \"output_tokens\": 2, \"output_tokens_details\": {\"reasoning_tokens\": 0}, \"total_tokens\": 7}}}\n\n"; +// FIXTURE: api/create-completion response shape (FIM), values filled in. LABELLED. +const char* kFim = + "{\"id\":\"f1\",\"choices\":[{\"finish_reason\":\"stop\",\"index\":0,\"logprobs\":null,\"text\":\" if a < 2:\\n return a\\n\"}],\"created\":1,\"model\":\"deepseek-flash\"," + "\"object\":\"text_completion\",\"usage\":{\"completion_tokens\":12,\"prompt_tokens\":20,\"total_tokens\":32,\"prompt_cache_hit_tokens\":4,\"prompt_cache_miss_tokens\":16}}"; +// Anthropic Messages shape (the compatible endpoint answers the Anthropic format). +// LABELLED: shape from Anthropic's public format, values invented; DeepSeek's own reply never seen. +const char* kMessage = + "{\"id\":\"msg_1\",\"type\":\"message\",\"role\":\"assistant\",\"model\":\"deepseek-flash\",\"content\":[{\"type\":\"thinking\",\"thinking\":\"greet\"},{\"type\":\"text\",\"text\":\"Hi there\"}," + "{\"type\":\"tool_use\",\"id\":\"tu_1\",\"name\":\"get_weather\",\"input\":{\"location\":\"Hangzhou\"}}],\"stop_reason\":\"tool_use\",\"usage\":{\"input_tokens\":10,\"output_tokens\":4}}"; +const char* kMessageStream = + "event: message_start\ndata: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_1\",\"type\":\"message\",\"role\":\"assistant\",\"model\":\"deepseek-flash\",\"content\":[],\"usage\":{\"input_tokens\":10,\"output_tokens\":1}}}\n\n" + "event: ping\ndata: {\"type\":\"ping\"}\n\n" + "event: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}}\n\n" + "event: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"Hi\"}}\n\n" + "event: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\" there\"}}\n\n" + "event: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":0}\n\n" + "event: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":1,\"content_block\":{\"type\":\"tool_use\",\"id\":\"tu_1\",\"name\":\"get_weather\",\"input\":{}}}\n\n" + "event: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":1,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"{\\\"location\\\":\"}}\n\n" + "event: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":1,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"\\\"Hangzhou\\\"}\"}}\n\n" + "event: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":1}\n\n" + "event: message_delta\ndata: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"tool_use\"},\"usage\":{\"output_tokens\":15}}\n\n" + "event: message_stop\ndata: {\"type\":\"message_stop\"}\n\n"; + +const std::string kPng = std::string("\x89PNG\r\n\x1a\n", 8) + "rest-of-the-image"; +} // namespace + +TEST(deepseek_account, models_and_balance_parse_the_documented_examples) { + Rig rig; + rig.openai->expect_response(Method::kGet, "/models", reply(kModels)); + rig.openai->expect_response(Method::kGet, "/user/balance", reply(kBalance)); + Account acct(rig.platform.openai); + ModelList models = acct.models(); + ASSERT_EQ(models.models.size(), 2u); + const ModelInfo* flash = models.find("deepseek-flash"); + ASSERT_TRUE(flash != nullptr); + ASSERT_EQ(flash->name, "DeepSeek-V4.1-Flash"); + ASSERT_EQ(flash->context_window, 1048576L); + ASSERT_EQ(flash->max_output_tokens, 393216L); + ASSERT_TRUE(flash->accepts_images()); + ASSERT_EQ(flash->effort_levels.size(), 3u); + ASSERT_EQ(flash->effort_default, "high"); + ASSERT_EQ(flash->system_prompt_update, "in-history"); + ASSERT_FALSE(models.find("deepseek-v4-pro")->accepts_images()); + ASSERT_EQ(models.find("deepseek-v4-pro")->system_prompt_update, "leading-only"); + ASSERT_TRUE(models.find("nope") == nullptr); + Balance b = acct.balance(); + ASSERT_TRUE(b.available); + ASSERT_EQ(b.entries.size(), 1u); + ASSERT_EQ(b.entries[0].currency, "CNY"); + ASSERT_EQ(b.entries[0].total, "110.00"); + ASSERT_EQ(b.entries[0].topped_up, "100.00"); + ASSERT_EQ(rig.openai->seen()[0].method, "GET"); + ASSERT_EQ(rig.openai->seen()[0].headers.get_or("Authorization", ""), std::string("Bearer ") + kKey); +} + +TEST(deepseek_account, model_catalog_names_and_anthropic_mapping) { + ASSERT_TRUE(ModelCatalog::status_of("deepseek-flash") == ModelStatus::kCurrent); + ASSERT_TRUE(ModelCatalog::status_of("deepseek-v4-flash") == ModelStatus::kLegacyAlias); + ASSERT_TRUE(ModelCatalog::status_of("deepseek-chat") == ModelStatus::kRetired); + ASSERT_TRUE(ModelCatalog::status_of("whatever") == ModelStatus::kUnknown); + ASSERT_EQ(ModelCatalog::served_as("deepseek-v4-flash"), "deepseek-flash"); + ASSERT_EQ(ModelCatalog::served_as("deepseek-v4-pro"), "deepseek-v4-pro"); + ASSERT_EQ(ModelCatalog::anthropic_mapped("claude-opus-4-8"), "deepseek-v4-pro"); + ASSERT_EQ(ModelCatalog::anthropic_mapped("claude-sonnet-5"), "deepseek-flash"); + ASSERT_EQ(ModelCatalog::anthropic_mapped("claude-haiku-4"), "deepseek-flash"); + ASSERT_EQ(ModelCatalog::anthropic_mapped("gpt-4"), "gpt-4"); + ASSERT_THROW(ModelCatalog::at(99), ApiError); +} + +TEST(deepseek_account, unconfigured_means_no_traffic) { + Rig rig(""); + Account acct(rig.platform.openai); + ASSERT_THROW(acct.models(), ApiError); + ASSERT_THROW(acct.balance(), ApiError); + ASSERT_EQ(rig.openai->send_count(), 0u); +} + +TEST(deepseek_files, upload_list_get_delete_requests_and_parsing) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/files", reply(kFile)); + rig.openai->expect_response(Method::kGet, "/files", reply(kFileList)); + rig.openai->expect_response(Method::kGet, "/files/file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9", reply(kFile)); + rig.openai->expect_response(Method::kDelete, "/files/file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9", reply(kFileDeleted)); + Files files(rig.platform.openai); + UploadParams up; + up.filename = "image.jpg"; + up.data = kPng; + up.expires_after_seconds = 3600; + FileInfo f = files.upload(up); + ASSERT_EQ(f.id, "file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9"); + ASSERT_EQ(f.bytes, 102400L); + ASSERT_EQ(f.purpose, "user_data"); + ASSERT_FALSE(f.expires_at.has_value()); + auto up_req = rig.openai->seen()[0]; + ASSERT_TRUE(has(up_req.headers.get_or("Content-Type", ""), "multipart/form-data")); + ASSERT_TRUE(has(up_req.body, "name=\"purpose\"\r\nContent-Type: text/plain\r\n\r\nuser_data")); + ASSERT_TRUE(has(up_req.body, "name=\"expires_after[anchor]\"\r\nContent-Type: text/plain\r\n\r\ncreated_at")); + ASSERT_TRUE(has(up_req.body, "name=\"expires_after[seconds]\"\r\nContent-Type: text/plain\r\n\r\n3600")); + ASSERT_TRUE(has(up_req.body, "filename=\"image.jpg\"")); + ASSERT_TRUE(has(up_req.body, "image/png")); + FileListParams lp; + lp.limit = 50; + lp.order = "desc"; + lp.after = "file-api-prev"; + FileList l = files.list(lp); + ASSERT_EQ(l.files.size(), 1u); + ASSERT_FALSE(l.has_more); + ASSERT_EQ(l.first_id, l.last_id); + ASSERT_EQ(rig.openai->seen()[1].target, "/files?limit=50&purpose=user_data&order=desc&after=file-api-prev"); + ASSERT_EQ(files.get("file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9").filename, "image.jpg"); + FileDeleted d = files.remove("file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9"); + ASSERT_TRUE(d.deleted); + ASSERT_EQ(rig.openai->seen()[3].method, "DELETE"); +} + +TEST(deepseek_files, input_is_validated_before_the_network) { + Rig rig; + Files files(rig.platform.openai); + UploadParams up; + up.filename = "a.jpg"; + up.data = "not an image"; + ASSERT_THROW(files.upload(up), ApiError); + up.data = kPng; + up.filename = ""; + ASSERT_THROW(files.upload(up), ApiError); + up.filename = "a/b.png"; + ASSERT_THROW(files.upload(up), ApiError); + up.filename = std::string(513, 'a'); + ASSERT_THROW(files.upload(up), ApiError); + up.filename = "a.png"; + up.expires_after_seconds = 3599; + ASSERT_THROW(files.upload(up), ApiError); + up.expires_after_seconds = 2592001; + ASSERT_THROW(files.upload(up), ApiError); + up.expires_after_seconds = std::nullopt; + up.data.clear(); + ASSERT_THROW(files.upload(up), ApiError); + FileListParams lp; + lp.limit = 0; + ASSERT_THROW(files.list(lp), ApiError); + lp.limit = 1001; + ASSERT_THROW(files.list(lp), ApiError); + lp.limit = 10; + lp.order = "sideways"; + ASSERT_THROW(files.list(lp), ApiError); + lp.order = ""; + lp.after = "../x"; + ASSERT_THROW(files.list(lp), ApiError); + ASSERT_THROW(files.get("a/b"), ApiError); + ASSERT_THROW(files.remove(""), ApiError); + ASSERT_EQ(rig.openai->send_count(), 0u); + // format sniffing + ASSERT_EQ(UploadParams::sniff(std::string("\xFF\xD8\xFF\xE0", 4)), "jpeg"); + ASSERT_EQ(UploadParams::sniff("GIF89a...."), "gif"); + ASSERT_EQ(UploadParams::sniff("RIFF\x01\x02\x03\x04WEBPVP8 "), "webp"); + ASSERT_EQ(UploadParams::sniff("%PDF-1.7"), ""); +} + +TEST(deepseek_files, list_all_walks_pages_and_reports_truncation) { + const char* page1 = + "{\"object\":\"list\",\"data\":[{\"id\":\"file-api-1\",\"object\":\"file\",\"bytes\":1,\"created_at\":1,\"filename\":\"a\",\"purpose\":\"user_data\"}],\"first_id\":\"file-api-1\",\"last_id\":\"file-api-1\",\"has_more\":true}"; + const char* page2 = + "{\"object\":\"list\",\"data\":[{\"id\":\"file-api-2\",\"object\":\"file\",\"bytes\":2,\"created_at\":2,\"filename\":\"b\",\"purpose\":\"user_data\"}],\"first_id\":\"file-api-2\",\"last_id\":\"file-api-2\",\"has_more\":false}"; + Rig rig; + rig.openai->expect_response(Method::kGet, "/files", reply(page1)); + rig.openai->expect_response(Method::kGet, "/files", reply(page2)); + Files files(rig.platform.openai); + FileList all = files.list_all(1); + ASSERT_EQ(all.files.size(), 2u); + ASSERT_FALSE(all.truncated); + ASSERT_TRUE(has(rig.openai->seen()[1].target, "after=file-api-1")); + // a server that always says has_more stops at the page cap and says so + Rig endless; + endless.always(endless.openai, Method::kGet, "/files", reply(page1), 100); + Files files2(endless.platform.openai); + FileList cut = files2.list_all(1); + ASSERT_TRUE(cut.truncated); + ASSERT_EQ(endless.openai->send_count(), 20u); +} + +TEST(deepseek_files, anthropic_surface_uses_header_key_and_beta_header) { + Rig rig; + rig.anthropic->expect_response(Method::kPost, "/anthropic/v1/files", reply(kAnthropicFile)); + rig.anthropic->expect_response(Method::kGet, "/anthropic/v1/files", reply("{\"data\":[" + std::string(kAnthropicFile) + "],\"first_id\":\"file-api-xxxxxxxxxxxxxxxx\",\"last_id\":\"file-api-xxxxxxxxxxxxxxxx\",\"has_more\":false}")); + rig.anthropic->expect_response(Method::kGet, "/anthropic/v1/files/file-api-xxxxxxxxxxxxxxxx", reply(kAnthropicFile)); + rig.anthropic->expect_response(Method::kDelete, "/anthropic/v1/files/file-api-xxxxxxxxxxxxxxxx", + reply("{\"id\":\"file-api-xxxxxxxxxxxxxxxx\",\"type\":\"file_deleted\"}")); + AnthropicFiles files(rig.platform.anthropic); + UploadParams up; + up.filename = "image.jpg"; + up.data = kPng; + FileInfo f = files.upload(up); + ASSERT_EQ(f.bytes, 102400L); + ASSERT_EQ(f.mime_type, "image/jpeg"); + ASSERT_EQ(f.created_text, "2026-01-01T00:00:00+00:00"); + auto s = rig.anthropic->seen()[0]; + ASSERT_EQ(s.headers.get_or("x-api-key", ""), kKey); + ASSERT_EQ(s.headers.get_or("Authorization", ""), ""); + ASSERT_EQ(s.headers.get_or("anthropic-beta", ""), "files-api-2025-04-14"); + ASSERT_FALSE(has(s.body, "purpose")); // the Anthropic shape has no purpose field + AnthropicFileListParams lp; + lp.limit = 20; + lp.after_id = "file-api-a"; + FileList l = files.list(lp); + ASSERT_EQ(l.files.size(), 1u); + ASSERT_EQ(rig.anthropic->seen()[1].target, "/anthropic/v1/files?limit=20&after_id=file-api-a"); + ASSERT_EQ(rig.anthropic->seen()[1].headers.get_or("anthropic-beta", ""), "files-api-2025-04-14"); + ASSERT_EQ(files.get("file-api-xxxxxxxxxxxxxxxx").filename, "image.jpg"); + ASSERT_TRUE(files.remove("file-api-xxxxxxxxxxxxxxxx").deleted); + lp.before_id = "file-api-b"; + ASSERT_THROW(files.list(lp), ApiError); // after_id and before_id are mutually exclusive + ASSERT_EQ(rig.openai->send_count(), 0u); +} + +TEST(deepseek_web, search_and_fetch) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/v1/tools/search", reply(kSearch)); + rig.openai->expect_response(Method::kPost, "/v1/tools/fetch", reply(kFetch)); + Web web(rig.platform.openai); + SearchParams sp; + sp.query = "DeepSeek V4 release"; + sp.count = 5; + sp.need_content = true; + SearchResults r = web.search(sp); + ASSERT_EQ(r.hits.size(), 1u); + ASSERT_EQ(r.hits[0].title, "DeepSeek V4 model released"); + ASSERT_EQ(r.hits[0].authority, 3); + ASSERT_TRUE(r.hits[0].high_quality()); + ASSERT_EQ(r.hits[0].site_name, "Example News"); + ASSERT_EQ(rig.openai->seen()[0].body, "{\"count\":5,\"need_content\":true,\"query\":\"DeepSeek V4 release\"}"); + FetchResult f = web.fetch("https://example.com/article"); + ASSERT_EQ(f.title, "Example article"); + ASSERT_TRUE(has(f.content, "Article content.")); + ASSERT_EQ(rig.openai->seen()[1].body, "{\"url\":\"https://example.com/article\"}"); +} + +TEST(deepseek_web, null_site_fields_and_empty_results_are_fine) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/v1/tools/search", reply("{\"results\":[{\"rerank_score\":0.2,\"title\":\"t\",\"url\":\"u\",\"snippet\":\"s\",\"summary\":\"m\",\"content\":\"\",\"site_name\":null,\"site_icon\":null,\"date\":null,\"authority\":-1}]}")); + rig.openai->expect_response(Method::kPost, "/v1/tools/search", reply("{\"results\":[]}")); + Web web(rig.platform.openai); + SearchParams sp; + sp.query = "x"; + SearchResults r = web.search(sp); + ASSERT_EQ(r.hits[0].site_name, ""); + ASSERT_EQ(r.hits[0].authority, -1); + ASSERT_FALSE(r.hits[0].high_quality()); + ASSERT_TRUE(web.search(sp).hits.empty()); +} + +TEST(deepseek_web, validation_before_the_network) { + Rig rig; + Web web(rig.platform.openai); + SearchParams sp; + sp.query = " "; + ASSERT_THROW(web.search(sp), ApiError); + sp.query = std::string(129, 'a'); + ASSERT_THROW(web.search(sp), ApiError); + sp.query = "ok"; + sp.count = 0; + ASSERT_THROW(web.search(sp), ApiError); + sp.count = 51; + ASSERT_THROW(web.search(sp), ApiError); + sp.count = 10; + sp.ori_question = ""; + ASSERT_THROW(web.search(sp), ApiError); + sp.query = std::string(128, 'a'); // exactly the cap passes + sp.ori_question = std::nullopt; + sp.validate(); + ASSERT_THROW(web.fetch(""), ApiError); + ASSERT_THROW(web.fetch("ftp://x/y"), ApiError); + ASSERT_THROW(web.fetch("https://user:pw@example.com/"), ApiError); + ASSERT_THROW(web.fetch("https://example.com/" + std::string(8200, 'a')), ApiError); + ASSERT_EQ(rig.openai->send_count(), 0u); +} + +TEST(deepseek_fim, request_and_parse) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/beta/completions", reply(kFim)); + Fim fim(rig.platform.openai); + FimParams p; + p.prompt = "def fib(a):"; + p.suffix = " return fib(a-1) + fib(a-2)"; + p.max_tokens = 128; + FimResult r = fim.create(p); + ASSERT_EQ(r.first().text, " if a < 2:\n return a\n"); + ASSERT_EQ(r.first().finish_reason, "stop"); + ASSERT_EQ(r.object, "text_completion"); + ASSERT_EQ(r.usage.cache_hit_tokens, 4); + ASSERT_EQ(r.usage.cache_miss_tokens, 16); + ASSERT_EQ(r.usage.cache_hit_ratio(), 0.2); + auto s = rig.openai->seen()[0]; + ASSERT_TRUE(has(s.body, "\"suffix\":\" return fib(a-1) + fib(a-2)\"")); + ASSERT_TRUE(has(s.body, "\"prompt\":\"def fib(a):\"")); +} + +TEST(deepseek_fim, stream_collects_text) { + const char* stream = + "data: {\"id\":\"f1\",\"choices\":[{\"index\":0,\"text\":\" if\",\"finish_reason\":null}],\"created\":1,\"model\":\"deepseek-flash\",\"object\":\"text_completion\"}\n\n" + "data: {\"id\":\"f1\",\"choices\":[{\"index\":0,\"text\":\" a < 2:\",\"finish_reason\":null}],\"created\":1,\"model\":\"deepseek-flash\",\"object\":\"text_completion\"}\n\n" + "data: {\"id\":\"f1\",\"choices\":[{\"index\":0,\"text\":\"\",\"finish_reason\":\"stop\"}],\"created\":1,\"model\":\"deepseek-flash\",\"object\":\"text_completion\",\"usage\":{\"completion_tokens\":5,\"prompt_tokens\":9,\"total_tokens\":14,\"prompt_cache_hit_tokens\":0,\"prompt_cache_miss_tokens\":9}}\n\n" + "data: [DONE]\n\n"; + Rig rig; + rig.openai->expect_response(Method::kPost, "/beta/completions", sse(stream)); + Fim fim(rig.platform.openai); + FimParams p; + p.prompt = "def fib(a):"; + std::string text; + FimResult r = fim.stream(p, [&](const std::string& d) { + text += d; + return true; + }); + ASSERT_EQ(text, " if a < 2:"); + ASSERT_EQ(r.first().finish_reason, "stop"); + ASSERT_EQ(r.usage.total_tokens, 14); + ASSERT_TRUE(has(rig.openai->seen()[0].body, "\"stream\":true")); +} + +TEST(deepseek_responses, create_parse_and_history) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/responses", reply(kResponse)); + Responses api(rig.platform.openai); + ResponsesParams p; + p.instructions = "You are a helpful assistant."; + p.input_text = "Hi, how are you?"; + p.effort = "high"; + p.max_output_tokens = 256; + ResponsesResult r = api.create(p); + ASSERT_TRUE(r.completed()); + ASSERT_EQ(r.output_text(), "Hello! How can I help you today?"); + ASSERT_EQ(r.reasoning_text(), "The user greets me. I should reply politely."); + ASSERT_EQ(r.usage.input_tokens, 22); + ASSERT_EQ(r.usage.reasoning_tokens, 27); + ASSERT_EQ(r.usage.total_tokens, 51); + ASSERT_EQ(r.history_items().as_array().size(), 2u); + ASSERT_TRUE(r.function_calls().empty()); + std::string body = rig.openai->seen()[0].body; + ASSERT_TRUE(has(body, "\"input\":\"Hi, how are you?\"")); + ASSERT_TRUE(has(body, "\"instructions\":\"You are a helpful assistant.\"")); + ASSERT_TRUE(has(body, "\"reasoning\":{\"effort\":\"high\"}")); + ASSERT_TRUE(has(body, "\"max_output_tokens\":256")); + ASSERT_FALSE(has(body, "previous_response_id")); // unsupported, never sent + ASSERT_FALSE(has(body, "\"store\"")); +} + +TEST(deepseek_responses, validation_rules) { + auto msg = [](ResponsesParams p) { + try { + p.validate(); + } catch (const ApiError& e) { + return e.message(); + } + return std::string("OK"); + }; + ResponsesParams empty; + ASSERT_TRUE(has(msg(empty), "at least one of input and instructions")); + ResponsesParams both; + both.input_text = "x"; + both.input_items.push(ResponseItems::message("user", "y")); + ASSERT_TRUE(has(msg(both), "not both")); + ResponsesParams ins; + ins.instructions = "only instructions is enough"; + ASSERT_EQ(msg(ins), "OK"); + ResponsesParams img; + img.input_items.push(ResponseItems::message_parts("user", {ResponseItems::input_image_url("https://e.com/a.jpg", "low")})); + ASSERT_EQ(msg(img), "OK"); + ResponsesParams sys_img; + sys_img.input_items.push(ResponseItems::message_parts("system", {ResponseItems::input_image_url("https://e.com/a.jpg")})); + ASSERT_TRUE(has(msg(sys_img), "only in user")); + Json both_img = ResponseItems::input_image_url("https://e.com/a.jpg"); + both_img.set("file_id", Json("file-api-1")); + ResponsesParams two; + two.input_items.push(ResponseItems::message_parts("user", {both_img})); + ASSERT_TRUE(has(msg(two), "cannot have both")); + Json neither = Json::object(); + neither.set("type", Json("input_image")); + ResponsesParams none; + none.input_items.push(ResponseItems::message_parts("user", {neither})); + ASSERT_TRUE(has(msg(none), "must have image_url or file_id")); + ResponsesParams orphan; + orphan.input_items.push(ResponseItems::message("user", "x")); + orphan.input_items.push(ResponseItems::function_call("c1", "get_date", "{}")); + ASSERT_TRUE(has(msg(orphan), "function_call_output")); + orphan.input_items.push(ResponseItems::function_call_output("c1", "2026-04-19")); + ASSERT_EQ(msg(orphan), "OK"); + orphan.input_items.push(ResponseItems::function_call("c1", "get_date", "{}")); + ASSERT_TRUE(has(msg(orphan), "unique")); + ResponsesParams unk; + unk.input_items.push(ResponseItems::message("user", "x")); + Json weird = Json::object(); + weird.set("type", Json("file_search_call")); + unk.input_items.push(weird); + ASSERT_TRUE(has(msg(unk), "not supported")); + ResponsesParams tools; + tools.input_text = "x"; + tools.tools.push(ResponseItems::function_tool("get_date", "d")); + tools.tools.push(ResponseItems::function_tool("get_date", "d")); + ASSERT_TRUE(has(msg(tools), "unique")); + tools.tools = Json::array(); + tools.tools.push(ResponseItems::apply_patch_tool()); + tools.tools.push(ResponseItems::web_search_tool()); + ASSERT_EQ(msg(tools), "OK"); + Json custom = ResponseItems::apply_patch_tool(); + custom.set("name", Json("other")); + tools.tools.push(custom); + ASSERT_TRUE(has(msg(tools), "apply_patch")); + ResponsesParams schema; + schema.input_text = "x"; + schema.format = TextFormat::kJsonSchema; + ASSERT_TRUE(has(msg(schema), "name")); + schema.schema_name = "answer"; + ASSERT_TRUE(has(msg(schema), "schema")); + schema.schema = Json::parse("{\"type\":\"object\"}"); + ASSERT_EQ(msg(schema), "OK"); + ASSERT_TRUE(has(schema.to_json().dump(), "\"text\":{\"format\":{\"name\":\"answer\",\"schema\":{\"type\":\"object\"},\"type\":\"json_schema\"}}")); + ResponsesParams choice; + choice.input_text = "x"; + choice.tool_choice = "required"; + ASSERT_TRUE(has(msg(choice), "needs tools")); + choice.tools.push(ResponseItems::function_tool("f", "")); + choice.tool_choice = "f"; + ASSERT_TRUE(has(choice.to_json().dump(), "\"tool_choice\":{\"name\":\"f\",\"type\":\"function\"}")); +} + +TEST(deepseek_responses, stream_events_end_with_a_terminal_event_no_done) { + Rig rig; + rig.openai->expect_response(Method::kPost, "/responses", sse(kResponseStream)); + Responses api(rig.platform.openai); + ResponsesParams p; + p.input_text = "Hi"; + std::string text, reasoning; + std::vector types; + ResponsesResult r = api.stream(p, [&](const ResponseEvent& e) { + types.push_back(e.type); + if (e.type == "response.output_text.delta") text += e.text_delta(); + if (e.type == "response.reasoning_text.delta") reasoning += e.text_delta(); + return true; + }); + ASSERT_EQ(text, "Hello!"); + ASSERT_EQ(reasoning, "The user"); + ASSERT_EQ(types.front(), "response.created"); + ASSERT_EQ(types.back(), "response.completed"); + ASSERT_EQ(r.status, "completed"); + ASSERT_EQ(r.output_text(), "Hello!"); + ASSERT_EQ(r.usage.cache_hit_tokens, 2); + ASSERT_EQ(r.usage.cache_miss_tokens, 3); + ASSERT_TRUE(has(rig.openai->seen()[0].body, "\"stream\":true")); + // no terminal event: loud + Rig cut; + cut.openai->expect_response(Method::kPost, "/responses", sse("event: response.created\ndata: {\"type\":\"response.created\",\"sequence_number\":0,\"response\":{\"id\":\"r\"}}\n\n")); + Responses api2(cut.platform.openai); + try { + api2.stream(p, nullptr); + FAIL("expected"); + } catch (const ApiError& e) { + ASSERT_EQ(e.type(), "STREAM_TRUNCATED"); + } +} + +TEST(deepseek_responses, failed_and_incomplete_terminals_are_results_not_throws) { + const char* failed = + "event: response.failed\ndata: {\"type\":\"response.failed\",\"sequence_number\":3,\"response\":{\"id\":\"r\",\"status\":\"failed\",\"error\":{\"code\":\"server_error\",\"message\":\"boom\"},\"output\":[]}}\n\n"; + const char* incomplete = + "event: response.incomplete\ndata: {\"type\":\"response.incomplete\",\"sequence_number\":3,\"response\":{\"id\":\"r\",\"status\":\"incomplete\",\"incomplete_details\":{\"reason\":\"max_output_tokens\"},\"output\":[]}}\n\n"; + ResponsesParams p; + p.input_text = "x"; + Rig a; + a.openai->expect_response(Method::kPost, "/responses", sse(failed)); + ResponsesResult f = Responses(a.platform.openai).stream(p, nullptr); + ASSERT_EQ(f.status, "failed"); + ASSERT_EQ(f.error.find("message")->as_string(), "boom"); + Rig b; + b.openai->expect_response(Method::kPost, "/responses", sse(incomplete)); + ResponsesResult i = Responses(b.platform.openai).stream(p, nullptr); + ASSERT_EQ(i.incomplete_reason, "max_output_tokens"); +} + +TEST(deepseek_anthropic, request_shape_headers_and_parse) { + Rig rig; + rig.anthropic->expect_response(Method::kPost, "/anthropic/v1/messages", reply(kMessage)); + AnthropicMessages api(rig.platform.anthropic); + MessagesParams p; + p.max_tokens = 1000; + p.system = "You are a helpful assistant."; + p.add(AnthropicBlocks::message("user", {AnthropicBlocks::text("Hi, how are you?")})); + p.thinking = true; + p.effort = "high"; + p.user_id = "u-1"; + p.tools.push(AnthropicBlocks::tool("get_weather", "weather", Json::parse("{\"type\":\"object\"}"))); + p.tool_choice = "get_weather"; + MessagesResult r = api.create(p); + ASSERT_EQ(r.text(), "Hi there"); + ASSERT_EQ(r.thinking_text(), "greet"); + ASSERT_EQ(r.stop_reason, "tool_use"); + ASSERT_EQ(r.tool_uses().size(), 1u); + ASSERT_EQ(r.tool_uses()[0].input.find("location")->as_string(), "Hangzhou"); + ASSERT_EQ(r.usage.input_tokens, 10); + auto s = rig.anthropic->seen()[0]; + ASSERT_EQ(s.headers.get_or("x-api-key", ""), kKey); + ASSERT_EQ(s.headers.get_or("Authorization", ""), ""); + ASSERT_EQ(s.headers.get_or("anthropic-beta", ""), ""); // only file images need it + ASSERT_TRUE(has(s.body, "\"max_tokens\":1000")); + ASSERT_TRUE(has(s.body, "\"thinking\":{\"type\":\"enabled\"}")); + ASSERT_FALSE(has(s.body, "budget_tokens")); + ASSERT_TRUE(has(s.body, "\"output_config\":{\"effort\":\"high\"}")); + ASSERT_TRUE(has(s.body, "\"metadata\":{\"user_id\":\"u-1\"}")); + ASSERT_TRUE(has(s.body, "\"tool_choice\":{\"name\":\"get_weather\",\"type\":\"tool\"}")); + ASSERT_FALSE(has(s.body, "top_k")); + ASSERT_EQ(rig.openai->send_count(), 0u); +} + +TEST(deepseek_anthropic, file_image_adds_the_beta_header_and_unsupported_blocks_are_rejected) { + Rig rig; + rig.anthropic->expect_response(Method::kPost, "/anthropic/v1/messages", reply(kMessage)); + AnthropicMessages api(rig.platform.anthropic); + MessagesParams p; + p.add(AnthropicBlocks::message("user", {AnthropicBlocks::text("What is in this image?"), AnthropicBlocks::image_file("file-api-xxxxxxxxxxxxxxxx")})); + ASSERT_TRUE(p.uses_file_image()); + api.create(p); + ASSERT_EQ(rig.anthropic->seen()[0].headers.get_or("anthropic-beta", ""), "files-api-2025-04-14"); + for (const char* type : {"document", "search_result", "redacted_thinking", "code_execution_tool_result", "mcp_tool_use", "mcp_tool_result", "container_upload"}) { + Json block = Json::object(); + block.set("type", Json(type)); + MessagesParams q; + q.add(AnthropicBlocks::message("user", {block})); + ASSERT_THROW(q.validate(), ApiError); + } + MessagesParams ok; + ok.add(AnthropicBlocks::message("user", {AnthropicBlocks::image_base64("image/webp", "AAAA"), AnthropicBlocks::image_url("https://e.com/a.png")})); + ok.validate(); + MessagesParams badmedia; + badmedia.add(AnthropicBlocks::message("user", {AnthropicBlocks::image_base64("image/bmp", "AAAA")})); + ASSERT_THROW(badmedia.validate(), ApiError); + MessagesParams norole; + norole.add(AnthropicBlocks::message_text("system", "x")); + ASSERT_THROW(norole.validate(), ApiError); + MessagesParams empty; + ASSERT_THROW(empty.validate(), ApiError); + MessagesParams tokens; + tokens.add(AnthropicBlocks::message_text("user", "x")); + tokens.max_tokens = 0; + ASSERT_THROW(tokens.validate(), ApiError); + tokens.max_tokens = 5; + tokens.effort = "turbo"; + ASSERT_THROW(tokens.validate(), ApiError); +} + +TEST(deepseek_anthropic, stream_folds_text_and_tool_input) { + Rig rig; + rig.anthropic->expect_response(Method::kPost, "/anthropic/v1/messages", sse(kMessageStream)); + AnthropicMessages api(rig.platform.anthropic); + MessagesParams p; + p.add(AnthropicBlocks::message_text("user", "Hi")); + std::string text; + std::vector events; + MessagesResult r = api.stream(p, [&](const molo::llm::SseEvent& e, const std::string& delta) { + events.push_back(e.event); + text += delta; + return true; + }); + ASSERT_EQ(text, "Hi there"); + ASSERT_EQ(r.text(), "Hi there"); + ASSERT_EQ(r.stop_reason, "tool_use"); + ASSERT_EQ(r.tool_uses().size(), 1u); + ASSERT_EQ(r.tool_uses()[0].input.find("location")->as_string(), "Hangzhou"); + ASSERT_EQ(r.usage.output_tokens, 15); + ASSERT_EQ(r.usage.input_tokens, 10); + ASSERT_EQ(events.front(), "message_start"); + ASSERT_EQ(events.back(), "message_stop"); + ASSERT_TRUE(has(rig.anthropic->seen()[0].body, "\"stream\":true")); + // an error event ends the stream with an ApiError + Rig bad; + bad.anthropic->expect_response(Method::kPost, "/anthropic/v1/messages", + sse("event: error\ndata: {\"type\":\"error\",\"error\":{\"type\":\"overloaded_error\",\"message\":\"busy\"}}\n\n")); + AnthropicMessages api2(bad.platform.anthropic); + try { + api2.stream(p, nullptr); + FAIL("expected"); + } catch (const ApiError& e) { + ASSERT_EQ(e.type(), "overloaded_error"); + } + // truncation without message_stop is loud + Rig cut; + cut.anthropic->expect_response(Method::kPost, "/anthropic/v1/messages", + sse("event: ping\ndata: {\"type\":\"ping\"}\n\n")); + AnthropicMessages api3(cut.platform.anthropic); + ASSERT_THROW(api3.stream(p, nullptr), ApiError); +} diff --git a/tests/src/deepseek/test_live.cpp b/tests/src/deepseek/test_live.cpp new file mode 100644 index 0000000..3392988 --- /dev/null +++ b/tests/src/deepseek/test_live.cpp @@ -0,0 +1,60 @@ +// Opt-in live checks. MOLO_LIVE_NET=1 enables the network; DEEPSEEK_API_KEY +// (via llm::Config) enables the read-only calls plus ONE tiny completion. +// Without them each test prints a loud SKIP. Nothing is created or deleted. +#include +#include + +#include "clients/transports/http_transport.h" +#include "deepseek/account.h" +#include "deepseek/chat.h" +#include "deepseek/platform.h" +#include "support.h" + +using namespace molo::deepseek; +using molo::llm::ApiError; + +namespace { +bool net() { return std::getenv("MOLO_LIVE_NET") != nullptr; } +} // namespace + +// No key needed: a deliberately invalid key must answer 401 with the +// OpenAI-style error envelope (type authentication_error). +TEST(deepseek_live, invalid_key_answers_401_with_the_error_envelope) { + if (!net()) { + std::cout << "SKIP deepseek_live.invalid_key_answers_401_with_the_error_envelope (set MOLO_LIVE_NET=1)\n"; + return; + } + molo::llm::ApiClientConfig cfg = Platform::config(Surface::kOpenai); + auto client = std::make_shared( + std::make_unique(), cfg, "sk-invalid-molo-probe"); + Account acct(client); + try { + acct.models(); + FAIL("expected 401"); + } catch (const ApiError& e) { + std::cout << " GET /models with an invalid key: " << e.http_status() << " " << e.type() << "\n"; + ASSERT_EQ(e.http_status(), 401); + ASSERT_EQ(e.type(), "authentication_error"); + } +} + +TEST(deepseek_live, models_balance_and_one_tiny_completion) { + Platform p = Platform::from_env(); + if (!net() || !p.configured()) { + std::cout << "SKIP deepseek_live.models_balance_and_one_tiny_completion (set MOLO_LIVE_NET=1 and DEEPSEEK_API_KEY)\n"; + return; + } + Account acct(p.openai); + ModelList models = acct.models(); + std::cout << " models: " << models.models.size() << "\n"; + ASSERT_TRUE(!models.models.empty()); + ASSERT_TRUE(models.find(ModelCatalog::default_model()) != nullptr); + Balance b = acct.balance(); + std::cout << " balance entries: " << b.entries.size() << " available=" << b.available << "\n"; + ChatParams params = ChatParams::prompt("Reply with the single word: ok"); + params.max_tokens = 16; + params.thinking = Thinking::kDisabled; + ChatResult r = Chat(p.openai).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/deepseek/test_params.cpp b/tests/src/deepseek/test_params.cpp new file mode 100644 index 0000000..10fd214 --- /dev/null +++ b/tests/src/deepseek/test_params.cpp @@ -0,0 +1,351 @@ +// DeepSeek: call table, error table, rules, chat request validation and body. +// Local and deterministic: no reply is scripted here. +#include + +#include "deepseek/calls.h" +#include "deepseek/chat.h" +#include "deepseek/chat_params.h" +#include "deepseek/errors.h" +#include "deepseek/fim.h" +#include "deepseek/rules.h" +#include "support.h" + +using namespace molo::deepseek; +using molo::llm::ApiError; + +namespace { +template +std::string invalid_message(F&& f) { + try { + f(); + } catch (const ApiError& e) { + ASSERT_EQ(e.http_status(), 400); + ASSERT_EQ(e.type(), "INVALID_ARGUMENT"); + ASSERT_EQ(e.vendor(), "deepseek"); + return e.message(); + } + FAIL("expected ApiError"); + return ""; +} +bool has(const std::string& hay, const std::string& needle) { return hay.find(needle) != std::string::npos; } +} // namespace + +TEST(deepseek_calls, table_shape_and_render) { + ASSERT_EQ(Calls::count(), 17u); + std::set seen; + for (std::size_t i = 0; i < Calls::count(); ++i) { + const CallSpec& s = Calls::at(i); + ASSERT_TRUE(seen.insert(std::string(s.http_method) + " " + s.path).second); + ASSERT_TRUE(s.path[0] == '/'); + if (s.surface == Surface::kAnthropic) ASSERT_TRUE(std::string(s.path).rfind("/anthropic/", 0) == 0); + } + ASSERT_EQ(Calls::render(Call::kChat), "/chat/completions"); + ASSERT_EQ(Calls::render(Call::kChatBeta), "/beta/chat/completions"); + ASSERT_EQ(Calls::render(Call::kFim), "/beta/completions"); + ASSERT_EQ(Calls::render(Call::kFileGet, "file-api-abc"), "/files/file-api-abc"); + ASSERT_EQ(Calls::render(Call::kAnthropicFileDelete, "file-api-abc"), "/anthropic/v1/files/file-api-abc"); + ASSERT_THROW(Calls::render(Call::kFileGet, "../x"), ApiError); + ASSERT_THROW(Calls::render(Call::kFileGet, ""), ApiError); + ASSERT_THROW(Calls::at(99), ApiError); + ASSERT_TRUE(Calls::method_of(Call::kFileDelete) == molo::clients::Method::kDelete); + ASSERT_TRUE(Calls::method_of(Call::kModels) == molo::clients::Method::kGet); + for (std::size_t i = 0; i < Calls::schema_count(); ++i) ASSERT_TRUE(std::string(Calls::schema_at(i).fields).size() > 0); +} + +TEST(deepseek_errors, documented_codes) { + for (int s : {400, 401, 402, 422, 429, 500, 503}) ASSERT_TRUE(Errors::find(s) != nullptr); + ASSERT_TRUE(Errors::find(418) == nullptr); + ASSERT_TRUE(Errors::kind_of(402) == ErrorKind::kBalance); + ASSERT_TRUE(Errors::kind_of(401) == ErrorKind::kAuth); + ASSERT_TRUE(Errors::kind_of(502) == ErrorKind::kTransport); + ASSERT_TRUE(Errors::kind_of(200) == ErrorKind::kNone); + ASSERT_TRUE(Errors::kind_of(418) == ErrorKind::kOther); + // wait and retry: 429, 500, 503 (+ search/fetch 408, 504); never the 4xx input errors + for (int s : {408, 429, 500, 503, 504}) { + ASSERT_TRUE(Errors::retryable(s)); + ASSERT_TRUE(Errors::wait_seconds(s) >= 1 && Errors::wait_seconds(s) <= Errors::kMaxWaitSeconds); + } + for (int s : {400, 401, 402, 403, 404, 413, 422}) { + ASSERT_FALSE(Errors::retryable(s)); + ASSERT_EQ(Errors::wait_seconds(s), 0); + } + ApiError e("deepseek", 402, "invalid_request_error", "Insufficient Balance"); + ASSERT_TRUE(has(Errors::explain(e), "Insufficient Balance")); + ASSERT_TRUE(has(Errors::explain(ApiError("deepseek", 418, "teapot", "short")), "teapot")); + ASSERT_THROW(Errors::at(999), ApiError); +} + +TEST(deepseek_rules, field_rules) { + ASSERT_THROW(Rules::model(""), ApiError); + ASSERT_THROW(Rules::model("bad name"), ApiError); + ASSERT_THROW(Rules::model(std::string(129, 'a')), ApiError); + Rules::model("deepseek-v4-pro"); + ASSERT_THROW(Rules::user_id("a b"), ApiError); + ASSERT_THROW(Rules::user_id(std::string(513, 'a')), ApiError); + Rules::user_id("user_1-A"); + ASSERT_THROW(Rules::tool_name("get weather"), ApiError); + ASSERT_THROW(Rules::tool_name(std::string(129, 'a')), ApiError); + ASSERT_THROW(Rules::stop(std::vector(17, "x")), ApiError); + ASSERT_THROW(Rules::stop({""}), ApiError); + Rules::stop(std::vector(16, "x")); + ASSERT_THROW(Rules::image_url("ftp://x/y.png"), ApiError); + ASSERT_THROW(Rules::image_url("data:text/plain;base64,AAAA"), ApiError); + ASSERT_THROW(Rules::image_url("https://example.com/" + std::string(8200, 'a')), ApiError); + Rules::image_url("https://example.com/a.jpg"); + Rules::image_url("data:image/jpeg;base64,AAAA"); + ASSERT_THROW(Rules::detail("ultra"), ApiError); + Rules::detail("original"); + for (const char* e : {"none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"}) Rules::effort(e); + ASSERT_THROW(Rules::effort("extreme"), ApiError); + ASSERT_THROW(Rules::top_p(0), ApiError); + ASSERT_THROW(Rules::top_p(1.01), ApiError); + Rules::top_p(1); + ASSERT_TRUE(Rules::has_json_word("Output in JSON please")); + ASSERT_FALSE(Rules::has_json_word("output as data")); + ASSERT_TRUE(Rules::is_http_url("https://a.example/x?y=1")); + ASSERT_FALSE(Rules::is_http_url("https://user:pw@a.example/")); + ASSERT_FALSE(Rules::is_http_url("https:///nohost")); + ASSERT_FALSE(Rules::is_http_url("https://a b.example/")); +} + +TEST(deepseek_chat, minimal_body_follows_the_documented_shape) { + ChatParams p = ChatParams::prompt("Hello!"); + Json b = p.to_json(); + ASSERT_EQ(b.dump(), "{\"messages\":[{\"content\":\"Hello!\",\"role\":\"user\"}],\"model\":\"deepseek-flash\"}"); + p.add(Messages::system("You are a helpful assistant.")); + p.thinking = Thinking::kEnabled; + p.reasoning_effort = "high"; + p.max_tokens = 128; + p.stop = {"```"}; + p.user_id = "u-1"; + p.temperature = 0.5; + p.top_p = 0.9; + p.logprobs = true; + p.top_logprobs = 3; + Json full = p.to_json(true); + ASSERT_EQ(full.find("thinking")->find("type")->as_string(), "enabled"); + ASSERT_EQ(full.find("reasoning_effort")->as_string(), "high"); + ASSERT_EQ(full.find("max_tokens")->as_int(), 128); + ASSERT_TRUE(full.find("stream")->as_bool()); + ASSERT_TRUE(full.find("stream_options")->find("include_usage")->as_bool()); + ASSERT_EQ(full.find("user_id")->as_string(), "u-1"); + ASSERT_EQ(full.find("top_logprobs")->as_int(), 3); + // frequency_penalty / presence_penalty are deprecated and never sent + ASSERT_FALSE(full.has("frequency_penalty")); + ASSERT_FALSE(full.has("presence_penalty")); + ASSERT_FALSE(b.has("stream")); + ASSERT_FALSE(b.has("stream_options")); +} + +TEST(deepseek_chat, validation_rules) { + auto bad = [](const std::function& mutate, const std::string& expect) { + ChatParams p = ChatParams::prompt("hi"); + mutate(p); + std::string msg = invalid_message([&] { p.to_json(); }); + ASSERT_TRUE(has(msg, expect)); + }; + bad([](ChatParams& p) { p.messages = Json::array(); }, "messages must not be empty"); + bad([](ChatParams& p) { p.max_tokens = 0; }, "max_tokens"); + bad([](ChatParams& p) { p.max_tokens = 393217; }, "max_tokens"); + bad([](ChatParams& p) { p.temperature = 2.5; }, "temperature"); + bad([](ChatParams& p) { p.top_p = 0.0; }, "top_p"); + bad([](ChatParams& p) { p.top_logprobs = 5; }, "needs logprobs"); + bad([](ChatParams& p) { p.logprobs = true; p.top_logprobs = 21; }, "top_logprobs"); + bad([](ChatParams& p) { p.reasoning_effort = "loud"; }, "reasoning effort"); + bad([](ChatParams& p) { p.thinking = Thinking::kEnabled; p.reasoning_effort = "none"; }, "contradicts"); + bad([](ChatParams& p) { p.json_mode = true; }, "'json'"); + bad([](ChatParams& p) { p.user_id = "no spaces"; }, "user_id"); + bad([](ChatParams& p) { p.stop = std::vector(17, "x"); }, "16 stop"); + bad([](ChatParams& p) { p.messages.push(Json(5)); }, "message must be an object"); + bad([](ChatParams& p) { Json m = Json::object(); m.set("role", Json("robot")); m.set("content", Json("x")); p.add(m); }, "role"); + bad([](ChatParams& p) { p.add(Messages::tool("", "x")); }, "tool_call_id"); + bad([](ChatParams& p) { p.extra.set("model", Json("x")); }, "collides"); + bad([](ChatParams& p) { p.tool_choice = "auto"; }, "needs tools"); + // json mode passes with the word in a message + ChatParams ok = ChatParams::prompt("Answer in JSON: {\"a\":1}"); + ok.json_mode = true; + ASSERT_EQ(ok.to_json().find("response_format")->find("type")->as_string(), "json_object"); +} + +TEST(deepseek_chat, tool_choice_rules_in_thinking_mode) { + ChatParams p = ChatParams::prompt("weather?"); + ToolDef t; + t.name = "get_weather"; + t.parameters = Json::parse("{\"type\":\"object\",\"properties\":{\"location\":{\"type\":\"string\"}},\"required\":[\"location\"]}"); + p.tools.push_back(t); + p.tool_choice = "auto"; + p.validate(); + // thinking is on by default: required and named choices are a 400 upstream, rejected here + p.tool_choice = "required"; + ASSERT_TRUE(has(invalid_message([&] { p.validate(); }), "thinking mode")); + p.tool_choice = "get_weather"; + ASSERT_TRUE(has(invalid_message([&] { p.validate(); }), "thinking mode")); + p.thinking = Thinking::kDisabled; + Json b = p.to_json(); + ASSERT_EQ(b.find("tool_choice")->find("function")->find("name")->as_string(), "get_weather"); + p.tool_choice = "required"; + ASSERT_EQ(p.to_json().find("tool_choice")->as_string(), "required"); + // effort none also switches thinking off + p.thinking = Thinking::kDefault; + p.reasoning_effort = "none"; + ASSERT_FALSE(p.thinking_on()); + p.validate(); + p.tool_choice = "missing_tool"; + ASSERT_TRUE(has(invalid_message([&] { p.validate(); }), "not defined")); + // names are unique, tools are capped + p.tool_choice = ""; + p.tools.push_back(t); + ASSERT_TRUE(has(invalid_message([&] { p.validate(); }), "unique")); +} + +TEST(deepseek_chat, reasoning_content_is_dropped_without_tools_and_kept_with_tools) { + // Thinking Mode guide: with tools, every earlier reasoning_content is sent back + // (400 otherwise); without tools the API ignores it, so it must not be sent. + ChatParams p; + p.add(Messages::user("9.11 and 9.8, which is greater?")); + p.add(Messages::assistant("9.8 is greater", "compare 9.11 and 9.80 ...")); + p.add(Messages::user("How many Rs are there in strawberry?")); + Json no_tools = p.to_json(); + ASSERT_FALSE(no_tools.find("messages")->as_array()[1].has("reasoning_content")); + ASSERT_EQ(p.messages.as_array()[1].find("reasoning_content")->as_string(), "compare 9.11 and 9.80 ..."); // input untouched + + ToolDef t; + t.name = "get_date"; + p.tools.push_back(t); + Json with_tools = p.to_json(); + ASSERT_EQ(with_tools.find("messages")->as_array()[1].find("reasoning_content")->as_string(), + "compare 9.11 and 9.80 ..."); +} + +TEST(deepseek_chat, vision_and_file_parts) { + ChatParams p; + p.model = "deepseek-flash"; + p.add(Messages::user_parts({Messages::text_part("What is in this image?"), + Messages::image_part("https://example.com/image.jpg", "low"), + Messages::file_part("file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9")})); + Json b = p.to_json(); + const Json& parts = *b.find("messages")->as_array()[0].find("content"); + ASSERT_EQ(parts.as_array()[1].find("image_url")->find("detail")->as_string(), "low"); + ASSERT_EQ(parts.as_array()[2].find("file_id")->as_string(), "file-api-0a1b2c3d4e5f60718293a4b5c6d7e8f9"); + // file_data inline needs a data URL and may carry a filename; file_id forbids filename + p.add(Messages::user_parts({Messages::file_data_part("data:image/jpeg;base64,AAAA", "image.jpg")})); + p.validate(); + Json both = Messages::file_part("file-api-x"); + both.set("filename", Json("a.jpg")); + ChatParams q; + q.add(Messages::user_parts({both})); + ASSERT_TRUE(has(invalid_message([&] { q.validate(); }), "filename")); + ChatParams r; + Json neither = Json::object(); + neither.set("type", Json("file")); + r.add(Messages::user_parts({neither})); + ASSERT_TRUE(has(invalid_message([&] { r.validate(); }), "exactly one")); + ChatParams s; + s.add(Messages::user_parts({Messages::image_part("gopher://x")})); + ASSERT_TRUE(has(invalid_message([&] { s.validate(); }), "image url")); + ChatParams u; + Json bad_part = Json::object(); + bad_part.set("type", Json("audio")); + u.add(Messages::user_parts({bad_part})); + ASSERT_TRUE(has(invalid_message([&] { u.validate(); }), "unknown content part")); + // 600 images per request + ChatParams many; + std::vector parts600; + for (int i = 0; i < 601; ++i) parts600.push_back(Messages::image_part("https://example.com/a.png")); + many.add(Messages::user_parts(parts600)); + ASSERT_TRUE(has(invalid_message([&] { many.validate(); }), "600")); +} + +TEST(deepseek_chat, beta_prefix_and_strict_routing) { + ChatParams p = ChatParams::prompt("Please write quick sort code"); + ASSERT_FALSE(p.needs_beta()); + ASSERT_TRUE(Chat::call_for(p) == Call::kChat); + p.add(Messages::assistant_prefix("```python\n")); + p.stop = {"```"}; + ASSERT_TRUE(p.has_prefix()); + ASSERT_TRUE(p.needs_beta()); + ASSERT_TRUE(Chat::call_for(p) == Call::kChatBeta); + Json b = p.to_json(); + const Json& last = b.find("messages")->as_array().back(); + ASSERT_TRUE(last.find("prefix")->as_bool()); + ASSERT_EQ(last.find("role")->as_string(), "assistant"); + // the prefix must be last and an assistant message + p.add(Messages::user("and then?")); + ASSERT_TRUE(has(invalid_message([&] { p.validate(); }), "last message")); + // the prefix message keeps its reasoning_content (CoT input) even without tools + ChatParams q = ChatParams::prompt("hi"); + q.add(Messages::assistant_prefix("Answer:", "my chain of thought")); + ASSERT_EQ(q.to_json().find("messages")->as_array().back().find("reasoning_content")->as_string(), + "my chain of thought"); +} + +TEST(deepseek_chat, strict_mode_schema_rules) { + // FIXTURE (Tool Calls guide, strict Mode): the documented get_weather definition + ToolDef t; + t.name = "get_weather"; + t.description = "Get weather of a location, the user should supply a location first."; + t.strict = true; + t.parameters = Json::parse( + "{\"type\":\"object\",\"properties\":{\"location\":{\"type\":\"string\",\"description\":\"The city and state, e.g. San Francisco, CA\"}}," + "\"required\":[\"location\"],\"additionalProperties\":false}"); + ASSERT_EQ(StrictSchema::check(t.parameters), ""); + ChatParams p = ChatParams::prompt("weather in Hangzhou"); + p.tools.push_back(t); + ASSERT_TRUE(p.needs_beta()); + ASSERT_TRUE(Chat::call_for(p) == Call::kChatBeta); + Json body = p.to_json(); + ASSERT_TRUE(body.find("tools")->as_array()[0].find("function")->find("strict")->as_bool()); + + auto problem = [](const char* schema) { return StrictSchema::check(Json::parse(schema)); }; + ASSERT_TRUE(has(problem("{\"type\":\"object\",\"properties\":{\"a\":{\"type\":\"string\"}},\"additionalProperties\":false}"), "required")); + ASSERT_TRUE(has(problem("{\"type\":\"object\",\"properties\":{\"a\":{\"type\":\"string\"}},\"required\":[\"a\"]}"), "additionalProperties")); + ASSERT_TRUE(has(problem("{\"type\":\"object\",\"properties\":{\"a\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"a\"],\"additionalProperties\":false}"), "minLength")); + ASSERT_TRUE(has(problem("{\"type\":\"object\",\"properties\":{\"a\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"maxItems\":3}},\"required\":[\"a\"],\"additionalProperties\":false}"), "maxItems")); + ASSERT_TRUE(has(problem("{\"type\":\"object\",\"properties\":{\"a\":{\"type\":\"null\"}},\"required\":[\"a\"],\"additionalProperties\":false}"), "null")); + ASSERT_TRUE(has(problem("{\"type\":\"string\"}"), "root")); + // anyOf, enum, array of strings, $ref pass + ASSERT_EQ(problem("{\"type\":\"object\",\"properties\":{\"account\":{\"anyOf\":[{\"type\":\"string\",\"format\":\"email\"},{\"type\":\"string\",\"pattern\":\"^\\\\d{11}$\"}]}," + "\"status\":{\"type\":\"string\",\"enum\":[\"a\",\"b\"]},\"k\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}}," + "\"required\":[\"account\",\"status\",\"k\"],\"additionalProperties\":false}"), ""); + // strict on one tool only is rejected: "all function need to set the strict property to true" + ChatParams mixed = ChatParams::prompt("x"); + mixed.tools.push_back(t); + ToolDef loose; + loose.name = "other"; + mixed.tools.push_back(loose); + ASSERT_TRUE(has(invalid_message([&] { mixed.validate(); }), "every function")); + // an invalid strict schema is rejected before the network + ToolDef broken = t; + broken.parameters = Json::parse("{\"type\":\"object\",\"properties\":{\"a\":{\"type\":\"string\"}}}"); + ChatParams bad = ChatParams::prompt("x"); + bad.tools.push_back(broken); + ASSERT_TRUE(has(invalid_message([&] { bad.validate(); }), "strict tool 'get_weather'")); +} + +TEST(deepseek_fim, validation_and_body) { + FimParams f; + f.prompt = "def fib(a):"; + f.suffix = " return fib(a-1) + fib(a-2)"; + f.max_tokens = 128; + Json b = f.to_json(); + ASSERT_EQ(b.find("suffix")->as_string(), f.suffix); + ASSERT_EQ(b.find("max_tokens")->as_int(), 128); + ASSERT_FALSE(b.has("stream")); + ASSERT_TRUE(f.to_json(true).find("stream")->as_bool()); + f.max_tokens = 4097; + ASSERT_TRUE(has(invalid_message([&] { f.validate(); }), "4096")); + f.max_tokens = 10; + f.echo = true; + ASSERT_TRUE(has(invalid_message([&] { f.validate(); }), "echo")); + f.suffix.clear(); + f.logprobs = 3; + ASSERT_TRUE(has(invalid_message([&] { f.validate(); }), "echo")); + f.logprobs = std::nullopt; + f.validate(); + FimParams empty; + ASSERT_TRUE(has(invalid_message([&] { empty.validate(); }), "prompt")); + FimParams lp; + lp.prompt = "x"; + lp.logprobs = 21; + ASSERT_TRUE(has(invalid_message([&] { lp.validate(); }), "logprobs")); +}