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

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-24 07:40:33 +02:00
co-authored by Claude Sonnet 5.5
parent 2e0270c043
commit 927e4e5a2f
42 changed files with 6219 additions and 3 deletions
+205
View File
@@ -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": "<text>"}`.
- 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`).
+51
View File
@@ -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
+46
View File
@@ -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 <string>
#include "deepseek/types.h"
#include "llm/api_client.h"
namespace molo::deepseek {
class Account : public llm::Service {
public:
explicit Account(std::shared_ptr<llm::ApiClient> 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
+383
View File
@@ -0,0 +1,383 @@
#include "deepseek/anthropic.h"
#include <set>
#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<Json>& 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<std::string>& supported_blocks() {
static const std::set<std::string> s = {"text", "image", "thinking", "tool_use", "tool_result",
"server_tool_use", "web_search_tool_result"};
return s;
}
const std::set<std::string>& unsupported_blocks() {
static const std::set<std::string> 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<std::string> 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::ToolUse> MessagesResult::tool_uses() const {
std::vector<ToolUse> 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<std::size_t>(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<std::size_t>(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<std::size_t>(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<bool(const llm::SseEvent&, const std::string&)>& 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
+99
View File
@@ -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 <functional>
#include <optional>
#include <string>
#include <vector>
#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<Json>& 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<bool> 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<std::string> stop_sequences;
std::optional<double> temperature; // 0..2
std::optional<double> 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<ToolUse> 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<std::string> 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<llm::ApiClient> 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<bool(const llm::SseEvent&, const std::string& text_delta)>& on_event);
};
} // namespace molo::deepseek
+92
View File
@@ -0,0 +1,92 @@
#include "deepseek/calls.h"
#include <cstring>
#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
+58
View File
@@ -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 <cstddef>
#include <string>
#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
+41
View File
@@ -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 <cstddef>
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
+87
View File
@@ -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
+67
View File
@@ -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 <functional>
#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<llm::ApiClient> client) : llm::Service(std::move(client)) {}
ChatResult create(const ChatParams& params);
using DeltaSink = std::function<bool(const StreamDelta&)>; // 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<std::string(const std::string&, const Json&, const std::string&)>;
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
+199
View File
@@ -0,0 +1,199 @@
#include "deepseek/chat_model.h"
#include <map>
#include "deepseek/platform.h"
#include "deepseek/rules.h"
#include "security/crypto/Base64.h"
namespace molo::deepseek {
DeepseekChatModel::DeepseekChatModel(std::shared_ptr<Chat> chat, std::string default_model)
: chat_(std::move(chat)), default_model_(std::move(default_model)) {}
std::shared_ptr<DeepseekChatModel> DeepseekChatModel::from_env(const std::string& default_model) {
Platform p = Platform::from_env();
return std::make_shared<DeepseekChatModel>(std::make_shared<Chat>(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<Json> parts;
for (const llm::ContentPart& p : m.parts) {
if (!p.text.empty()) parts.push_back(Messages::text_part(p.text));
if (p.image) parts.push_back(image_part_of(*p.image));
}
params.add(Messages::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<bool(const llm::ChatChunk&)>& on_chunk) {
ChatParams params = to_params(request);
std::map<int, std::string> ids; // tool index -> call id, so later fragments carry it
std::map<int, std::string> 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
+44
View File
@@ -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": "<raw text>"} instead of being dropped.
// - finish_reason is passed through (stop, length, tool_calls, content_filter,
// insufficient_system_resource, aborted).
#include <memory>
#include "deepseek/chat.h"
#include "llm/chat_types.h"
namespace molo::deepseek {
class DeepseekChatModel : public llm::ChatModel {
public:
explicit DeepseekChatModel(std::shared_ptr<Chat> chat, std::string default_model = "deepseek-flash");
static std::shared_ptr<DeepseekChatModel> 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<bool(const llm::ChatChunk&)>& 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> chat_;
std::string default_model_;
};
} // namespace molo::deepseek
+430
View File
@@ -0,0 +1,430 @@
#include "deepseek/chat_params.h"
#include <algorithm>
#include <set>
#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<Json>& 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<Json>& 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<std::string> 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<std::string> 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<std::string> 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
+94
View File
@@ -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 <optional>
#include <string>
#include <vector>
#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<Json>& 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<Json>& 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<int> max_tokens; // 1..393216
bool json_mode = false; // response_format {"type":"json_object"}
std::vector<std::string> stop; // up to 16
bool include_usage = true; // stream_options.include_usage (stream only)
std::optional<double> temperature; // 0..2; no effect in thinking mode
std::optional<double> top_p; // (0,1]
std::vector<ToolDef> tools;
// "", none, auto, required, or a function name (required / named need thinking off).
std::string tool_choice;
bool logprobs = false;
std::optional<int> 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
+180
View File
@@ -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<int>(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<int>(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<int>(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
+89
View File
@@ -0,0 +1,89 @@
#pragma once
// Chat Completions response and the stream accumulator that folds
// chat.completion.chunk documents into the same ChatResult.
#include <string>
#include <vector>
#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<ToolCallRecord> 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<ChatChoice> 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<ToolFragment> 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
+82
View File
@@ -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
+48
View File
@@ -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 <string>
#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
+143
View File
@@ -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
+68
View File
@@ -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 <optional>
#include <string>
#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<long> 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<llm::ApiClient> 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<llm::ApiClient> 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
+123
View File
@@ -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<int>(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<bool(const std::string&)>& 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
+55
View File
@@ -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 <functional>
#include <optional>
#include <string>
#include <vector>
#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<int> max_tokens; // 1..4096
bool echo = false; // not with suffix or logprobs
std::optional<int> logprobs; // 0..20
std::vector<std::string> stop;
bool include_usage = true;
std::optional<double> temperature;
std::optional<double> 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<FimChoice> choices;
TokenUsage usage;
const FimChoice& first() const;
static FimResult parse(const Json& doc);
};
class Fim : public llm::Service {
public:
explicit Fim(std::shared_ptr<llm::ApiClient> 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<bool(const std::string&)>& on_text);
};
} // namespace molo::deepseek
+38
View File
@@ -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<clients::Transport> openai_transport,
std::unique_ptr<clients::Transport> anthropic_transport,
const std::string& key) {
Platform p;
p.openai = std::make_shared<llm::ApiClient>(std::move(openai_transport), config(Surface::kOpenai), key);
p.anthropic = std::make_shared<llm::ApiClient>(std::move(anthropic_transport),
config(Surface::kAnthropic), key);
return p;
}
} // namespace molo::deepseek
+31
View File
@@ -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 <memory>
#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<llm::ApiClient> openai;
std::shared_ptr<llm::ApiClient> 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<clients::Transport> openai_transport,
std::unique_ptr<clients::Transport> anthropic_transport,
const std::string& key);
bool configured() const { return openai && openai->configured(); }
};
} // namespace molo::deepseek
+358
View File
@@ -0,0 +1,358 @@
#include "deepseek/responses.h"
#include <set>
#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<Json>& 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<Json>& 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<std::string> 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<std::string> 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<FunctionCallItem> ResponsesResult::function_calls() const {
std::vector<FunctionCallItem> 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<bool(const ResponseEvent&)>& 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
+99
View File
@@ -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 <functional>
#include <optional>
#include <string>
#include <vector>
#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<Json>& 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<Json>& 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<std::string> 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<int> max_output_tokens; // includes reasoning tokens
std::optional<double> temperature;
std::optional<double> 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<int> 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<FunctionCallItem> 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<llm::ApiClient> 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<bool(const ResponseEvent&)>& on_event);
};
} // namespace molo::deepseek
+87
View File
@@ -0,0 +1,87 @@
#include "deepseek/rules.h"
#include <cctype>
#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<unsigned char>(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<std::string>& 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<unsigned char>(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<unsigned char>(text[i])) == 'j' &&
std::tolower(static_cast<unsigned char>(text[i + 1])) == 's' &&
std::tolower(static_cast<unsigned char>(text[i + 2])) == 'o' &&
std::tolower(static_cast<unsigned char>(text[i + 3])) == 'n')
return true;
return false;
}
} // namespace molo::deepseek
+38
View File
@@ -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 <string>
#include <vector>
#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<std::string>& 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
+168
View File
@@ -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'(?<![A-Za-z0-9_])' + re.escape(field) + r'(?![a-z0-9_])')
return any(word.search(l) or l.startswith(field) for l in lines)
def has_route(lines, method, path, api_page):
if api_page:
doc_path = path.replace("{file_id}", ":file_id")
for i, l in enumerate(lines):
if l.startswith(method) and l.rstrip() == method and any(
x == doc_path for x in lines[i + 1:i + 3]):
return True
return False
joined = "\n".join(lines)
if method in ("GET", "POST", "DELETE") and (method + " " + path) in joined:
return True
if path in joined:
return True
# guide prose: "base_url ... /anthropic" and an SDK call <resource>.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"<loc>([^<]*)</loc>", 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())
+216
View File
@@ -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<int>(J::num(doc, key)); }
std::vector<std::string> strings(const Json& doc, const char* key) {
std::vector<std::string> 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<double>(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<int>(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
+123
View File
@@ -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 <optional>
#include <string>
#include <vector>
#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<std::string> input_modalities;
std::vector<std::string> output_modalities;
std::vector<std::string> 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<ModelInfo> 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<BalanceEntry> 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<long> 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<FileInfo> 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<SearchHit> 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
+60
View File
@@ -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
+35
View File
@@ -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 <optional>
#include <string>
#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<std::string> 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<llm::ApiClient> 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