@qvac/sdk 0.18.2 → 0.19.0

package/dist/src/client/api/audio-gen.js

@@ -0,0 +1,68 @@
+import { stream as streamRpc } from '../rpc/rpc-client.js';
+import { createAudioGenResult } from './audio-gen-result.js';
+/**
+ * Generates PCM audio using a loaded AudioGen model.
+ *
+ * @param params - Loaded model ID, required caption, and optional lyrics, musical controls, duration, and seed.
+ * @param params.maxFrames - MiniMax semantic-frame cap; mutually exclusive with `duration`.
+ * @param params.inferenceSteps - MiniMax flow steps for this run.
+ * @param params.cfgScale - MiniMax flow classifier-free guidance scale for this run.
+ * @param params.referenceAudio - Optional timbre reference: a file path (decoded server-side)
+ *   or raw interleaved stereo 48 kHz Float32 LE PCM bytes.
+ * @param params.sourceAudio - Source audio to re-render (same forms as `referenceAudio`);
+ *   required when `taskType` is `"cover-nofsq"`.
+ * @param params.taskType - `"text2music"` (default) or `"cover-nofsq"`.
+ * @param params.audioCoverStrength - Source-context strength for cover tasks (0..1).
+ * @param params.coverNoiseStrength - Initial source/noise blend for cover tasks (0..1).
+ * @returns A run with a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise describing the backend the run resolved to.
+ *
+ * @example
+ * ```typescript
+ * const modelId = await loadModel({
+ *   modelType: "audiogen",
+ *   modelConfig: {
+ *     textEncModelSrc,
+ *     lmModelSrc,
+ *     ditModelSrc,
+ *     vaeModelSrc,
+ *   },
+ * });
+ * const run = audioGen({ modelId, caption: "ambient electronic music", duration: 10 });
+ * stopButton.onclick = () => cancel({ requestId: run.requestId });
+ * for await (const progress of run.progressStream) {
+ *   console.log(progress.stage, progress.step, progress.total);
+ * }
+ * const { pcm, sampleRate, channels, bitsPerSample } = await run.audio;
+ * const stats = await run.stats;
+ *
+ * // MiniMax-Music3 uses a local LM and synthesis GGUF pair:
+ * const minimaxId = await loadModel({
+ *   modelType: "audiogen",
+ *   modelConfig: {
+ *     engine: "minimax",
+ *     lmModelSrc: "/models/mm3-lm-q8.gguf",
+ *     synthModelSrc: "/models/mm3-synth-q8.gguf",
+ *   },
+ * });
+ * const minimaxRun = audioGen({
+ *   modelId: minimaxId,
+ *   caption: "warm cinematic piano",
+ *   maxFrames: 250,
+ *   inferenceSteps: 12,
+ *   cfgScale: 1.8,
+ * });
+ *
+ * // Re-render an existing song with a new caption (cover) and a timbre reference:
+ * const cover = audioGen({
+ *   modelId,
+ *   caption: "orchestral arrangement with dramatic strings",
+ *   taskType: "cover-nofsq",
+ *   sourceAudio: "/path/to/source.wav",
+ *   referenceAudio: "/path/to/reference.mp3",
+ *   coverNoiseStrength: 0.75,
+ * });
+ * ```
+ */
+export function audioGen(params) {
+    return createAudioGenResult(params, streamRpc);
+}

package/dist/src/client/api/batch-completion.d.ts

