quantum-ai-sdk 0.2.0 → 0.2.2

package/dist/client.js

@@ -0,0 +1,498 @@
+import { parseAPIError } from "./errors.js";
+import { chat, chatStream } from "./chat.js";
+import { chatSession } from "./session.js";
+import { agentRun, missionRun } from "./agent.js";
+import { generateImage, editImage } from "./image.js";
+import { speak, transcribe, soundEffects, generateMusic, dialogue, speechToSpeech, isolateVoice, remixVoice, dub, align, voiceDesign, starfishTTS, } from "./audio.js";
+import { generateVideo, videoStudio, videoTranslate, videoPhotoAvatar, videoDigitalTwin, videoAvatars, videoTemplates, videoHeygenVoices, } from "./video.js";
+import { embed } from "./embeddings.js";
+import { extractDocument, chunkDocument, processDocument } from "./documents.js";
+import { ragSearch, ragCorpora, surrealRagSearch, surrealRagProviders } from "./rag.js";
+import { listModels, getPricing } from "./models.js";
+import { accountBalance, accountUsage, accountUsageSummary, accountPricing, } from "./account.js";
+import { createJob, getJob, pollJob, listJobs, chatJob, streamJob, generate3D } from "./jobs.js";
+import { createKey, listKeys, revokeKey } from "./keys.js";
+import { computeTemplates, computeProvision, computeInstances, computeInstance, computeDelete, computeSSHKey, computeKeepalive, } from "./compute.js";
+import { listVoices, cloneVoice, deleteVoice } from "./voices.js";
+import { realtimeConnect, realtimeSession, realtimeEnd, realtimeRefresh } from "./realtime.js";
+import { batchSubmit, batchSubmitJsonl, batchJobs, batchJob } from "./batch.js";
+import { creditPacks, creditPurchase, creditBalance, creditTiers, devProgramApply } from "./credits.js";
+import { authApple } from "./auth.js";
+import { DEFAULT_BASE_URL } from "./types.js";
+/**
+ * QuantumClient is the Quantum AI API client.
+ *
+ * @example
+ * ```ts
+ * const client = new QuantumClient("qai_key_xxx");
+ *
+ * const resp = await client.chat({
+ *   model: "claude-sonnet-4-6",
+ *   messages: [{ role: "user", content: "Hello!" }],
+ * });
+ * ```
+ */
+export class QuantumClient {
+    apiKey;
+    baseUrl;
+    _fetch;
+    constructor(apiKey, options) {
+        this.apiKey = apiKey;
+        this.baseUrl = options?.baseUrl ?? DEFAULT_BASE_URL;
+        this._fetch = options?.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /** @internal — used by realtime module to build WebSocket URL. */
+    get _baseUrl() {
+        return this.baseUrl;
+    }
+    /** @internal — used by realtime module for auth. */
+    get _apiKey() {
+        return this.apiKey;
+    }
+    // ── Chat ──────────────────────────────────────────────────────────
+    /** Send a non-streaming chat request. */
+    async chat(req) {
+        return chat(this, req);
+    }
+    /**
+     * Send a streaming chat request. Returns an AsyncIterableIterator of StreamEvents.
+     *
+     * @example
+     * ```ts
+     * for await (const event of client.chatStream({
+     *   model: "gpt-5-mini",
+     *   messages: [{ role: "user", content: "Write a haiku" }],
+     * })) {
+     *   process.stdout.write(event.delta?.text ?? "");
+     * }
+     * ```
+     */
+    async *chatStream(req, signal) {
+        yield* chatStream(this, req, signal);
+    }
+    // ── Session Chat ────────────────────────────────────────────────
+    /**
+     * Send a session-based chat request. The server manages conversation history.
+     *
+     * @example
+     * ```ts
+     * // Start a new session
+     * const resp = await client.chatSession({
+     *   message: "Hello!",
+     *   model: "claude-sonnet-4-6",
+     * });
+     *
+     * // Continue the conversation
+     * const resp2 = await client.chatSession({
+     *   session_id: resp.session_id,
+     *   message: "Tell me more",
+     * });
+     * ```
+     */
+    async chatSession(req) {
+        return chatSession(this, req);
+    }
+    // ── Agent ───────────────────────────────────────────────────────
+    /**
+     * Run a server-side agent orchestration. Streams SSE events as the
+     * conductor delegates work to workers.
+     *
+     * @example
+     * ```ts
+     * for await (const event of client.agentRun({
+     *   task: "Research the latest AI papers and summarize them",
+     * })) {
+     *   console.log(event.type, event);
+     * }
+     * ```
+     */
+    async *agentRun(req, signal) {
+        yield* agentRun(this, req, signal);
+    }
+    /**
+     * Run a full mission orchestration. Streams SSE events as the conductor
+     * plans, delegates, and workers execute.
+     *
+     * @example
+     * ```ts
+     * for await (const event of client.missionRun({
+     *   goal: "Build a REST API server in Go",
+     * })) {
+     *   console.log(event.type, event);
+     * }
+     * ```
+     */
+    async *missionRun(req, signal) {
+        yield* missionRun(this, req, signal);
+    }
+    // ── Image ─────────────────────────────────────────────────────────
+    /** Generate images from a text prompt. */
+    async generateImage(req) {
+        return generateImage(this, req);
+    }
+    /** Edit images using an AI model. */
+    async editImage(req) {
+        return editImage(this, req);
+    }
+    // ── Audio ─────────────────────────────────────────────────────────
+    /** Generate speech from text. */
+    async speak(req) {
+        return speak(this, req);
+    }
+    /** Convert speech to text. */
+    async transcribe(req) {
+        return transcribe(this, req);
+    }
+    /** Generate sound effects from a text prompt (ElevenLabs). */
+    async soundEffects(req) {
+        return soundEffects(this, req);
+    }
+    /** Generate music from a text prompt. */
+    async generateMusic(req) {
+        return generateMusic(this, req);
+    }
+    /** Generate multi-speaker dialogue audio (ElevenLabs). */
+    async dialogue(req) {
+        return dialogue(this, req);
+    }
+    /** Convert speech audio to a different voice (ElevenLabs). */
+    async speechToSpeech(req) {
+        return speechToSpeech(this, req);
+    }
+    /** Remove background noise and isolate speech (ElevenLabs). */
+    async isolateVoice(req) {
+        return isolateVoice(this, req);
+    }
+    /** Transform a voice by modifying attributes (ElevenLabs). */
+    async remixVoice(req) {
+        return remixVoice(this, req);
+    }
+    /** Dub audio/video into a target language (ElevenLabs). */
+    async dub(req) {
+        return dub(this, req);
+    }
+    /** Get word-level timestamps for audio+text alignment (ElevenLabs). */
+    async align(req) {
+        return align(this, req);
+    }
+    /** Generate voice previews from a text description (ElevenLabs). */
+    async voiceDesign(req) {
+        return voiceDesign(this, req);
+    }
+    /** Generate speech using HeyGen's Starfish TTS model. */
+    async starfishTTS(req) {
+        return starfishTTS(this, req);
+    }
+    // ── Video ─────────────────────────────────────────────────────────
+    /**
+     * Generate a video from a text prompt.
+     *
+     * Video generation is slow (30s-5min). For production use, consider
+     * submitting via the Jobs API instead.
+     */
+    async generateVideo(req) {
+        return generateVideo(this, req);
+    }
+    /** Create a talking-head video via HeyGen Studio. Returns an async job. */
+    async videoStudio(req) {
+        return videoStudio(this, req);
+    }
+    /** Submit a video translation job via HeyGen. Returns an async job. */
+    async videoTranslate(req) {
+        return videoTranslate(this, req);
+    }
+    /** Create a photo avatar via HeyGen. Returns an async job. */
+    async videoPhotoAvatar(req) {
+        return videoPhotoAvatar(this, req);
+    }
+    /** Create a digital twin via HeyGen. Returns an async job. */
+    async videoDigitalTwin(req) {
+        return videoDigitalTwin(this, req);
+    }
+    /** List available HeyGen avatars. */
+    async videoAvatars() {
+        return videoAvatars(this);
+    }
+    /** List available HeyGen templates. */
+    async videoTemplates() {
+        return videoTemplates(this);
+    }
+    /** List available HeyGen voices. */
+    async videoHeygenVoices() {
+        return videoHeygenVoices(this);
+    }
+    // ── Embeddings ────────────────────────────────────────────────────
+    /** Generate text embeddings for the given inputs. */
+    async embed(req) {
+        return embed(this, req);
+    }
+    // ── Documents ─────────────────────────────────────────────────────
+    /** Extract text content from a document (PDF, image, etc.). */
+    async extractDocument(req) {
+        return extractDocument(this, req);
+    }
+    /** Chunk a document into smaller pieces for embedding or processing. */
+    async chunkDocument(req) {
+        return chunkDocument(this, req);
+    }
+    /** Process a document with extraction + optional instructions. */
+    async processDocument(req) {
+        return processDocument(this, req);
+    }
+    // ── RAG ───────────────────────────────────────────────────────────
+    /** Search Vertex AI RAG corpora for relevant documentation. */
+    async ragSearch(req) {
+        return ragSearch(this, req);
+    }
+    /** List available Vertex AI RAG corpora. */
+    async ragCorpora() {
+        return ragCorpora(this);
+    }
+    /** Search provider API documentation via SurrealDB vector search. */
+    async surrealRagSearch(req) {
+        return surrealRagSearch(this, req);
+    }
+    /** List available documentation providers in SurrealDB RAG. */
+    async surrealRagProviders() {
+        return surrealRagProviders(this);
+    }
+    // ── Models ────────────────────────────────────────────────────────
+    /** List all available models with provider and pricing information. */
+    async listModels() {
+        return listModels(this);
+    }
+    /** Get the complete pricing table for all models. */
+    async getPricing() {
+        return getPricing(this);
+    }
+    // ── Account ───────────────────────────────────────────────────────
+    /** Get the account credit balance. */
+    async accountBalance() {
+        return accountBalance(this);
+    }
+    /** Get paginated usage history. */
+    async accountUsage(query) {
+        return accountUsage(this, query);
+    }
+    /** Get monthly usage summary. */
+    async accountUsageSummary(months) {
+        return accountUsageSummary(this, months);
+    }
+    /** Get the full pricing table (model ID -> pricing entry map). */
+    async accountPricing() {
+        return accountPricing(this);
+    }
+    // ── Jobs ──────────────────────────────────────────────────────────
+    /** Create an async job. Returns the job ID for polling. */
+    async createJob(req) {
+        return createJob(this, req);
+    }
+    /** Check the status of an async job. */
+    async getJob(jobId) {
+        return getJob(this, jobId);
+    }
+    /**
+     * Poll a job until completion or timeout.
+     *
+     * @param jobId - Job ID to poll.
+     * @param intervalMs - Polling interval in milliseconds (default 2000).
+     * @param maxAttempts - Maximum poll attempts before timeout (default 150).
+     */
+    async pollJob(jobId, intervalMs, maxAttempts) {
+        return pollJob(this, jobId, intervalMs, maxAttempts);
+    }
+    /** List all jobs for the authenticated user. */
+    async listJobs() {
+        return listJobs(this);
+    }
+    /**
+     * Submit a chat completion as an async job.
+     * Use for long-running models (e.g. Opus) where sync chat may time out.
+     * Params are the same shape as ChatRequest (model, messages, tools, etc.)
+     */
+    async chatJob(req) {
+        return chatJob(this, req);
+    }
+    /**
+     * Stream job progress via SSE. Yields events as the job runs.
+     * Events: progress (status update), complete (with result), error.
+     */
+    streamJob(jobId, signal) {
+        return streamJob(this, jobId, signal);
+    }
+    /** Generate a 3D model via the async jobs system. */
+    async generate3D(model, prompt, imageUrl) {
+        return generate3D(this, model, prompt, imageUrl);
+    }
+    // ── API Keys ──────────────────────────────────────────────────────
+    /** Create a scoped API key. */
+    async createKey(req) {
+        return createKey(this, req);
+    }
+    /** List all API keys for the authenticated user. */
+    async listKeys() {
+        return listKeys(this);
+    }
+    /** Revoke an API key. */
+    async revokeKey(id) {
+        return revokeKey(this, id);
+    }
+    // ── Compute ───────────────────────────────────────────────────────
+    /** Get available compute templates with pricing. */
+    async computeTemplates() {
+        return computeTemplates(this);
+    }
+    /** Provision a new GPU compute instance. */
+    async computeProvision(req) {
+        return computeProvision(this, req);
+    }
+    /** List all compute instances for the authenticated user. */
+    async computeInstances() {
+        return computeInstances(this);
+    }
+    /** Get full status of a single compute instance. */
+    async computeInstance(id) {
+        return computeInstance(this, id);
+    }
+    /** Tear down a compute instance and finalize billing. */
+    async computeDelete(id) {
+        return computeDelete(this, id);
+    }
+    /** Inject an SSH public key into a running instance. */
+    async computeSSHKey(id, req) {
+        return computeSSHKey(this, id, req);
+    }
+    /** Reset the inactivity timer on a compute instance. */
+    async computeKeepalive(id) {
+        return computeKeepalive(this, id);
+    }
+    // ── Voice Management ──────────────────────────────────────────────
+    /** List all available voices (ElevenLabs). */
+    async listVoices() {
+        return listVoices(this);
+    }
+    /** Create an instant voice clone from audio samples (ElevenLabs). */
+    async cloneVoice(req) {
+        return cloneVoice(this, req);
+    }
+    /** Delete a cloned voice (ElevenLabs). */
+    async deleteVoice(id) {
+        return deleteVoice(this, id);
+    }
+    // ── Realtime Voice ────────────────────────────────────────────────
+    /**
+     * Open a realtime voice session via WebSocket (proxy path).
+     * Returns [sender, receiver] for bidirectional audio communication.
+     */
+    async realtimeConnect(config) {
+        return realtimeConnect(this, config);
+    }
+    /** Request an ephemeral token for direct xAI voice connection (lower latency). */
+    async realtimeSession() {
+        return realtimeSession(this);
+    }
+    /** End a realtime session and finalize billing. */
+    async realtimeEnd(sessionId, durationSeconds) {
+        return realtimeEnd(this, sessionId, durationSeconds);
+    }
+    /** Refresh an ephemeral token for long sessions (>4 min). */
+    async realtimeRefresh(sessionId) {
+        return realtimeRefresh(this, sessionId);
+    }
+    // ── Batch Processing ──────────────────────────────────────────────
+    /** Submit a batch of jobs for processing. */
+    async batchSubmit(req) {
+        return batchSubmit(this, req);
+    }
+    /** Submit a batch of jobs using JSONL format. */
+    async batchSubmitJsonl(jsonl) {
+        return batchSubmitJsonl(this, jsonl);
+    }
+    /** List all batch jobs for the account. */
+    async batchJobs() {
+        return batchJobs(this);
+    }
+    /** Get the status and result of a single batch job. */
+    async batchJob(id) {
+        return batchJob(this, id);
+    }
+    // ── Credits ───────────────────────────────────────────────────────
+    /** List available credit packs (no auth required). */
+    async creditPacks() {
+        return creditPacks(this);
+    }
+    /** Purchase a credit pack. Returns a checkout URL for payment. */
+    async creditPurchase(req) {
+        return creditPurchase(this, req);
+    }
+    /** Get the current credit balance. */
+    async creditBalance() {
+        return creditBalance(this);
+    }
+    /** List available credit tiers (no auth required). */
+    async creditTiers() {
+        return creditTiers(this);
+    }
+    /** Apply for the developer program. */
+    async devProgramApply(req) {
+        return devProgramApply(this, req);
+    }
+    // ── Auth ──────────────────────────────────────────────────────────
+    /** Authenticate with Apple Sign-In. */
+    async authApple(req) {
+        return authApple(this, req);
+    }
+    // ── Internal HTTP helpers ─────────────────────────────────────────
+    /**
+     * Send a JSON request and decode the JSON response.
+     * @internal
+     */
+    async _doJSON(method, path, body) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+        const init = { method, headers };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(body);
+        }
+        const response = await this._fetch(`${this.baseUrl}${path}`, init);
+        const meta = {
+            requestId: response.headers.get("X-QAI-Request-Id") ?? "",
+            model: response.headers.get("X-QAI-Model") ?? "",
+            costTicks: 0,
+        };
+        const costHeader = response.headers.get("X-QAI-Cost-Ticks");
+        if (costHeader) {
+            meta.costTicks = parseInt(costHeader, 10) || 0;
+        }
+        if (!response.ok) {
+            throw await parseAPIError(response, meta.requestId);
+        }
+        const data = (await response.json());
+        return { data, meta };
+    }
+    /**
+     * Send a JSON request expecting an SSE (text/event-stream) response.
+     * Returns the raw Response for the caller to read SSE events from.
+     * @internal
+     */
+    async _doStreamRaw(path, body, signal) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            Accept: "text/event-stream",
+        };
+        const response = await this._fetch(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal,
+        });
+        if (!response.ok) {
+            const requestId = response.headers.get("X-QAI-Request-Id") ?? "";
+            throw await parseAPIError(response, requestId);
+        }
+        return response;
+    }
+}

