@qvac/sdk 0.18.2 → 0.19.1

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

@@ -0,0 +1,93 @@
+import { type TranscribeClientParams, type RPCOptions, type TranscribeSegment, type TranscribeStreamRequest, type TranscribeStreamClientParams, type TranscribeStreamSession, type TranscribeStreamMetadataSession, type TranscribeStreamConversationSession, type TranscribeStats } from '@qvac/inference/surface';
+import { duplex } from '../rpc/rpc-client.js';
+type TranscribeDuplexFactory = (request: TranscribeStreamRequest, options?: RPCOptions) => ReturnType<typeof duplex>;
+/**
+ * Transcribe audio and return the complete text. Accepts either a file
+ * path or an audio buffer.
+ *
+ * @param params - Transcription parameters.
+ * @param params.modelId - The identifier of the transcription model to use
+ * @param params.audioChunk - Audio input as either a file path (string) or audio buffer
+ * @param params.prompt - Optional initial prompt to guide the transcription
+ * @param params.metadata - When true, resolves to an array of transcript
+ *                          segments (`{ text, startMs, endMs, append, id }`)
+ *                          instead of joined text. Whisper engine only.
+ * @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 transcribe(params: TranscribeClientParams & {
+    metadata: true;
+}, options?: RPCOptions): Promise<TranscribeSegment[]> & {
+    requestId: string;
+};
+export declare function transcribe(params: TranscribeClientParams, options?: RPCOptions): Promise<string> & {
+    requestId: string;
+};
+/**
+ * @deprecated Pass audio via `transcribe()` instead. This overload will be
+ * removed in the next major version.
+ *
+ * Streaming transcription with upfront audio: sends full audio, yields text
+ * chunks as they arrive.
+ *
+ * @overloadLabel "Upfront audio (deprecated)"
+ * @param params - Transcription parameters including audio source.
+ * @param options - Optional RPC options including per-call profiling.
+ * @returns An async generator yielding text chunks as they become available.
+ */
+export declare function transcribeStream(params: TranscribeClientParams & {
+    metadata: true;
+}, options?: RPCOptions): AsyncGenerator<TranscribeSegment>;
+export declare function transcribeStream(params: TranscribeClientParams, options?: RPCOptions): AsyncGenerator<string>;
+/**
+ * Opens a bidirectional streaming transcription session. Audio is streamed
+ * in via `write()`, and transcription text is yielded as the model's VAD
+ * detects complete speech segments.
+ *
+ * The returned session is single-use. Attempting to iterate a second
+ * time will throw a `TranscriptionFailedError`.
+ *
+ * @overloadLabel "Bidirectional session"
+ * @param params - Streaming transcription parameters.
+ * @param params.modelId - The loaded transcription model to use
+ * @param params.prompt - Optional initial prompt to guide transcription
+ * @param params.metadata - When true, the session yields transcript segment
+ *                          objects (`{ text, startMs, endMs, append, id }`)
+ *                          instead of plain text. Whisper engine only.
+ * @param options - Optional RPC options including per-call profiling.
+ * @returns A session object: call `write(audioChunk)` with a `Uint8Array`
+ *          (Node `Buffer` is a `Uint8Array` subtype) to feed audio,
+ *          iterate with `for await (...)` to receive transcription, and
+ *          `end()` to signal end of audio. After consuming the iterator,
+ *          await `session.stats` for terminal engine statistics.
+ */
+export declare function transcribeStream(params: TranscribeStreamClientParams & {
+    emitVadEvents: true;
+}, options?: RPCOptions): Promise<TranscribeStreamConversationSession>;
+export declare function transcribeStream(params: TranscribeStreamClientParams & {
+    parakeetStreamingConfig: NonNullable<TranscribeStreamClientParams['parakeetStreamingConfig']>;
+}, options?: RPCOptions): Promise<TranscribeStreamConversationSession>;
+export declare function transcribeStream(params: TranscribeStreamClientParams & {
+    metadata: true;
+}, options?: RPCOptions): Promise<TranscribeStreamMetadataSession>;
+export declare function transcribeStream(params: TranscribeStreamClientParams, options?: RPCOptions): Promise<TranscribeStreamSession>;
+/**
+ * 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 declare function createTranscribeStreamSession<T>(params: TranscribeStreamClientParams, options: RPCOptions | undefined, process: (line: string, onStats: (stats: TranscribeStats | undefined) => void) => T | undefined | null, sessionName: string, duplexFactory?: TranscribeDuplexFactory): Promise<{
+    stats: Promise<TranscribeStats | undefined>;
+    write(audioChunk: Uint8Array): void;
+    end(): void;
+    destroy(): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}>;
+export declare function processLine(line: string, onStats: (stats: TranscribeStats | undefined) => void): string | undefined | null;
+export {};
+//# sourceMappingURL=transcribe.d.ts.map

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

@@ -0,0 +1,295 @@
+import { transcribeResponseSchema, transcribeStreamResponseSchema } 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 { generateClientRequestId } from './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/src/client/api/translate.d.ts

@@ -0,0 +1,51 @@
+import { type TranslateClientParams, type TranslationStats, type RPCOptions } from '@qvac/inference/surface';
+/**
+ * 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 a tokenStream generator, `translations` (one entry per
+ * input, in order), `text` (those entries joined by newlines) and stats
+ * @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>;
+    translations: Promise<string[]>;
+    text: Promise<string>;
+    requestId: string;
+};
+//# sourceMappingURL=translate.d.ts.map

package/dist/src/client/api/translate.js

@@ -0,0 +1,133 @@
+import { stream as streamRpc } from '../rpc/rpc-client.js';
+import { generateClientRequestId } from './client-request-id.js';
+import { translateResponseSchema } from '@qvac/inference/surface';
+/**
+ * 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 a tokenStream generator, `translations` (one entry per
+ * input, in order), `text` (those entries joined by newlines) and stats
+ * @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);
+            }
+        })();
+        return {
+            tokenStream,
+            translations: Promise.resolve([]),
+            text: Promise.resolve(''),
+            stats: statsPromise,
+            requestId
+        };
+    }
+    else {
+        const tokenStream = (async function* () {
+            //Empty generator for non-streaming mode
+        })();
+        const batched = Array.isArray(params.text);
+        const translationsPromise = (async () => {
+            const collected = batched ? [] : [''];
+            try {
+                for await (const response of streamRpc(request, options)) {
+                    if (response.type === 'translate') {
+                        const streamResponse = translateResponseSchema.parse(response);
+                        if (streamResponse.done) {
+                            stats = streamResponse.stats;
+                            statsResolver(stats);
+                        }
+                        else if (batched) {
+                            collected.push(streamResponse.token);
+                        }
+                        else {
+                            collected[0] += streamResponse.token;
+                        }
+                    }
+                }
+            }
+            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 collected;
+        })();
+        return {
+            tokenStream,
+            translations: translationsPromise,
+            text: translationsPromise.then((entries) => entries.join('\n')),
+            stats: statsPromise,
+            requestId
+        };
+    }
+}

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

@@ -0,0 +1,18 @@
+import { type UnloadModelParams } from '@qvac/inference/surface';
+/**
+ * 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/src/client/api/unload-model.js

@@ -0,0 +1,42 @@
+import { isBare } from 'which-runtime';
+import {} from '@qvac/inference/surface';
+import { send, close } from '../rpc/rpc-client.js';
+import { stopLoggingStreamForModel } from '../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) {
+        logger.info('🧹 No models active, automatically closing RPC connection...');
+        await close();
+    }
+}

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

@@ -0,0 +1,45 @@
+import { type UpscaleClientParams, type UpscaleStats } from '@qvac/inference/surface';
+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