@@ -0,0 +1,28 @@
+import { type BatchCompletionClientParams, type BatchCompletionRun, type BatchCompletionStreamRequest, type McpClientInput, type RPCOptions, type Tool } from '@qvac/inference/surface';
+import { type ToolInput } from '../../utils/tool-helpers.js';
+type BatchPromptParams = Omit<BatchCompletionClientParams['prompts'][number], 'tools'> & {
+    tools?: Tool[] | ToolInput[];
+    mcp?: McpClientInput[];
+};
+type BatchCompletionParams = Omit<BatchCompletionClientParams, 'prompts' | 'requestId'> & {
+    prompts: BatchPromptParams[];
+    rpcOptions?: RPCOptions;
+};
+type BatchCompletionStreamFactory = (request: BatchCompletionStreamRequest, options?: RPCOptions) => AsyncGenerator<unknown>;
+/**
+ * Runs multiple prompts concurrently through one loaded model.
+ *
+ * The returned run exposes the request ID immediately, a merged event stream,
+ * ordered results, aggregate batch statistics, and per-prompt streams via
+ * `byId()`. Stream-level failures reject the aggregate promises; individual
+ * terminal failures are also exposed through the corresponding `byId().final`.
+ *
+ * @param params - The loaded model, prompts, concurrency controls, and optional
+ *   RPC settings for the batch.
+ * @returns A live batch run that can be consumed as merged or per-prompt
+ *   streams.
+ */
+export declare function batchCompletion(params: BatchCompletionParams): BatchCompletionRun;
+export declare function createBatchCompletionRun(params: BatchCompletionParams, streamFactory: BatchCompletionStreamFactory): BatchCompletionRun;
+export {};
+//# sourceMappingURL=batch-completion.d.ts.map

package/dist/src/client/api/batch-completion.js