package/dist/compute.d.ts

@@ -0,0 +1,37 @@
+import type { QuantumClient } from "./client.js";
+import type { DeleteResponse, InstanceResponse, InstancesResponse, ProvisionRequest, ProvisionResponse, SSHKeyRequest, StatusResponse, TemplatesResponse } from "./types.js";
+/**
+ * Get available compute templates with pricing.
+ * @internal — called by QuantumClient.computeTemplates()
+ */
+export declare function computeTemplates(client: QuantumClient): Promise<TemplatesResponse>;
+/**
+ * Provision a new GPU compute instance.
+ * @internal — called by QuantumClient.computeProvision()
+ */
+export declare function computeProvision(client: QuantumClient, req: ProvisionRequest): Promise<ProvisionResponse>;
+/**
+ * List all compute instances for the authenticated user.
+ * @internal — called by QuantumClient.computeInstances()
+ */
+export declare function computeInstances(client: QuantumClient): Promise<InstancesResponse>;
+/**
+ * Get full status of a single compute instance.
+ * @internal — called by QuantumClient.computeInstance()
+ */
+export declare function computeInstance(client: QuantumClient, id: string): Promise<InstanceResponse>;
+/**
+ * Tear down a compute instance and finalize billing.
+ * @internal — called by QuantumClient.computeDelete()
+ */
+export declare function computeDelete(client: QuantumClient, id: string): Promise<DeleteResponse>;
+/**
+ * Inject an SSH public key into a running instance.
+ * @internal — called by QuantumClient.computeSSHKey()
+ */
+export declare function computeSSHKey(client: QuantumClient, id: string, req: SSHKeyRequest): Promise<StatusResponse>;
+/**
+ * Reset the inactivity timer on a compute instance.
+ * @internal — called by QuantumClient.computeKeepalive()
+ */
+export declare function computeKeepalive(client: QuantumClient, id: string): Promise<StatusResponse>;

