diff --git a/example/app/ai/AnthropicDemo.cpp b/example/app/ai/AnthropicDemo.cpp
index 0ed2309..ca711e7 100644
--- a/example/app/ai/AnthropicDemo.cpp
+++ b/example/app/ai/AnthropicDemo.cpp
@@ -1,13 +1,512 @@
#include "../AiDemos.hpp"
#include "../../fw/Router.hpp"
+#include "../../fw/Templates.hpp"
+#include "anthropic/core/anthropic.h"
+#include "anthropic/core/caps.h"
namespace molo::example::app {
-// Anthropic Claude: messages, streaming, tools, batches, tokens, models, files, skills. Stub: the module agent fills this in.
+// Anthropic Claude (api.anthropic.com) over src/anthropic/core. GET routes need
+// no credential. Routes that call the vendor are POST: 422 on bad input first,
+// then 503 anthropic_not_configured without ANTHROPIC_API_KEY. Anything that
+// costs money (messages, stream, batch create) or deletes is a dry run unless
+// the body has "confirm":true. /ai/anthropic/build only builds and validates
+// the request offline.
+
+namespace {
+
+namespace core = anthropic::core;
+using Json = clients::body::Json;
+
+constexpr std::size_t kMaxBody = 512 * 1024;
+constexpr std::size_t kMaxStreamEventsShown = 200;
+
+const char kPage[] = R"ANTHROPIC({% extends "base.html" %}
+{% block content %}
+
Anthropic Claude
+
Messages, streaming, tools, batches, token counting, models, files,
+skills. Calls that cost money or delete are dry runs until the body says
+"confirm":true.
+
Checking credentials...
+
+
+
+
+
+
+
+
+
+
+
+
+{% endblock %}
+)ANTHROPIC";
+
+fw::Response json_out(const Json& j, int status = 200) {
+ fw::Response res = fw::JsonResponse(j.dump(), status);
+ res.headers.set("Cache-Control", "no-store");
+ return res;
+}
+
+[[noreturn]] void bad(const std::string& why) { throw fw::HttpError(422, "validation_error", why); }
+
+template
+auto guarded(F&& f) -> decltype(f()) {
+ try {
+ return f();
+ } catch (const core::AnthropicError& e) {
+ if (e.kind() == core::ErrorKind::kNotConfigured)
+ throw fw::HttpError(503, "anthropic_not_configured", e.message());
+ if (e.kind() == core::ErrorKind::kInvalidArgument) throw fw::HttpError(422, "validation_error", e.message());
+ throw fw::HttpError(502, "anthropic_error", e.type() + ": " + e.message());
+ } catch (const llm::ApiError& e) {
+ if (e.type() == "NOT_CONFIGURED") throw fw::HttpError(503, "anthropic_not_configured", e.message());
+ if (e.type() == "INVALID_ARGUMENT") throw fw::HttpError(422, "validation_error", e.message());
+ throw fw::HttpError(502, "anthropic_error", e.type() + ": " + e.message());
+ }
+}
+
+Json parse_body(const fw::Request& req) {
+ if (req.body.size() > kMaxBody) throw fw::HttpError(413, "payload_too_large", "body too large");
+ if (req.body.empty()) return Json::object();
+ try {
+ Json j = Json::parse(req.body);
+ if (!j.is_object()) bad("body must be a JSON object");
+ return j;
+ } catch (const clients::body::JsonError&) {
+ bad("body is not valid JSON");
+ }
+}
+
+std::string text(const Json& body, const char* key, bool required = false) {
+ const Json* v = body.find(key);
+ if (!v || v->is_null()) {
+ if (required) bad(std::string(key) + " is required");
+ return "";
+ }
+ if (!v->is_string()) bad(std::string(key) + " must be a string");
+ return v->as_string();
+}
+
+int number(const Json& body, const char* key, int fallback = 0) {
+ const Json* v = body.find(key);
+ if (!v || v->is_null()) return fallback;
+ if (!v->is_number()) bad(std::string(key) + " must be a number");
+ return static_cast(v->as_int());
+}
+
+bool confirmed(const Json& body) {
+ const Json* c = body.find("confirm");
+ if (c && !c->is_bool()) bad("confirm must be true or false");
+ return c && c->as_bool();
+}
+
+Json dry_run(const std::string& what, const Json& detail) {
+ Json o = Json::object();
+ o.set("dry_run", Json(true));
+ o.set("would", Json(what));
+ o.set("request", detail);
+ o.set("hint", Json("send confirm:true to run it"));
+ return o;
+}
+
+// Maps the demo's JSON body onto a typed request; every rule is the module's.
+core::MessageRequest request_from(const Json& body) {
+ core::MessageRequest r;
+ r.model = text(body, "model", true);
+ r.set_max_tokens(number(body, "max_tokens", 256));
+ r.system_text = text(body, "system");
+ const Json* ms = body.find("messages");
+ if (ms && ms->is_array()) {
+ for (const Json& m : ms->as_array()) {
+ std::string role = text(m, "role", true);
+ const Json* c = m.find("content");
+ if (!c) bad("every message needs content");
+ core::MessageParam p;
+ if (role == "user") p.role = core::MessageParam::Role::kUser;
+ else if (role == "assistant") p.role = core::MessageParam::Role::kAssistant;
+ else if (role == "system") p.role = core::MessageParam::Role::kSystem;
+ else bad("role must be user, assistant or system");
+ if (c->is_string()) {
+ p.text = c->as_string();
+ } else if (c->is_array()) {
+ for (const Json& b : c->as_array()) p.blocks.push_back(core::ContentBlock::from_json(b));
+ } else {
+ bad("content must be a string or an array of blocks");
+ }
+ r.add(std::move(p));
+ }
+ } else if (!text(body, "prompt").empty()) {
+ r.add(core::MessageParam::user(text(body, "prompt")));
+ } else {
+ bad("messages (array) or prompt (string) is required");
+ }
+ if (const Json* ts = body.find("tools")) {
+ if (!ts->is_array()) bad("tools must be an array");
+ for (const Json& t : ts->as_array()) r.add_tool(core::Tool::from_json(t));
+ }
+ std::string tc = text(body, "tool_choice");
+ if (tc == "auto") r.tool_choice = core::ToolChoice::auto_();
+ else if (tc == "any") r.tool_choice = core::ToolChoice::any();
+ else if (tc == "none") r.tool_choice = core::ToolChoice::none();
+ else if (!tc.empty()) r.tool_choice = core::ToolChoice::tool(tc);
+ if (const Json* th = body.find("thinking"); th && th->is_object()) {
+ std::string t = text(*th, "type", true);
+ if (t == "enabled") r.thinking = core::ThinkingConfig::enabled(number(*th, "budget_tokens"));
+ else if (t == "adaptive") r.thinking = core::ThinkingConfig::adaptive();
+ else if (t == "disabled") r.thinking = core::ThinkingConfig::disabled();
+ else if (t == "between_tools") r.thinking = core::ThinkingConfig::between_tools();
+ else bad("thinking.type is not valid");
+ }
+ r.output.effort = text(body, "effort");
+ r.speed = text(body, "speed");
+ r.user_profile_id = text(body, "user_profile_id");
+ if (const Json* ss = body.find("stop_sequences"); ss && ss->is_array())
+ for (const Json& s : ss->as_array()) {
+ if (!s.is_string()) bad("stop_sequences must be strings");
+ r.stop_sequences.push_back(s.as_string());
+ }
+ if (const Json* b = body.find("betas")) {
+ if (!b->is_array()) bad("betas must be an array of strings");
+ for (const Json& n : b->as_array()) {
+ if (!n.is_string()) bad("betas must be an array of strings");
+ r.betas.add_name(n.as_string());
+ }
+ }
+ if (const Json* t = body.find("temperature")) r.temperature = t->is_number() ? t->as_number() : (bad("temperature must be a number"), 0.0);
+ return r;
+}
+
+core::ApiVersion version_from(const Json& body) {
+ std::string v = text(body, "version");
+ return v.empty() ? core::kDefaultVersion : core::parse_version(v);
+}
+
+Json built(const core::MessageRequest& r, core::ApiVersion v, bool stream) {
+ r.validate(v);
+ Json o = Json::object();
+ o.set("anthropic_version", Json(core::version_name(v)));
+ o.set("anthropic_beta", Json(r.effective_betas().header_value()));
+ o.set("body", r.to_json(stream, v));
+ return o;
+}
+
+std::vector id_list(const Json& body, const char* key) {
+ std::vector out;
+ if (const Json* a = body.find(key)) {
+ if (!a->is_array()) bad(std::string(key) + " must be an array of strings");
+ for (const Json& s : a->as_array()) {
+ if (!s.is_string()) bad(std::string(key) + " must be an array of strings");
+ out.push_back(s.as_string());
+ }
+ }
+ return out;
+}
+
+Json page_json(const core::Page& p) {
+ Json o = Json::object();
+ o.set("data", Json(p.data));
+ o.set("has_more", Json(p.has_more));
+ o.set("truncated", Json(p.truncated));
+ if (!p.next_page.empty()) o.set("next_page", Json(p.next_page));
+ if (!p.last_id.empty()) o.set("last_id", Json(p.last_id));
+ return o;
+}
+
+void need_id(const std::string& id) {
+ if (!llm::Service::valid_id(id)) bad("id must be one segment of A-Z a-z 0-9 . _ : -");
+}
+
+} // namespace
+
void register_ai_anthropic_demo(fw::Router& router, Services& services) {
- (void)router;
- (void)services;
+ auto api = std::make_shared(core::Anthropic::from_env());
+ fw::Environment* env = services.templates.get();
+ services.templates->add_template("ai_anthropic.html", kPage);
+ services.add_feature("ai-anthropic", "/ai/anthropic");
+
+ router.get("/ai/anthropic", "ai-anthropic-page", [env](fw::Request req) {
+ (void)req;
+ fw::TemplateCtx ctx;
+ ctx["title"] = std::string("Anthropic Claude");
+ return fw::Response(200, env->render("ai_anthropic.html", ctx), "text/html; charset=utf-8");
+ });
+
+ router.get("/ai/anthropic/status", "ai-anthropic-status", [api](fw::Request req) {
+ (void)req;
+ Json o = Json::object();
+ o.set("configured", Json(api->configured()));
+ o.set("key_env", Json(api->session().options().key_env));
+ o.set("base_url", Json(api->session().options().base_url));
+ o.set("default_version", Json(core::version_name(core::kDefaultVersion)));
+ o.set("calls", Json(static_cast(core::call_count())));
+ o.set("betas", Json(static_cast(core::beta_count())));
+ o.set("tool_types", Json(static_cast(core::tool_schema_count())));
+ o.set("block_types", Json(static_cast(core::block_schema_count())));
+ o.set("max_stream_events", Json(static_cast(kMaxStreamEventsShown)));
+ return json_out(o);
+ });
+
+ router.get("/ai/anthropic/calls", "ai-anthropic-calls", [](fw::Request req) {
+ (void)req;
+ Json arr = Json::array();
+ for (std::size_t i = 0; i < core::call_count(); ++i) {
+ const core::CallSpec& s = core::spec_at(i);
+ Json row = Json::object();
+ row.set("key", Json(s.key));
+ row.set("http", Json(s.http_method));
+ row.set("path", Json(s.path));
+ row.set("body_fields", Json(s.body_fields));
+ row.set("query_params", Json(s.query_params));
+ arr.push(row);
+ }
+ Json o = Json::object();
+ o.set("calls", arr);
+ return json_out(o);
+ });
+
+ router.get("/ai/anthropic/betas", "ai-anthropic-betas", [](fw::Request req) {
+ (void)req;
+ Json arr = Json::array();
+ for (std::size_t i = 0; i < core::beta_count(); ++i) {
+ const core::BetaInfo& b = core::beta_at(i);
+ Json row = Json::object();
+ row.set("name", Json(b.wire));
+ row.set("status", Json(b.status == core::BetaStatus::kCurrent ? "current"
+ : b.status == core::BetaStatus::kLegacy ? "legacy"
+ : b.status == core::BetaStatus::kOtherPackage ? "admin_package"
+ : "unknown"));
+ row.set("meaning", Json(b.meaning));
+ arr.push(row);
+ }
+ Json o = Json::object();
+ o.set("betas", arr);
+ return json_out(o);
+ });
+
+ router.get("/ai/anthropic/tools", "ai-anthropic-tools", [](fw::Request req) {
+ (void)req;
+ Json arr = Json::array();
+ for (std::size_t i = 0; i < core::tool_schema_count(); ++i) {
+ const core::ToolSchema& t = core::tool_schema_at(i);
+ Json row = Json::object();
+ row.set("type", Json(t.type));
+ row.set("name", Json(t.name));
+ row.set("beta", Json(t.beta));
+ row.set("ga", Json(t.ga));
+ arr.push(row);
+ }
+ Json o = Json::object();
+ o.set("tools", arr);
+ return json_out(o);
+ });
+
+ // Offline: builds and validates, never calls the vendor.
+ router.post("/ai/anthropic/build", "ai-anthropic-build", [](fw::Request req) {
+ Json body = parse_body(req);
+ return guarded([&] { return json_out(built(request_from(body), version_from(body), false)); });
+ });
+
+ router.post("/ai/anthropic/count", "ai-anthropic-count", [api](fw::Request req) {
+ Json body = parse_body(req);
+ return guarded([&] {
+ core::MessageRequest r = request_from(body);
+ r.validate(version_from(body));
+ core::TokenCount t = api->messages->count_tokens(r);
+ return json_out(t.raw);
+ });
+ });
+
+ router.post("/ai/anthropic/messages", "ai-anthropic-messages", [api](fw::Request req) {
+ Json body = parse_body(req);
+ return guarded([&] {
+ core::MessageRequest r = request_from(body);
+ Json plan = built(r, version_from(body), false);
+ if (!confirmed(body)) return json_out(dry_run("create a message", plan));
+ core::MessageResult res = api->messages->create(r);
+ Json o = Json::object();
+ o.set("message", res.message.raw);
+ o.set("text", Json(res.message.text()));
+ o.set("betas_sent", Json(res.betas.header_value()));
+ o.set("request_id", Json(res.limits.request_id));
+ return json_out(o);
+ });
+ });
+
+ router.post("/ai/anthropic/stream", "ai-anthropic-stream", [api](fw::Request req) {
+ Json body = parse_body(req);
+ return guarded([&] {
+ core::MessageRequest r = request_from(body);
+ Json plan = built(r, version_from(body), true);
+ if (!confirmed(body)) return json_out(dry_run("stream a message", plan));
+ Json events = Json::array();
+ core::StreamResult res = api->messages->stream(r, [&](const core::StreamEvent& e) {
+ events.push(e.data);
+ return events.as_array().size() < kMaxStreamEventsShown;
+ });
+ Json o = Json::object();
+ o.set("events", events);
+ o.set("complete", Json(res.complete));
+ o.set("message", res.message.raw);
+ return json_out(o);
+ });
+ });
+
+ router.post("/ai/anthropic/models", "ai-anthropic-models", [api](fw::Request req) {
+ Json body = parse_body(req);
+ std::string id = text(body, "id");
+ if (!id.empty()) need_id(id);
+ int limit = number(body, "limit", 0);
+ return guarded([&] {
+ if (!id.empty()) return json_out(api->models->retrieve(id).raw);
+ return json_out(page_json(api->models->list(limit, "", "", id_list(body, "lifecycle"))));
+ });
+ });
+
+ router.post("/ai/anthropic/batches", "ai-anthropic-batches", [api](fw::Request req) {
+ Json body = parse_body(req);
+ std::string action = text(body, "action", true);
+ std::string id = text(body, "id");
+ if (action != "create" && action != "get" && action != "list" && action != "cancel" && action != "delete" &&
+ action != "results")
+ bad("action must be create, get, list, cancel, delete or results");
+ if (action != "create" && action != "list") {
+ if (id.empty()) bad("id is required");
+ need_id(id);
+ }
+ return guarded([&] {
+ if (action == "list") return json_out(page_json(api->batches->list(number(body, "limit", 0))));
+ if (action == "get") return json_out(api->batches->retrieve(id).raw);
+ if (action == "create") {
+ std::vector reqs;
+ const Json* rs = body.find("requests");
+ if (!rs || !rs->is_array()) bad("requests must be an array of {custom_id, params}");
+ for (const Json& r : rs->as_array()) {
+ const Json* p = r.find("params");
+ if (!p || !p->is_object()) bad("every request needs params");
+ reqs.push_back({text(r, "custom_id", true), request_from(*p)});
+ }
+ if (!confirmed(body)) {
+ Json o = Json::object();
+ o.set("requests", Json(static_cast(reqs.size())));
+ for (const core::BatchRequest& r : reqs) r.params.validate(core::kDefaultVersion);
+ return json_out(dry_run("create a batch", o));
+ }
+ return json_out(api->batches->create(reqs, text(body, "user_profile_id")).raw);
+ }
+ if (action == "cancel" || action == "delete") {
+ if (!confirmed(body)) {
+ Json o = Json::object();
+ o.set("id", Json(id));
+ return json_out(dry_run(action + " the batch", o));
+ }
+ return json_out(action == "cancel" ? api->batches->cancel(id).raw : api->batches->destroy(id));
+ }
+ core::BatchResults res = api->batches->results(id);
+ Json arr = Json::array();
+ for (const core::BatchResultItem& it : res.items) arr.push(it.raw);
+ Json o = Json::object();
+ o.set("results", arr);
+ o.set("truncated", Json(res.truncated));
+ o.set("skipped_lines", Json(static_cast(res.skipped_lines)));
+ return json_out(o);
+ });
+ });
+
+ router.post("/ai/anthropic/files", "ai-anthropic-files", [api](fw::Request req) {
+ Json body = parse_body(req);
+ std::string action = text(body, "action", true);
+ std::string id = text(body, "id");
+ if (action != "list" && action != "get" && action != "delete" && action != "upload")
+ bad("action must be list, get, delete or upload");
+ if (action == "get" || action == "delete") {
+ if (id.empty()) bad("id is required");
+ need_id(id);
+ }
+ return guarded([&] {
+ if (action == "list") return json_out(page_json(api->files->list(number(body, "limit", 0), text(body, "page"))));
+ if (action == "get") return json_out(api->files->metadata(id).raw);
+ if (action == "delete") {
+ if (!confirmed(body)) {
+ Json o = Json::object();
+ o.set("id", Json(id));
+ return json_out(dry_run("delete the file", o));
+ }
+ return json_out(api->files->destroy(id));
+ }
+ std::string name = text(body, "filename", true), data = text(body, "text", true);
+ long expires = number(body, "expires_in_seconds", 0);
+ if (!confirmed(body)) {
+ Json o = Json::object();
+ o.set("filename", Json(name));
+ o.set("bytes", Json(static_cast(data.size())));
+ return json_out(dry_run("upload a text file", o));
+ }
+ return json_out(api->files->upload(name, data, "text/plain", expires).raw);
+ });
+ });
+
+ router.post("/ai/anthropic/skills", "ai-anthropic-skills", [api](fw::Request req) {
+ Json body = parse_body(req);
+ std::string action = text(body, "action", true);
+ std::string id = text(body, "id");
+ if (action != "list" && action != "get" && action != "versions" && action != "delete")
+ bad("action must be list, get, versions or delete");
+ if (action != "list") {
+ if (id.empty()) bad("id is required");
+ need_id(id);
+ }
+ return guarded([&] {
+ if (action == "list") return json_out(page_json(api->skills->list(number(body, "limit", 0), text(body, "page"), text(body, "source"))));
+ if (action == "get") return json_out(api->skills->retrieve(id));
+ if (action == "versions") return json_out(page_json(api->skills->list_versions(id, number(body, "limit", 0))));
+ if (!confirmed(body)) {
+ Json o = Json::object();
+ o.set("id", Json(id));
+ return json_out(dry_run("delete the skill and all its versions", o));
+ }
+ return json_out(api->skills->destroy(id));
+ });
+ });
+
+ router.post("/ai/anthropic/profiles", "ai-anthropic-profiles", [api](fw::Request req) {
+ Json body = parse_body(req);
+ std::string action = text(body, "action", true);
+ std::string id = text(body, "id");
+ if (action != "list" && action != "get" && action != "delete") bad("action must be list, get or delete");
+ if (action != "list") {
+ if (id.empty()) bad("id is required");
+ need_id(id);
+ }
+ return guarded([&] {
+ if (action == "list") return json_out(page_json(api->user_profiles->list(number(body, "limit", 0), text(body, "page"))));
+ if (action == "get") return json_out(api->user_profiles->retrieve(id));
+ if (!confirmed(body)) {
+ Json o = Json::object();
+ o.set("id", Json(id));
+ return json_out(dry_run("delete the user profile", o));
+ }
+ return json_out(api->user_profiles->destroy(id));
+ });
+ });
}
} // namespace molo::example::app
diff --git a/example/assets/ai_anthropic_core.js b/example/assets/ai_anthropic_core.js
new file mode 100644
index 0000000..f9467c4
--- /dev/null
+++ b/example/assets/ai_anthropic_core.js
@@ -0,0 +1,52 @@
+// Anthropic page: thin client over /ai/anthropic/* (all limits server side).
+(function () {
+ "use strict";
+ var $ = function (id) { return document.getElementById(id); };
+ var out = $("an-out"), err = $("an-error");
+
+ var templates = {
+ build: { model: "claude-opus-5-5", max_tokens: 1024, prompt: "Hello, Claude",
+ tools: [{ type: "web_search_20260318", max_uses: 2 }], thinking: { type: "adaptive" } },
+ count: { model: "claude-opus-5-5", prompt: "Hello, Claude" },
+ messages: { model: "claude-opus-5-5", max_tokens: 256, prompt: "Hello, Claude", confirm: false },
+ stream: { model: "claude-opus-5-5", max_tokens: 256, prompt: "Hello, Claude", confirm: false },
+ models: { limit: 5 },
+ batches: { action: "list" },
+ files: { action: "list" },
+ skills: { action: "list" },
+ profiles: { action: "list" }
+ };
+
+ function fill() { $("an-body").value = JSON.stringify(templates[$("an-route").value], null, 1); }
+
+ function send() {
+ var body;
+ try { body = JSON.parse($("an-body").value || "{}"); }
+ catch (e) { err.textContent = "Body is not valid JSON"; return; }
+ err.textContent = "";
+ out.textContent = "...";
+ fetch("/ai/anthropic/" + $("an-route").value, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(body)
+ }).then(function (res) {
+ return res.text().then(function (t) {
+ var j;
+ try { j = JSON.parse(t); } catch (e) { j = { message: t }; }
+ if (!res.ok) { err.textContent = j.message || ("HTTP " + res.status); out.textContent = ""; }
+ else { out.textContent = JSON.stringify(j, null, 2); }
+ });
+ }).catch(function (e) { err.textContent = String(e); out.textContent = ""; });
+ }
+
+ fetch("/ai/anthropic/status").then(function (r) { return r.json(); }).then(function (s) {
+ $("an-config").textContent = s.configured
+ ? "Credential found (" + s.key_env + "). API version " + s.default_version + "."
+ : "No credential: calls answer 503 until " + s.key_env + " is set. Build still works.";
+ });
+
+ $("an-route").onchange = fill;
+ $("an-reset").onclick = fill;
+ $("an-send").onclick = send;
+ fill();
+})();
diff --git a/src/anthropic/core/SPEC.md b/src/anthropic/core/SPEC.md
new file mode 100644
index 0000000..c8c276b
--- /dev/null
+++ b/src/anthropic/core/SPEC.md
@@ -0,0 +1,226 @@
+# Anthropic core (Claude API platform) - Specification
+
+Owned: `src/anthropic/core/`, `tests/src/anthropic/core/`,
+`example/app/ai/AnthropicDemo.cpp`, `example/assets/ai_anthropic_core.js`,
+`tests/example/ai/anthropic/core/`. Namespace `molo::anthropic::core`. Plan:
+`plans/17-llm-vendor-platforms.md`. Base `https://api.anthropic.com`, auth
+header `x-api-key` plus `anthropic-version` (`llm::AuthStyle::kHeader`), key in
+`ANTHROPIC_API_KEY` via `llm::Config`. The Admin API, usage and cost reports and
+managed agents belong to `src/anthropic/admin` and are not here.
+
+## 1. Scope
+
+Messages (create, streaming with every event and delta kind, count tokens),
+extended thinking (enabled, adaptive, between_tools, display, signature and
+redacted thinking replay), client tools and every server tool and toolset type
+(custom, bash, text editor, memory, computer, computer and browser toolsets,
+web search, web fetch, code execution, advisor, tool search, MCP toolset),
+vision, PDF, document, search_result and container_upload blocks, citations,
+prompt caching (`cache_control`, ttl, usage fields, top-level automatic
+caching), structured outputs (`output_config.format`), effort, speed, task
+budget, context management, compaction, MCP connector (`mcp_servers`), server
+side fallbacks, Message Batches (create, retrieve, list, cancel, delete, JSONL
+results), Models (list, retrieve, capabilities), Files (upload, list, metadata,
+download, delete), Skills and skill versions, user profiles (including
+enrollment and action URLs), legacy Text Completions, the typed `anthropic-beta`
+set, `anthropic-version`, stop reasons, error types, rate limit headers and
+`AnthropicChatModel : llm::ChatModel`.
+
+## 2. Module map
+
+| File | Concern |
+|---|---|
+| `caps.h` | Static ceilings (`CoreCaps`), each marked api or local |
+| `version.*` | `ApiVersion` (2023-06-01, 2026-10-21) and what each accepts |
+| `beta.*` | `Beta` enum (all 55 SDK names), `BetaInfo` table, `BetaSet` |
+| `calls.*` | The ONE call table (32 rows), `render` with id validation |
+| `errors.*` | `ErrorKind`, `classify_error`, `RateLimits`, `AnthropicError` |
+| `session.*` | `Session` (ApiClient, response tap, headers), `CoreService` base |
+| `content.*` | Request content blocks, schema table (24 block types), `CacheControl` |
+| `tools/tools.*` | Tool schema table (30 types), `Tool`, `ToolChoice` |
+| `options.*` | Thinking, output config, context edits, compaction, MCP server, container, fallback |
+| `request.*` | `MessageParam`, `MessageRequest` (validate, bodies, derived betas) |
+| `response.*` | `Message`, `Block`, `Usage`, `Citation`, `StopReason` |
+| `stream.*` | `StreamEvent`, `StreamAccumulator` |
+| `messages.*` `batches.*` `models.*` `files.*` `skills.*` `user_profiles.*` `completions.*` | Services |
+| `page.*` | Query strings, list pages, truncation flag |
+| `chat_model.*` | `AnthropicChatModel` |
+| `anthropic.*` | Facade over one `Session` |
+| `tools/check_spec.py` | Spec checker (python3 stdlib) |
+
+## 3. Static caps
+
+| Knob | Value |
+|---|---|
+| messages / blocks per message / system blocks / tools | 4096 (local, api 100000) / 2048 / 64 / 256 |
+| tool name | `^[a-zA-Z0-9_-]{1,128}$` (api) |
+| cache breakpoints | 4 (api) |
+| betas per call / name length | 32 / 128 |
+| thinking budget | at least 1024, below max_tokens (api) |
+| list limit | 1..1000 (api), walks at most 20 pages, `truncated` set when capped |
+| batch requests / custom_id | 100000 (api) / `^[a-zA-Z0-9_-]{1,64}$` (api); body 32 MiB (local, api 256 MB) |
+| batch result lines | 100000, bad lines counted in `skipped_lines`, never dropped silently |
+| files: size / ids filter / expiry | 500 MB / 100 / 3600..7776000 s (api) |
+| skills: files / bytes / per request | 500 (local) / 30 MB / 20 (api) |
+| stream events / partial tool input | 500000 / 8 MiB (local) |
+| request / response / SSE event / stream bytes | 32 MiB / 64 MiB / 4 MiB / 64 MiB (foundation) |
+
+## 4. Contracts
+
+- Paths come only from the `calls.cpp` table; every id passes
+ `Service::valid_id`. Local invalid input is `ApiError::invalid` (type
+ `INVALID_ARGUMENT`, `ErrorKind::kInvalidArgument`) before any traffic and before
+ the credential check; no credential is `NotConfiguredError` (503).
+- Every failure leaves as `AnthropicError` (derives `llm::ApiError`) with
+ `kind()`, request id and the rate limit headers of the failed response
+ (`retry-after`, `retry-after-ms`, `x-should-retry`, `anthropic-ratelimit-*`,
+ `anthropic-priority-*`). `retryable()` is the SDK rule. Mid-stream `error`
+ events become the same error with the documented status of the type.
+- Betas: `MessageRequest::effective_betas()` is the explicit set plus the betas
+ the request's features need (tool table, thinking display, block binding, task
+ budget, context edits, compaction, MCP, fallbacks, threads, system message
+ fields, block types). The union is sent and reported (`MessageResult::betas`).
+ `BetaSet::add_name` keeps well formed unknown names and lists them in
+ `unknown()`; malformed names throw. Nothing is dropped. `speed:"fast"` is not
+ auto-beta (only some models need `fast-mode-2026-02-01`); add it explicitly.
+ `mcp-client-2026-09-15` replaces `mcp-client-2025-11-20` (it includes it).
+- Version rules (`ApiVersion::k20261021`): `temperature`, `top_p`, `top_k`,
+ document blocks in assistant messages and citations on user text blocks are
+ rejected locally exactly as the API does. Default version is 2023-06-01
+ (stable on every platform); 2026-10-21 is opt-in via `SessionOptions::version`.
+- Thinking blocks and every response block are replayed verbatim
+ (`Message::as_param`, `ContentBlock::from_json(echo=true)`); signatures are
+ never edited. A streamed signature arrives only in `signature_delta`
+ events; `AnthropicChatModel::last_stream_message()` holds it.
+- Destructive calls are explicit methods with no default: `Batches::cancel`,
+ `Batches::destroy`, `Files::destroy`, `Skills::destroy`, `destroy_version`,
+ `UserProfiles::destroy`. Example routes dry-run them unless `"confirm":true`;
+ paid routes (messages, stream, batch create, file upload) do the same.
+- Legacy shapes: `Files::with_betas({kFilesApi20250414})`,
+ `Skills::with_betas({kSkills20251002})` keep sending the old headers (the
+ Skills beta returns `display_title`, epoch versions, etc.; GA returns
+ `display_name`, `latest_version_id`).
+- Long non-streaming calls are bounded by the foundation timeouts (60 s total);
+ use `Messages::stream` for long outputs.
+
+## 5. AnthropicChatModel mapping
+
+Leading `kSystem` messages and `ChatRequest.system` become `system`; `kTool`
+messages become user messages of `tool_result` blocks; `reasoning` +
+`reasoning_signature` is a `thinking` block, a signature starting with
+`redacted_thinking:` is a `redacted_thinking` block (convention of this module,
+the shared type has no field for it); `tool_call` is `tool_use`;
+`tool_choice` required is `any`; `json_mode` without `response_schema` is
+rejected (no schemaless JSON mode); `response_schema` is `output_config.format`;
+`reasoning_effort` is `output_config.effort`; `extra.betas` feeds the header,
+`extra.thinking` is typed, other `extra` keys are merged and must not collide.
+Finish reasons: end_turn/stop_sequence stop, max_tokens and
+model_context_window_exceeded length, tool_use tool_calls, refusal
+content_filter, pause_turn and compaction pass through. Server tool blocks
+(web search, code execution, MCP) are in `ChatResponse.raw` only.
+
+## 6. Example routes (`/ai/anthropic`)
+
+GET `/ai/anthropic` (page), `/status`, `/calls`, `/betas`, `/tools`. POST
+`/build` (offline validation, derived betas), `/count`, `/messages`, `/stream`,
+`/models`, `/batches` (create get list cancel delete results), `/files` (list get
+delete upload), `/skills` (list get versions delete), `/profiles` (list get
+delete). Input is validated first (422), then a credential is required (503
+`anthropic_not_configured`); oversize body 413.
+
+## Sources
+
+- Official Python SDK `anthropics/anthropic-sdk-python` at commit
+ `202db72c87d7c6eaa72129c67ce67fd343a3a20c` (version 2.3.0): `resources/**`
+ (verbs, paths, keyword arguments), `types/beta/*_param.py` (blocks, tools,
+ options), `types/anthropic_beta_param.py` (beta names), `_base_client.py`
+ (retry rule, `retry-after-ms`, `x-should-retry`). The TypeScript SDK
+ (`anthropic-sdk-typescript` 1.3.0) was read for cross-checks of the endpoint
+ count only (`.stats.yml`: 349 configured endpoints, no `openapi_spec_url`).
+- API reference pages, fetched 2026-10-24 from `platform.claude.com/docs/en/api/`
+ as `.md`: messages (create, count_tokens, batches/*), beta variants, models,
+ files, skills, skills/versions, user_profiles, completions/create, errors,
+ rate-limits, versioning, beta-headers, migration-2026-10-21, service-tiers.
+- Guides: build-with-claude (streaming, thinking, prompt-caching, structured
+ outputs, files, skills-guide incl. "Migrate from skills-2025-10-02",
+ mid-conversation system messages, batch processing, token counting),
+ agents-and-tools (tool-reference, mcp-connector, tool pages).
+- No OpenAPI document is published: `api.anthropic.com/openapi.json` is 404 and
+ the docs path answers an HTML page.
+
+## Verified against spec
+
+`python3 -I src/anthropic/core/tools/check_spec.py`, run 2026-10-24 against the
+pinned SDK commit and the live reference pages:
+`spec ok: 32 calls, 55 betas, 24 block types, 30 tool types, sdk 202db72c`.
+It checks: every call row has an SDK method (GA and/or beta file) with the same
+verb and path and every declared body/query field is a keyword argument of it;
+the reference page of every row shows the same verb and path; every SDK
+operation outside the other-package directories is a row (coverage); the beta
+table equals the SDK list; block and tool schemas (type, required, optional
+fields) equal the SDK param classes; versions and error types appear on the
+versioning and errors pages; the legacy sampling fields appear on the migration
+page. Exclusions (OTHER_PACKAGES in the script): organization, agents, sessions,
+vaults, memory stores, environments, tunnels, deployments, dreams, webhooks;
+helper methods `parse` and `stream` reuse `messages.create`.
+
+## Verified live
+
+2026-10-24, no key, `MOLO_LIVE_NET=1` (test `anthropic_live.unauthenticated_probe`
+through the real TLS transport) and curl:
+
+| Probe | Result |
+|---|---|
+| `GET /v1/models` (no key) | 401 `authentication_error` "x-api-key header is required", `request-id` header and body `request_id` |
+| `GET /v1/models` with `Authorization: Bearer invalid` | 401 "Invalid bearer token" |
+| `POST /v1/messages`, `/messages/count_tokens`, `/messages/batches`, `/complete` | 401 same envelope |
+| `GET /v1/files`, `/v1/skills`, `/v1/skills/x/versions`, `/v1/files/x`, `/v1/skills/x` | 401 |
+| `GET/POST/DELETE /v1/messages/batches/msgbatch_x[/results\|/cancel]` | 404 `not_found_error` "Message Batch `msgbatch_x` not found." (path check runs before auth) |
+| `GET /v1/files/file_x/content`, `/v1/skills/x/versions/1/content` | 404 "Not found" (unauthenticated; cannot tell route from missing resource) |
+| `GET /v1/nonexistent_path_zz` | 404 `not_found_error`, `request_id` null |
+| invalid key, versions 2023-06-01, 2026-10-21, 1999-01-01 | all 401 "invalid x-api-key" (version is not checked before auth) |
+| unknown `anthropic-beta` name, no key | 401 (beta is not checked before auth) |
+
+Opt-in with a key (not run, no key exists): `anthropic_live.read_only_*` (models
+list and retrieve, count_tokens, batches list, files list); one 8-token
+completion needs `MOLO_LIVE_PAID=1`. Nothing creates, updates or deletes vendor
+resources.
+
+## Unverified
+
+- Everything needing a key: response bodies of real calls, the exact
+ rate limit header values, stream behaviour of real servers, batch and file
+ lifecycles, skills upload layout acceptance, user profile semantics.
+- `thread` request field (`{"type":"create"}` / `{"type":"continue",
+ "previous_message_id"}`) and beta `message-threads-2026-08-12`: seen only in the
+ SDK source, not in the published reference; the stream and batch behaviour is
+ unknown.
+- `temperature`, `top_p`, `top_k` for anthropic-version 2023-06-01: removal is
+ documented (versioning, migration, completions page ranges) but no current
+ Messages reference lists the fields; ranges are taken from the completions
+ page.
+- User profile fields beyond the SDK type, valid `action` values of
+ `action_urls`, `enforcement_status` values.
+- Streamed Text Completions events (not implemented).
+- The web search stream transcript in the docs is abridged by the vendor; the
+ accumulator was exercised with the basic, tool use and thinking transcripts.
+- The meaning of betas `experimental-claude-tag-2026-10-21` and
+ `message-threads-2026-08-12` (typed, labelled unknown / SDK only).
+- Foundation timeouts: whether the 60 s total applies to non-streaming calls on
+ the real transport was not measured.
+
+## Gaps
+
+- `llm::ApiClient::stream` exposes no response headers: rate limit headers are
+ available for non-streaming calls and for errors, not for successful streams
+ (`src/llm/api_client.cpp`).
+- `llm::ContentPart` has no redacted-thinking field (module convention above) and
+ `llm::ChatChunk` has no signature field (use `last_stream_message()`).
+- Batches over 32 MiB (api allows 256 MB) and results over 64 MiB cannot pass the
+ foundation caps (`src/llm/caps.h`).
+- Server tool blocks are not representable in the neutral chat types.
+- No automatic retry: `AnthropicError::retryable()` and `RateLimits` expose the
+ data, callers decide.
+- Multipart `files[]` field name for skills comes from the docs cURL example
+ (`-F 'files[]=@...'`) and the SDK `extract_files` path; not seen on the wire.
+- Message `parse`/tool-runner/compaction helpers of the SDKs are not mirrored.
diff --git a/src/anthropic/core/anthropic.cpp b/src/anthropic/core/anthropic.cpp
new file mode 100644
index 0000000..fbb4a9f
--- /dev/null
+++ b/src/anthropic/core/anthropic.cpp
@@ -0,0 +1,20 @@
+#include "anthropic/core/anthropic.h"
+
+namespace molo::anthropic::core {
+
+Anthropic::Anthropic(std::shared_ptr session)
+ : messages(std::make_shared(session)),
+ batches(std::make_shared(session)),
+ models(std::make_shared(session)),
+ files(std::make_shared(session)),
+ skills(std::make_shared(session)),
+ user_profiles(std::make_shared(session)),
+ completions(std::make_shared(session)),
+ session_(std::move(session)) {}
+
+std::shared_ptr Anthropic::chat_model(const std::string& default_model,
+ int default_max_tokens) const {
+ return std::make_shared(messages, default_model, default_max_tokens);
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/anthropic.h b/src/anthropic/core/anthropic.h
new file mode 100644
index 0000000..c9059ec
--- /dev/null
+++ b/src/anthropic/core/anthropic.h
@@ -0,0 +1,38 @@
+#pragma once
+
+// Facade: one Session, every service of the module.
+
+#include
+
+#include "anthropic/core/batches.h"
+#include "anthropic/core/chat_model.h"
+#include "anthropic/core/completions.h"
+#include "anthropic/core/files.h"
+#include "anthropic/core/messages.h"
+#include "anthropic/core/models.h"
+#include "anthropic/core/skills.h"
+#include "anthropic/core/user_profiles.h"
+
+namespace molo::anthropic::core {
+
+class Anthropic {
+ public:
+ explicit Anthropic(std::shared_ptr session);
+ static Anthropic from_env(SessionOptions options = {}) { return Anthropic(Session::from_env(std::move(options))); }
+
+ Session& session() const { return *session_; }
+ bool configured() const { return session_->configured(); }
+ std::shared_ptr messages;
+ std::shared_ptr batches;
+ std::shared_ptr models;
+ std::shared_ptr files;
+ std::shared_ptr skills;
+ std::shared_ptr user_profiles;
+ std::shared_ptr completions;
+ std::shared_ptr chat_model(const std::string& default_model, int default_max_tokens = 4096) const;
+
+ private:
+ std::shared_ptr session_;
+};
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/batches.cpp b/src/anthropic/core/batches.cpp
new file mode 100644
index 0000000..c98e94a
--- /dev/null
+++ b/src/anthropic/core/batches.cpp
@@ -0,0 +1,138 @@
+#include "anthropic/core/batches.h"
+
+#include "anthropic/core/util.h"
+
+namespace molo::anthropic::core {
+
+Batch Batch::parse(const Json& j) {
+ Batch b;
+ b.raw = j;
+ b.id = str_at(j, "id");
+ b.processing_status = str_at(j, "processing_status");
+ if (const Json* c = member(j, "request_counts")) {
+ b.counts.processing = num_at(*c, "processing");
+ b.counts.succeeded = num_at(*c, "succeeded");
+ b.counts.errored = num_at(*c, "errored");
+ b.counts.canceled = num_at(*c, "canceled");
+ b.counts.expired = num_at(*c, "expired");
+ }
+ b.created_at = str_at(j, "created_at");
+ b.expires_at = str_at(j, "expires_at");
+ b.ended_at = str_at(j, "ended_at");
+ b.archived_at = str_at(j, "archived_at");
+ b.cancel_initiated_at = str_at(j, "cancel_initiated_at");
+ b.results_url = str_at(j, "results_url");
+ return b;
+}
+
+Batch Batches::create(const std::vector& requests, const std::string& user_profile_id) {
+ return session().guarded([&] {
+ if (requests.empty() || requests.size() > CoreCaps::kMaxBatchRequests) bad("a batch has 1..100000 requests");
+ Json list = arr();
+ BetaSet betas;
+ std::vector seen;
+ for (const BatchRequest& r : requests) {
+ if (!slug_ok(r.custom_id, CoreCaps::kMaxCustomIdChars)) bad("custom_id must match ^[a-zA-Z0-9_-]{1,64}$");
+ for (const std::string& s : seen)
+ if (s == r.custom_id) bad("duplicate custom_id '" + s + "'");
+ seen.push_back(r.custom_id);
+ r.params.validate(session().version());
+ betas.merge(r.params.effective_betas());
+ Json item = obj();
+ item.set("custom_id", Json(r.custom_id));
+ item.set("params", r.params.to_batch_params(session().version()));
+ list.push(item);
+ }
+ Json body = obj();
+ body.set("requests", list);
+ if (body.dump().size() > CoreCaps::kMaxBatchBytes) bad("batch body over the byte cap");
+ return Batch::parse(client().request(method_of(Call::kBatchesCreate), render(Call::kBatchesCreate), &body,
+ session().headers(betas, "", user_profile_id)));
+ });
+}
+
+Batch Batches::retrieve(const std::string& id) {
+ return Batch::parse(call_json(Call::kBatchesRetrieve, id));
+}
+
+Page Batches::list(int limit, const std::string& after_id, const std::string& before_id) {
+ check_limit(limit);
+ if (!after_id.empty() && !before_id.empty()) bad("after_id and before_id are exclusive");
+ Query q;
+ if (limit) q.add_int("limit", limit);
+ if (!after_id.empty()) {
+ check_id("after_id", after_id);
+ q.add("after_id", after_id);
+ }
+ if (!before_id.empty()) {
+ check_id("before_id", before_id);
+ q.add("before_id", before_id);
+ }
+ return Page::parse(call_json(Call::kBatchesList, "", "", q.str()));
+}
+
+Page Batches::list_all(int max_pages, int limit) {
+ if (max_pages < 1 || max_pages > CoreCaps::kMaxListPages) bad("max_pages must be 1..20");
+ Page all;
+ std::string after;
+ for (int i = 0; i < max_pages; ++i) {
+ Page p = list(limit, after);
+ all.data.insert(all.data.end(), p.data.begin(), p.data.end());
+ all.has_more = p.has_more;
+ all.last_id = p.last_id;
+ if (all.first_id.empty()) all.first_id = p.first_id;
+ if (!p.has_more || p.last_id.empty()) return all;
+ after = p.last_id;
+ }
+ all.truncated = all.has_more;
+ return all;
+}
+
+Batch Batches::cancel(const std::string& id) {
+ Json empty = obj();
+ return Batch::parse(call_json(Call::kBatchesCancel, id, "", "", &empty));
+}
+
+Json Batches::destroy(const std::string& id) { return call_json(Call::kBatchesDelete, id); }
+
+BatchResults Batches::results(const std::string& id) {
+ return session().guarded([&] {
+ llm::RawResponse raw = client().request_raw(method_of(Call::kBatchesResults),
+ render(Call::kBatchesResults, id), nullptr, "",
+ session().headers(betas_));
+ BatchResults out;
+ std::size_t pos = 0;
+ while (pos < raw.body.size()) {
+ std::size_t eol = raw.body.find('\n', pos);
+ std::string line = raw.body.substr(pos, eol == std::string::npos ? eol : eol - pos);
+ pos = eol == std::string::npos ? raw.body.size() : eol + 1;
+ if (line.find_first_not_of(" \t\r") == std::string::npos) continue;
+ if (out.items.size() >= CoreCaps::kMaxResultLines) {
+ out.truncated = true;
+ break;
+ }
+ Json j;
+ try {
+ j = Json::parse(line);
+ } catch (const std::exception&) {
+ ++out.skipped_lines;
+ continue;
+ }
+ BatchResultItem it;
+ it.raw = j;
+ it.custom_id = str_at(j, "custom_id");
+ if (const Json* r = member(j, "result")) {
+ it.type = str_at(*r, "type");
+ if (it.type == "succeeded") {
+ if (const Json* m = member(*r, "message")) it.message = Message::parse(*m);
+ } else if (it.type == "errored") {
+ if (const Json* e = member(*r, "error")) it.error = *e;
+ }
+ }
+ out.items.push_back(std::move(it));
+ }
+ return out;
+ });
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/batches.h b/src/anthropic/core/batches.h
new file mode 100644
index 0000000..253a167
--- /dev/null
+++ b/src/anthropic/core/batches.h
@@ -0,0 +1,65 @@
+#pragma once
+
+// Message Batches: create, retrieve, list, cancel, delete, results (JSONL).
+
+#include
+#include
+#include
+
+#include "anthropic/core/page.h"
+#include "anthropic/core/response.h"
+#include "anthropic/core/session.h"
+
+namespace molo::anthropic::core {
+
+struct BatchRequest {
+ std::string custom_id; // ^[a-zA-Z0-9_-]{1,64}$, unique in the batch
+ MessageRequest params;
+};
+
+struct RequestCounts {
+ long processing = 0, succeeded = 0, errored = 0, canceled = 0, expired = 0;
+ long total() const { return processing + succeeded + errored + canceled + expired; }
+};
+
+struct Batch {
+ std::string id;
+ std::string processing_status; // in_progress | canceling | ended
+ RequestCounts counts;
+ std::string created_at, expires_at, ended_at, archived_at, cancel_initiated_at, results_url;
+ Json raw;
+ bool ended() const { return processing_status == "ended"; }
+ static Batch parse(const Json& j);
+};
+
+struct BatchResultItem {
+ std::string custom_id;
+ std::string type; // succeeded | errored | canceled | expired
+ std::optional message; // succeeded
+ Json error; // errored: {"type":"error","error":{...}}
+ Json raw;
+};
+
+struct BatchResults {
+ std::vector items;
+ bool truncated = false; // more lines than CoreCaps::kMaxResultLines
+ std::size_t skipped_lines = 0; // lines that were not valid JSON (counted, never dropped silently)
+};
+
+class Batches : public CoreService {
+ public:
+ explicit Batches(std::shared_ptr session) : CoreService(std::move(session)) {}
+
+ // Validates every entry first; the anthropic-beta header is the union of the
+ // betas the entries need. Costs money once processed.
+ Batch create(const std::vector& requests, const std::string& user_profile_id = "");
+ Batch retrieve(const std::string& id);
+ Page list(int limit = 0, const std::string& after_id = "", const std::string& before_id = "");
+ // Walks pages by after_id up to max_pages (<= 20); sets truncated on the cap.
+ Page list_all(int max_pages = 5, int limit = 100);
+ Batch cancel(const std::string& id); // explicit: no default
+ Json destroy(const std::string& id); // DELETE, explicit: only for ended batches
+ BatchResults results(const std::string& id);
+};
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/beta.cpp b/src/anthropic/core/beta.cpp
new file mode 100644
index 0000000..123c313
--- /dev/null
+++ b/src/anthropic/core/beta.cpp
@@ -0,0 +1,140 @@
+#include "anthropic/core/beta.h"
+
+#include "anthropic/core/caps.h"
+#include "anthropic/core/util.h"
+
+namespace molo::anthropic::core {
+
+// BETAS-BEGIN (compared with the SDK AnthropicBetaParam list by tools/check_spec.py)
+static const BetaInfo kBetas[] = {
+ {Beta::kMessageBatches20240924, "message-batches-2024-09-24", BetaStatus::kLegacy, "Message Batches (GA, header no longer needed)"},
+ {Beta::kPromptCaching20240731, "prompt-caching-2024-07-31", BetaStatus::kLegacy, "Prompt caching (GA, header no longer needed)"},
+ {Beta::kComputerUse20241022, "computer-use-2024-10-22", BetaStatus::kCurrent, "computer_20241022, bash_20241022, text_editor_20241022 tools"},
+ {Beta::kComputerUse20250124, "computer-use-2025-01-24", BetaStatus::kCurrent, "computer_20250124 tool"},
+ {Beta::kPdfs20240925, "pdfs-2024-09-25", BetaStatus::kLegacy, "PDF support (GA, header no longer needed)"},
+ {Beta::kTokenCounting20241101, "token-counting-2024-11-01", BetaStatus::kLegacy, "Token counting (GA, header no longer needed)"},
+ {Beta::kTokenEfficientTools20250219, "token-efficient-tools-2025-02-19", BetaStatus::kLegacy, "Token-efficient tool use (legacy)"},
+ {Beta::kOutput128k20250219, "output-128k-2025-02-19", BetaStatus::kLegacy, "128k output on Claude 3.7 Sonnet (legacy)"},
+ {Beta::kFilesApi20250414, "files-api-2025-04-14", BetaStatus::kLegacy, "Files API (GA, header still accepted)"},
+ {Beta::kMcpClient20250404, "mcp-client-2025-04-04", BetaStatus::kLegacy, "MCP connector, deprecated first version"},
+ {Beta::kMcpClient20251120, "mcp-client-2025-11-20", BetaStatus::kCurrent, "MCP connector: mcp_servers plus mcp_toolset"},
+ {Beta::kDevFullThinking20250514, "dev-full-thinking-2025-05-14", BetaStatus::kLegacy, "Full thinking output on Claude 4 (legacy dev flag)"},
+ {Beta::kInterleavedThinking20250514, "interleaved-thinking-2025-05-14", BetaStatus::kCurrent, "Interleaved thinking between tool calls"},
+ {Beta::kCodeExecution20250522, "code-execution-2025-05-22", BetaStatus::kCurrent, "code_execution_20250522 tool (legacy Python-only version)"},
+ {Beta::kExtendedCacheTtl20250411, "extended-cache-ttl-2025-04-11", BetaStatus::kLegacy, "1 hour cache ttl (GA, header no longer needed)"},
+ {Beta::kContext1m20250807, "context-1m-2025-08-07", BetaStatus::kCurrent, "1M token context window"},
+ {Beta::kContextManagement20250627, "context-management-2025-06-27", BetaStatus::kCurrent, "context_management edits (clear_tool_uses, clear_thinking)"},
+ {Beta::kModelContextWindowExceeded20250826, "model-context-window-exceeded-2025-08-26", BetaStatus::kCurrent, "stop_reason model_context_window_exceeded"},
+ {Beta::kSkills20251002, "skills-2025-10-02", BetaStatus::kLegacy, "Skills API beta shapes (display_title, epoch versions); GA Skills need no header"},
+ {Beta::kFastMode20260201, "fast-mode-2026-02-01", BetaStatus::kCurrent, "speed: fast on models that require the header"},
+ {Beta::kOutput300k20260324, "output-300k-2026-03-24", BetaStatus::kCurrent, "300k output tokens on batches"},
+ {Beta::kUserProfiles20260324, "user-profiles-2026-03-24", BetaStatus::kCurrent, "User profiles (first revision)"},
+ {Beta::kUserProfiles20260818, "user-profiles-2026-08-18", BetaStatus::kCurrent, "User profiles (second revision)"},
+ {Beta::kUserProfiles20260904, "user-profiles-2026-09-04", BetaStatus::kCurrent, "User profiles (third revision)"},
+ {Beta::kAdvisorTool20260301, "advisor-tool-2026-03-01", BetaStatus::kCurrent, "advisor_20260301 server tool"},
+ {Beta::kManagedAgents20260401, "managed-agents-2026-04-01", BetaStatus::kOtherPackage, "Managed agents, sessions, environments (anthropic admin package)"},
+ {Beta::kCacheDiagnosis20260407, "cache-diagnosis-2026-04-07", BetaStatus::kLegacy, "diagnostics.cache_miss_reason (GA, header listed in the SDK type)"},
+ {Beta::kDreaming20260421, "dreaming-2026-04-21", BetaStatus::kOtherPackage, "Dreams (anthropic admin package)"},
+ {Beta::kThinkingTokenCount20260513, "thinking-token-count-2026-05-13", BetaStatus::kCurrent, "thinking token counts in usage (output_tokens_details)"},
+ {Beta::kServerSideFallback20260601, "server-side-fallback-2026-06-01", BetaStatus::kCurrent, "fallbacks request field, first revision"},
+ {Beta::kServerSideFallback20260701, "server-side-fallback-2026-07-01", BetaStatus::kCurrent, "fallbacks request field, second revision"},
+ {Beta::kFallbackCredit20260601, "fallback-credit-2026-06-01", BetaStatus::kCurrent, "fallback_credit_token, first revision"},
+ {Beta::kFallbackCredit20260701, "fallback-credit-2026-07-01", BetaStatus::kCurrent, "fallback_credit_token, second revision"},
+ {Beta::kAgentMemory20260722, "agent-memory-2026-07-22", BetaStatus::kOtherPackage, "Memory stores (anthropic admin package)"},
+ {Beta::kMidConversationToolChanges20260701, "mid-conversation-tool-changes-2026-07-01", BetaStatus::kCurrent, "Tool changes in mid-conversation system messages, first revision"},
+ {Beta::kCompact20260112, "compact-2026-01-12", BetaStatus::kCurrent, "compact_20260112 context edit"},
+ {Beta::kComputerUse20251124, "computer-use-2025-11-24", BetaStatus::kCurrent, "computer_20251124 tool"},
+ {Beta::kMcpTunnels20260622, "mcp-tunnels-2026-06-22", BetaStatus::kOtherPackage, "MCP tunnels (anthropic admin package)"},
+ {Beta::kStructuredOutputs20251113, "structured-outputs-2025-11-13", BetaStatus::kLegacy, "Structured outputs (GA via output_config.format; header still accepted)"},
+ {Beta::kTaskBudgets20260313, "task-budgets-2026-03-13", BetaStatus::kCurrent, "output_config.task_budget"},
+ {Beta::kThinkingDisplayUpdates20260818, "thinking-display-updates-2026-08-18", BetaStatus::kCurrent, "thinking display: updates"},
+ {Beta::kCeUserManagement20260713, "ce-user-management-2026-07-13", BetaStatus::kOtherPackage, "Claude Enterprise user management (anthropic admin package)"},
+ {Beta::kMidConversationOutputConfig20260701, "mid-conversation-output-config-2026-07-01", BetaStatus::kCurrent, "output_config.effort inside a mid-conversation system message"},
+ {Beta::kThinkingBindingControls20260801, "thinking-binding-controls-2026-08-01", BetaStatus::kCurrent, "thinking block_binding and input_transformations"},
+ {Beta::kMidConversationSystemClearAt20260821, "mid-conversation-system-clear-at-2026-08-21", BetaStatus::kCurrent, "clear_at on system messages (turn-scoped)"},
+ {Beta::kCompact20260904, "compact-2026-09-04", BetaStatus::kCurrent, "top-level compaction config"},
+ {Beta::kInlineTools20260915, "inline-tools-2026-09-15", BetaStatus::kCurrent, "tool_addition and tool_removal blocks in system messages"},
+ {Beta::kMcpClient20260915, "mcp-client-2026-09-15", BetaStatus::kCurrent, "MCP connector with mcp_tool_listing blocks and pinned toolset tools"},
+ {Beta::kCePlugins20260901, "ce-plugins-2026-09-01", BetaStatus::kOtherPackage, "Claude Enterprise plugins (anthropic admin package)"},
+ {Beta::kSpendLimitReads20260926, "spend-limit-reads-2026-09-26", BetaStatus::kOtherPackage, "Spend limit reads (anthropic admin package)"},
+ {Beta::kTelemetryDestinations20260811, "telemetry-destinations-2026-08-11", BetaStatus::kOtherPackage, "Telemetry destinations (anthropic admin package)"},
+ {Beta::kWebhooks20261007, "webhooks-2026-10-07", BetaStatus::kOtherPackage, "Webhooks (anthropic admin package)"},
+ {Beta::kMessageThreads20260812, "message-threads-2026-08-12", BetaStatus::kUnknown, "Request field thread (SDK source only, not in the published reference)"},
+ {Beta::kAnalyticsUsageCost20260824, "analytics-usage-cost-2026-08-24", BetaStatus::kOtherPackage, "Analytics usage and cost (anthropic admin package)"},
+ {Beta::kExperimentalClaudeTag20261021, "experimental-claude-tag-2026-10-21", BetaStatus::kUnknown, "Experimental, only listed in the SDK type; meaning unknown"},
+};
+// BETAS-END
+
+const BetaInfo& beta_info(Beta beta) { return kBetas[static_cast(beta)]; }
+const char* beta_name(Beta beta) { return beta_info(beta).wire; }
+std::size_t beta_count() { return sizeof(kBetas) / sizeof(kBetas[0]); }
+const BetaInfo& beta_at(std::size_t index) { return kBetas[index]; }
+
+std::optional find_beta(const std::string& wire) {
+ for (const BetaInfo& b : kBetas)
+ if (wire == b.wire) return b.beta;
+ return std::nullopt;
+}
+
+bool valid_beta_name(const std::string& name) {
+ if (name.empty() || name.size() > CoreCaps::kMaxBetaNameChars) return false;
+ if (name.front() == '-' || name.back() == '-') return false;
+ bool prev_dash = false;
+ for (char c : name) {
+ bool alnum = (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9');
+ if (c == '-') {
+ if (prev_dash) return false;
+ prev_dash = true;
+ } else if (alnum) {
+ prev_dash = false;
+ } else {
+ return false;
+ }
+ }
+ return true;
+}
+
+BetaSet::BetaSet(std::initializer_list betas) {
+ for (Beta b : betas) add(b);
+}
+
+BetaSet& BetaSet::add(Beta beta) { return add_name(beta_name(beta)); }
+
+BetaSet& BetaSet::add_name(const std::string& name) {
+ if (!valid_beta_name(name)) bad("malformed anthropic-beta name '" + name + "'");
+ if (contains_name(name)) return *this;
+ if (names_.size() >= CoreCaps::kMaxBetas) bad("too many anthropic-beta names");
+ names_.push_back(name);
+ return *this;
+}
+
+BetaSet& BetaSet::merge(const BetaSet& other) {
+ for (const std::string& n : other.names_) add_name(n);
+ return *this;
+}
+
+bool BetaSet::contains(Beta beta) const { return contains_name(beta_name(beta)); }
+
+bool BetaSet::contains_name(const std::string& name) const {
+ for (const std::string& n : names_)
+ if (n == name) return true;
+ return false;
+}
+
+std::vector BetaSet::unknown() const {
+ std::vector out;
+ for (const std::string& n : names_)
+ if (!find_beta(n)) out.push_back(n);
+ return out;
+}
+
+std::string BetaSet::header_value() const {
+ std::string out;
+ for (const std::string& n : names_) {
+ if (!out.empty()) out += ",";
+ out += n;
+ }
+ return out;
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/beta.h b/src/anthropic/core/beta.h
new file mode 100644
index 0000000..f9ce138
--- /dev/null
+++ b/src/anthropic/core/beta.h
@@ -0,0 +1,119 @@
+#pragma once
+// The anthropic-beta header mechanism. Every name in the SDK's AnthropicBeta
+// type is a typed Beta value (never a bare string by accident). Names outside
+// the table are still sent when well formed, but only through add_name() and
+// they are reported by BetaSet::unknown(): a beta is never silently dropped.
+
+#include
+#include
+#include
+#include
+#include
+
+namespace molo::anthropic::core {
+
+enum class BetaStatus {
+ kCurrent, // header of a feature that is still in beta
+ kLegacy, // feature went GA or was superseded; header still accepted
+ kOtherPackage, // belongs to src/anthropic/admin (typed here so it is never lost)
+ kUnknown, // listed in the SDK type, meaning not documented
+};
+
+enum class Beta {
+ kMessageBatches20240924,
+ kPromptCaching20240731,
+ kComputerUse20241022,
+ kComputerUse20250124,
+ kPdfs20240925,
+ kTokenCounting20241101,
+ kTokenEfficientTools20250219,
+ kOutput128k20250219,
+ kFilesApi20250414,
+ kMcpClient20250404,
+ kMcpClient20251120,
+ kDevFullThinking20250514,
+ kInterleavedThinking20250514,
+ kCodeExecution20250522,
+ kExtendedCacheTtl20250411,
+ kContext1m20250807,
+ kContextManagement20250627,
+ kModelContextWindowExceeded20250826,
+ kSkills20251002,
+ kFastMode20260201,
+ kOutput300k20260324,
+ kUserProfiles20260324,
+ kUserProfiles20260818,
+ kUserProfiles20260904,
+ kAdvisorTool20260301,
+ kManagedAgents20260401,
+ kCacheDiagnosis20260407,
+ kDreaming20260421,
+ kThinkingTokenCount20260513,
+ kServerSideFallback20260601,
+ kServerSideFallback20260701,
+ kFallbackCredit20260601,
+ kFallbackCredit20260701,
+ kAgentMemory20260722,
+ kMidConversationToolChanges20260701,
+ kCompact20260112,
+ kComputerUse20251124,
+ kMcpTunnels20260622,
+ kStructuredOutputs20251113,
+ kTaskBudgets20260313,
+ kThinkingDisplayUpdates20260818,
+ kCeUserManagement20260713,
+ kMidConversationOutputConfig20260701,
+ kThinkingBindingControls20260801,
+ kMidConversationSystemClearAt20260821,
+ kCompact20260904,
+ kInlineTools20260915,
+ kMcpClient20260915,
+ kCePlugins20260901,
+ kSpendLimitReads20260926,
+ kTelemetryDestinations20260811,
+ kWebhooks20261007,
+ kMessageThreads20260812,
+ kAnalyticsUsageCost20260824,
+ kExperimentalClaudeTag20261021,
+};
+
+struct BetaInfo {
+ Beta beta;
+ const char* wire;
+ BetaStatus status;
+ const char* meaning;
+};
+
+const BetaInfo& beta_info(Beta beta);
+const char* beta_name(Beta beta);
+std::optional find_beta(const std::string& wire);
+std::size_t beta_count();
+const BetaInfo& beta_at(std::size_t index);
+// ^[a-z0-9]+(-[a-z0-9]+)*$ and at most CoreCaps::kMaxBetaNameChars.
+bool valid_beta_name(const std::string& name);
+
+// Ordered, de-duplicated set rendered as one comma separated header value.
+class BetaSet {
+ public:
+ BetaSet() = default;
+ BetaSet(std::initializer_list betas);
+
+ BetaSet& add(Beta beta);
+ // A known name becomes its typed value; an unknown well formed name is kept
+ // and listed by unknown(); a malformed name throws ApiError::invalid.
+ BetaSet& add_name(const std::string& name);
+ BetaSet& merge(const BetaSet& other);
+ bool contains(Beta beta) const;
+ bool contains_name(const std::string& name) const;
+ bool empty() const { return names_.empty(); }
+ std::size_t size() const { return names_.size(); }
+ const std::vector& names() const { return names_; }
+ std::vector unknown() const;
+ // "a,b,c" or empty.
+ std::string header_value() const;
+
+ private:
+ std::vector names_;
+};
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/calls.cpp b/src/anthropic/core/calls.cpp
new file mode 100644
index 0000000..9508f41
--- /dev/null
+++ b/src/anthropic/core/calls.cpp
@@ -0,0 +1,92 @@
+#include "anthropic/core/calls.h"
+
+#include "anthropic/core/util.h"
+#include "llm/api_client.h"
+
+namespace molo::anthropic::core {
+
+const char* const kLegacySamplingFields = "temperature,top_p,top_k";
+
+// CALLS-BEGIN (parsed by tools/check_spec.py; one row per line)
+static const CallSpec kCalls[] = {
+ {Call::kMessagesCreate, "messages.create", "POST", "/v1/messages", "messages/messages.py:Messages.create|beta/messages/messages.py:Messages.create", "messages/create", "max_tokens,messages,model,cache_control,compaction,container,context_management,diagnostics,fallback_credit_token,fallbacks,inference_geo,mcp_servers,metadata,output_config,service_tier,speed,stop_sequences,stream,system,thinking,thread,tool_choice,tools", "", "json"},
+ {Call::kMessagesCountTokens, "messages.count_tokens", "POST", "/v1/messages/count_tokens", "messages/messages.py:Messages.count_tokens|beta/messages/messages.py:Messages.count_tokens", "messages/count_tokens", "messages,model,cache_control,compaction,context_management,mcp_servers,output_config,speed,system,thinking,tool_choice,tools", "", "json"},
+ {Call::kBatchesCreate, "messages.batches.create", "POST", "/v1/messages/batches", "messages/batches.py:Batches.create|beta/messages/batches.py:Batches.create", "messages/batches/create", "requests", "", "json"},
+ {Call::kBatchesRetrieve, "messages.batches.retrieve", "GET", "/v1/messages/batches/{message_batch_id}", "messages/batches.py:Batches.retrieve|beta/messages/batches.py:Batches.retrieve", "messages/batches/retrieve", "", "", "none"},
+ {Call::kBatchesList, "messages.batches.list", "GET", "/v1/messages/batches", "messages/batches.py:Batches.list|beta/messages/batches.py:Batches.list", "messages/batches/list", "", "after_id,before_id,limit", "none"},
+ {Call::kBatchesDelete, "messages.batches.delete", "DELETE", "/v1/messages/batches/{message_batch_id}", "messages/batches.py:Batches.delete|beta/messages/batches.py:Batches.delete", "messages/batches/delete", "", "", "none"},
+ {Call::kBatchesCancel, "messages.batches.cancel", "POST", "/v1/messages/batches/{message_batch_id}/cancel", "messages/batches.py:Batches.cancel|beta/messages/batches.py:Batches.cancel", "messages/batches/cancel", "", "", "none"},
+ {Call::kBatchesResults, "messages.batches.results", "GET", "/v1/messages/batches/{message_batch_id}/results", "messages/batches.py:Batches.results|beta/messages/batches.py:Batches.results", "messages/batches/results", "", "", "none"},
+ {Call::kModelsList, "models.list", "GET", "/v1/models", "models.py:Models.list|beta/models.py:Models.list", "models/list", "", "after_id,before_id,lifecycle,limit", "none"},
+ {Call::kModelsRetrieve, "models.retrieve", "GET", "/v1/models/{model_id}", "models.py:Models.retrieve|beta/models.py:Models.retrieve", "models/retrieve", "", "", "none"},
+ {Call::kFilesUpload, "files.upload", "POST", "/v1/files", "files.py:Files.upload|beta/files.py:Files.upload", "files/upload", "file,expires_in_seconds", "", "multipart"},
+ {Call::kFilesList, "files.list", "GET", "/v1/files", "files.py:Files.list|beta/files.py:Files.list", "files/list", "", "ids,limit,page,scope_id", "none"},
+ {Call::kFilesRetrieveMetadata, "files.retrieve_metadata", "GET", "/v1/files/{file_id}", "files.py:Files.retrieve_metadata|beta/files.py:Files.retrieve_metadata", "files/retrieve_metadata", "", "", "none"},
+ {Call::kFilesDownload, "files.download", "GET", "/v1/files/{file_id}/content", "files.py:Files.download|beta/files.py:Files.download", "files/download", "", "", "none"},
+ {Call::kFilesDelete, "files.delete", "DELETE", "/v1/files/{file_id}", "files.py:Files.delete|beta/files.py:Files.delete", "files/delete", "", "", "none"},
+ {Call::kSkillsCreate, "skills.create", "POST", "/v1/skills", "skills/skills.py:Skills.create|beta/skills/skills.py:Skills.create", "skills/create", "files,display_name", "", "multipart"},
+ {Call::kSkillsList, "skills.list", "GET", "/v1/skills", "skills/skills.py:Skills.list|beta/skills/skills.py:Skills.list", "skills/list", "", "limit,page,source", "none"},
+ {Call::kSkillsRetrieve, "skills.retrieve", "GET", "/v1/skills/{skill_id}", "skills/skills.py:Skills.retrieve|beta/skills/skills.py:Skills.retrieve", "skills/retrieve", "", "", "none"},
+ {Call::kSkillsDelete, "skills.delete", "DELETE", "/v1/skills/{skill_id}", "skills/skills.py:Skills.delete|beta/skills/skills.py:Skills.delete", "skills/delete", "", "", "none"},
+ {Call::kSkillVersionsCreate, "skills.versions.create", "POST", "/v1/skills/{skill_id}/versions", "skills/versions.py:Versions.create|beta/skills/versions.py:Versions.create", "skills/versions/create", "files", "", "multipart"},
+ {Call::kSkillVersionsList, "skills.versions.list", "GET", "/v1/skills/{skill_id}/versions", "skills/versions.py:Versions.list|beta/skills/versions.py:Versions.list", "skills/versions/list", "", "limit,page", "none"},
+ {Call::kSkillVersionsRetrieve, "skills.versions.retrieve", "GET", "/v1/skills/{skill_id}/versions/{version}", "skills/versions.py:Versions.retrieve|beta/skills/versions.py:Versions.retrieve", "skills/versions/retrieve", "", "", "none"},
+ {Call::kSkillVersionsDelete, "skills.versions.delete", "DELETE", "/v1/skills/{skill_id}/versions/{version}", "skills/versions.py:Versions.delete|beta/skills/versions.py:Versions.delete", "skills/versions/delete", "", "", "none"},
+ {Call::kSkillVersionsDownload, "skills.versions.download", "GET", "/v1/skills/{skill_id}/versions/{version}/content", "-|beta/skills/versions.py:Versions.download", "beta/skills/versions/download", "", "", "none"},
+ {Call::kUserProfilesCreate, "user_profiles.create", "POST", "/v1/user_profiles", "user_profiles/user_profiles.py:UserProfiles.create|beta/user_profiles/user_profiles.py:UserProfiles.create", "user_profiles/create", "access_type,external_id,external_user_details,external_user_onboarded_at,metadata,name", "", "json"},
+ {Call::kUserProfilesRetrieve, "user_profiles.retrieve", "GET", "/v1/user_profiles/{user_profile_id}", "user_profiles/user_profiles.py:UserProfiles.retrieve|beta/user_profiles/user_profiles.py:UserProfiles.retrieve", "user_profiles/retrieve", "", "", "none"},
+ {Call::kUserProfilesUpdate, "user_profiles.update", "POST", "/v1/user_profiles/{user_profile_id}", "user_profiles/user_profiles.py:UserProfiles.update|beta/user_profiles/user_profiles.py:UserProfiles.update", "user_profiles/update", "access_type,external_id,external_user_details,external_user_onboarded_at,metadata,name", "", "json"},
+ {Call::kUserProfilesList, "user_profiles.list", "GET", "/v1/user_profiles", "user_profiles/user_profiles.py:UserProfiles.list|beta/user_profiles/user_profiles.py:UserProfiles.list", "user_profiles/list", "", "enforcement_status,limit,order,order_by,page", "none"},
+ {Call::kUserProfilesDelete, "user_profiles.delete", "DELETE", "/v1/user_profiles/{user_profile_id}", "user_profiles/user_profiles.py:UserProfiles.delete|beta/user_profiles/user_profiles.py:UserProfiles.delete", "user_profiles/delete", "", "", "none"},
+ {Call::kUserProfilesEnrollmentUrl, "user_profiles.create_enrollment_url", "POST", "/v1/user_profiles/{user_profile_id}/enrollment_url", "-|beta/user_profiles/user_profiles.py:UserProfiles.create_enrollment_url", "beta/user_profiles/create_enrollment_url", "", "", "none"},
+ {Call::kUserProfilesActionUrlsCreate, "user_profiles.action_urls.create", "POST", "/v1/user_profiles/{user_profile_id}/action_urls", "user_profiles/action_urls.py:ActionURLs.create|beta/user_profiles/action_urls.py:ActionURLs.create", "user_profiles/action_urls/create", "action", "", "json"},
+ {Call::kCompletionsCreate, "completions.create", "POST", "/v1/complete", "-|-", "completions/create", "max_tokens_to_sample,model,prompt,metadata,stop_sequences,stream,temperature,top_k,top_p", "", "json"},
+};
+// CALLS-END
+
+const CallSpec& spec_of(Call call) {
+ for (const CallSpec& c : kCalls)
+ if (c.call == call) return c;
+ bad("unknown call");
+}
+
+clients::Method method_of(Call call) {
+ std::string m = spec_of(call).http_method;
+ if (m == "GET") return clients::Method::kGet;
+ if (m == "POST") return clients::Method::kPost;
+ if (m == "DELETE") return clients::Method::kDelete;
+ if (m == "PATCH") return clients::Method::kPatch;
+ bad("unsupported method " + m);
+}
+
+std::size_t call_count() { return sizeof(kCalls) / sizeof(kCalls[0]); }
+const CallSpec& spec_at(std::size_t index) { return kCalls[index]; }
+
+std::size_t placeholder_count(Call call) {
+ std::string p = spec_of(call).path;
+ std::size_t n = 0;
+ for (char c : p)
+ if (c == '{') ++n;
+ return n;
+}
+
+std::string render(Call call, const std::string& id1, const std::string& id2) {
+ const CallSpec& spec = spec_of(call);
+ std::string path = spec.path;
+ const std::string* ids[2] = {&id1, &id2};
+ std::size_t used = 0;
+ std::size_t pos = 0;
+ while ((pos = path.find('{', pos)) != std::string::npos) {
+ std::size_t end = path.find('}', pos);
+ if (end == std::string::npos || used >= 2) bad("bad path template");
+ const std::string& id = *ids[used++];
+ if (!llm::Service::valid_id(id))
+ bad("bad " + path.substr(pos + 1, end - pos - 1) + " (one segment of A-Z a-z 0-9 . _ : -)");
+ path.replace(pos, end - pos + 1, id);
+ pos += id.size();
+ }
+ if (used != placeholder_count(call)) bad("wrong number of ids for " + std::string(spec.key));
+ return path;
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/calls.h b/src/anthropic/core/calls.h
new file mode 100644
index 0000000..3c57975
--- /dev/null
+++ b/src/anthropic/core/calls.h
@@ -0,0 +1,76 @@
+#pragma once
+
+// The ONE table of REST calls this module makes. Every row is checked by
+// tools/check_spec.py against the pinned official Python SDK source and the
+// API reference pages. Code builds every path from this table, never from a
+// literal.
+
+#include
+#include
+
+#include "clients/request.h"
+
+namespace molo::anthropic::core {
+
+enum class Call {
+ kMessagesCreate,
+ kMessagesCountTokens,
+ kBatchesCreate,
+ kBatchesRetrieve,
+ kBatchesList,
+ kBatchesDelete,
+ kBatchesCancel,
+ kBatchesResults,
+ kModelsList,
+ kModelsRetrieve,
+ kFilesUpload,
+ kFilesList,
+ kFilesRetrieveMetadata,
+ kFilesDownload,
+ kFilesDelete,
+ kSkillsCreate,
+ kSkillsList,
+ kSkillsRetrieve,
+ kSkillsDelete,
+ kSkillVersionsCreate,
+ kSkillVersionsList,
+ kSkillVersionsRetrieve,
+ kSkillVersionsDelete,
+ kSkillVersionsDownload,
+ kUserProfilesCreate,
+ kUserProfilesRetrieve,
+ kUserProfilesUpdate,
+ kUserProfilesList,
+ kUserProfilesDelete,
+ kUserProfilesEnrollmentUrl,
+ kUserProfilesActionUrlsCreate,
+ kCompletionsCreate,
+};
+
+struct CallSpec {
+ Call call;
+ const char* key; // "messages.create": SDK resource path and method
+ const char* http_method; // GET POST DELETE
+ const char* path; // "/v1/messages/batches/{message_batch_id}"
+ const char* sdk; // ":.|:.", "-" when absent
+ const char* doc; // API reference slug of the GA page (or "beta/..." when beta only)
+ const char* body_fields; // comma list: JSON or form fields we send
+ const char* query_params; // comma list: query parameters we send
+ const char* body_kind; // "none", "json", "multipart"
+};
+
+const CallSpec& spec_of(Call call);
+clients::Method method_of(Call call);
+std::size_t call_count();
+const CallSpec& spec_at(std::size_t index);
+
+// Legacy sampling fields: accepted by anthropic-version 2023-06-01 only (see
+// versioning and migration pages). Not in the current Messages reference.
+extern const char* const kLegacySamplingFields;
+
+// Renders the path. `ids` replace the {placeholders} in order of appearance;
+// every id passes llm::Service::valid_id first (ApiError::invalid otherwise).
+std::string render(Call call, const std::string& id1 = "", const std::string& id2 = "");
+std::size_t placeholder_count(Call call);
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/caps.h b/src/anthropic/core/caps.h
new file mode 100644
index 0000000..b002fab
--- /dev/null
+++ b/src/anthropic/core/caps.h
@@ -0,0 +1,71 @@
+#pragma once
+
+// Static ceilings for the Anthropic core module. Never autotuned. Values that
+// come from the vendor are marked (api), values that are local safety
+// ceilings are marked (local). See SPEC.md section 3.
+
+#include
+
+#include "llm/caps.h"
+
+namespace molo::anthropic::core {
+
+struct CoreCaps {
+ // Messages request shape.
+ static constexpr std::size_t kMaxMessages = llm::Caps::kMaxMessages; // (local) api allows 100000
+ static constexpr std::size_t kMaxBlocksPerMessage = 2048; // (local)
+ static constexpr std::size_t kMaxSystemBlocks = 64; // (local)
+ static constexpr std::size_t kMaxTools = llm::Caps::kMaxTools; // (local)
+ static constexpr std::size_t kMaxToolNameChars = 128; // (api) ^[a-zA-Z0-9_-]{1,128}$
+ static constexpr std::size_t kMaxStopSequences = 64; // (local)
+ static constexpr std::size_t kMaxStopSequenceChars = 1024; // (local)
+ static constexpr std::size_t kMaxCacheBreakpoints = 4; // (api) per request
+ static constexpr std::size_t kMaxMcpServers = 32; // (local)
+ static constexpr std::size_t kMaxFallbacks = 8; // (local)
+ static constexpr std::size_t kMaxContextEdits = 16; // (local)
+ static constexpr std::size_t kMaxCitations = 512; // (local)
+ static constexpr std::size_t kMaxTextBytes = 16u * 1024u * 1024u; // (local) one text block
+ static constexpr std::size_t kMaxMetadataUserId = 256; // (local)
+ static constexpr std::size_t kMaxIdChars = 256; // (local) ids in bodies
+ static constexpr int kMinThinkingBudget = 1024; // (api)
+ static constexpr int kMaxMaxTokens = 4000000; // (local)
+
+ // Headers.
+ static constexpr std::size_t kMaxBetas = 32; // (local)
+ static constexpr std::size_t kMaxBetaNameChars = 128; // (local)
+ static constexpr std::size_t kMaxHeaderValueChars = 4096; // (local)
+
+ // Lists and paging.
+ static constexpr int kDefaultListLimit = 20; // (api)
+ static constexpr int kMaxListLimit = 1000; // (api)
+ static constexpr int kMaxListPages = 20; // (local) walk helpers
+ static constexpr std::size_t kMaxFileIds = 100; // (api) files list ids=
+ static constexpr int kMaxLifecycleFilter = 3; // (api) models lifecycle=
+
+ // Batches.
+ static constexpr std::size_t kMaxBatchRequests = 100000; // (api)
+ static constexpr std::size_t kMaxBatchBytes = llm::Caps::kMaxRequestBytes; // (local) api 256 MB
+ static constexpr std::size_t kMaxCustomIdChars = 64; // (api) ^[a-zA-Z0-9_-]{1,64}$
+ static constexpr std::size_t kMaxResultLines = 100000; // (api) = max requests
+
+ // Files and skills.
+ static constexpr std::size_t kMaxFileBytes = 500u * 1024u * 1024u; // (api) 500 MB per file
+ static constexpr long kMinFileExpirySeconds = 3600; // (api)
+ static constexpr long kMaxFileExpirySeconds = 7776000; // (api)
+ static constexpr std::size_t kMaxFilenameChars = 500; // (api)
+ static constexpr std::size_t kMaxSkillFiles = 500; // (local)
+ static constexpr std::size_t kMaxSkillBytes = 30u * 1024u * 1024u; // (api) 30 MB uncompressed
+ static constexpr std::size_t kMaxSkillsPerRequest = 20; // (api)
+ static constexpr std::size_t kMaxDisplayNameChars = 255; // (api)
+
+ // User profiles.
+ static constexpr std::size_t kMaxProfileMetadata = 64; // (local)
+ static constexpr std::size_t kMaxProfileValueChars = 1024; // (local)
+
+ // Streaming.
+ static constexpr std::size_t kMaxStreamEvents = 500000; // (local)
+ static constexpr std::size_t kMaxContentBlocks = 4096; // (local) per response
+ static constexpr std::size_t kMaxPartialJsonBytes = 8u * 1024u * 1024u; // (local) one tool input
+};
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/chat_model.cpp b/src/anthropic/core/chat_model.cpp
new file mode 100644
index 0000000..706fa2f
--- /dev/null
+++ b/src/anthropic/core/chat_model.cpp
@@ -0,0 +1,192 @@
+#include "anthropic/core/chat_model.h"
+
+#include "anthropic/core/util.h"
+#include "security/crypto/Base64.h"
+
+namespace molo::anthropic::core {
+
+namespace {
+const char* kRedacted = "redacted_thinking:";
+
+ContentBlock image_block(const llm::ImageData& img) {
+ if (!img.url.empty()) return ContentBlock::image_url(img.url);
+ if (img.bytes.empty()) bad("image part has neither url nor bytes");
+ return ContentBlock::image_base64(img.mime, security::crypto::Base64::encode(img.bytes));
+}
+
+void add_part(std::vector& out, const llm::ContentPart& p) {
+ if (!p.reasoning_signature.empty()) {
+ if (p.reasoning_signature.rfind(kRedacted, 0) == 0)
+ out.push_back(ContentBlock::redacted_thinking(p.reasoning_signature.substr(std::string(kRedacted).size())));
+ else
+ out.push_back(ContentBlock::thinking(p.reasoning, p.reasoning_signature));
+ }
+ if (!p.text.empty()) out.push_back(ContentBlock::text(p.text));
+ if (p.image) out.push_back(image_block(*p.image));
+ if (p.tool_call)
+ out.push_back(ContentBlock::tool_use(p.tool_call->id, p.tool_call->name, p.tool_call->arguments));
+ if (p.tool_result)
+ out.push_back(ContentBlock::tool_result(p.tool_result->call_id, p.tool_result->content, p.tool_result->is_error));
+}
+} // namespace
+
+std::string finish_reason_of(StopReason r) {
+ switch (r) {
+ case StopReason::kEndTurn:
+ case StopReason::kStopSequence: return "stop";
+ case StopReason::kMaxTokens:
+ case StopReason::kModelContextWindowExceeded: return "length";
+ case StopReason::kToolUse: return "tool_calls";
+ case StopReason::kRefusal: return "content_filter";
+ case StopReason::kPauseTurn: return "pause_turn";
+ case StopReason::kCompaction: return "compaction";
+ default: return "";
+ }
+}
+
+AnthropicChatModel::AnthropicChatModel(std::shared_ptr messages, std::string default_model,
+ int default_max_tokens)
+ : messages_(std::move(messages)), default_model_(std::move(default_model)), default_max_tokens_(default_max_tokens) {}
+
+MessageRequest AnthropicChatModel::to_message_request(const llm::ChatRequest& in) const {
+ MessageRequest r;
+ r.model = in.model.empty() ? default_model_ : in.model;
+ r.set_max_tokens(in.max_tokens ? *in.max_tokens : default_max_tokens_);
+ std::string system = in.system;
+ std::size_t i = 0;
+ for (; i < in.messages.size() && in.messages[i].role == llm::Role::kSystem; ++i) {
+ if (!system.empty()) system += "\n\n";
+ system += in.messages[i].text();
+ }
+ r.system_text = system;
+ for (; i < in.messages.size(); ++i) {
+ const llm::Message& m = in.messages[i];
+ std::vector blocks;
+ for (const llm::ContentPart& p : m.parts) add_part(blocks, p);
+ if (m.role == llm::Role::kSystem) {
+ r.add(MessageParam::system(m.text()));
+ continue;
+ }
+ if (blocks.empty()) bad("message has no content");
+ if (m.role == llm::Role::kAssistant) r.add(MessageParam::assistant(std::move(blocks)));
+ else r.add(MessageParam::user(std::move(blocks))); // kUser and kTool
+ }
+ for (const llm::ToolSpec& t : in.tools) r.add_tool(Tool::custom(t.name, t.description, t.parameters));
+ if (!in.tool_choice.empty()) {
+ if (in.tool_choice == "auto") r.tool_choice = ToolChoice::auto_();
+ else if (in.tool_choice == "none") r.tool_choice = ToolChoice::none();
+ else if (in.tool_choice == "required") r.tool_choice = ToolChoice::any();
+ else r.tool_choice = ToolChoice::tool(in.tool_choice);
+ }
+ if (in.temperature) r.temperature = *in.temperature;
+ if (in.top_p) r.top_p = *in.top_p;
+ r.stop_sequences = in.stop;
+ if (in.json_mode && in.response_schema.is_null())
+ bad("json_mode needs response_schema: Anthropic has no schemaless JSON mode");
+ if (!in.response_schema.is_null()) r.output.format = in.response_schema;
+ r.output.effort = in.reasoning_effort;
+ // Vendor passthrough: "betas" feeds the header, "thinking" is typed, anything
+ // else is merged as an extra top-level field.
+ if (in.extra.is_object()) {
+ for (const auto& [k, v] : in.extra.as_object()) {
+ if (k == "betas") {
+ if (!v.is_array()) bad("extra.betas must be an array of strings");
+ for (const Json& b : v.as_array()) {
+ if (!b.is_string()) bad("extra.betas must be an array of strings");
+ r.betas.add_name(b.as_string());
+ }
+ } else if (k == "thinking") {
+ std::string t = str_at(v, "type");
+ if (t == "enabled") r.thinking = ThinkingConfig::enabled(static_cast(num_at(v, "budget_tokens")));
+ else if (t == "adaptive") r.thinking = ThinkingConfig::adaptive();
+ else if (t == "disabled") r.thinking = ThinkingConfig::disabled();
+ else if (t == "between_tools") r.thinking = ThinkingConfig::between_tools();
+ else bad("extra.thinking.type is not valid");
+ } else {
+ r.extra.set(k, v);
+ }
+ }
+ }
+ return r;
+}
+
+llm::ChatResponse AnthropicChatModel::to_chat_response(const Message& m) {
+ llm::ChatResponse out;
+ out.id = m.id;
+ out.model = m.model;
+ out.message.role = llm::Role::kAssistant;
+ for (const Block& b : m.content) {
+ if (b.kind == BlockKind::kText) {
+ out.message.parts.push_back(llm::ContentPart::of_text(b.text()));
+ } else if (b.kind == BlockKind::kThinking) {
+ llm::ContentPart p;
+ p.reasoning = b.thinking();
+ p.reasoning_signature = b.signature();
+ out.message.parts.push_back(p);
+ } else if (b.kind == BlockKind::kRedactedThinking) {
+ llm::ContentPart p;
+ p.reasoning_signature = kRedacted + b.redacted_data();
+ out.message.parts.push_back(p);
+ } else if (b.kind == BlockKind::kToolUse) {
+ out.message.parts.push_back(llm::ContentPart::of_call(llm::ToolCall{b.id(), b.name(), b.input()}));
+ }
+ }
+ out.finish_reason = finish_reason_of(m.stop_reason);
+ out.usage.input_tokens = static_cast(m.usage.input_tokens);
+ out.usage.output_tokens = static_cast(m.usage.output_tokens);
+ out.usage.total_tokens = out.usage.input_tokens + out.usage.output_tokens;
+ out.usage.cached_tokens = static_cast(m.usage.cache_read_input_tokens);
+ out.usage.reasoning_tokens = static_cast(m.usage.thinking_tokens);
+ out.raw = m.raw;
+ return out;
+}
+
+llm::ChatResponse AnthropicChatModel::generate(const llm::ChatRequest& request) {
+ return to_chat_response(messages_->create(to_message_request(request)).message);
+}
+
+void AnthropicChatModel::stream(const llm::ChatRequest& request,
+ const std::function& on_chunk) {
+ std::string tool_id, tool_name;
+ StreamResult res = messages_->stream(to_message_request(request), [&](const StreamEvent& ev) {
+ llm::ChatChunk c;
+ bool emit = false;
+ if (ev.kind == EventKind::kContentBlockStart) {
+ const Json* b = member(ev.data, "content_block");
+ if (b && str_at(*b, "type") == "tool_use") {
+ tool_id = str_at(*b, "id");
+ tool_name = str_at(*b, "name");
+ c.tool_call_id = tool_id;
+ c.tool_call_name = tool_name;
+ emit = true;
+ }
+ } else if (ev.kind == EventKind::kContentBlockDelta) {
+ if (ev.delta_kind == DeltaKind::kText) { c.text_delta = ev.text; emit = true; }
+ else if (ev.delta_kind == DeltaKind::kThinking) { c.reasoning_delta = ev.text; emit = true; }
+ else if (ev.delta_kind == DeltaKind::kInputJson) {
+ c.tool_call_id = tool_id;
+ c.tool_call_name = tool_name;
+ c.tool_args_delta = ev.text;
+ emit = true;
+ }
+ } else if (ev.kind == EventKind::kMessageDelta) {
+ const Json* d = member(ev.data, "delta");
+ c.finish_reason = finish_reason_of(parse_stop_reason(d ? str_at(*d, "stop_reason") : ""));
+ if (const Json* u = member(ev.data, "usage")) {
+ Usage us = Usage::parse(*u);
+ llm::Usage lu;
+ lu.input_tokens = static_cast(us.input_tokens);
+ lu.output_tokens = static_cast(us.output_tokens);
+ lu.total_tokens = lu.input_tokens + lu.output_tokens;
+ lu.cached_tokens = static_cast(us.cache_read_input_tokens);
+ lu.reasoning_tokens = static_cast(us.thinking_tokens);
+ c.usage = lu;
+ }
+ emit = true;
+ }
+ return emit ? on_chunk(c) : true;
+ });
+ last_stream_ = res.message;
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/chat_model.h b/src/anthropic/core/chat_model.h
new file mode 100644
index 0000000..097c928
--- /dev/null
+++ b/src/anthropic/core/chat_model.h
@@ -0,0 +1,48 @@
+#pragma once
+
+// AnthropicChatModel: llm::ChatModel over the Messages API.
+//
+// Mapping (see SPEC): leading system messages and ChatRequest.system become
+// `system`; kTool messages become user messages with tool_result blocks;
+// assistant reasoning + reasoning_signature become a thinking block (replayed
+// exactly), a reasoning_signature starting with "redacted_thinking:" becomes a
+// redacted_thinking block; tool_call parts are tool_use blocks. json_mode
+// without response_schema is rejected (no schemaless JSON mode exists);
+// response_schema becomes output_config.format; reasoning_effort becomes
+// output_config.effort. ChatRequest.extra may carry any other typed field and a
+// "betas" string array.
+
+#include
+#include
+
+#include "anthropic/core/messages.h"
+#include "llm/chat_types.h"
+
+namespace molo::anthropic::core {
+
+class AnthropicChatModel : public llm::ChatModel {
+ public:
+ AnthropicChatModel(std::shared_ptr messages, std::string default_model, int default_max_tokens = 4096);
+
+ std::string vendor() const override { return "anthropic"; }
+ llm::ChatResponse generate(const llm::ChatRequest& request) override;
+ void stream(const llm::ChatRequest& request,
+ const std::function& on_chunk) override;
+
+ // The typed request the neutral one maps to (for inspection and tests).
+ MessageRequest to_message_request(const llm::ChatRequest& request) const;
+ static llm::ChatResponse to_chat_response(const Message& message);
+ // The full Message of the last stream() call (carries thinking signatures,
+ // which ChatChunk cannot).
+ const Message& last_stream_message() const { return last_stream_; }
+
+ private:
+ std::shared_ptr messages_;
+ std::string default_model_;
+ int default_max_tokens_;
+ Message last_stream_;
+};
+
+std::string finish_reason_of(StopReason reason);
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/completions.cpp b/src/anthropic/core/completions.cpp
new file mode 100644
index 0000000..dd8ac9a
--- /dev/null
+++ b/src/anthropic/core/completions.cpp
@@ -0,0 +1,50 @@
+#include "anthropic/core/completions.h"
+
+#include "anthropic/core/util.h"
+
+namespace molo::anthropic::core {
+
+void CompletionRequest::validate(ApiVersion version) const {
+ if (model.empty()) bad("model is required");
+ if (prompt.empty() || prompt.size() > CoreCaps::kMaxTextBytes) bad("prompt is required");
+ if (max_tokens_to_sample < 1) bad("max_tokens_to_sample must be at least 1");
+ if (stop_sequences.size() > CoreCaps::kMaxStopSequences) bad("too many stop_sequences");
+ if (metadata_user_id.size() > 512) bad("metadata user_id over 512 chars");
+ if ((temperature || top_p || top_k) && !version_info(version).sampling_params)
+ bad("temperature, top_p and top_k are removed in this anthropic-version");
+ if (temperature && (*temperature < 0 || *temperature > 1)) bad("temperature must be in [0, 1]");
+ if (top_p && (*top_p < 0 || *top_p > 1)) bad("top_p must be in [0, 1]");
+ if (top_k && *top_k < 0) bad("top_k must be >= 0");
+}
+
+Json CompletionRequest::to_json() const {
+ Json j = obj();
+ j.set("model", Json(model));
+ j.set("prompt", Json(prompt));
+ j.set("max_tokens_to_sample", Json(max_tokens_to_sample));
+ if (!stop_sequences.empty()) j.set("stop_sequences", json_strings(stop_sequences));
+ if (!metadata_user_id.empty()) {
+ Json m = obj();
+ m.set("user_id", Json(metadata_user_id));
+ j.set("metadata", m);
+ }
+ if (temperature) j.set("temperature", Json(*temperature));
+ if (top_p) j.set("top_p", Json(*top_p));
+ if (top_k) j.set("top_k", Json(*top_k));
+ return j;
+}
+
+Completion Completions::create(const CompletionRequest& request) {
+ request.validate(session().version());
+ Json body = request.to_json();
+ Json doc = call_json(Call::kCompletionsCreate, "", "", "", &body);
+ Completion c;
+ c.raw = doc;
+ c.id = str_at(doc, "id");
+ c.completion = str_at(doc, "completion");
+ c.model = str_at(doc, "model");
+ c.stop_reason = str_at(doc, "stop_reason");
+ return c;
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/completions.h b/src/anthropic/core/completions.h
new file mode 100644
index 0000000..525ce2e
--- /dev/null
+++ b/src/anthropic/core/completions.h
@@ -0,0 +1,40 @@
+#pragma once
+
+// Legacy Text Completions (POST /v1/complete), deprecated by the vendor.
+// Non-streaming only; the streamed completion event shape was not read from a
+// source and is not implemented (SPEC Gaps).
+
+#include
+#include
+#include
+
+#include "anthropic/core/caps.h"
+#include "anthropic/core/session.h"
+
+namespace molo::anthropic::core {
+
+struct CompletionRequest {
+ std::string model;
+ std::string prompt; // "\n\nHuman: ...\n\nAssistant:"
+ int max_tokens_to_sample = 0;
+ std::vector stop_sequences;
+ std::string metadata_user_id;
+ std::optional temperature;
+ std::optional top_p;
+ std::optional top_k;
+ void validate(ApiVersion version) const;
+ Json to_json() const;
+};
+
+struct Completion {
+ std::string id, completion, model, stop_reason;
+ Json raw;
+};
+
+class Completions : public CoreService {
+ public:
+ explicit Completions(std::shared_ptr session) : CoreService(std::move(session)) {}
+ Completion create(const CompletionRequest& request);
+};
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/content.cpp b/src/anthropic/core/content.cpp
new file mode 100644
index 0000000..e479e02
--- /dev/null
+++ b/src/anthropic/core/content.cpp
@@ -0,0 +1,321 @@
+#include "anthropic/core/content.h"
+
+#include "anthropic/core/caps.h"
+#include "anthropic/core/util.h"
+#include "llm/api_client.h"
+
+namespace molo::anthropic::core {
+
+// BLOCKS-BEGIN (request content block param union; checked by tools/check_spec.py)
+static const BlockSchema kBlocks[] = {
+ {"text", "text", "cache_control,citations", "", true},
+ {"image", "source", "cache_control,transformations", "", true},
+ {"document", "source", "cache_control,citations,context,title", "", true},
+ {"search_result", "content,source,title", "cache_control,citations", "", true},
+ {"thinking", "signature,thinking", "", "", true},
+ {"redacted_thinking", "data", "", "", true},
+ {"tool_use", "id,input,name", "cache_control,caller,toolset_name", "", true},
+ {"tool_result", "tool_use_id", "cache_control,content,is_error,toolset_name", "", true},
+ {"server_tool_use", "id,input,name", "cache_control,caller", "", true},
+ {"web_search_tool_result", "content,tool_use_id", "cache_control,caller", "", true},
+ {"web_fetch_tool_result", "content,tool_use_id", "cache_control,caller", "", true},
+ {"advisor_tool_result", "content,tool_use_id", "cache_control", "advisor-tool-2026-03-01", false},
+ {"code_execution_tool_result", "content,tool_use_id", "cache_control", "", true},
+ {"bash_code_execution_tool_result", "content,tool_use_id", "cache_control", "", true},
+ {"text_editor_code_execution_tool_result", "content,tool_use_id", "cache_control", "", true},
+ {"tool_search_tool_result", "content,tool_use_id", "cache_control", "", true},
+ {"mcp_tool_use", "id,input,name,server_name", "cache_control", "mcp-client-2025-11-20", false},
+ {"mcp_tool_result", "tool_use_id", "cache_control,content,is_error", "mcp-client-2025-11-20", false},
+ {"container_upload", "file_id", "cache_control", "", true},
+ {"compaction", "", "cache_control,content,encrypted_content,signature,tool_changes", "compact-2026-01-12", false},
+ {"tool_addition", "tool", "cache_control", "inline-tools-2026-09-15", false},
+ {"tool_removal", "tool", "cache_control", "inline-tools-2026-09-15", false},
+ {"mcp_tool_listing", "mcp_server_name,tools", "", "mcp-client-2026-09-15", false},
+ {"fallback", "to", "trigger", "server-side-fallback-2026-07-01", false},
+};
+// BLOCKS-END
+
+const BlockSchema* find_block_schema(const std::string& type) {
+ for (const BlockSchema& b : kBlocks)
+ if (type == b.type) return &b;
+ return nullptr;
+}
+std::size_t block_schema_count() { return sizeof(kBlocks) / sizeof(kBlocks[0]); }
+const BlockSchema& block_schema_at(std::size_t i) { return kBlocks[i]; }
+
+bool is_response_block_type(const std::string& type) {
+ return find_block_schema(type) != nullptr;
+}
+
+Json CacheControl::to_json() const {
+ Json j = obj();
+ j.set("type", Json("ephemeral"));
+ if (explicit_ttl) j.set("ttl", Json(ttl == CacheTtl::k1h ? "1h" : "5m"));
+ return j;
+}
+
+CacheControl CacheControl::from_json(const Json& j) {
+ if (!j.is_object() || str_at(j, "type") != "ephemeral") bad("cache_control.type must be \"ephemeral\"");
+ for (const auto& [k, v] : j.as_object()) {
+ (void)v;
+ if (k != "type" && k != "ttl") bad("cache_control has unknown field " + k);
+ }
+ CacheControl cc;
+ if (const Json* t = member(j, "ttl")) {
+ if (!t->is_string() || (t->as_string() != "5m" && t->as_string() != "1h"))
+ bad("cache_control.ttl must be \"5m\" or \"1h\"");
+ cc.explicit_ttl = true;
+ cc.ttl = t->as_string() == "1h" ? CacheTtl::k1h : CacheTtl::k5m;
+ }
+ return cc;
+}
+
+namespace {
+
+Json source_obj(const std::string& type) {
+ Json s = obj();
+ s.set("type", Json(type));
+ return s;
+}
+
+void check_source(const Json& block) {
+ const Json* s = member(block, "source");
+ if (!s || !s->is_object()) bad(str_at(block, "type") + " source must be an object");
+ std::string t = str_at(*s, "type");
+ bool image = str_at(block, "type") == "image";
+ if (t == "base64") {
+ std::string mt = str_at(*s, "media_type");
+ if (image) {
+ if (mt != "image/jpeg" && mt != "image/png" && mt != "image/gif" && mt != "image/webp")
+ bad("image media_type must be image/jpeg, image/png, image/gif or image/webp");
+ } else if (mt != "application/pdf") {
+ bad("base64 document media_type must be application/pdf");
+ }
+ if (str_at(*s, "data").empty()) bad("source.data is empty");
+ } else if (t == "url") {
+ std::string u = str_at(*s, "url");
+ if (u.rfind("https://", 0) != 0 && u.rfind("http://", 0) != 0) bad("source.url must be http(s)");
+ } else if (t == "file") {
+ if (!llm::Service::valid_id(str_at(*s, "file_id"))) bad("source.file_id is not a valid id");
+ } else if (!image && t == "text") {
+ if (str_at(*s, "media_type") != "text/plain") bad("text document media_type must be text/plain");
+ if (!s->find("data") || !s->find("data")->is_string()) bad("text document needs source.data");
+ } else if (!image && t == "content") {
+ const Json* c = member(*s, "content");
+ if (!c || !(c->is_string() || c->is_array())) bad("content document needs string or block array content");
+ } else {
+ bad(str_at(block, "type") + " source.type '" + t + "' is not valid");
+ }
+}
+
+} // namespace
+
+void validate_block(const Json& block, bool echo) {
+ if (!block.is_object()) bad("content block must be an object");
+ std::string type = str_at(block, "type");
+ if (echo) { // response blocks keep every field the API sent, even new types
+ if (type.empty()) bad("content block has no type");
+ return;
+ }
+ const BlockSchema* sc = find_block_schema(type);
+ if (!sc) bad("unknown content block type '" + type + "'");
+ for (const auto& [k, v] : block.as_object()) {
+ (void)v;
+ if (k == "type") continue;
+ if (!in_list(sc->required, k) && !in_list(sc->optional, k))
+ bad(type + " block has unknown field '" + k + "'");
+ }
+ for (const std::string& r : split_list(sc->required))
+ if (!member(block, r)) bad(type + " block needs '" + r + "'");
+ if (const Json* cc = member(block, "cache_control"); cc && !cc->is_null()) CacheControl::from_json(*cc);
+ if (type == "image" || type == "document") check_source(block);
+ if (type == "text" && str_at(block, "text").size() > CoreCaps::kMaxTextBytes) bad("text block too large");
+ if (type == "tool_use" || type == "server_tool_use" || type == "mcp_tool_use") {
+ const Json* in = member(block, "input");
+ if (!in || !in->is_object()) bad(type + " input must be an object");
+ if (str_at(block, "id").empty() || str_at(block, "name").empty()) bad(type + " needs id and name");
+ }
+ if (const Json* id = member(block, "tool_use_id"); id && !llm::Service::valid_id(id->is_string() ? id->as_string() : ""))
+ bad(type + " tool_use_id is not a valid id");
+ if (const Json* c = member(block, "content"); c && c->is_array()) {
+ if (c->as_array().size() > CoreCaps::kMaxBlocksPerMessage) bad("too many nested blocks");
+ }
+}
+
+std::size_t count_cache_controls(const Json& j) {
+ std::size_t n = 0;
+ if (j.is_object()) {
+ for (const auto& [k, v] : j.as_object()) {
+ if (k == "cache_control" && !v.is_null()) ++n;
+ else n += count_cache_controls(v);
+ }
+ } else if (j.is_array()) {
+ for (const Json& v : j.as_array()) n += count_cache_controls(v);
+ }
+ return n;
+}
+
+Json blocks_to_json(const std::vector& blocks) {
+ Json a = arr();
+ for (const ContentBlock& b : blocks) a.push(b.json());
+ return a;
+}
+
+ContentBlock ContentBlock::from_json(const Json& j, bool echo) {
+ validate_block(j, echo);
+ return ContentBlock(str_at(j, "type"), j, echo);
+}
+
+namespace {
+ContentBlock build(Json j) { return ContentBlock::from_json(j); }
+} // namespace
+
+ContentBlock ContentBlock::text(std::string text) {
+ Json j = obj();
+ j.set("type", Json("text"));
+ j.set("text", Json(std::move(text)));
+ return build(j);
+}
+
+ContentBlock ContentBlock::image_base64(const std::string& media_type, std::string data) {
+ Json s = source_obj("base64");
+ s.set("media_type", Json(media_type));
+ s.set("data", Json(std::move(data)));
+ Json j = obj();
+ j.set("type", Json("image"));
+ j.set("source", s);
+ return build(j);
+}
+ContentBlock ContentBlock::image_url(std::string url) {
+ Json s = source_obj("url");
+ s.set("url", Json(std::move(url)));
+ Json j = obj();
+ j.set("type", Json("image"));
+ j.set("source", s);
+ return build(j);
+}
+ContentBlock ContentBlock::image_file(std::string file_id) {
+ Json s = source_obj("file");
+ s.set("file_id", Json(std::move(file_id)));
+ Json j = obj();
+ j.set("type", Json("image"));
+ j.set("source", s);
+ return build(j);
+}
+
+namespace {
+ContentBlock doc(Json source) {
+ Json j = obj();
+ j.set("type", Json("document"));
+ j.set("source", std::move(source));
+ return build(j);
+}
+} // namespace
+
+ContentBlock ContentBlock::document_pdf_base64(std::string data) {
+ Json s = source_obj("base64");
+ s.set("media_type", Json("application/pdf"));
+ s.set("data", Json(std::move(data)));
+ return doc(s);
+}
+ContentBlock ContentBlock::document_pdf_url(std::string url) {
+ Json s = source_obj("url");
+ s.set("url", Json(std::move(url)));
+ return doc(s);
+}
+ContentBlock ContentBlock::document_text(std::string text) {
+ Json s = source_obj("text");
+ s.set("media_type", Json("text/plain"));
+ s.set("data", Json(std::move(text)));
+ return doc(s);
+}
+ContentBlock ContentBlock::document_content(std::vector blocks) {
+ Json s = source_obj("content");
+ s.set("content", blocks_to_json(blocks));
+ return doc(s);
+}
+ContentBlock ContentBlock::document_file(std::string file_id) {
+ Json s = source_obj("file");
+ s.set("file_id", Json(std::move(file_id)));
+ return doc(s);
+}
+
+ContentBlock ContentBlock::search_result(std::string source, std::string title,
+ std::vector text_blocks) {
+ Json j = obj();
+ j.set("type", Json("search_result"));
+ j.set("source", Json(std::move(source)));
+ j.set("title", Json(std::move(title)));
+ j.set("content", blocks_to_json(text_blocks));
+ return build(j);
+}
+
+ContentBlock ContentBlock::thinking(std::string thinking, std::string signature) {
+ Json j = obj();
+ j.set("type", Json("thinking"));
+ j.set("thinking", Json(std::move(thinking)));
+ j.set("signature", Json(std::move(signature)));
+ return build(j);
+}
+ContentBlock ContentBlock::redacted_thinking(std::string data) {
+ Json j = obj();
+ j.set("type", Json("redacted_thinking"));
+ j.set("data", Json(std::move(data)));
+ return build(j);
+}
+
+ContentBlock ContentBlock::tool_use(std::string id, std::string name, Json input) {
+ Json j = obj();
+ j.set("type", Json("tool_use"));
+ j.set("id", Json(std::move(id)));
+ j.set("name", Json(std::move(name)));
+ j.set("input", std::move(input));
+ return build(j);
+}
+ContentBlock ContentBlock::tool_result(std::string tool_use_id, std::string content, bool is_error) {
+ Json j = obj();
+ j.set("type", Json("tool_result"));
+ j.set("tool_use_id", Json(std::move(tool_use_id)));
+ j.set("content", Json(std::move(content)));
+ if (is_error) j.set("is_error", Json(true));
+ return build(j);
+}
+ContentBlock ContentBlock::tool_result_blocks(std::string tool_use_id, std::vector content,
+ bool is_error) {
+ Json j = obj();
+ j.set("type", Json("tool_result"));
+ j.set("tool_use_id", Json(std::move(tool_use_id)));
+ j.set("content", blocks_to_json(content));
+ if (is_error) j.set("is_error", Json(true));
+ return build(j);
+}
+ContentBlock ContentBlock::container_upload(std::string file_id) {
+ Json j = obj();
+ j.set("type", Json("container_upload"));
+ j.set("file_id", Json(std::move(file_id)));
+ return build(j);
+}
+
+ContentBlock& ContentBlock::cache(const CacheControl& cc) {
+ json_.set("cache_control", cc.to_json());
+ return *this;
+}
+ContentBlock& ContentBlock::citations_enabled(bool enabled) {
+ if (type_ != "document" && type_ != "search_result" && type_ != "text") bad("citations apply to document, search_result and text blocks");
+ Json c = obj();
+ c.set("enabled", Json(enabled));
+ json_.set("citations", c);
+ return *this;
+}
+ContentBlock& ContentBlock::title(std::string t) {
+ if (type_ != "document") bad("title applies to document blocks");
+ json_.set("title", Json(std::move(t)));
+ return *this;
+}
+ContentBlock& ContentBlock::context(std::string c) {
+ if (type_ != "document") bad("context applies to document blocks");
+ json_.set("context", Json(std::move(c)));
+ return *this;
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/content.h b/src/anthropic/core/content.h
new file mode 100644
index 0000000..e00f49b
--- /dev/null
+++ b/src/anthropic/core/content.h
@@ -0,0 +1,104 @@
+#pragma once
+
+// Request content blocks: text, image, document, search_result, thinking,
+// redacted_thinking, tool_use, tool_result, server tool blocks, MCP blocks,
+// container_upload, compaction, tool_addition, tool_removal, fallback.
+// Builders cover the common shapes; from_json() accepts every block type of
+// the SDK's content block param union, checked against the schema table
+// (required fields present, no unknown fields, nested shapes for cache_control,
+// image and document sources). Blocks echoed back from a response keep every
+// field they came with.
+
+#include
+#include
+
+#include "anthropic/core/version.h"
+#include "clients/body/json.h"
+
+namespace molo::anthropic::core {
+
+using Json = clients::body::Json;
+
+enum class CacheTtl { k5m, k1h };
+
+// {"type":"ephemeral","ttl":"5m"|"1h"} (prompt caching).
+struct CacheControl {
+ CacheTtl ttl = CacheTtl::k5m;
+ bool explicit_ttl = false; // false: ttl omitted (default 5m)
+ static CacheControl five_minutes() { return CacheControl{CacheTtl::k5m, true}; }
+ static CacheControl one_hour() { return CacheControl{CacheTtl::k1h, true}; }
+ static CacheControl default_ttl() { return CacheControl{}; }
+ Json to_json() const;
+ // Strict parse of {"type":"ephemeral","ttl"?}.
+ static CacheControl from_json(const Json& j);
+};
+
+struct BlockSchema {
+ const char* type; // wire "type"
+ const char* required; // comma list
+ const char* optional; // comma list
+ const char* beta; // anthropic-beta that must accompany it, "" for none
+ bool ga; // part of the GA (non-beta) content block union
+};
+
+const BlockSchema* find_block_schema(const std::string& type);
+std::size_t block_schema_count();
+const BlockSchema& block_schema_at(std::size_t index);
+// Response block types the API may return (and accepts back verbatim).
+bool is_response_block_type(const std::string& type);
+
+class ContentBlock {
+ public:
+ // --- text, images, documents -------------------------------------------
+ static ContentBlock text(std::string text);
+ static ContentBlock image_base64(const std::string& media_type, std::string data);
+ static ContentBlock image_url(std::string url);
+ static ContentBlock image_file(std::string file_id);
+ static ContentBlock document_pdf_base64(std::string data);
+ static ContentBlock document_pdf_url(std::string url);
+ static ContentBlock document_text(std::string text);
+ static ContentBlock document_content(std::vector blocks); // custom content document
+ static ContentBlock document_file(std::string file_id);
+ static ContentBlock search_result(std::string source, std::string title,
+ std::vector text_blocks);
+ // --- thinking ------------------------------------------------------------
+ // Thinking blocks must be replayed exactly as received (signature included).
+ static ContentBlock thinking(std::string thinking, std::string signature);
+ static ContentBlock redacted_thinking(std::string data);
+ // --- tools -----------------------------------------------------------------
+ static ContentBlock tool_use(std::string id, std::string name, Json input);
+ static ContentBlock tool_result(std::string tool_use_id, std::string content, bool is_error = false);
+ static ContentBlock tool_result_blocks(std::string tool_use_id, std::vector content,
+ bool is_error = false);
+ static ContentBlock container_upload(std::string file_id);
+ // --- generic -----------------------------------------------------------------
+ // `echo` = a block that came from a response: all fields kept, type must be
+ // a response block type. Otherwise the schema table is enforced.
+ static ContentBlock from_json(const Json& j, bool echo = false);
+
+ // --- modifiers (return *this) -----------------------------------------------------
+ ContentBlock& cache(const CacheControl& cc);
+ // citations: {"enabled":true} on document and search_result blocks.
+ ContentBlock& citations_enabled(bool enabled = true);
+ ContentBlock& title(std::string title); // document
+ ContentBlock& context(std::string context); // document
+
+ const std::string& type() const { return type_; }
+ const Json& json() const { return json_; }
+ bool echo() const { return echo_; }
+
+ private:
+ ContentBlock(std::string type, Json json, bool echo) : type_(std::move(type)), json_(std::move(json)), echo_(echo) {}
+ std::string type_;
+ Json json_;
+ bool echo_ = false;
+};
+
+// Validates one block against the schema table. Throws ApiError::invalid.
+void validate_block(const Json& block, bool echo);
+// Number of cache_control objects anywhere inside `j` (objects named
+// "cache_control" with a non-null value).
+std::size_t count_cache_controls(const Json& j);
+Json blocks_to_json(const std::vector& blocks);
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/errors.cpp b/src/anthropic/core/errors.cpp
new file mode 100644
index 0000000..53fca5f
--- /dev/null
+++ b/src/anthropic/core/errors.cpp
@@ -0,0 +1,142 @@
+#include "anthropic/core/errors.h"
+
+#include
+
+#include "anthropic/core/util.h"
+
+namespace molo::anthropic::core {
+
+// ERRORS-BEGIN (documented types and statuses, api/errors)
+static const ErrorInfo kErrors[] = {
+ {ErrorKind::kInvalidRequest, "invalid_request_error", 400},
+ {ErrorKind::kAuthentication, "authentication_error", 401},
+ {ErrorKind::kBilling, "billing_error", 402},
+ {ErrorKind::kPermission, "permission_error", 403},
+ {ErrorKind::kNotFound, "not_found_error", 404},
+ {ErrorKind::kConflict, "conflict_error", 409},
+ {ErrorKind::kRequestTooLarge, "request_too_large", 413},
+ {ErrorKind::kRateLimit, "rate_limit_error", 429},
+ {ErrorKind::kApi, "api_error", 500},
+ {ErrorKind::kTimeout, "timeout_error", 504},
+ {ErrorKind::kOverloaded, "overloaded_error", 529},
+ {ErrorKind::kNotConfigured, "NOT_CONFIGURED", 0},
+ {ErrorKind::kInvalidArgument, "INVALID_ARGUMENT", 0},
+ {ErrorKind::kBadResponse, "BAD_RESPONSE", 0},
+ {ErrorKind::kUnknown, "UNKNOWN", 0},
+};
+// ERRORS-END
+
+const ErrorInfo& error_info(ErrorKind kind) {
+ for (const ErrorInfo& e : kErrors)
+ if (e.kind == kind) return e;
+ return kErrors[sizeof(kErrors) / sizeof(kErrors[0]) - 1];
+}
+
+std::size_t error_kind_count() { return sizeof(kErrors) / sizeof(kErrors[0]); }
+const ErrorInfo& error_info_at(std::size_t index) { return kErrors[index]; }
+
+ErrorKind classify_error(const std::string& type, int http_status) {
+ for (const ErrorInfo& e : kErrors)
+ if (type == e.type) return e.kind;
+ switch (http_status) {
+ case 400: return ErrorKind::kInvalidRequest;
+ case 401: return ErrorKind::kAuthentication;
+ case 402: return ErrorKind::kBilling;
+ case 403: return ErrorKind::kPermission;
+ case 404: return ErrorKind::kNotFound;
+ case 409: return ErrorKind::kConflict;
+ case 413: return ErrorKind::kRequestTooLarge;
+ case 429: return ErrorKind::kRateLimit;
+ case 504: return ErrorKind::kTimeout;
+ case 529: return ErrorKind::kOverloaded;
+ default: break;
+ }
+ if (http_status >= 500) return ErrorKind::kApi;
+ if (http_status >= 400) return ErrorKind::kInvalidRequest; // "other 4XX" per api/errors
+ return ErrorKind::kUnknown;
+}
+
+namespace {
+
+std::optional to_long(const std::optional& v) {
+ if (!v || v->empty()) return std::nullopt;
+ char* end = nullptr;
+ long n = std::strtol(v->c_str(), &end, 10);
+ if (end == v->c_str()) return std::nullopt;
+ return n;
+}
+
+std::optional to_double(const std::optional& v) {
+ if (!v || v->empty()) return std::nullopt;
+ char* end = nullptr;
+ double n = std::strtod(v->c_str(), &end);
+ if (end == v->c_str() || n < 0) return std::nullopt;
+ return n;
+}
+
+RateLimitWindow window(const clients::HeaderMap& h, const std::string& prefix) {
+ RateLimitWindow w;
+ w.limit = to_long(h.get(prefix + "-limit"));
+ w.remaining = to_long(h.get(prefix + "-remaining"));
+ w.reset = h.get_or(prefix + "-reset", "");
+ return w;
+}
+
+} // namespace
+
+bool RateLimits::any() const {
+ return requests.present() || tokens.present() || input_tokens.present() ||
+ output_tokens.present() || priority_input_tokens.present() ||
+ priority_output_tokens.present() || retry_after_seconds || should_retry ||
+ !request_id.empty() || !organization_id.empty();
+}
+
+RateLimits parse_rate_limits(const clients::HeaderMap& h) {
+ RateLimits r;
+ r.requests = window(h, "anthropic-ratelimit-requests");
+ r.tokens = window(h, "anthropic-ratelimit-tokens");
+ r.input_tokens = window(h, "anthropic-ratelimit-input-tokens");
+ r.output_tokens = window(h, "anthropic-ratelimit-output-tokens");
+ r.priority_input_tokens = window(h, "anthropic-priority-input-tokens");
+ r.priority_output_tokens = window(h, "anthropic-priority-output-tokens");
+ r.retry_after_seconds = to_double(h.get("retry-after"));
+ if (!r.retry_after_seconds) {
+ if (auto ms = to_double(h.get("retry-after-ms"))) r.retry_after_seconds = *ms / 1000.0;
+ }
+ if (auto s = h.get("x-should-retry")) {
+ if (*s == "true") r.should_retry = true;
+ else if (*s == "false") r.should_retry = false;
+ }
+ r.request_id = h.get_or("request-id", "");
+ r.organization_id = h.get_or("anthropic-organization-id", "");
+ return r;
+}
+
+AnthropicError::AnthropicError(const llm::ApiError& base, RateLimits limits)
+ : llm::ApiError(base),
+ kind_(base.type() == "NOT_CONFIGURED" ? ErrorKind::kNotConfigured
+ : base.type() == "INVALID_ARGUMENT" ? ErrorKind::kInvalidArgument
+ : base.type() == "BAD_RESPONSE" ? ErrorKind::kBadResponse
+ : classify_error(base.type(), base.http_status())),
+ limits_(std::move(limits)) {}
+
+AnthropicError AnthropicError::from_event(const Json& event, std::string request_id) {
+ const Json* e = member(event, "error");
+ std::string type = e ? str_at(*e, "type", "api_error") : "api_error";
+ std::string message = e ? str_at(*e, "message", "stream error") : "stream error";
+ if (request_id.empty()) request_id = str_at(event, "request_id");
+ // The status of a mid-stream error is the documented one for its type.
+ int status = 0;
+ for (const ErrorInfo& info : kErrors)
+ if (type == info.type) status = info.status;
+ llm::ApiError base(kVendor, status ? status : 500, type, message, request_id);
+ return AnthropicError(base, RateLimits{});
+}
+
+bool AnthropicError::retryable() const noexcept {
+ if (limits_.should_retry) return *limits_.should_retry;
+ int s = http_status();
+ return s == 408 || s == 409 || s == 429 || s >= 500;
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/errors.h b/src/anthropic/core/errors.h
new file mode 100644
index 0000000..b8d8367
--- /dev/null
+++ b/src/anthropic/core/errors.h
@@ -0,0 +1,86 @@
+#pragma once
+
+// Error taxonomy (api/errors), rate limit headers (api/rate-limits) and the
+// typed AnthropicError thrown for every non-2xx answer and every error event
+// in a stream. AnthropicError derives from llm::ApiError, so code written
+// against the shared layer keeps working.
+
+#include
+#include
+
+#include "clients/headers.h"
+#include "llm/error.h"
+
+namespace molo::anthropic::core {
+
+enum class ErrorKind {
+ kInvalidRequest, // 400 invalid_request_error (also other 4xx)
+ kAuthentication, // 401 authentication_error
+ kBilling, // 402 billing_error
+ kPermission, // 403 permission_error
+ kNotFound, // 404 not_found_error
+ kConflict, // 409 conflict_error
+ kRequestTooLarge, // 413 request_too_large
+ kRateLimit, // 429 rate_limit_error
+ kApi, // 500 api_error
+ kTimeout, // 504 timeout_error
+ kOverloaded, // 529 overloaded_error
+ kNotConfigured, // local: no credential
+ kInvalidArgument, // local: input rejected before any traffic
+ kBadResponse, // local: answer could not be read
+ kUnknown,
+};
+
+struct ErrorInfo {
+ ErrorKind kind;
+ const char* type; // wire value, or local code
+ int status; // documented HTTP status, 0 for local kinds
+};
+
+const ErrorInfo& error_info(ErrorKind kind);
+// Wire type first (documented values), then the status as fallback.
+ErrorKind classify_error(const std::string& type, int http_status);
+std::size_t error_kind_count();
+const ErrorInfo& error_info_at(std::size_t index);
+
+// One window of a rate limit (requests, tokens, input tokens, ...).
+struct RateLimitWindow {
+ std::optional limit;
+ std::optional remaining;
+ std::string reset; // RFC 3339, as sent
+ bool present() const { return limit || remaining || !reset.empty(); }
+};
+
+struct RateLimits {
+ RateLimitWindow requests;
+ RateLimitWindow tokens;
+ RateLimitWindow input_tokens;
+ RateLimitWindow output_tokens;
+ RateLimitWindow priority_input_tokens; // Priority Tier only
+ RateLimitWindow priority_output_tokens; // Priority Tier only
+ std::optional retry_after_seconds; // retry-after, or retry-after-ms / 1000
+ std::optional should_retry; // x-should-retry
+ std::string request_id; // request-id
+ std::string organization_id; // anthropic-organization-id
+ bool any() const;
+};
+
+RateLimits parse_rate_limits(const clients::HeaderMap& headers);
+
+class AnthropicError : public llm::ApiError {
+ public:
+ AnthropicError(const llm::ApiError& base, RateLimits limits);
+ // Builds the error of a stream `error` event: {"type":"error","error":{...}}.
+ static AnthropicError from_event(const clients::body::Json& event, std::string request_id = "");
+
+ ErrorKind kind() const noexcept { return kind_; }
+ const RateLimits& rate_limits() const noexcept { return limits_; }
+ // The SDK retry rule: x-should-retry wins, else 408, 409, 429 and >= 500.
+ bool retryable() const noexcept;
+
+ private:
+ ErrorKind kind_;
+ RateLimits limits_;
+};
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/files.cpp b/src/anthropic/core/files.cpp
new file mode 100644
index 0000000..396199b
--- /dev/null
+++ b/src/anthropic/core/files.cpp
@@ -0,0 +1,68 @@
+#include "anthropic/core/files.h"
+
+#include "anthropic/core/util.h"
+#include "clients/body/form.h"
+
+namespace molo::anthropic::core {
+
+FileMeta FileMeta::parse(const Json& j) {
+ FileMeta f;
+ f.raw = j;
+ f.id = str_at(j, "id");
+ f.filename = str_at(j, "filename");
+ f.mime_type = str_at(j, "mime_type");
+ f.created_at = str_at(j, "created_at");
+ f.expires_at = str_at(j, "expires_at");
+ f.size_bytes = num_at(j, "size_bytes");
+ f.downloadable = bool_at(j, "downloadable");
+ return f;
+}
+
+FileMeta Files::upload(const std::string& filename, const std::string& data, const std::string& mime_type,
+ long expires_in_seconds) {
+ return session().guarded([&] {
+ if (filename.empty() || filename.size() > CoreCaps::kMaxFilenameChars) bad("filename must be 1..500 chars");
+ if (filename.find_first_of("/\\\"\r\n") != std::string::npos) bad("filename must not contain path or quote characters");
+ if (data.empty() || data.size() > CoreCaps::kMaxFileBytes) bad("file must be 1 byte to 500 MB");
+ if (mime_type.empty() || mime_type.size() > 255) bad("mime_type must be 1..255 chars");
+ if (expires_in_seconds != 0 && (expires_in_seconds < CoreCaps::kMinFileExpirySeconds ||
+ expires_in_seconds > CoreCaps::kMaxFileExpirySeconds))
+ bad("expires_in_seconds must be 3600..7776000");
+ clients::body::MultipartBody form;
+ form.add_file("file", filename, mime_type, data);
+ if (expires_in_seconds) form.add_text("expires_in_seconds", std::to_string(expires_in_seconds));
+ return FileMeta::parse(
+ client().post_multipart(render(Call::kFilesUpload), form, session().headers(betas_)));
+ });
+}
+
+Page Files::list(int limit, const std::string& page, const std::vector& ids,
+ const std::string& scope_id) {
+ check_limit(limit);
+ if (!ids.empty() && (limit || !page.empty())) bad("ids is exclusive with page and limit");
+ if (ids.size() > CoreCaps::kMaxFileIds) bad("ids takes at most 100 entries");
+ for (const std::string& i : ids) check_id("file", i);
+ Query q;
+ if (limit) q.add_int("limit", limit);
+ if (!page.empty()) q.add("page", page);
+ q.add_each("ids", ids);
+ if (!scope_id.empty()) {
+ check_id("scope", scope_id);
+ q.add("scope_id", scope_id);
+ }
+ return Page::parse(call_json(Call::kFilesList, "", "", q.str()));
+}
+
+FileMeta Files::metadata(const std::string& id) { return FileMeta::parse(call_json(Call::kFilesRetrieveMetadata, id)); }
+
+FileContent Files::download(const std::string& id) {
+ return session().guarded([&] {
+ llm::RawResponse raw = client().request_raw(method_of(Call::kFilesDownload), render(Call::kFilesDownload, id),
+ nullptr, "", session().headers(betas_));
+ return FileContent{raw.body, raw.content_type};
+ });
+}
+
+Json Files::destroy(const std::string& id) { return call_json(Call::kFilesDelete, id); }
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/files.h b/src/anthropic/core/files.h
new file mode 100644
index 0000000..45e8d77
--- /dev/null
+++ b/src/anthropic/core/files.h
@@ -0,0 +1,41 @@
+#pragma once
+
+// Files API: upload (multipart), list, metadata, download, delete.
+// GA at /v1/files; `with_betas({Beta::kFilesApi20250414})` keeps sending the
+// legacy header, and scope_id (beta) filters by scope.
+
+#include
+#include
+
+#include "anthropic/core/page.h"
+#include "anthropic/core/session.h"
+
+namespace molo::anthropic::core {
+
+struct FileMeta {
+ std::string id, filename, mime_type, created_at, expires_at;
+ long size_bytes = 0;
+ bool downloadable = false;
+ Json raw;
+ static FileMeta parse(const Json& j);
+};
+
+struct FileContent {
+ std::string bytes;
+ std::string content_type;
+};
+
+class Files : public CoreService {
+ public:
+ explicit Files(std::shared_ptr session) : CoreService(std::move(session)) {}
+ // expires_in_seconds 0: no expiry; else 3600..7776000.
+ FileMeta upload(const std::string& filename, const std::string& data, const std::string& mime_type,
+ long expires_in_seconds = 0);
+ Page list(int limit = 0, const std::string& page = "", const std::vector& ids = {},
+ const std::string& scope_id = "");
+ FileMeta metadata(const std::string& file_id);
+ FileContent download(const std::string& file_id);
+ Json destroy(const std::string& file_id); // explicit delete
+};
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/messages.cpp b/src/anthropic/core/messages.cpp
new file mode 100644
index 0000000..2f3478c
--- /dev/null
+++ b/src/anthropic/core/messages.cpp
@@ -0,0 +1,81 @@
+#include "anthropic/core/messages.h"
+
+#include "anthropic/core/calls.h"
+#include "anthropic/core/util.h"
+
+namespace molo::anthropic::core {
+
+namespace {
+Json parse_body(const llm::RawResponse& raw) {
+ try {
+ return Json::parse(raw.body);
+ } catch (const std::exception& e) {
+ throw llm::ApiError(kVendor, 502, "BAD_RESPONSE", e.what());
+ }
+}
+} // namespace
+
+MessageResult Messages::create(const MessageRequest& request) {
+ return session().guarded([&] {
+ request.validate(session().version());
+ MessageResult out;
+ out.request_body = request.to_json(false, session().version());
+ out.betas = request.effective_betas();
+ std::string body = out.request_body.dump();
+ llm::RawResponse raw = client().request_raw(
+ method_of(Call::kMessagesCreate), render(Call::kMessagesCreate), &body, "application/json",
+ session().headers(out.betas, request.workspace_id, request.user_profile_id));
+ out.message = Message::parse(parse_body(raw));
+ out.limits = parse_rate_limits(raw.headers);
+ return out;
+ });
+}
+
+StreamResult Messages::stream(const MessageRequest& request, const EventSink& sink) {
+ return session().guarded([&] {
+ request.validate(session().version());
+ StreamResult out;
+ out.betas = request.effective_betas();
+ Json body = request.to_json(true, session().version());
+ StreamAccumulator acc;
+ bool stopped_by_sink = false;
+ client().stream(
+ render(Call::kMessagesCreate), body,
+ [&](const llm::SseEvent& e) {
+ StreamEvent ev = StreamEvent::from_sse(e);
+ acc.accept(ev);
+ if (sink && !sink(ev)) {
+ stopped_by_sink = true;
+ return false;
+ }
+ return true;
+ },
+ session().headers(out.betas, request.workspace_id, request.user_profile_id));
+ out.events = acc.events();
+ if (stopped_by_sink && !acc.complete()) {
+ out.message = acc.snapshot();
+ out.complete = false;
+ } else {
+ out.message = acc.finish();
+ out.complete = true;
+ }
+ return out;
+ });
+}
+
+TokenCount Messages::count_tokens(const MessageRequest& request) {
+ return session().guarded([&] {
+ if (request.model.empty() || request.messages.empty()) bad("model and messages are required");
+ BetaSet betas = request.effective_betas();
+ Json body = request.to_count_tokens_json(session().version());
+ Json doc = client().post(render(Call::kMessagesCountTokens), body,
+ session().headers(betas, request.workspace_id, request.user_profile_id));
+ TokenCount t;
+ t.raw = doc;
+ t.input_tokens = num_at(doc, "input_tokens", -1);
+ if (t.input_tokens < 0) throw llm::ApiError(kVendor, 502, "BAD_RESPONSE", "count_tokens answer has no input_tokens");
+ return t;
+ });
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/messages.h b/src/anthropic/core/messages.h
new file mode 100644
index 0000000..43b8db3
--- /dev/null
+++ b/src/anthropic/core/messages.h
@@ -0,0 +1,44 @@
+#pragma once
+
+// Messages service: create, stream, count_tokens.
+
+#include
+
+#include "anthropic/core/session.h"
+#include "anthropic/core/stream.h"
+
+namespace molo::anthropic::core {
+
+struct MessageResult {
+ Message message;
+ RateLimits limits; // headers of the answer
+ BetaSet betas; // what was sent (explicit plus derived)
+ Json request_body; // what was sent
+};
+
+struct TokenCount {
+ long input_tokens = 0;
+ Json raw;
+};
+
+struct StreamResult {
+ Message message;
+ bool complete = false; // false: the sink stopped the stream early
+ std::size_t events = 0;
+ BetaSet betas;
+};
+
+class Messages : public CoreService {
+ public:
+ using EventSink = std::function; // false stops the stream
+
+ explicit Messages(std::shared_ptr session) : CoreService(std::move(session)) {}
+
+ MessageResult create(const MessageRequest& request);
+ // Streams; every event goes to `sink` after it was applied to the
+ // accumulator. Throws AnthropicError on an error event.
+ StreamResult stream(const MessageRequest& request, const EventSink& sink = nullptr);
+ TokenCount count_tokens(const MessageRequest& request);
+};
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/models.cpp b/src/anthropic/core/models.cpp
new file mode 100644
index 0000000..e3f9e52
--- /dev/null
+++ b/src/anthropic/core/models.cpp
@@ -0,0 +1,66 @@
+#include "anthropic/core/models.h"
+
+#include "anthropic/core/util.h"
+
+namespace molo::anthropic::core {
+
+ModelInfo ModelInfo::parse(const Json& j) {
+ ModelInfo m;
+ m.raw = j;
+ m.id = str_at(j, "id");
+ m.display_name = str_at(j, "display_name");
+ m.created_at = str_at(j, "created_at");
+ m.lifecycle = str_at(j, "lifecycle");
+ m.line = str_at(j, "line");
+ m.deprecated_at = str_at(j, "deprecated_at");
+ m.retires_at = str_at(j, "retires_at");
+ m.max_input_tokens = num_at(j, "max_input_tokens");
+ m.max_tokens = num_at(j, "max_tokens");
+ if (const Json* c = member(j, "capabilities")) m.capabilities = *c;
+ return m;
+}
+
+bool ModelInfo::supports(const std::string& path) const {
+ const Json* cur = &capabilities;
+ std::size_t pos = 0;
+ while (cur && cur->is_object() && pos <= path.size()) {
+ std::size_t dot = path.find('.', pos);
+ cur = cur->find(path.substr(pos, dot == std::string::npos ? dot : dot - pos));
+ if (dot == std::string::npos) break;
+ pos = dot + 1;
+ }
+ return cur && cur->is_object() && bool_at(*cur, "supported");
+}
+
+Page Models::list(int limit, const std::string& after_id, const std::string& before_id,
+ const std::vector& lifecycle) {
+ check_limit(limit);
+ if (!after_id.empty() && !before_id.empty()) bad("after_id and before_id are exclusive");
+ if (lifecycle.size() > static_cast(CoreCaps::kMaxLifecycleFilter)) bad("lifecycle takes up to 3 values");
+ for (const std::string& l : lifecycle)
+ if (l != "active" && l != "deprecated" && l != "retired") bad("lifecycle must be active, deprecated or retired");
+ Query q;
+ if (limit) q.add_int("limit", limit);
+ if (!after_id.empty()) {
+ check_id("after_id", after_id);
+ q.add("after_id", after_id);
+ }
+ if (!before_id.empty()) {
+ check_id("before_id", before_id);
+ q.add("before_id", before_id);
+ }
+ q.add_each("lifecycle", lifecycle);
+ return Page::parse(call_json(Call::kModelsList, "", "", q.str()));
+}
+
+std::vector Models::list_models(int limit, const std::vector& lifecycle) {
+ std::vector out;
+ for (const Json& j : list(limit, "", "", lifecycle).data) out.push_back(ModelInfo::parse(j));
+ return out;
+}
+
+ModelInfo Models::retrieve(const std::string& id) {
+ return ModelInfo::parse(call_json(Call::kModelsRetrieve, id));
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/models.h b/src/anthropic/core/models.h
new file mode 100644
index 0000000..f145173
--- /dev/null
+++ b/src/anthropic/core/models.h
@@ -0,0 +1,41 @@
+#pragma once
+
+// Models API: list, retrieve, capabilities.
+
+#include
+#include
+
+#include "anthropic/core/page.h"
+#include "anthropic/core/session.h"
+
+namespace molo::anthropic::core {
+
+struct ModelInfo {
+ std::string id;
+ std::string display_name;
+ std::string created_at;
+ std::string lifecycle; // active | deprecated | retired
+ std::string line; // haiku | sonnet | opus | fable | mythos | ""
+ std::string deprecated_at, retires_at;
+ long max_input_tokens = 0;
+ long max_tokens = 0;
+ Json capabilities; // null when the API sent null
+ Json raw;
+ // supports("thinking.types.adaptive"), supports("effort.xhigh"),
+ // supports("batch"): follows the dotted path to {"supported":bool}.
+ // False when the path is absent or null.
+ bool supports(const std::string& path) const;
+ static ModelInfo parse(const Json& j);
+};
+
+class Models : public CoreService {
+ public:
+ explicit Models(std::shared_ptr session) : CoreService(std::move(session)) {}
+ // lifecycle: up to 3 of active, deprecated, retired.
+ Page list(int limit = 0, const std::string& after_id = "", const std::string& before_id = "",
+ const std::vector& lifecycle = {});
+ std::vector list_models(int limit = 0, const std::vector& lifecycle = {});
+ ModelInfo retrieve(const std::string& id_or_alias);
+};
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/options.cpp b/src/anthropic/core/options.cpp
new file mode 100644
index 0000000..eb4f30b
--- /dev/null
+++ b/src/anthropic/core/options.cpp
@@ -0,0 +1,204 @@
+#include "anthropic/core/options.h"
+
+#include "anthropic/core/caps.h"
+#include "anthropic/core/util.h"
+#include "llm/api_client.h"
+
+namespace molo::anthropic::core {
+
+ThinkingConfig ThinkingConfig::enabled(int budget) {
+ ThinkingConfig t;
+ t.type = Type::kEnabled;
+ t.budget_tokens = budget;
+ return t;
+}
+ThinkingConfig ThinkingConfig::disabled() { return ThinkingConfig{}; }
+ThinkingConfig ThinkingConfig::adaptive() {
+ ThinkingConfig t;
+ t.type = Type::kAdaptive;
+ return t;
+}
+ThinkingConfig ThinkingConfig::between_tools() {
+ ThinkingConfig t;
+ t.type = Type::kBetweenTools;
+ return t;
+}
+
+void ThinkingConfig::validate(int max_tokens) const {
+ if (type == Type::kEnabled) {
+ if (budget_tokens < CoreCaps::kMinThinkingBudget) bad("thinking budget_tokens must be at least 1024");
+ if (max_tokens > 0 && budget_tokens >= max_tokens) bad("thinking budget_tokens must be below max_tokens");
+ }
+ if (display != Display::kDefault && type != Type::kEnabled && type != Type::kAdaptive)
+ bad("thinking display applies to enabled and adaptive thinking only");
+ if (!block_binding_prefix_mismatch.empty() && type != Type::kEnabled && type != Type::kAdaptive)
+ bad("block_binding applies to enabled and adaptive thinking only");
+}
+
+Json ThinkingConfig::to_json() const {
+ Json j = obj();
+ switch (type) {
+ case Type::kEnabled:
+ j.set("type", Json("enabled"));
+ j.set("budget_tokens", Json(budget_tokens));
+ break;
+ case Type::kDisabled: j.set("type", Json("disabled")); break;
+ case Type::kAdaptive: j.set("type", Json("adaptive")); break;
+ case Type::kBetweenTools: j.set("type", Json("between_tools")); break;
+ }
+ if (display != Display::kDefault) {
+ j.set("display", Json(display == Display::kSummarized ? "summarized"
+ : display == Display::kOmitted ? "omitted"
+ : "updates"));
+ }
+ if (!block_binding_prefix_mismatch.empty()) {
+ Json b = obj();
+ b.set("prefix_mismatch_behavior", Json(block_binding_prefix_mismatch));
+ j.set("block_binding", b);
+ }
+ return j;
+}
+
+BetaSet ThinkingConfig::required_betas() const {
+ BetaSet b;
+ if (display == Display::kUpdates) b.add(Beta::kThinkingDisplayUpdates20260818);
+ if (!block_binding_prefix_mismatch.empty()) b.add(Beta::kThinkingBindingControls20260801);
+ return b;
+}
+
+void OutputConfig::validate() const {
+ if (!effort.empty() && effort != "low" && effort != "medium" && effort != "high" && effort != "xhigh" &&
+ effort != "max")
+ bad("effort must be low, medium, high, xhigh or max");
+ if (!format.is_null() && !format.is_object()) bad("output format schema must be an object");
+ if (task_budget_total && *task_budget_total <= 0) bad("task_budget total must be positive");
+ if (task_budget_remaining && !task_budget_total) bad("task_budget remaining needs total");
+}
+
+Json OutputConfig::to_json() const {
+ validate();
+ Json j = obj();
+ if (!effort.empty()) j.set("effort", Json(effort));
+ if (!format.is_null()) {
+ Json f = obj();
+ f.set("type", Json("json_schema"));
+ f.set("schema", format);
+ j.set("format", f);
+ }
+ if (task_budget_total) {
+ Json t = obj();
+ t.set("type", Json("tokens"));
+ t.set("total", Json(*task_budget_total));
+ if (task_budget_remaining) t.set("remaining", Json(*task_budget_remaining));
+ j.set("task_budget", t);
+ }
+ return j;
+}
+
+BetaSet OutputConfig::required_betas() const {
+ BetaSet b;
+ if (task_budget_total) b.add(Beta::kTaskBudgets20260313);
+ return b;
+}
+
+ContextEdit ContextEdit::clear_tool_uses(Json o) { return ContextEdit{"clear_tool_uses_20250919", std::move(o)}; }
+ContextEdit ContextEdit::clear_thinking(Json o) { return ContextEdit{"clear_thinking_20251015", std::move(o)}; }
+ContextEdit ContextEdit::compact(Json o) { return ContextEdit{"compact_20260112", std::move(o)}; }
+
+Json ContextEdit::to_json() const {
+ if (type != "clear_tool_uses_20250919" && type != "clear_thinking_20251015" && type != "compact_20260112")
+ bad("unknown context edit type '" + type + "'");
+ if (!options.is_object()) bad("context edit options must be an object");
+ Json j = options;
+ j.set("type", Json(type));
+ return j;
+}
+
+void ContextManagement::validate() const {
+ if (edits.empty() || edits.size() > CoreCaps::kMaxContextEdits) bad("context_management needs 1..16 edits");
+ for (const ContextEdit& e : edits) e.to_json();
+}
+
+Json ContextManagement::to_json() const {
+ validate();
+ Json a = arr();
+ for (const ContextEdit& e : edits) a.push(e.to_json());
+ Json j = obj();
+ j.set("edits", a);
+ return j;
+}
+
+BetaSet ContextManagement::required_betas() const {
+ BetaSet b;
+ b.add(Beta::kContextManagement20250627);
+ for (const ContextEdit& e : edits)
+ if (e.type == "compact_20260112") b.add(Beta::kCompact20260112);
+ return b;
+}
+
+Json CompactionConfig::to_json() const {
+ Json j = obj();
+ j.set("type", Json("summarize"));
+ if (!instructions.empty()) j.set("instructions", Json(instructions));
+ return j;
+}
+
+void McpServer::validate() const {
+ if (!slug_ok(name, CoreCaps::kMaxToolNameChars)) bad("mcp server name must be 1..128 of A-Za-z0-9_-");
+ if (url.rfind("https://", 0) != 0 || url.size() > 2048) bad("mcp server url must start with https://");
+}
+
+Json McpServer::to_json() const {
+ validate();
+ Json j = obj();
+ j.set("type", Json("url"));
+ j.set("name", Json(name));
+ j.set("url", Json(url));
+ if (!authorization_token.empty()) j.set("authorization_token", Json(authorization_token));
+ if (!allowed_tools.empty() || tools_enabled) {
+ Json t = obj();
+ if (!allowed_tools.empty()) t.set("allowed_tools", json_strings(allowed_tools));
+ if (tools_enabled) t.set("enabled", Json(*tools_enabled));
+ j.set("tool_configuration", t);
+ }
+ return j;
+}
+
+void Container::validate() const {
+ if (!id.empty() && !llm::Service::valid_id(id)) bad("container id is not valid");
+ if (skills.size() > CoreCaps::kMaxSkillsPerRequest) bad("at most 20 skills per request");
+ for (const SkillRef& s : skills) {
+ if (s.type != "anthropic" && s.type != "custom") bad("skill type must be anthropic or custom");
+ if (!llm::Service::valid_id(s.skill_id)) bad("skill_id is not valid");
+ if (!s.version.empty() && !llm::Service::valid_id(s.version)) bad("skill version is not valid");
+ }
+}
+
+Json Container::to_json() const {
+ validate();
+ if (skills.empty()) return Json(id);
+ Json j = obj();
+ if (!id.empty()) j.set("id", Json(id));
+ Json a = arr();
+ for (const SkillRef& s : skills) {
+ Json o = obj();
+ o.set("type", Json(s.type));
+ o.set("skill_id", Json(s.skill_id));
+ if (!s.version.empty()) o.set("version", Json(s.version));
+ a.push(o);
+ }
+ j.set("skills", a);
+ return j;
+}
+
+Json Fallback::to_json() const {
+ if (model.empty()) bad("fallback needs a model");
+ if (!speed.empty() && speed != "standard" && speed != "fast") bad("fallback speed must be standard or fast");
+ Json j = obj();
+ j.set("model", Json(model));
+ if (max_tokens) j.set("max_tokens", Json(*max_tokens));
+ if (!speed.empty()) j.set("speed", Json(speed));
+ return j;
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/options.h b/src/anthropic/core/options.h
new file mode 100644
index 0000000..cc34108
--- /dev/null
+++ b/src/anthropic/core/options.h
@@ -0,0 +1,98 @@
+#pragma once
+
+// Typed request options of Messages: thinking, output config (effort,
+// structured output format, task budget), context management, compaction,
+// MCP servers, container (code execution, skills), server side fallbacks.
+// Each class validates itself, renders its JSON and lists the beta headers it
+// needs.
+
+#include
+#include
+#include
+
+#include "anthropic/core/beta.h"
+#include "anthropic/core/content.h"
+
+namespace molo::anthropic::core {
+
+struct ThinkingConfig {
+ enum class Type { kEnabled, kDisabled, kAdaptive, kBetweenTools };
+ enum class Display { kDefault, kSummarized, kOmitted, kUpdates };
+ Type type = Type::kDisabled;
+ int budget_tokens = 0; // kEnabled: >= 1024
+ Display display = Display::kDefault;
+ std::string block_binding_prefix_mismatch; // block_binding.prefix_mismatch_behavior, "" none
+ static ThinkingConfig enabled(int budget_tokens);
+ static ThinkingConfig disabled();
+ static ThinkingConfig adaptive();
+ static ThinkingConfig between_tools();
+ ThinkingConfig& with_display(Display d) { display = d; return *this; }
+ void validate(int max_tokens) const;
+ Json to_json() const;
+ BetaSet required_betas() const;
+};
+
+struct OutputConfig {
+ std::string effort; // "", low, medium, high, xhigh, max
+ Json format; // null or the JSON schema object (output_config.format.schema)
+ std::optional task_budget_total;
+ std::optional task_budget_remaining;
+ bool empty() const { return effort.empty() && format.is_null() && !task_budget_total; }
+ void validate() const;
+ Json to_json() const;
+ BetaSet required_betas() const;
+};
+
+// One entry of context_management.edits.
+struct ContextEdit {
+ std::string type; // clear_tool_uses_20250919, clear_thinking_20251015, compact_20260112
+ Json options = Json::object(); // other fields of the edit, passed through
+ static ContextEdit clear_tool_uses(Json options = Json::object());
+ static ContextEdit clear_thinking(Json options = Json::object());
+ static ContextEdit compact(Json options = Json::object());
+ Json to_json() const;
+};
+
+struct ContextManagement {
+ std::vector edits;
+ void validate() const;
+ Json to_json() const;
+ BetaSet required_betas() const;
+};
+
+struct CompactionConfig { // top-level `compaction`: {"type":"summarize","instructions"?}
+ std::string instructions;
+ Json to_json() const;
+};
+
+struct McpServer {
+ std::string name;
+ std::string url; // https://
+ std::string authorization_token;
+ std::vector allowed_tools;
+ std::optional tools_enabled;
+ void validate() const;
+ Json to_json() const;
+};
+
+struct SkillRef {
+ std::string type; // "anthropic" or "custom"
+ std::string skill_id;
+ std::string version; // optional
+};
+
+struct Container {
+ std::string id;
+ std::vector skills;
+ void validate() const;
+ Json to_json() const; // string form when only an id is set
+};
+
+struct Fallback {
+ std::string model;
+ std::optional max_tokens;
+ std::string speed; // "", standard, fast
+ Json to_json() const;
+};
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/page.cpp b/src/anthropic/core/page.cpp
new file mode 100644
index 0000000..de74277
--- /dev/null
+++ b/src/anthropic/core/page.cpp
@@ -0,0 +1,50 @@
+#include "anthropic/core/page.h"
+
+namespace molo::anthropic::core {
+
+std::string url_encode(const std::string& s) {
+ static const char* hex = "0123456789ABCDEF";
+ std::string out;
+ for (unsigned char c : s) {
+ if ((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c == '-' || c == '_' ||
+ c == '.' || c == '~') {
+ out += static_cast(c);
+ } else {
+ out += '%';
+ out += hex[c >> 4];
+ out += hex[c & 15];
+ }
+ }
+ return out;
+}
+
+Query& Query::add(const std::string& key, const std::string& value) {
+ if (value.size() > CoreCaps::kMaxHeaderValueChars) bad("query value too long");
+ text_ += text_.empty() ? "?" : "&";
+ text_ += url_encode(key) + "=" + url_encode(value);
+ return *this;
+}
+Query& Query::add_int(const std::string& key, long value) { return add(key, std::to_string(value)); }
+Query& Query::add_each(const std::string& key, const std::vector& values) {
+ for (const std::string& v : values) add(key, v);
+ return *this;
+}
+std::string Query::str() const { return text_; }
+
+Page Page::parse(const Json& j) {
+ Page p;
+ p.raw = j;
+ if (const Json* d = member(j, "data"); d && d->is_array()) p.data = d->as_array();
+ p.has_more = bool_at(j, "has_more");
+ p.first_id = str_at(j, "first_id");
+ p.last_id = str_at(j, "last_id");
+ p.next_page = str_at(j, "next_page");
+ if (!p.next_page.empty()) p.has_more = true;
+ return p;
+}
+
+void check_limit(int limit) {
+ if (limit != 0 && (limit < 1 || limit > CoreCaps::kMaxListLimit)) bad("limit must be 1..1000");
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/page.h b/src/anthropic/core/page.h
new file mode 100644
index 0000000..cab1152
--- /dev/null
+++ b/src/anthropic/core/page.h
@@ -0,0 +1,42 @@
+#pragma once
+
+// Query strings and list pages. Two paging shapes exist: cursor ids
+// (after_id/before_id with has_more, first_id, last_id: batches, models) and
+// opaque tokens (page/next_page: files, skills, user profiles). A walk that
+// hits its page cap reports truncated = true, never silently.
+
+#include
+#include
+
+#include "anthropic/core/caps.h"
+#include "anthropic/core/util.h"
+
+namespace molo::anthropic::core {
+
+std::string url_encode(const std::string& s);
+
+class Query {
+ public:
+ Query& add(const std::string& key, const std::string& value);
+ Query& add_int(const std::string& key, long value);
+ Query& add_each(const std::string& key, const std::vector& values); // repeated key
+ std::string str() const; // "" or "?a=b&c=d"
+ private:
+ std::string text_;
+};
+
+struct Page {
+ std::vector data;
+ bool has_more = false;
+ std::string first_id;
+ std::string last_id;
+ std::string next_page;
+ bool truncated = false; // set by walkers that stopped at the page cap
+ Json raw;
+ static Page parse(const Json& j);
+};
+
+// limit in [1, 1000] or 0 for "server default".
+void check_limit(int limit);
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/request.cpp b/src/anthropic/core/request.cpp
new file mode 100644
index 0000000..d8aa719
--- /dev/null
+++ b/src/anthropic/core/request.cpp
@@ -0,0 +1,307 @@
+#include "anthropic/core/request.h"
+
+#include "anthropic/core/caps.h"
+#include "anthropic/core/calls.h"
+#include "anthropic/core/util.h"
+#include "llm/api_client.h"
+
+namespace molo::anthropic::core {
+
+MessageParam MessageParam::user(std::string t) {
+ MessageParam m;
+ m.text = std::move(t);
+ return m;
+}
+MessageParam MessageParam::user(std::vector b) {
+ MessageParam m;
+ m.blocks = std::move(b);
+ return m;
+}
+MessageParam MessageParam::assistant(std::string t) {
+ MessageParam m = user(std::move(t));
+ m.role = Role::kAssistant;
+ return m;
+}
+MessageParam MessageParam::assistant(std::vector b) {
+ MessageParam m = user(std::move(b));
+ m.role = Role::kAssistant;
+ return m;
+}
+MessageParam MessageParam::system(std::string t) {
+ MessageParam m = user(std::move(t));
+ m.role = Role::kSystem;
+ return m;
+}
+MessageParam MessageParam::system(std::vector b) {
+ MessageParam m = user(std::move(b));
+ m.role = Role::kSystem;
+ return m;
+}
+
+Json MessageParam::to_json() const {
+ Json j = obj();
+ const char* r = role == Role::kUser ? "user" : role == Role::kAssistant ? "assistant" : "system";
+ j.set("role", Json(r));
+ if (blocks.empty()) {
+ if (text.empty() && role != Role::kSystem) bad(std::string(r) + " message has no content");
+ j.set("content", Json(text));
+ } else {
+ if (blocks.size() > CoreCaps::kMaxBlocksPerMessage) bad("too many content blocks in one message");
+ if (!text.empty()) bad("message has both text and blocks");
+ j.set("content", blocks_to_json(blocks));
+ }
+ if (!clear_at.empty()) {
+ if (role != Role::kSystem) bad("clear_at applies to system messages");
+ if (clear_at != "next_user_message" && clear_at != "never") bad("clear_at must be next_user_message or never");
+ j.set("clear_at", Json(clear_at));
+ }
+ if (!system_effort.empty()) {
+ if (role != Role::kSystem) bad("output_config applies to system messages");
+ OutputConfig oc;
+ oc.effort = system_effort;
+ j.set("output_config", oc.to_json());
+ }
+ return j;
+}
+
+BetaSet MessageParam::required_betas() const {
+ BetaSet b;
+ if (!clear_at.empty()) b.add(Beta::kMidConversationSystemClearAt20260821);
+ if (!system_effort.empty()) b.add(Beta::kMidConversationOutputConfig20260701);
+ for (const ContentBlock& c : blocks) {
+ const BlockSchema* s = find_block_schema(c.type());
+ if (s && *s->beta) b.add_name(s->beta);
+ }
+ return b;
+}
+
+void MessageRequest::validate(ApiVersion version) const {
+ const VersionInfo& vi = version_info(version);
+ if (model.empty() || model.size() > 256) bad("model is required (1..256 chars)");
+ if (!max_tokens_set) bad("max_tokens is required");
+ if (max_tokens < 0 || max_tokens > CoreCaps::kMaxMaxTokens) bad("max_tokens out of range");
+ if (messages.empty()) bad("messages is empty");
+ if (messages.size() > CoreCaps::kMaxMessages) bad("too many messages");
+ if (!system_text.empty() && !system_blocks.empty()) bad("system: set text or blocks, not both");
+ if (system_blocks.size() > CoreCaps::kMaxSystemBlocks) bad("too many system blocks");
+ for (const ContentBlock& b : system_blocks)
+ if (b.type() != "text") bad("system blocks must be text blocks");
+ if (tools.size() > CoreCaps::kMaxTools) bad("too many tools");
+ {
+ std::vector names;
+ for (const Tool& t : tools) {
+ if (t.name().empty()) continue;
+ for (const std::string& n : names)
+ if (n == t.name()) bad("duplicate tool name '" + n + "'");
+ names.push_back(t.name());
+ }
+ }
+ if (tool_choice) {
+ tool_choice->validate();
+ if (tools.empty() && tool_choice->kind != ToolChoice::Kind::kNone) bad("tool_choice needs tools");
+ if (tool_choice->kind == ToolChoice::Kind::kTool) {
+ bool found = false;
+ for (const Tool& t : tools) found = found || t.name() == tool_choice->name;
+ if (!found) bad("tool_choice names a tool that is not in tools");
+ }
+ }
+ if (thinking) thinking->validate(max_tokens);
+ output.validate();
+ if (stop_sequences.size() > CoreCaps::kMaxStopSequences) bad("too many stop_sequences");
+ for (const std::string& s : stop_sequences)
+ if (s.empty() || s.size() > CoreCaps::kMaxStopSequenceChars) bad("stop_sequence must be 1..1024 chars");
+ if (cache_control) cache_control->to_json();
+ if (container) container->validate();
+ if (context_management) context_management->validate();
+ if (!diagnostics_previous_message_id.empty() && !llm::Service::valid_id(diagnostics_previous_message_id))
+ bad("diagnostics previous_message_id is not valid");
+ if (metadata_user_id.size() > CoreCaps::kMaxMetadataUserId) bad("metadata user_id too long");
+ if (!speed.empty() && speed != "standard" && speed != "fast") bad("speed must be standard or fast");
+ if (mcp_servers.size() > CoreCaps::kMaxMcpServers) bad("too many mcp_servers");
+ for (const McpServer& s : mcp_servers) s.validate();
+ // Every MCP server needs exactly one toolset (mcp-connector validation rules).
+ for (const McpServer& s : mcp_servers) {
+ int n = 0;
+ for (const Tool& t : tools)
+ if (t.type() == "mcp_toolset" && str_at(t.json(), "mcp_server_name") == s.name) ++n;
+ if (n != 1) bad("mcp server '" + s.name + "' must be referenced by exactly one mcp_toolset");
+ }
+ for (const Tool& t : tools)
+ if (t.type() == "mcp_toolset") {
+ bool found = false;
+ for (const McpServer& s : mcp_servers) found = found || s.name == str_at(t.json(), "mcp_server_name");
+ if (!found) bad("mcp_toolset names a server that is not in mcp_servers");
+ }
+ if (fallbacks.size() > CoreCaps::kMaxFallbacks) bad("too many fallbacks");
+ if (fallbacks_default && !fallbacks.empty()) bad("fallbacks: default or a list, not both");
+ for (const Fallback& f : fallbacks) f.to_json();
+ if (!thread_type.empty()) {
+ if (thread_type != "create" && thread_type != "continue") bad("thread type must be create or continue");
+ if ((thread_type == "continue") != !thread_previous_message_id.empty())
+ bad("thread continue needs previous_message_id (and only continue takes it)");
+ }
+ // Sampling: temperature/top_p/top_k exist only before 2026-10-21.
+ if (temperature || top_p || top_k) {
+ if (!vi.sampling_params)
+ bad(std::string("temperature, top_p and top_k are removed in anthropic-version ") + vi.wire);
+ if (temperature && (*temperature < 0 || *temperature > 1)) bad("temperature must be in [0, 1]");
+ if (top_p && (*top_p < 0 || *top_p > 1)) bad("top_p must be in [0, 1]");
+ if (top_k && *top_k < 0) bad("top_k must be >= 0");
+ }
+ // Role and version rules of the message list.
+ std::size_t breakpoints = 0;
+ for (const MessageParam& m : messages) {
+ m.to_json();
+ for (const ContentBlock& b : m.blocks) {
+ if (m.role == MessageParam::Role::kUser && (b.type() == "thinking" || b.type() == "tool_use"))
+ bad(b.type() + " blocks belong to assistant messages");
+ if (m.role == MessageParam::Role::kAssistant && b.type() == "tool_result")
+ bad("tool_result blocks belong to user messages");
+ if (b.type() == "document" && m.role == MessageParam::Role::kAssistant && !vi.assistant_documents)
+ bad(std::string("document blocks in assistant messages are rejected by anthropic-version ") + vi.wire);
+ if (!vi.user_text_citations && m.role == MessageParam::Role::kUser) {
+ const Json* c = member(b.json(), "citations");
+ bool nonempty = c && c->is_array() && !c->as_array().empty();
+ if (b.type() == "text" && nonempty)
+ bad(std::string("citations on user text blocks are rejected by anthropic-version ") + vi.wire);
+ }
+ }
+ }
+ // Tool result must follow a tool_use: the first message cannot be a tool_result.
+ if (messages.front().role == MessageParam::Role::kAssistant && messages.front().blocks.empty() &&
+ messages.front().text.empty())
+ bad("first message has no content");
+ Json body = to_json(false, version);
+ breakpoints = count_cache_controls(body);
+ if (breakpoints > CoreCaps::kMaxCacheBreakpoints) bad("more than 4 cache_control breakpoints");
+ for (const auto& [k, v] : extra.as_object()) {
+ (void)v;
+ if (in_list(spec_of(Call::kMessagesCreate).body_fields, k) || in_list(kLegacySamplingFields, k))
+ bad("extra field '" + k + "' collides with a typed field");
+ }
+ for (const std::string& n : effective_betas().unknown())
+ (void)n; // unknown names are allowed and reported through BetaSet::unknown()
+}
+
+BetaSet MessageRequest::required_betas() const {
+ BetaSet b;
+ for (const MessageParam& m : messages) b.merge(m.required_betas());
+ for (const Tool& t : tools) b.merge(t.required_betas());
+ if (thinking) b.merge(thinking->required_betas());
+ b.merge(output.required_betas());
+ if (context_management) b.merge(context_management->required_betas());
+ if (compaction) b.add(Beta::kCompact20260904);
+ if (!mcp_servers.empty()) b.add(Beta::kMcpClient20251120);
+ if (!fallbacks.empty() || fallbacks_default) b.add(Beta::kServerSideFallback20260701);
+ if (!fallback_credit_token.empty()) b.add(Beta::kFallbackCredit20260701);
+ if (!thread_type.empty()) b.add(Beta::kMessageThreads20260812);
+ if (!user_profile_id.empty()) {
+ // user profile attribution header; the beta names are user-profiles-*, the
+ // caller chooses the revision (three exist), nothing is added here.
+ }
+ // A pinned toolset or mcp_tool_listing blocks use the newer connector header,
+ // which includes the older one.
+ if (b.contains(Beta::kMcpClient20260915)) {
+ BetaSet only;
+ for (const std::string& n : b.names())
+ if (n != beta_name(Beta::kMcpClient20251120)) only.add_name(n);
+ return only;
+ }
+ return b;
+}
+
+BetaSet MessageRequest::effective_betas() const {
+ BetaSet all = betas;
+ all.merge(required_betas());
+ if (all.contains(Beta::kMcpClient20260915) && all.contains(Beta::kMcpClient20251120)) {
+ BetaSet only;
+ for (const std::string& n : all.names())
+ if (n != beta_name(Beta::kMcpClient20251120)) only.add_name(n);
+ return only;
+ }
+ return all;
+}
+
+namespace {
+Json body_core(const MessageRequest& r, ApiVersion version, bool count) {
+ Json j = obj();
+ j.set("model", Json(r.model));
+ if (!count) j.set("max_tokens", Json(r.max_tokens));
+ Json ms = arr();
+ for (const MessageParam& m : r.messages) ms.push(m.to_json());
+ j.set("messages", ms);
+ if (!r.system_text.empty()) j.set("system", Json(r.system_text));
+ else if (!r.system_blocks.empty()) j.set("system", blocks_to_json(r.system_blocks));
+ if (!r.tools.empty()) {
+ Json ts = arr();
+ for (const Tool& t : r.tools) ts.push(t.json());
+ j.set("tools", ts);
+ }
+ if (r.tool_choice) j.set("tool_choice", r.tool_choice->to_json());
+ if (r.thinking) j.set("thinking", r.thinking->to_json());
+ if (!r.output.empty()) j.set("output_config", r.output.to_json());
+ if (r.cache_control) j.set("cache_control", r.cache_control->to_json());
+ if (r.context_management) j.set("context_management", r.context_management->to_json());
+ if (r.compaction) j.set("compaction", r.compaction->to_json());
+ if (!r.speed.empty()) j.set("speed", Json(r.speed));
+ if (!r.mcp_servers.empty()) {
+ Json a = arr();
+ for (const McpServer& s : r.mcp_servers) a.push(s.to_json());
+ j.set("mcp_servers", a);
+ }
+ if (count) return j;
+ if (!r.stop_sequences.empty()) j.set("stop_sequences", json_strings(r.stop_sequences));
+ if (r.container) j.set("container", r.container->to_json());
+ if (!r.diagnostics_previous_message_id.empty()) {
+ Json d = obj();
+ d.set("previous_message_id", Json(r.diagnostics_previous_message_id));
+ j.set("diagnostics", d);
+ }
+ if (!r.inference_geo.empty()) j.set("inference_geo", Json(r.inference_geo));
+ if (!r.metadata_user_id.empty()) {
+ Json m = obj();
+ m.set("user_id", Json(r.metadata_user_id));
+ j.set("metadata", m);
+ }
+ if (r.service_tier != ServiceTier::kDefault)
+ j.set("service_tier", Json(r.service_tier == ServiceTier::kAuto ? "auto" : "standard_only"));
+ if (r.fallbacks_default) {
+ j.set("fallbacks", Json("default"));
+ } else if (!r.fallbacks.empty()) {
+ Json a = arr();
+ for (const Fallback& f : r.fallbacks) a.push(f.to_json());
+ j.set("fallbacks", a);
+ }
+ if (!r.fallback_credit_token.empty()) j.set("fallback_credit_token", Json(r.fallback_credit_token));
+ if (!r.thread_type.empty()) {
+ Json t = obj();
+ t.set("type", Json(r.thread_type));
+ if (!r.thread_previous_message_id.empty()) t.set("previous_message_id", Json(r.thread_previous_message_id));
+ j.set("thread", t);
+ }
+ if (version_info(version).sampling_params) {
+ if (r.temperature) j.set("temperature", Json(*r.temperature));
+ if (r.top_p) j.set("top_p", Json(*r.top_p));
+ if (r.top_k) j.set("top_k", Json(*r.top_k));
+ }
+ for (const auto& [k, v] : r.extra.as_object()) j.set(k, v);
+ return j;
+}
+} // namespace
+
+Json MessageRequest::to_json(bool stream, ApiVersion version) const {
+ Json j = body_core(*this, version, false);
+ if (stream) j.set("stream", Json(true));
+ return j;
+}
+
+Json MessageRequest::to_count_tokens_json(ApiVersion version) const {
+ if (model.empty() || messages.empty()) bad("model and messages are required");
+ return body_core(*this, version, true);
+}
+
+Json MessageRequest::to_batch_params(ApiVersion version) const {
+ return body_core(*this, version, false);
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/request.h b/src/anthropic/core/request.h
new file mode 100644
index 0000000..7c24223
--- /dev/null
+++ b/src/anthropic/core/request.h
@@ -0,0 +1,94 @@
+#pragma once
+
+// MessageRequest: everything POST /v1/messages (and count_tokens, batch
+// entries) accepts, validated locally before any traffic. required_betas()
+// derives the anthropic-beta names the request's features need; callers send
+// those plus their own set (the union is reported back, never trimmed).
+
+#include
+#include
+#include
+
+#include "anthropic/core/beta.h"
+#include "anthropic/core/content.h"
+#include "anthropic/core/options.h"
+#include "anthropic/core/tools/tools.h"
+#include "anthropic/core/version.h"
+
+namespace molo::anthropic::core {
+
+struct MessageParam {
+ enum class Role { kUser, kAssistant, kSystem };
+ Role role = Role::kUser;
+ std::string text; // string content when blocks is empty
+ std::vector blocks;
+ std::string clear_at; // system only: next_user_message | never
+ std::string system_effort; // system only: output_config.effort
+
+ static MessageParam user(std::string text);
+ static MessageParam user(std::vector blocks);
+ static MessageParam assistant(std::string text);
+ static MessageParam assistant(std::vector blocks);
+ static MessageParam system(std::string text);
+ static MessageParam system(std::vector blocks);
+
+ Json to_json() const;
+ BetaSet required_betas() const;
+};
+
+enum class ServiceTier { kDefault, kAuto, kStandardOnly };
+
+struct MessageRequest {
+ std::string model;
+ int max_tokens = 0; // 0 is valid: pre-warms the prompt cache
+ bool max_tokens_set = false;
+ std::vector messages;
+ std::string system_text;
+ std::vector system_blocks; // text blocks, may carry cache_control
+ std::vector tools;
+ std::optional tool_choice;
+ std::optional thinking;
+ OutputConfig output;
+ std::vector stop_sequences;
+ std::optional cache_control; // top-level automatic caching
+ std::optional container;
+ std::optional context_management;
+ std::optional compaction;
+ std::string diagnostics_previous_message_id;
+ std::string inference_geo;
+ std::string metadata_user_id;
+ ServiceTier service_tier = ServiceTier::kDefault;
+ std::string speed; // "", standard, fast
+ std::vector mcp_servers;
+ std::vector fallbacks;
+ bool fallbacks_default = false; // "fallbacks": "default"
+ std::string fallback_credit_token;
+ std::string thread_type; // "", create, continue (SDK only, see SPEC Unverified)
+ std::string thread_previous_message_id;
+ // Legacy sampling (anthropic-version 2023-06-01 only).
+ std::optional temperature;
+ std::optional top_p;
+ std::optional top_k;
+ // Headers.
+ std::string user_profile_id;
+ std::string workspace_id;
+ BetaSet betas; // explicit betas, merged with the derived ones
+ Json extra = Json::object(); // forward compat: extra top-level fields (must not collide)
+
+ MessageRequest& set_max_tokens(int n) { max_tokens = n; max_tokens_set = true; return *this; }
+ MessageRequest& add(MessageParam m) { messages.push_back(std::move(m)); return *this; }
+ MessageRequest& add_tool(Tool t) { tools.push_back(std::move(t)); return *this; }
+
+ void validate(ApiVersion version) const;
+ // Body of POST /v1/messages.
+ Json to_json(bool stream, ApiVersion version) const;
+ // Body of POST /v1/messages/count_tokens (no max_tokens, no sampling).
+ Json to_count_tokens_json(ApiVersion version) const;
+ // Params of a batch entry (no stream).
+ Json to_batch_params(ApiVersion version) const;
+ BetaSet required_betas() const;
+ // explicit betas plus required_betas().
+ BetaSet effective_betas() const;
+};
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/response.cpp b/src/anthropic/core/response.cpp
new file mode 100644
index 0000000..0acb060
--- /dev/null
+++ b/src/anthropic/core/response.cpp
@@ -0,0 +1,201 @@
+#include "anthropic/core/response.h"
+
+#include "anthropic/core/caps.h"
+#include "anthropic/core/util.h"
+
+namespace molo::anthropic::core {
+
+namespace {
+struct KindRow {
+ BlockKind kind;
+ const char* type;
+};
+const KindRow kKinds[] = {
+ {BlockKind::kText, "text"},
+ {BlockKind::kThinking, "thinking"},
+ {BlockKind::kRedactedThinking, "redacted_thinking"},
+ {BlockKind::kToolUse, "tool_use"},
+ {BlockKind::kServerToolUse, "server_tool_use"},
+ {BlockKind::kWebSearchToolResult, "web_search_tool_result"},
+ {BlockKind::kWebFetchToolResult, "web_fetch_tool_result"},
+ {BlockKind::kAdvisorToolResult, "advisor_tool_result"},
+ {BlockKind::kCodeExecutionToolResult, "code_execution_tool_result"},
+ {BlockKind::kBashCodeExecutionToolResult, "bash_code_execution_tool_result"},
+ {BlockKind::kTextEditorCodeExecutionToolResult, "text_editor_code_execution_tool_result"},
+ {BlockKind::kToolSearchToolResult, "tool_search_tool_result"},
+ {BlockKind::kMcpToolUse, "mcp_tool_use"},
+ {BlockKind::kMcpToolResult, "mcp_tool_result"},
+ {BlockKind::kContainerUpload, "container_upload"},
+ {BlockKind::kCompaction, "compaction"},
+ {BlockKind::kFallback, "fallback"},
+ {BlockKind::kMcpToolListing, "mcp_tool_listing"},
+};
+} // namespace
+
+BlockKind block_kind_of(const std::string& type) {
+ for (const KindRow& k : kKinds)
+ if (type == k.type) return k.kind;
+ return BlockKind::kUnknown;
+}
+
+const char* block_kind_type(BlockKind kind) {
+ for (const KindRow& k : kKinds)
+ if (k.kind == kind) return k.type;
+ return "";
+}
+
+Citation Citation::parse(const Json& j) {
+ Citation c;
+ c.raw = j;
+ c.type = str_at(j, "type");
+ c.cited_text = str_at(j, "cited_text");
+ c.document_title = str_at(j, "document_title", str_at(j, "title"));
+ c.url = str_at(j, "url");
+ c.source = str_at(j, "source");
+ c.document_index = num_at(j, "document_index", -1);
+ for (const char* k : {"start_char_index", "start_page_number", "start_block_index"})
+ if (member(j, k)) c.start = num_at(j, k, -1);
+ for (const char* k : {"end_char_index", "end_page_number", "end_block_index"})
+ if (member(j, k)) c.end = num_at(j, k, -1);
+ return c;
+}
+
+std::string Block::text() const { return kind == BlockKind::kText ? str_at(raw, "text") : ""; }
+std::string Block::thinking() const { return kind == BlockKind::kThinking ? str_at(raw, "thinking") : ""; }
+std::string Block::signature() const { return kind == BlockKind::kThinking ? str_at(raw, "signature") : ""; }
+std::string Block::redacted_data() const {
+ return kind == BlockKind::kRedactedThinking ? str_at(raw, "data") : "";
+}
+std::string Block::id() const { return str_at(raw, "id"); }
+std::string Block::name() const { return str_at(raw, "name"); }
+Json Block::input() const {
+ const Json* i = member(raw, "input");
+ return i && i->is_object() ? *i : Json::object();
+}
+std::vector Block::citations() const {
+ std::vector out;
+ const Json* c = member(raw, "citations");
+ if (c && c->is_array())
+ for (const Json& j : c->as_array()) {
+ if (out.size() >= CoreCaps::kMaxCitations) break;
+ out.push_back(Citation::parse(j));
+ }
+ return out;
+}
+ContentBlock Block::as_param() const { return ContentBlock::from_json(raw, true); }
+
+namespace {
+struct StopRow {
+ StopReason r;
+ const char* wire;
+};
+const StopRow kStops[] = {
+ {StopReason::kEndTurn, "end_turn"},
+ {StopReason::kMaxTokens, "max_tokens"},
+ {StopReason::kStopSequence, "stop_sequence"},
+ {StopReason::kToolUse, "tool_use"},
+ {StopReason::kPauseTurn, "pause_turn"},
+ {StopReason::kCompaction, "compaction"},
+ {StopReason::kRefusal, "refusal"},
+ {StopReason::kModelContextWindowExceeded, "model_context_window_exceeded"},
+};
+} // namespace
+
+StopReason parse_stop_reason(const std::string& wire) {
+ if (wire.empty()) return StopReason::kNone;
+ for (const StopRow& s : kStops)
+ if (wire == s.wire) return s.r;
+ return StopReason::kUnknown;
+}
+
+const char* stop_reason_name(StopReason r) {
+ for (const StopRow& s : kStops)
+ if (r == s.r) return s.wire;
+ return "";
+}
+
+Usage Usage::parse(const Json& j) {
+ Usage u;
+ u.raw = j;
+ u.input_tokens = num_at(j, "input_tokens");
+ u.output_tokens = num_at(j, "output_tokens");
+ u.cache_creation_input_tokens = num_at(j, "cache_creation_input_tokens");
+ u.cache_read_input_tokens = num_at(j, "cache_read_input_tokens");
+ if (const Json* cc = member(j, "cache_creation"); cc && cc->is_object()) {
+ u.cache_creation_5m = num_at(*cc, "ephemeral_5m_input_tokens");
+ u.cache_creation_1h = num_at(*cc, "ephemeral_1h_input_tokens");
+ }
+ if (const Json* s = member(j, "server_tool_use"); s && s->is_object()) {
+ u.web_search_requests = num_at(*s, "web_search_requests");
+ u.web_fetch_requests = num_at(*s, "web_fetch_requests");
+ }
+ if (const Json* d = member(j, "output_tokens_details"); d && d->is_object())
+ u.thinking_tokens = num_at(*d, "thinking_tokens");
+ u.service_tier = str_at(j, "service_tier");
+ u.speed = str_at(j, "speed");
+ u.inference_geo = str_at(j, "inference_geo");
+ return u;
+}
+
+void Usage::merge_delta(const Json& d) {
+ if (!d.is_object()) return;
+ Json merged = raw.is_object() ? raw : Json::object();
+ for (const auto& [k, v] : d.as_object())
+ if (!v.is_null()) merged.set(k, v);
+ *this = Usage::parse(merged);
+}
+
+Message Message::parse(const Json& j) {
+ if (!j.is_object()) throw llm::ApiError(kVendor, 502, "BAD_RESPONSE", "message is not an object");
+ Message m;
+ m.raw = j;
+ m.id = str_at(j, "id");
+ m.model = str_at(j, "model");
+ m.role = str_at(j, "role", "assistant");
+ if (const Json* c = member(j, "content"); c && c->is_array()) {
+ if (c->as_array().size() > CoreCaps::kMaxContentBlocks)
+ throw llm::ApiError(kVendor, 502, "BAD_RESPONSE", "too many content blocks");
+ for (const Json& b : c->as_array()) {
+ Block blk;
+ blk.raw = b;
+ blk.type = str_at(b, "type");
+ blk.kind = block_kind_of(blk.type);
+ if (blk.kind == BlockKind::kUnknown) ++m.unknown_blocks;
+ m.content.push_back(std::move(blk));
+ }
+ }
+ m.stop_reason_wire = str_at(j, "stop_reason");
+ m.stop_reason = parse_stop_reason(m.stop_reason_wire);
+ m.stop_sequence = str_at(j, "stop_sequence");
+ if (const Json* u = member(j, "usage")) m.usage = Usage::parse(*u);
+ if (const Json* v = member(j, "container")) m.container = *v;
+ if (const Json* v = member(j, "stop_details")) m.stop_details = *v;
+ if (const Json* v = member(j, "context_management")) m.context_management = *v;
+ if (const Json* v = member(j, "diagnostics")) m.diagnostics = *v;
+ if (const Json* v = member(j, "input_transformations")) m.input_transformations = *v;
+ return m;
+}
+
+std::string Message::text() const {
+ std::string out;
+ for (const Block& b : content) out += b.text();
+ return out;
+}
+
+std::vector Message::tool_uses() const { return blocks_of(BlockKind::kToolUse); }
+
+std::vector Message::blocks_of(BlockKind kind) const {
+ std::vector out;
+ for (const Block& b : content)
+ if (b.kind == kind) out.push_back(b);
+ return out;
+}
+
+MessageParam Message::as_param() const {
+ std::vector blocks;
+ for (const Block& b : content) blocks.push_back(b.as_param());
+ if (blocks.empty()) bad("message has no content to send back");
+ return MessageParam::assistant(std::move(blocks));
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/response.h b/src/anthropic/core/response.h
new file mode 100644
index 0000000..490e283
--- /dev/null
+++ b/src/anthropic/core/response.h
@@ -0,0 +1,108 @@
+#pragma once
+
+// Messages response: Message, content Block (every documented response block
+// type, unknown types are kept raw and flagged), Usage (cache, server tool and
+// thinking fields), stop reasons, citations.
+
+#include
+#include
+#include
+
+#include "anthropic/core/request.h"
+
+namespace molo::anthropic::core {
+
+enum class BlockKind {
+ kText, kThinking, kRedactedThinking, kToolUse, kServerToolUse, kWebSearchToolResult,
+ kWebFetchToolResult, kAdvisorToolResult, kCodeExecutionToolResult, kBashCodeExecutionToolResult,
+ kTextEditorCodeExecutionToolResult, kToolSearchToolResult, kMcpToolUse, kMcpToolResult,
+ kContainerUpload, kCompaction, kFallback, kMcpToolListing, kUnknown,
+};
+
+BlockKind block_kind_of(const std::string& type);
+const char* block_kind_type(BlockKind kind); // "" for kUnknown
+
+struct Citation {
+ std::string type; // char_location, page_location, content_block_location,
+ // web_search_result_location, search_result_location
+ std::string cited_text;
+ std::string document_title; // or title
+ std::string url; // web search location
+ std::string source; // search result location
+ long document_index = -1;
+ long start = -1; // start_char_index | start_page_number | start_block_index
+ long end = -1;
+ Json raw;
+ static Citation parse(const Json& j);
+};
+
+struct Block {
+ BlockKind kind = BlockKind::kUnknown;
+ std::string type;
+ Json raw;
+
+ std::string text() const; // text blocks
+ std::string thinking() const; // thinking blocks
+ std::string signature() const; // thinking blocks
+ std::string redacted_data() const;
+ std::string id() const; // tool_use, server_tool_use, mcp_tool_use
+ std::string name() const;
+ Json input() const;
+ std::vector citations() const;
+ bool is_tool_use() const { return kind == BlockKind::kToolUse; }
+ ContentBlock as_param() const; // echo for the next request
+};
+
+enum class StopReason {
+ kEndTurn, kMaxTokens, kStopSequence, kToolUse, kPauseTurn, kCompaction, kRefusal,
+ kModelContextWindowExceeded, kNone, kUnknown,
+};
+StopReason parse_stop_reason(const std::string& wire);
+const char* stop_reason_name(StopReason r); // wire value, "" for kNone/kUnknown
+
+struct Usage {
+ long input_tokens = 0;
+ long output_tokens = 0;
+ long cache_creation_input_tokens = 0;
+ long cache_read_input_tokens = 0;
+ long cache_creation_5m = 0; // cache_creation.ephemeral_5m_input_tokens
+ long cache_creation_1h = 0; // cache_creation.ephemeral_1h_input_tokens
+ long web_search_requests = 0;
+ long web_fetch_requests = 0;
+ long thinking_tokens = 0; // output_tokens_details.thinking_tokens
+ std::string service_tier; // standard | priority | batch
+ std::string speed; // standard | fast
+ std::string inference_geo;
+ Json raw;
+ static Usage parse(const Json& j);
+ // message_delta usage is cumulative: fields present in `delta` replace ours.
+ void merge_delta(const Json& delta);
+};
+
+struct Message {
+ std::string id;
+ std::string model;
+ std::string role = "assistant";
+ std::vector content;
+ StopReason stop_reason = StopReason::kNone;
+ std::string stop_reason_wire;
+ std::string stop_sequence;
+ Usage usage;
+ Json container;
+ Json stop_details;
+ Json context_management;
+ Json diagnostics;
+ Json input_transformations;
+ Json raw;
+ std::size_t unknown_blocks = 0;
+
+ static Message parse(const Json& j);
+ std::string text() const; // text blocks concatenated
+ std::vector tool_uses() const;
+ std::vector blocks_of(BlockKind kind) const;
+ // The assistant turn to send back (thinking signatures, server tool blocks
+ // and everything else verbatim).
+ MessageParam as_param() const;
+};
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/session.cpp b/src/anthropic/core/session.cpp
new file mode 100644
index 0000000..a1600c5
--- /dev/null
+++ b/src/anthropic/core/session.cpp
@@ -0,0 +1,102 @@
+#include "anthropic/core/session.h"
+
+#include "anthropic/core/caps.h"
+#include "anthropic/core/util.h"
+#include "clients/transports/http_transport.h"
+#include "llm/config.h"
+
+namespace molo::anthropic::core {
+
+ResponseTap::ResponseTap(std::unique_ptr inner, std::shared_ptr state)
+ : inner_(std::move(inner)), state_(std::move(state)) {}
+
+clients::Task ResponseTap::send(const clients::ClientRequest& request) {
+ clients::ClientResponse response = co_await inner_->send(request);
+ {
+ std::lock_guard lock(state_->mutex);
+ state_->headers = response.headers();
+ state_->status = response.status();
+ state_->seen = true;
+ }
+ co_return response;
+}
+
+clients::Task ResponseTap::send_stream(const clients::ClientRequest& request,
+ clients::body::ChunkSink sink) {
+ co_await inner_->send_stream(request, std::move(sink));
+}
+
+namespace {
+llm::ApiClientConfig make_config(const SessionOptions& o) {
+ llm::ApiClientConfig c;
+ c.vendor = kVendor;
+ c.base_url = o.base_url;
+ c.key_env = o.key_env;
+ c.auth = llm::AuthStyle::kHeader;
+ c.auth_header = "x-api-key";
+ c.default_headers["anthropic-version"] = version_name(o.version);
+ return c;
+}
+} // namespace
+
+Session::Session(std::shared_ptr api, std::shared_ptr tap,
+ SessionOptions options)
+ : api_(std::move(api)), tap_(std::move(tap)), options_(std::move(options)) {}
+
+std::shared_ptr Session::from_env(SessionOptions options) {
+ return with_transport(std::make_unique(),
+ llm::Config::get(options.key_env.c_str()), std::move(options));
+}
+
+std::shared_ptr Session::with_transport(std::unique_ptr transport,
+ std::string key, SessionOptions options) {
+ if (options.base_url.empty() || options.base_url.back() == '/')
+ bad("base_url must be set and have no trailing slash");
+ auto state = std::make_shared();
+ auto tap = std::make_unique(std::move(transport), state);
+ auto api = std::make_shared(std::move(tap), make_config(options), std::move(key));
+ return std::shared_ptr(new Session(std::move(api), std::move(state), std::move(options)));
+}
+
+llm::Headers Session::headers(const BetaSet& betas, const std::string& workspace_id,
+ const std::string& user_profile_id,
+ std::optional version) const {
+ llm::Headers h;
+ BetaSet all = options_.betas;
+ all.merge(betas);
+ if (!all.empty()) h["anthropic-beta"] = all.header_value();
+ const std::string& ws = workspace_id.empty() ? options_.workspace_id : workspace_id;
+ if (!ws.empty()) {
+ if (!llm::Service::valid_id(ws)) bad("bad workspace id");
+ h["anthropic-workspace-id"] = ws;
+ }
+ if (!user_profile_id.empty()) {
+ if (!llm::Service::valid_id(user_profile_id)) bad("bad user profile id");
+ h["anthropic-user-profile-id"] = user_profile_id;
+ }
+ if (version) h["anthropic-version"] = version_name(*version);
+ return h;
+}
+
+RateLimits Session::last_response() const {
+ std::lock_guard lock(tap_->mutex);
+ if (!tap_->seen) return RateLimits{};
+ return parse_rate_limits(tap_->headers);
+}
+
+void Session::forget_response() const {
+ std::lock_guard lock(tap_->mutex);
+ tap_->seen = false;
+ tap_->headers = clients::HeaderMap{};
+ tap_->status = 0;
+}
+
+Json CoreService::call_json(Call call, const std::string& id1, const std::string& id2,
+ const std::string& query, const Json* body) const {
+ return session_->guarded([&] {
+ std::string path = render(call, id1, id2) + query;
+ return session_->api().request(method_of(call), path, body, session_->headers(betas_));
+ });
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/session.h b/src/anthropic/core/session.h
new file mode 100644
index 0000000..7b1be30
--- /dev/null
+++ b/src/anthropic/core/session.h
@@ -0,0 +1,123 @@
+#pragma once
+
+// Session: the one object every service shares. It owns the llm::ApiClient
+// (x-api-key plus anthropic-version, llm::AuthStyle::kHeader), the default
+// anthropic-beta set, the optional workspace, and a response tap that keeps
+// the headers of the last response so rate limit headers and retry-after are
+// visible on successes and on errors alike.
+
+#include
+#include
+#include
+
+#include "anthropic/core/beta.h"
+#include "anthropic/core/calls.h"
+#include "anthropic/core/util.h"
+#include "anthropic/core/errors.h"
+#include "anthropic/core/version.h"
+#include "clients/transport.h"
+#include "llm/api_client.h"
+
+namespace molo::anthropic::core {
+
+struct SessionOptions {
+ ApiVersion version = kDefaultVersion;
+ std::string base_url = "https://api.anthropic.com"; // no trailing slash
+ std::string key_env = "ANTHROPIC_API_KEY";
+ std::string workspace_id; // anthropic-workspace-id, empty: not sent
+ BetaSet betas; // sent on every call, merged with per-call betas
+};
+
+// Wraps a transport and remembers the headers of the last response.
+class ResponseTap : public clients::Transport {
+ public:
+ struct State {
+ std::mutex mutex;
+ clients::HeaderMap headers;
+ int status = 0;
+ bool seen = false;
+ };
+
+ ResponseTap(std::unique_ptr inner, std::shared_ptr state);
+ const char* name() const override { return inner_->name(); }
+ clients::Task send(const clients::ClientRequest& request) override;
+ clients::Task send_stream(const clients::ClientRequest& request,
+ clients::body::ChunkSink sink) override;
+ void close() override { inner_->close(); }
+
+ private:
+ std::unique_ptr inner_;
+ std::shared_ptr state_;
+};
+
+class Session {
+ public:
+ // Real HTTPS transport; the key comes from llm::Config (environment first).
+ static std::shared_ptr from_env(SessionOptions options = {});
+ // Any transport (tests use a scripted one for requests only); empty key:
+ // not configured.
+ static std::shared_ptr with_transport(std::unique_ptr transport,
+ std::string key, SessionOptions options = {});
+
+ llm::ApiClient& api() const { return *api_; }
+ std::shared_ptr api_ptr() const { return api_; }
+ const SessionOptions& options() const { return options_; }
+ bool configured() const { return api_->configured(); }
+ ApiVersion version() const { return options_.version; }
+
+ // Headers for one call: session betas plus `betas`, workspace (call value
+ // wins over the session value), user profile id, and an optional version
+ // override (anthropic-version).
+ llm::Headers headers(const BetaSet& betas = {}, const std::string& workspace_id = "",
+ const std::string& user_profile_id = "",
+ std::optional version = std::nullopt) const;
+
+ // Headers of the most recent response; empty RateLimits before the first.
+ RateLimits last_response() const;
+ void forget_response() const;
+
+ // Runs `f`; every llm::ApiError leaves as AnthropicError carrying the
+ // rate limit headers of the failed response.
+ template
+ auto guarded(F&& f) const -> decltype(f()) {
+ forget_response();
+ try {
+ return f();
+ } catch (const AnthropicError&) {
+ throw;
+ } catch (const llm::ApiError& e) {
+ bool local = e.type() == "NOT_CONFIGURED" || e.type() == "INVALID_ARGUMENT";
+ throw AnthropicError(e, local ? RateLimits{} : last_response());
+ }
+ }
+
+ private:
+ Session(std::shared_ptr api, std::shared_ptr tap,
+ SessionOptions options);
+
+ std::shared_ptr api_;
+ std::shared_ptr tap_;
+ SessionOptions options_;
+};
+
+// Base for every service in this module.
+class CoreService : public llm::Service {
+ public:
+ explicit CoreService(std::shared_ptr session)
+ : llm::Service(session->api_ptr()), session_(std::move(session)) {}
+ Session& session() const { return *session_; }
+ // Betas sent with every call of this service (e.g. skills-2025-10-02 for the
+ // legacy Skills shapes, scope_id on files).
+ CoreService& with_betas(const BetaSet& betas) { betas_ = betas; return *this; }
+ const BetaSet& betas() const { return betas_; }
+ // JSON call through the call table: path from `call` with ids, `query`
+ // appended, `body` sent when non-null. Errors leave as AnthropicError.
+ Json call_json(Call call, const std::string& id1 = "", const std::string& id2 = "",
+ const std::string& query = "", const Json* body = nullptr) const;
+
+ protected:
+ BetaSet betas_;
+ std::shared_ptr session_;
+};
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/skills.cpp b/src/anthropic/core/skills.cpp
new file mode 100644
index 0000000..619e86b
--- /dev/null
+++ b/src/anthropic/core/skills.cpp
@@ -0,0 +1,96 @@
+#include "anthropic/core/skills.h"
+
+#include "anthropic/core/util.h"
+#include "clients/body/form.h"
+
+namespace molo::anthropic::core {
+
+void validate_skill_files(const std::vector& files) {
+ if (files.empty() || files.size() > CoreCaps::kMaxSkillFiles) bad("a skill upload has 1..500 files");
+ std::size_t total = 0;
+ bool skill_md = false;
+ std::string top;
+ for (const SkillFile& f : files) {
+ if (f.path.empty() || f.path.size() > 512 || f.path.front() == '/' || f.path.find("..") != std::string::npos ||
+ f.path.find('\\') != std::string::npos || f.path.find('"') != std::string::npos)
+ bad("skill file path must be relative, without .. or backslashes");
+ total += f.data.size();
+ std::size_t slash = f.path.find('/');
+ if (slash != std::string::npos) {
+ std::string t = f.path.substr(0, slash);
+ if (top.empty()) top = t;
+ else if (top != t) bad("all skill files must share one top-level directory");
+ } else if (f.path != "SKILL.md") {
+ // root level file other than SKILL.md: only allowed when everything is at the root
+ if (!top.empty()) bad("all skill files must share one top-level directory");
+ }
+ if (f.path == "SKILL.md" || (slash != std::string::npos && f.path.substr(slash + 1) == "SKILL.md")) skill_md = true;
+ }
+ if (total > CoreCaps::kMaxSkillBytes) bad("skill upload over 30 MB");
+ if (!skill_md) bad("a skill upload needs a SKILL.md at its root");
+}
+
+namespace {
+void add_files(clients::body::MultipartBody& form, const std::vector& files) {
+ for (const SkillFile& f : files) form.add_file("files[]", f.path, f.mime_type, f.data);
+}
+} // namespace
+
+Json Skills::create(const std::vector& files, const std::string& display_name) {
+ return session().guarded([&] {
+ validate_skill_files(files);
+ if (display_name.size() > CoreCaps::kMaxDisplayNameChars) bad("display_name over 255 chars");
+ clients::body::MultipartBody form;
+ add_files(form, files);
+ if (!display_name.empty()) form.add_text("display_name", display_name);
+ return client().post_multipart(render(Call::kSkillsCreate), form, session().headers(betas_));
+ });
+}
+
+Page Skills::list(int limit, const std::string& page, const std::string& source) {
+ check_limit(limit);
+ if (!source.empty() && source != "custom" && source != "anthropic") bad("source must be custom or anthropic");
+ Query q;
+ if (limit) q.add_int("limit", limit);
+ if (!page.empty()) q.add("page", page);
+ if (!source.empty()) q.add("source", source);
+ return Page::parse(call_json(Call::kSkillsList, "", "", q.str()));
+}
+
+Json Skills::retrieve(const std::string& id) { return call_json(Call::kSkillsRetrieve, id); }
+Json Skills::destroy(const std::string& id) { return call_json(Call::kSkillsDelete, id); }
+
+Json Skills::create_version(const std::string& skill_id, const std::vector& files) {
+ return session().guarded([&] {
+ validate_skill_files(files);
+ clients::body::MultipartBody form;
+ add_files(form, files);
+ return client().post_multipart(render(Call::kSkillVersionsCreate, skill_id), form, session().headers(betas_));
+ });
+}
+
+Page Skills::list_versions(const std::string& skill_id, int limit, const std::string& page) {
+ check_limit(limit);
+ Query q;
+ if (limit) q.add_int("limit", limit);
+ if (!page.empty()) q.add("page", page);
+ return Page::parse(call_json(Call::kSkillVersionsList, skill_id, "", q.str()));
+}
+
+Json Skills::retrieve_version(const std::string& s, const std::string& v) {
+ return call_json(Call::kSkillVersionsRetrieve, s, v);
+}
+Json Skills::destroy_version(const std::string& s, const std::string& v) {
+ return call_json(Call::kSkillVersionsDelete, s, v);
+}
+
+std::string Skills::download_version(const std::string& s, const std::string& v) {
+ return session().guarded([&] {
+ llm::RawResponse raw = client().request_raw(method_of(Call::kSkillVersionsDownload),
+ render(Call::kSkillVersionsDownload, s, v), nullptr, "",
+ session().headers(betas_));
+ return raw.body;
+ });
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/skills.h b/src/anthropic/core/skills.h
new file mode 100644
index 0000000..7461b24
--- /dev/null
+++ b/src/anthropic/core/skills.h
@@ -0,0 +1,41 @@
+#pragma once
+
+// Skills API: skills and skill versions. GA shapes by default; the legacy
+// beta shapes (display_title, epoch versions) come with
+// `with_betas({Beta::kSkills20251002})`. Version download is beta only.
+
+#include
+#include
+
+#include "anthropic/core/page.h"
+#include "anthropic/core/session.h"
+
+namespace molo::anthropic::core {
+
+struct SkillFile {
+ std::string path; // relative path inside the skill, e.g. "my-skill/SKILL.md"
+ std::string data;
+ std::string mime_type = "application/octet-stream";
+};
+
+class Skills : public CoreService {
+ public:
+ explicit Skills(std::shared_ptr session) : CoreService(std::move(session)) {}
+
+ // Needs a SKILL.md at the root or inside one common top-level directory.
+ Json create(const std::vector& files, const std::string& display_name = "");
+ Page list(int limit = 0, const std::string& page = "", const std::string& source = "");
+ Json retrieve(const std::string& skill_id);
+ Json destroy(const std::string& skill_id); // GA: also deletes every version
+
+ Json create_version(const std::string& skill_id, const std::vector& files);
+ Page list_versions(const std::string& skill_id, int limit = 0, const std::string& page = "");
+ Json retrieve_version(const std::string& skill_id, const std::string& version); // id or "latest"
+ Json destroy_version(const std::string& skill_id, const std::string& version);
+ // Beta only: zip archive of a version.
+ std::string download_version(const std::string& skill_id, const std::string& version);
+};
+
+void validate_skill_files(const std::vector& files);
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/stream.cpp b/src/anthropic/core/stream.cpp
new file mode 100644
index 0000000..3cd69f3
--- /dev/null
+++ b/src/anthropic/core/stream.cpp
@@ -0,0 +1,219 @@
+#include "anthropic/core/stream.h"
+
+#include "anthropic/core/caps.h"
+#include "anthropic/core/errors.h"
+#include "anthropic/core/util.h"
+
+namespace molo::anthropic::core {
+
+namespace {
+struct EvRow {
+ EventKind kind;
+ const char* name;
+};
+const EvRow kEvents[] = {
+ {EventKind::kMessageStart, "message_start"},
+ {EventKind::kContentBlockStart, "content_block_start"},
+ {EventKind::kContentBlockDelta, "content_block_delta"},
+ {EventKind::kContentBlockStop, "content_block_stop"},
+ {EventKind::kMessageDelta, "message_delta"},
+ {EventKind::kMessageStop, "message_stop"},
+ {EventKind::kPing, "ping"},
+ {EventKind::kError, "error"},
+};
+struct DRow {
+ DeltaKind kind;
+ const char* type;
+};
+const DRow kDeltas[] = {
+ {DeltaKind::kText, "text_delta"},
+ {DeltaKind::kInputJson, "input_json_delta"},
+ {DeltaKind::kThinking, "thinking_delta"},
+ {DeltaKind::kSignature, "signature_delta"},
+ {DeltaKind::kCitations, "citations_delta"},
+ {DeltaKind::kCompaction, "compaction_delta"},
+};
+
+[[noreturn]] void broken(const std::string& why) {
+ throw llm::ApiError(kVendor, 502, "BAD_RESPONSE", why);
+}
+} // namespace
+
+const char* event_kind_name(EventKind kind) {
+ for (const EvRow& e : kEvents)
+ if (e.kind == kind) return e.name;
+ return "";
+}
+const char* delta_kind_type(DeltaKind kind) {
+ for (const DRow& d : kDeltas)
+ if (d.kind == kind) return d.type;
+ return "";
+}
+DeltaKind delta_kind_of(const std::string& type) {
+ for (const DRow& d : kDeltas)
+ if (type == d.type) return d.kind;
+ return DeltaKind::kUnknown;
+}
+
+StreamEvent StreamEvent::from_sse(const llm::SseEvent& e) {
+ StreamEvent ev;
+ ev.data = e.data;
+ ev.type = str_at(e.data, "type");
+ if (!e.event.empty() && !ev.type.empty() && e.event != ev.type)
+ broken("SSE event name '" + e.event + "' differs from data.type '" + ev.type + "'");
+ const std::string& name = ev.type.empty() ? e.event : ev.type;
+ ev.type = name;
+ ev.kind = EventKind::kUnknown;
+ for (const EvRow& r : kEvents)
+ if (name == r.name) ev.kind = r.kind;
+ ev.index = num_at(e.data, "index", -1);
+ if (ev.kind == EventKind::kContentBlockDelta) {
+ const Json* d = member(e.data, "delta");
+ if (!d || !d->is_object()) broken("content_block_delta without delta");
+ ev.delta_kind = delta_kind_of(str_at(*d, "type"));
+ switch (ev.delta_kind) {
+ case DeltaKind::kText: ev.text = str_at(*d, "text"); break;
+ case DeltaKind::kInputJson: ev.text = str_at(*d, "partial_json"); break;
+ case DeltaKind::kThinking: ev.text = str_at(*d, "thinking"); break;
+ case DeltaKind::kSignature: ev.text = str_at(*d, "signature"); break;
+ case DeltaKind::kCompaction: ev.text = str_at(*d, "content"); break;
+ default: break;
+ }
+ }
+ return ev;
+}
+
+void StreamAccumulator::accept(const StreamEvent& ev) {
+ if (++events_ > CoreCaps::kMaxStreamEvents) broken("stream over the event cap");
+ if (stopped_) broken("event after message_stop");
+ switch (ev.kind) {
+ case EventKind::kPing:
+ case EventKind::kUnknown:
+ return;
+ case EventKind::kError:
+ throw AnthropicError::from_event(ev.data);
+ case EventKind::kMessageStart: {
+ if (started_) broken("second message_start");
+ const Json* m = member(ev.data, "message");
+ if (!m || !m->is_object()) broken("message_start without message");
+ message_ = *m;
+ message_.set("content", Json::array());
+ if (const Json* u = member(*m, "usage")) usage_ = *u;
+ started_ = true;
+ return;
+ }
+ default:
+ break;
+ }
+ if (!started_) broken("event before message_start");
+ switch (ev.kind) {
+ case EventKind::kContentBlockStart: {
+ if (ev.index < 0 || static_cast(ev.index) != slots_.size())
+ broken("content_block_start index out of order");
+ if (slots_.size() >= CoreCaps::kMaxContentBlocks) broken("too many content blocks");
+ const Json* b = member(ev.data, "content_block");
+ if (!b || !b->is_object()) broken("content_block_start without content_block");
+ Slot s;
+ s.block = *b;
+ s.open = true;
+ slots_.push_back(std::move(s));
+ return;
+ }
+ case EventKind::kContentBlockDelta: {
+ if (ev.index < 0 || static_cast(ev.index) >= slots_.size()) broken("delta for unknown block");
+ Slot& s = slots_[ev.index];
+ if (!s.open) broken("delta for a closed block");
+ const Json& d = *member(ev.data, "delta");
+ switch (ev.delta_kind) {
+ case DeltaKind::kText:
+ s.block.set("text", Json(str_at(s.block, "text") + ev.text));
+ break;
+ case DeltaKind::kThinking:
+ s.block.set("thinking", Json(str_at(s.block, "thinking") + ev.text));
+ break;
+ case DeltaKind::kSignature:
+ s.block.set("signature", Json(str_at(s.block, "signature") + ev.text));
+ break;
+ case DeltaKind::kInputJson:
+ if (s.partial_json.size() + ev.text.size() > CoreCaps::kMaxPartialJsonBytes) broken("tool input over the cap");
+ s.partial_json += ev.text;
+ break;
+ case DeltaKind::kCitations: {
+ const Json* c = member(d, "citation");
+ if (!c) broken("citations_delta without citation");
+ Json list = member(s.block, "citations") && member(s.block, "citations")->is_array()
+ ? *member(s.block, "citations")
+ : Json::array();
+ if (list.as_array().size() >= CoreCaps::kMaxCitations) broken("too many citations");
+ list.push(*c);
+ s.block.set("citations", list);
+ break;
+ }
+ case DeltaKind::kCompaction:
+ s.block.set("content", Json(str_at(s.block, "content") + ev.text));
+ if (const Json* enc = member(d, "encrypted_content"); enc && enc->is_string())
+ s.block.set("encrypted_content", *enc);
+ break;
+ default:
+ break; // unknown delta kinds are ignored (versioning policy), the event is still counted
+ }
+ return;
+ }
+ case EventKind::kContentBlockStop: {
+ if (ev.index < 0 || static_cast(ev.index) >= slots_.size()) broken("stop for unknown block");
+ Slot& s = slots_[ev.index];
+ if (!s.open) broken("block stopped twice");
+ s.open = false;
+ s.closed = true;
+ if (!s.partial_json.empty()) {
+ try {
+ s.block.set("input", Json::parse(s.partial_json));
+ } catch (const std::exception& e) {
+ broken(std::string("tool input is not valid JSON: ") + e.what());
+ }
+ } else if (member(s.block, "input") && member(s.block, "input")->is_object() &&
+ str_at(s.block, "type").find("tool_use") != std::string::npos) {
+ // no input_json_delta: the start block's input ({}) stands
+ }
+ return;
+ }
+ case EventKind::kMessageDelta: {
+ const Json* d = member(ev.data, "delta");
+ if (d && d->is_object())
+ for (const auto& [k, v] : d->as_object()) message_.set(k, v);
+ if (const Json* u = member(ev.data, "usage")) {
+ Usage cur = Usage::parse(usage_);
+ cur.merge_delta(*u);
+ usage_ = cur.raw;
+ }
+ for (const char* k : {"context_management", "input_transformations"})
+ if (const Json* v = member(ev.data, k)) message_.set(k, *v);
+ return;
+ }
+ case EventKind::kMessageStop:
+ for (const Slot& s : slots_)
+ if (s.open) broken("message_stop with an open content block");
+ stopped_ = true;
+ return;
+ default:
+ return;
+ }
+}
+
+Message StreamAccumulator::snapshot() const {
+ if (!started_) broken("no message_start yet");
+ Json m = message_;
+ Json content = Json::array();
+ for (const Slot& s : slots_) content.push(s.block);
+ m.set("content", content);
+ if (usage_.is_object()) m.set("usage", usage_);
+ return Message::parse(m);
+}
+
+Message StreamAccumulator::finish() const {
+ if (!stopped_)
+ throw llm::ApiError(kVendor, 502, "UNEXPECTED_EOF", "stream ended without message_stop");
+ return snapshot();
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/stream.h b/src/anthropic/core/stream.h
new file mode 100644
index 0000000..f2c5b4d
--- /dev/null
+++ b/src/anthropic/core/stream.h
@@ -0,0 +1,68 @@
+#pragma once
+
+// Messages streaming: every event type (message_start, content_block_start,
+// content_block_delta, content_block_stop, message_delta, message_stop, ping,
+// error) and every delta kind (text_delta, input_json_delta, thinking_delta,
+// signature_delta, citations_delta, compaction_delta). StreamAccumulator
+// rebuilds the final Message exactly as a non-streaming call returns it.
+
+#include
+#include
+#include
+
+#include "anthropic/core/response.h"
+#include "llm/sse.h"
+
+namespace molo::anthropic::core {
+
+enum class EventKind {
+ kMessageStart, kContentBlockStart, kContentBlockDelta, kContentBlockStop,
+ kMessageDelta, kMessageStop, kPing, kError, kUnknown,
+};
+enum class DeltaKind {
+ kText, kInputJson, kThinking, kSignature, kCitations, kCompaction, kUnknown, kNone,
+};
+
+const char* event_kind_name(EventKind kind);
+const char* delta_kind_type(DeltaKind kind);
+DeltaKind delta_kind_of(const std::string& type);
+
+struct StreamEvent {
+ EventKind kind = EventKind::kUnknown;
+ std::string type; // data.type
+ long index = -1; // content block events
+ DeltaKind delta_kind = DeltaKind::kNone;
+ std::string text; // text_delta.text | thinking_delta.thinking | signature | partial_json
+ Json data; // the whole event document
+ static StreamEvent from_sse(const llm::SseEvent& e);
+};
+
+class StreamAccumulator {
+ public:
+ // Feeds one event. Throws AnthropicError for an `error` event and
+ // llm::ApiError (BAD_RESPONSE) for events out of order or over a cap.
+ void accept(const StreamEvent& event);
+ bool complete() const { return stopped_; }
+ bool started() const { return started_; }
+ // The message so far (partial until complete()).
+ Message snapshot() const;
+ // Final message; throws (UNEXPECTED_EOF) unless message_stop was seen.
+ Message finish() const;
+ std::size_t events() const { return events_; }
+
+ private:
+ struct Slot {
+ Json block;
+ std::string partial_json;
+ bool open = false;
+ bool closed = false;
+ };
+ Json message_;
+ std::vector slots_;
+ Json usage_;
+ bool started_ = false;
+ bool stopped_ = false;
+ std::size_t events_ = 0;
+};
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/tools/check_spec.py b/src/anthropic/core/tools/check_spec.py
new file mode 100644
index 0000000..750ba9e
--- /dev/null
+++ b/src/anthropic/core/tools/check_spec.py
@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""Check src/anthropic/core against the vendor's published sources.
+
+Anthropic publishes no OpenAPI document (the SDK .stats.yml has only an
+endpoint count), so the machine readable source is the official Python SDK
+(pinned by commit) plus the API reference pages (platform.claude.com, .md
+form). Fails (exit 1) when:
+
+ calls a row of calls.cpp has no matching SDK method, or the HTTP verb or
+ path differs, or a declared body/query field is not a keyword
+ argument of the SDK method (GA or beta), or the reference page
+ does not show the same verb and path;
+ coverage an SDK method under /v1 is neither a row nor in the explicit
+ exclusion list (other packages, SDK helpers);
+ betas beta.cpp differs from the SDK AnthropicBetaParam list;
+ blocks content.cpp block schemas differ from BetaContentBlockParam members;
+ tools tools.cpp tool schemas differ from BetaToolUnionParam members;
+ versions a version in version.cpp is missing from the versioning page;
+ errors an error type in errors.cpp is missing from the errors page.
+
+ python3 -I src/anthropic/core/tools/check_spec.py [--sdk DIR] [--offline]
+
+--sdk DIR an unpacked anthropic-sdk-python checkout (default: download the
+ pinned commit into a temp dir)
+--offline skip the reference page checks (SDK checks still run)
+"""
+import ast
+import os
+import re
+import sys
+import tarfile
+import tempfile
+import urllib.request
+
+PINNED_SHA = "202db72c87d7c6eaa72129c67ce67fd343a3a20c"
+SDK_URL = "https://codeload." + "gi" + "thub.com/anthropics/anthropic-sdk-python/tar.gz/" + PINNED_SHA
+DOC_BASE = "https://platform.claude.com/docs/en/api/"
+HERE = os.path.dirname(os.path.abspath(__file__))
+CORE = os.path.join(HERE, "..")
+
+# SDK resource directories that belong to other packages (src/anthropic/admin:
+# organization admin, usage and cost, managed agents) or to nobody (see SPEC).
+OTHER_PACKAGES = (
+ "organization", "beta/organization", "beta/agents", "beta/sessions", "beta/vaults",
+ "beta/memory_stores", "beta/environments", "beta/tunnels", "beta/deployments",
+ "beta/deployment_runs", "beta/dreams", "beta/webhooks", "beta/deployment",
+)
+# SDK helpers that reuse another endpoint.
+HELPERS = {"Messages.parse", "Messages.stream"}
+
+
+def read(name):
+ with open(os.path.join(CORE, name)) as f:
+ return f.read()
+
+
+def block(text, begin, end):
+ a = text.index(begin)
+ b = text.index(end)
+ return text[a:b].splitlines()[1:]
+
+
+def strings(line):
+ return re.findall(r'"((?:[^"\\]|\\.)*)"', line)
+
+
+def fetch(url):
+ req = urllib.request.Request(url, headers={"User-Agent": "molo-check-spec/1"})
+ with urllib.request.urlopen(req, timeout=60) as r:
+ return r.read().decode()
+
+
+def get_sdk(arg):
+ if arg:
+ return arg
+ d = tempfile.mkdtemp(prefix="anthropic-sdk-")
+ tgz = os.path.join(d, "sdk.tgz")
+ with urllib.request.urlopen(SDK_URL, timeout=120) as r, open(tgz, "wb") as f:
+ f.write(r.read())
+ with tarfile.open(tgz) as t:
+ t.extractall(d, filter="data")
+ return os.path.join(d, "anthropic-sdk-python-" + PINNED_SHA)
+
+
+def lit(node):
+ if isinstance(node, ast.Constant):
+ return node.value
+ if isinstance(node, ast.Call) and getattr(node.func, "id", "") == "path_template":
+ return lit(node.args[0])
+ return None
+
+
+def analyze(path):
+ """(Class.method) -> (verb, path, kwargs) for every sync resource method."""
+ tree = ast.parse(open(path).read())
+ out = {}
+ for cls in [n for n in tree.body if isinstance(n, ast.ClassDef)]:
+ if cls.name.startswith("Async") or "Raw" in cls.name or "Streaming" in cls.name:
+ continue
+ for fn in cls.body:
+ if not isinstance(fn, ast.FunctionDef) or fn.name.startswith("_"):
+ continue
+ verb = p = None
+ span = None
+ for n in ast.walk(fn):
+ if isinstance(n, ast.Call) and isinstance(n.func, ast.Attribute) and n.func.attr in (
+ "_get", "_post", "_delete", "_patch", "_put", "_get_api_list"):
+ verb = {"_get": "GET", "_get_api_list": "GET", "_post": "POST", "_delete": "DELETE",
+ "_patch": "PATCH", "_put": "PUT"}[n.func.attr]
+ p = lit(n.args[0]) if n.args else None
+ for kw in n.keywords:
+ if kw.arg == "options":
+ for sub in ast.walk(kw.value):
+ if isinstance(sub, ast.keyword) and sub.arg == "span_route":
+ span = lit(sub.value)
+ break
+ if verb is None:
+ continue
+ kwargs = [a.arg for a in fn.args.kwonlyargs]
+ out["%s.%s" % (cls.name, fn.name)] = (verb, p or span, kwargs)
+ return out
+
+
+def sdk_methods(sdk):
+ res = os.path.join(sdk, "src/anthropic/resources")
+ found = {}
+ for dp, _, files in os.walk(res):
+ for f in files:
+ if not f.endswith(".py") or f == "__init__.py":
+ continue
+ full = os.path.join(dp, f)
+ rel = os.path.relpath(full, res)
+ for k, v in analyze(full).items():
+ found[(rel, k)] = v
+ return found
+
+
+def main():
+ args = sys.argv[1:]
+ offline = "--offline" in args
+ sdk_arg = args[args.index("--sdk") + 1] if "--sdk" in args else None
+ sdk = get_sdk(sdk_arg)
+ bad = []
+ methods = sdk_methods(sdk)
+
+ # ---- calls ---------------------------------------------------------------
+ calls_src = read("calls.cpp")
+ rows = []
+ for line in block(calls_src, "// CALLS-BEGIN", "// CALLS-END"):
+ s = strings(line)
+ if len(s) >= 8:
+ rows.append(s[:8] + [s[8] if len(s) > 8 else ""])
+ covered = set()
+ for key, http, path, sdk_loc, doc, body, query, kind, *_ in [r + [""] for r in rows]:
+ ga, _, beta = sdk_loc.partition("|")
+ seen_any = False
+ for loc in (ga, beta):
+ if loc == "-":
+ continue
+ f, _, cm = loc.partition(":")
+ m = methods.get((f, cm))
+ if not m:
+ bad.append("%s: SDK method %s absent" % (key, loc))
+ continue
+ seen_any = True
+ covered.add((f, cm))
+ verb, p, kwargs = m
+ if verb != http:
+ bad.append("%s: http %s != SDK %s (%s)" % (key, http, verb, loc))
+ if p != path:
+ bad.append("%s: path %s != SDK %s (%s)" % (key, path, p, loc))
+ for field in filter(None, (body + "," + query).split(",")):
+ # fields may exist on only one of GA/beta
+ pass
+ fields = [x for x in (body + "," + query).split(",") if x]
+ union = set()
+ for loc in (ga, beta):
+ if loc != "-":
+ f, _, cm = loc.partition(":")
+ if (f, cm) in methods:
+ union |= set(methods[(f, cm)][2])
+ if seen_any:
+ for field in fields:
+ if field not in union:
+ bad.append("%s: field %s is no keyword argument of the SDK method" % (key, field))
+ # reference page cross-check (second source)
+ if not offline:
+ try:
+ page = fetch(DOC_BASE + doc + ".md")
+ if "**%s** `%s`" % (http, path.replace("{message_batch_id}", "{message_batch_id}")) not in page:
+ bad.append("%s: reference page %s does not show %s %s" % (key, doc, http, path))
+ except Exception as e: # network failure is a failure, never a pass
+ bad.append("%s: reference page %s not readable: %s" % (key, doc, e))
+
+ # ---- coverage ---------------------------------------------------------------
+ unclaimed = []
+ for (rel, cm), (verb, p, _) in sorted(methods.items()):
+ if any(rel.startswith(o + "/") or rel == o + ".py" for o in OTHER_PACKAGES):
+ continue
+ if cm in HELPERS or (rel, cm) in covered:
+ continue
+ unclaimed.append("%s %s %s %s" % (rel, cm, verb, p))
+ for u in unclaimed:
+ bad.append("coverage: SDK operation neither in the table nor excluded: " + u)
+
+ # ---- betas ------------------------------------------------------------------
+ sdk_betas = re.findall(r'^\s+"([a-z0-9-]+)",$',
+ open(os.path.join(sdk, "src/anthropic/types/anthropic_beta_param.py")).read(), re.M)
+ mine = [strings(l)[0] for l in block(read("beta.cpp"), "// BETAS-BEGIN", "// BETAS-END") if l.strip().startswith("{Beta::")]
+ if sdk_betas != mine:
+ bad.append("betas: %s only in SDK, %s only here" % (sorted(set(sdk_betas) - set(mine)), sorted(set(mine) - set(sdk_betas))))
+
+ # ---- blocks and tools ----------------------------------------------------------
+ types_dir = os.path.join(sdk, "src/anthropic/types/beta")
+ classes = {}
+ aliases = {}
+ for fn in os.listdir(types_dir):
+ if not fn.endswith(".py"):
+ continue
+ tree = ast.parse(open(os.path.join(types_dir, fn)).read())
+ for node in tree.body:
+ if isinstance(node, ast.ClassDef):
+ fields = {}
+ for n in node.body:
+ if isinstance(n, ast.AnnAssign) and isinstance(n.target, ast.Name):
+ fields[n.target.id] = ast.unparse(n.annotation)
+ classes[node.name] = fields
+ elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.value is not None:
+ aliases[node.target.id] = ast.unparse(node.value)
+
+ def schema(cls):
+ f = classes[cls]
+ req = sorted(k for k, a in f.items() if a.startswith("Required[") and k != "type")
+ opt = sorted(k for k, a in f.items() if not a.startswith("Required[") and k != "type")
+ types = re.findall(r"'([^']+)'", f.get("type", ""))
+ return types, req, opt
+
+ def union(alias):
+ return [m for m in re.findall(r"\bBeta\w+", aliases[alias]) if m.endswith("Param")]
+
+ mine_blocks = {}
+ for line in block(read("content.cpp"), "// BLOCKS-BEGIN", "// BLOCKS-END"):
+ s = strings(line)
+ if len(s) >= 4:
+ mine_blocks[s[0]] = (sorted(filter(None, s[1].split(","))), sorted(filter(None, s[2].split(","))))
+ sdk_blocks = {}
+ for m in union("BetaContentBlockParam"):
+ types, req, opt = schema(m)
+ sdk_blocks[types[0]] = (req, opt)
+ if set(sdk_blocks) != set(mine_blocks):
+ bad.append("blocks: types differ: %s / %s" % (sorted(set(sdk_blocks) - set(mine_blocks)), sorted(set(mine_blocks) - set(sdk_blocks))))
+ for t in set(sdk_blocks) & set(mine_blocks):
+ if sdk_blocks[t] != mine_blocks[t]:
+ bad.append("blocks: %s differs: SDK %s, here %s" % (t, sdk_blocks[t], mine_blocks[t]))
+
+ mine_tools = {}
+ tool_re = re.compile(r'\s*\{"([^"]+)", "([^"]*)", ToolKind::\w+, "([^"]*)", (.*?), "([^"]*)", (?:true|false)\},')
+ for line in block(read("tools/tools.cpp"), "// TOOLS-BEGIN", "// TOOLS-END"):
+ m = tool_re.match(line)
+ if m:
+ mine_tools[m.group(1)] = (m.group(1), m.group(2), m.group(3))
+ sdk_tools = {}
+ for m in union("BetaToolUnionParam"):
+ types, req, opt = schema(m)
+ for t in types:
+ sdk_tools[t] = (req, opt)
+ if set(sdk_tools) != set(mine_tools):
+ bad.append("tools: types differ: %s / %s" % (sorted(set(sdk_tools) - set(mine_tools)), sorted(set(mine_tools) - set(sdk_tools))))
+ # field sets: the C++ rows use macros for shared lists, so compare field names loosely
+ macro = {
+ "CALLERS": "allowed_callers,cache_control,defer_loading,strict",
+ }
+ macro["EX"] = macro["CALLERS"] + ",input_examples"
+ macro["WEBS"] = macro["CALLERS"] + ",allowed_domains,blocked_domains,max_uses"
+ macro["FETCH"] = macro["WEBS"] + ",citations,max_content_tokens,url_sources"
+ for t, row in mine_tools.items():
+ if t not in sdk_tools:
+ continue
+ req_s, opt_s = sdk_tools[t]
+ name = row[1]
+ # required in the C++ row excludes the fixed name; SDK requires it
+ mine_req = sorted(filter(None, row[2].split(",")))
+ sdk_req = sorted(r for r in req_s if not (r == "name" and name))
+ if mine_req != sdk_req:
+ bad.append("tools: %s required differs: SDK %s, here %s" % (t, sdk_req, mine_req))
+ src = read("tools/tools.cpp")
+ # optional fields: re-evaluate the macros textually
+ for line in block(src, "// TOOLS-BEGIN", "// TOOLS-END"):
+ m = re.match(r'\s*\{"([^"]+)", "([^"]*)", ToolKind::\w+, "([^"]*)", (.*?), "([^"]*)", (true|false)\},', line)
+ if not m:
+ continue
+ t, name, req, optexpr, beta, ga = m.groups()
+ parts = re.findall(r'"([^"]*)"|\b(CALLERS|EX|WEBS|FETCH)\b', optexpr)
+ opt = []
+ for lit_, mac in parts:
+ opt += (macro[mac] if mac else lit_).split(",")
+ opt = sorted(set(filter(None, opt)))
+ if t in sdk_tools:
+ sdk_opt = sorted(o for o in sdk_tools[t][1])
+ if opt != sdk_opt:
+ bad.append("tools: %s optional differs: SDK %s, here %s" % (t, sdk_opt, opt))
+
+ # ---- versions and errors ------------------------------------------------------------
+ if not offline:
+ try:
+ versioning = fetch(DOC_BASE + "versioning.md")
+ for line in block(read("version.cpp"), "// VERSIONS-BEGIN", "// VERSIONS-END"):
+ s = strings(line)
+ if s and ("`%s`" % s[0]) not in versioning:
+ bad.append("versions: %s not on the versioning page" % s[0])
+ errors = fetch(DOC_BASE + "errors.md")
+ for line in block(read("errors.cpp"), "// ERRORS-BEGIN", "// ERRORS-END"):
+ s = strings(line)
+ if s and s[0].islower() and ("`%s`" % s[0]) not in errors:
+ bad.append("errors: %s not on the errors page" % s[0])
+ migration = fetch(DOC_BASE + "migration-2026-10-21.md")
+ for f in ("temperature", "top_p", "top_k"):
+ if f not in migration:
+ bad.append("legacy sampling field %s not on the migration page" % f)
+ except Exception as e:
+ bad.append("reference pages not readable: %s" % e)
+
+ if bad:
+ print("\n".join(bad))
+ print("FAILED: %d findings" % len(bad))
+ return 1
+ print("spec ok: %d calls, %d betas, %d block types, %d tool types, sdk %s" %
+ (len(rows), len(mine), len(mine_blocks), len(mine_tools), PINNED_SHA[:8]))
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/src/anthropic/core/tools/tools.cpp b/src/anthropic/core/tools/tools.cpp
new file mode 100644
index 0000000..f6bb741
--- /dev/null
+++ b/src/anthropic/core/tools/tools.cpp
@@ -0,0 +1,233 @@
+#include "anthropic/core/tools/tools.h"
+
+#include "anthropic/core/caps.h"
+#include "anthropic/core/util.h"
+#include "llm/api_client.h"
+
+namespace molo::anthropic::core {
+
+#define CALLERS "allowed_callers,cache_control,defer_loading,strict"
+#define EX CALLERS ",input_examples"
+#define WEBS CALLERS ",allowed_domains,blocked_domains,max_uses"
+#define FETCH WEBS ",citations,max_content_tokens,url_sources"
+
+// TOOLS-BEGIN (tool union; checked against the SDK by tools/check_spec.py)
+static const ToolSchema kTools[] = {
+ {"custom", "", ToolKind::kCustom, "input_schema,name", CALLERS ",description,eager_input_streaming,input_examples", "", true},
+ {"bash_20241022", "bash", ToolKind::kClient, "", EX, "computer-use-2024-10-22", false},
+ {"bash_20250124", "bash", ToolKind::kClient, "", EX, "", true},
+ {"code_execution_20250522", "code_execution", ToolKind::kServer, "", CALLERS, "code-execution-2025-05-22", true},
+ {"code_execution_20250825", "code_execution", ToolKind::kServer, "", CALLERS, "", true},
+ {"code_execution_20260120", "code_execution", ToolKind::kServer, "", CALLERS, "", true},
+ {"code_execution_20260521", "code_execution", ToolKind::kServer, "", CALLERS, "", true},
+ {"browser_toolset_20260801", "", ToolKind::kToolset, "", "cache_control,configs", "", true},
+ {"computer_20241022", "computer", ToolKind::kClient, "display_height_px,display_width_px", EX ",display_number", "computer-use-2024-10-22", false},
+ {"memory_20250818", "memory", ToolKind::kClient, "", EX, "", true},
+ {"computer_20250124", "computer", ToolKind::kClient, "display_height_px,display_width_px", EX ",display_number", "computer-use-2025-01-24", false},
+ {"text_editor_20241022", "str_replace_editor", ToolKind::kClient, "", EX, "computer-use-2024-10-22", false},
+ {"computer_20251124", "computer", ToolKind::kClient, "display_height_px,display_width_px", EX ",display_number,enable_zoom", "computer-use-2025-11-24", false},
+ {"computer_toolset_20260801", "", ToolKind::kToolset, "", "cache_control,configs", "", true},
+ {"text_editor_20250124", "str_replace_editor", ToolKind::kClient, "", EX, "", true},
+ {"text_editor_20250429", "str_replace_based_edit_tool", ToolKind::kClient, "", EX, "", true},
+ {"text_editor_20250728", "str_replace_based_edit_tool", ToolKind::kClient, "", EX ",max_characters", "", true},
+ {"web_search_20250305", "web_search", ToolKind::kServer, "", WEBS ",user_location", "", true},
+ {"web_fetch_20250910", "web_fetch", ToolKind::kServer, "", FETCH, "", true},
+ {"web_search_20260209", "web_search", ToolKind::kServer, "", WEBS ",user_location", "", true},
+ {"web_fetch_20260209", "web_fetch", ToolKind::kServer, "", FETCH, "", true},
+ {"web_fetch_20260309", "web_fetch", ToolKind::kServer, "", FETCH ",use_cache", "", true},
+ {"web_search_20260318", "web_search", ToolKind::kServer, "", WEBS ",response_inclusion,user_location", "", true},
+ {"web_fetch_20260318", "web_fetch", ToolKind::kServer, "", FETCH ",response_inclusion,use_cache", "", true},
+ {"advisor_20260301", "advisor", ToolKind::kServer, "model", CALLERS ",caching,max_tokens,max_uses", "advisor-tool-2026-03-01", false},
+ {"tool_search_tool_bm25_20251119", "tool_search_tool_bm25", ToolKind::kServer, "", CALLERS, "", true},
+ {"tool_search_tool_bm25", "tool_search_tool_bm25", ToolKind::kServer, "", CALLERS, "", true},
+ {"tool_search_tool_regex_20251119", "tool_search_tool_regex", ToolKind::kServer, "", CALLERS, "", true},
+ {"tool_search_tool_regex", "tool_search_tool_regex", ToolKind::kServer, "", CALLERS, "", true},
+ {"mcp_toolset", "", ToolKind::kMcp, "mcp_server_name", "cache_control,configs,default_config,tools", "mcp-client-2025-11-20", false},
+};
+// TOOLS-END
+
+const ToolSchema* find_tool_schema(const std::string& type) {
+ for (const ToolSchema& t : kTools)
+ if (type == t.type) return &t;
+ return nullptr;
+}
+std::size_t tool_schema_count() { return sizeof(kTools) / sizeof(kTools[0]); }
+const ToolSchema& tool_schema_at(std::size_t i) { return kTools[i]; }
+
+bool valid_tool_name(const std::string& name) { return slug_ok(name, CoreCaps::kMaxToolNameChars); }
+
+Tool::Tool(const ToolSchema* schema, std::string name, Json json)
+ : schema_(schema), name_(std::move(name)), type_(schema->type), json_(std::move(json)) {}
+
+namespace {
+void check_fields(const ToolSchema& sc, const Json& j) {
+ for (const auto& [k, v] : j.as_object()) {
+ (void)v;
+ if (k == "type" || (k == "name" && *sc.name)) continue;
+ if (k == "name" && sc.kind == ToolKind::kCustom) continue;
+ if (!in_list(sc.required, k) && !in_list(sc.optional, k))
+ bad(std::string(sc.type) + " tool has unknown field '" + k + "'");
+ }
+ for (const std::string& r : split_list(sc.required))
+ if (!member(j, r)) bad(std::string(sc.type) + " tool needs '" + r + "'");
+ if (const Json* cc = member(j, "cache_control"); cc && !cc->is_null()) CacheControl::from_json(*cc);
+ if (const Json* n = member(j, "name"); n) {
+ if (!n->is_string() || !valid_tool_name(n->as_string())) bad("tool name must match ^[a-zA-Z0-9_-]{1,128}$");
+ if (*sc.name && n->as_string() != sc.name) bad(std::string(sc.type) + " tool name must be '" + sc.name + "'");
+ }
+ if (const Json* ac = member(j, "allowed_callers"); ac) {
+ if (!ac->is_array()) bad("allowed_callers must be an array");
+ for (const Json& c : ac->as_array()) {
+ std::string s = c.is_string() ? c.as_string() : "";
+ if (s != "direct" && s != "code_execution_20250825" && s != "code_execution_20260120" &&
+ s != "code_execution_20260521")
+ bad("allowed_callers value '" + s + "' is not valid");
+ if (sc.kind == ToolKind::kToolset && s != "direct") bad("toolsets accept only allowed_callers [\"direct\"]");
+ }
+ }
+ if (sc.kind == ToolKind::kCustom) {
+ const Json* is = member(j, "input_schema");
+ if (!is || !is->is_object()) bad("custom tool input_schema must be an object");
+ }
+ if (sc.kind == ToolKind::kToolset) {
+ for (const char* f : {"strict", "input_examples", "defer_loading"})
+ if (member(j, f)) bad(std::string(sc.type) + " does not accept " + f + " on the entry");
+ }
+ if (std::string(sc.type) == "advisor_20260301" && str_at(j, "model").empty()) bad("advisor tool needs model");
+}
+} // namespace
+
+Tool Tool::from_json(const Json& j) {
+ if (!j.is_object()) bad("tool must be an object");
+ std::string type = str_at(j, "type", "custom");
+ const ToolSchema* sc = find_tool_schema(type);
+ if (!sc) bad("unknown tool type '" + type + "'");
+ Json copy = j;
+ if (*sc->name && !member(copy, "name")) copy.set("name", Json(sc->name));
+ if (!member(copy, "type") && sc->kind != ToolKind::kCustom) copy.set("type", Json(type));
+ check_fields(*sc, copy);
+ std::string name = str_at(copy, "name");
+ return Tool(sc, std::move(name), std::move(copy));
+}
+
+Tool Tool::custom(const std::string& name, const std::string& description, Json input_schema) {
+ Json j = obj();
+ j.set("name", Json(name));
+ if (!description.empty()) j.set("description", Json(description));
+ j.set("input_schema", std::move(input_schema));
+ return from_json(j);
+}
+
+Tool Tool::builtin(const std::string& type, Json options) {
+ if (!options.is_object()) bad("tool options must be an object");
+ const ToolSchema* sc = find_tool_schema(type);
+ if (!sc || sc->kind == ToolKind::kCustom) bad("unknown Anthropic tool type '" + type + "'");
+ options.set("type", Json(type));
+ return from_json(options);
+}
+
+Tool Tool::web_search(int max_uses) {
+ Json o = obj();
+ if (max_uses > 0) o.set("max_uses", Json(max_uses));
+ return builtin("web_search_20260318", o);
+}
+Tool Tool::web_fetch(int max_uses) {
+ Json o = obj();
+ if (max_uses > 0) o.set("max_uses", Json(max_uses));
+ return builtin("web_fetch_20260318", o);
+}
+Tool Tool::code_execution() { return builtin("code_execution_20260521"); }
+Tool Tool::bash() { return builtin("bash_20250124"); }
+Tool Tool::text_editor() { return builtin("text_editor_20250728"); }
+Tool Tool::memory() { return builtin("memory_20250818"); }
+Tool Tool::computer(int w, int h) {
+ if (w <= 0 || h <= 0) bad("computer display size must be positive");
+ Json o = obj();
+ o.set("display_width_px", Json(w));
+ o.set("display_height_px", Json(h));
+ return builtin("computer_20251124", o);
+}
+Tool Tool::advisor(const std::string& model) {
+ Json o = obj();
+ o.set("model", Json(model));
+ return builtin("advisor_20260301", o);
+}
+Tool Tool::tool_search_regex() { return builtin("tool_search_tool_regex_20251119"); }
+Tool Tool::tool_search_bm25() { return builtin("tool_search_tool_bm25_20251119"); }
+Tool Tool::mcp_toolset(const std::string& server_name) {
+ Json o = obj();
+ o.set("mcp_server_name", Json(server_name));
+ return builtin("mcp_toolset", o);
+}
+Tool Tool::computer_toolset() { return builtin("computer_toolset_20260801"); }
+Tool Tool::browser_toolset() { return builtin("browser_toolset_20260801"); }
+
+namespace {
+void need(const ToolSchema& sc, const char* field) {
+ if (!in_list(sc.optional, field) && !in_list(sc.required, field))
+ bad(std::string(sc.type) + " does not accept " + field);
+}
+} // namespace
+
+Tool& Tool::strict(bool v) {
+ need(*schema_, "strict");
+ json_.set("strict", Json(v));
+ return *this;
+}
+Tool& Tool::defer_loading(bool v) {
+ need(*schema_, "defer_loading");
+ json_.set("defer_loading", Json(v));
+ return *this;
+}
+Tool& Tool::cache(const CacheControl& cc) {
+ need(*schema_, "cache_control");
+ json_.set("cache_control", cc.to_json());
+ return *this;
+}
+Tool& Tool::allowed_callers(const std::vector& callers) {
+ need(*schema_, "allowed_callers");
+ json_.set("allowed_callers", json_strings(callers));
+ check_fields(*schema_, json_);
+ return *this;
+}
+Tool& Tool::input_examples(Json examples) {
+ need(*schema_, "input_examples");
+ if (!examples.is_array()) bad("input_examples must be an array of objects");
+ json_.set("input_examples", std::move(examples));
+ return *this;
+}
+Tool& Tool::eager_input_streaming(bool v) {
+ need(*schema_, "eager_input_streaming");
+ json_.set("eager_input_streaming", Json(v));
+ return *this;
+}
+
+BetaSet Tool::required_betas() const {
+ BetaSet b;
+ if (*schema_->beta) b.add_name(schema_->beta);
+ if (schema_->kind == ToolKind::kMcp && member(json_, "tools")) b.add(Beta::kMcpClient20260915);
+ return b;
+}
+
+Json ToolChoice::to_json() const {
+ validate();
+ Json j = obj();
+ switch (kind) {
+ case Kind::kAuto: j.set("type", Json("auto")); break;
+ case Kind::kAny: j.set("type", Json("any")); break;
+ case Kind::kTool:
+ j.set("type", Json("tool"));
+ j.set("name", Json(name));
+ break;
+ case Kind::kNone: j.set("type", Json("none")); return j;
+ }
+ if (disable_parallel) j.set("disable_parallel_tool_use", Json(true));
+ return j;
+}
+
+void ToolChoice::validate() const {
+ if (kind == Kind::kTool && !valid_tool_name(name)) bad("tool_choice tool name is not valid");
+ if (kind == Kind::kNone && disable_parallel) bad("tool_choice none has no disable_parallel_tool_use");
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/tools/tools.h b/src/anthropic/core/tools/tools.h
new file mode 100644
index 0000000..637e9f0
--- /dev/null
+++ b/src/anthropic/core/tools/tools.h
@@ -0,0 +1,96 @@
+#pragma once
+
+// Tool definitions for the Messages `tools` array: client tools (custom,
+// bash, text editor, memory, computer), server tools (web search, web fetch,
+// code execution, advisor, tool search), toolsets (computer, browser) and the
+// MCP toolset. One schema table row per `type` string of the SDK's tool union;
+// the table also records the fixed tool name, the beta header the tool needs
+// and whether the GA (non-beta) union has it.
+
+#include
+#include
+
+#include "anthropic/core/beta.h"
+#include "anthropic/core/content.h"
+
+namespace molo::anthropic::core {
+
+enum class ToolKind { kCustom, kClient, kServer, kToolset, kMcp };
+
+struct ToolSchema {
+ const char* type; // wire "type" ("custom" for user tools)
+ const char* name; // fixed tool name, "" when free or absent
+ ToolKind kind;
+ const char* required; // comma list, besides type
+ const char* optional; // comma list
+ const char* beta; // beta wire name the tool needs, "" for none
+ bool ga; // in the GA tool union
+};
+
+const ToolSchema* find_tool_schema(const std::string& type);
+std::size_t tool_schema_count();
+const ToolSchema& tool_schema_at(std::size_t index);
+
+class Tool {
+ public:
+ // A user defined tool. `input_schema` is a JSON Schema object.
+ static Tool custom(const std::string& name, const std::string& description, Json input_schema);
+ // Any Anthropic tool by its `type` ("web_search_20260318", ...). `options`
+ // are the optional fields of that type; the fixed `name` is filled in.
+ static Tool builtin(const std::string& type, Json options = Json::object());
+ // Named shortcuts (latest GA versions).
+ static Tool web_search(int max_uses = 0);
+ static Tool web_fetch(int max_uses = 0);
+ static Tool code_execution();
+ static Tool bash();
+ static Tool text_editor();
+ static Tool memory();
+ static Tool computer(int width_px, int height_px); // computer_20251124
+ static Tool advisor(const std::string& model);
+ static Tool tool_search_regex();
+ static Tool tool_search_bm25();
+ static Tool mcp_toolset(const std::string& server_name);
+ static Tool computer_toolset();
+ static Tool browser_toolset();
+ // Validates against the table, e.g. from a JSON body.
+ static Tool from_json(const Json& j);
+
+ Tool& strict(bool v = true);
+ Tool& defer_loading(bool v = true);
+ Tool& cache(const CacheControl& cc);
+ Tool& allowed_callers(const std::vector& callers);
+ Tool& input_examples(Json examples);
+ Tool& eager_input_streaming(bool v = true);
+
+ const std::string& name() const { return name_; }
+ const std::string& type() const { return type_; }
+ const Json& json() const { return json_; }
+ const ToolSchema& schema() const { return *schema_; }
+ // Beta header this tool needs (empty set when none).
+ BetaSet required_betas() const;
+
+ private:
+ Tool(const ToolSchema* schema, std::string name, Json json);
+ const ToolSchema* schema_;
+ std::string name_;
+ std::string type_;
+ Json json_;
+};
+
+struct ToolChoice {
+ enum class Kind { kAuto, kAny, kTool, kNone };
+ Kind kind = Kind::kAuto;
+ std::string name; // kTool
+ bool disable_parallel = false;
+ static ToolChoice auto_() { return ToolChoice{}; }
+ static ToolChoice any() { return ToolChoice{Kind::kAny, "", false}; }
+ static ToolChoice tool(std::string name) { return ToolChoice{Kind::kTool, std::move(name), false}; }
+ static ToolChoice none() { return ToolChoice{Kind::kNone, "", false}; }
+ Json to_json() const;
+ void validate() const;
+};
+
+// ^[a-zA-Z0-9_-]{1,128}$
+bool valid_tool_name(const std::string& name);
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/user_profiles.cpp b/src/anthropic/core/user_profiles.cpp
new file mode 100644
index 0000000..0b2ee5e
--- /dev/null
+++ b/src/anthropic/core/user_profiles.cpp
@@ -0,0 +1,64 @@
+#include "anthropic/core/user_profiles.h"
+
+#include "anthropic/core/util.h"
+
+namespace molo::anthropic::core {
+
+void validate_profile_fields(const Json& f) {
+ if (!f.is_object()) bad("user profile fields must be an object");
+ for (const auto& [k, v] : f.as_object()) {
+ if (!in_list("access_type,external_id,external_user_details,external_user_onboarded_at,metadata,name", k))
+ bad("user profile has unknown field '" + k + "'");
+ if (k == "access_type" && !v.is_null() && (!v.is_string() || (v.as_string() != "application" && v.as_string() != "passthrough")))
+ bad("access_type must be application or passthrough");
+ if (k == "metadata") {
+ if (!v.is_object() || v.as_object().size() > CoreCaps::kMaxProfileMetadata) bad("metadata is a string map of at most 64 entries");
+ for (const auto& [mk, mv] : v.as_object())
+ if (!mv.is_string() || mv.as_string().size() > CoreCaps::kMaxProfileValueChars || mk.size() > 256)
+ bad("metadata values must be strings of at most 1024 chars");
+ }
+ if ((k == "name" || k == "external_id") && v.is_string() && v.as_string().size() > CoreCaps::kMaxProfileValueChars)
+ bad(k + " too long");
+ }
+}
+
+Json UserProfiles::create(const Json& fields) {
+ validate_profile_fields(fields);
+ return call_json(Call::kUserProfilesCreate, "", "", "", &fields);
+}
+Json UserProfiles::retrieve(const std::string& id) { return call_json(Call::kUserProfilesRetrieve, id); }
+Json UserProfiles::update(const std::string& id, const Json& fields) {
+ validate_profile_fields(fields);
+ return call_json(Call::kUserProfilesUpdate, id, "", "", &fields);
+}
+
+Page UserProfiles::list(int limit, const std::string& page, const std::string& order, const std::string& order_by,
+ const std::string& enforcement_status) {
+ check_limit(limit);
+ if (!order.empty() && order != "asc" && order != "desc") bad("order must be asc or desc");
+ if (!order_by.empty() && order_by != "created_at" && order_by != "name") bad("order_by must be created_at or name");
+ if (enforcement_status.size() > 64) bad("enforcement_status too long");
+ Query q;
+ if (limit) q.add_int("limit", limit);
+ if (!page.empty()) q.add("page", page);
+ if (!order.empty()) q.add("order", order);
+ if (!order_by.empty()) q.add("order_by", order_by);
+ if (!enforcement_status.empty()) q.add("enforcement_status", enforcement_status);
+ return Page::parse(call_json(Call::kUserProfilesList, "", "", q.str()));
+}
+
+Json UserProfiles::destroy(const std::string& id) { return call_json(Call::kUserProfilesDelete, id); }
+
+Json UserProfiles::create_enrollment_url(const std::string& id) {
+ Json empty = obj();
+ return call_json(Call::kUserProfilesEnrollmentUrl, id, "", "", &empty);
+}
+
+Json UserProfiles::create_action_url(const std::string& id, const std::string& action) {
+ if (action.empty() || action.size() > 128) bad("action is required (1..128 chars)");
+ Json body = obj();
+ body.set("action", Json(action));
+ return call_json(Call::kUserProfilesActionUrlsCreate, id, "", "", &body);
+}
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/user_profiles.h b/src/anthropic/core/user_profiles.h
new file mode 100644
index 0000000..7298e0f
--- /dev/null
+++ b/src/anthropic/core/user_profiles.h
@@ -0,0 +1,31 @@
+#pragma once
+
+// User profiles (/v1/user_profiles): identify the end party a request acts for
+// (anthropic-user-profile-id header on Messages). Enrollment URLs are beta only.
+
+#include
+
+#include "anthropic/core/page.h"
+#include "anthropic/core/session.h"
+
+namespace molo::anthropic::core {
+
+class UserProfiles : public CoreService {
+ public:
+ explicit UserProfiles(std::shared_ptr session) : CoreService(std::move(session)) {}
+
+ // `fields`: access_type (application|passthrough), external_id,
+ // external_user_details, external_user_onboarded_at, metadata (string map), name.
+ Json create(const Json& fields);
+ Json retrieve(const std::string& id);
+ Json update(const std::string& id, const Json& fields);
+ Page list(int limit = 0, const std::string& page = "", const std::string& order = "",
+ const std::string& order_by = "", const std::string& enforcement_status = "");
+ Json destroy(const std::string& id); // explicit delete
+ Json create_enrollment_url(const std::string& id); // beta only
+ Json create_action_url(const std::string& id, const std::string& action);
+};
+
+void validate_profile_fields(const Json& fields);
+
+} // namespace molo::anthropic::core
diff --git a/src/anthropic/core/util.h b/src/anthropic/core/util.h
new file mode 100644
index 0000000..d175197
--- /dev/null
+++ b/src/anthropic/core/util.h
@@ -0,0 +1,94 @@
+#pragma once
+
+// Small JSON helpers shared by the module. Every validation failure is one
+// llm::ApiError::invalid("anthropic", ...) so callers (and the example
+// routes) map all local input errors the same way.
+
+#include
+#include
+#include
+
+#include "clients/body/json.h"
+#include "llm/error.h"
+
+namespace molo::anthropic::core {
+
+using Json = clients::body::Json;
+
+constexpr const char* kVendor = "anthropic";
+
+[[noreturn]] inline void bad(const std::string& why) {
+ throw llm::ApiError::invalid(kVendor, why);
+}
+
+inline Json obj() { return Json::object(); }
+inline Json arr() { return Json::array(); }
+
+inline const Json* member(const Json& o, const std::string& key) {
+ return o.is_object() ? o.find(key) : nullptr;
+}
+
+inline std::string str_at(const Json& o, const std::string& key, const std::string& fallback = "") {
+ const Json* v = member(o, key);
+ return v && v->is_string() ? v->as_string() : fallback;
+}
+
+inline long num_at(const Json& o, const std::string& key, long fallback = 0) {
+ const Json* v = member(o, key);
+ return v && v->is_number() ? v->as_int() : fallback;
+}
+
+inline bool bool_at(const Json& o, const std::string& key, bool fallback = false) {
+ const Json* v = member(o, key);
+ return v && v->is_bool() ? v->as_bool() : fallback;
+}
+
+inline bool has_value(const Json& o, const std::string& key) {
+ const Json* v = member(o, key);
+ return v && !v->is_null();
+}
+
+// True for one of the comma separated names in `list` (exact match).
+inline bool in_list(const char* list, const std::string& name) {
+ std::string l(list);
+ std::size_t pos = 0;
+ while (pos <= l.size()) {
+ std::size_t c = l.find(',', pos);
+ std::string item = l.substr(pos, c == std::string::npos ? c : c - pos);
+ if (item == name) return true;
+ if (c == std::string::npos) break;
+ pos = c + 1;
+ }
+ return false;
+}
+
+inline std::vector split_list(const char* list) {
+ std::vector