@@ -0,0 +1,345 @@
+import { stream as streamRpc } from '../rpc/rpc-client.js';
+import { generateClientRequestId } from './client-request-id.js';
+import { getClientLogger } from '../../logging/index.js';
+import { batchCompletionStreamResponseSchema } from '@qvac/inference/surface';
+import { buildFinalFromEvents } from '../../utils/aggregate-events.js';
+import { CompletionFailedError, InferenceCancelledError } from '../../utils/errors-server.js';
+import { getMcpToolsWithHandlers } from '../../utils/mcp-adapter.js';
+import { validateTools } from '../../utils/tool-helpers.js';
+const logger = getClientLogger();
+function createPerIdState() {
+    let finalResolver = () => { };
+    let finalRejecter = () => { };
+    const final = new Promise((resolve, reject) => {
+        finalResolver = resolve;
+        finalRejecter = reject;
+    });
+    final.catch(() => { });
+    return {
+        allEvents: [],
+        final,
+        finalResolver,
+        finalRejecter,
+        eventWaiters: [],
+        done: false
+    };
+}
+function addHandlers(target, source) {
+    for (const [name, handler] of source) {
+        if (target.has(name)) {
+            logger.warn(`Duplicate tool handler for "${name}", overwriting`);
+        }
+        target.set(name, handler);
+    }
+}
+async function resolveBatchPrompts(prompts) {
+    const resolvedPrompts = [];
+    const resolvedHandlers = [];
+    for (const prompt of prompts) {
+        let allTools = [];
+        const handlers = new Map();
+        if (prompt.tools) {
+            const { tools, handlers: toolHandlers } = validateTools(prompt.tools);
+            allTools = tools;
+            addHandlers(handlers, toolHandlers);
+        }
+        if (prompt.mcp && prompt.mcp.length > 0) {
+            const { tools: mcpTools, handlers: mcpHandlers } = await getMcpToolsWithHandlers(prompt.mcp);
+            allTools = [...mcpTools, ...allTools];
+            addHandlers(handlers, mcpHandlers);
+        }
+        resolvedHandlers.push(handlers);
+        resolvedPrompts.push({
+            ...(prompt.id !== undefined && { id: prompt.id }),
+            history: prompt.history,
+            ...(prompt.generationParams && {
+                generationParams: prompt.generationParams
+            }),
+            ...(prompt.responseFormat && { responseFormat: prompt.responseFormat }),
+            ...(allTools.length > 0 && { tools: allTools })
+        });
+    }
+    return { prompts: resolvedPrompts, handlers: resolvedHandlers };
+}
+/**
+ * Runs multiple prompts concurrently through one loaded model.
+ *
+ * The returned run exposes the request ID immediately, a merged event stream,
+ * ordered results, aggregate batch statistics, and per-prompt streams via
+ * `byId()`. Stream-level failures reject the aggregate promises; individual
+ * terminal failures are also exposed through the corresponding `byId().final`.
+ *
+ * @param params - The loaded model, prompts, concurrency controls, and optional
+ *   RPC settings for the batch.
+ * @returns A live batch run that can be consumed as merged or per-prompt
+ *   streams.
+ */
+export function batchCompletion(params) {
+    return createBatchCompletionRun(params, streamRpc);
+}
+export function createBatchCompletionRun(params, streamFactory) {
+    const requestId = generateClientRequestId();
+    const states = new Map();
+    const subStreams = new Map();
+    const eventQueue = [];
+    const handlersById = new Map();
+    let handlersByPosition = [];
+    const emptyHandlers = new Map();
+    let eventResolve = null;
+    let idsResolver = () => { };
+    let idsRejecter = () => { };
+    let resultsResolver = () => { };
+    let resultsRejecter = () => { };
+    let statsResolver = () => { };
+    let statsRejecter = () => { };
+    let idsResolved = false;
+    let done = false;
+    let streamError = null;
+    let settledIds = null;
+    const idsPromise = new Promise((resolve, reject) => {
+        idsResolver = resolve;
+        idsRejecter = reject;
+    });
+    idsPromise.catch(() => { });
+    const resultsPromise = new Promise((resolve, reject) => {
+        resultsResolver = resolve;
+        resultsRejecter = reject;
+    });
+    resultsPromise.catch(() => { });
+    const statsPromise = new Promise((resolve, reject) => {
+        statsResolver = resolve;
+        statsRejecter = reject;
+    });
+    statsPromise.catch(() => { });
+    function ensureState(id) {
+        let state = states.get(id);
+        if (!state) {
+            state = createPerIdState();
+            states.set(id, state);
+            if (done) {
+                if (streamError !== null) {
+                    state.finalRejecter(streamError);
+                    state.done = true;
+                }
+                else if (settledIds?.has(id)) {
+                    settleState(id, state);
+                }
+                else {
+                    state.finalRejecter(new CompletionFailedError(`Unknown batch prompt id "${id}".`));
+                    state.done = true;
+                }
+            }
+        }
+        return state;
+    }
+    function notifyWaiters() {
+        if (eventResolve) {
+            eventResolve();
+            eventResolve = null;
+        }
+        for (const state of states.values()) {
+            const waiters = state.eventWaiters.splice(0);
+            for (const resolve of waiters)
+                resolve();
+        }
+    }
+    function resolveIds(ids) {
+        if (idsResolved)
+            return;
+        idsResolved = true;
+        for (const [index, id] of ids.entries()) {
+            handlersById.set(id, handlersByPosition[index] ?? emptyHandlers);
+            ensureState(id);
+        }
+        idsResolver(ids);
+    }
+    function rejectAll(error) {
+        idsRejecter(error);
+        resultsRejecter(error);
+        statsRejecter(error);
+        for (const state of states.values()) {
+            if (!state.done)
+                state.finalRejecter(error);
+            state.done = true;
+        }
+    }
+    function settleState(id, state) {
+        if (state.done)
+            return undefined;
+        const handlers = handlersById.get(id) ?? emptyHandlers;
+        const { final, error, cancelled } = buildFinalFromEvents(state.allEvents, handlers);
+        if (error) {
+            const err = new CompletionFailedError(error.message, error);
+            state.finalRejecter(err);
+            state.done = true;
+            return err;
+        }
+        if (cancelled) {
+            const err = new InferenceCancelledError(requestId, {
+                text: final.contentText,
+                toolCalls: final.toolCalls,
+                ...(final.stats && { stats: final.stats })
+            });
+            state.finalRejecter(err);
+            state.done = true;
+            return err;
+        }
+        state.finalResolver(final);
+        state.done = true;
+        return { id, final };
+    }
+    function finishAll(ids) {
+        const results = [];
+        let firstError;
+        settledIds = new Set(ids);
+        for (const id of ids) {
+            const state = ensureState(id);
+            const outcome = settleState(id, state);
+            if (outcome instanceof Error) {
+                firstError ??= outcome;
+            }
+            else if (outcome !== undefined) {
+                results.push(outcome);
+            }
+        }
+        for (const [id, state] of states) {
+            if (!settledIds.has(id) && !state.done) {
+                state.finalRejecter(new CompletionFailedError(`Unknown batch prompt id "${id}".`));
+                state.done = true;
+            }
+        }
+        if (firstError !== undefined) {
+            resultsRejecter(firstError);
+        }
+        else {
+            resultsResolver(results);
+        }
+        return firstError;
+    }
+    const processResponses = async () => {
+        try {
+            const resolved = await resolveBatchPrompts(params.prompts);
+            handlersByPosition = resolved.handlers;
+            const request = {
+                type: 'batchCompletionStream',
+                modelId: params.modelId,
+                prompts: resolved.prompts,
+                stream: params.stream ?? true,
+                captureThinking: params.captureThinking,
+                emitRawDeltas: params.emitRawDeltas,
+                toolDialect: params.toolDialect,
+                requestId
+            };
+            let orderedIds = [];
+            const responses = streamFactory(request, params.rpcOptions);
+            for await (const response of responses) {
+                if (response &&
+                    typeof response === 'object' &&
+                    'type' in response &&
+                    response.type === 'batchCompletionStream') {
+                    const streamResponse = batchCompletionStreamResponseSchema.parse(response);
+                    if (streamResponse.ids) {
+                        orderedIds = streamResponse.ids;
+                        resolveIds(orderedIds);
+                    }
+                    for (const batchEvent of streamResponse.events) {
+                        const state = ensureState(batchEvent.id);
+                        state.allEvents.push(batchEvent.event);
+                        eventQueue.push(batchEvent);
+                    }
+                    notifyWaiters();
+                    if (streamResponse.done) {
+                        if (!idsResolved) {
+                            orderedIds =
+                                orderedIds.length > 0
+                                    ? orderedIds
+                                    : params.prompts.map((prompt, index) => prompt.id ?? String(index));
+                            resolveIds(orderedIds);
+                        }
+                        const firstError = finishAll(orderedIds);
+                        if (firstError !== undefined) {
+                            statsRejecter(firstError);
+                        }
+                        else {
+                            statsResolver(streamResponse.stats);
+                        }
+                        done = true;
+                        notifyWaiters();
+                    }
+                }
+            }
+        }
+        catch (error) {
+            streamError = error instanceof Error ? error : new Error(String(error));
+            rejectAll(error);
+            done = true;
+            for (const state of states.values())
+                state.done = true;
+            notifyWaiters();
+        }
+    };
+    void processResponses();
+    const events = (async function* () {
+        while (true) {
+            if (eventQueue.length > 0) {
+                yield eventQueue.shift();
+            }
+            else if (done) {
+                if (streamError !== null) {
+                    throw streamError;
+                }
+                break;
+            }
+            else {
+                await new Promise((resolve) => {
+                    eventResolve = resolve;
+                });
+            }
+        }
+    })();
+    function makeSubStream(id) {
+        const state = ensureState(id);
+        const events = {
+            async *[Symbol.asyncIterator]() {
+                let index = 0;
+                while (true) {
+                    if (index < state.allEvents.length) {
+                        yield state.allEvents[index];
+                        index += 1;
+                    }
+                    else if (state.done || done) {
+                        if (streamError !== null) {
+                            throw streamError;
+                        }
+                        break;
+                    }
+                    else {
+                        await new Promise((resolve) => {
+                            state.eventWaiters.push(resolve);
+                        });
+                    }
+                }
+            }
+        };
+        return {
+            events,
+            final: state.final
+        };
+    }
+    function byId(id) {
+        let subStream = subStreams.get(id);
+        if (!subStream) {
+            subStream = makeSubStream(id);
+            subStreams.set(id, subStream);
+        }
+        return subStream;
+    }
+    return {
+        requestId,
+        ids: idsPromise,
+        events,
+        results: resultsPromise,
+        stats: statsPromise,
+        byId
+    };
+}