package/dist/compute.js

@@ -0,0 +1,56 @@
+/**
+ * Get available compute templates with pricing.
+ * @internal — called by QuantumClient.computeTemplates()
+ */
+export async function computeTemplates(client) {
+    const { data } = await client._doJSON("GET", "/qai/v1/compute/templates", undefined);
+    return data;
+}
+/**
+ * Provision a new GPU compute instance.
+ * @internal — called by QuantumClient.computeProvision()
+ */
+export async function computeProvision(client, req) {
+    const { data } = await client._doJSON("POST", "/qai/v1/compute/provision", req);
+    return data;
+}
+/**
+ * List all compute instances for the authenticated user.
+ * @internal — called by QuantumClient.computeInstances()
+ */
+export async function computeInstances(client) {
+    const { data } = await client._doJSON("GET", "/qai/v1/compute/instances", undefined);
+    return data;
+}
+/**
+ * Get full status of a single compute instance.
+ * @internal — called by QuantumClient.computeInstance()
+ */
+export async function computeInstance(client, id) {
+    const { data } = await client._doJSON("GET", `/qai/v1/compute/instance/${id}`, undefined);
+    return data;
+}
+/**
+ * Tear down a compute instance and finalize billing.
+ * @internal — called by QuantumClient.computeDelete()
+ */
+export async function computeDelete(client, id) {
+    const { data } = await client._doJSON("DELETE", `/qai/v1/compute/instance/${id}`, undefined);
+    return data;
+}
+/**
+ * Inject an SSH public key into a running instance.
+ * @internal — called by QuantumClient.computeSSHKey()
+ */
+export async function computeSSHKey(client, id, req) {
+    const { data } = await client._doJSON("POST", `/qai/v1/compute/instance/${id}/ssh-key`, req);
+    return data;
+}
+/**
+ * Reset the inactivity timer on a compute instance.
+ * @internal — called by QuantumClient.computeKeepalive()
+ */
+export async function computeKeepalive(client, id) {
+    const { data } = await client._doJSON("POST", `/qai/v1/compute/instance/${id}/keepalive`, undefined);
+    return data;
+}

