feat(clients): xai platform: voice, files, collections, management API, key info

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-24 08:05:20 +02:00
co-authored by Claude Sonnet 5.5
parent 2e0270c043
commit 85015b1c33
57 changed files with 6925 additions and 3 deletions
+193
View File
@@ -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.<token>` 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.
+21
View File
@@ -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<llm::ApiClient> 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
+135
View File
@@ -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<std::string>& 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<std::size_t>(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
+54
View File
@@ -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 <string>
#include <vector>
#include "xai/platform/platform_service.h"
namespace molo::xai::platform {
struct ApiKeySpec {
std::string name; // required for create
std::vector<std::string> 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<llm::ApiClient> 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<std::string>& 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
+50
View File
@@ -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
+38
View File
@@ -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 <string>
#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<llm::ApiClient> 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
+130
View File
@@ -0,0 +1,130 @@
#include "xai/platform/billing.h"
#include <cctype>
#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<unsigned char>(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<unsigned char>(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
+44
View File
@@ -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 <string>
#include <vector>
#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<std::string> invoice_ids;
};
class BillingService : public PlatformService {
public:
explicit BillingService(std::shared_ptr<llm::ApiClient> 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
+118
View File
@@ -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<std::size_t>(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<std::string> 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
+62
View File
@@ -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 <cstddef>
#include <initializer_list>
#include <string>
#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:<operationId>" | "docs:<page>" | "guide:<page>"
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<std::string> segments = {});
} // namespace molo::xai::platform
+59
View File
@@ -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 <cstddef>
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
+28
View File
@@ -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
+46
View File
@@ -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 <memory>
#include <string>
#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<llm::ApiClient> api,
std::shared_ptr<llm::ApiClient> management)
: api_(std::move(api)), management_(std::move(management)) {}
static llm::ApiClientConfig api_config();
static llm::ApiClientConfig management_config();
const std::shared_ptr<llm::ApiClient>& api() const { return api_; }
const std::shared_ptr<llm::ApiClient>& management() const { return management_; }
private:
std::shared_ptr<llm::ApiClient> api_;
std::shared_ptr<llm::ApiClient> management_;
};
} // namespace molo::xai::platform
+207
View File
@@ -0,0 +1,207 @@
#include "xai/platform/collections.h"
#include <algorithm>
#include "xai/platform/caps.h"
namespace molo::xai::platform {
namespace {
bool one_of(const std::string& v, std::initializer_list<const char*> 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<std::string>& 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
+69
View File
@@ -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 <string>
#include <vector>
#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<llm::ApiClient> 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<std::string>& 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
+70
View File
@@ -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
+37
View File
@@ -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 <string>
#include <vector>
#include "xai/platform/platform_service.h"
namespace molo::xai::platform {
struct DocumentSearchRequest {
std::string query; // required
std::vector<std::string> 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<llm::ApiClient> 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
+114
View File
@@ -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<std::size_t>(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
+47
View File
@@ -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 <string>
#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<llm::ApiClient> 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
+118
View File
@@ -0,0 +1,118 @@
#include "xai/platform/platform_service.h"
#include <cctype>
#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<char>(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<llm::ApiClient> 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<unsigned char>(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<std::string> 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<std::string> 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<std::string> 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<std::string> 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
+66
View File
@@ -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 <initializer_list>
#include <memory>
#include <string>
#include <utility>
#include <vector>
#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<std::pair<std::string, std::string>>& pairs() const { return pairs_; }
private:
std::vector<std::pair<std::string, std::string>> pairs_;
};
class PlatformService : public llm::Service {
public:
PlatformService(std::shared_ptr<llm::ApiClient> 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<std::string> segments,
const Json* body = nullptr, const Query& query = Query());
llm::RawResponse invoke_raw(Call call, std::initializer_list<std::string> segments,
const std::string* body = nullptr,
const std::string& content_type = "",
const Query& query = Query());
Json invoke_multipart(Call call, std::initializer_list<std::string> segments,
const clients::body::MultipartBody& form);
[[noreturn]] void bad(const std::string& why) const;
std::string path_of(Call call, std::initializer_list<std::string> segments,
const Query& query) const;
private:
Host host_;
};
} // namespace molo::xai::platform
+147
View File
@@ -0,0 +1,147 @@
#include "xai/platform/realtime_rest.h"
#include <cctype>
#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<unsigned char>(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<unsigned char>(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
+54
View File
@@ -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 <string>
#include <vector>
#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<std::string> 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<llm::ApiClient> 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
+311
View File
@@ -0,0 +1,311 @@
#include "xai/platform/realtime_session.h"
#include <chrono>
#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::milliseconds>(
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<int>(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<WsEvent> 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<int>(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
+103
View File
@@ -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 <deque>
#include <memory>
#include <string>
#include <vector>
#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<FunctionCall> calls; // response.function_call_arguments.done
Json usage; // response.done.response.usage
std::vector<WsEvent> events; // every event, in order (bounded)
bool truncated = false; // event or audio cap hit
std::vector<std::string> 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<WsEvent>& 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<WsEvent> 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<WsEvent> setup_events_;
std::deque<WsEvent> pending_; // read ahead while settling the two setup events
std::string conversation_id_;
bool input_binary_ = false;
};
} // namespace molo::xai::platform
+261
View File
@@ -0,0 +1,261 @@
#include "xai/platform/session_config.h"
#include <cctype>
#include <utility>
#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<std::string>& 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<std::string>& allow,
const std::vector<std::string>& 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<const char*, const std::string*>{"country", &country},
{"city", &city}, {"region", &region}, {"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<std::string>& allow,
const std::vector<std::string>& 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<std::string>& 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<std::string>& allowed,
const std::string& authorization,
const std::map<std::string, std::string>& 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
+74
View File
@@ -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 <map>
#include <optional>
#include <string>
#include <vector>
#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<std::string>& allowed_domains = {},
const std::vector<std::string>& 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<std::string>& allowed_handles = {},
const std::vector<std::string>& 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<std::string>& 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<std::string>& allowed_tools = {},
const std::string& authorization = "",
const std::map<std::string, std::string>& 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<bool> resumption;
AudioFormat input, output;
std::string language_hint; // BCP-47; es/pt need the regional variant
std::vector<std::string> keyterms; // max 100, 50 chars
double output_speed = 0; // 0 = unset, else 0.7..1.5
std::vector<Json> tools; // from SessionTool
std::map<std::string, std::string> 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
+175
View File
@@ -0,0 +1,175 @@
#include "xai/platform/socket.h"
#include <chrono>
#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::milliseconds>(
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::WsClient>(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<int>(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<WsEvent> 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<long>(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
+74
View File
@@ -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 <memory>
#include <optional>
#include <string>
#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 <token> (API key or client secret)
kClientSecretProtocol, // Sec-WebSocket-Protocol: xai-client-secret.<token>
};
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<WsEvent> 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<google::live::WsClient> ws_;
bool open_ = false;
long started_ms_ = 0;
Counters counters_;
};
} // namespace molo::xai::platform
+68
View File
@@ -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
+43
View File
@@ -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 <string>
#include <vector>
#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<std::string> 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<llm::ApiClient> 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
+153
View File
@@ -0,0 +1,153 @@
#include "xai/platform/stt_stream.h"
#include <chrono>
#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::milliseconds>(
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<int>(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<int>(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
+69
View File
@@ -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 <string>
#include <vector>
#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<std::string> 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<Json> partials; // transcript.partial bodies, in order
std::vector<Json> 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<WsEvent> 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
+275
View File
@@ -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/<page>.md
guide https://docs.x.ai/developers/<page>.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())
+87
View File
@@ -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<std::string, std::string>& 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
+48
View File
@@ -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 <map>
#include <string>
#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<std::string, std::string> 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<llm::ApiClient> 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<std::string, std::string>& m);
} // namespace molo::xai::platform
+116
View File
@@ -0,0 +1,116 @@
#include "xai/platform/tts_stream.h"
#include <chrono>
#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::milliseconds>(
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<int>(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
+60
View File
@@ -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 <string>
#include <vector>
#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<Json> 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<WsEvent> 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
+53
View File
@@ -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 <algorithm>
#include <initializer_list>
#include <string>
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 <typename Arr>
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 <typename Arr>
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<char>(std::tolower(static_cast<unsigned char>(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<char>(std::tolower(static_cast<unsigned char>(*p))));
return t == lower;
});
}
};
} // namespace molo::xai::platform
+87
View File
@@ -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<const char*, const std::string*>{"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
+38
View File
@@ -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 <string>
#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<llm::ApiClient> 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
+181
View File
@@ -0,0 +1,181 @@
#include "xai/platform/webhook.h"
#include <array>
#include <cstdint>
#include <cstring>
#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<std::size_t>(64 - used_, n);
std::memcpy(buf_ + used_, d, take);
used_ += take; d += take; n -= take;
if (used_ == 64) { block(buf_); used_ = 0; }
}
}
std::array<std::uint8_t, 32> 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<std::uint8_t>(bits >> (56 - 8 * i));
update(len, 8);
std::array<std::uint8_t, 32> out{};
for (int i = 0; i < 8; ++i)
for (int j = 0; j < 4; ++j) out[i * 4 + j] = static_cast<std::uint8_t>(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<const std::uint8_t*>(s.data()), s.size());
auto d = h.finish();
return std::string(reinterpret_cast<const char*>(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<unsigned char>(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<char>(k[i] ^ 0x36);
opad[i] = static_cast<char>(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_<base64>");
}
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,<sig>" 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
+46
View File
@@ -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_<base64>").
// Pure local logic, no network.
#include <string>
#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,<b64> v1,<b64>"
};
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
+149
View File
@@ -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
+44
View File
@@ -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 <cstddef>
#include <string>
#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