package/dist/src/client/api/bci-transcribe.d.ts

@@ -0,0 +1,57 @@
+import { type BciTranscribeClientParams, type BciTranscribeStreamClientParams, type BciTranscribeStreamSession, type BciTranscribeStreamMetadataSession, type RPCOptions, type TranscribeSegment } from '@qvac/inference/surface';
+/**
+ * Transcribe a neural-signal buffer with a loaded BCI model and return the
+ * complete text. Accepts either a `.bin` file path or a raw neural buffer.
+ *
+ * @param params - BCI transcription parameters.
+ * @param params.modelId - The identifier of the loaded BCI model to use.
+ * @param params.neuralData - Neural signal as either a file path (string) or
+ *                            a binary buffer (`Uint8Array`).
+ * @param params.metadata - When true, resolves to an array of transcript
+ *                          segments (`{ text, startMs, endMs, append, id }`)
+ *                          instead of joined text.
+ * @param options - Optional RPC options including per-call profiling.
+ * @returns A promise (decorated with `requestId`) resolving to the complete
+ *          transcribed text, or — when `metadata` is true — the list of
+ *          transcript segments in emission order. The `requestId` is
+ *          reachable synchronously so callers can target this in-flight
+ *          transcription with `cancel({ requestId })` before `await` resolves.
+ */
+export declare function bciTranscribe(params: BciTranscribeClientParams & {
+    metadata: true;
+}, options?: RPCOptions): Promise<TranscribeSegment[]> & {
+    requestId: string;
+};
+export declare function bciTranscribe(params: BciTranscribeClientParams, options?: RPCOptions): Promise<string> & {
+    requestId: string;
+};
+/**
+ * Opens a bidirectional streaming BCI transcription session. Neural-signal
+ * chunks are streamed in via `write()`, and transcription is yielded as the
+ * addon's sliding window decodes successive windows.
+ *
+ * The returned session is single-use. Attempting to iterate a second time
+ * will throw a `TranscriptionFailedError`.
+ *
+ * @param params - Streaming BCI transcription parameters.
+ * @param params.modelId - The loaded BCI model to use.
+ * @param params.metadata - When true, the session yields transcript segment
+ *                          objects (`{ text, startMs, endMs, append, id }`)
+ *                          instead of plain text.
+ * @param params.windowTimesteps - Decode window size in timesteps.
+ * @param params.hopTimesteps - How far the window advances between decodes.
+ * @param params.emit - `'delta'` (default) yields only the newly-discovered
+ *                       tail per window; `'full'` yields the full running
+ *                       transcript each update.
+ * @param options - Optional RPC options including per-call profiling.
+ * @returns A session object: call `write(neuralChunk)` with a `Uint8Array`
+ *          to feed neural-signal bytes, iterate with `for await (...)` to
+ *          receive transcription, and `end()` to signal end of input. The
+ *          session exposes `requestId` synchronously for targeted
+ *          `cancel({ requestId })`.
+ */
+export declare function bciTranscribeStream(params: BciTranscribeStreamClientParams & {
+    metadata: true;
+}, options?: RPCOptions): Promise<BciTranscribeStreamMetadataSession>;
+export declare function bciTranscribeStream(params: BciTranscribeStreamClientParams, options?: RPCOptions): Promise<BciTranscribeStreamSession>;
+//# sourceMappingURL=bci-transcribe.d.ts.map