package/dist/contact.d.ts

@@ -0,0 +1,12 @@
+import type { ContactRequest, StatusResponse } from "./types.js";
+/**
+ * Send a contact form message. This is a public endpoint (no auth required).
+ *
+ * Unlike other SDK methods, this is a standalone function rather than a
+ * QuantumClient method because it does not require an API key.
+ *
+ * @param req - Contact form data.
+ * @param baseUrl - API base URL (defaults to production).
+ * @param fetchFn - Custom fetch implementation.
+ */
+export declare function contact(req: ContactRequest, baseUrl?: string, fetchFn?: typeof globalThis.fetch): Promise<StatusResponse>;

package/dist/contact.js

@@ -0,0 +1,26 @@
+import { DEFAULT_BASE_URL } from "./types.js";
+import { parseAPIError } from "./errors.js";
+/**
+ * Send a contact form message. This is a public endpoint (no auth required).
+ *
+ * Unlike other SDK methods, this is a standalone function rather than a
+ * QuantumClient method because it does not require an API key.
+ *
+ * @param req - Contact form data.
+ * @param baseUrl - API base URL (defaults to production).
+ * @param fetchFn - Custom fetch implementation.
+ */
+export async function contact(req, baseUrl, fetchFn) {
+    const url = `${baseUrl ?? DEFAULT_BASE_URL}/qai/v1/contact`;
+    const doFetch = fetchFn ?? globalThis.fetch.bind(globalThis);
+    const response = await doFetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(req),
+    });
+    if (!response.ok) {
+        const requestId = response.headers.get("X-QAI-Request-Id") ?? "";
+        throw await parseAPIError(response, requestId);
+    }
+    return (await response.json());
+}

