#include "xai/core/calls.h" #include #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(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& 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