package/dist/src/client/api/bci-transcribe.js

@@ -0,0 +1,173 @@
+import { bciTranscribeResponseSchema, bciTranscribeClientParamsSchema, bciTranscribeStreamResponseSchema } from '@qvac/inference/surface';
+import { stream, duplex } from '../rpc/rpc-client.js';
+import { getClientLogger } from '../../logging/index.js';
+import { TranscriptionFailedError } from '../../utils/errors-client.js';
+import { decoratePromise } from '../../utils/decorate-promise.js';
+import { parseClientInput } from '../parse-input.js';
+import { generateClientRequestId } from './client-request-id.js';
+const logger = getClientLogger();
+function buildBciTranscribeRequest(params, requestId) {
+    return {
+        type: 'bciTranscribe',
+        modelId: params.modelId,
+        neuralData: typeof params.neuralData === 'string'
+            ? { type: 'filePath', value: params.neuralData }
+            : {
+                type: 'base64',
+                value: Buffer.from(params.neuralData).toString('base64')
+            },
+        ...(params.metadata === true && { metadata: true }),
+        requestId
+    };
+}
+export function bciTranscribe(params, options) {
+    const parsed = parseClientInput(bciTranscribeClientParamsSchema, params);
+    const requestId = generateClientRequestId();
+    const inner = runBciTranscribe(parsed, requestId, options);
+    return decoratePromise(inner, { requestId });
+}
+async function runBciTranscribe(params, requestId, options) {
+    const request = buildBciTranscribeRequest(params, requestId);
+    if (params.metadata === true) {
+        const segments = [];
+        for await (const response of stream(request, options)) {
+            if (response.type === 'bciTranscribe') {
+                const parsed = bciTranscribeResponseSchema.parse(response);
+                if (parsed.segment) {
+                    segments.push(parsed.segment);
+                }
+                if (parsed.done) {
+                    break;
+                }
+            }
+        }
+        return segments;
+    }
+    let fullText = '';
+    for await (const response of stream(request, options)) {
+        if (response.type === 'bciTranscribe') {
+            const parsed = bciTranscribeResponseSchema.parse(response);
+            if (parsed.text) {
+                fullText += parsed.text;
+            }
+            if (parsed.done) {
+                break;
+            }
+        }
+    }
+    return fullText;
+}
+function buildBciTranscribeStreamRequest(params, requestId) {
+    const streamOpts = {
+        ...(params.windowTimesteps !== undefined && {
+            windowTimesteps: params.windowTimesteps
+        }),
+        ...(params.hopTimesteps !== undefined && {
+            hopTimesteps: params.hopTimesteps
+        }),
+        ...(params.emit !== undefined && { emit: params.emit })
+    };
+    return {
+        type: 'bciTranscribeStream',
+        modelId: params.modelId,
+        ...(params.metadata === true && { metadata: true }),
+        ...(Object.keys(streamOpts).length > 0 && { streamOpts }),
+        requestId
+    };
+}
+export function bciTranscribeStream(params, options) {
+    if (params.metadata === true) {
+        return createBciStreamSession(params, options, processLineMetadata, 'BciTranscribeStreamMetadataSession');
+    }
+    return createBciStreamSession(params, options, processLine, 'BciTranscribeStreamSession');
+}
+async function createBciStreamSession(params, options, process, sessionName) {
+    const requestId = generateClientRequestId();
+    const request = buildBciTranscribeStreamRequest(params, requestId);
+    const { requestStream, responseStream } = await duplex(request, options);
+    const responses = parseLines(responseStream, process);
+    let consumed = false;
+    return {
+        requestId,
+        write(neuralChunk) {
+            requestStream.write(neuralChunk);
+        },
+        end() {
+            requestStream.end();
+        },
+        destroy() {
+            requestStream.destroy();
+            responseStream.destroy();
+        },
+        [Symbol.asyncIterator]() {
+            if (consumed) {
+                throw new TranscriptionFailedError(`${sessionName} can only be iterated once`);
+            }
+            consumed = true;
+            return responses;
+        }
+    };
+}
+/**
+ * Line-delimited parser: reads newline-separated frames from a duplex
+ * response stream, passes each non-empty line through `process`, and yields
+ * whatever values it returns. `null` from `process` terminates the stream.
+ */
+async function* parseLines(responseStream, process) {
+    let buf = '';
+    for await (const chunk of responseStream) {
+        buf += chunk.toString();
+        const lines = buf.split('\n');
+        buf = lines.pop() || '';
+        for (const line of lines) {
+            const result = process(line);
+            if (result === null)
+                return;
+            if (result !== undefined)
+                yield result;
+        }
+    }
+    if (buf.trim()) {
+        const result = process(buf);
+        if (result !== null && result !== undefined)
+            yield result;
+    }
+}
+function parseResponseLine(line) {
+    if (!line.trim())
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        logger.warn('bciTranscribeStream: malformed JSON from server:', line);
+        return null;
+    }
+    const obj = parsed;
+    if (obj['type'] === 'error') {
+        throw new TranscriptionFailedError(obj['message'] ?? 'Unknown server error');
+    }
+    return bciTranscribeStreamResponseSchema.parse(parsed);
+}
+/**
+ * Shared wire-frame decoder. Returns `null` for the terminal `done` frame,
+ * `undefined` for frames the caller should skip, or the value extracted from
+ * the frame.
+ */
+function processWith(line, extract) {
+    const response = parseResponseLine(line);
+    if (response === null)
+        return undefined;
+    if (response.error)
+        throw new TranscriptionFailedError(response.error);
+    if (response.done)
+        return null;
+    return extract(response);
+}
+function processLine(line) {
+    return processWith(line, (response) => (response.text?.trim() ? response.text : undefined));
+}
+function processLineMetadata(line) {
+    return processWith(line, (response) => response.segment);
+}