feat(clients): xai core: Responses, chat, tools, media, batch, models, ChatModel

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-24 08:04:30 +02:00
co-authored by Claude Sonnet 5.5
parent 2e0270c043
commit a39826aaea
55 changed files with 8148 additions and 3 deletions
+255
View File
@@ -0,0 +1,255 @@
#include "xai/core/calls.h"
#include <cstring>
#include "xai/core/caps.h"
#include "xai/core/params.h"
namespace molo::xai::core {
// Row: call, method, path, operationId (or "docs"), body fields, query
// params, doc-only body fields ("field@docs page"), request schema, response
// schema, source. Fields the spec marks (Unsupported) or "only maintained for
// compatibility" are not sent and not listed (see SPEC "Excluded fields").
//
// CALLS-BEGIN (parsed by tools/check_spec.py; one row per line)
static const CallSpec kCalls[] = {
{Call::kChatCreate, "POST", "/v1/chat/completions", "handle_generic_completion_request", "deferred,frequency_penalty,guidelines,logprobs,max_completion_tokens,max_tokens,messages,model,n,parallel_tool_calls,presence_penalty,prompt_cache_key,reasoning_effort,response_format,safety_identifier,search_parameters,seed,service_tier,stop,stream,stream_options,temperature,tool_choice,tools,top_logprobs,top_p,user", "", "", "ChatRequest", "ChatResponse", "openapi"},
{Call::kChatDeferredGet, "GET", "/v1/chat/deferred-completion/{request_id}", "handle_get_deferred_completion_request", "", "", "", "", "ChatResponse", "openapi"},
{Call::kCompletionsLegacy, "POST", "/v1/completions", "handle_sample_request", "echo,logprobs,max_tokens,model,n,presence_penalty,prompt,seed,stop,temperature,top_p,user", "", "", "SampleRequest", "SampleResponse", "openapi"},
{Call::kCompleteLegacy, "POST", "/v1/complete", "handle_generic_complete_request", "max_tokens_to_sample,metadata,model,prompt,stop_sequences,temperature,top_p", "", "", "CompleteRequest", "CompleteResponse", "openapi"},
{Call::kMessagesCreate, "POST", "/v1/messages", "handle_generic_messages_request", "max_tokens,messages,metadata,model,stop_sequences,stream,system,temperature,tool_choice,tools,top_p", "", "", "MessageRequest", "MessageResponse", "openapi"},
{Call::kResponsesCreate, "POST", "/v1/responses", "handle_generic_model_request", "guidelines,include,input,instructions,logprobs,max_output_tokens,max_turns,min_p,model,parallel_tool_calls,previous_response_id,prompt_cache_key,reasoning,reasoning_effort,safety_identifier,search_parameters,service_tier,store,stream,temperature,text,tool_choice,tools,top_k,top_logprobs,top_p,user", "", "", "ModelRequest", "ModelResponse", "openapi"},
{Call::kResponsesGet, "GET", "/v1/responses/{response_id}", "handle_get_stored_completion_request", "", "", "", "", "ModelResponse", "openapi"},
{Call::kResponsesDelete, "DELETE", "/v1/responses/{response_id}", "handle_delete_stored_completion_request", "", "", "", "", "DeleteStoredCompletionResponse", "openapi"},
{Call::kResponsesInputItems, "GET", "/v1/responses/{response_id}/input_items", "handle_list_input_items", "", "limit,order,after", "", "", "ListInputItemsResponse", "openapi"},
{Call::kResponsesCompact, "POST", "/v1/responses/compact", "handle_compact_request", "input,model", "", "", "CompactRequest", "CompactResponse", "openapi"},
{Call::kImagesGenerate, "POST", "/v1/images/generations", "handle_generate_image_request", "aspect_ratio,deferred,model,n,output,prompt,resolution,response_format,storage_options,user", "", "quality@model-capabilities/images/generation", "GenerateImageRequest", "GeneratedImageResponse", "openapi"},
{Call::kImagesEdit, "POST", "/v1/images/edits", "handle_edit_image_request", "aspect_ratio,deferred,image,images,model,n,output,prompt,resolution,response_format,storage_options,user", "", "", "EditImageRequest", "GeneratedImageResponse", "openapi"},
{Call::kImagesGet, "GET", "/v1/images/{request_id}", "handle_get_deferred_image_request", "", "", "", "", "GetDeferredImageResponse", "openapi"},
{Call::kVideosGenerate, "POST", "/v1/videos/generations", "handle_generate_video_request", "aspect_ratio,duration,image,keyframes,model,output,prompt,reference_audios,reference_images,resolution,storage_options,user", "", "last_frame@model-capabilities/video/reference-to-video", "GenerateVideoRequest", "StartDeferredResponse", "openapi"},
{Call::kVideosEdit, "POST", "/v1/videos/edits", "handle_edit_video_request", "model,output,prompt,storage_options,user,video", "", "", "EditVideoRequest", "StartDeferredResponse", "openapi"},
{Call::kVideosExtend, "POST", "/v1/videos/extensions", "handle_extend_video_request", "duration,model,output,prompt,storage_options,video", "", "", "ExtendVideoRequest", "StartDeferredResponse", "openapi"},
{Call::kVideosGet, "GET", "/v1/videos/{request_id}", "handle_get_deferred_video_request", "", "", "", "", "VideoResponse", "openapi"},
{Call::kEmbeddingsCreate, "POST", "/v1/embeddings", "handle_embedding_request", "dimensions,encoding_format,input,model,user", "", "", "EmbeddingRequest", "EmbeddingResponse", "openapi"},
{Call::kTokenizeText, "POST", "/v1/tokenize-text", "handle_tokenize_text_request", "model,text,user", "", "", "TokenizeRequest", "TokenizeResponse", "openapi"},
{Call::kModelsList, "GET", "/v1/models", "handle_models_list_request", "", "", "", "", "ListModelsResponse", "openapi"},
{Call::kModelsGet, "GET", "/v1/models/{model_id}", "handle_model_get_request", "", "", "", "", "Model", "openapi"},
{Call::kLanguageModelsList, "GET", "/v1/language-models", "handle_language_models_list_request", "", "", "", "", "ListLanguageModelsResponse", "openapi"},
{Call::kLanguageModelsGet, "GET", "/v1/language-models/{model_id}", "handle_language_model_get_request", "", "", "", "", "LanguageModel", "openapi"},
{Call::kImageModelsList, "GET", "/v1/image-generation-models", "handle_image_generation_models_list_request", "", "", "", "", "ListImageGenerationModelsResponse", "openapi"},
{Call::kImageModelsGet, "GET", "/v1/image-generation-models/{model_id}", "handle_image_generation_model_get_request", "", "", "", "", "ImageGenerationModel", "openapi"},
{Call::kVideoModelsList, "GET", "/v1/video-generation-models", "handle_video_generation_models_list_request", "", "", "", "", "ListVideoGenerationModelsResponse", "openapi"},
{Call::kVideoModelsGet, "GET", "/v1/video-generation-models/{model_id}", "handle_video_generation_model_get_request", "", "", "", "", "VideoGenerationModel", "openapi"},
{Call::kEmbeddingModelsList, "GET", "/v1/embedding-models", "handle_embedding_models_list_request", "", "", "", "", "ListEmbeddingModelsResponse", "openapi"},
{Call::kEmbeddingModelsGet, "GET", "/v1/embedding-models/{model_id}", "handle_embedding_model_get_request", "", "", "", "", "EmbeddingModel", "openapi"},
{Call::kApiKeyInfo, "GET", "/v1/api-key", "handle_get_api_key_info_request", "", "", "", "", "ApiKey", "openapi"},
{Call::kMe, "GET", "/v1/me", "handle_get_me_request", "", "", "", "", "GetMeResponse", "openapi"},
{Call::kSkillsList, "GET", "/v1/skills", "handle_list_skills_request", "", "limit,after,order", "", "", "SkillList", "openapi"},
{Call::kSkillsUpload, "POST", "/v1/skills", "handle_upload_skill_request", "files", "", "", "UploadSkillMultipartRequest", "Skill", "openapi"},
{Call::kSkillsGet, "GET", "/v1/skills/{skill_id}", "handle_retrieve_skill_request", "", "", "", "", "Skill", "openapi"},
{Call::kSkillsDelete, "DELETE", "/v1/skills/{skill_id}", "handle_delete_skill_request", "", "", "", "", "DeletedSkill", "openapi"},
{Call::kSkillsContent, "GET", "/v1/skills/{skill_id}/content", "handle_download_skill_content_request", "", "", "", "", "string", "openapi"},
{Call::kBatchCreate, "POST", "/v1/batches", "POST /v1/batches", "name", "", "input_file_id@advanced-api-usage/batch-api", "", "", "docs"},
{Call::kBatchList, "GET", "/v1/batches", "GET /v1/batches", "", "limit,pagination_token", "", "", "", "docs"},
{Call::kBatchGet, "GET", "/v1/batches/{batch_id}", "GET /v1/batches/{batch_id}", "", "", "", "", "", "docs"},
{Call::kBatchRequestsAdd, "POST", "/v1/batches/{batch_id}/requests", "POST /v1/batches/{batch_id}/requests", "batch_requests", "", "", "", "", "docs"},
{Call::kBatchRequestsList, "GET", "/v1/batches/{batch_id}/requests", "GET /v1/batches/{batch_id}/requests", "", "limit,pagination_token", "", "", "", "docs"},
{Call::kBatchResults, "GET", "/v1/batches/{batch_id}/results", "GET /v1/batches/{batch_id}/results", "", "limit,pagination_token", "", "", "", "docs"},
{Call::kBatchCancel, "POST", "/v1/batches/{batch_id}:cancel", "POST /v1/batches/{batch_id}:cancel", "", "", "", "", "", "docs"},
};
// CALLS-END
// Response schema fields this module reads (checked against the OpenAPI
// component schemas; a renamed or removed field fails the checker).
// SCHEMAS-BEGIN
static const SchemaFields kSchemas[] = {
{"ChatResponse", "choices,citations,created,id,model,object,output_files,service_tier,system_fingerprint,usage"},
{"Choice", "finish_reason,index,logprobs,message"},
{"ChoiceMessage", "content,reasoning_content,refusal,role,tool_calls"},
{"ChatResponseChunk", "choices,citations,created,id,model,object,output_files,service_tier,system_fingerprint,usage"},
{"ChoiceChunk", "delta,finish_reason,index,logprobs"},
{"Delta", "content,images,reasoning_content,role,tool_calls"},
{"ToolCall", "function,id,index,type"},
{"Function", "arguments,name"},
{"Usage", "completion_tokens,completion_tokens_details,cost_in_usd_ticks,num_sources_used,prompt_tokens,prompt_tokens_details,server_side_tool_usage_details,total_tokens"},
{"CompletionUsageDetail", "accepted_prediction_tokens,audio_tokens,reasoning_tokens,rejected_prediction_tokens"},
{"PromptUsageDetail", "audio_tokens,cached_tokens,image_tokens,text_tokens"},
{"ServerSideToolUsageDetails", "code_interpreter_calls,document_search_calls,file_search_calls,image_generation_calls,mcp_calls,web_search_calls,x_posts_fetched,x_search_calls,x_users_fetched"},
{"ModelResponse", "background,completed_at,created_at,error,id,incomplete_details,instructions,max_output_tokens,max_tool_calls,model,object,output,parallel_tool_calls,previous_response_id,reasoning,service_tier,status,store,temperature,text,tool_choice,tools,top_p,usage,user"},
{"ModelUsage", "context_details,cost_in_nano_usd,cost_in_usd_ticks,input_tokens,input_tokens_details,num_server_side_tools_used,num_sources_used,output_tokens,output_tokens_details,server_side_tool_usage_details,total_tokens"},
{"OutputMessage", "content,id,role,status,type"},
{"Annotation", "end_index,start_index,title,type,url"},
{"FunctionToolCall", "arguments,call_id,id,name,status,type"},
{"Reasoning", "content,encrypted_content,id,status,summary,type"},
{"WebSearchCall", "action,id,status,type"},
{"FileSearchCall", "id,queries,results,status,type"},
{"CodeInterpreterCall", "code,id,outputs,status,type"},
{"McpCall", "arguments,error,id,name,output,server_label,status,type"},
{"CustomToolCall", "call_id,id,input,name,status,type"},
{"ShellCall", "action,call_id,environment,id,status,type"},
{"ImageGenerationCall", "id,prompt,result,status,type"},
{"ToolSearchCall", "arguments,call_id,execution,id,status,type"},
{"ToolSearchOutput", "call_id,execution,id,status,tools,type"},
{"DeleteStoredCompletionResponse", "deleted,id,object"},
{"ListInputItemsResponse", "data,first_id,has_more,last_id,object"},
{"CompactResponse", "created_at,id,model,object,output,usage"},
{"CompactUsage", "dropped_message_count,input_tokens,output_tokens,total_tokens"},
{"GeneratedImageResponse", "data,usage"},
{"GeneratedImage", "b64_json,file_output,mime_type,storage_error,url"},
{"FileOutput", "expires_at,file_id,filename,public_url,public_url_error,public_url_expires_at"},
{"GetDeferredImageResponse", "data,error,request_id,status,usage"},
{"ImageError", "code,message"},
{"MediaUsage", "cost_in_usd_ticks,input_tokens,input_tokens_details,output_tokens,output_tokens_details,total_tokens"},
{"StartDeferredResponse", "request_id"},
{"StartDeferredChatResponse", "request_id"},
{"VideoResponse", "error,model,progress,status,usage,video"},
{"GeneratedVideo", "duration,file_output,respect_moderation,storage_error,url"},
{"VideoError", "code,message"},
{"EmbeddingResponse", "data,model,object,usage"},
{"Embedding", "embedding,index,object"},
{"EmbeddingUsage", "prompt_tokens,total_tokens"},
{"TokenizeResponse", "token_ids"},
{"TokenizeResponseToken", "string_token,token_bytes,token_id"},
{"Model", "aliases,cached_prompt_text_token_price,cached_prompt_text_token_price_long_context,capabilities,completion_text_token_price,completion_text_token_price_long_context,context_length,created,id,image_price,long_context_threshold,object,owned_by,pricing,prompt_image_token_price,prompt_text_token_price,prompt_text_token_price_long_context"},
{"ListModelsResponse", "data,object"},
{"LanguageModel", "aliases,cached_prompt_text_token_price,cached_prompt_text_token_price_long_context,capabilities,completion_text_token_price,completion_text_token_price_long_context,created,fingerprint,id,input_modalities,long_context_threshold,object,output_modalities,owned_by,prompt_image_token_price,prompt_text_token_price,prompt_text_token_price_long_context,search_price,version"},
{"ModelCapabilities", "default_reasoning_effort,reasoning_effort"},
{"ImageGenerationModel", "aliases,created,fingerprint,id,image_price,input_modalities,max_prompt_length,object,output_modalities,owned_by,pricing,version"},
{"ImagePricingTier", "price_per_image,quality,resolution"},
{"VideoGenerationModel", "aliases,created,fingerprint,id,input_modalities,object,output_modalities,owned_by,version"},
{"EmbeddingModel", "aliases,created,fingerprint,id,input_modalities,object,output_modalities,owned_by,prompt_image_token_price,prompt_text_token_price,version"},
{"ApiKey", "acls,api_key_blocked,api_key_disabled,api_key_id,create_time,modified_by,modify_time,name,redacted_api_key,team_blocked,team_id,user_id"},
{"GetMeResponse", "api_key,oauth,team_blocked,team_id,user_id,zdr_status"},
{"MeApiKeyInfo", "api_key_id,blocked,disabled,redacted_api_key"},
{"Skill", "created_at,default_version,description,id,latest_version,name,object"},
{"SkillList", "data,first_id,has_more,last_id,object"},
{"DeletedSkill", "deleted,id,object"},
{"MessageResponse", "content,id,model,role,stop_reason,stop_sequence,type,usage"},
{"MessageUsage", "cache_creation_input_tokens,cache_read_input_tokens,input_tokens,output_tokens"},
{"CompleteResponse", "completion,id,model,stop_reason,type"},
{"SampleResponse", "choices,created,id,model,object,system_fingerprint,usage"},
{"SampleChoice", "finish_reason,index,text"},
};
// SCHEMAS-END
// Server-side and client tool types the builders write, with the fields each
// builder sets (checked against the ModelTool variants).
// TOOLS-BEGIN
static const ToolFields kTools[] = {
{"function", "name,description,parameters,strict,defer_loading"},
{"web_search", "allowed_domains,excluded_domains,enable_image_search,enable_image_understanding,user_location"},
{"x_search", "allowed_x_handles,excluded_x_handles,from_date,to_date,enable_image_understanding,enable_video_understanding"},
{"image_generation", "action"},
{"file_search", "vector_store_ids,max_num_results"},
{"code_interpreter", "container"},
{"mcp", "server_label,server_url,server_description,allowed_tools,authorization,headers,defer_loading"},
{"shell", "environment"},
{"tool_search", "execution"},
};
// TOOLS-END
const CallSpec& spec_at(std::size_t index) { return kCalls[index]; }
std::size_t call_count() { return sizeof(kCalls) / sizeof(kCalls[0]); }
std::size_t tool_field_count() { return sizeof(kTools) / sizeof(kTools[0]); }
const ToolFields& tool_fields_at(std::size_t index) { return kTools[index]; }
const CallSpec& spec_of(Call call) {
for (const CallSpec& s : kCalls)
if (s.call == call) return s;
Check::fail("call is not in the table");
}
clients::Method method_of(Call call) {
const char* m = spec_of(call).http_method;
if (!std::strcmp(m, "GET")) return clients::Method::kGet;
if (!std::strcmp(m, "DELETE")) return clients::Method::kDelete;
return clients::Method::kPost;
}
namespace {
bool in_list(const char* list, const std::string& item) {
std::string l(list);
std::size_t pos = 0;
while (pos <= l.size()) {
std::size_t comma = l.find(',', pos);
std::string part = l.substr(pos, comma == std::string::npos ? std::string::npos : comma - pos);
std::size_t at = part.find('@');
if (at != std::string::npos) part = part.substr(0, at);
if (part == item) return true;
if (comma == std::string::npos) break;
pos = comma + 1;
}
return false;
}
std::string percent_encode(const std::string& value) {
static const char* hex = "0123456789ABCDEF";
std::string out;
for (unsigned char c : value) {
bool keep = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') ||
c == '-' || c == '_' || c == '.' || c == '~';
if (keep) {
out += static_cast<char>(c);
} else {
out += '%';
out += hex[c >> 4];
out += hex[c & 15];
}
}
return out;
}
} // namespace
bool declares_body_field(Call call, const std::string& field) {
const CallSpec& s = spec_of(call);
return in_list(s.body_fields, field) || in_list(s.doc_fields, field);
}
bool declares_query_param(Call call, const std::string& name) {
return in_list(spec_of(call).query_params, name);
}
std::string render(Call call, const std::vector<std::string>& ids) {
std::string tmpl = spec_of(call).path;
std::string out;
std::size_t used = 0;
for (std::size_t i = 0; i < tmpl.size(); ++i) {
if (tmpl[i] != '{') {
out += tmpl[i];
continue;
}
std::size_t close = tmpl.find('}', i);
if (close == std::string::npos) Check::fail("bad path template");
std::string name = tmpl.substr(i + 1, close - i - 1);
if (used >= ids.size()) Check::fail("missing " + name);
std::string label = name.size() > 3 && name.compare(name.size() - 3, 3, "_id") == 0
? name.substr(0, name.size() - 3)
: name;
Check::id(label, ids[used]);
out += ids[used++];
i = close;
}
if (used != ids.size()) Check::fail("surplus path ids");
return out;
}
Query& Query::add(Call call, const std::string& name, const std::string& value) {
if (!declares_query_param(call, name)) Check::fail("query parameter " + name + " is not in the call table");
if (pairs_.size() >= Caps::kMaxQueryParams) Check::fail("too many query parameters");
if (value.empty() || value.size() > Caps::kMaxQueryValueLen) Check::fail("bad value for " + name);
pairs_.emplace_back(name, value);
return *this;
}
Query& Query::add(Call call, const std::string& name, long value) {
return add(call, name, std::to_string(value));
}
std::string Query::str() const {
std::string out;
for (const auto& [k, v] : pairs_) out += (out.empty() ? "?" : "&") + k + "=" + percent_encode(v);
return out;
}
} // namespace molo::xai::core