package/dist/credits.d.ts

@@ -0,0 +1,27 @@
+import type { QuantumClient } from "./client.js";
+import type { CreditPacksResponse, CreditPurchaseRequest, CreditPurchaseResponse, CreditBalanceResponse, CreditTiersResponse, DevProgramApplyRequest, DevProgramApplyResponse } from "./types.js";
+/**
+ * List available credit packs. No authentication required.
+ * @internal — called by QuantumClient.creditPacks()
+ */
+export declare function creditPacks(client: QuantumClient): Promise<CreditPacksResponse>;
+/**
+ * Purchase a credit pack. Returns a checkout URL for payment.
+ * @internal — called by QuantumClient.creditPurchase()
+ */
+export declare function creditPurchase(client: QuantumClient, req: CreditPurchaseRequest): Promise<CreditPurchaseResponse>;
+/**
+ * Get the current credit balance.
+ * @internal — called by QuantumClient.creditBalance()
+ */
+export declare function creditBalance(client: QuantumClient): Promise<CreditBalanceResponse>;
+/**
+ * List available credit tiers. No authentication required.
+ * @internal — called by QuantumClient.creditTiers()
+ */
+export declare function creditTiers(client: QuantumClient): Promise<CreditTiersResponse>;
+/**
+ * Apply for the developer program.
+ * @internal — called by QuantumClient.devProgramApply()
+ */
+export declare function devProgramApply(client: QuantumClient, req: DevProgramApplyRequest): Promise<DevProgramApplyResponse>;