From 85015b1c33ed3232a2d17a6d0fdbc97381d220b3 Mon Sep 17 00:00:00 2001 From: retoor Date: Sat, 24 Oct 2026 08:05:20 +0200 Subject: [PATCH] feat(clients): xai platform: voice, files, collections, management API, key info Co-Authored-By: Claude Sonnet 5.5 --- example/app/ai/XaiPlatformDemo.cpp | 746 +++++++++++++++++- example/assets/ai_xai_platform.js | 62 ++ src/xai/platform/SPEC.md | 193 +++++ src/xai/platform/account.h | 21 + src/xai/platform/api_keys.cpp | 135 ++++ src/xai/platform/api_keys.h | 54 ++ src/xai/platform/audit.cpp | 50 ++ src/xai/platform/audit.h | 38 + src/xai/platform/billing.cpp | 130 +++ src/xai/platform/billing.h | 44 ++ src/xai/platform/calls.cpp | 118 +++ src/xai/platform/calls.h | 62 ++ src/xai/platform/caps.h | 59 ++ src/xai/platform/clients.cpp | 28 + src/xai/platform/clients.h | 46 ++ src/xai/platform/collections.cpp | 207 +++++ src/xai/platform/collections.h | 69 ++ src/xai/platform/documents_search.cpp | 70 ++ src/xai/platform/documents_search.h | 37 + src/xai/platform/files.cpp | 114 +++ src/xai/platform/files.h | 47 ++ src/xai/platform/platform_service.cpp | 118 +++ src/xai/platform/platform_service.h | 66 ++ src/xai/platform/realtime_rest.cpp | 147 ++++ src/xai/platform/realtime_rest.h | 54 ++ src/xai/platform/realtime_session.cpp | 311 ++++++++ src/xai/platform/realtime_session.h | 103 +++ src/xai/platform/session_config.cpp | 261 ++++++ src/xai/platform/session_config.h | 74 ++ src/xai/platform/socket.cpp | 175 ++++ src/xai/platform/socket.h | 74 ++ src/xai/platform/stt.cpp | 68 ++ src/xai/platform/stt.h | 43 + src/xai/platform/stt_stream.cpp | 153 ++++ src/xai/platform/stt_stream.h | 69 ++ src/xai/platform/tools/check_spec.py | 275 +++++++ src/xai/platform/tts.cpp | 87 ++ src/xai/platform/tts.h | 48 ++ src/xai/platform/tts_stream.cpp | 116 +++ src/xai/platform/tts_stream.h | 60 ++ src/xai/platform/voice_types.h | 53 ++ src/xai/platform/voices.cpp | 87 ++ src/xai/platform/voices.h | 38 + src/xai/platform/webhook.cpp | 181 +++++ src/xai/platform/webhook.h | 46 ++ src/xai/platform/ws_events.cpp | 149 ++++ src/xai/platform/ws_events.h | 44 ++ .../example/ai/xai/platform/confirm_test.cpp | 59 ++ tests/example/ai/xai/platform/local_test.cpp | 81 ++ tests/example/ai/xai/platform/page_test.cpp | 22 + tests/example/ai/xai/platform/routes_test.cpp | 64 ++ tests/example/ai/xai/platform/status_test.cpp | 29 + tests/src/xai/platform/rig.h | 84 ++ tests/src/xai/platform/test_live.cpp | 94 +++ tests/src/xai/platform/test_rest.cpp | 449 +++++++++++ tests/src/xai/platform/test_voice.cpp | 432 ++++++++++ tests/src/xai/platform/test_ws.cpp | 384 +++++++++ 57 files changed, 6925 insertions(+), 3 deletions(-) create mode 100644 example/assets/ai_xai_platform.js create mode 100644 src/xai/platform/SPEC.md create mode 100644 src/xai/platform/account.h create mode 100644 src/xai/platform/api_keys.cpp create mode 100644 src/xai/platform/api_keys.h create mode 100644 src/xai/platform/audit.cpp create mode 100644 src/xai/platform/audit.h create mode 100644 src/xai/platform/billing.cpp create mode 100644 src/xai/platform/billing.h create mode 100644 src/xai/platform/calls.cpp create mode 100644 src/xai/platform/calls.h create mode 100644 src/xai/platform/caps.h create mode 100644 src/xai/platform/clients.cpp create mode 100644 src/xai/platform/clients.h create mode 100644 src/xai/platform/collections.cpp create mode 100644 src/xai/platform/collections.h create mode 100644 src/xai/platform/documents_search.cpp create mode 100644 src/xai/platform/documents_search.h create mode 100644 src/xai/platform/files.cpp create mode 100644 src/xai/platform/files.h create mode 100644 src/xai/platform/platform_service.cpp create mode 100644 src/xai/platform/platform_service.h create mode 100644 src/xai/platform/realtime_rest.cpp create mode 100644 src/xai/platform/realtime_rest.h create mode 100644 src/xai/platform/realtime_session.cpp create mode 100644 src/xai/platform/realtime_session.h create mode 100644 src/xai/platform/session_config.cpp create mode 100644 src/xai/platform/session_config.h create mode 100644 src/xai/platform/socket.cpp create mode 100644 src/xai/platform/socket.h create mode 100644 src/xai/platform/stt.cpp create mode 100644 src/xai/platform/stt.h create mode 100644 src/xai/platform/stt_stream.cpp create mode 100644 src/xai/platform/stt_stream.h create mode 100644 src/xai/platform/tools/check_spec.py create mode 100644 src/xai/platform/tts.cpp create mode 100644 src/xai/platform/tts.h create mode 100644 src/xai/platform/tts_stream.cpp create mode 100644 src/xai/platform/tts_stream.h create mode 100644 src/xai/platform/voice_types.h create mode 100644 src/xai/platform/voices.cpp create mode 100644 src/xai/platform/voices.h create mode 100644 src/xai/platform/webhook.cpp create mode 100644 src/xai/platform/webhook.h create mode 100644 src/xai/platform/ws_events.cpp create mode 100644 src/xai/platform/ws_events.h create mode 100644 tests/example/ai/xai/platform/confirm_test.cpp create mode 100644 tests/example/ai/xai/platform/local_test.cpp create mode 100644 tests/example/ai/xai/platform/page_test.cpp create mode 100644 tests/example/ai/xai/platform/routes_test.cpp create mode 100644 tests/example/ai/xai/platform/status_test.cpp create mode 100644 tests/src/xai/platform/rig.h create mode 100644 tests/src/xai/platform/test_live.cpp create mode 100644 tests/src/xai/platform/test_rest.cpp create mode 100644 tests/src/xai/platform/test_voice.cpp create mode 100644 tests/src/xai/platform/test_ws.cpp diff --git a/example/app/ai/XaiPlatformDemo.cpp b/example/app/ai/XaiPlatformDemo.cpp index 3d7d097..bdd277a 100644 --- a/example/app/ai/XaiPlatformDemo.cpp +++ b/example/app/ai/XaiPlatformDemo.cpp @@ -1,13 +1,753 @@ #include "../AiDemos.hpp" +#include +#include + #include "../../fw/Router.hpp" +#include "../../fw/Templates.hpp" +#include "llm/api_client.h" +#include "llm/config.h" +#include "security/crypto/Base64.h" +#include "xai/platform/account.h" +#include "xai/platform/api_keys.h" +#include "xai/platform/audit.h" +#include "xai/platform/billing.h" +#include "xai/platform/calls.h" +#include "xai/platform/clients.h" +#include "xai/platform/collections.h" +#include "xai/platform/documents_search.h" +#include "xai/platform/files.h" +#include "xai/platform/realtime_rest.h" +#include "xai/platform/realtime_session.h" +#include "xai/platform/stt.h" +#include "xai/platform/tts.h" +#include "xai/platform/voices.h" +#include "xai/platform/webhook.h" namespace molo::example::app { -// xAI Grok: voice/realtime, collections, files, management API. Stub: the module agent fills this in. +// xAI platform: voice (realtime agent, TTS, STT), collections, files, the +// management API (keys, billing, usage, audit) and key info, over the real +// src/xai/platform part. GET routes need no credential. Every route that +// calls xAI is a POST: 503 not_configured without the key it needs +// (XAI_API_KEY or XAI_MANAGEMENT_KEY), 422 on bad input. Destructive or +// paid calls are dry runs unless the body says "confirm":true. + +namespace { + +namespace xp = xai::platform; +using Json = clients::body::Json; + +constexpr std::size_t kMaxBody = 4u * 1024u * 1024u; + +const char kPage[] = R"XAIP({% extends "base.html" %} +{% block content %} +

xAI Platform

+

Voice, collections, files and the management API. Destructive and +paid calls are dry runs until the body says "confirm":true.

+

Checking xAI keys...

+
+ + +
+ +

