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:
@@ -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.
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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", ®ion}, {"timezone", &timezone}})
|
||||
if (!v->empty()) {
|
||||
if (v->size() > 128) bad("location field too long");
|
||||
loc.set(k, *v);
|
||||
}
|
||||
t.set("location", loc);
|
||||
}
|
||||
return t;
|
||||
}
|
||||
|
||||
Json SessionTool::x_search(const std::vector<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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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())
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user