@qvac/sdk 0.18.2 → 0.19.1

package/dist/client/api/transcribe.js

@@ -1,295 +0,0 @@
-import { transcribeResponseSchema, transcribeStreamResponseSchema } from '../../schemas/index.js';
-import { stream, duplex } from '../../client/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 { generateClientRequestId } from '../../client/api/client-request-id.js';
-const logger = getClientLogger();
-function buildTranscribeRequest(params, requestId) {
-    return {
-        type: 'transcribe',
-        modelId: params.modelId,
-        audioChunk: typeof params.audioChunk === 'string'
-            ? { type: 'filePath', value: params.audioChunk }
-            : { type: 'base64', value: params.audioChunk.toString('base64') },
-        ...(params.prompt && { prompt: params.prompt }),
-        ...(params.metadata === true && { metadata: true }),
-        requestId
-    };
-}
-export function transcribe(params, options) {
-    // Client-generated id surfaced synchronously on the returned promise
-    // — same shape as `loadModel` / `downloadAsset` / `completion`. The
-    // CLI cancel bridge in `qvac serve` binds `req.on('close')` to
-    // `cancel({ requestId })` immediately after the call returns so a
-    // client disconnect aborts the in-flight transcription.
-    const requestId = generateClientRequestId();
-    const inner = runTranscribe(params, requestId, options);
-    return decoratePromise(inner, { requestId });
-}
-async function runTranscribe(params, requestId, options) {
-    const request = buildTranscribeRequest(params, requestId);
-    if (params.metadata === true) {
-        const segments = [];
-        for await (const response of stream(request, options)) {
-            if (response.type === 'transcribe') {
-                const parsed = transcribeResponseSchema.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 === 'transcribe') {
-            const parsed = transcribeResponseSchema.parse(response);
-            if (parsed.text) {
-                fullText += parsed.text;
-            }
-            if (parsed.done) {
-                break;
-            }
-        }
-    }
-    return fullText;
-}
-export function transcribeStream(params, options) {
-    if ('audioChunk' in params && params.audioChunk !== undefined) {
-        logger.warn('transcribeStream() with audioChunk is deprecated — use transcribe() instead.');
-        if (params.metadata === true) {
-            return transcribeStreamWithAudioMetadata(params, options);
-        }
-        return transcribeStreamWithAudio(params, options);
-    }
-    const streamParams = params;
-    if (streamParams.emitVadEvents === true || streamParams.parakeetStreamingConfig !== undefined) {
-        return transcribeStreamDuplexConversation(streamParams, options);
-    }
-    if (streamParams.metadata === true) {
-        return transcribeStreamDuplexMetadata(streamParams, options);
-    }
-    return transcribeStreamDuplex(streamParams, options);
-}
-/**
- * Streams `transcribe` wire responses for an upfront-audio request and yields
- * the value extracted from each response frame until `done` is seen.
- */
-async function* streamTranscribeValues(params, options, extract) {
-    const request = buildTranscribeRequest(params, generateClientRequestId());
-    for await (const response of stream(request, options)) {
-        if (response.type === 'transcribe') {
-            const parsed = transcribeResponseSchema.parse(response);
-            const value = extract(parsed);
-            if (value !== undefined)
-                yield value;
-            if (parsed.done)
-                break;
-        }
-    }
-}
-function transcribeStreamWithAudio(params, options) {
-    return streamTranscribeValues(params, options, (parsed) => parsed.text ? parsed.text : undefined);
-}
-function transcribeStreamWithAudioMetadata(params, options) {
-    return streamTranscribeValues(params, options, (parsed) => parsed.segment);
-}
-function buildTranscribeStreamRequest(params) {
-    return {
-        type: 'transcribeStream',
-        modelId: params.modelId,
-        ...(params.prompt && { prompt: params.prompt }),
-        ...(params.metadata === true && { metadata: true }),
-        ...(params.emitVadEvents === true && { emitVadEvents: true }),
-        ...(params.endOfTurnSilenceMs !== undefined && {
-            endOfTurnSilenceMs: params.endOfTurnSilenceMs
-        }),
-        ...(params.vadRunIntervalMs !== undefined && {
-            vadRunIntervalMs: params.vadRunIntervalMs
-        }),
-        ...(params.parakeetStreamingConfig && {
-            parakeetStreamingConfig: params.parakeetStreamingConfig
-        })
-    };
-}
-/**
- * Shared duplex session factory. The per-call line processor decides whether
- * to surface strings or segments; `sessionName` is only used to label the
- * "already iterated" error so callers see the correct session type.
- */
-export async function createTranscribeStreamSession(params, options, process, sessionName, duplexFactory = duplex) {
-    const request = buildTranscribeStreamRequest(params);
-    const { requestStream, responseStream } = await duplexFactory(request, options);
-    let statsSettled = false;
-    let resolveStatsPromise = () => { };
-    let rejectStatsPromise = () => { };
-    const stats = new Promise((resolve, reject) => {
-        resolveStatsPromise = resolve;
-        rejectStatsPromise = reject;
-    });
-    stats.catch(() => { });
-    function resolveStats(value) {
-        if (statsSettled)
-            return;
-        statsSettled = true;
-        resolveStatsPromise(value);
-    }
-    function rejectStats(error) {
-        if (statsSettled)
-            return;
-        statsSettled = true;
-        rejectStatsPromise(error);
-    }
-    function resolveEmptyStats() {
-        resolveStats(undefined);
-    }
-    function processResponse(line) {
-        return process(line, resolveStats);
-    }
-    const responses = parseLines(responseStream, processResponse, resolveEmptyStats, rejectStats);
-    let consumed = false;
-    return {
-        stats,
-        write(audioChunk) {
-            requestStream.write(audioChunk);
-        },
-        end() {
-            requestStream.end();
-        },
-        destroy() {
-            resolveStats(undefined);
-            requestStream.destroy();
-            responseStream.destroy();
-        },
-        [Symbol.asyncIterator]() {
-            if (consumed) {
-                throw new TranscriptionFailedError(`${sessionName} can only be iterated once`);
-            }
-            consumed = true;
-            return responses;
-        }
-    };
-}
-function transcribeStreamDuplex(params, options) {
-    return createTranscribeStreamSession(params, options, processLine, 'TranscribeStreamSession');
-}
-function transcribeStreamDuplexMetadata(params, options) {
-    return createTranscribeStreamSession(params, options, processLineMetadata, 'TranscribeStreamMetadataSession');
-}
-function transcribeStreamDuplexConversation(params, options) {
-    const wantsMetadata = params.metadata === true;
-    return createTranscribeStreamSession(params, options, (line, onStats) => processLineConversation(line, wantsMetadata, onStats), 'TranscribeStreamConversationSession');
-}
-/**
- * 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, onClose, onError) {
-    let buf = '';
-    try {
-        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;
-            }
-        }
-        // Process any residual data after stream ends
-        if (buf.trim()) {
-            const result = process(buf);
-            if (result !== null && result !== undefined)
-                yield result;
-        }
-    }
-    catch (error) {
-        onError(error);
-        throw error;
-    }
-    finally {
-        onClose();
-    }
-}
-function parseResponseLine(line) {
-    if (!line.trim())
-        return null;
-    let parsed;
-    try {
-        parsed = JSON.parse(line);
-    }
-    catch {
-        logger.warn('transcribeStream: malformed JSON from server:', line);
-        return null;
-    }
-    const obj = parsed;
-    if (obj['type'] === 'error') {
-        throw new TranscriptionFailedError(obj['message'] ?? 'Unknown server error');
-    }
-    return transcribeStreamResponseSchema.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, onStats) {
-    const response = parseResponseLine(line);
-    if (response === null)
-        return undefined;
-    if (response.error)
-        throw new TranscriptionFailedError(response.error);
-    if (response.done) {
-        onStats(response.stats);
-        return null;
-    }
-    return extract(response);
-}
-export function processLine(line, onStats) {
-    return processWith(line, (response) => (response.text?.trim() ? response.text : undefined), onStats);
-}
-function processLineMetadata(line, onStats) {
-    return processWith(line, (response) => response.segment, onStats);
-}
-function processLineConversation(line, wantsMetadata, onStats) {
-    return processWith(line, (response) => {
-        if (response.vad) {
-            return {
-                type: 'vad',
-                speaking: response.vad.speaking,
-                probability: response.vad.probability
-            };
-        }
-        if (response.endOfTurn) {
-            if (response.endOfTurn.source === 'whisper') {
-                return {
-                    type: 'endOfTurn',
-                    source: 'whisper',
-                    silenceDurationMs: response.endOfTurn.silenceDurationMs
-                };
-            }
-            return {
-                type: 'endOfTurn',
-                source: 'parakeet'
-            };
-        }
-        if (wantsMetadata) {
-            if (response.segment) {
-                return { type: 'segment', segment: response.segment };
-            }
-            return undefined;
-        }
-        if (response.text && response.text.trim()) {
-            return { type: 'text', text: response.text };
-        }
-        return undefined;
-    }, onStats);
-}

package/dist/client/api/translate.d.ts

@@ -1,49 +0,0 @@
-import { type TranslateClientParams, type TranslationStats, type RPCOptions } from '../../schemas/index.js';
-/**
- * Translates text from one language to another using a specified translation model.
- * Supports both NMT (Neural Machine Translation) and LLM models.
- *
- * @param params - Translation configuration object
- * @param params.modelId - The identifier of the translation model to use
- * @param params.text - The input text to translate
- * @param params.from - Source language code (optional)
- * @param params.to - Target language code
- * @param params.stream - Whether to stream tokens (true) or return complete response (false). Defaults to true.
- * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
- * @returns Object with tokenStream generator and text/stats properties
- * @throws {QvacErrorBase} When translation fails with an error message or when language detection fails
- * @example
- * ```typescript
- * // Streaming mode (default)
- * const result = translate({
- *   modelId: "modelId",
- *   text: "Hello world",
- *   from: "en",
- *   to: "es",
- *   modelType: "llm",
- * });
- *
- * for await (const token of result.tokenStream) {
- *   console.log(token);
- * }
- *
- * // Non-streaming mode
- * const response = translate({
- *   modelId: "modelId",
- *   text: "Hello world",
- *   from: "en",
- *   to: "es",
- *   modelType: "llm",
- *   stream: false,
- * });
- *
- * console.log(await response.text);
- * ```
- */
-export declare function translate(params: TranslateClientParams, options?: RPCOptions): {
-    tokenStream: AsyncGenerator<string>;
-    stats: Promise<TranslationStats | undefined>;
-    text: Promise<string>;
-    requestId: string;
-};
-//# sourceMappingURL=translate.d.ts.map

package/dist/client/api/translate.js

@@ -1,125 +0,0 @@
-import { stream as streamRpc } from '../../client/rpc/rpc-client.js';
-import { generateClientRequestId } from '../../client/api/client-request-id.js';
-import { translateResponseSchema } from '../../schemas/index.js';
-/**
- * Translates text from one language to another using a specified translation model.
- * Supports both NMT (Neural Machine Translation) and LLM models.
- *
- * @param params - Translation configuration object
- * @param params.modelId - The identifier of the translation model to use
- * @param params.text - The input text to translate
- * @param params.from - Source language code (optional)
- * @param params.to - Target language code
- * @param params.stream - Whether to stream tokens (true) or return complete response (false). Defaults to true.
- * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
- * @returns Object with tokenStream generator and text/stats properties
- * @throws {QvacErrorBase} When translation fails with an error message or when language detection fails
- * @example
- * ```typescript
- * // Streaming mode (default)
- * const result = translate({
- *   modelId: "modelId",
- *   text: "Hello world",
- *   from: "en",
- *   to: "es",
- *   modelType: "llm",
- * });
- *
- * for await (const token of result.tokenStream) {
- *   console.log(token);
- * }
- *
- * // Non-streaming mode
- * const response = translate({
- *   modelId: "modelId",
- *   text: "Hello world",
- *   from: "en",
- *   to: "es",
- *   modelType: "llm",
- *   stream: false,
- * });
- *
- * console.log(await response.text);
- * ```
- */
-export function translate(params, options) {
-    // Stable identity generated client-side so `cancel({ requestId })` works the
-    // moment we return, before the first round-trip. Surfaced on the handle.
-    const requestId = generateClientRequestId();
-    // Source-language auto-detection lives in the worker now
-    // (server/bare/ops/translate.ts): `from` is passed through when present and
-    // resolved server-side when absent, so every language binding shares one
-    // detector instead of each shipping its own.
-    const request = {
-        type: 'translate',
-        ...params,
-        requestId
-    };
-    let stats;
-    let statsResolver = () => { };
-    const statsPromise = new Promise((resolve) => {
-        statsResolver = resolve;
-    });
-    if (params.stream) {
-        const tokenStream = (async function* () {
-            try {
-                for await (const response of streamRpc(request, options)) {
-                    if (response.type === 'translate') {
-                        const streamResponse = translateResponseSchema.parse(response);
-                        if (!streamResponse.done) {
-                            yield streamResponse.token;
-                        }
-                        else {
-                            stats = streamResponse.stats;
-                            statsResolver(stats);
-                        }
-                    }
-                }
-            }
-            finally {
-                // Settle stats even if the stream ended early (cancel) or errored, so
-                // `await handle.stats` can't hang. Idempotent if already resolved.
-                statsResolver(stats);
-            }
-        })();
-        const textPromise = Promise.resolve('');
-        return {
-            tokenStream,
-            text: textPromise,
-            stats: statsPromise,
-            requestId
-        };
-    }
-    else {
-        const tokenStream = (async function* () {
-            //Empty generator for non-streaming mode
-        })();
-        const textPromise = (async () => {
-            let buffer = '';
-            try {
-                for await (const response of streamRpc(request, options)) {
-                    if (response.type === 'translate') {
-                        const streamResponse = translateResponseSchema.parse(response);
-                        buffer += streamResponse.token;
-                        if (streamResponse.done) {
-                            stats = streamResponse.stats;
-                            statsResolver(stats);
-                        }
-                    }
-                }
-            }
-            finally {
-                // Settle stats even if the stream ended early (cancel) or errored, so
-                // `await handle.stats` can't hang. Idempotent if already resolved.
-                statsResolver(stats);
-            }
-            return buffer;
-        })();
-        return {
-            tokenStream,
-            text: textPromise,
-            stats: statsPromise,
-            requestId
-        };
-    }
-}

package/dist/client/api/unload-model.d.ts

@@ -1,18 +0,0 @@
-import { type UnloadModelParams } from '../../schemas/index.js';
-/**
- * Unloads a previously loaded model from the server.
- *
- * When the last model is unloaded (no more models remain), this function
- * automatically closes the RPC connection on Node/Electron, allowing the
- * process to exit naturally without requiring manual cleanup. On Bare the
- * connection is left open by default so long-lived workers survive a routine
- * unload; pass `autoClose: true` to opt in to closing.
- *
- * @param params - The parameters for unloading the model
- * @param params.modelId - The unique identifier of the model to unload
- * @param params.clearStorage - Whether to clear the storage for the model
- * @param params.autoClose - Override the runtime-default auto-close behavior
- * @throws {QvacErrorBase} When the response type is invalid or when the unload operation fails
- */
-export declare function unloadModel(params: UnloadModelParams): Promise<void>;
-//# sourceMappingURL=unload-model.d.ts.map

package/dist/client/api/unload-model.js

@@ -1,44 +0,0 @@
-import { isBare } from 'which-runtime';
-import {} from '../../schemas/index.js';
-import { send, close } from '../../client/rpc/rpc-client.js';
-import { stopLoggingStreamForModel } from '../../client/logging-stream-registry.js';
-import { InvalidResponseError, ModelUnloadFailedError } from '../../utils/errors-client.js';
-import { getClientLogger } from '../../logging/index.js';
-const logger = getClientLogger();
-/**
- * Unloads a previously loaded model from the server.
- *
- * When the last model is unloaded (no more models remain), this function
- * automatically closes the RPC connection on Node/Electron, allowing the
- * process to exit naturally without requiring manual cleanup. On Bare the
- * connection is left open by default so long-lived workers survive a routine
- * unload; pass `autoClose: true` to opt in to closing.
- *
- * @param params - The parameters for unloading the model
- * @param params.modelId - The unique identifier of the model to unload
- * @param params.clearStorage - Whether to clear the storage for the model
- * @param params.autoClose - Override the runtime-default auto-close behavior
- * @throws {QvacErrorBase} When the response type is invalid or when the unload operation fails
- */
-export async function unloadModel(params) {
-    const request = {
-        type: 'unloadModel',
-        modelId: params.modelId,
-        clearStorage: params.clearStorage ?? false
-    };
-    const response = await send(request);
-    if (response.type !== 'unloadModel') {
-        throw new InvalidResponseError('unloadModel');
-    }
-    if (!response.success) {
-        throw new ModelUnloadFailedError(params.modelId);
-    }
-    stopLoggingStreamForModel(params.modelId);
-    const shouldAutoClose = params.autoClose ?? !isBare;
-    if (shouldAutoClose &&
-        response.hasActiveModels === false &&
-        response.hasActiveProviders === false) {
-        logger.info('🧹 No models or providers active, automatically closing RPC connection...');
-        await close();
-    }
-}

package/dist/client/api/upscale.d.ts

@@ -1,45 +0,0 @@
-import { type UpscaleClientParams, type UpscaleStats } from '../../schemas/sdcpp-config.js';
-interface UpscaleResult {
-    outputs: Promise<Uint8Array[]>;
-    stats: Promise<UpscaleStats | undefined>;
-}
-/**
- * Runs standalone ESRGAN upscaling on an arbitrary PNG/JPEG image.
- *
- * The model must have been loaded with `modelType: "diffusion"` and
- * `modelConfig.mode: "upscale"` — calling `upscale()` against a model
- * loaded in default (`mode: "diffusion"`) mode throws
- * `ModelOperationNotSupportedError` upfront.
- *
- * `outputs` always resolves to length 1: `repeats` runs N passes
- * internally and emits a single final image at `source * scale^repeats`
- * dimensions. The `Uint8Array[]` shape reserves headroom for future
- * multi-output variants.
- *
- * @param params - `{ modelId, image, repeats? }`. `image` is raw PNG/JPEG
- *   bytes; the client base64-encodes them on the wire.
- * @returns `{ outputs, stats }` — `outputs` resolves to a single-element
- *   array containing the final upscaled PNG; `stats` resolves to
- *   addon-side stats (load/upscale ms, final width/height, repeats
- *   actually executed, etc.).
- * @throws {ModelOperationNotSupportedError} If the model was not loaded
- *   with `mode: "upscale"`.
- * @throws {StreamEndedError} If the RPC stream closes without emitting a
- *   terminal `done` chunk.
- *
- * @example
- * ```ts
- * const modelId = await loadModel(REALESRGAN_X4PLUS_ANIME_6B, {
- *   modelType: "diffusion",
- *   modelConfig: { mode: "upscale", upscaler: { tile_size: 128 } },
- * });
- * const pngBytes = fs.readFileSync("input.png");
- * const { outputs, stats } = upscale({ modelId, image: pngBytes, repeats: 2 });
- * const [upscaledPng] = await outputs;
- * fs.writeFileSync("upscaled.png", upscaledPng);
- * console.log(await stats);
- * ```
- */
-export declare function upscale(params: UpscaleClientParams): UpscaleResult;
-export {};
-//# sourceMappingURL=upscale.d.ts.map

package/dist/client/api/upscale.js

@@ -1,99 +0,0 @@
-import { upscaleStreamResponseSchema } from '../../schemas/sdcpp-config.js';
-import { stream as streamRpc } from '../../client/rpc/rpc-client.js';
-import { decodeBase64, encodeBase64 } from '../../utils/encoding.js';
-import { StreamEndedError } from '../../utils/errors-client.js';
-/**
- * Runs standalone ESRGAN upscaling on an arbitrary PNG/JPEG image.
- *
- * The model must have been loaded with `modelType: "diffusion"` and
- * `modelConfig.mode: "upscale"` — calling `upscale()` against a model
- * loaded in default (`mode: "diffusion"`) mode throws
- * `ModelOperationNotSupportedError` upfront.
- *
- * `outputs` always resolves to length 1: `repeats` runs N passes
- * internally and emits a single final image at `source * scale^repeats`
- * dimensions. The `Uint8Array[]` shape reserves headroom for future
- * multi-output variants.
- *
- * @param params - `{ modelId, image, repeats? }`. `image` is raw PNG/JPEG
- *   bytes; the client base64-encodes them on the wire.
- * @returns `{ outputs, stats }` — `outputs` resolves to a single-element
- *   array containing the final upscaled PNG; `stats` resolves to
- *   addon-side stats (load/upscale ms, final width/height, repeats
- *   actually executed, etc.).
- * @throws {ModelOperationNotSupportedError} If the model was not loaded
- *   with `mode: "upscale"`.
- * @throws {StreamEndedError} If the RPC stream closes without emitting a
- *   terminal `done` chunk.
- *
- * @example
- * ```ts
- * const modelId = await loadModel(REALESRGAN_X4PLUS_ANIME_6B, {
- *   modelType: "diffusion",
- *   modelConfig: { mode: "upscale", upscaler: { tile_size: 128 } },
- * });
- * const pngBytes = fs.readFileSync("input.png");
- * const { outputs, stats } = upscale({ modelId, image: pngBytes, repeats: 2 });
- * const [upscaledPng] = await outputs;
- * fs.writeFileSync("upscaled.png", upscaledPng);
- * console.log(await stats);
- * ```
- */
-export function upscale(params) {
-    const request = {
-        modelId: params.modelId,
-        image: encodeBase64(params.image),
-        ...(params.repeats !== undefined && { repeats: params.repeats }),
-        type: 'upscaleStream'
-    };
-    let statsResolver = () => { };
-    let statsRejecter = () => { };
-    const statsPromise = new Promise((resolve, reject) => {
-        statsResolver = resolve;
-        statsRejecter = reject;
-    });
-    statsPromise.catch(() => { });
-    let outputsResolver = () => { };
-    let outputsRejecter = () => { };
-    const outputsPromise = new Promise((resolve, reject) => {
-        outputsResolver = resolve;
-        outputsRejecter = reject;
-    });
-    outputsPromise.catch(() => { });
-    const collectedBuffers = [];
-    async function processResponses() {
-        let sawDone = false;
-        try {
-            for await (const response of streamRpc(request)) {
-                if (response &&
-                    typeof response === 'object' &&
-                    'type' in response &&
-                    response.type === 'upscaleStream') {
-                    const parsed = upscaleStreamResponseSchema.parse(response);
-                    if (parsed.data) {
-                        collectedBuffers.push(decodeBase64(parsed.data));
-                    }
-                    if (parsed.done) {
-                        sawDone = true;
-                        statsResolver(parsed.stats);
-                        outputsResolver(collectedBuffers);
-                    }
-                }
-            }
-            if (!sawDone) {
-                const error = new StreamEndedError();
-                statsRejecter(error);
-                outputsRejecter(error);
-            }
-        }
-        catch (error) {
-            statsRejecter(error);
-            outputsRejecter(error);
-        }
-    }
-    void processResponses();
-    return {
-        outputs: outputsPromise,
-        stats: statsPromise
-    };
-}