+
+ + +{% endblock %} +)XAIP"; + +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); } + +// Maps service errors onto the demo's status contract. +template +auto guarded(F&& f) -> decltype(f()) { + try { + return f(); + } catch (const llm::NotConfiguredError& e) { + throw fw::HttpError(503, "not_configured", e.message()); + } catch (const llm::ApiError& e) { + if (e.http_status() == 400 && e.type() == "INVALID_ARGUMENT") bad(e.message()); + throw fw::HttpError(502, "xai_error", + "HTTP " + std::to_string(e.http_status()) + " " + e.type() + ": " + e.message()); + } catch (const clients::body::JsonError&) { + bad("body is not valid JSON"); + } +} + +// One request body with typed, validated accessors (422 on a wrong type). +class Body { + public: + explicit Body(const fw::Request& req) { + if (req.body.size() > kMaxBody) throw fw::HttpError(413, "payload_too_large", "body too large"); + if (req.body.empty()) { + doc_ = Json::object(); + return; + } + try { + doc_ = Json::parse(req.body); + } catch (const clients::body::JsonError&) { + bad("body is not valid JSON"); + } + if (!doc_.is_object()) bad("body must be a JSON object"); + } + + std::string text(const char* key, bool required = false) const { + const Json* v = doc_.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(); + } + long number(const char* key, long fallback = 0) const { + const Json* v = doc_.find(key); + if (!v || v->is_null()) return fallback; + if (!v->is_number()) bad(std::string(key) + " must be a number"); + return v->as_int(); + } + double real(const char* key, double fallback = 0) const { + const Json* v = doc_.find(key); + if (!v || v->is_null()) return fallback; + if (!v->is_number()) bad(std::string(key) + " must be a number"); + return v->as_number(); + } + bool flag(const char* key) const { + const Json* v = doc_.find(key); + if (!v || v->is_null()) return false; + if (!v->is_bool()) bad(std::string(key) + " must be true or false"); + return v->as_bool(); + } + Json object(const char* key) const { + const Json* v = doc_.find(key); + if (!v || v->is_null()) return Json(); + if (!v->is_object()) bad(std::string(key) + " must be an object"); + return *v; + } + Json array(const char* key) const { + const Json* v = doc_.find(key); + if (!v || v->is_null()) return Json(); + if (!v->is_array()) bad(std::string(key) + " must be an array"); + return *v; + } + std::vector strings(const char* key) const { + std::vector out; + Json a = array(key); + if (a.is_null()) return out; + for (const Json& s : a.as_array()) { + if (!s.is_string()) bad(std::string(key) + " must hold strings"); + out.push_back(s.as_string()); + } + return out; + } + // Base64 payload -> bytes. + std::string bytes(const char* key) const { + std::string b64 = text(key), raw; + if (b64.empty()) return raw; + if (!security::crypto::Base64::decode(b64, raw)) bad(std::string(key) + " is not valid base64"); + return raw; + } + bool confirm() const { return flag("confirm"); } + const Json& doc() const { return doc_; } + + private: + Json doc_ = Json::object(); +}; + +Json dry_run(xp::Call call, std::initializer_list segments) { + Json o = Json::object(); + o.set("dry_run", Json(true)); + o.set("http", Json(xp::spec_of(call).http_method)); + o.set("path", Json(xp::render(call, segments))); + o.set("host", Json(xp::spec_of(call).host)); + o.set("hint", Json("send \"confirm\":true to run it")); + return o; +} + +std::string b64(const std::string& raw) { return security::crypto::Base64::encode(raw); } + +// All handlers share the clients built from the environment at request time. +class XaiPlatformRoutes { + public: + Json account(const Body& b) const { + xp::AccountService svc(clients().api()); + std::string a = b.text("action", true); + if (a == "api_key") return guarded([&] { return svc.api_key_info(); }); + if (a == "me") return guarded([&] { return svc.me(); }); + bad("action must be api_key or me"); + } + + Json files(const Body& b) const { + xp::FilesService svc(clients().api()); + std::string a = b.text("action", true); + std::string id = a == "list" || a == "upload" ? "" : b.text("id", true); + if (a == "list") { + xp::FileListOptions o; + o.limit = static_cast(b.number("limit")); + o.order = b.text("order"); + o.sort_by = b.text("sort_by"); + o.filter = b.text("filter"); + o.pagination_token = b.text("pagination_token"); + return guarded([&] { return svc.list(o); }); + } + if (a == "list_all") { + return guarded([&] { + xp::FileListing l = svc.list_all(static_cast(b.number("max_pages", 5)), b.text("filter")); + Json o = Json::object(); + o.set("files", l.files); + o.set("truncated", Json(l.truncated)); + o.set("pages", Json(static_cast(l.pages))); + return o; + }); + } + if (a == "upload") { + std::string name = b.text("filename", true); + std::string data = b.bytes("data_base64"); + return guarded([&] { + return svc.upload(name, b.text("content_type") .empty() ? "application/octet-stream" : b.text("content_type"), + data, b.number("expires_after"), b.text("purpose")); + }); + } + if (a == "get") return guarded([&] { return svc.get(id); }); + if (a == "content") { + return guarded([&] { + llm::RawResponse r = svc.content(id, b.text("format")); + Json o = Json::object(); + o.set("content_type", Json(r.content_type)); + o.set("bytes", Json(static_cast(r.body.size()))); + // Text goes through; binary comes back base64 (bounded by the body cap). + o.set(b.text("format") == "text" ? "text" : "data_base64", + Json(b.text("format") == "text" ? r.body : b64(r.body))); + return o; + }); + } + if (a == "public_url") return guarded([&] { return svc.create_public_url(id, b.number("expires_after")); }); + if (a == "revoke_url") { + if (!b.confirm()) return guarded([&] { svc.check_id("file", id); return dry_run(xp::Call::kPublicUrlRevoke, {id}); }); + return guarded([&] { return svc.revoke_public_url(id, true); }); + } + if (a == "delete") { + if (!b.confirm()) return guarded([&] { svc.check_id("file", id); return dry_run(xp::Call::kFileDelete, {id}); }); + return guarded([&] { return svc.remove(id, true); }); + } + bad("action must be list, list_all, upload, get, content, public_url, revoke_url or delete"); + } + + Json collections(const Body& b) const { + xp::CollectionsService svc(clients().management()); + std::string a = b.text("action", true); + auto cid = [&] { return b.text("collection_id", true); }; + auto fid = [&] { return b.text("file_id", true); }; + xp::ListOptions lo; + lo.team_id = b.text("team_id"); + lo.limit = static_cast(b.number("limit")); + lo.order = b.text("order"); + lo.sort_by = b.text("sort_by"); + lo.filter = b.text("filter"); + lo.name = b.text("name"); + lo.pagination_token = b.text("pagination_token"); + if (a == "list") return guarded([&] { return svc.list(lo); }); + if (a == "create" || a == "update") { + xp::CollectionSpec s; + s.name = b.text("collection_name"); + s.description = b.text("collection_description"); + s.embedding_model = b.text("embedding_model"); + s.metric_space = b.text("metric_space"); + s.chunk_configuration = b.object("chunk_configuration"); + s.field_definitions = b.array("field_definitions"); + s.team_id = lo.team_id; + if (a == "create") return guarded([&] { return svc.create(s); }); + std::string id = cid(); + return guarded([&] { return svc.update(id, s, b.array("field_definition_updates")); }); + } + if (a == "get") { std::string id = cid(); return guarded([&] { return svc.get(id, lo.team_id); }); } + if (a == "delete") { + std::string id = cid(); + if (!b.confirm()) return guarded([&] { svc.check_id("collection", id); return dry_run(xp::Call::kCollectionDelete, {id}); }); + return guarded([&] { return svc.remove(id, true, lo.team_id); }); + } + if (a == "add_document") { std::string c = cid(), f = fid(); return guarded([&] { return svc.add_document(c, f, b.object("fields"), lo.team_id); }); } + if (a == "upload_document") { + std::string c = cid(), n = b.text("name", true), data = b.bytes("data_base64"); + return guarded([&] { + return svc.upload_document(c, n, b.text("content_type").empty() ? "application/octet-stream" : b.text("content_type"), + data, b.object("fields")); + }); + } + if (a == "list_documents") { std::string c = cid(); return guarded([&] { return svc.list_documents(c, lo); }); } + if (a == "get_document") { std::string c = cid(), f = fid(); return guarded([&] { return svc.get_document(c, f, lo.team_id); }); } + if (a == "reindex_document") { std::string c = cid(), f = fid(); return guarded([&] { return svc.reindex_document(c, f, lo.team_id); }); } + if (a == "remove_document") { + std::string c = cid(), f = fid(); + if (!b.confirm()) return guarded([&] { svc.check_id("collection", c); svc.check_id("file", f); return dry_run(xp::Call::kDocRemove, {c, f}); }); + return guarded([&] { return svc.remove_document(c, f, true, lo.team_id); }); + } + if (a == "batch_get") { std::string c = cid(); return guarded([&] { return svc.batch_get(c, b.strings("file_ids"), lo.team_id); }); } + bad("unknown collections action"); + } + + Json search(const Body& b) const { + xp::DocumentSearch svc(clients().api()); + xp::DocumentSearchRequest q; + q.query = b.text("query", true); + q.collection_ids = b.strings("collection_ids"); + q.rag_pipeline = b.text("rag_pipeline"); + q.filter = b.text("filter"); + q.instructions = b.text("instructions"); + q.limit = static_cast(b.number("limit")); + q.ranking_metric = b.text("ranking_metric"); + q.retrieval_mode = b.text("retrieval_mode"); + q.retrieval_options = b.object("retrieval_options"); + q.group_by = b.object("group_by"); + return guarded([&] { return svc.search(q); }); + } + + Json voices(const Body& b) const { + xp::VoicesService svc(clients().api()); + std::string a = b.text("action", true); + std::string id = a == "list" || a == "custom_list" ? "" : b.text("voice_id", true); + if (a == "list") return guarded([&] { return svc.tts_voices(); }); + if (a == "get") return guarded([&] { return svc.tts_voice(id); }); + if (a == "custom_list") return guarded([&] { return svc.list_custom(static_cast(b.number("limit")), b.text("pagination_token")); }); + if (a == "custom_get") return guarded([&] { return svc.get_custom(id); }); + if (a == "custom_patch") return guarded([&] { return svc.patch_custom(id, b.object("changes")); }); + if (a == "custom_delete") { + if (!b.confirm()) return guarded([&] { svc.check_id("voice", id); return dry_run(xp::Call::kCustomVoiceDelete, {id}); }); + return guarded([&] { return svc.remove_custom(id, true); }); + } + bad("action must be list, get, custom_list, custom_get, custom_patch or custom_delete"); + } + + Json tts(const Body& b) const { + xp::TextToSpeech svc(clients().api()); + xp::TtsRequest q; + q.text = b.text("text", true); + q.language = b.text("language").empty() ? "en" : b.text("language"); + q.voice_id = b.text("voice_id"); + q.codec = b.text("codec"); + q.sample_rate = static_cast(b.number("sample_rate")); + q.bit_rate = static_cast(b.number("bit_rate")); + q.optimize_streaming_latency = static_cast(b.number("optimize_streaming_latency")); + q.speed = b.real("speed"); + q.text_normalization = b.flag("text_normalization"); + q.with_timestamps = b.flag("with_timestamps"); + if (b.object("replace").is_object()) + for (const auto& [k, v] : b.object("replace").as_object()) { + if (!v.is_string()) bad("replace values must be strings"); + q.replace[k] = v.as_string(); + } + Json body = guarded([&] { return svc.build(q); }); + if (!b.confirm()) { + Json o = dry_run(xp::Call::kTts, {}); + o.set("request", body); + return o; + } + return guarded([&] { + xp::TtsResult r = svc.synthesize(q); + Json o = Json::object(); + o.set("content_type", Json(r.content_type)); + o.set("bytes", Json(static_cast(r.audio.size()))); + o.set("audio_base64", Json(b64(r.audio))); + if (q.with_timestamps) { + o.set("duration", Json(r.duration)); + o.set("audio_timestamps", r.timestamps); + } + return o; + }); + } + + Json stt(const Body& b) const { + xp::SpeechToText svc(clients().api()); + xp::SttRequest q; + q.url = b.text("url"); + q.data = b.bytes("data_base64"); + q.filename = b.text("filename").empty() ? "audio" : b.text("filename"); + q.content_type = b.text("content_type").empty() ? "application/octet-stream" : b.text("content_type"); + q.model = b.text("model"); + q.audio_format = b.text("audio_format"); + q.sample_rate = static_cast(b.number("sample_rate")); + q.language = b.text("language"); + q.format = b.flag("format"); + q.multichannel = b.flag("multichannel"); + q.channels = static_cast(b.number("channels")); + q.diarize = b.flag("diarize"); + q.keyterms = b.strings("keyterms"); + q.filler_words = b.flag("filler_words"); + q.vad_threshold = b.real("vad_threshold", -1); + guarded([&] { return svc.build(q).encoded_size(); }); // validate before anything else + if (!b.confirm()) return dry_run(xp::Call::kStt, {}); + return guarded([&] { return svc.transcribe(q); }); + } + + Json client_secret(const Body& b) const { + xp::RealtimeRest svc(clients().api()); + xp::ClientSecretRequest q; + q.expires_seconds = b.number("expires_seconds"); + q.model = b.text("model"); + q.reasoning_effort = b.text("reasoning_effort"); + Json body = guarded([&] { return svc.build_client_secret(q); }); + if (!b.confirm()) { + Json o = dry_run(xp::Call::kClientSecret, {}); + o.set("request", body); + return o; + } + return guarded([&] { return svc.client_secret(q); }); + } + + static xp::SessionConfig session_config(const Body& b) { + xp::SessionConfig c; + c.model = b.text("model"); + c.instructions = b.text("instructions"); + c.reasoning_effort = b.text("reasoning_effort"); + c.voice = b.text("voice"); + std::string turns = b.text("turn_detection"); + if (turns == "server_vad") c.turns = xp::SessionConfig::Turns::kServerVad; + else if (turns == "manual") c.turns = xp::SessionConfig::Turns::kManual; + else if (!turns.empty()) bad("turn_detection must be server_vad or manual"); + c.idle_timeout_ms = b.number("idle_timeout_ms"); + c.input.type = b.text("input_type"); + c.input.rate = static_cast(b.number("input_rate")); + c.output.type = b.text("output_type"); + c.output.rate = static_cast(b.number("output_rate")); + c.language_hint = b.text("language_hint"); + c.keyterms = b.strings("keyterms"); + c.output_speed = b.real("output_speed"); + Json tools = b.array("tools"); + if (tools.is_array()) for (const Json& t : tools.as_array()) c.tools.push_back(t); + if (b.object("replace").is_object()) + for (const auto& [k, v] : b.object("replace").as_object()) { + if (!v.is_string()) bad("replace values must be strings"); + c.replace[k] = v.as_string(); + } + return c; + } + + Json session_preview(const Body& b) const { + xp::SessionConfig c = session_config(b); + return guarded([&] { return c.update_message(); }); + } + + // One shot: connect, configure, one user text turn, fold the response. + Json session(const Body& b) const { + xp::SessionConfig c = session_config(b); + std::string text = b.text("text", true); + Json update = guarded([&] { return c.update_message(); }); + if (text.size() > xp::PlatformCaps::kMaxItemTextChars) bad("text too long"); + if (!b.confirm()) { + Json o = Json::object(); + o.set("dry_run", Json(true)); + o.set("http", Json("WEBSOCKET")); + o.set("path", Json(xp::PlatformEndpoints::kRealtimeUrl)); + o.set("session_update", update); + o.set("hint", Json("send \"confirm\":true to run it")); + return o; + } + return guarded([&] { + std::string key = llm::Config::get(xp::PlatformEndpoints::kApiKeyEnv); + if (key.empty()) throw llm::NotConfiguredError("xai", xp::PlatformEndpoints::kApiKeyEnv); + xp::RealtimeOptions o; + o.model = c.model; + xp::RealtimeSession s(key, o); + s.connect(); + s.update_session(c); + s.add_user_text(text); + s.create_response(); + xp::RealtimeResponse r = s.run_response(static_cast(b.number("max_wait_ms", 30000))); + s.close(); + Json out = Json::object(); + out.set("status", Json(r.status)); + out.set("transcript", Json(r.transcript)); + out.set("text", Json(r.text)); + out.set("audio_bytes", Json(static_cast(r.audio.size()))); + out.set("usage", r.usage); + out.set("events", Json(static_cast(r.events.size()))); + Json calls = Json::array(); + for (const xp::FunctionCall& f : r.calls) { + Json j = Json::object(); + j.set("call_id", Json(f.call_id)); + j.set("name", Json(f.name)); + j.set("arguments", Json(f.arguments)); + calls.push(j); + } + out.set("function_calls", calls); + Json errs = Json::array(); + for (const std::string& e : r.errors) errs.push(Json(e)); + out.set("errors", errs); + out.set("truncated", Json(r.truncated)); + return out; + }); + } + + Json phone_numbers(const Body& b) const { + xp::RealtimeRest svc(clients().api()); + std::string a = b.text("action", true); + if (a == "list") return guarded([&] { return svc.list_phone_numbers(static_cast(b.number("limit")), b.text("pagination_token"), b.text("agent_id")); }); + if (a == "create") { + xp::PhoneNumberSpec s; + if (!b.text("origin").empty()) s.origin = b.text("origin"); + s.name = b.text("name"); + s.agent_id = b.text("agent_id"); + s.area_code = b.text("area_code"); + s.phone_number = b.text("phone_number"); + s.sip_username = b.text("sip_username"); + s.sip_password = b.text("sip_password"); + s.allowed_addresses = b.strings("allowed_addresses"); + s.webhook_url = b.text("webhook_url"); + s.webhook_name = b.text("webhook_name"); + Json body = guarded([&] { return svc.build_phone_number(s); }); + if (!b.confirm()) { + Json o = dry_run(xp::Call::kPhoneCreate, {}); + o.set("request", body); + return o; + } + return guarded([&] { return svc.create_phone_number(s); }); + } + if (a == "delete") { + std::string id = b.text("phone_number_id", true); + if (!b.confirm()) return guarded([&] { svc.check_id("phone number", id); return dry_run(xp::Call::kPhoneDelete, {id}); }); + return guarded([&] { return svc.remove_phone_number(id, true); }); + } + bad("action must be list, create or delete"); + } + + Json calls(const Body& b) const { + xp::RealtimeRest svc(clients().api()); + std::string a = b.text("action", true), id = b.text("call_id", true); + if (a != "refer" && a != "hangup") bad("action must be refer or hangup"); + std::string target = a == "refer" ? b.text("target_uri", true) : ""; + if (!b.confirm()) { + return guarded([&] { + svc.check_id("call", id); + return dry_run(a == "refer" ? xp::Call::kCallRefer : xp::Call::kCallHangup, {id}); + }); + } + return guarded([&] { return a == "refer" ? svc.refer_call(id, target, true) : svc.hangup_call(id, true); }); + } + + // Local: checks a signed realtime.call.incoming webhook with the secret. + Json webhook_verify(const Body& b) const { + xp::WebhookHeaders h; + h.id = b.text("webhook_id", true); + h.timestamp = b.text("webhook_timestamp", true); + h.signature = b.text("webhook_signature", true); + std::string body = b.text("body", true); + long now = b.number("now", static_cast(std::time(nullptr))); + return guarded([&] { + xp::WebhookVerifier v(b.text("secret", true)); + xp::IncomingCall c = v.parse_incoming(h, body, now); + Json o = Json::object(); + o.set("valid", Json(true)); + o.set("call_id", Json(c.call_id)); + o.set("join", Json(std::string(xp::PlatformEndpoints::kRealtimeUrl) + "?call_id=" + c.call_id)); + return o; + }); + } + + Json keys(const Body& b) const { + xp::ApiKeysService svc(clients().management()); + std::string a = b.text("action", true); + std::string team = b.text("team_id"); + std::string kid = b.text("api_key_id"); + if (a == "validate") return guarded([&] { return svc.validate_management_key(); }); + if (a == "list") { + return guarded([&] { + return svc.list(team, static_cast(b.number("page_size")), b.text("pagination_token"), + b.flag("active_only"), b.strings("acl_filters")); + }); + } + if (a == "list_all") { + return guarded([&] { + xp::KeyListing l = svc.list_all(team, static_cast(b.number("max_pages", 5)), + static_cast(b.number("page_size", 50))); + Json o = Json::object(); + o.set("keys", l.keys); + o.set("truncated", Json(l.truncated)); + o.set("pages", Json(static_cast(l.pages))); + return o; + }); + } + if (a == "models") return guarded([&] { return svc.team_models(team); }); + if (a == "endpoints") return guarded([&] { return svc.team_endpoints(team); }); + if (a == "propagation") return guarded([&] { return svc.propagation(kid); }); + if (a == "create") { + xp::ApiKeySpec s; + s.name = b.text("name"); + s.acls = b.strings("acls"); + s.qps = b.number("qps"); + s.qpm = b.number("qpm"); + s.tpm = b.number("tpm"); + s.expire_time = b.text("expire_time"); + return guarded([&] { return svc.create(team, s); }); + } + if (a == "update") return guarded([&] { return svc.update(kid, b.object("changes")); }); + if (a == "rotate") { + if (!b.confirm()) return guarded([&] { svc.check_id("api key", kid); return dry_run(xp::Call::kKeyRotate, {kid}); }); + return guarded([&] { return svc.rotate(kid, true, b.text("expire_time"), b.text("old_secret_expire_time")); }); + } + if (a == "delete") { + if (!b.confirm()) return guarded([&] { svc.check_id("api key", kid); return dry_run(xp::Call::kKeyDelete, {kid}); }); + return guarded([&] { return svc.remove(kid, true); }); + } + bad("unknown keys action"); + } + + Json billing(const Body& b) const { + xp::BillingService svc(clients().management()); + std::string a = b.text("action", true), team = b.text("team_id"); + if (a == "info") return guarded([&] { return svc.billing_info(team); }); + if (a == "payment_methods") return guarded([&] { return svc.payment_methods(team); }); + if (a == "invoice_preview") return guarded([&] { return svc.invoice_preview(team); }); + if (a == "spending_limits") return guarded([&] { return svc.spending_limits(team); }); + if (a == "prepaid_balance") return guarded([&] { return svc.prepaid_balance(team); }); + if (a == "invoices") { + xp::InvoiceQuery q; + q.cycle_year = static_cast(b.number("cycle_year")); + q.cycle_month = static_cast(b.number("cycle_month")); + q.since_year = static_cast(b.number("since_year")); + q.since_month = static_cast(b.number("since_month")); + q.invoice_ids = b.strings("invoice_ids"); + return guarded([&] { return svc.invoices(team, q); }); + } + if (a == "usage") return guarded([&] { return svc.usage(team, b.object("analytics_request")); }); + // Money and billing state: dry run unless confirmed. + struct Mut { const char* name; xp::Call call; }; + for (const Mut& m : {Mut{"set_info", xp::Call::kBillingInfoSet}, Mut{"set_default_payment_method", xp::Call::kPaymentDefault}, + Mut{"set_spending_limit", xp::Call::kSpendingSet}, Mut{"top_up", xp::Call::kPrepaidTopUp}}) { + if (a != m.name) continue; + if (!b.confirm()) return guarded([&] { svc.require_uuid("team_id", team); return dry_run(m.call, {team}); }); + return guarded([&]() -> Json { + if (a == "set_info") return svc.set_billing_info(team, b.object("billing_info"), true); + if (a == "set_default_payment_method") return svc.set_default_payment_method(team, b.text("payment_method_id"), true); + if (a == "set_spending_limit") return svc.set_soft_spending_limit(team, b.text("amount"), true); + return svc.top_up(team, b.text("amount"), true); + }); + } + bad("unknown billing action"); + } + + Json audit(const Body& b) const { + xp::AuditService svc(clients().management()); + xp::AuditQuery q; + q.page_size = static_cast(b.number("page_size")); + q.page_token = b.text("page_token"); + q.user_id = b.text("user_id"); + q.query = b.text("query"); + q.event_id = b.text("event_id"); + q.time_from = b.text("time_from"); + q.time_to = b.text("time_to"); + q.order_by = b.text("order_by"); + std::string team = b.text("team_id"); + return guarded([&] { return svc.events(team, q); }); + } + + private: + static xp::PlatformClients clients() { return xp::PlatformClients::from_env(); } +}; + +} // namespace + void register_ai_xaiplatform_demo(fw::Router& router, Services& services) { - (void)router; - (void)services; + fw::Environment* env = services.templates.get(); + services.templates->add_template("ai_xai_platform.html", kPage); + services.add_feature("ai-xai-platform", "/ai/xai/platform"); + + auto routes = std::make_shared(); + + router.get("/ai/xai/platform", "ai-xai-platform-page", [env](fw::Request req) { + (void)req; + fw::TemplateCtx ctx; + ctx["title"] = std::string("xAI Platform"); + return fw::Response(200, env->render("ai_xai_platform.html", ctx), "text/html; charset=utf-8"); + }); + + router.get("/ai/xai/platform/status", "ai-xai-platform-status", [](fw::Request req) { + (void)req; + Json o = Json::object(); + o.set("api_key_configured", Json(!llm::Config::get(xp::PlatformEndpoints::kApiKeyEnv).empty())); + o.set("management_key_configured", Json(!llm::Config::get(xp::PlatformEndpoints::kManagementKeyEnv).empty())); + o.set("api_base", Json(xp::PlatformEndpoints::kApiBase)); + o.set("management_base", Json(xp::PlatformEndpoints::kManagementBase)); + o.set("realtime_url", Json(xp::PlatformEndpoints::kRealtimeUrl)); + o.set("calls", Json(static_cast(xp::call_count()))); + o.set("max_body_bytes", Json(static_cast(kMaxBody))); + return json_out(o); + }); + + router.get("/ai/xai/platform/calls", "ai-xai-platform-calls", [](fw::Request req) { + (void)req; + Json arr = Json::array(); + for (std::size_t i = 0; i < xp::call_count(); ++i) { + const xp::CallSpec& s = xp::spec_at(i); + Json row = Json::object(); + row.set("http", Json(s.http_method)); + row.set("host", Json(s.host)); + row.set("path", Json(s.path)); + row.set("source", Json(s.source)); + arr.push(row); + } + Json o = Json::object(); + o.set("calls", arr); + return json_out(o); + }); + + using Handler = Json (XaiPlatformRoutes::*)(const Body&) const; + struct Route { const char* path; const char* name; Handler handler; }; + const Route table[] = { + {"/ai/xai/platform/account", "ai-xai-platform-account", &XaiPlatformRoutes::account}, + {"/ai/xai/platform/files", "ai-xai-platform-files", &XaiPlatformRoutes::files}, + {"/ai/xai/platform/collections", "ai-xai-platform-collections", &XaiPlatformRoutes::collections}, + {"/ai/xai/platform/search", "ai-xai-platform-search", &XaiPlatformRoutes::search}, + {"/ai/xai/platform/voices", "ai-xai-platform-voices", &XaiPlatformRoutes::voices}, + {"/ai/xai/platform/tts", "ai-xai-platform-tts", &XaiPlatformRoutes::tts}, + {"/ai/xai/platform/stt", "ai-xai-platform-stt", &XaiPlatformRoutes::stt}, + {"/ai/xai/platform/realtime/secret", "ai-xai-platform-secret", &XaiPlatformRoutes::client_secret}, + {"/ai/xai/platform/realtime/session", "ai-xai-platform-session", &XaiPlatformRoutes::session}, + {"/ai/xai/platform/realtime/session/preview", "ai-xai-platform-session-preview", &XaiPlatformRoutes::session_preview}, + {"/ai/xai/platform/realtime/phone-numbers", "ai-xai-platform-phones", &XaiPlatformRoutes::phone_numbers}, + {"/ai/xai/platform/realtime/calls", "ai-xai-platform-calls-control", &XaiPlatformRoutes::calls}, + {"/ai/xai/platform/webhook/verify", "ai-xai-platform-webhook", &XaiPlatformRoutes::webhook_verify}, + {"/ai/xai/platform/keys", "ai-xai-platform-keys", &XaiPlatformRoutes::keys}, + {"/ai/xai/platform/billing", "ai-xai-platform-billing", &XaiPlatformRoutes::billing}, + {"/ai/xai/platform/audit", "ai-xai-platform-audit", &XaiPlatformRoutes::audit}, + }; + for (const Route& r : table) { + Handler h = r.handler; + router.post(r.path, r.name, [routes, h](fw::Request req) { + Body body(req); + return json_out(((*routes).*h)(body)); + }); + } } } // namespace molo::example::app diff --git a/example/assets/ai_xai_platform.js b/example/assets/ai_xai_platform.js new file mode 100644 index 0000000..33643a4 --- /dev/null +++ b/example/assets/ai_xai_platform.js @@ -0,0 +1,62 @@ +// xAI Platform page: thin client over /ai/xai/platform/* (all limits server side). +(function () { + "use strict"; + var $ = function (id) { return document.getElementById(id); }; + var out = $("xp-out"), err = $("xp-error"); + + // One example body per route. Ids are placeholders to replace. + var templates = { + "account": { action: "api_key" }, + "files": { action: "list", limit: 10 }, + "collections": { action: "list", limit: 10 }, + "search": { query: "What were the key revenue drivers?", collection_ids: ["collection_ID"], retrieval_mode: "hybrid" }, + "voices": { action: "list" }, + "tts": { text: "Hello from Grok.", language: "en", voice_id: "eve", confirm: false }, + "stt": { url: "https://example.com/audio.mp3", language: "en", confirm: false }, + "realtime/secret": { expires_seconds: 300, confirm: false }, + "realtime/session": { text: "Say hello in one sentence.", voice: "eve", turn_detection: "server_vad", confirm: false }, + "realtime/session/preview": { voice: "eve", instructions: "You are a helpful agent.", turn_detection: "server_vad", output_speed: 1.0 }, + "realtime/phone-numbers": { action: "list" }, + "realtime/calls": { action: "hangup", call_id: "CALL_ID", confirm: false }, + "webhook/verify": { secret: "whsec_...", webhook_id: "msg_1", webhook_timestamp: "1750000000", webhook_signature: "v1,...", body: "{}" }, + "keys": { action: "validate" }, + "billing": { action: "prepaid_balance", team_id: "TEAM_UUID" }, + "audit": { team_id: "TEAM_UUID", page_size: 20 } + }; + + function show(j, ok) { + if (ok) { err.textContent = ""; out.textContent = JSON.stringify(j, null, 2); } + else { err.textContent = j.message || "Request failed"; out.textContent = ""; } + } + + function send() { + var body; + try { body = JSON.parse($("xp-body").value || "{}"); } + catch (e) { err.textContent = "Body is not valid JSON"; return; } + err.textContent = ""; + out.textContent = "..."; + fetch("/ai/xai/platform/" + $("xp-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 }; } + show(j, res.ok); + }); + }).catch(function (e) { err.textContent = String(e); out.textContent = ""; }); + } + + function fill() { $("xp-body").value = JSON.stringify(templates[$("xp-route").value], null, 1); } + + fetch("/ai/xai/platform/status").then(function (r) { return r.json(); }).then(function (s) { + var parts = []; + parts.push(s.api_key_configured ? "XAI_API_KEY found." : "No XAI_API_KEY: inference-host routes answer 503."); + parts.push(s.management_key_configured ? "XAI_MANAGEMENT_KEY found." : "No XAI_MANAGEMENT_KEY: collections and management routes answer 503."); + $("xp-config").textContent = parts.join(" "); + }); + $("xp-route").onchange = fill; + $("xp-send").onclick = send; + fill(); +})(); diff --git a/src/xai/platform/SPEC.md b/src/xai/platform/SPEC.md new file mode 100644 index 0000000..7c7b299 --- /dev/null +++ b/src/xai/platform/SPEC.md @@ -0,0 +1,193 @@ +# xai platform (molo::xai::platform) + +Status 2026-10-24. xAI's non-chat platform surface: voice (realtime agent +WebSocket, TTS and STT over HTTP and WebSocket, custom voices, SIP phone +numbers and call control, webhook verification), files, collections and +documents (management host) plus document search (inference host), the +management API (API keys, billing, usage, audit) and API key / caller info. +Chat, responses, tools, image, video, batch, models and the Anthropic +compatible endpoint belong to `src/xai/core`. Plan: `plans/17-llm-vendor-platforms.md`. + +## Scope and credentials + +| Host | Base URL | Credential (`llm::Config::get`) | +|---|---|---| +| inference | `https://api.x.ai` | `XAI_API_KEY` | +| management | `https://management-api.x.ai` | `XAI_MANAGEMENT_KEY` | +| realtime | `wss://api.x.ai/v1/realtime` | API key, or an ephemeral client secret | +| tts stream | `wss://api.x.ai/v1/tts` | API key | +| stt stream | `wss://api.x.ai/v1/stt` | API key | + +Both HTTP hosts use `Authorization: Bearer`. A service refuses (local 400) a +client built for the other credential, so the management key is never sent to +the inference host. A missing key throws `llm::NotConfiguredError` before any +network traffic. Collection management is on the management host and takes the +management key; searching a collection (`/v1/documents/search`) is on the +inference host and takes the API key. + +## Module map + +| File | Concern | +|---|---| +| `caps.h` | `PlatformCaps`: every ceiling | +| `calls.{h,cpp}` | the ONE REST call table (59 rows), `render()` | +| `platform_service.{h,cpp}` | base: table driven calls, `Query`, uuid / text / range / confirm checks, host-key guard | +| `clients.{h,cpp}` | `PlatformClients`: the two `ApiClient`s, endpoint constants | +| `account.h` | `AccountService`: `GET /v1/api-key`, `GET /v1/me` | +| `files.{h,cpp}` | `FilesService`: upload, list (+ bounded walk), get, content, public URL create / revoke, delete | +| `collections.{h,cpp}` | `CollectionsService`: collection CRUD, documents (add, upload, list, get, reindex, remove, batchGet) | +| `documents_search.{h,cpp}` | `DocumentSearch`: `/v1/documents/search` | +| `api_keys.{h,cpp}` | `ApiKeysService`: create, list (+ walk), update, rotate, delete, propagation, team models / endpoints, management key validation | +| `billing.{h,cpp}` | `BillingService`: billing info, invoices, payment methods, spending limits, prepaid balance, top-up, usage | +| `audit.{h,cpp}` | `AuditService`: audit events (+ bounded walk) | +| `voices.{h,cpp}` | `VoicesService`: built-in TTS voices, custom voices (create, list, get, patch, delete, audio) | +| `tts.{h,cpp}` | `TextToSpeech`: `POST /v1/tts` | +| `stt.{h,cpp}` | `SpeechToText`: `POST /v1/stt` (multipart, file last) | +| `realtime_rest.{h,cpp}` | `RealtimeRest`: client secrets, SIP phone numbers, refer, hangup | +| `webhook.{h,cpp}` | `WebhookVerifier`: Standard Webhooks v1 signature check of `realtime.call.incoming`, own SHA-256 / HMAC | +| `ws_events.{h,cpp}` | `WsVocabulary`: every WebSocket message, query param, session field and tool type (120 rows) | +| `session_config.{h,cpp}` | `SessionConfig` and `SessionTool`: typed, validated `session.update` | +| `socket.{h,cpp}` | `XaiSocket`: connect, auth in headers only, send, decoded `next()` with deadline; reuses `google::live::WsClient` | +| `realtime_session.{h,cpp}` | `RealtimeSession`: session.created wait, audio in, items, response folding, function calls | +| `tts_stream.{h,cpp}` | `TtsStream`: text deltas in, audio chunks out, multi utterance | +| `stt_stream.{h,cpp}` | `SttStream`: transcript.created wait, binary audio, finalize, transcript.done | +| `voice_types.h` | shared enumerations | +| `tools/check_spec.py` | spec checker | + +## Contracts + +- Every path comes from `calls.cpp`; ids pass `llm::Service::valid_id`, team + and key ids must be UUIDs (the management API answers `Invalid uuid` otherwise). +- Destructive or money moving calls (`delete`, `revoke`, `rotate`, `top_up`, + spending limit, billing info, default payment method, `refer`, `hangup`, + phone number removal, custom voice delete) take an explicit `confirm` with no + default; `false` throws a local 400 and sends nothing. +- List walks (`list_all`, `events_all`) stop at the caller's page cap (max 100) + and report `truncated: true` when more pages existed. An empty + `paginationToken` is never sent (the server rejects it). +- Sockets: credential in the `Authorization` header (or the + `Sec-WebSocket-Protocol: xai-client-secret.` form for ephemeral + secrets), never in the URL; client messages must be in the vocabulary table; + unknown server messages are delivered with `known=false` and counted; a bad + audio base64 delta throws; the session stops at `max_session_seconds`. +- The demo and every example route answer 503 `not_configured` without the + key they need, 422 on bad input, and are dry runs without `"confirm":true` + for destructive or paid calls. + +## Caps + +Source of truth: `caps.h`. Highlights: TTS text 60000 chars (doc), STT file +500 MB (doc), files 50 MB (doc), collection document 100 MB (doc), keyterms +100 x 50 chars (doc), client secret 3600 s (doc), file / URL expiry 3600..2592000 s +(doc), custom voice limit 1..1000 (doc), phone number limit 100 (doc), web search +domains 5 and X handles 20 (doc), session 1800 s, audio chunk 262144 bytes, +page walks 100 pages, webhook tolerance 300 s, webhook body 1 MB, session +instructions 32000 chars, 64 session tools. Numbers without "(doc)" are our own +ceilings. + +## Sources + +- OpenAPI: `https://api.x.ai/api-docs/openapi.json` (same as `https://docs.x.ai/openapi.json`): + api-key, me, files and public URLs, documents search. +- REST reference pages (markdown) under `https://docs.x.ai/developers/rest-api-reference/`: + `inference/voice`, `collections/collection`, `collections/search`, + `management/auth`, `management/billing`, `management/audit`, `files/*`, + `inference/other`. The management host has no OpenAPI document (404 on + `/openapi.json` and `/api-docs/openapi.json`). +- WebSocket schemas: `https://docs.x.ai/voice-realtime.ws.json`, + `tts-streaming.ws.json`, `stt-streaming.ws.json`. +- Guides (prose, cross-checks and guide-only items): `model-capabilities/audio/{speech-to-speech, + speech-to-speech/sip, text-to-speech, speech-to-text, custom-voices, ephemeral-tokens}`, + `files/{collections,collections/api,collections/metadata,public-urls}`, + `management-api-guide`. +- Second source: `xai-org/xai-proto` `management_api/v1/billing.proto` (11 rpcs = + the 11 billing rows) and `api/v1/auth.proto` (`get_api_key_info`), `documents.proto` + (retrieval modes), `files.proto` (public URL rpcs). +- Webhook scheme: Standard Webhooks v1 as stated on the SIP page. + +## Verified against spec + +`python3 -I src/xai/platform/tools/check_spec.py` on 2026-10-24: OK, 59 call +rows (10 against OpenAPI, 48 against reference pages, 1 against a guide), 120 +WebSocket rows, 11 billing rpcs cross-checked, OpenAPI 39 paths, 10 reference +pages. It fails on: a row absent from its source, a body field or query +parameter absent, a changed operation id, a WebSocket message / query / session +field / tool type that differs from the three `.ws.json` documents (both +directions), an OpenAPI operation or reference-page operation that is neither a +row nor excluded, a billing rpc count mismatch. Negative run: renaming one +query parameter made it fail. Exclusions are listed in the script: other +package (`chat`, `responses`, `images`, `videos`, `models`, `embeddings`, +`messages`, `tokenize-text`), `/v1/skills` (outside this package's brief; live +`GET` answered 404 unauthenticated), and three file operations the docs list +without any shape (`POST /v1/files:initialize`, `POST /v1/files:uploadChunks`, +`PUT /v1/files/{file_id}`). + +## Verified live + +No xAI key exists in this environment. Unauthenticated probes, 2026-10-24: + +- `api.x.ai` answers `401` with `{"code":"unauthenticated:no-credentials","error":...}` for + GET `/v1/api-key`, `/v1/me`, `/v1/files`, `/v1/files/{id}`, `/v2/phone-numbers`, `/v1/collections`; + POST `/v1/tts`, `/v1/stt`, `/v1/realtime/client_secrets`, `/v1/files/{id}/public-url`, + `/v1/files/{id}/public-url/revoke`, `/v2/phone-numbers`; DELETE `/v2/phone-numbers/{id}`. + `POST /v1/documents/search` with `{}` answers `422 missing field query`; `POST /v1/files` + without a multipart boundary answers `400`. +- WebSocket upgrades without credentials to `/v1/realtime`, `/v1/tts?language=en`, `/v1/stt` + answer `401`; with a bogus bearer, `/v1/realtime` answers `400 Incorrect API key provided`. + The module's own sockets (`RealtimeSession`, `TtsStream`, `SttStream`) reached all three + over TLS and reported `400` through `ApiError` (TLS and handshake path proven). +- `management-api.x.ai` answers `401 {"code":16,"message":"No credentials presented..."}` for + collections, documents, batchGet, management key validation, key list / models / endpoints / + propagation, key create, rotate; billing and audit with a non-UUID team answer + `400 Invalid uuid`. With a bogus bearer the client reports + `401 Invalid bearer token. Please ensure you use a valid management key`. +- Inconclusive: GET `/v1/tts/voices`, `/v1/tts/voices/{id}`, `/v1/custom-voices` (+ id, audio), + POST `/v1/custom-voices`, POST `/v1/realtime/calls/{id}/hangup|refer`, PATCH and DELETE + `/v1/custom-voices/{id}` hung until a 60 s read timeout unauthenticated. Their paths + are verified against the reference page only. +- No team members endpoint: `GET /auth/teams/{id}/members`, `/users`, `/{id}` answer `404`. +- `GET api.x.ai/v1/skills` answers `404` although the OpenAPI document lists it. +- Opt-in live tests (`tests/src/xai/platform/test_live.cpp`) need `MOLO_LIVE_NET=1` plus the + key; paid TTS also `MOLO_LIVE_PAID=1`. They print a loud SKIP otherwise and have not run + against a key. + +## Unverified + +Everything below is inferred or taken from prose, not seen on the wire. + +- Response shapes: all REST results are returned as the server's JSON unchanged except + what the demo reads (`value`, `teamId`, `data`, `pagination_token`, `paginationToken`, + `apiKeys`, `events`, `nextPageToken`, `audio`). Billing, key and collection responses + were read from the reference examples only. +- Function tools use the flat shape of the guide examples (`{"type":"function","name":...}`); + `voice-realtime.ws.json` nests them under `function`. +- `conversation.created` is documented as the first message and also as the second step of the + example flow; `RealtimeSession::connect` accepts either order. +- `optimize_streaming_latency`: REST reference lists `"0"|"1"` (sent as a string), the guide 0..2, + the socket 0 or 1. `vad_threshold` default is 0.5 (guide) vs 0.08 (socket reference). +- `model` on `POST /v1/stt` is in the guide, not the reference table. +- `POST /v1/collections/{id}/documents` (one step multipart: name, data, content_type, fields) + appears only in a guide curl example. +- `conversation_id` query, `conversation.item.created`, `response.audio.delta` are guide-only. +- Money values (`amount.val`, spending limit) are sent as decimal strings; the unit is not documented. +- Team and key ids must be UUIDs (inferred from the live `Invalid uuid`); file ids, collection + ids and call ids only pass `valid_id`. +- Webhook secret handling (`whsec_` + base64, HMAC over `id.timestamp.body`) follows Standard + Webhooks; it is tested with locally signed payloads and RFC 4231 HMAC vectors, not with a + payload xAI signed. +- Ephemeral secret over `Sec-WebSocket-Protocol` was tested against a loopback only. +- Binary audio transport (`audio.*.transport = "binary"`) is tested against a loopback only. +- Phone numbers: the SIP page says provisioning xAI numbers by API is unsupported; the reference + lists `origin: xai_provisioned`. Both are accepted by the builder. + +## Gaps + +- Team members: no public endpoint (see probes). Owner: xAI. +- `POST /v1/files:initialize`, `POST /v1/files:uploadChunks`, `PUT /v1/files/{file_id}`: + listed by the docs without a shape (`check_spec.py` EXCLUDED_DOCS). +- Skills (`/v1/skills*`) are in the OpenAPI document but unrouted live and outside this brief; + not implemented (`EXCLUDED_OPENAPI_PREFIXES`). +- No microphone capture or playback; callers supply PCM / codec bytes. +- Reconnect with resumption passes `conversation_id` only; no automatic backoff loop. +- WebRTC bridging (cookbook example) is a browser concern; not covered. +- Live tests have never run against a key. diff --git a/src/xai/platform/account.h b/src/xai/platform/account.h new file mode 100644 index 0000000..9dcdae9 --- /dev/null +++ b/src/xai/platform/account.h @@ -0,0 +1,21 @@ +#pragma once + +// Who am I: the API key behind XAI_API_KEY (GET /v1/api-key) and the +// authenticated caller (GET /v1/me). Read-only. + +#include "xai/platform/platform_service.h" + +namespace molo::xai::platform { + +class AccountService : public PlatformService { + public: + explicit AccountService(std::shared_ptr api) + : PlatformService(std::move(api), Host::kApi) {} + + // Name, ACLs, blocked/disabled flags, ids. Never the key itself. + Json api_key_info() { return invoke(Call::kApiKeyInfo, {}); } + // user_id, team_id, zdr_status, team_blocked, api_key or oauth block. + Json me() { return invoke(Call::kMe, {}); } +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/api_keys.cpp b/src/xai/platform/api_keys.cpp new file mode 100644 index 0000000..6a27465 --- /dev/null +++ b/src/xai/platform/api_keys.cpp @@ -0,0 +1,135 @@ +#include "xai/platform/api_keys.h" + +#include "xai/platform/caps.h" + +namespace molo::xai::platform { + +bool ApiKeysService::valid_acl(const std::string& acl) { + return acl.rfind("api-key:model:", 0) == 0 || acl.rfind("api-key:endpoint:", 0) == 0; +} + +Json ApiKeysService::create(const std::string& team_id, const ApiKeySpec& s) { + require_uuid("team_id", team_id); + require_text("name", s.name, PlatformCaps::kMaxNameChars); + Json b = Json::object(); + b.set("name", s.name); + if (!s.acls.empty()) { + if (s.acls.size() > 256) bad("too many acls"); + Json acls = Json::array(); + for (const std::string& a : s.acls) { + if (!valid_acl(a) || a.size() > 256) bad("acl must start with api-key:model: or api-key:endpoint:"); + acls.push(a); + } + b.set("acls", acls); + } + if (s.qps < 0 || s.qpm < 0 || s.tpm < 0) bad("rate limits must not be negative"); + if (s.qps) b.set("qps", Json(s.qps)); + if (s.qpm) b.set("qpm", Json(s.qpm)); + if (s.tpm) b.set("tpm", Json(std::to_string(s.tpm))); // spec: tpm is a string + if (!s.expire_time.empty()) { + require_text("expire_time", s.expire_time, 64); + b.set("expireTime", s.expire_time); + } + return invoke(Call::kKeyCreate, {team_id}, &b); +} + +Json ApiKeysService::list(const std::string& team_id, int page_size, const std::string& token, + bool active_only, const std::vector& acl_filters) { + require_uuid("team_id", team_id); + Query q; + if (page_size != 0) { + require_range("page_size", page_size, 1, PlatformCaps::kMaxLimit); + q.add_int("pageSize", page_size); + } + require_text("pagination_token", token, 512, false); + q.add_if("paginationToken", token); // an empty token is rejected by the server: never send it + if (active_only) q.add_bool("activeOnly", true); + if (acl_filters.size() > 32) bad("too many acl filters"); + for (const std::string& a : acl_filters) { + if (!valid_acl(a)) bad("bad acl filter"); + q.add("aclFilters", a); + } + return invoke(Call::kKeyList, {team_id}, nullptr, q); +} + +KeyListing ApiKeysService::list_all(const std::string& team_id, std::size_t max_pages, + int page_size) { + if (max_pages == 0 || max_pages > PlatformCaps::kMaxPages) bad("max_pages must be 1..100"); + require_range("page_size", page_size, 1, PlatformCaps::kMaxLimit); + KeyListing out; + std::string token; + for (;;) { + Json page = list(team_id, page_size, token); + ++out.pages; + const Json* keys = page.find("apiKeys"); + std::size_t n = keys && keys->is_array() ? keys->as_array().size() : 0; + if (n) for (const Json& k : keys->as_array()) out.keys.push(k); + const Json* t = page.find("paginationToken"); + token = t && t->is_string() ? t->as_string() : ""; + // Docs: keep going until a page returns fewer than pageSize keys. + if (n < static_cast(page_size) || token.empty()) return out; + if (out.pages >= max_pages) { + out.truncated = true; + return out; + } + } +} + +Json ApiKeysService::update(const std::string& id, const Json& changes) { + check_id("api key", id); + if (!changes.is_object() || changes.as_object().empty()) bad("changes must be a non-empty object"); + static const char* allowed[] = {"name", "disabled", "qps", "qpm", "tpm", "expireTime", "aclStrings"}; + std::string mask; + for (const auto& [k, v] : changes.as_object()) { + bool ok = false; + for (const char* a : allowed) ok = ok || k == a; + if (!ok) bad("field not updatable: " + k); + if (k == "aclStrings") { + if (!v.is_array()) bad("aclStrings must be an array"); + for (const Json& a : v.as_array()) + if (!a.is_string() || !valid_acl(a.as_string())) bad("bad acl"); + } + mask += (mask.empty() ? "" : ",") + k; + } + Json b = Json::object(); + b.set("apiKey", changes); + b.set("fieldMask", mask); + return invoke(Call::kKeyUpdate, {id}, &b); +} + +Json ApiKeysService::rotate(const std::string& id, bool confirm, const std::string& expire_time, + const std::string& old_expire_time) { + check_id("api key", id); + require_confirm("rotating an API key", confirm); + require_text("expire_time", expire_time, 64, false); + require_text("old_secret_expire_time", old_expire_time, 64, false); + Json b = Json::object(); + if (!expire_time.empty()) b.set("expireTime", expire_time); + if (!old_expire_time.empty()) b.set("oldSecretExpireTime", old_expire_time); + return invoke(Call::kKeyRotate, {id}, &b); +} + +Json ApiKeysService::remove(const std::string& id, bool confirm) { + check_id("api key", id); + require_confirm("deleting an API key", confirm); + return invoke(Call::kKeyDelete, {id}); +} + +Json ApiKeysService::propagation(const std::string& id) { + check_id("api key", id); + return invoke(Call::kKeyPropagation, {id}); +} + +Json ApiKeysService::team_models(const std::string& team_id) { + require_uuid("team_id", team_id); + return invoke(Call::kTeamModels, {team_id}); +} + +Json ApiKeysService::team_endpoints(const std::string& team_id) { + require_uuid("team_id", team_id); + return invoke(Call::kTeamEndpoints, {team_id}); +} + +Json ApiKeysService::validate_management_key() { return invoke(Call::kKeyValidate, {}); } + +} // namespace molo::xai::platform diff --git a/src/xai/platform/api_keys.h b/src/xai/platform/api_keys.h new file mode 100644 index 0000000..1c733a8 --- /dev/null +++ b/src/xai/platform/api_keys.h @@ -0,0 +1,54 @@ +#pragma once + +// API key management on management-api.x.ai (XAI_MANAGEMENT_KEY): create, +// list (bounded page walk), update, rotate, delete, propagation status, the +// team's model and endpoint ACL catalogue, and management key validation. +// The secret of a new or rotated key is returned once, in "apiKey": callers +// must never log it. + +#include +#include + +#include "xai/platform/platform_service.h" + +namespace molo::xai::platform { + +struct ApiKeySpec { + std::string name; // required for create + std::vector acls; // api-key:model:* , api-key:endpoint:* + long qps = 0; // 0 = unset + long qpm = 0; + long tpm = 0; + std::string expire_time; // RFC 3339, "" = unset +}; + +struct KeyListing { + Json keys = Json::array(); + bool truncated = false; + std::size_t pages = 0; +}; + +class ApiKeysService : public PlatformService { + public: + explicit ApiKeysService(std::shared_ptr management) + : PlatformService(std::move(management), Host::kManagement) {} + + static bool valid_acl(const std::string& acl); + + Json create(const std::string& team_id, const ApiKeySpec& spec); + Json list(const std::string& team_id, int page_size = 0, const std::string& token = "", + bool active_only = false, const std::vector& acl_filters = {}); + KeyListing list_all(const std::string& team_id, std::size_t max_pages, int page_size = 50); + // fieldMask is built from the fields set in `changes` + // (name, disabled, qps, qpm, tpm, expireTime, aclStrings are passed as given). + Json update(const std::string& api_key_id, const Json& changes); + Json rotate(const std::string& api_key_id, bool confirm, const std::string& expire_time = "", + const std::string& old_secret_expire_time = ""); + Json remove(const std::string& api_key_id, bool confirm); + Json propagation(const std::string& api_key_id); + Json team_models(const std::string& team_id); + Json team_endpoints(const std::string& team_id); + Json validate_management_key(); +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/audit.cpp b/src/xai/platform/audit.cpp new file mode 100644 index 0000000..50e292a --- /dev/null +++ b/src/xai/platform/audit.cpp @@ -0,0 +1,50 @@ +#include "xai/platform/audit.h" + +#include "xai/platform/caps.h" + +namespace molo::xai::platform { + +Json AuditService::events(const std::string& team_id, const AuditQuery& a) { + require_uuid("team_id", team_id); + Query q; + if (a.page_size != 0) { + require_range("page_size", a.page_size, 1, PlatformCaps::kMaxLimit); + q.add_int("pageSize", a.page_size); + } + require_text("page_token", a.page_token, 512, false); + require_text("user_id", a.user_id, 128, false); + require_text("query", a.query, PlatformCaps::kMaxFilterChars, false); + require_text("event_id", a.event_id, 128, false); + require_text("time_from", a.time_from, 64, false); + require_text("time_to", a.time_to, 64, false); + if (!a.order_by.empty() && a.order_by != "TIME_ASCENDING" && a.order_by != "TIME_DESCENDING") + bad("order_by must be TIME_ASCENDING or TIME_DESCENDING"); + q.add_if("pageToken", a.page_token).add_if("eventFilter.userId", a.user_id); + q.add_if("eventFilter.query", a.query).add_if("eventFilter.eventId", a.event_id); + q.add_if("eventTimeFrom", a.time_from).add_if("eventTimeTo", a.time_to); + q.add_if("orderBy", a.order_by); + return invoke(Call::kAuditEvents, {team_id}, nullptr, q); +} + +AuditListing AuditService::events_all(const std::string& team_id, std::size_t max_pages, + AuditQuery query) { + if (max_pages == 0 || max_pages > PlatformCaps::kMaxPages) bad("max_pages must be 1..100"); + if (query.page_size == 0) query.page_size = 100; + AuditListing out; + for (;;) { + Json page = events(team_id, query); + ++out.pages; + const Json* ev = page.find("events"); + if (ev && ev->is_array()) for (const Json& e : ev->as_array()) out.events.push(e); + const Json* t = page.find("nextPageToken"); + std::string next = t && t->is_string() ? t->as_string() : ""; + if (next.empty()) return out; + if (out.pages >= max_pages) { + out.truncated = true; + return out; + } + query.page_token = next; + } +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/audit.h b/src/xai/platform/audit.h new file mode 100644 index 0000000..042cb95 --- /dev/null +++ b/src/xai/platform/audit.h @@ -0,0 +1,38 @@ +#pragma once + +// GET /audit/teams/{teamId}/events on management-api.x.ai. Read-only, with a +// bounded page walk that reports truncation. + +#include + +#include "xai/platform/platform_service.h" + +namespace molo::xai::platform { + +struct AuditQuery { + int page_size = 0; + std::string page_token; + std::string user_id; + std::string query; // full-text search in descriptions + std::string event_id; + std::string time_from; // ISO 8601 + std::string time_to; + std::string order_by; // "" | TIME_ASCENDING | TIME_DESCENDING +}; + +struct AuditListing { + Json events = Json::array(); + bool truncated = false; + std::size_t pages = 0; +}; + +class AuditService : public PlatformService { + public: + explicit AuditService(std::shared_ptr management) + : PlatformService(std::move(management), Host::kManagement) {} + + Json events(const std::string& team_id, const AuditQuery& query = {}); + AuditListing events_all(const std::string& team_id, std::size_t max_pages, AuditQuery query = {}); +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/billing.cpp b/src/xai/platform/billing.cpp new file mode 100644 index 0000000..ed74e37 --- /dev/null +++ b/src/xai/platform/billing.cpp @@ -0,0 +1,130 @@ +#include "xai/platform/billing.h" + +#include + +#include "xai/platform/caps.h" + +namespace molo::xai::platform { + +bool BillingService::valid_amount(const std::string& s) { + if (s.empty() || s.size() > 21) return false; + std::size_t dot = s.find('.'); + std::string whole = s.substr(0, dot); + if (whole.empty() || whole.size() > 18) return false; + for (char c : whole) if (!std::isdigit(static_cast(c))) return false; + if (dot == std::string::npos) return true; + std::string frac = s.substr(dot + 1); + if (frac.empty() || frac.size() > 2) return false; + for (char c : frac) if (!std::isdigit(static_cast(c))) return false; + return true; +} + +Json BillingService::billing_info(const std::string& t) { + require_uuid("team_id", t); + return invoke(Call::kBillingInfoGet, {t}); +} + +Json BillingService::set_billing_info(const std::string& t, const Json& info, bool confirm) { + require_uuid("team_id", t); + require_confirm("changing billing info", confirm); + if (!info.is_object() || info.as_object().empty()) bad("billing_info must be a non-empty object"); + Json b = Json::object(); + b.set("billingInfo", info); + return invoke(Call::kBillingInfoSet, {t}, &b); +} + +Json BillingService::invoices(const std::string& t, const InvoiceQuery& iq) { + require_uuid("team_id", t); + Query q; + if ((iq.cycle_year != 0) != (iq.cycle_month != 0)) bad("billing cycle needs year and month"); + if ((iq.since_year != 0) != (iq.since_month != 0)) bad("since needs year and month"); + if (iq.cycle_year) { + require_range("cycle year", iq.cycle_year, 2020, 2100); + require_range("cycle month", iq.cycle_month, 1, 12); + q.add_int("billingCycle.year", iq.cycle_year).add_int("billingCycle.month", iq.cycle_month); + } + if (iq.since_year) { + require_range("since year", iq.since_year, 2020, 2100); + require_range("since month", iq.since_month, 1, 12); + q.add_int("since.year", iq.since_year).add_int("since.month", iq.since_month); + } + if (iq.invoice_ids.size() > PlatformCaps::kMaxBatchFileIds) bad("too many invoice ids"); + for (const std::string& id : iq.invoice_ids) { + require_text("invoice id", id, 128); + q.add("invoiceIds.invoiceIds", id); + } + return invoke(Call::kInvoices, {t}, nullptr, q); +} + +Json BillingService::payment_methods(const std::string& t) { + require_uuid("team_id", t); + return invoke(Call::kPaymentMethods, {t}); +} + +Json BillingService::set_default_payment_method(const std::string& t, const std::string& id, + bool confirm) { + require_uuid("team_id", t); + require_text("payment_method_id", id, 128); + require_confirm("changing the default payment method", confirm); + Json b = Json::object(); + b.set("paymentMethodId", id); + return invoke(Call::kPaymentDefault, {t}, &b); +} + +Json BillingService::invoice_preview(const std::string& t) { + require_uuid("team_id", t); + return invoke(Call::kInvoicePreview, {t}); +} + +Json BillingService::spending_limits(const std::string& t) { + require_uuid("team_id", t); + return invoke(Call::kSpendingGet, {t}); +} + +Json BillingService::set_soft_spending_limit(const std::string& t, const std::string& amount, + bool confirm) { + require_uuid("team_id", t); + if (!valid_amount(amount)) bad("amount must be a decimal string like 100 or 100.50"); + require_confirm("changing the spending limit", confirm); + Json v = Json::object(); + v.set("val", amount); + Json b = Json::object(); + b.set("desiredSoftSpendingLimit", v); + return invoke(Call::kSpendingSet, {t}, &b); +} + +Json BillingService::prepaid_balance(const std::string& t) { + require_uuid("team_id", t); + return invoke(Call::kPrepaidBalance, {t}); +} + +Json BillingService::top_up(const std::string& t, const std::string& amount, bool confirm) { + require_uuid("team_id", t); + if (!valid_amount(amount)) bad("amount must be a decimal string like 100 or 100.50"); + require_confirm("a prepaid top-up", confirm); + Json v = Json::object(); + v.set("val", amount); + Json b = Json::object(); + b.set("amount", v); + return invoke(Call::kPrepaidTopUp, {t}, &b); +} + +Json BillingService::usage(const std::string& t, const Json& req) { + require_uuid("team_id", t); + if (!req.is_object()) bad("analytics_request must be an object"); + const Json* range = req.find("timeRange"); + const Json* values = req.find("values"); + if (!range || !range->is_object()) bad("analytics_request.timeRange is required"); + if (!values || !values->is_array() || values->as_array().empty() || + values->as_array().size() > 16) + bad("analytics_request.values must hold 1..16 entries"); + for (const char* k : {"groupBy", "filters"}) { + const Json* a = req.find(k); + if (a && (!a->is_array() || a->as_array().size() > 32)) bad(std::string(k) + " must be an array of at most 32"); + } + Json b = Json::object(); + b.set("analyticsRequest", req); + return invoke(Call::kUsage, {t}, &b); +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/billing.h b/src/xai/platform/billing.h new file mode 100644 index 0000000..5c377b8 --- /dev/null +++ b/src/xai/platform/billing.h @@ -0,0 +1,44 @@ +#pragma once + +// Billing and usage on management-api.x.ai (XAI_MANAGEMENT_KEY). Reads are +// plain; every call that changes billing state or spends money takes an +// explicit confirm flag with no default. + +#include +#include + +#include "xai/platform/platform_service.h" + +namespace molo::xai::platform { + +struct InvoiceQuery { + int cycle_year = 0, cycle_month = 0; // both or neither + int since_year = 0, since_month = 0; // both or neither + std::vector invoice_ids; +}; + +class BillingService : public PlatformService { + public: + explicit BillingService(std::shared_ptr management) + : PlatformService(std::move(management), Host::kManagement) {} + + // Decimal string for money values ("10", "10.50"): 1..18 digits, optional 2 decimals. + static bool valid_amount(const std::string& s); + + Json billing_info(const std::string& team_id); + Json set_billing_info(const std::string& team_id, const Json& billing_info, bool confirm); + Json invoices(const std::string& team_id, const InvoiceQuery& query = {}); + Json payment_methods(const std::string& team_id); + Json set_default_payment_method(const std::string& team_id, const std::string& payment_method_id, + bool confirm); + Json invoice_preview(const std::string& team_id); + Json spending_limits(const std::string& team_id); + Json set_soft_spending_limit(const std::string& team_id, const std::string& amount, bool confirm); + Json prepaid_balance(const std::string& team_id); + // Spends money: confirm required. + Json top_up(const std::string& team_id, const std::string& amount, bool confirm); + // analyticsRequest per spec: {timeRange, timeUnit, values[], groupBy[], filters[]}. + Json usage(const std::string& team_id, const Json& analytics_request); +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/calls.cpp b/src/xai/platform/calls.cpp new file mode 100644 index 0000000..ab50fa4 --- /dev/null +++ b/src/xai/platform/calls.cpp @@ -0,0 +1,118 @@ +#include "xai/platform/calls.h" + +#include "llm/api_client.h" +#include "llm/error.h" + +namespace molo::xai::platform { + +// CALLS-BEGIN (parsed by tools/check_spec.py; one row per line) +// {Call, method, host, path, source, body_fields, query_params, guide_fields} +static const CallSpec kCalls[] = { + {Call::kApiKeyInfo, "GET", "api", "/v1/api-key", "openapi:handle_get_api_key_info_request", "", "", ""}, + {Call::kMe, "GET", "api", "/v1/me", "openapi:handle_get_me_request", "", "", ""}, + {Call::kFileUpload, "POST", "api", "/v1/files", "openapi:handle_upload_file_request", "expires_after,file,purpose", "", ""}, + {Call::kFileList, "GET", "api", "/v1/files", "openapi:handle_list_files_request", "", "limit,order,sort_by,pagination_token,after,filter", ""}, + {Call::kFileGet, "GET", "api", "/v1/files/{file_id}", "openapi:handle_retrieve_file_request", "", "", ""}, + {Call::kFileDelete, "DELETE", "api", "/v1/files/{file_id}", "openapi:handle_delete_file_request", "", "", ""}, + {Call::kFileContent, "GET", "api", "/v1/files/{file_id}/content", "openapi:handle_download_file_content_request", "", "format", ""}, + {Call::kPublicUrlCreate, "POST", "api", "/v1/files/{file_id}/public-url", "openapi:handle_create_public_url_request", "expires_after", "", ""}, + {Call::kPublicUrlRevoke, "POST", "api", "/v1/files/{file_id}/public-url/revoke", "openapi:handle_revoke_public_url_request", "", "", ""}, + {Call::kDocumentsSearch, "POST", "api", "/v1/documents/search", "openapi:handle_document_search_request_v2", "query,source,filter,group_by,instructions,limit,ranking_metric,retrieval_mode", "", ""}, + {Call::kClientSecret, "POST", "api", "/v1/realtime/client_secrets", "docs:inference/voice", "expires_after,session", "", ""}, + {Call::kPhoneCreate, "POST", "api", "/v2/phone-numbers", "docs:inference/voice", "origin,name,agent_id,area_code,phone_number,sip_auth,webhook", "", ""}, + {Call::kPhoneList, "GET", "api", "/v2/phone-numbers", "docs:inference/voice", "", "limit,pagination_token,agent_id", ""}, + {Call::kPhoneDelete, "DELETE", "api", "/v2/phone-numbers/{phone_number_id}", "docs:inference/voice", "", "", ""}, + {Call::kCallRefer, "POST", "api", "/v1/realtime/calls/{call_id}/refer", "docs:inference/voice", "target_uri", "", ""}, + {Call::kCallHangup, "POST", "api", "/v1/realtime/calls/{call_id}/hangup", "docs:inference/voice", "", "", ""}, + {Call::kTts, "POST", "api", "/v1/tts", "docs:inference/voice", "text,voice_id,output_format,language,optimize_streaming_latency,text_normalization,with_timestamps,speed,replace", "", ""}, + {Call::kTtsVoices, "GET", "api", "/v1/tts/voices", "docs:inference/voice", "", "", ""}, + {Call::kTtsVoiceGet, "GET", "api", "/v1/tts/voices/{voice_id}", "docs:inference/voice", "", "", ""}, + {Call::kStt, "POST", "api", "/v1/stt", "docs:inference/voice", "file,url,audio_format,sample_rate,language,format,multichannel,channels,diarize,keyterm,filler_words,vad_threshold", "", "model"}, + {Call::kCustomVoiceCreate, "POST", "api", "/v1/custom-voices", "docs:inference/voice", "file,name,description,gender,accent,age,language,use_case,tone", "", ""}, + {Call::kCustomVoiceList, "GET", "api", "/v1/custom-voices", "docs:inference/voice", "", "limit,pagination_token", ""}, + {Call::kCustomVoiceGet, "GET", "api", "/v1/custom-voices/{voice_id}", "docs:inference/voice", "", "", ""}, + {Call::kCustomVoicePatch, "PATCH", "api", "/v1/custom-voices/{voice_id}", "docs:inference/voice", "name,description,gender,accent,age,language,use_case,tone", "", ""}, + {Call::kCustomVoiceDelete, "DELETE", "api", "/v1/custom-voices/{voice_id}", "docs:inference/voice", "", "", ""}, + {Call::kCustomVoiceAudio, "GET", "api", "/v1/custom-voices/{voice_id}/audio", "docs:inference/voice", "", "", ""}, + {Call::kCollectionCreate, "POST", "management", "/v1/collections", "docs:collections/collection", "team_id,collection_name,index_configuration,chunk_configuration,metric_space,version,field_definitions,collection_description", "", ""}, + {Call::kCollectionList, "GET", "management", "/v1/collections", "docs:collections/collection", "", "team_id,limit,order,sort_by,pagination_token,filter", ""}, + {Call::kCollectionGet, "GET", "management", "/v1/collections/{collection_id}", "docs:collections/collection", "", "team_id", ""}, + {Call::kCollectionDelete, "DELETE", "management", "/v1/collections/{collection_id}", "docs:collections/collection", "", "team_id", ""}, + {Call::kCollectionUpdate, "PUT", "management", "/v1/collections/{collection_id}", "docs:collections/collection", "team_id,collection_name,chunk_configuration,field_definition_updates,collection_description", "", ""}, + {Call::kDocAdd, "POST", "management", "/v1/collections/{collection_id}/documents/{file_id}", "docs:collections/collection", "team_id,fields", "", ""}, + {Call::kDocUpload, "POST", "management", "/v1/collections/{collection_id}/documents", "guide:files/collections/api", "", "", "name,data,content_type,fields"}, + {Call::kDocList, "GET", "management", "/v1/collections/{collection_id}/documents", "docs:collections/collection", "", "team_id,limit,order,sort_by,pagination_token,name,filter", ""}, + {Call::kDocGet, "GET", "management", "/v1/collections/{collection_id}/documents/{file_id}", "docs:collections/collection", "", "team_id", ""}, + {Call::kDocReindex, "PATCH", "management", "/v1/collections/{collection_id}/documents/{file_id}", "docs:collections/collection", "", "team_id", ""}, + {Call::kDocRemove, "DELETE", "management", "/v1/collections/{collection_id}/documents/{file_id}", "docs:collections/collection", "", "team_id", ""}, + {Call::kDocBatchGet, "GET", "management", "/v1/collections/{collection_id}/documents:batchGet", "docs:collections/collection", "", "team_id,file_ids", ""}, + {Call::kKeyCreate, "POST", "management", "/auth/teams/{teamId}/api-keys", "docs:management/auth", "name,acls,qps,qpm,tpm,expireTime", "", ""}, + {Call::kKeyList, "GET", "management", "/auth/teams/{teamId}/api-keys", "docs:management/auth", "", "pageSize,paginationToken,aclFilters,activeOnly", ""}, + {Call::kKeyUpdate, "PUT", "management", "/auth/api-keys/{api_key_id}", "docs:management/auth", "apiKey,fieldMask", "", ""}, + {Call::kKeyRotate, "POST", "management", "/auth/api-keys/{apiKeyId}/rotate", "docs:management/auth", "expireTime,oldSecretExpireTime", "", ""}, + {Call::kKeyDelete, "DELETE", "management", "/auth/api-keys/{apiKeyId}", "docs:management/auth", "", "", ""}, + {Call::kKeyPropagation, "GET", "management", "/auth/api-keys/{apiKeyId}/propagation", "docs:management/auth", "", "", ""}, + {Call::kTeamModels, "GET", "management", "/auth/teams/{teamId}/models", "docs:management/auth", "", "", ""}, + {Call::kTeamEndpoints, "GET", "management", "/auth/teams/{teamId}/endpoints", "docs:management/auth", "", "", ""}, + {Call::kKeyValidate, "GET", "management", "/auth/management-keys/validation", "docs:management/auth", "", "", ""}, + {Call::kBillingInfoGet, "GET", "management", "/v1/billing/teams/{team_id}/billing-info", "docs:management/billing", "", "", ""}, + {Call::kBillingInfoSet, "POST", "management", "/v1/billing/teams/{team_id}/billing-info", "docs:management/billing", "billingInfo", "", ""}, + {Call::kInvoices, "GET", "management", "/v1/billing/teams/{team_id}/invoices", "docs:management/billing", "", "billingCycle.year,billingCycle.month,since.year,since.month,invoiceIds.invoiceIds", ""}, + {Call::kPaymentMethods, "GET", "management", "/v1/billing/teams/{team_id}/payment-method", "docs:management/billing", "", "", ""}, + {Call::kPaymentDefault, "POST", "management", "/v1/billing/teams/{team_id}/payment-method/default", "docs:management/billing", "paymentMethodId", "", ""}, + {Call::kInvoicePreview, "GET", "management", "/v1/billing/teams/{team_id}/postpaid/invoice/preview", "docs:management/billing", "", "", ""}, + {Call::kSpendingGet, "GET", "management", "/v1/billing/teams/{team_id}/postpaid/spending-limits", "docs:management/billing", "", "", ""}, + {Call::kSpendingSet, "POST", "management", "/v1/billing/teams/{team_id}/postpaid/spending-limits", "docs:management/billing", "desiredSoftSpendingLimit", "", ""}, + {Call::kPrepaidBalance, "GET", "management", "/v1/billing/teams/{team_id}/prepaid/balance", "docs:management/billing", "", "", ""}, + {Call::kPrepaidTopUp, "POST", "management", "/v1/billing/teams/{team_id}/prepaid/top-up", "docs:management/billing", "amount", "", ""}, + {Call::kUsage, "POST", "management", "/v1/billing/teams/{team_id}/usage", "docs:management/billing", "analyticsRequest", "", ""}, + {Call::kAuditEvents, "GET", "management", "/audit/teams/{teamId}/events", "docs:management/audit", "", "pageSize,pageToken,eventFilter.userId,eventFilter.query,eventFilter.eventId,eventTimeFrom,eventTimeTo,orderBy", ""}, +}; +// CALLS-END + +static_assert(sizeof(kCalls) / sizeof(kCalls[0]) == 59, "call table size"); + +std::size_t call_count() { return sizeof(kCalls) / sizeof(kCalls[0]); } +const CallSpec& spec_at(std::size_t i) { return kCalls[i]; } + +const CallSpec& spec_of(Call call) { + const CallSpec& s = kCalls[static_cast(call)]; + if (s.call != call) throw llm::ApiError::invalid("xai", "call table out of order"); + return s; +} + +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 == "PUT") return clients::Method::kPut; + if (m == "PATCH") return clients::Method::kPatch; + return clients::Method::kDelete; +} + +Host host_of(Call call) { + return std::string(spec_of(call).host) == "management" ? Host::kManagement : Host::kApi; +} + +std::string render(Call call, std::initializer_list segments) { + std::string path = spec_of(call).path; + std::string out; + auto it = segments.begin(); + for (std::size_t i = 0; i < path.size(); ++i) { + if (path[i] != '{') { + out.push_back(path[i]); + continue; + } + std::size_t close = path.find('}', i); + if (close == std::string::npos || it == segments.end()) + throw llm::ApiError::invalid("xai", "wrong number of path segments"); + if (!llm::Service::valid_id(*it)) throw llm::ApiError::invalid("xai", "bad path id"); + out += *it; + ++it; + i = close; + } + if (it != segments.end()) throw llm::ApiError::invalid("xai", "wrong number of path segments"); + return out; +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/calls.h b/src/xai/platform/calls.h new file mode 100644 index 0000000..21ffa62 --- /dev/null +++ b/src/xai/platform/calls.h @@ -0,0 +1,62 @@ +#pragma once + +// The ONE table of REST calls this module makes. Every row is checked by +// tools/check_spec.py against xAI's OpenAPI document or the docs.x.ai REST +// reference pages. Code builds every path from this table, never a literal. + +#include +#include +#include + +#include "clients/request.h" + +namespace molo::xai::platform { + +enum class Call { + // Account (api.x.ai) + kApiKeyInfo, kMe, + // Files (api.x.ai) + kFileUpload, kFileList, kFileGet, kFileDelete, kFileContent, kPublicUrlCreate, + kPublicUrlRevoke, + // Document search (api.x.ai) + kDocumentsSearch, + // Voice REST (api.x.ai) + kClientSecret, kPhoneCreate, kPhoneList, kPhoneDelete, kCallRefer, kCallHangup, kTts, + kTtsVoices, kTtsVoiceGet, kStt, kCustomVoiceCreate, kCustomVoiceList, kCustomVoiceGet, + kCustomVoicePatch, kCustomVoiceDelete, kCustomVoiceAudio, + // Collections (management-api.x.ai) + kCollectionCreate, kCollectionList, kCollectionGet, kCollectionDelete, kCollectionUpdate, + kDocAdd, kDocUpload, kDocList, kDocGet, kDocReindex, kDocRemove, kDocBatchGet, + // Management keys (management-api.x.ai) + kKeyCreate, kKeyList, kKeyUpdate, kKeyRotate, kKeyDelete, kKeyPropagation, kTeamModels, + kTeamEndpoints, kKeyValidate, + // Billing and audit (management-api.x.ai) + kBillingInfoGet, kBillingInfoSet, kInvoices, kPaymentMethods, kPaymentDefault, + kInvoicePreview, kSpendingGet, kSpendingSet, kPrepaidBalance, kPrepaidTopUp, kUsage, + kAuditEvents, +}; + +enum class Host { kApi, kManagement }; + +struct CallSpec { + Call call; + const char* http_method; // GET POST PUT PATCH DELETE + const char* host; // "api" -> api.x.ai, "management" -> management-api.x.ai + const char* path; // exactly as the spec prints it + const char* source; // "openapi:" | "docs:" | "guide:" + const char* body_fields; // comma list: top-level request body / form fields we send + const char* query_params; // comma list + const char* guide_fields; // comma list: fields only the prose guide documents +}; + +const CallSpec& spec_of(Call call); +clients::Method method_of(Call call); +Host host_of(Call call); +std::size_t call_count(); +const CallSpec& spec_at(std::size_t index); + +// Fills `{placeholders}` in order with `segments`. Each segment must pass +// llm::Service::valid_id; wrong count or bad id throws llm::ApiError::invalid. +std::string render(Call call, std::initializer_list segments = {}); + +} // namespace molo::xai::platform diff --git a/src/xai/platform/caps.h b/src/xai/platform/caps.h new file mode 100644 index 0000000..4fcc5d5 --- /dev/null +++ b/src/xai/platform/caps.h @@ -0,0 +1,59 @@ +#pragma once + +// Static ceilings for the xAI platform module. Never autotuned. Numbers marked +// "doc" come from docs.x.ai; the rest are our own ceilings (see SPEC.md). + +#include + +namespace molo::xai::platform { + +struct PlatformCaps { + // Ids and text. + static constexpr std::size_t kMaxNameChars = 256; + static constexpr std::size_t kMaxFilterChars = 4096; + static constexpr std::size_t kMaxQueryChars = 8000; + static constexpr std::size_t kMaxFieldsJsonBytes = 64u * 1024u; + // Pagination. + static constexpr int kMaxLimit = 1000; // custom voices: 1..1000 (doc) + static constexpr int kMaxPhoneNumberLimit = 100; // doc: clamped to 100 + static constexpr std::size_t kMaxPages = 100; // page walks (llm::Caps) + // Files and collections. + static constexpr std::size_t kMaxFileBytes = 50u * 1024u * 1024u; // doc: files API + static constexpr std::size_t kMaxCollectionDocBytes = 100u * 1024u * 1024u; // doc + static constexpr std::size_t kMaxCollectionIds = 32; + static constexpr std::size_t kMaxBatchFileIds = 100; + static constexpr long kMinExpirySeconds = 3600; // doc + static constexpr long kMaxExpirySeconds = 2592000; // doc: 30 days + // Voice REST. + static constexpr std::size_t kMaxTtsChars = 60000; // doc + static constexpr std::size_t kMaxSttBytes = 500u * 1024u * 1024u; // doc + static constexpr std::size_t kMaxCustomVoiceBytes = 50u * 1024u * 1024u; + static constexpr std::size_t kMaxKeyterms = 100; // doc + static constexpr std::size_t kMaxKeytermChars = 50; // doc + static constexpr int kMaxChannels = 8; // doc + static constexpr std::size_t kMaxReplaceEntries = 100; + static constexpr std::size_t kMaxReplaceChars = 200; + static constexpr long kMaxClientSecretSeconds = 3600; // doc + static constexpr std::size_t kMaxSipAddresses = 64; + // Realtime and streams (WebSocket). + static constexpr std::size_t kMaxInstructionChars = 32000; + static constexpr std::size_t kMaxSessionTools = 64; + static constexpr std::size_t kMaxToolFieldList = 20; // doc: handles max 20 + static constexpr std::size_t kMaxDomainList = 5; // doc + static constexpr std::size_t kMaxAudioChunkBytes = 256u * 1024u; + static constexpr std::size_t kMaxTextDeltaChars = 60000; // doc: tts delta + static constexpr std::size_t kMaxItemTextChars = 32000; + static constexpr int kConnectTimeoutMs = 10000; + static constexpr int kHandshakeTimeoutMs = 10000; + static constexpr int kIoTimeoutMs = 5000; + static constexpr int kPollIntervalMs = 200; + static constexpr int kSetupTimeoutMs = 15000; + static constexpr int kMaxSessionSeconds = 1800; + static constexpr std::size_t kMaxEventsPerWait = 4096; + static constexpr std::size_t kMaxStreamAudioBytes = 64u * 1024u * 1024u; + // Webhooks (Standard Webhooks). + static constexpr long kWebhookToleranceSeconds = 300; + static constexpr std::size_t kMaxWebhookBodyBytes = 1024u * 1024u; +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/clients.cpp b/src/xai/platform/clients.cpp new file mode 100644 index 0000000..9bf7d24 --- /dev/null +++ b/src/xai/platform/clients.cpp @@ -0,0 +1,28 @@ +#include "xai/platform/clients.h" + +namespace molo::xai::platform { + +llm::ApiClientConfig PlatformClients::api_config() { + llm::ApiClientConfig c; + c.vendor = "xai"; + c.base_url = PlatformEndpoints::kApiBase; + c.key_env = PlatformEndpoints::kApiKeyEnv; + c.auth = llm::AuthStyle::kBearer; + return c; +} + +llm::ApiClientConfig PlatformClients::management_config() { + llm::ApiClientConfig c; + c.vendor = "xai"; + c.base_url = PlatformEndpoints::kManagementBase; + c.key_env = PlatformEndpoints::kManagementKeyEnv; + c.auth = llm::AuthStyle::kBearer; + return c; +} + +PlatformClients PlatformClients::from_env() { + return PlatformClients(llm::ApiClient::from_env(api_config()), + llm::ApiClient::from_env(management_config())); +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/clients.h b/src/xai/platform/clients.h new file mode 100644 index 0000000..9c7e51a --- /dev/null +++ b/src/xai/platform/clients.h @@ -0,0 +1,46 @@ +#pragma once + +// The two credentials and two hosts of the xAI platform surface: +// api https://api.x.ai XAI_API_KEY +// management https://management-api.x.ai XAI_MANAGEMENT_KEY +// Both are Bearer tokens. A missing key makes every call on that host throw +// llm::NotConfiguredError before any network traffic. + +#include +#include + +#include "llm/api_client.h" + +namespace molo::xai::platform { + +struct PlatformEndpoints { + static constexpr const char* kApiBase = "https://api.x.ai"; + static constexpr const char* kManagementBase = "https://management-api.x.ai"; + static constexpr const char* kRealtimeUrl = "wss://api.x.ai/v1/realtime"; + static constexpr const char* kTtsStreamUrl = "wss://api.x.ai/v1/tts"; + static constexpr const char* kSttStreamUrl = "wss://api.x.ai/v1/stt"; + static constexpr const char* kApiKeyEnv = "XAI_API_KEY"; + static constexpr const char* kManagementKeyEnv = "XAI_MANAGEMENT_KEY"; +}; + +class PlatformClients { + public: + // Real HTTPS transports, keys from llm::Config. + static PlatformClients from_env(); + // Injected clients (tests). + PlatformClients(std::shared_ptr api, + std::shared_ptr management) + : api_(std::move(api)), management_(std::move(management)) {} + + static llm::ApiClientConfig api_config(); + static llm::ApiClientConfig management_config(); + + const std::shared_ptr& api() const { return api_; } + const std::shared_ptr& management() const { return management_; } + + private: + std::shared_ptr api_; + std::shared_ptr management_; +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/collections.cpp b/src/xai/platform/collections.cpp new file mode 100644 index 0000000..3e0b9b5 --- /dev/null +++ b/src/xai/platform/collections.cpp @@ -0,0 +1,207 @@ +#include "xai/platform/collections.h" + +#include + +#include "xai/platform/caps.h" + +namespace molo::xai::platform { + +namespace { +bool one_of(const std::string& v, std::initializer_list set) { + return std::any_of(set.begin(), set.end(), [&](const char* s) { return v == s; }); +} +} // namespace + +void CollectionsService::check_team(const std::string& team_id) const { + if (!team_id.empty()) require_uuid("team_id", team_id); +} + +Query CollectionsService::list_query(const ListOptions& o, bool documents) const { + check_team(o.team_id); + Query q; + q.add_if("team_id", o.team_id); + if (o.limit != 0) { + require_range("limit", o.limit, 1, PlatformCaps::kMaxLimit); + q.add_int("limit", o.limit); + } + if (!o.order.empty() && !one_of(o.order, {"ORDERING_ASCENDING", "ORDERING_DESCENDING"})) + bad("order must be ORDERING_ASCENDING or ORDERING_DESCENDING"); + if (!o.sort_by.empty()) { + bool ok = documents ? one_of(o.sort_by, {"DOCUMENTS_SORT_BY_NAME", "DOCUMENTS_SORT_BY_SIZE", + "DOCUMENTS_SORT_BY_AGE"}) + : one_of(o.sort_by, {"COLLECTIONS_SORT_BY_NAME", "COLLECTIONS_SORT_BY_AGE"}); + if (!ok) bad("sort_by is not a documented value"); + } + require_text("pagination_token", o.pagination_token, 512, false); + require_text("filter", o.filter, PlatformCaps::kMaxFilterChars, false); + require_text("name", o.name, PlatformCaps::kMaxNameChars, false); + q.add_if("order", o.order).add_if("sort_by", o.sort_by); + q.add_if("pagination_token", o.pagination_token).add_if("filter", o.filter); + if (documents) q.add_if("name", o.name); + return q; +} + +Json CollectionsService::spec_body(const CollectionSpec& s, bool create) const { + check_team(s.team_id); + Json b = Json::object(); + if (create || !s.name.empty()) { + require_text("collection_name", s.name, PlatformCaps::kMaxNameChars); + b.set("collection_name", s.name); + } + if (!s.description.empty()) { + require_text("collection_description", s.description, 2000); + b.set("collection_description", s.description); + } + if (!s.team_id.empty()) b.set("team_id", s.team_id); + if (create && !s.embedding_model.empty()) { + require_text("embedding_model", s.embedding_model, PlatformCaps::kMaxNameChars); + Json idx = Json::object(); + idx.set("model_name", s.embedding_model); + b.set("index_configuration", idx); + } + if (create && !s.metric_space.empty()) { + if (!one_of(s.metric_space, {"HNSW_METRIC_COSINE", "HNSW_METRIC_EUCLIDEAN", + "HNSW_METRIC_INNER_PRODUCT"})) + bad("metric_space is not a documented value"); + b.set("metric_space", s.metric_space); + } + if (!s.chunk_configuration.is_null()) { + if (!s.chunk_configuration.is_object()) bad("chunk_configuration must be an object"); + b.set("chunk_configuration", s.chunk_configuration); + } + if (create && !s.field_definitions.is_null()) { + if (!s.field_definitions.is_array()) bad("field_definitions must be an array"); + for (const Json& d : s.field_definitions.as_array()) { + const Json* k = d.is_object() ? d.find("key") : nullptr; + if (!k || !k->is_string() || k->as_string().empty()) bad("every field definition needs a key"); + } + b.set("field_definitions", s.field_definitions); + } + return b; +} + +Json CollectionsService::create(const CollectionSpec& spec) { + Json body = spec_body(spec, true); + return invoke(Call::kCollectionCreate, {}, &body); +} + +Json CollectionsService::list(const ListOptions& o) { + return invoke(Call::kCollectionList, {}, nullptr, list_query(o, false)); +} + +Json CollectionsService::get(const std::string& id, const std::string& team_id) { + check_id("collection", id); + check_team(team_id); + return invoke(Call::kCollectionGet, {id}, nullptr, Query().add_if("team_id", team_id)); +} + +Json CollectionsService::update(const std::string& id, const CollectionSpec& changes, + const Json& updates) { + check_id("collection", id); + Json body = spec_body(changes, false); + if (!updates.is_null()) { + if (!updates.is_array() || updates.as_array().empty()) bad("field_definition_updates must be a non-empty array"); + for (const Json& u : updates.as_array()) { + const Json* def = u.is_object() ? u.find("field_definition") : nullptr; + const Json* op = u.find("operation"); + if (!def || !def->is_object() || !def->find("key")) bad("an update needs field_definition.key"); + if (op && !(op->is_string() && one_of(op->as_string(), {"FIELD_DEFINITION_ADD", "FIELD_DEFINITION_DELETE"}))) + bad("operation must be FIELD_DEFINITION_ADD or FIELD_DEFINITION_DELETE"); + } + body.set("field_definition_updates", updates); + } + if (body.as_object().empty()) bad("nothing to update"); + return invoke(Call::kCollectionUpdate, {id}, &body); +} + +Json CollectionsService::remove(const std::string& id, bool confirm, const std::string& team_id) { + check_id("collection", id); + check_team(team_id); + require_confirm("deleting a collection", confirm); + return invoke(Call::kCollectionDelete, {id}, nullptr, Query().add_if("team_id", team_id)); +} + +namespace { +void check_fields(const PlatformService&, const Json& fields) { + if (fields.is_null()) return; + if (!fields.is_object()) throw llm::ApiError::invalid("xai", "fields must be an object"); + if (fields.dump().size() > PlatformCaps::kMaxFieldsJsonBytes) + throw llm::ApiError::invalid("xai", "fields over 64 KB"); +} +} // namespace + +Json CollectionsService::add_document(const std::string& cid, const std::string& fid, + const Json& fields, const std::string& team_id) { + check_id("collection", cid); + check_id("file", fid); + check_team(team_id); + check_fields(*this, fields); + Json body = Json::object(); + if (!team_id.empty()) body.set("team_id", team_id); + if (!fields.is_null()) body.set("fields", fields); + return invoke(Call::kDocAdd, {cid, fid}, &body); +} + +Json CollectionsService::upload_document(const std::string& cid, const std::string& name, + const std::string& content_type, + const std::string& data, const Json& fields) { + check_id("collection", cid); + require_text("name", name, PlatformCaps::kMaxNameChars); + require_text("content_type", content_type, 128); + if (name.find_first_of("\"\\/\r\n") != std::string::npos) bad("name has path or quote characters"); + if (data.empty()) bad("document is empty"); + if (data.size() > PlatformCaps::kMaxCollectionDocBytes) bad("document is over 100 MB"); + check_fields(*this, fields); + clients::body::MultipartBody form; + form.add_text("name", name); + form.add_text("content_type", content_type); + if (!fields.is_null()) form.add_text("fields", fields.dump()); + form.add_file("data", name, content_type, data); + return invoke_multipart(Call::kDocUpload, {cid}, form); +} + +Json CollectionsService::list_documents(const std::string& cid, const ListOptions& o) { + check_id("collection", cid); + return invoke(Call::kDocList, {cid}, nullptr, list_query(o, true)); +} + +Json CollectionsService::get_document(const std::string& cid, const std::string& fid, + const std::string& team_id) { + check_id("collection", cid); + check_id("file", fid); + check_team(team_id); + return invoke(Call::kDocGet, {cid, fid}, nullptr, Query().add_if("team_id", team_id)); +} + +Json CollectionsService::reindex_document(const std::string& cid, const std::string& fid, + const std::string& team_id) { + check_id("collection", cid); + check_id("file", fid); + check_team(team_id); + return invoke(Call::kDocReindex, {cid, fid}, nullptr, Query().add_if("team_id", team_id)); +} + +Json CollectionsService::remove_document(const std::string& cid, const std::string& fid, + bool confirm, const std::string& team_id) { + check_id("collection", cid); + check_id("file", fid); + check_team(team_id); + require_confirm("removing a document", confirm); + return invoke(Call::kDocRemove, {cid, fid}, nullptr, Query().add_if("team_id", team_id)); +} + +Json CollectionsService::batch_get(const std::string& cid, const std::vector& ids, + const std::string& team_id) { + check_id("collection", cid); + check_team(team_id); + if (ids.empty() || ids.size() > PlatformCaps::kMaxBatchFileIds) bad("file_ids must hold 1..100 ids"); + Query q; + q.add_if("team_id", team_id); + for (const std::string& id : ids) { + check_id("file", id); + q.add("file_ids", id); + } + return invoke(Call::kDocBatchGet, {cid}, nullptr, q); +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/collections.h b/src/xai/platform/collections.h new file mode 100644 index 0000000..e20f309 --- /dev/null +++ b/src/xai/platform/collections.h @@ -0,0 +1,69 @@ +#pragma once + +// Collections and their documents on management-api.x.ai (XAI_MANAGEMENT_KEY). +// Searching a collection is a different host and key: see DocumentSearch. + +#include +#include + +#include "xai/platform/platform_service.h" + +namespace molo::xai::platform { + +struct CollectionSpec { + std::string name; // required + std::string description; + std::string embedding_model; // index_configuration.model_name + std::string metric_space; // "" or HNSW_METRIC_COSINE|EUCLIDEAN|INNER_PRODUCT + Json chunk_configuration; // null or object, passed through (checked in SPEC) + Json field_definitions; // null or array of {key, required, unique, ...} + std::string team_id; // optional UUID, else derived from the key +}; + +struct ListOptions { + std::string team_id; + int limit = 0; // 0 = server default + std::string order; // ORDERING_ASCENDING | ORDERING_DESCENDING + std::string sort_by; // see the validators in collections.cpp + std::string pagination_token; + std::string name; // documents only + std::string filter; +}; + +class CollectionsService : public PlatformService { + public: + explicit CollectionsService(std::shared_ptr management) + : PlatformService(std::move(management), Host::kManagement) {} + + Json create(const CollectionSpec& spec); + Json list(const ListOptions& options = {}); + Json get(const std::string& collection_id, const std::string& team_id = ""); + // Renames and/or changes chunking / field definitions (adds and deletes). + Json update(const std::string& collection_id, const CollectionSpec& changes, + const Json& field_definition_updates = Json()); + Json remove(const std::string& collection_id, bool confirm, const std::string& team_id = ""); + + // Step 2 of the two step upload: attach an uploaded file (Files API). + Json add_document(const std::string& collection_id, const std::string& file_id, + const Json& fields = Json(), const std::string& team_id = ""); + // One step multipart upload (documented in the guide only: see SPEC Unverified). + Json upload_document(const std::string& collection_id, const std::string& name, + const std::string& content_type, const std::string& data, + const Json& fields = Json()); + Json list_documents(const std::string& collection_id, const ListOptions& options = {}); + Json get_document(const std::string& collection_id, const std::string& file_id, + const std::string& team_id = ""); + Json reindex_document(const std::string& collection_id, const std::string& file_id, + const std::string& team_id = ""); + Json remove_document(const std::string& collection_id, const std::string& file_id, + bool confirm, const std::string& team_id = ""); + Json batch_get(const std::string& collection_id, const std::vector& file_ids, + const std::string& team_id = ""); + + private: + void check_team(const std::string& team_id) const; + Query list_query(const ListOptions& o, bool documents) const; + Json spec_body(const CollectionSpec& s, bool create) const; +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/documents_search.cpp b/src/xai/platform/documents_search.cpp new file mode 100644 index 0000000..66023d8 --- /dev/null +++ b/src/xai/platform/documents_search.cpp @@ -0,0 +1,70 @@ +#include "xai/platform/documents_search.h" + +#include "xai/platform/caps.h" + +namespace molo::xai::platform { + +Json DocumentSearch::build(const DocumentSearchRequest& r) const { + require_text("query", r.query, PlatformCaps::kMaxQueryChars); + if (r.collection_ids.empty() || r.collection_ids.size() > PlatformCaps::kMaxCollectionIds) + bad("collection_ids must hold 1..32 ids"); + Json ids = Json::array(); + for (const std::string& id : r.collection_ids) { + check_id("collection", id); + ids.push(id); + } + Json source = Json::object(); + source.set("collection_ids", ids); + if (!r.rag_pipeline.empty()) { + if (r.rag_pipeline != "chroma_db" && r.rag_pipeline != "es") bad("rag_pipeline must be chroma_db or es"); + source.set("rag_pipeline", r.rag_pipeline); + } + Json b = Json::object(); + b.set("query", r.query); + b.set("source", source); + if (!r.filter.empty()) { + require_text("filter", r.filter, PlatformCaps::kMaxFilterChars); + b.set("filter", r.filter); + } + if (!r.instructions.empty()) { + require_text("instructions", r.instructions, PlatformCaps::kMaxQueryChars); + b.set("instructions", r.instructions); + } + if (r.limit != 0) { + require_range("limit", r.limit, 1, 1000); + b.set("limit", Json(r.limit)); + } + if (!r.ranking_metric.empty()) { + if (r.ranking_metric != "RANKING_METRIC_L2_DISTANCE" && + r.ranking_metric != "RANKING_METRIC_COSINE_SIMILARITY") + bad("ranking_metric is not a documented value"); + b.set("ranking_metric", r.ranking_metric); + } + if (!r.retrieval_mode.empty()) { + if (r.retrieval_mode != "hybrid" && r.retrieval_mode != "semantic" && r.retrieval_mode != "keyword") + bad("retrieval_mode must be hybrid, semantic or keyword"); + Json mode = Json::object(); + if (!r.retrieval_options.is_null()) { + if (!r.retrieval_options.is_object()) bad("retrieval_options must be an object"); + mode = r.retrieval_options; + } + mode.set("type", r.retrieval_mode); + b.set("retrieval_mode", mode); + } else if (!r.retrieval_options.is_null()) { + bad("retrieval_options needs retrieval_mode"); + } + if (!r.group_by.is_null()) { + const Json* keys = r.group_by.is_object() ? r.group_by.find("keys") : nullptr; + if (!keys || !keys->is_array() || keys->as_array().empty()) + bad("group_by.keys must be a non-empty array"); + b.set("group_by", r.group_by); + } + return b; +} + +Json DocumentSearch::search(const DocumentSearchRequest& r) { + Json body = build(r); + return invoke(Call::kDocumentsSearch, {}, &body); +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/documents_search.h b/src/xai/platform/documents_search.h new file mode 100644 index 0000000..f88b1bd --- /dev/null +++ b/src/xai/platform/documents_search.h @@ -0,0 +1,37 @@ +#pragma once + +// POST /v1/documents/search on api.x.ai (XAI_API_KEY): semantic, keyword or +// hybrid search over one or more collections. + +#include +#include + +#include "xai/platform/platform_service.h" + +namespace molo::xai::platform { + +struct DocumentSearchRequest { + std::string query; // required + std::vector collection_ids; // 1..kMaxCollectionIds + std::string rag_pipeline; // "" | chroma_db | es + std::string filter; // AIP-160 metadata filter + std::string instructions; + int limit = 0; // 0 = server default + std::string ranking_metric; // "" | RANKING_METRIC_L2_DISTANCE | ..._COSINE_SIMILARITY + std::string retrieval_mode; // "" | hybrid | semantic | keyword + Json retrieval_options; // extra keys merged into retrieval_mode (reranker, search_multiplier) + Json group_by; // null or {keys:[...], aggregate:{min_k|max_k:{k,keys}}} +}; + +class DocumentSearch : public PlatformService { + public: + explicit DocumentSearch(std::shared_ptr api) + : PlatformService(std::move(api), Host::kApi) {} + + // Request body exactly as sent; throws on invalid input. + Json build(const DocumentSearchRequest& request) const; + // Returns {matches:[{file_id, chunk_id, chunk_content, score, collection_ids, fields, page_number?}]}. + Json search(const DocumentSearchRequest& request); +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/files.cpp b/src/xai/platform/files.cpp new file mode 100644 index 0000000..09f7550 --- /dev/null +++ b/src/xai/platform/files.cpp @@ -0,0 +1,114 @@ +#include "xai/platform/files.h" + +#include "xai/platform/caps.h" + +namespace molo::xai::platform { + +namespace { +bool safe_filename(const std::string& s) { + if (s.empty() || s.size() > PlatformCaps::kMaxNameChars) return false; + for (unsigned char c : s) + if (c < 0x20 || c == 0x7f || c == '"' || c == '\\' || c == '/') return false; + return true; +} +} // namespace + +Json FilesService::upload(const std::string& filename, const std::string& content_type, + const std::string& data, long expires_after_seconds, + const std::string& purpose) { + if (!safe_filename(filename)) bad("filename is empty, too long or has path or quote characters"); + require_text("content_type", content_type, 128); + if (data.empty()) bad("file is empty"); + if (data.size() > PlatformCaps::kMaxFileBytes) bad("file is over 50 MB"); + if (expires_after_seconds != 0) + require_range("expires_after", expires_after_seconds, PlatformCaps::kMinExpirySeconds, + PlatformCaps::kMaxExpirySeconds); + require_text("purpose", purpose, 64, false); + clients::body::MultipartBody form; + // Spec: expires_after must come before the file part. + if (expires_after_seconds != 0) form.add_text("expires_after", std::to_string(expires_after_seconds)); + if (!purpose.empty()) form.add_text("purpose", purpose); + form.add_file("file", filename, content_type, data); + return invoke_multipart(Call::kFileUpload, {}, form); +} + +Json FilesService::list(const FileListOptions& o) { + Query q; + if (o.limit != 0) { + require_range("limit", o.limit, 1, PlatformCaps::kMaxLimit); + q.add_int("limit", o.limit); + } + if (!o.order.empty() && o.order != "asc" && o.order != "desc") bad("order must be asc or desc"); + if (!o.sort_by.empty() && o.sort_by != "created_at" && o.sort_by != "filename" && + o.sort_by != "size") + bad("sort_by must be created_at, filename or size"); + require_text("pagination_token", o.pagination_token, 512, false); + require_text("filter", o.filter, PlatformCaps::kMaxFilterChars, false); + q.add_if("order", o.order).add_if("sort_by", o.sort_by); + q.add_if("pagination_token", o.pagination_token).add_if("filter", o.filter); + return invoke(Call::kFileList, {}, nullptr, q); +} + +FileListing FilesService::list_all(std::size_t max_pages, const std::string& filter) { + if (max_pages == 0 || max_pages > PlatformCaps::kMaxPages) bad("max_pages must be 1..100"); + constexpr int kPage = 100; + FileListing out; + FileListOptions o; + o.limit = kPage; + o.filter = filter; + for (;;) { + Json page = list(o); + ++out.pages; + const Json* data = page.find("data"); + std::size_t n = data && data->is_array() ? data->as_array().size() : 0; + if (n) for (const Json& f : data->as_array()) out.files.push(f); + const Json* tok = page.find("pagination_token"); + std::string next = tok && tok->is_string() ? tok->as_string() : ""; + if (n < static_cast(kPage) || next.empty()) return out; + if (out.pages >= max_pages) { + out.truncated = true; // loud: more pages existed + return out; + } + o.pagination_token = next; + } +} + +Json FilesService::get(const std::string& id) { + check_id("file", id); + return invoke(Call::kFileGet, {id}); +} + +llm::RawResponse FilesService::content(const std::string& id, const std::string& format) { + check_id("file", id); + if (!format.empty() && format != "original" && format != "text") + bad("format must be original or text"); + Query q; + q.add_if("format", format); + return invoke_raw(Call::kFileContent, {id}, nullptr, "", q); +} + +Json FilesService::create_public_url(const std::string& id, long seconds) { + check_id("file", id); + Json body = Json::object(); + if (seconds != 0) { + require_range("expires_after", seconds, PlatformCaps::kMinExpirySeconds, + PlatformCaps::kMaxExpirySeconds); + body.set("expires_after", Json(seconds)); + } + return invoke(Call::kPublicUrlCreate, {id}, &body); +} + +Json FilesService::revoke_public_url(const std::string& id, bool confirm) { + check_id("file", id); + require_confirm("revoking a public URL", confirm); + Json body = Json::object(); + return invoke(Call::kPublicUrlRevoke, {id}, &body); +} + +Json FilesService::remove(const std::string& id, bool confirm) { + check_id("file", id); + require_confirm("deleting a file", confirm); + return invoke(Call::kFileDelete, {id}); +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/files.h b/src/xai/platform/files.h new file mode 100644 index 0000000..aad6afe --- /dev/null +++ b/src/xai/platform/files.h @@ -0,0 +1,47 @@ +#pragma once + +// Files API on api.x.ai: upload (multipart, max 50 MB), list with a bounded +// page walk, retrieve, content download, delete, public URLs. + +#include + +#include "xai/platform/platform_service.h" + +namespace molo::xai::platform { + +struct FileListOptions { + int limit = 0; // 0: server default, else 1..kMaxLimit + std::string order; // "", "asc", "desc" + std::string sort_by; // "", "created_at", "filename", "size" + std::string pagination_token; + std::string filter; // AIP-160 +}; + +struct FileListing { + Json files = Json::array(); + bool truncated = false; // page cap hit while more pages existed + std::size_t pages = 0; +}; + +class FilesService : public PlatformService { + public: + explicit FilesService(std::shared_ptr api) + : PlatformService(std::move(api), Host::kApi) {} + + // expires_after_seconds 0 = never expires, else 3600..2592000. + Json upload(const std::string& filename, const std::string& content_type, + const std::string& data, long expires_after_seconds = 0, + const std::string& purpose = ""); + Json list(const FileListOptions& options = {}); + // Walks pagination_token until a short page, at most `max_pages` pages. + FileListing list_all(std::size_t max_pages, const std::string& filter = ""); + Json get(const std::string& file_id); + // format "" | "original" | "text". + llm::RawResponse content(const std::string& file_id, const std::string& format = ""); + Json create_public_url(const std::string& file_id, long expires_after_seconds = 0); + // Destructive: no default. confirm=false throws. + Json revoke_public_url(const std::string& file_id, bool confirm); + Json remove(const std::string& file_id, bool confirm); +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/platform_service.cpp b/src/xai/platform/platform_service.cpp new file mode 100644 index 0000000..0379d7b --- /dev/null +++ b/src/xai/platform/platform_service.cpp @@ -0,0 +1,118 @@ +#include "xai/platform/platform_service.h" + +#include + +#include "xai/platform/clients.h" + +namespace molo::xai::platform { + +namespace { +std::string encode(const std::string& s) { + static const char* hex = "0123456789ABCDEF"; + std::string out; + for (unsigned char c : s) { + if (std::isalnum(c) || c == '-' || c == '_' || c == '~' || c == '.') { + out.push_back(static_cast(c)); + } else { + out.push_back('%'); + out.push_back(hex[c >> 4]); + out.push_back(hex[c & 15]); + } + } + return out; +} +} // namespace + +Query& Query::add(const std::string& name, const std::string& value) { + pairs_.emplace_back(name, value); + return *this; +} +Query& Query::add_int(const std::string& name, long value) { + return add(name, std::to_string(value)); +} +Query& Query::add_bool(const std::string& name, bool value) { + return add(name, value ? "true" : "false"); +} +Query& Query::add_if(const std::string& name, const std::string& value) { + if (!value.empty()) add(name, value); + return *this; +} +std::string Query::str() const { + std::string out; + for (const auto& [k, v] : pairs_) { + out += out.empty() ? '?' : '&'; + out += encode(k) + "=" + encode(v); + } + return out; +} + +PlatformService::PlatformService(std::shared_ptr client, Host host) + : llm::Service(std::move(client)), host_(host) {} + +void PlatformService::bad(const std::string& why) const { + throw llm::ApiError::invalid("xai", why); +} + +bool PlatformService::valid_uuid(const std::string& s) { + if (s.size() != 36) return false; + for (std::size_t i = 0; i < s.size(); ++i) { + bool dash = i == 8 || i == 13 || i == 18 || i == 23; + if (dash ? s[i] != '-' : !std::isxdigit(static_cast(s[i]))) return false; + } + return true; +} + +void PlatformService::require_uuid(const std::string& what, const std::string& s) const { + if (!valid_uuid(s)) bad(what + " must be a UUID"); +} + +void PlatformService::require_text(const std::string& what, const std::string& s, + std::size_t max_chars, bool required) const { + if (required && s.empty()) bad(what + " is required"); + if (s.size() > max_chars) bad(what + " is over " + std::to_string(max_chars) + " characters"); + for (unsigned char c : s) + if (c == 0) bad(what + " has a NUL byte"); +} + +void PlatformService::require_range(const std::string& what, long v, long lo, long hi) const { + if (v < lo || v > hi) + bad(what + " must be in " + std::to_string(lo) + ".." + std::to_string(hi)); +} + +void PlatformService::require_confirm(const std::string& what, bool confirm) const { + if (!confirm) bad(what + " is destructive or costs money: pass confirm=true"); +} + +std::string PlatformService::path_of(Call call, std::initializer_list segments, + const Query& query) const { + if (host_of(call) != host_) bad("call belongs to the other xAI host"); + // The client must carry this host's credential: never send the management + // key to the inference host or the API key to the management host. + const char* want = host_ == Host::kApi ? PlatformEndpoints::kApiKeyEnv + : PlatformEndpoints::kManagementKeyEnv; + if (client().config().key_env != want) bad(std::string("client is not configured for ") + want); + return render(call, segments) + query.str(); +} + +Json PlatformService::invoke(Call call, std::initializer_list segments, + const Json* body, const Query& query) { + std::string path = path_of(call, segments, query); + return client().request(method_of(call), path, body); +} + +llm::RawResponse PlatformService::invoke_raw(Call call, + std::initializer_list segments, + const std::string* body, + const std::string& content_type, + const Query& query) { + std::string path = path_of(call, segments, query); + return client().request_raw(method_of(call), path, body, content_type); +} + +Json PlatformService::invoke_multipart(Call call, std::initializer_list segments, + const clients::body::MultipartBody& form) { + if (method_of(call) != clients::Method::kPost) bad("multipart needs a POST call"); + return client().post_multipart(path_of(call, segments, Query()), form); +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/platform_service.h b/src/xai/platform/platform_service.h new file mode 100644 index 0000000..a9f0697 --- /dev/null +++ b/src/xai/platform/platform_service.h @@ -0,0 +1,66 @@ +#pragma once + +// Base of every xAI platform REST service: table driven calls, validated +// path segments, bounded query strings. One instance talks to one host +// (api.x.ai with XAI_API_KEY, or management-api.x.ai with XAI_MANAGEMENT_KEY). + +#include +#include +#include +#include +#include + +#include "clients/body/json.h" +#include "llm/api_client.h" +#include "xai/platform/calls.h" + +namespace molo::xai::platform { + +using Json = clients::body::Json; + +// Percent-encoded query string builder. Values are encoded, empty values +// skipped by the add_* helpers that take optionals. +class Query { + public: + Query& add(const std::string& name, const std::string& value); + Query& add_int(const std::string& name, long value); + Query& add_bool(const std::string& name, bool value); + Query& add_if(const std::string& name, const std::string& value); // skips "" + bool empty() const { return pairs_.empty(); } + std::string str() const; // "" or "?a=b&c=d" + const std::vector>& pairs() const { return pairs_; } + + private: + std::vector> pairs_; +}; + +class PlatformService : public llm::Service { + public: + PlatformService(std::shared_ptr client, Host host); + + // Checks used by every service (throw llm::ApiError::invalid). + static bool valid_uuid(const std::string& s); + void require_uuid(const std::string& what, const std::string& s) const; + void require_text(const std::string& what, const std::string& s, std::size_t max_chars, + bool required = true) const; + void require_range(const std::string& what, long v, long lo, long hi) const; + void require_confirm(const std::string& what, bool confirm) const; + + protected: + Json invoke(Call call, std::initializer_list segments, + const Json* body = nullptr, const Query& query = Query()); + llm::RawResponse invoke_raw(Call call, std::initializer_list segments, + const std::string* body = nullptr, + const std::string& content_type = "", + const Query& query = Query()); + Json invoke_multipart(Call call, std::initializer_list segments, + const clients::body::MultipartBody& form); + [[noreturn]] void bad(const std::string& why) const; + std::string path_of(Call call, std::initializer_list segments, + const Query& query) const; + + private: + Host host_; +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/realtime_rest.cpp b/src/xai/platform/realtime_rest.cpp new file mode 100644 index 0000000..1a64a62 --- /dev/null +++ b/src/xai/platform/realtime_rest.cpp @@ -0,0 +1,147 @@ +#include "xai/platform/realtime_rest.h" + +#include + +#include "xai/platform/caps.h" +#include "xai/platform/voice_types.h" + +namespace molo::xai::platform { + +using E = VoiceEnums; + +bool RealtimeRest::valid_e164(const std::string& s) { + if (s.size() < 8 || s.size() > 16 || s[0] != '+' || s[1] < '1' || s[1] > '9') return false; + for (std::size_t i = 1; i < s.size(); ++i) + if (!std::isdigit(static_cast(s[i]))) return false; + return true; +} + +Json RealtimeRest::build_client_secret(const ClientSecretRequest& r) const { + Json b = Json::object(); + if (r.expires_seconds != 0) { + require_range("expires_seconds", r.expires_seconds, 1, PlatformCaps::kMaxClientSecretSeconds); + Json e = Json::object(); + e.set("seconds", Json(r.expires_seconds)); + b.set("expires_after", e); + } + Json s = Json::object(); + if (!r.model.empty()) { + if (!E::has(E::kRealtimeModels, r.model)) bad("model is not a documented realtime model"); + s.set("model", r.model); + } + if (!r.reasoning_effort.empty()) { + if (r.reasoning_effort != "high" && r.reasoning_effort != "none") bad("reasoning_effort must be high or none"); + Json re = Json::object(); + re.set("effort", r.reasoning_effort); + s.set("reasoning", re); + } + if (!s.as_object().empty()) b.set("session", s); + return b; +} + +Json RealtimeRest::client_secret(const ClientSecretRequest& r) { + Json body = build_client_secret(r); + return invoke(Call::kClientSecret, {}, &body); +} + +Json RealtimeRest::build_phone_number(const PhoneNumberSpec& p) const { + if (p.origin != "byo_trunk" && p.origin != "xai_provisioned") bad("origin must be byo_trunk or xai_provisioned"); + require_text("name", p.name, PlatformCaps::kMaxNameChars); + if (!p.agent_id.empty() && !p.webhook_url.empty()) bad("agent_id and webhook are mutually exclusive"); + Json b = Json::object(); + b.set("origin", p.origin); + b.set("name", p.name); + if (!p.agent_id.empty()) { + check_id("agent", p.agent_id); + b.set("agent_id", p.agent_id); + } + if (p.origin == "byo_trunk") { + if (!valid_e164(p.phone_number)) bad("phone_number must be E.164 (+15551234567)"); + if (!p.area_code.empty()) bad("area_code is for xai_provisioned only"); + b.set("phone_number", p.phone_number); + } else { + if (!p.phone_number.empty()) bad("phone_number is for byo_trunk only"); + if (!p.area_code.empty()) { + if (p.area_code.size() != 3) bad("area_code must be 3 digits"); + for (char c : p.area_code) if (!std::isdigit(static_cast(c))) bad("area_code must be 3 digits"); + b.set("area_code", p.area_code); + } + } + if (p.sip_username.empty() != p.sip_password.empty()) bad("sip username and password go together"); + if (!p.sip_username.empty() || !p.allowed_addresses.empty()) { + Json sip = Json::object(); + if (!p.sip_username.empty()) { + require_text("sip username", p.sip_username, 128); + require_text("sip password", p.sip_password, 256); + sip.set("auth_username", p.sip_username); + sip.set("auth_password", p.sip_password); + } + if (p.allowed_addresses.size() > PlatformCaps::kMaxSipAddresses) bad("too many allowed_addresses"); + if (!p.allowed_addresses.empty()) { + Json arr = Json::array(); + for (const std::string& a : p.allowed_addresses) { + require_text("allowed address", a, 64); + if (a.find_first_not_of("0123456789abcdefABCDEF.:/") != std::string::npos) bad("allowed address is not a CIDR range"); + arr.push(a); + } + sip.set("allowed_addresses", arr); + } + b.set("sip_auth", sip); + } + if (!p.webhook_url.empty()) { + require_text("webhook url", p.webhook_url, 2048); + if (p.webhook_url.rfind("https://", 0) != 0) bad("webhook url must be https"); + Json w = Json::object(); + w.set("url", p.webhook_url); + if (!p.webhook_name.empty()) w.set("name", p.webhook_name); + if (!p.webhook_auth_url.empty()) w.set("auth_url", p.webhook_auth_url); + if (!p.webhook_auth_token.empty()) w.set("auth_token", p.webhook_auth_token); + b.set("webhook", w); + } + return b; +} + +Json RealtimeRest::create_phone_number(const PhoneNumberSpec& p) { + Json body = build_phone_number(p); + return invoke(Call::kPhoneCreate, {}, &body); +} + +Json RealtimeRest::list_phone_numbers(int limit, const std::string& token, + const std::string& agent_id) { + Query q; + if (limit != 0) { + require_range("limit", limit, 1, PlatformCaps::kMaxPhoneNumberLimit); + q.add_int("limit", limit); + } + require_text("pagination_token", token, 256, false); + q.add_if("pagination_token", token); + if (!agent_id.empty()) check_id("agent", agent_id); + q.add_if("agent_id", agent_id); + return invoke(Call::kPhoneList, {}, nullptr, q); +} + +Json RealtimeRest::remove_phone_number(const std::string& id, bool confirm) { + check_id("phone number", id); + require_confirm("removing a phone number", confirm); + return invoke(Call::kPhoneDelete, {id}); +} + +Json RealtimeRest::refer_call(const std::string& call_id, const std::string& target, + bool confirm) { + check_id("call", call_id); + require_confirm("transferring a call", confirm); + if (target.rfind("tel:", 0) != 0 && target.rfind("sip:", 0) != 0) bad("target_uri must be a tel: or sip: URI"); + require_text("target_uri", target, 512); + Json b = Json::object(); + b.set("target_uri", target); + return invoke(Call::kCallRefer, {call_id}, &b); +} + +Json RealtimeRest::hangup_call(const std::string& call_id, bool confirm) { + check_id("call", call_id); + require_confirm("hanging up a call", confirm); + Json b = Json::object(); + return invoke(Call::kCallHangup, {call_id}, &b); +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/realtime_rest.h b/src/xai/platform/realtime_rest.h new file mode 100644 index 0000000..342a2e1 --- /dev/null +++ b/src/xai/platform/realtime_rest.h @@ -0,0 +1,54 @@ +#pragma once + +// HTTP side of the realtime voice API on api.x.ai (XAI_API_KEY): ephemeral +// client secrets for browser sockets, SIP phone numbers, and call control +// (refer, hangup). The WebSocket itself is RealtimeSession. + +#include +#include + +#include "xai/platform/platform_service.h" + +namespace molo::xai::platform { + +struct ClientSecretRequest { + long expires_seconds = 0; // 0 = server default (600), else 1..3600 + std::string model; // "" | grok-voice-latest | grok-voice-3.0 | grok-voice-2.0 + std::string reasoning_effort; // "" | high | none +}; + +struct PhoneNumberSpec { + std::string origin = "byo_trunk"; // byo_trunk | xai_provisioned + std::string name; // required + std::string agent_id; // mutually exclusive with webhook_url + std::string area_code; // xai_provisioned only, 3 digits + std::string phone_number; // byo_trunk only, E.164 + std::string sip_username, sip_password; // together or not at all + std::vector allowed_addresses; // CIDR ranges + std::string webhook_url, webhook_name, webhook_auth_url, webhook_auth_token; +}; + +class RealtimeRest : public PlatformService { + public: + explicit RealtimeRest(std::shared_ptr api) + : PlatformService(std::move(api), Host::kApi) {} + + static bool valid_e164(const std::string& s); + + Json build_client_secret(const ClientSecretRequest& request) const; + // {value, expires_at}: the value is a credential, never log it. + Json client_secret(const ClientSecretRequest& request = {}); + + Json build_phone_number(const PhoneNumberSpec& spec) const; + // Response carries webhook.dispatch_signing_secret exactly once. + Json create_phone_number(const PhoneNumberSpec& spec); + Json list_phone_numbers(int limit = 0, const std::string& pagination_token = "", + const std::string& agent_id = ""); + Json remove_phone_number(const std::string& phone_number_id, bool confirm); + + // Transfers a SIP call; blocks until the destination answers. {} on success. + Json refer_call(const std::string& call_id, const std::string& target_uri, bool confirm); + Json hangup_call(const std::string& call_id, bool confirm); +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/realtime_session.cpp b/src/xai/platform/realtime_session.cpp new file mode 100644 index 0000000..9509e55 --- /dev/null +++ b/src/xai/platform/realtime_session.cpp @@ -0,0 +1,311 @@ +#include "xai/platform/realtime_session.h" + +#include + +#include "llm/api_client.h" +#include "security/crypto/Base64.h" +#include "xai/platform/clients.h" +#include "xai/platform/platform_service.h" +#include "xai/platform/voice_types.h" + +namespace molo::xai::platform { + +namespace { + +[[noreturn]] void bad(const std::string& why) { throw llm::ApiError::invalid("xai", why); } + +long now_ms() { + return std::chrono::duration_cast( + std::chrono::steady_clock::now().time_since_epoch()) + .count(); +} + +std::string build_url(const RealtimeOptions& o) { + std::string base = o.url.empty() ? PlatformEndpoints::kRealtimeUrl : o.url; + Query q; + if (!o.model.empty()) { + if (!VoiceEnums::has(VoiceEnums::kRealtimeModels, o.model)) bad("model is not a documented realtime model"); + q.add("model", o.model); + } + if (!o.reasoning_effort.empty()) { + if (o.reasoning_effort != "high" && o.reasoning_effort != "none") bad("reasoning effort must be high or none"); + q.add("reasoning.effort", o.reasoning_effort); + } + if (!o.call_id.empty()) { + if (!llm::Service::valid_id(o.call_id)) bad("bad call_id"); + q.add("call_id", o.call_id); + } + if (!o.conversation_id.empty()) { + if (!llm::Service::valid_id(o.conversation_id)) bad("bad conversation_id"); + q.add("conversation_id", o.conversation_id); + } + std::string s = q.str(); + return XaiSocket::with_query(base, s.empty() ? "" : s.substr(1)); +} + +Json text_part(const char* type, const std::string& text) { + Json p = Json::object(); + p.set("type", type); + p.set("text", text); + return p; +} + +void check_text(const std::string& what, const std::string& s, std::size_t max) { + if (s.empty() || s.size() > max) bad(what + " must be 1.." + std::to_string(max) + " characters"); +} + +} // namespace + +RealtimeSession::RealtimeSession(std::string token, RealtimeOptions options) + : token_(token), + options_(options), + socket_("realtime", build_url(options), std::move(token), options.auth, options.socket) {} + +std::string RealtimeSession::url() const { return build_url(options_); } + +void RealtimeSession::connect() { + socket_.connect(); + long deadline = now_ms() + options_.setup_timeout_ms; + for (;;) { + long left = deadline - now_ms(); + if (left <= 0) { + socket_.close(); + throw llm::ApiError("xai", 504, "timeout", "session.created not received in time"); + } + auto ev = socket_.next(static_cast(left)); + if (!ev) continue; + if (ev->type == "websocket.close" || ev->is_error()) { + std::string why = ev->type == "websocket.close" ? "server closed before session.created" + : "server error before session.created"; + socket_.close(); + throw llm::ApiError("xai", 502, "UNAVAILABLE", why); + } + if (ev->type == "conversation.created") { + const Json* c = ev->body.find("conversation"); + if (c && c->is_object()) conversation_id_ = llm::Service::string_at(*c, "id"); + } + bool created = ev->type == "session.created"; + setup_events_.push_back(std::move(*ev)); + if (created) { + // The docs list conversation.created both before and after + // session.created: settle it briefly, keep anything else for next(). + if (conversation_id_.empty()) { + if (auto more = socket_.next(250)) { + if (more->type == "conversation.created") { + if (const Json* c = more->body.find("conversation"); c && c->is_object()) + conversation_id_ = llm::Service::string_at(*c, "id"); + setup_events_.push_back(std::move(*more)); + } else { + pending_.push_back(std::move(*more)); + } + } + } + return; + } + if (setup_events_.size() > 16) bad("too many events before session.created"); + } +} + +void RealtimeSession::close() { socket_.close(); } + +std::optional RealtimeSession::next(int wait_ms) { + if (!pending_.empty()) { + WsEvent ev = std::move(pending_.front()); + pending_.pop_front(); + return ev; + } + return socket_.next(wait_ms); +} + +void RealtimeSession::send(Json message) { socket_.send_json(message); } + +void RealtimeSession::update_session(const SessionConfig& config) { send(config.update_message()); } + +void RealtimeSession::append_audio(const std::string& bytes) { + if (bytes.empty() || bytes.size() > PlatformCaps::kMaxAudioChunkBytes) bad("audio chunk must be 1..262144 bytes"); + if (input_binary_) { + socket_.send_binary(bytes); + return; + } + Json m = Json::object(); + m.set("type", "input_audio_buffer.append"); + m.set("audio", security::crypto::Base64::encode(bytes)); + send(m); +} + +void RealtimeSession::commit_audio() { + Json m = Json::object(); + m.set("type", "input_audio_buffer.commit"); + send(m); +} + +void RealtimeSession::clear_audio() { + Json m = Json::object(); + m.set("type", "input_audio_buffer.clear"); + send(m); +} + +void RealtimeSession::add_user_text(const std::string& text, const std::string& previous) { + check_text("text", text, PlatformCaps::kMaxItemTextChars); + Json item = Json::object(); + item.set("type", "message"); + item.set("role", "user"); + Json content = Json::array(); + content.push(text_part("input_text", text)); + item.set("content", content); + Json m = Json::object(); + m.set("type", "conversation.item.create"); + if (!previous.empty()) { + if (!llm::Service::valid_id(previous)) bad("bad previous_item_id"); + m.set("previous_item_id", previous); + } + m.set("item", item); + send(m); +} + +void RealtimeSession::seed_assistant_text(const std::string& text) { + check_text("text", text, PlatformCaps::kMaxItemTextChars); + Json item = Json::object(); + item.set("type", "message"); + item.set("role", "assistant"); + Json content = Json::array(); + content.push(text_part("text", text)); + item.set("content", content); + Json m = Json::object(); + m.set("type", "conversation.item.create"); + m.set("item", item); + send(m); +} + +void RealtimeSession::add_function_output(const std::string& call_id, const std::string& output) { + if (!llm::Service::valid_id(call_id)) bad("bad call_id"); + if (output.size() > PlatformCaps::kMaxItemTextChars) bad("function output too long"); + Json item = Json::object(); + item.set("type", "function_call_output"); + item.set("call_id", call_id); + item.set("output", output); + Json m = Json::object(); + m.set("type", "conversation.item.create"); + m.set("item", item); + send(m); +} + +void RealtimeSession::add_function_call_history(const std::string& name, + const std::string& arguments, + const std::string& call_id) { + check_text("name", name, 64); + if (arguments.size() > PlatformCaps::kMaxItemTextChars) bad("arguments too long"); + if (!call_id.empty() && !llm::Service::valid_id(call_id)) bad("bad call_id"); + Json item = Json::object(); + item.set("type", "function_call"); + item.set("name", name); + item.set("arguments", arguments); + if (!call_id.empty()) item.set("call_id", call_id); + Json m = Json::object(); + m.set("type", "conversation.item.create"); + m.set("item", item); + send(m); +} + +void RealtimeSession::force_message(const std::string& text, bool interruptible) { + check_text("text", text, PlatformCaps::kMaxItemTextChars); + Json item = Json::object(); + item.set("type", "force_message"); + item.set("role", "assistant"); + Json content = Json::array(); + content.push(text_part("output_text", text)); + item.set("content", content); + if (!interruptible) item.set("interruptible", Json(false)); + Json m = Json::object(); + m.set("type", "conversation.item.create"); + m.set("item", item); + send(m); +} + +void RealtimeSession::delete_item(const std::string& id) { + if (!llm::Service::valid_id(id)) bad("bad item id"); + Json m = Json::object(); + m.set("type", "conversation.item.delete"); + m.set("item_id", id); + send(m); +} + +void RealtimeSession::truncate_item(const std::string& id, int content_index, int audio_end_ms) { + if (!llm::Service::valid_id(id)) bad("bad item id"); + if (content_index < 0 || content_index > 64 || audio_end_ms < 0 || audio_end_ms > 3600000) + bad("content_index or audio_end_ms out of range"); + Json m = Json::object(); + m.set("type", "conversation.item.truncate"); + m.set("item_id", id); + m.set("content_index", Json(content_index)); + m.set("audio_end_ms", Json(audio_end_ms)); + send(m); +} + +void RealtimeSession::create_response(const std::string& instructions) { + Json m = Json::object(); + m.set("type", "response.create"); + if (!instructions.empty()) { + if (instructions.size() > PlatformCaps::kMaxInstructionChars) bad("instructions too long"); + Json r = Json::object(); + r.set("instructions", instructions); + m.set("response", r); + } + send(m); +} + +void RealtimeSession::cancel_response(const std::string& response_id) { + Json m = Json::object(); + m.set("type", "response.cancel"); + if (!response_id.empty()) { + if (!llm::Service::valid_id(response_id)) bad("bad response id"); + m.set("response_id", response_id); + } + send(m); +} + +RealtimeResponse RealtimeSession::run_response(int max_wait_ms, std::size_t max_events) { + RealtimeResponse out; + long deadline = now_ms() + max_wait_ms; + for (std::size_t n = 0; n < max_events; ++n) { + long left = deadline - now_ms(); + if (left <= 0) return out; + auto ev = next(static_cast(left)); + if (!ev) return out; + const std::string& t = ev->type; + auto str = [&](const char* k) { return llm::Service::string_at(ev->body, k); }; + if (t == "response.created") { + if (const Json* r = ev->body.find("response"); r && r->is_object()) out.response_id = llm::Service::string_at(*r, "id"); + } else if (t == "response.output_audio_transcript.delta") { + out.transcript += str("delta"); + } else if (t == "response.text.delta" || t == "response.output_text.delta") { + out.text += str("delta"); + } else if (!ev->audio.empty()) { + if (out.audio.size() + ev->audio.size() > PlatformCaps::kMaxStreamAudioBytes) out.truncated = true; + else out.audio += ev->audio; + } else if (t == "response.function_call_arguments.done") { + out.calls.push_back({str("call_id"), str("name"), str("arguments"), str("item_id")}); + } else if (t == "error") { + const Json* e = ev->body.find("error"); + std::string msg = e && e->is_object() + ? llm::Service::string_at(*e, "type") + ": " + llm::Service::string_at(*e, "message") + : "error"; + out.errors.push_back(msg); + } + bool done = t == "response.done"; + bool closed = t == "websocket.close"; + if (done) { + if (const Json* r = ev->body.find("response"); r && r->is_object()) { + out.status = llm::Service::string_at(*r, "status"); + if (const Json* u = r->find("usage")) out.usage = *u; + } + } + if (out.events.size() < PlatformCaps::kMaxEventsPerWait) out.events.push_back(std::move(*ev)); + else out.truncated = true; + if (done || closed) return out; + } + out.truncated = true; + return out; +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/realtime_session.h b/src/xai/platform/realtime_session.h new file mode 100644 index 0000000..58499ec --- /dev/null +++ b/src/xai/platform/realtime_session.h @@ -0,0 +1,103 @@ +#pragma once + +// Realtime voice agent session (wss://api.x.ai/v1/realtime): connect, wait +// for session.created, configure with SessionConfig, stream audio in, read +// events out, run tool calls. One thread reads (next / run_response); any +// thread may send. The credential is an xAI API key (server side) or an +// ephemeral client secret from RealtimeRest::client_secret. + +#include +#include +#include +#include + +#include "xai/platform/session_config.h" +#include "xai/platform/socket.h" + +namespace molo::xai::platform { + +struct RealtimeOptions { + std::string url; // "" = wss://api.x.ai/v1/realtime (tests point at loopback) + std::string model; // query: "" | grok-voice-latest | ... + std::string reasoning_effort; // query reasoning.effort: "" | high | none + std::string call_id; // SIP call (API key only; client secrets are refused) + std::string conversation_id; // session resumption (guide) + SocketAuth auth = SocketAuth::kBearer; + SocketOptions socket; + int setup_timeout_ms = PlatformCaps::kSetupTimeoutMs; +}; + +struct FunctionCall { + std::string call_id, name, arguments, item_id; +}; + +// What one assistant turn produced, folded from its events. +struct RealtimeResponse { + std::string response_id; + std::string status; // completed | cancelled | incomplete + std::string transcript; // response.output_audio_transcript.delta joined + std::string text; // response.(output_)text.delta joined + std::string audio; // decoded audio bytes (json or binary transport) + std::vector calls; // response.function_call_arguments.done + Json usage; // response.done.response.usage + std::vector events; // every event, in order (bounded) + bool truncated = false; // event or audio cap hit + std::vector errors; // error events (type: message) +}; + +class RealtimeSession { + public: + RealtimeSession(std::string token, RealtimeOptions options = {}); + + // "wss://api.x.ai/v1/realtime?model=..." as it will be opened (no credential). + std::string url() const; + // Opens the socket and waits for session.created (events before it are kept + // in setup_events). Throws llm::ApiError. + void connect(); + void close(); + bool is_open() const { return socket_.is_open(); } + const std::vector& setup_events() const { return setup_events_; } + // conversation.created.conversation.id, "" before it arrived. + const std::string& conversation_id() const { return conversation_id_; } + + // Client messages. + void update_session(const SessionConfig& config); + // PCM/codec bytes; sent as base64 JSON, or a binary frame when + // set_input_binary(true) (match audio.input.transport = "binary"). + void append_audio(const std::string& bytes); + void set_input_binary(bool on) { input_binary_ = on; } + void commit_audio(); // manual turns only (turn_detection null) + void clear_audio(); + void add_user_text(const std::string& text, const std::string& previous_item_id = ""); + void seed_assistant_text(const std::string& text); + void add_function_output(const std::string& call_id, const std::string& output); + void add_function_call_history(const std::string& name, const std::string& arguments, + const std::string& call_id); + // Hard coded TTS line without the model (SpaceXSI extension). + void force_message(const std::string& text, bool interruptible = true); + void delete_item(const std::string& item_id); + void truncate_item(const std::string& item_id, int content_index, int audio_end_ms); + void create_response(const std::string& instructions = ""); + void cancel_response(const std::string& response_id = ""); + + // Server events. + std::optional next(int wait_ms); + // Reads until response.done (or error / close / wait elapsed) and folds + // the events. max_events bounds the loop. + RealtimeResponse run_response(int max_wait_ms, + std::size_t max_events = PlatformCaps::kMaxEventsPerWait); + + const XaiSocket::Counters& counters() const { return socket_.counters(); } + + private: + void send(Json message); + std::string token_; + RealtimeOptions options_; + XaiSocket socket_; + std::vector setup_events_; + std::deque pending_; // read ahead while settling the two setup events + std::string conversation_id_; + bool input_binary_ = false; +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/session_config.cpp b/src/xai/platform/session_config.cpp new file mode 100644 index 0000000..d8024b4 --- /dev/null +++ b/src/xai/platform/session_config.cpp @@ -0,0 +1,261 @@ +#include "xai/platform/session_config.h" + +#include +#include + +#include "llm/api_client.h" +#include "llm/error.h" +#include "xai/platform/caps.h" +#include "xai/platform/ws_events.h" +#include "xai/platform/tts.h" +#include "xai/platform/voice_types.h" + +namespace molo::xai::platform { + +using E = VoiceEnums; + +namespace { + +[[noreturn]] void bad(const std::string& why) { throw llm::ApiError::invalid("xai", why); } + +Json strings(const std::vector& v, std::size_t max, const std::string& what, + std::size_t max_chars = 256) { + if (v.size() > max) bad(what + " has more than " + std::to_string(max) + " entries"); + Json a = Json::array(); + for (const std::string& s : v) { + if (s.empty() || s.size() > max_chars) bad(what + " has an empty or too long entry"); + a.push(s); + } + return a; +} + +bool iso_date(const std::string& s) { + if (s.size() != 10 || s[4] != '-' || s[7] != '-') return false; + for (std::size_t i = 0; i < s.size(); ++i) + if (i != 4 && i != 7 && (s[i] < '0' || s[i] > '9')) return false; + return true; +} + +Json format_json(const AudioFormat& f, const char* side) { + Json o = Json::object(); + Json fmt = Json::object(); + if (!f.type.empty()) { + if (!E::has(E::kSessionAudioTypes, f.type)) bad(std::string(side) + " audio type is not documented"); + fmt.set("type", f.type); + } + if (f.rate) { + if (f.type != "audio/pcm" && !f.type.empty()) bad("rate applies to audio/pcm only"); + if (!E::has_int(E::kSessionRates, f.rate)) bad(std::string(side) + " sample rate is not documented"); + fmt.set("rate", Json(f.rate)); + } + if (!fmt.as_object().empty()) o.set("format", fmt); + if (!f.transport.empty()) { + if (f.transport != "json" && f.transport != "binary") bad("transport must be json or binary"); + o.set("transport", f.transport); + } + return o; +} + +} // namespace + +Json SessionTool::function(const std::string& name, const std::string& description, + const Json& parameters) { + if (name.empty() || name.size() > 64) bad("function name must be 1..64 characters"); + for (unsigned char c : name) + if (!(std::isalnum(c) || c == '_' || c == '-')) bad("function name has invalid characters"); + if (description.size() > 1000) bad("function description is over 1000 characters"); + if (!parameters.is_object()) bad("function parameters must be a JSON schema object"); + if (parameters.dump().size() > 32 * 1024) bad("function parameters over 32 KB"); + Json t = Json::object(); + t.set("type", "function"); + t.set("name", name); + if (!description.empty()) t.set("description", description); + t.set("parameters", parameters); + return t; +} + +Json SessionTool::send_dtmf() { + Json t = Json::object(); + t.set("type", "function"); + t.set("name", "send_dtmf"); + return t; +} + +Json SessionTool::web_search(const std::vector& allow, + const std::vector& exclude, bool images, + const std::string& country, const std::string& city, + const std::string& region, const std::string& timezone) { + if (!allow.empty() && !exclude.empty()) bad("allowed_domains and excluded_domains are mutually exclusive"); + Json t = Json::object(); + t.set("type", "web_search"); + if (!allow.empty()) t.set("allowed_domains", strings(allow, PlatformCaps::kMaxDomainList, "allowed_domains")); + if (!exclude.empty()) t.set("excluded_domains", strings(exclude, PlatformCaps::kMaxDomainList, "excluded_domains")); + if (images) t.set("enable_image_understanding", Json(true)); + if (!country.empty() || !city.empty() || !region.empty() || !timezone.empty()) { + Json loc = Json::object(); + for (auto [k, v] : {std::pair{"country", &country}, + {"city", &city}, {"region", ®ion}, {"timezone", &timezone}}) + if (!v->empty()) { + if (v->size() > 128) bad("location field too long"); + loc.set(k, *v); + } + t.set("location", loc); + } + return t; +} + +Json SessionTool::x_search(const std::vector& allow, + const std::vector& exclude, const std::string& from, + const std::string& to, bool images, bool videos) { + if (!allow.empty() && !exclude.empty()) bad("allowed_x_handles and excluded_x_handles are mutually exclusive"); + Json t = Json::object(); + t.set("type", "x_search"); + if (!allow.empty()) t.set("allowed_x_handles", strings(allow, PlatformCaps::kMaxToolFieldList, "allowed_x_handles", 64)); + if (!exclude.empty()) t.set("excluded_x_handles", strings(exclude, PlatformCaps::kMaxToolFieldList, "excluded_x_handles", 64)); + if (!from.empty()) { + if (!iso_date(from)) bad("from_date must be YYYY-MM-DD"); + t.set("from_date", from); + } + if (!to.empty()) { + if (!iso_date(to)) bad("to_date must be YYYY-MM-DD"); + t.set("to_date", to); + } + if (!from.empty() && !to.empty() && from > to) bad("from_date is later than to_date"); + if (images) t.set("enable_image_understanding", Json(true)); + if (videos) t.set("enable_video_understanding", Json(true)); + return t; +} + +Json SessionTool::file_search(const std::vector& ids, int max_results) { + if (ids.empty()) bad("file_search needs at least one collection id"); + Json t = Json::object(); + t.set("type", "file_search"); + t.set("vector_store_ids", strings(ids, PlatformCaps::kMaxCollectionIds, "vector_store_ids")); + if (max_results) { + if (max_results < 1 || max_results > 100) bad("max_num_results must be 1..100"); + t.set("max_num_results", Json(max_results)); + } + return t; +} + +Json SessionTool::mcp(const std::string& url, const std::string& label, + const std::string& description, const std::vector& allowed, + const std::string& authorization, + const std::map& headers) { + if (url.rfind("https://", 0) != 0 && url.rfind("http://", 0) != 0) bad("server_url must be http(s)"); + if (url.size() > 2048) bad("server_url too long"); + if (label.empty() || label.size() > 64) bad("server_label must be 1..64 characters"); + Json t = Json::object(); + t.set("type", "mcp"); + t.set("server_url", url); + t.set("server_label", label); + if (!description.empty()) { + if (description.size() > 1000) bad("server_description too long"); + t.set("server_description", description); + } + if (!allowed.empty()) t.set("allowed_tools", strings(allowed, 128, "allowed_tools")); + if (!authorization.empty()) { + if (authorization.size() > 4096) bad("authorization too long"); + t.set("authorization", authorization); + } + if (!headers.empty()) { + if (headers.size() > 32) bad("too many headers"); + Json h = Json::object(); + for (const auto& [k, v] : headers) { + if (k.empty() || k.size() > 128 || v.size() > 4096 || + k.find_first_of("\r\n") != std::string::npos || v.find_first_of("\r\n") != std::string::npos) + bad("bad MCP header"); + h.set(k, v); + } + t.set("headers", h); + } + return t; +} + +Json SessionConfig::build() const { + Json s = Json::object(); + if (!model.empty()) { + if (!E::has(E::kRealtimeModels, model)) bad("model is not a documented realtime model"); + s.set("model", model); + } + if (!instructions.empty()) { + if (instructions.size() > PlatformCaps::kMaxInstructionChars) bad("instructions over 32000 characters"); + s.set("instructions", instructions); + } + if (!reasoning_effort.empty()) { + if (reasoning_effort != "high" && reasoning_effort != "none") bad("reasoning effort must be high or none"); + Json r = Json::object(); + r.set("effort", reasoning_effort); + s.set("reasoning", r); + } + if (!voice.empty()) { + if (!llm::Service::valid_id(voice)) bad("bad voice id"); + s.set("voice", voice); + } + if (turns != Turns::kUnset || idle_timeout_ms) { + Json td = Json::object(); + if (turns == Turns::kManual) { + if (idle_timeout_ms) bad("idle_timeout_ms needs server_vad"); + td.set("type", Json()); + } else { + td.set("type", "server_vad"); + } + if (idle_timeout_ms) { + if (idle_timeout_ms < 1 || idle_timeout_ms > 3600000) bad("idle_timeout_ms must be 1..3600000"); + td.set("idle_timeout_ms", Json(idle_timeout_ms)); + } + s.set("turn_detection", td); + } + if (resumption) { + Json r = Json::object(); + r.set("enabled", Json(*resumption)); + s.set("resumption", r); + } + Json audio = Json::object(); + Json in = format_json(input, "input"); + if (!language_hint.empty() || !keyterms.empty()) { + Json tr = Json::object(); + if (!language_hint.empty()) { + if (language_hint.size() > 16) bad("language_hint too long"); + if (language_hint == "es" || language_hint == "pt") bad("es and pt need a regional variant (es-MX, pt-BR, ...)"); + tr.set("language_hint", language_hint); + } + if (!keyterms.empty()) tr.set("keyterms", strings(keyterms, PlatformCaps::kMaxKeyterms, "keyterms", PlatformCaps::kMaxKeytermChars)); + in.set("transcription", tr); + } + if (!in.as_object().empty()) audio.set("input", in); + Json out = format_json(output, "output"); + if (output_speed != 0) { + if (output_speed < 0.7 || output_speed > 1.5) bad("output speed must be 0.7..1.5"); + out.set("speed", Json(output_speed)); + } + if (!out.as_object().empty()) audio.set("output", out); + if (!audio.as_object().empty()) s.set("audio", audio); + if (!tools.empty()) { + if (tools.size() > PlatformCaps::kMaxSessionTools) bad("too many tools"); + Json a = Json::array(); + for (const Json& t : tools) { + if (!t.is_object() || !t.find("type") || !t.find("type")->is_string() || + !WsVocabulary::has("realtime", "tool", t.find("type")->as_string())) + bad("tool needs a documented type"); + a.push(t); + } + s.set("tools", a); + } + if (clear_replace) { + if (!replace.empty()) bad("replace and clear_replace are exclusive"); + s.set("replace", Json()); + } else if (!replace.empty()) { + s.set("replace", replace_map_to_json(replace)); + } + return s; +} + +Json SessionConfig::update_message() const { + Json m = Json::object(); + m.set("type", "session.update"); + m.set("session", build()); + return m; +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/session_config.h b/src/xai/platform/session_config.h new file mode 100644 index 0000000..ea818c1 --- /dev/null +++ b/src/xai/platform/session_config.h @@ -0,0 +1,74 @@ +#pragma once + +// Typed builder for the realtime `session.update` message and its tools. +// Every field is validated against the caps and enums of docs.x.ai before +// any frame is sent; invalid input throws llm::ApiError::invalid. + +#include +#include +#include +#include + +#include "clients/body/json.h" + +namespace molo::xai::platform { + +using Json = clients::body::Json; + +struct AudioFormat { + std::string type; // "" | audio/pcm | audio/pcmu | audio/pcma | audio/opus + int rate = 0; // PCM only: 8000..48000 (documented set) + std::string transport; // "" | json | binary +}; + +// Tool factories. function tools use the flat shape of the guide examples. +class SessionTool { + public: + static Json function(const std::string& name, const std::string& description, + const Json& parameters_schema); + // Built-in DTMF sender for SIP sessions: the API supplies the schema. + static Json send_dtmf(); + static Json web_search(const std::vector& allowed_domains = {}, + const std::vector& excluded_domains = {}, + bool enable_image_understanding = false, + const std::string& country = "", const std::string& city = "", + const std::string& region = "", const std::string& timezone = ""); + static Json x_search(const std::vector& allowed_handles = {}, + const std::vector& excluded_handles = {}, + const std::string& from_date = "", const std::string& to_date = "", + bool enable_image_understanding = false, + bool enable_video_understanding = false); + // collections searched via the Collections API ids + static Json file_search(const std::vector& collection_ids, int max_num_results = 0); + static Json mcp(const std::string& server_url, const std::string& server_label, + const std::string& server_description = "", + const std::vector& allowed_tools = {}, + const std::string& authorization = "", + const std::map& headers = {}); +}; + +struct SessionConfig { + std::string model; // "" | grok-voice-latest | grok-voice-3.0 | grok-voice-2.0 + std::string instructions; + std::string reasoning_effort; // "" | high | none + std::string voice; // built-in id (eve) or custom voice id + // turn detection: unset keeps the server default. + enum class Turns { kUnset, kServerVad, kManual }; + Turns turns = Turns::kUnset; // kManual sends turn_detection.type = null + long idle_timeout_ms = 0; // 0 = unset; server_vad only + std::optional resumption; + AudioFormat input, output; + std::string language_hint; // BCP-47; es/pt need the regional variant + std::vector keyterms; // max 100, 50 chars + double output_speed = 0; // 0 = unset, else 0.7..1.5 + std::vector tools; // from SessionTool + std::map replace; // pronunciation substitutions + bool clear_replace = false; // sends "replace": null + + // The "session" object. Throws on invalid input. + Json build() const; + // {"type":"session.update","session":{...}} + Json update_message() const; +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/socket.cpp b/src/xai/platform/socket.cpp new file mode 100644 index 0000000..25ddb8c --- /dev/null +++ b/src/xai/platform/socket.cpp @@ -0,0 +1,175 @@ +#include "xai/platform/socket.h" + +#include + +#include "llm/error.h" +#include "security/crypto/Base64.h" + +namespace molo::xai::platform { + +namespace gl = google::live; +using clients::body::Json; + +namespace { + +long now_ms() { + return std::chrono::duration_cast( + std::chrono::steady_clock::now().time_since_epoch()) + .count(); +} + +llm::ApiError map_error(const gl::WsError& e) { + using K = gl::WsError::Kind; + int status = e.http_status(); + if (status == 401 || status == 403) + return llm::ApiError("xai", status, "authentication_error", e.what()); + if (e.kind() == K::Invalid) return llm::ApiError("xai", 400, "invalid_request_error", e.what()); + if (e.kind() == K::Timeout) return llm::ApiError("xai", 504, "timeout", e.what()); + return llm::ApiError("xai", status ? status : 502, "UNAVAILABLE", e.what()); +} + +bool is_audio_delta(const std::string& type) { + return type == "response.output_audio.delta" || type == "response.audio.delta" || + type == "audio.delta"; +} + +} // namespace + +XaiSocket::XaiSocket(std::string stream, std::string url, std::string token, SocketAuth auth, + SocketOptions options) + : stream_(std::move(stream)), + url_(std::move(url)), + token_(std::move(token)), + auth_(auth), + options_(std::move(options)) {} + +XaiSocket::~XaiSocket() { + try { + close(); + } catch (...) { + } +} + +std::string XaiSocket::with_query(const std::string& url, const std::string& query) { + if (query.empty()) return url; + return url + (url.find('?') == std::string::npos ? "?" : "&") + query; +} + +void XaiSocket::connect() { + if (open_) throw llm::ApiError::invalid("xai", "socket already open"); + if (token_.empty() || token_.find_first_of("\r\n") != std::string::npos) + throw llm::ApiError::invalid("xai", "missing or malformed credential"); + try { + gl::WsUrl url = gl::WsUrl::parse(url_); + ws_ = std::make_unique(gl::open_stream( + url, options_.connect_timeout_ms, PlatformCaps::kIoTimeoutMs, options_.tls)); + gl::WsHeaders headers; + if (auth_ == SocketAuth::kBearer) + headers.emplace_back("Authorization", "Bearer " + token_); + else + headers.emplace_back("Sec-WebSocket-Protocol", "xai-client-secret." + token_); + ws_->handshake(url, headers, options_.handshake_timeout_ms); + ws_->set_read_timeout_ms(PlatformCaps::kPollIntervalMs); + } catch (const gl::WsError& e) { + if (ws_) ws_->shutdown(); + ws_.reset(); + throw map_error(e); + } + open_ = true; + started_ms_ = now_ms(); +} + +void XaiSocket::send_json(const Json& message) { + if (!open_) throw llm::ApiError("xai", 409, "not_open", "socket is not open"); + const Json* type = message.is_object() ? message.find("type") : nullptr; + if (!type || !type->is_string() || !WsVocabulary::known_client(stream_, type->as_string())) + throw llm::ApiError::invalid("xai", "unknown client message type for " + stream_); + try { + ws_->send_text(message.dump()); + } catch (const gl::WsError& e) { + throw map_error(e); + } + ++counters_.sent; +} + +void XaiSocket::send_binary(const std::string& bytes) { + if (!open_) throw llm::ApiError("xai", 409, "not_open", "socket is not open"); + if (bytes.empty() || bytes.size() > PlatformCaps::kMaxAudioChunkBytes) + throw llm::ApiError::invalid("xai", "audio chunk must be 1..262144 bytes"); + try { + ws_->send_binary(bytes); + } catch (const gl::WsError& e) { + throw map_error(e); + } + ++counters_.sent; +} + +void XaiSocket::close() { + if (!ws_) return; + try { + if (open_) ws_->close(1000, ""); + } catch (...) { + } + ws_->shutdown(); + open_ = false; +} + +WsEvent XaiSocket::decode(const gl::WsMessage& m) { + WsEvent ev; + if (m.kind == gl::WsMessage::Kind::Close) { + ev.type = "websocket.close"; + Json b = Json::object(); + b.set("code", Json(static_cast(m.code))); + b.set("reason", m.data); + ev.body = b; + open_ = false; + return ev; + } + ++counters_.received; + if (m.kind == gl::WsMessage::Kind::Binary) { + ev.binary = true; + ev.type = "audio.binary"; + ev.audio = m.data; + ++counters_.binary_frames; + return ev; + } + try { + ev.body = Json::parse(m.data); + } catch (const std::exception&) { + ++counters_.decode_errors; + ev.known = false; + ev.type = ""; + return ev; + } + if (const Json* t = ev.body.is_object() ? ev.body.find("type") : nullptr; t && t->is_string()) + ev.type = t->as_string(); + ev.known = !ev.type.empty() && WsVocabulary::known_server(stream_, ev.type); + if (!ev.known) ++counters_.unknown_events; + if (is_audio_delta(ev.type)) { + const Json* d = ev.body.find("delta"); + if (d && d->is_string() && !security::crypto::Base64::decode(d->as_string(), ev.audio)) { + ++counters_.decode_errors; + throw llm::ApiError("xai", 502, "BAD_RESPONSE", "audio delta is not valid base64"); + } + } + return ev; +} + +std::optional XaiSocket::next(int wait_ms) { + if (!ws_) throw llm::ApiError("xai", 409, "not_open", "socket is not open"); + long deadline = now_ms() + wait_ms; + for (;;) { + if (now_ms() - started_ms_ > static_cast(options_.max_session_seconds) * 1000) + throw llm::ApiError("xai", 504, "max_duration", "session ran past the local time cap"); + try { + auto m = ws_->receive(); + if (m) return decode(*m); + } catch (const gl::WsError& e) { + open_ = false; + throw map_error(e); + } + if (now_ms() >= deadline) return std::nullopt; + } +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/socket.h b/src/xai/platform/socket.h new file mode 100644 index 0000000..2e49091 --- /dev/null +++ b/src/xai/platform/socket.h @@ -0,0 +1,74 @@ +#pragma once + +// One xAI voice WebSocket: connect (bearer header or the browser style +// Sec-WebSocket-Protocol), send JSON or binary frames, read decoded events +// with a deadline. Built on the RFC 6455 client in src/google/live. The +// credential only ever travels in a header, never in the URL, and never in an +// error message. + +#include +#include +#include + +#include "clients/body/json.h" +#include "google/live/ws_client.h" +#include "google/live/ws_stream.h" +#include "xai/platform/caps.h" +#include "xai/platform/ws_events.h" + +namespace molo::xai::platform { + +struct SocketOptions { + int connect_timeout_ms = PlatformCaps::kConnectTimeoutMs; + int handshake_timeout_ms = PlatformCaps::kHandshakeTimeoutMs; + int max_session_seconds = PlatformCaps::kMaxSessionSeconds; + google::live::TlsFactory tls; // null: default wolfSSL session +}; + +enum class SocketAuth { + kBearer, // Authorization: Bearer (API key or client secret) + kClientSecretProtocol, // Sec-WebSocket-Protocol: xai-client-secret. +}; + +class XaiSocket { + public: + // stream: "realtime" | "tts" | "stt" (picks the event vocabulary). + XaiSocket(std::string stream, std::string url, std::string token, SocketAuth auth, + SocketOptions options = {}); + ~XaiSocket(); + + // Throws llm::ApiError (401 on a refused upgrade with 401/403, else 502). + void connect(); + bool is_open() const { return open_; } + + void send_json(const clients::body::Json& message); + void send_binary(const std::string& bytes); + void close(); + + // Next decoded server message, or nullopt when `wait_ms` elapsed with no + // message. A close frame yields type "websocket.close" with body + // {code, reason}. Throws when the session ran past max_session_seconds. + std::optional next(int wait_ms); + + struct Counters { + std::size_t sent = 0, received = 0, unknown_events = 0, binary_frames = 0, decode_errors = 0; + }; + const Counters& counters() const { return counters_; } + + static std::string with_query(const std::string& url, const std::string& query); + + private: + WsEvent decode(const google::live::WsMessage& m); + + std::string stream_; + std::string url_; + std::string token_; + SocketAuth auth_; + SocketOptions options_; + std::unique_ptr ws_; + bool open_ = false; + long started_ms_ = 0; + Counters counters_; +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/stt.cpp b/src/xai/platform/stt.cpp new file mode 100644 index 0000000..9e54874 --- /dev/null +++ b/src/xai/platform/stt.cpp @@ -0,0 +1,68 @@ +#include "xai/platform/stt.h" + +#include "xai/platform/caps.h" +#include "xai/platform/voice_types.h" + +namespace molo::xai::platform { + +using E = VoiceEnums; + +clients::body::MultipartBody SpeechToText::build(const SttRequest& r) const { + bool has_file = !r.data.empty(); + if (has_file == !r.url.empty()) bad("give exactly one of data or url"); + if (has_file && r.data.size() > PlatformCaps::kMaxSttBytes) bad("audio is over 500 MB"); + if (!r.url.empty()) { + require_text("url", r.url, 2048); + if (r.url.rfind("https://", 0) != 0 && r.url.rfind("http://", 0) != 0) bad("url must be http or https"); + } + if (has_file) { + require_text("filename", r.filename, PlatformCaps::kMaxNameChars); + if (r.filename.find_first_of("\"\\/\r\n") != std::string::npos) bad("filename has path or quote characters"); + require_text("content_type", r.content_type, 128); + } + clients::body::MultipartBody form; + if (!r.model.empty()) { + require_text("model", r.model, 128); + form.add_text("model", r.model); + } + if (!r.audio_format.empty()) { + if (!E::has(E::kSttAudioFormats, r.audio_format)) bad("audio_format must be pcm, mulaw or alaw"); + form.add_text("audio_format", r.audio_format); + } + if (r.sample_rate) { + if (!E::has_int(E::kSampleRates, r.sample_rate)) bad("sample_rate is not a documented value"); + form.add_text("sample_rate", std::to_string(r.sample_rate)); + } + if (!r.audio_format.empty() && !r.sample_rate) bad("raw audio needs sample_rate"); + if (!r.language.empty()) { + require_text("language", r.language, 16); + form.add_text("language", r.language); + } + if (r.format && r.language.empty()) bad("format needs language"); + if (r.format) form.add_text("format", "true"); + if (r.multichannel) form.add_text("multichannel", "true"); + if (r.channels) { + require_range("channels", r.channels, 2, PlatformCaps::kMaxChannels); + form.add_text("channels", std::to_string(r.channels)); + } + if (r.diarize) form.add_text("diarize", "true"); + if (r.keyterms.size() > PlatformCaps::kMaxKeyterms) bad("at most 100 keyterms"); + for (const std::string& k : r.keyterms) { + require_text("keyterm", k, PlatformCaps::kMaxKeytermChars); + form.add_text("keyterm", k); + } + if (r.filler_words) form.add_text("filler_words", "true"); + if (r.vad_threshold >= 0) { + if (r.vad_threshold > 1.0) bad("vad_threshold must be 0..1"); + form.add_text("vad_threshold", std::to_string(r.vad_threshold)); + } + if (!r.url.empty()) form.add_text("url", r.url); + if (has_file) form.add_file("file", r.filename, r.content_type, r.data); + return form; +} + +Json SpeechToText::transcribe(const SttRequest& r) { + return invoke_multipart(Call::kStt, {}, build(r)); +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/stt.h b/src/xai/platform/stt.h new file mode 100644 index 0000000..873d4a0 --- /dev/null +++ b/src/xai/platform/stt.h @@ -0,0 +1,43 @@ +#pragma once + +// Speech to text over HTTP (POST /v1/stt, multipart; file up to 500 MB or a +// server-side url). The streaming WebSocket form is SttStream. + +#include +#include + +#include "xai/platform/platform_service.h" + +namespace molo::xai::platform { + +struct SttRequest { + // Exactly one of (data) or (url). + std::string filename = "audio"; + std::string content_type = "application/octet-stream"; + std::string data; + std::string url; + std::string model; // "" = server default (grok-voice-transcribe-2.0) + std::string audio_format; // raw audio only: pcm | mulaw | alaw + int sample_rate = 0; // raw audio only + std::string language; // "" = auto detect + bool format = false; // inverse text normalization, needs language + bool multichannel = false; + int channels = 0; // 2..8, raw multichannel only + bool diarize = false; + std::vector keyterms; // max 100, 50 chars each + bool filler_words = false; + double vad_threshold = -1; // <0 = unset, else 0..1 +}; + +class SpeechToText : public PlatformService { + public: + explicit SpeechToText(std::shared_ptr api) + : PlatformService(std::move(api), Host::kApi) {} + + // Validates and encodes; `file` is always the last part (spec requirement). + clients::body::MultipartBody build(const SttRequest& request) const; + // {text, language, duration, words[], channels[]?} + Json transcribe(const SttRequest& request); +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/stt_stream.cpp b/src/xai/platform/stt_stream.cpp new file mode 100644 index 0000000..3f293ea --- /dev/null +++ b/src/xai/platform/stt_stream.cpp @@ -0,0 +1,153 @@ +#include "xai/platform/stt_stream.h" + +#include + +#include "llm/api_client.h" +#include "xai/platform/clients.h" +#include "xai/platform/platform_service.h" +#include "xai/platform/voice_types.h" + +namespace molo::xai::platform { + +namespace { + +[[noreturn]] void bad(const std::string& why) { throw llm::ApiError::invalid("xai", why); } + +long now_ms() { + return std::chrono::duration_cast( + std::chrono::steady_clock::now().time_since_epoch()) + .count(); +} + +std::string build_url(const SttStreamOptions& o) { + Query q; + if (o.sample_rate) { + if (!VoiceEnums::has_int(VoiceEnums::kSampleRates, o.sample_rate)) bad("sample_rate is not a documented value"); + q.add_int("sample_rate", o.sample_rate); + } + if (!o.encoding.empty()) { + if (!VoiceEnums::has(VoiceEnums::kSttAudioFormats, o.encoding)) bad("encoding must be pcm, mulaw or alaw"); + q.add("encoding", o.encoding); + } + if (o.interim_results) q.add_bool("interim_results", true); + if (o.endpointing_ms >= 0) { + if (o.endpointing_ms > 60000) bad("endpointing must be 0..60000 ms"); + q.add_int("endpointing", o.endpointing_ms); + } + if (!o.language.empty()) { + if (o.language.size() > 16) bad("language too long"); + q.add("language", o.language); + } + if (o.format) { + if (o.language.empty()) bad("format needs language"); + q.add_bool("format", true); + } + if (!o.model.empty()) { + if (!llm::Service::valid_id(o.model)) bad("bad model"); + q.add("model", o.model); + } + if (o.multichannel) q.add_bool("multichannel", true); + if (o.channels) { + if (o.channels < 2 || o.channels > PlatformCaps::kMaxChannels) bad("channels must be 2..8"); + q.add_int("channels", o.channels); + } + if (o.diarize) q.add_bool("diarize", true); + if (o.keyterms.size() > PlatformCaps::kMaxKeyterms) bad("at most 100 keyterms"); + for (const std::string& k : o.keyterms) { + if (k.empty() || k.size() > PlatformCaps::kMaxKeytermChars) bad("keyterm must be 1..50 characters"); + q.add("keyterm", k); + } + if (o.filler_words) q.add_bool("filler_words", true); + if (o.smart_turn >= 0) { + if (o.smart_turn > 1) bad("smart_turn must be 0..1"); + q.add("smart_turn", std::to_string(o.smart_turn)); + } + if (o.smart_turn_timeout_ms >= 0) q.add_int("smart_turn_timeout", o.smart_turn_timeout_ms); + if (o.vad_threshold >= 0) { + if (o.vad_threshold > 1) bad("vad_threshold must be 0..1"); + q.add("vad_threshold", std::to_string(o.vad_threshold)); + } + std::string base = o.url.empty() ? PlatformEndpoints::kSttStreamUrl : o.url; + std::string s = q.str(); + return XaiSocket::with_query(base, s.empty() ? "" : s.substr(1)); +} + +} // namespace + +SttStream::SttStream(std::string api_key, SttStreamOptions options) + : options_(options), + socket_("stt", build_url(options), std::move(api_key), SocketAuth::kBearer, options.socket) {} + +std::string SttStream::url() const { return build_url(options_); } + +void SttStream::connect() { + socket_.connect(); + long deadline = now_ms() + options_.ready_timeout_ms; + for (;;) { + long left = deadline - now_ms(); + if (left <= 0) { + socket_.close(); + throw llm::ApiError("xai", 504, "timeout", "transcript.created not received in time"); + } + auto ev = socket_.next(static_cast(left)); + if (!ev) continue; + if (ev->type == "transcript.created") { + id_ = llm::Service::string_at(ev->body, "id"); + return; + } + if (ev->is_error() || ev->type == "websocket.close") { + socket_.close(); + throw llm::ApiError("xai", 502, "UNAVAILABLE", "stream failed before transcript.created: " + + llm::Service::string_at(ev->body, "message")); + } + } +} + +void SttStream::send_audio(const std::string& bytes) { socket_.send_binary(bytes); } + +void SttStream::finalize(int channel) { + Json m = Json::object(); + m.set("type", "finalize"); + if (channel >= 0) { + if (channel >= PlatformCaps::kMaxChannels) bad("channel out of range"); + m.set("channel", Json(channel)); + } + socket_.send_json(m); +} + +void SttStream::finish() { + Json m = Json::object(); + m.set("type", "audio.done"); + socket_.send_json(m); +} + +Transcript SttStream::collect(int max_wait_ms) { + Transcript out; + out.id = id_; + long deadline = now_ms() + max_wait_ms; + std::size_t want = options_.multichannel && options_.channels > 1 ? options_.channels : 1; + for (;;) { + long left = deadline - now_ms(); + if (left <= 0) return out; + auto ev = socket_.next(static_cast(left)); + if (!ev) return out; + if (ev->type == "transcript.partial") { + if (out.partials.size() < PlatformCaps::kMaxEventsPerWait) out.partials.push_back(ev->body); + } else if (ev->type == "transcript.done") { + out.done.push_back(ev->body); + if (out.text.empty()) out.text = llm::Service::string_at(ev->body, "text"); + if (const Json* d = ev->body.find("duration"); d && d->is_number()) out.duration = d->as_number(); + if (out.done.size() >= want) { + out.complete = true; + return out; + } + } else if (ev->type == "error") { + out.error = llm::Service::string_at(ev->body, "message", "error"); + return out; + } else if (ev->type == "websocket.close") { + return out; + } + } +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/stt_stream.h b/src/xai/platform/stt_stream.h new file mode 100644 index 0000000..69a35ff --- /dev/null +++ b/src/xai/platform/stt_stream.h @@ -0,0 +1,69 @@ +#pragma once + +// Streaming speech to text (wss://api.x.ai/v1/stt): wait for +// transcript.created, send binary audio frames paced by the caller, read +// transcript.partial events, end with audio.done and read transcript.done. + +#include +#include + +#include "xai/platform/socket.h" + +namespace molo::xai::platform { + +struct SttStreamOptions { + std::string url; // "" = wss://api.x.ai/v1/stt + int sample_rate = 0; // 0 = server default 16000 + std::string encoding; // "" | pcm | mulaw | alaw (raw audio) + bool interim_results = false; + int endpointing_ms = -1; // <0 unset (server default 400) + std::string language; + bool format = false; + std::string model; + bool multichannel = false; + int channels = 0; + bool diarize = false; + std::vector keyterms; + bool filler_words = false; + double smart_turn = -1; // <0 unset + int smart_turn_timeout_ms = -1; + double vad_threshold = -1; // <0 unset, else 0..1 + int ready_timeout_ms = PlatformCaps::kSetupTimeoutMs; + SocketOptions socket; +}; + +struct Transcript { + std::string text; // transcript.done text (final) + double duration = 0; + std::vector partials; // transcript.partial bodies, in order + std::vector done; // transcript.done bodies (one per channel when multichannel) + std::string id; // transcript.created id + bool complete = false; + std::string error; +}; + +class SttStream { + public: + SttStream(std::string api_key, SttStreamOptions options); + + std::string url() const; + // Opens the socket and waits for transcript.created. + void connect(); + void close() { socket_.close(); } + bool is_open() const { return socket_.is_open(); } + const std::string& transcript_id() const { return id_; } + + void send_audio(const std::string& bytes); // binary frame, 1..262144 bytes + void finalize(int channel = -1); // force speech_final + void finish(); // audio.done + std::optional next(int wait_ms) { return socket_.next(wait_ms); } + // Reads until transcript.done (all channels) / error / close / wait elapsed. + Transcript collect(int max_wait_ms); + + private: + SttStreamOptions options_; + XaiSocket socket_; + std::string id_; +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/tools/check_spec.py b/src/xai/platform/tools/check_spec.py new file mode 100644 index 0000000..a8dfdc8 --- /dev/null +++ b/src/xai/platform/tools/check_spec.py @@ -0,0 +1,275 @@ +#!/usr/bin/env python3 +"""Check the xAI platform call tables against xAI's published specs. + +Fails (exit 1) when a declared call is absent from its source, a request +field or query parameter we use is not in the spec, a WebSocket message, +query parameter or session field in ws_events.cpp differs from the three +docs.x.ai .ws.json documents, or a spec operation in our areas is neither in +the table nor in an explicit exclusion list. Python 3 stdlib only, no +credentials. + + python3 -I src/xai/platform/tools/check_spec.py + +Sources (all public, read at run time): + openapi https://api.x.ai/api-docs/openapi.json (also docs.x.ai/openapi.json) + docs https://docs.x.ai/developers/rest-api-reference/.md + guide https://docs.x.ai/developers/.md (prose, cross-checks) + ws https://docs.x.ai/{voice-realtime,tts-streaming,stt-streaming}.ws.json + proto xai-org/xai-proto billing.proto and auth.proto (second source for billing) +""" +import json +import os +import re +import sys +import urllib.request + +HERE = os.path.dirname(os.path.abspath(__file__)) +CALLS = os.path.join(HERE, "..", "calls.cpp") +WSCPP = os.path.join(HERE, "..", "ws_events.cpp") +DOCS = "https://docs.x.ai/developers/" +OPENAPI = "https://api.x.ai/api-docs/openapi.json" +PROTO = "https://raw.githubusercontent.com/xai-org/xai-proto/main/proto/xai/" + +# Operations that belong to other packages or are deliberately not wrapped. +EXCLUDED_OPENAPI_PREFIXES = ( + "/v1/chat/", "/v1/complete", "/v1/completions","/v1/embedding", "/v1/image", "/v1/language-models", + "/v1/messages", "/v1/models", "/v1/responses", "/v1/tokenize-text", + "/v1/video", "/v1/skills", +) +EXCLUDED_DOCS = { + # Documented without a request or response shape: nothing to verify against. + ("POST", "/v1/files:initialize"), + ("POST", "/v1/files:uploadChunks"), + ("PUT", "/v1/files/{file_id}"), + # Core package (src/xai/core). + ("POST", "/v1/tokenize-text"), +} +DOC_PAGES = ( + "inference/voice", "collections/collection", "collections/search", + "management/auth", "management/billing", "management/audit", + "files/upload", "files/manage", "files/download", "inference/other", +) +GUIDES = ( + "model-capabilities/audio/text-to-speech", "model-capabilities/audio/speech-to-text", + "model-capabilities/audio/custom-voices", "model-capabilities/audio/speech-to-speech", + "files/collections/api", +) +VOICE_GUIDES = GUIDES[:3] + +ROW = re.compile( + r'^\s*\{Call::(\w+), "([A-Z]+)", "(\w+)", "([^"]*)", "([^"]*)", "([^"]*)", "([^"]*)", "([^"]*)"\},?\s*$') +WSROW = re.compile(r'^\s*\{"(\w+)", "(\w+)", "([^"]*)"\},?\s*$') + +_cache = {} + + +def fetch(url): + if url not in _cache: + last = None + for _ in range(3): + try: + with urllib.request.urlopen(url, timeout=60) as r: + _cache[url] = r.read().decode("utf-8") + break + except Exception as e: # noqa: BLE001 + last = e + else: + raise SystemExit("cannot fetch %s: %s" % (url, last)) + return _cache[url] + + +def block(text, begin, end): + a = text.index(begin) + b = text.index(end) + return text[a:b].splitlines()[1:] + + +def parse_doc_page(slug): + """-> {(METHOD, path): {'body': set, 'query': set}} from a reference .md page.""" + md = fetch(DOCS + "rest-api-reference/" + slug + ".md").replace("\\", "") + out = {} + for sec in re.split(r"(?m)^## ", md)[1:]: + head, _, rest = sec.partition("\n") + m = re.match(r"(GET|POST|PUT|PATCH|DELETE) (\S+)$", head.strip()) + if not m: + continue + info = {"body": set(), "query": set()} + sub = None + for line in rest.split("\n"): + h = re.match(r"### (.*)", line) + if h: + sub = h.group(1).strip() + continue + b = re.match(r"\* `([^`]+)` \(", line) + if b and sub == "Request Body": + info["body"].add(b.group(1)) + elif b and sub == "Query Parameters": + info["query"].add(b.group(1)) + out[(m.group(1), m.group(2))] = info + return out + + +def ws_expected(doc): + """Rebuild the (kind, name) set the way the table is generated.""" + out = set() + for q in doc["queryParameters"]: + out.add(("query", q["name"])) + for m in doc["clientMessages"]: + out.add(("client", m["type"])) + for m in doc["serverMessages"]: + out.add(("server", m["type"])) + return out + + +def session_paths(schema, prefix, out): + for k, v in (schema.get("properties") or {}).items(): + if k == "tools": + continue + out.add(("session", prefix + k)) + if v.get("type") == "object": + session_paths(v, prefix + k + ".", out) + + +def main(): + text = open(CALLS).read() + rows = [] + for line in block(text, "// CALLS-BEGIN", "// CALLS-END"): + m = ROW.match(line) + if m: + rows.append(m.groups()) + bad = [] + if not rows: + bad.append("no rows parsed from calls.cpp") + + openapi = json.loads(fetch(OPENAPI)) + docs = {slug: parse_doc_page(slug) for slug in DOC_PAGES} + guides = {g: fetch(DOCS + g + ".md").replace("\\", "") for g in GUIDES} + + n_openapi = n_docs = n_guide = 0 + table_keys = set() + for name, http, host, path, source, body, query, guide in rows: + table_keys.add((http, path)) + kind, _, ref = source.partition(":") + fields = [f for f in body.split(",") if f] + qparams = [q for q in query.split(",") if q] + if kind == "openapi": + n_openapi += 1 + op = (openapi["paths"].get(path) or {}).get(http.lower()) + if not op: + bad.append("%s: %s %s absent from openapi" % (name, http, path)) + continue + if op.get("operationId") != ref: + bad.append("%s: operationId %s != %s" % (name, ref, op.get("operationId"))) + params = {p["name"] for p in op.get("parameters", []) if p.get("in") == "query"} + for q in qparams: + if q not in params: + bad.append("%s: query param %s absent" % (name, q)) + if fields: + content = op.get("requestBody", {}).get("content", {}) + schema = next(iter(content.values()), {}).get("schema", {}) + if "$ref" in schema: + schema = openapi["components"]["schemas"][schema["$ref"].split("/")[-1]] + props = set((schema.get("properties") or {}).keys()) + for f in fields: + if f not in props: + bad.append("%s: body field %s absent" % (name, f)) + elif kind == "docs": + n_docs += 1 + ent = docs.get(ref, {}).get((http, path)) + if ent is None: + bad.append("%s: %s %s absent from docs page %s" % (name, http, path, ref)) + continue + for f in fields: + if f not in ent["body"]: + bad.append("%s: body field %s absent from docs" % (name, f)) + for q in qparams: + if q not in ent["query"]: + bad.append("%s: query param %s absent from docs" % (name, q)) + if ref == "inference/voice" and not path.startswith("/v2/") and "realtime" not in path: + blob = "\n".join(guides[g] for g in VOICE_GUIDES) + for f in fields + [x for x in guide.split(",") if x]: + if "`%s`" % f not in blob: + bad.append("%s: field %s not in the voice guides" % (name, f)) + elif kind == "guide": + n_guide += 1 + g = guides.get(ref, "") + for f in [x for x in guide.split(",") if x]: + if '"%s=' % f not in g and "%s=" % f not in g: + bad.append("%s: guide field %s not in %s" % (name, f, ref)) + if "/documents " not in g: + bad.append("%s: documents upload example absent from guide" % name) + else: + bad.append("%s: unknown source %s" % (name, source)) + + # Hosts: collection and management paths live on the management host. + for name, http, host, path, source, *_ in rows: + if host not in ("api", "management"): + bad.append("%s: bad host %s" % (name, host)) + + # Coverage: every openapi operation is a row or an exclusion. + for path, item in openapi["paths"].items(): + for method in item: + if method not in ("get", "post", "put", "patch", "delete"): + continue + if (method.upper(), path) in table_keys: + continue + if path.startswith(EXCLUDED_OPENAPI_PREFIXES): + continue + bad.append("openapi %s %s is neither a row nor excluded" % (method.upper(), path)) + # Coverage: every docs reference operation is a row or an exclusion. + for slug, ops in docs.items(): + for key in ops: + if key in table_keys or key in EXCLUDED_DOCS: + continue + bad.append("docs %s %s %s is neither a row nor excluded" % (slug, key[0], key[1])) + + # Second source for billing and key info: xai-proto. + billing = fetch(PROTO + "management_api/v1/billing.proto") + rpcs = re.findall(r"(?m)^\s*rpc (\w+)\(", billing) + billing_rows = [r for r in rows if r[3].startswith("/v1/billing/")] + if len(rpcs) != len(billing_rows): + bad.append("billing.proto has %d rpcs, table has %d billing rows" % (len(rpcs), len(billing_rows))) + if "rpc get_api_key_info" not in fetch(PROTO + "api/v1/auth.proto"): + bad.append("auth.proto has no get_api_key_info") + + # WebSocket vocabulary. + wsrows = set() + for line in block(open(WSCPP).read(), "// WS-BEGIN", "// WS-END"): + m = WSROW.match(line) + if m: + wsrows.add(m.groups()) + n_ws = len(wsrows) + files = (("realtime", "voice-realtime"), ("tts", "tts-streaming"), ("stt", "stt-streaming")) + for stream, fname in files: + doc = json.loads(fetch("https://docs.x.ai/%s.ws.json" % fname)) + want = ws_expected(doc) + if stream == "realtime": + su = [m for m in doc["clientMessages"] if m["type"] == "session.update"][0] + sess = su["schema"]["properties"]["session"] + session_paths(sess, "", want) + for t in sess["properties"]["tools"]["items"]["properties"]["type"]["enum"]: + want.add(("tool", t)) + have = {(k, n) for s, k, n in wsrows if s == stream and not k.startswith("guide_")} + for k, n in sorted(want - have): + bad.append("ws %s: %s %s in spec but not in table" % (stream, k, n)) + for k, n in sorted(have - want): + bad.append("ws %s: %s %s in table but not in spec" % (stream, k, n)) + sts = guides["model-capabilities/audio/speech-to-speech"] + for s, k, n in wsrows: + if k.startswith("guide_") and n not in sts and n.replace("_", "\\_") not in sts: + bad.append("ws guide row %s %s %s not in the speech-to-speech guide" % (s, k, n)) + + if bad: + print("FAIL: %d problems" % len(bad)) + for b in bad: + print(" " + b) + return 1 + print("OK: %d call rows (%d openapi, %d docs, %d guide), %d ws rows, " + "%d billing rpcs cross-checked, openapi %d paths, docs %d pages" + % (len(rows), n_openapi, n_docs, n_guide, n_ws, len(rpcs), len(openapi["paths"]), + len(DOC_PAGES))) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/src/xai/platform/tts.cpp b/src/xai/platform/tts.cpp new file mode 100644 index 0000000..296fff6 --- /dev/null +++ b/src/xai/platform/tts.cpp @@ -0,0 +1,87 @@ +#include "xai/platform/tts.h" + +#include "security/crypto/Base64.h" +#include "xai/platform/caps.h" +#include "xai/platform/voice_types.h" + +namespace molo::xai::platform { + +using E = VoiceEnums; + +Json replace_map_to_json(const std::map& m) { + if (m.size() > PlatformCaps::kMaxReplaceEntries) + throw llm::ApiError::invalid("xai", "too many replace entries"); + Json o = Json::object(); + for (const auto& [k, v] : m) { + if (k.empty() || k.size() > PlatformCaps::kMaxReplaceChars || + v.size() > PlatformCaps::kMaxReplaceChars) + throw llm::ApiError::invalid("xai", "replace entry is empty or too long"); + o.set(k, v); + } + return o; +} + +Json TextToSpeech::build(const TtsRequest& r) const { + require_text("text", r.text, PlatformCaps::kMaxTtsChars); + if (!E::language_ok(r.language)) bad("language is not a documented code"); + Json b = Json::object(); + b.set("text", r.text); + b.set("language", r.language); + if (!r.voice_id.empty()) { + if (!valid_id(r.voice_id)) bad("bad voice_id"); + b.set("voice_id", r.voice_id); + } + if (!r.codec.empty() || r.sample_rate || r.bit_rate) { + std::string codec = r.codec.empty() ? "mp3" : r.codec; + if (!E::has(E::kTtsCodecs, codec)) bad("codec is not a documented value"); + Json f = Json::object(); + f.set("codec", codec); + if (r.sample_rate) { + if (!E::has_int(E::kSampleRates, r.sample_rate)) bad("sample_rate is not a documented value"); + f.set("sample_rate", Json(r.sample_rate)); + } + if (r.bit_rate) { + if (codec != "mp3") bad("bit_rate applies to mp3 only"); + if (!E::has_int(E::kBitRates, r.bit_rate)) bad("bit_rate is not a documented value"); + f.set("bit_rate", Json(r.bit_rate)); + } + b.set("output_format", f); + } + require_range("optimize_streaming_latency", r.optimize_streaming_latency, 0, 2); + if (r.optimize_streaming_latency) + b.set("optimize_streaming_latency", Json(std::to_string(r.optimize_streaming_latency))); + if (r.speed != 0) { + if (r.speed < 0.7 || r.speed > 1.5) bad("speed must be 0.7..1.5"); + b.set("speed", Json(r.speed)); + } + if (r.text_normalization) b.set("text_normalization", Json(true)); + if (r.with_timestamps) b.set("with_timestamps", Json(true)); + if (!r.replace.empty()) b.set("replace", replace_map_to_json(r.replace)); + return b; +} + +TtsResult TextToSpeech::synthesize(const TtsRequest& r) { + std::string body = build(r).dump(); + llm::RawResponse raw = invoke_raw(Call::kTts, {}, &body, "application/json"); + TtsResult out; + out.content_type = raw.content_type; + if (!r.with_timestamps) { + out.audio = std::move(raw.body); + return out; + } + Json env; + try { + env = Json::parse(raw.body); + } catch (const std::exception& e) { + throw llm::ApiError("xai", 502, "BAD_RESPONSE", e.what()); + } + std::string b64 = string_at(env, "audio"); + if (!security::crypto::Base64::decode(b64, out.audio)) + throw llm::ApiError("xai", 502, "BAD_RESPONSE", "audio is not valid base64"); + out.content_type = string_at(env, "content_type", out.content_type); + if (const Json* d = env.find("duration"); d && d->is_number()) out.duration = d->as_number(); + if (const Json* t = env.find("audio_timestamps")) out.timestamps = *t; + return out; +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/tts.h b/src/xai/platform/tts.h new file mode 100644 index 0000000..2aa8edc --- /dev/null +++ b/src/xai/platform/tts.h @@ -0,0 +1,48 @@ +#pragma once + +// Text to speech over HTTP (POST /v1/tts). Returns raw audio bytes, or with +// with_timestamps a JSON envelope (base64 audio plus per-character times). +// The streaming WebSocket form is TtsStream. + +#include +#include + +#include "xai/platform/platform_service.h" + +namespace molo::xai::platform { + +struct TtsRequest { + std::string text; // 1..60000 chars, speech tags allowed + std::string language = "en"; // BCP-47 or "auto" (required by the API) + std::string voice_id; // "" = server default (eve) + std::string codec; // "" = mp3 | wav | pcm | mulaw | alaw + int sample_rate = 0; // 0 = default 24000 + int bit_rate = 0; // mp3 only + int optimize_streaming_latency = 0; // 0..2 (reference lists 0,1; guide 0..2) + double speed = 0; // 0 = default; 0.7..1.5 + bool text_normalization = false; + bool with_timestamps = false; + std::map replace; // pronunciation substitutions +}; + +struct TtsResult { + std::string audio; // decoded bytes + std::string content_type; + double duration = 0; // only with timestamps + Json timestamps; // audio_timestamps, only with timestamps +}; + +class TextToSpeech : public PlatformService { + public: + explicit TextToSpeech(std::shared_ptr api) + : PlatformService(std::move(api), Host::kApi) {} + + Json build(const TtsRequest& request) const; + TtsResult synthesize(const TtsRequest& request); +}; + +// Shared with the realtime session: validates a pronunciation map. +// Throws llm::ApiError::invalid over the entry and length caps. +Json replace_map_to_json(const std::map& m); + +} // namespace molo::xai::platform diff --git a/src/xai/platform/tts_stream.cpp b/src/xai/platform/tts_stream.cpp new file mode 100644 index 0000000..b75dc27 --- /dev/null +++ b/src/xai/platform/tts_stream.cpp @@ -0,0 +1,116 @@ +#include "xai/platform/tts_stream.h" + +#include + +#include "llm/api_client.h" +#include "xai/platform/clients.h" +#include "xai/platform/platform_service.h" +#include "xai/platform/voice_types.h" + +namespace molo::xai::platform { + +namespace { + +using E = VoiceEnums; + +[[noreturn]] void bad(const std::string& why) { throw llm::ApiError::invalid("xai", why); } + +long now_ms() { + return std::chrono::duration_cast( + std::chrono::steady_clock::now().time_since_epoch()) + .count(); +} + +std::string build_url(const TtsStreamOptions& o) { + if (!E::language_ok(o.language)) bad("language is not a documented code"); + Query q; + q.add("language", o.language); + if (!o.voice.empty()) { + if (!llm::Service::valid_id(o.voice)) bad("bad voice"); + q.add("voice", o.voice); + } + std::string codec = o.codec; + if (!codec.empty()) { + if (!E::has(E::kTtsCodecs, codec)) bad("codec is not a documented value"); + q.add("codec", codec); + } + if (o.sample_rate) { + if (!E::has_int(E::kSampleRates, o.sample_rate)) bad("sample_rate is not a documented value"); + q.add_int("sample_rate", o.sample_rate); + } + if (o.bit_rate) { + if (!codec.empty() && codec != "mp3") bad("bit_rate applies to mp3 only"); + if (!E::has_int(E::kBitRates, o.bit_rate)) bad("bit_rate is not a documented value"); + q.add_int("bit_rate", o.bit_rate); + } + if (o.optimize_streaming_latency < 0 || o.optimize_streaming_latency > 1) + bad("optimize_streaming_latency must be 0 or 1 on the socket"); + if (o.optimize_streaming_latency) q.add_int("optimize_streaming_latency", 1); + if (o.speed != 0) { + if (o.speed < 0.7 || o.speed > 1.5) bad("speed must be 0.7..1.5"); + q.add("speed", std::to_string(o.speed)); + } + if (o.text_normalization) q.add_bool("text_normalization", true); + if (o.with_timestamps) q.add_bool("with_timestamps", true); + std::string base = o.url.empty() ? PlatformEndpoints::kTtsStreamUrl : o.url; + return XaiSocket::with_query(base, q.str().substr(1)); +} + +} // namespace + +TtsStream::TtsStream(std::string api_key, TtsStreamOptions options) + : options_(options), + socket_("tts", build_url(options), std::move(api_key), SocketAuth::kBearer, options.socket) {} + +std::string TtsStream::url() const { return build_url(options_); } + +void TtsStream::connect() { socket_.connect(); } + +void TtsStream::send_text(const std::string& delta) { + if (delta.empty() || delta.size() > PlatformCaps::kMaxTextDeltaChars) bad("delta must be 1..60000 characters"); + Json m = Json::object(); + m.set("type", "text.delta"); + m.set("delta", delta); + socket_.send_json(m); +} + +void TtsStream::finish_utterance() { + Json m = Json::object(); + m.set("type", "text.done"); + socket_.send_json(m); +} + +TtsUtterance TtsStream::collect(int max_wait_ms) { + TtsUtterance out; + long deadline = now_ms() + max_wait_ms; + for (;;) { + long left = deadline - now_ms(); + if (left <= 0) return out; + auto ev = socket_.next(static_cast(left)); + if (!ev) return out; + if (ev->type == "audio.delta") { + ++out.chunks; + if (out.audio.size() + ev->audio.size() > PlatformCaps::kMaxStreamAudioBytes) out.truncated = true; + else out.audio += ev->audio; + if (const Json* t = ev->body.find("audio_timestamps")) out.chunk_timestamps.push_back(*t); + } else if (ev->type == "audio.done") { + out.trace_id = llm::Service::string_at(ev->body, "trace_id"); + out.complete = true; + return out; + } else if (ev->type == "error") { + out.error = llm::Service::string_at(ev->body, "message", "error"); + return out; + } else if (ev->type == "websocket.close") { + return out; + } + } +} + +TtsUtterance TtsStream::speak(const std::string& text, int max_wait_ms) { + for (std::size_t i = 0; i < text.size(); i += PlatformCaps::kMaxTextDeltaChars) + send_text(text.substr(i, PlatformCaps::kMaxTextDeltaChars)); + finish_utterance(); + return collect(max_wait_ms); +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/tts_stream.h b/src/xai/platform/tts_stream.h new file mode 100644 index 0000000..3cffa18 --- /dev/null +++ b/src/xai/platform/tts_stream.h @@ -0,0 +1,60 @@ +#pragma once + +// Streaming text to speech (wss://api.x.ai/v1/tts): send text deltas, receive +// base64 audio chunks; multiple utterances per connection. + +#include +#include + +#include "xai/platform/socket.h" + +namespace molo::xai::platform { + +struct TtsStreamOptions { + std::string url; // "" = wss://api.x.ai/v1/tts + std::string language = "en"; // required + std::string voice; // "" = eve + std::string codec; // "" | mp3 | wav | pcm | mulaw | alaw + int sample_rate = 0; + int bit_rate = 0; // mp3 only + int optimize_streaming_latency = 0; // 0 or 1 on the socket + double speed = 0; // 0.7..1.5 + bool text_normalization = false; + bool with_timestamps = false; + SocketOptions socket; +}; + +struct TtsUtterance { + std::string audio; // concatenated decoded chunks + std::string trace_id; // audio.done.trace_id + std::vector chunk_timestamps; // audio_timestamps per chunk (with_timestamps) + std::size_t chunks = 0; + bool complete = false; // audio.done seen + bool truncated = false; // audio cap hit + std::string error; // error event message +}; + +class TtsStream { + public: + TtsStream(std::string api_key, TtsStreamOptions options); + + std::string url() const; // as opened, no credential + void connect(); + void close() { socket_.close(); } + bool is_open() const { return socket_.is_open(); } + + // text.delta, at most 60000 characters per delta. + void send_text(const std::string& delta); + void finish_utterance(); // text.done + std::optional next(int wait_ms) { return socket_.next(wait_ms); } + // Reads until audio.done / error / close / wait elapsed. + TtsUtterance collect(int max_wait_ms); + // send_text + finish_utterance + collect. + TtsUtterance speak(const std::string& text, int max_wait_ms); + + private: + TtsStreamOptions options_; + XaiSocket socket_; +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/voice_types.h b/src/xai/platform/voice_types.h new file mode 100644 index 0000000..975149a --- /dev/null +++ b/src/xai/platform/voice_types.h @@ -0,0 +1,53 @@ +#pragma once + +// Enumerations shared by the voice REST, streaming and realtime classes. +// Values are checked against docs.x.ai (reference + .ws.json) by +// tools/check_spec.py. + +#include +#include +#include + +namespace molo::xai::platform { + +struct VoiceEnums { + static constexpr const char* kLanguages[] = { + "auto", "en", "ar-EG", "ar-SA", "ar-AE", "bn", "zh", "fr", "de", "hi", "id", + "it", "ja", "ko", "pt-BR", "pt-PT", "ru", "es-MX", "es-ES", "tr", "vi"}; + static constexpr const char* kTtsCodecs[] = {"mp3", "wav", "pcm", "mulaw", "alaw"}; + static constexpr int kSampleRates[] = {8000, 16000, 22050, 24000, 44100, 48000}; + static constexpr int kBitRates[] = {32000, 64000, 96000, 128000, 192000}; + static constexpr const char* kRealtimeModels[] = {"grok-voice-latest", "grok-voice-3.0", + "grok-voice-2.0"}; + static constexpr const char* kSessionAudioTypes[] = {"audio/pcm", "audio/pcmu", "audio/pcma", + "audio/opus"}; + static constexpr int kSessionRates[] = {8000, 11025, 16000, 22050, 24000, 32000, 44100, 48000}; + static constexpr const char* kSttAudioFormats[] = {"pcm", "mulaw", "alaw"}; + static constexpr const char* kGenders[] = {"male", "female", "neutral"}; + static constexpr const char* kAges[] = {"young", "middle-aged", "old"}; + static constexpr const char* kUseCases[] = {"conversational", "narration", "characters", + "educational", "advertisement", "social_media", + "entertainment"}; + static constexpr const char* kTones[] = {"warm", "casual", "professional", "friendly", + "authoritative", "expressive", "calm"}; + + template + static bool has(const Arr& arr, const std::string& v) { + return std::any_of(std::begin(arr), std::end(arr), [&](const char* s) { return v == s; }); + } + template + static bool has_int(const Arr& arr, int v) { + return std::any_of(std::begin(arr), std::end(arr), [&](int s) { return v == s; }); + } + static bool language_ok(const std::string& v) { + std::string lower; + for (char c : v) lower.push_back(static_cast(std::tolower(static_cast(c)))); + return std::any_of(std::begin(kLanguages), std::end(kLanguages), [&](const char* s) { + std::string t; + for (const char* p = s; *p; ++p) t.push_back(static_cast(std::tolower(static_cast(*p)))); + return t == lower; + }); + } +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/voices.cpp b/src/xai/platform/voices.cpp new file mode 100644 index 0000000..0490db7 --- /dev/null +++ b/src/xai/platform/voices.cpp @@ -0,0 +1,87 @@ +#include "xai/platform/voices.h" + +#include "xai/platform/caps.h" +#include "xai/platform/voice_types.h" + +namespace molo::xai::platform { + +namespace { +using E = VoiceEnums; +} + +Json VoicesService::tts_voices() { return invoke(Call::kTtsVoices, {}); } + +Json VoicesService::tts_voice(const std::string& id) { + check_id("voice", id); + return invoke(Call::kTtsVoiceGet, {id}); +} + +Json VoicesService::create_custom(const CustomVoiceUpload& u) { + require_text("filename", u.filename, PlatformCaps::kMaxNameChars); + if (u.filename.find_first_of("\"\\/\r\n") != std::string::npos) bad("filename has path or quote characters"); + require_text("content_type", u.content_type, 128); + if (u.data.empty()) bad("reference audio is empty"); + if (u.data.size() > PlatformCaps::kMaxCustomVoiceBytes) bad("reference audio is over 50 MB"); + if (!u.gender.empty() && !E::has(E::kGenders, u.gender)) bad("gender is not a documented value"); + if (!u.age.empty() && !E::has(E::kAges, u.age)) bad("age is not a documented value"); + if (!u.use_case.empty() && !E::has(E::kUseCases, u.use_case)) bad("use_case is not a documented value"); + if (!u.tone.empty() && !E::has(E::kTones, u.tone)) bad("tone is not a documented value"); + clients::body::MultipartBody form; + for (auto [k, v] : {std::pair{"name", &u.name}, + {"description", &u.description}, {"gender", &u.gender}, + {"accent", &u.accent}, {"age", &u.age}, {"language", &u.language}, + {"use_case", &u.use_case}, {"tone", &u.tone}}) { + require_text(k, *v, 1000, false); + if (!v->empty()) form.add_text(k, *v); + } + form.add_file("file", u.filename, u.content_type, u.data); + return invoke_multipart(Call::kCustomVoiceCreate, {}, form); +} + +Json VoicesService::list_custom(int limit, const std::string& token) { + Query q; + if (limit != 0) { + require_range("limit", limit, 1, PlatformCaps::kMaxLimit); + q.add_int("limit", limit); + } + require_text("pagination_token", token, 512, false); + q.add_if("pagination_token", token); + return invoke(Call::kCustomVoiceList, {}, nullptr, q); +} + +Json VoicesService::get_custom(const std::string& id) { + check_id("voice", id); + return invoke(Call::kCustomVoiceGet, {id}); +} + +Json VoicesService::patch_custom(const std::string& id, const Json& changes) { + check_id("voice", id); + if (!changes.is_object() || changes.as_object().empty()) bad("changes must be a non-empty object"); + for (const auto& [k, v] : changes.as_object()) { + bool known = k == "name" || k == "description" || k == "gender" || k == "accent" || + k == "age" || k == "language" || k == "use_case" || k == "tone"; + if (!known) bad("field not patchable: " + k); + if (v.is_null()) continue; + if (!v.is_string() || v.as_string().empty()) bad(k + " must be a non-empty string or null"); + const std::string& s = v.as_string(); + if (s.size() > 1000) bad(k + " is too long"); + if (k == "gender" && !E::has(E::kGenders, s)) bad("gender is not a documented value"); + if (k == "age" && !E::has(E::kAges, s)) bad("age is not a documented value"); + if (k == "use_case" && !E::has(E::kUseCases, s)) bad("use_case is not a documented value"); + if (k == "tone" && !E::has(E::kTones, s)) bad("tone is not a documented value"); + } + return invoke(Call::kCustomVoicePatch, {id}, &changes); +} + +Json VoicesService::remove_custom(const std::string& id, bool confirm) { + check_id("voice", id); + require_confirm("deleting a custom voice", confirm); + return invoke(Call::kCustomVoiceDelete, {id}); +} + +llm::RawResponse VoicesService::custom_audio(const std::string& id) { + check_id("voice", id); + return invoke_raw(Call::kCustomVoiceAudio, {id}); +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/voices.h b/src/xai/platform/voices.h new file mode 100644 index 0000000..1d00baf --- /dev/null +++ b/src/xai/platform/voices.h @@ -0,0 +1,38 @@ +#pragma once + +// Built-in TTS voices (GET /v1/tts/voices) and custom voices +// (/v1/custom-voices, Enterprise plan for create). api.x.ai, XAI_API_KEY. + +#include + +#include "xai/platform/platform_service.h" + +namespace molo::xai::platform { + +struct CustomVoiceUpload { + std::string filename; // reference clip, max 120 s + std::string content_type; // audio/wav recommended + std::string data; + std::string name, description, accent, language; + std::string gender, age, use_case, tone; // "" = unset; enums per docs +}; + +class VoicesService : public PlatformService { + public: + explicit VoicesService(std::shared_ptr api) + : PlatformService(std::move(api), Host::kApi) {} + + Json tts_voices(); + Json tts_voice(const std::string& voice_id); + + Json create_custom(const CustomVoiceUpload& upload); + // limit 0 = server default (100), else 1..1000. + Json list_custom(int limit = 0, const std::string& pagination_token = ""); + Json get_custom(const std::string& voice_id); + // Fields omitted stay; a JSON null clears; "" is rejected (spec). + Json patch_custom(const std::string& voice_id, const Json& changes); + Json remove_custom(const std::string& voice_id, bool confirm); + llm::RawResponse custom_audio(const std::string& voice_id); +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/webhook.cpp b/src/xai/platform/webhook.cpp new file mode 100644 index 0000000..f257a40 --- /dev/null +++ b/src/xai/platform/webhook.cpp @@ -0,0 +1,181 @@ +#include "xai/platform/webhook.h" + +#include +#include +#include + +#include "security/crypto/Base64.h" +#include "xai/platform/caps.h" + +namespace molo::xai::platform { + +namespace { + +// Self-contained SHA-256 (FIPS 180-4): the ai library does not link the +// security Hmac object, and a webhook check must not need a second library. +class Sha256 { + public: + Sha256() { reset(); } + void update(const std::uint8_t* d, std::size_t n) { + total_ += n; + while (n) { + std::size_t take = std::min(64 - used_, n); + std::memcpy(buf_ + used_, d, take); + used_ += take; d += take; n -= take; + if (used_ == 64) { block(buf_); used_ = 0; } + } + } + std::array finish() { + std::uint64_t bits = total_ * 8; + std::uint8_t pad = 0x80; + update(&pad, 1); + std::uint8_t zero = 0; + while (used_ != 56) update(&zero, 1); + std::uint8_t len[8]; + for (int i = 0; i < 8; ++i) len[i] = static_cast(bits >> (56 - 8 * i)); + update(len, 8); + std::array out{}; + for (int i = 0; i < 8; ++i) + for (int j = 0; j < 4; ++j) out[i * 4 + j] = static_cast(h_[i] >> (24 - 8 * j)); + return out; + } + + private: + void reset() { + static const std::uint32_t iv[8] = {0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, + 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19}; + std::memcpy(h_, iv, sizeof h_); + used_ = 0; + total_ = 0; + } + static std::uint32_t rotr(std::uint32_t x, int n) { return (x >> n) | (x << (32 - n)); } + void block(const std::uint8_t* p) { + static const std::uint32_t k[64] = { + 0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, + 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, + 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, + 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, + 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, + 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, + 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, + 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3, + 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, + 0xc67178f2}; + std::uint32_t w[64]; + for (int i = 0; i < 16; ++i) + w[i] = (std::uint32_t(p[i * 4]) << 24) | (std::uint32_t(p[i * 4 + 1]) << 16) | + (std::uint32_t(p[i * 4 + 2]) << 8) | std::uint32_t(p[i * 4 + 3]); + for (int i = 16; i < 64; ++i) { + std::uint32_t s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >> 3); + std::uint32_t s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >> 10); + w[i] = w[i - 16] + s0 + w[i - 7] + s1; + } + std::uint32_t a = h_[0], b = h_[1], c = h_[2], d = h_[3], e = h_[4], f = h_[5], g = h_[6], h = h_[7]; + for (int i = 0; i < 64; ++i) { + std::uint32_t t1 = h + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + k[i] + w[i]; + std::uint32_t t2 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c)); + h = g; g = f; f = e; e = d + t1; d = c; c = b; b = a; a = t1 + t2; + } + h_[0] += a; h_[1] += b; h_[2] += c; h_[3] += d; h_[4] += e; h_[5] += f; h_[6] += g; h_[7] += h; + } + std::uint32_t h_[8]; + std::uint8_t buf_[64]; + std::size_t used_ = 0; + std::uint64_t total_ = 0; +}; + +std::string sha256(const std::string& s) { + Sha256 h; + h.update(reinterpret_cast(s.data()), s.size()); + auto d = h.finish(); + return std::string(reinterpret_cast(d.data()), d.size()); +} + +bool constant_time_equal(const std::string& a, const std::string& b) { + if (a.size() != b.size()) return false; + unsigned char diff = 0; + for (std::size_t i = 0; i < a.size(); ++i) diff |= static_cast(a[i] ^ b[i]); + return diff == 0; +} + +[[noreturn]] void reject(const std::string& why) { + throw llm::ApiError("xai", 401, "webhook_invalid", why); +} + +bool all_digits(const std::string& s) { + if (s.empty() || s.size() > 12) return false; + for (char c : s) if (c < '0' || c > '9') return false; + return true; +} + +} // namespace + +std::string WebhookVerifier::hmac_sha256(const std::string& key, const std::string& message) { + std::string k = key.size() > 64 ? sha256(key) : key; + k.resize(64, '\0'); + std::string ipad(64, '\0'), opad(64, '\0'); + for (int i = 0; i < 64; ++i) { + ipad[i] = static_cast(k[i] ^ 0x36); + opad[i] = static_cast(k[i] ^ 0x5c); + } + return sha256(opad + sha256(ipad + message)); +} + +WebhookVerifier::WebhookVerifier(std::string secret) { + const std::string prefix = "whsec_"; + if (secret.rfind(prefix, 0) == 0) secret.erase(0, prefix.size()); + if (secret.empty() || secret.size() > 512 || + !security::crypto::Base64::decode(secret, key_) || key_.empty()) + throw llm::ApiError::invalid("xai", "webhook secret is not whsec_"); +} + +std::string WebhookVerifier::sign(const WebhookHeaders& h, const std::string& body) const { + return "v1," + security::crypto::Base64::encode( + hmac_sha256(key_, h.id + "." + h.timestamp + "." + body)); +} + +void WebhookVerifier::verify(const WebhookHeaders& h, const std::string& body, + long now_seconds) const { + if (h.id.empty() || h.id.size() > 256 || h.signature.empty() || h.signature.size() > 4096) + reject("missing webhook-id or webhook-signature"); + if (!all_digits(h.timestamp)) reject("bad webhook-timestamp"); + if (body.size() > PlatformCaps::kMaxWebhookBodyBytes) reject("webhook body too large"); + long ts = std::stol(h.timestamp); + long skew = now_seconds > ts ? now_seconds - ts : ts - now_seconds; + if (skew > PlatformCaps::kWebhookToleranceSeconds) reject("timestamp outside the tolerance"); + std::string expected = sign(h, body); + // The header holds space separated "v1," entries (key rotation). + std::size_t pos = 0; + while (pos < h.signature.size()) { + std::size_t end = h.signature.find(' ', pos); + if (end == std::string::npos) end = h.signature.size(); + std::string entry = h.signature.substr(pos, end - pos); + if (!entry.empty() && constant_time_equal(entry, expected)) return; + pos = end + 1; + } + reject("no matching signature"); +} + +IncomingCall WebhookVerifier::parse_incoming(const WebhookHeaders& h, const std::string& body, + long now_seconds) const { + verify(h, body, now_seconds); + Json doc; + try { + doc = Json::parse(body); + } catch (const std::exception&) { + throw llm::ApiError("xai", 400, "webhook_invalid", "body is not JSON"); + } + IncomingCall out; + out.type = llm::Service::string_at(doc, "type"); + if (out.type != "realtime.call.incoming") + throw llm::ApiError("xai", 400, "webhook_invalid", "not a realtime.call.incoming event"); + const Json* data = doc.find("data"); + if (!data || !data->is_object()) throw llm::ApiError("xai", 400, "webhook_invalid", "no data object"); + out.data = *data; + out.call_id = llm::Service::string_at(*data, "call_id"); + if (!llm::Service::valid_id(out.call_id)) + throw llm::ApiError("xai", 400, "webhook_invalid", "data.call_id missing or malformed"); + return out; +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/webhook.h b/src/xai/platform/webhook.h new file mode 100644 index 0000000..20b8c6f --- /dev/null +++ b/src/xai/platform/webhook.h @@ -0,0 +1,46 @@ +#pragma once + +// Verification of the signed `realtime.call.incoming` webhook xAI posts for a +// SIP phone number (Standard Webhooks v1: HMAC-SHA256 over +// "{webhook-id}.{webhook-timestamp}.{body}", secret "whsec_"). +// Pure local logic, no network. + +#include + +#include "xai/platform/platform_service.h" + +namespace molo::xai::platform { + +struct WebhookHeaders { + std::string id; // webhook-id + std::string timestamp; // webhook-timestamp (unix seconds) + std::string signature; // webhook-signature: "v1, v1," +}; + +struct IncomingCall { + std::string call_id; // data.call_id + std::string type; // realtime.call.incoming + Json data; +}; + +class WebhookVerifier { + public: + // secret is the "whsec_..." value returned once by phone number creation. + explicit WebhookVerifier(std::string secret); + + static std::string hmac_sha256(const std::string& key, const std::string& message); // raw 32 bytes + + // Throws llm::ApiError (401 type "webhook_invalid") on any failure: bad + // headers, timestamp outside the tolerance, no matching v1 signature. + void verify(const WebhookHeaders& headers, const std::string& body, long now_seconds) const; + // verify() then parse; throws when the event is not realtime.call.incoming. + IncomingCall parse_incoming(const WebhookHeaders& headers, const std::string& body, + long now_seconds) const; + // The signature a sender would produce (tests, local simulators). + std::string sign(const WebhookHeaders& headers, const std::string& body) const; + + private: + std::string key_; // decoded secret bytes +}; + +} // namespace molo::xai::platform diff --git a/src/xai/platform/ws_events.cpp b/src/xai/platform/ws_events.cpp new file mode 100644 index 0000000..ec4dce1 --- /dev/null +++ b/src/xai/platform/ws_events.cpp @@ -0,0 +1,149 @@ +#include "xai/platform/ws_events.h" + +namespace molo::xai::platform { + +// WS-BEGIN (generated from the docs.x.ai .ws.json files, parsed by tools/check_spec.py) +// {stream, kind, name} +static const WsRow kRows[] = { + {"realtime", "query", "call_id"}, + {"realtime", "query", "model"}, + {"realtime", "query", "reasoning.effort"}, + {"realtime", "client", "session.update"}, + {"realtime", "client", "input_audio_buffer.append"}, + {"realtime", "client", "input_audio_buffer.commit"}, + {"realtime", "client", "conversation.item.create"}, + {"realtime", "client", "input_audio_buffer.clear"}, + {"realtime", "client", "conversation.item.delete"}, + {"realtime", "client", "conversation.item.truncate"}, + {"realtime", "client", "response.create"}, + {"realtime", "client", "response.cancel"}, + {"realtime", "server", "session.created"}, + {"realtime", "server", "conversation.created"}, + {"realtime", "server", "session.updated"}, + {"realtime", "server", "input_audio_buffer.speech_started"}, + {"realtime", "server", "input_audio_buffer.speech_stopped"}, + {"realtime", "server", "input_audio_buffer.committed"}, + {"realtime", "server", "input_audio_buffer.timeout_triggered"}, + {"realtime", "server", "input_audio_buffer.cleared"}, + {"realtime", "server", "conversation.item.deleted"}, + {"realtime", "server", "conversation.item.added"}, + {"realtime", "server", "conversation.item.truncated"}, + {"realtime", "server", "conversation.item.input_audio_transcription.completed"}, + {"realtime", "server", "conversation.item.input_audio_transcription.updated"}, + {"realtime", "server", "input_audio_buffer.dtmf_event_received"}, + {"realtime", "server", "response.created"}, + {"realtime", "server", "response.output_item.added"}, + {"realtime", "server", "response.output_item.done"}, + {"realtime", "server", "response.content_part.added"}, + {"realtime", "server", "response.content_part.done"}, + {"realtime", "server", "response.output_audio_transcript.delta"}, + {"realtime", "server", "response.output_audio_transcript.done"}, + {"realtime", "server", "response.output_audio.delta"}, + {"realtime", "server", "response.output_audio.done"}, + {"realtime", "server", "response.text.delta"}, + {"realtime", "server", "response.output_text.delta"}, + {"realtime", "server", "response.function_call_arguments.delta"}, + {"realtime", "server", "response.function_call_arguments.done"}, + {"realtime", "server", "mcp_list_tools.in_progress"}, + {"realtime", "server", "mcp_list_tools.completed"}, + {"realtime", "server", "mcp_list_tools.failed"}, + {"realtime", "server", "response.mcp_call_arguments.delta"}, + {"realtime", "server", "response.mcp_call_arguments.done"}, + {"realtime", "server", "response.mcp_call.in_progress"}, + {"realtime", "server", "response.mcp_call.completed"}, + {"realtime", "server", "response.mcp_call.failed"}, + {"realtime", "server", "response.done"}, + {"realtime", "server", "error"}, + {"realtime", "session", "model"}, + {"realtime", "session", "instructions"}, + {"realtime", "session", "reasoning"}, + {"realtime", "session", "reasoning.effort"}, + {"realtime", "session", "voice"}, + {"realtime", "session", "turn_detection"}, + {"realtime", "session", "turn_detection.type"}, + {"realtime", "session", "turn_detection.idle_timeout_ms"}, + {"realtime", "session", "resumption"}, + {"realtime", "session", "resumption.enabled"}, + {"realtime", "session", "audio"}, + {"realtime", "session", "audio.input"}, + {"realtime", "session", "audio.input.format"}, + {"realtime", "session", "audio.input.format.type"}, + {"realtime", "session", "audio.input.format.rate"}, + {"realtime", "session", "audio.input.transport"}, + {"realtime", "session", "audio.input.transcription"}, + {"realtime", "session", "audio.input.transcription.language_hint"}, + {"realtime", "session", "audio.input.transcription.keyterms"}, + {"realtime", "session", "audio.output"}, + {"realtime", "session", "audio.output.format"}, + {"realtime", "session", "audio.output.format.type"}, + {"realtime", "session", "audio.output.format.rate"}, + {"realtime", "session", "audio.output.transport"}, + {"realtime", "session", "audio.output.speed"}, + {"realtime", "session", "replace"}, + {"realtime", "tool", "function"}, + {"realtime", "tool", "web_search"}, + {"realtime", "tool", "x_search"}, + {"realtime", "tool", "file_search"}, + {"realtime", "tool", "mcp"}, + {"tts", "query", "voice"}, + {"tts", "query", "language"}, + {"tts", "query", "codec"}, + {"tts", "query", "sample_rate"}, + {"tts", "query", "bit_rate"}, + {"tts", "query", "optimize_streaming_latency"}, + {"tts", "query", "speed"}, + {"tts", "query", "text_normalization"}, + {"tts", "query", "with_timestamps"}, + {"tts", "client", "text.delta"}, + {"tts", "client", "text.done"}, + {"tts", "server", "audio.delta"}, + {"tts", "server", "audio.done"}, + {"tts", "server", "error"}, + {"stt", "query", "sample_rate"}, + {"stt", "query", "encoding"}, + {"stt", "query", "interim_results"}, + {"stt", "query", "endpointing"}, + {"stt", "query", "language"}, + {"stt", "query", "format"}, + {"stt", "query", "model"}, + {"stt", "query", "multichannel"}, + {"stt", "query", "channels"}, + {"stt", "query", "diarize"}, + {"stt", "query", "keyterm"}, + {"stt", "query", "filler_words"}, + {"stt", "query", "smart_turn"}, + {"stt", "query", "smart_turn_timeout"}, + {"stt", "query", "vad_threshold"}, + {"stt", "client", "Binary frame (audio)"}, + {"stt", "client", "finalize"}, + {"stt", "client", "audio.done"}, + {"stt", "server", "transcript.created"}, + {"stt", "server", "transcript.partial"}, + {"stt", "server", "transcript.done"}, + {"stt", "server", "error"}, + {"realtime", "guide_query", "conversation_id"}, + {"realtime", "guide_server", "conversation.item.created"}, + {"realtime", "guide_server", "response.audio.delta"}, + {"realtime", "guide_client", "conversation.item.create"}, +}; +// WS-END + +std::size_t WsVocabulary::count() { return sizeof(kRows) / sizeof(kRows[0]); } +const WsRow& WsVocabulary::at(std::size_t i) { return kRows[i]; } + +bool WsVocabulary::has(const std::string& stream, const std::string& kind, + const std::string& name) { + for (const WsRow& r : kRows) + if (stream == r.stream && kind == r.kind && name == r.name) return true; + return false; +} + +bool WsVocabulary::known_server(const std::string& stream, const std::string& type) { + return has(stream, "server", type) || has(stream, "guide_server", type); +} + +bool WsVocabulary::known_client(const std::string& stream, const std::string& type) { + return has(stream, "client", type) || has(stream, "guide_client", type); +} + +} // namespace molo::xai::platform diff --git a/src/xai/platform/ws_events.h b/src/xai/platform/ws_events.h new file mode 100644 index 0000000..1ff0d41 --- /dev/null +++ b/src/xai/platform/ws_events.h @@ -0,0 +1,44 @@ +#pragma once + +// The WebSocket vocabulary of the three xAI voice sockets (realtime, TTS +// stream, STT stream): one table of every client message, server message, +// query parameter and session field. tools/check_spec.py compares the table +// with docs.x.ai/{voice-realtime,tts-streaming,stt-streaming}.ws.json. + +#include +#include + +#include "clients/body/json.h" + +namespace molo::xai::platform { + +using Json = clients::body::Json; + +struct WsRow { + const char* stream; // "realtime" | "tts" | "stt" + const char* kind; // client | server | query | session | tool | guide_client | guide_server | guide_query + const char* name; +}; + +class WsVocabulary { + public: + static std::size_t count(); + static const WsRow& at(std::size_t i); + static bool has(const std::string& stream, const std::string& kind, const std::string& name); + // Convenience: is `type` a documented server message of `stream` + // (spec table or guide-only extras)? + static bool known_server(const std::string& stream, const std::string& type); + static bool known_client(const std::string& stream, const std::string& type); +}; + +// One decoded server message. +struct WsEvent { + std::string type; // "" when the frame had no type + clients::body::Json body; // the full JSON object (null for binary audio) + std::string audio; // decoded bytes for audio deltas / binary frames + bool binary = false; // raw binary frame (audio transport "binary") + bool known = true; // type is in the vocabulary + bool is_error() const { return type == "error"; } +}; + +} // namespace molo::xai::platform diff --git a/tests/example/ai/xai/platform/confirm_test.cpp b/tests/example/ai/xai/platform/confirm_test.cpp new file mode 100644 index 0000000..ca72a48 --- /dev/null +++ b/tests/example/ai/xai/platform/confirm_test.cpp @@ -0,0 +1,59 @@ +// Destructive and paid routes are dry runs unless the body says "confirm":true. +// A dry run needs no key and sends nothing; confirm without a key is 503; a +// non-boolean confirm is 422. +#include + +#include "support/Assert.hpp" + +using namespace molo::example::test; + +int main() { + unsetenv("XAI_API_KEY"); + unsetenv("XAI_MANAGEMENT_KEY"); + Fixture f; + const std::string team = "5ea6f6bd-7815-4b8a-9135-28b2d7ba6722"; + const struct { + const char* path; + std::string body; // without the closing brace; confirm is appended + std::string expect_path; + } cases[] = { + {"/ai/xai/platform/files", "{\"action\":\"delete\",\"id\":\"file_abc\"", "/v1/files/file_abc"}, + {"/ai/xai/platform/files", "{\"action\":\"revoke_url\",\"id\":\"file_abc\"", "/v1/files/file_abc/public-url/revoke"}, + {"/ai/xai/platform/collections", "{\"action\":\"delete\",\"collection_id\":\"collection_x\"", "/v1/collections/collection_x"}, + {"/ai/xai/platform/collections", "{\"action\":\"remove_document\",\"collection_id\":\"collection_x\",\"file_id\":\"file_y\"", + "/v1/collections/collection_x/documents/file_y"}, + {"/ai/xai/platform/voices", "{\"action\":\"custom_delete\",\"voice_id\":\"abcd1234\"", "/v1/custom-voices/abcd1234"}, + {"/ai/xai/platform/keys", "{\"action\":\"delete\",\"api_key_id\":\"" + team + "\"", "/auth/api-keys/" + team}, + {"/ai/xai/platform/keys", "{\"action\":\"rotate\",\"api_key_id\":\"" + team + "\"", "/auth/api-keys/" + team + "/rotate"}, + {"/ai/xai/platform/billing", "{\"action\":\"top_up\",\"team_id\":\"" + team + "\",\"amount\":\"10\"", + "/v1/billing/teams/" + team + "/prepaid/top-up"}, + {"/ai/xai/platform/billing", "{\"action\":\"set_spending_limit\",\"team_id\":\"" + team + "\",\"amount\":\"100\"", + "/v1/billing/teams/" + team + "/postpaid/spending-limits"}, + {"/ai/xai/platform/realtime/phone-numbers", "{\"action\":\"delete\",\"phone_number_id\":\"phone_1\"", "/v2/phone-numbers/phone_1"}, + {"/ai/xai/platform/realtime/calls", "{\"action\":\"refer\",\"call_id\":\"c1\",\"target_uri\":\"tel:+15551234567\"", "/v1/realtime/calls/c1/refer"}, + {"/ai/xai/platform/tts", "{\"text\":\"hi\"", "/v1/tts"}, + {"/ai/xai/platform/stt", "{\"url\":\"https://example.com/a.mp3\"", "/v1/stt"}, + {"/ai/xai/platform/realtime/secret", "{\"expires_seconds\":60", "/v1/realtime/client_secrets"}, + {"/ai/xai/platform/realtime/session", "{\"text\":\"hi\"", "wss://api.x.ai/v1/realtime"}, + }; + for (const auto& c : cases) { + std::string p = c.path; + auto dry = f.client->post(p, c.body + "}", "application/json"); + check(dry.status == 200 && contains(dry.body, "\"dry_run\":true") && contains(dry.body, c.expect_path), + p + " " + c.expect_path + ": default is a dry run"); + auto off = f.client->post(p, c.body + ",\"confirm\":false}", "application/json"); + check(off.status == 200 && contains(off.body, "\"dry_run\":true"), p + ": confirm false is a dry run"); + auto real = f.client->post(p, c.body + ",\"confirm\":true}", "application/json"); + check(real.status == 503 && contains(real.body, "not_configured"), p + ": confirmed without a key is 503"); + check(f.client->post(p, c.body + ",\"confirm\":\"yes\"}", "application/json").status == 422, + p + ": non-bool confirm is 422"); + } + // Dry runs still validate their input. + check(f.client->post("/ai/xai/platform/files", "{\"action\":\"delete\",\"id\":\"../x\"}", "application/json").status == 422, + "bad id is 422 even on a dry run"); + check(f.client->post("/ai/xai/platform/billing", "{\"action\":\"top_up\",\"team_id\":\"" + team + "\",\"amount\":\"-5\",\"confirm\":true}", "application/json").status == 422, + "a bad amount is 422 before the key is needed"); + check(f.client->post("/ai/xai/platform/tts", "{\"text\":\"hi\",\"speed\":9}", "application/json").status == 422, + "tts speed out of range is 422 on a dry run"); + return finish("ai/xai/platform/confirm"); +} diff --git a/tests/example/ai/xai/platform/local_test.cpp b/tests/example/ai/xai/platform/local_test.cpp new file mode 100644 index 0000000..cb78ea5 --- /dev/null +++ b/tests/example/ai/xai/platform/local_test.cpp @@ -0,0 +1,81 @@ +// Local routes (no key, no network): POST /ai/xai/platform/realtime/session/preview +// and /ai/xai/platform/webhook/verify, plus body and limit cases. +#include + +#include "support/Assert.hpp" +#include "xai/platform/webhook.h" + +using namespace molo::example::test; + +int main() { + unsetenv("XAI_API_KEY"); + unsetenv("XAI_MANAGEMENT_KEY"); + Fixture f; + auto pre = f.client->post("/ai/xai/platform/realtime/session/preview", + "{\"voice\":\"eve\",\"turn_detection\":\"server_vad\",\"instructions\":\"Be brief.\"," + "\"input_type\":\"audio/pcm\",\"input_rate\":16000," + "\"tools\":[{\"type\":\"web_search\"}]}", + "application/json"); + check(pre.status == 200 && contains(pre.body, "\"type\":\"session.update\""), "preview builds session.update"); + check(contains(pre.body, "\"rate\":16000") && contains(pre.body, "\"type\":\"server_vad\""), "preview carries audio and turns"); + auto manual = f.client->post("/ai/xai/platform/realtime/session/preview", "{\"turn_detection\":\"manual\"}", "application/json"); + check(manual.status == 200 && contains(manual.body, "\"type\":null"), "manual turns send a null type"); + for (const char* bad : {"{\"model\":\"gpt-realtime\"}", "{\"input_type\":\"audio/mp3\"}", "{\"output_speed\":3}", + "{\"turn_detection\":\"loud\"}", "{\"language_hint\":\"es\"}", "{\"tools\":[{\"type\":\"nope\"}]}", + "{\"keyterms\":[1]}", "{\"idle_timeout_ms\":\"soon\"}"}) + check(f.client->post("/ai/xai/platform/realtime/session/preview", bad, "application/json").status == 422, + std::string("preview refuses ") + bad); + + // Webhook verification with a locally signed SIP event (shape from the docs). + const std::string secret = "whsec_MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY="; + const std::string event = + "{\"object\":\"event\",\"id\":\"evt_123\",\"type\":\"realtime.call.incoming\",\"created_at\":1750000000," + "\"data\":{\"call_id\":\"00000000-0000-0000-0000-000000000000\",\"metadata\":{}}}"; + molo::xai::platform::WebhookVerifier v(secret); + molo::xai::platform::WebhookHeaders h{"msg_1", "1750000000", ""}; + h.signature = v.sign(h, event); + auto esc = [](const std::string& s) { + std::string o; + for (char c : s) { + if (c == '"' || c == '\\') o.push_back('\\'); + o.push_back(c); + } + return o; + }; + auto req = [&](const std::string& sig, const std::string& body, long now) { + return "{\"secret\":\"" + secret + "\",\"webhook_id\":\"msg_1\",\"webhook_timestamp\":\"1750000000\"," + "\"webhook_signature\":\"" + sig + "\",\"body\":\"" + esc(body) + "\",\"now\":" + std::to_string(now) + "}"; + }; + auto ok = f.client->post("/ai/xai/platform/webhook/verify", req(h.signature, event, 1750000010), "application/json"); + check(ok.status == 200 && contains(ok.body, "\"valid\":true") && + contains(ok.body, "call_id=00000000-0000-0000-0000-000000000000"), + "valid signature opens the call"); + auto tamper = f.client->post("/ai/xai/platform/webhook/verify", req(h.signature, event + " ", 1750000010), "application/json"); + check(tamper.status == 502 || tamper.status == 422, "tampered body is refused (loud)"); + auto old = f.client->post("/ai/xai/platform/webhook/verify", req(h.signature, event, 1750001000), "application/json"); + check(old.status != 200, "stale timestamp is refused"); + check(f.client->post("/ai/xai/platform/webhook/verify", "{}", "application/json").status == 422, "missing fields is 422"); + + // Limits and bodies. + std::string big(5 * 1024 * 1024, 'a'); + check(f.client->post("/ai/xai/platform/files", "{\"action\":\"upload\",\"filename\":\"a\",\"data_base64\":\"" + big + "\"}", + "application/json").status == 413, "body over the cap is 413"); + check(f.client->post("/ai/xai/platform/files", "{\"action\":\"upload\",\"filename\":\"a.txt\",\"data_base64\":\"!!!\"}", + "application/json").status == 422, "bad base64 is 422"); + check(f.client->post("/ai/xai/platform/files", "{\"action\":\"upload\",\"filename\":\"a/b\",\"data_base64\":\"QUJD\"}", + "application/json").status == 422, "path in filename is 422"); + check(f.client->post("/ai/xai/platform/files", "{\"action\":\"list\",\"limit\":5000}", "application/json").status == 422, + "limit over the cap is 422"); + check(f.client->post("/ai/xai/platform/files", "{\"action\":\"list_all\",\"max_pages\":1000}", "application/json").status == 422, + "page walk over the cap is 422"); + check(f.client->post("/ai/xai/platform/tts", "{\"text\":123}", "application/json").status == 422, "wrong type is 422"); + check(f.client->post("/ai/xai/platform/tts", "{\"text\":\"" + std::string(60001, 'a') + "\"}", "application/json").status == 422, + "tts text over 60000 characters is 422"); + check(f.client->post("/ai/xai/platform/stt", "{\"keyterms\":[\"a\"],\"url\":\"ftp://x\"}", "application/json").status == 422, + "stt url scheme is checked"); + check(f.client->post("/ai/xai/platform/collections", "{\"action\":\"batch_get\",\"collection_id\":\"c\",\"file_ids\":[]}", + "application/json").status == 422, "empty batch is 422"); + check(f.client->post("/ai/xai/platform/search", "{\"query\":\"q\",\"collection_ids\":[\"c\"],\"retrieval_mode\":\"fuzzy\"}", + "application/json").status == 422, "unknown retrieval mode is 422"); + return finish("ai/xai/platform/local"); +} diff --git a/tests/example/ai/xai/platform/page_test.cpp b/tests/example/ai/xai/platform/page_test.cpp new file mode 100644 index 0000000..f6ab6f2 --- /dev/null +++ b/tests/example/ai/xai/platform/page_test.cpp @@ -0,0 +1,22 @@ +// Route: GET /ai/xai/platform (page, no credential needed) +#include "support/Assert.hpp" + +using namespace molo::example::test; + +int main() { + unsetenv("XAI_API_KEY"); + unsetenv("XAI_MANAGEMENT_KEY"); + Fixture f; + auto res = f.client->get("/ai/xai/platform"); + check(res.status == 200, "status 200"); + check(contains(res.headers.get("Content-Type"), "text/html"), "html"); + check(contains(res.body, "xAI Platform") && contains(res.body, "viewport"), "page and mobile viewport"); + check(contains(res.body, "/embedded/ai_xai_platform.js"), "script wired"); + check(contains(res.body, "