@qvac/sdk 0.18.2 → 0.19.1

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

@@ -1,178 +0,0 @@
-import { type LoadModelOptions, type LoadCustomPluginModelOptions, type LoadModelDescriptorParam, type ReloadConfigOptions, type RPCOptions, type ModelDescriptor } from '../../schemas/index.js';
-/**
- * Loads a model from a descriptor; `modelType` is inferred from `modelSrc`.
- * `modelConfig` narrows per-engine when `modelSrc.engine` is a literal,
- * otherwise falls back to a permissive shape.
- *
- * @overloadLabel "From descriptor"
- * @param options - Descriptor-based load options. `modelSrc` is a
- *   `ModelDescriptor` (e.g. one of the `LLAMA_3_2_1B_INST_Q4_0`-style
- *   constants); `modelType` is inferred from it.
- * @param rpcOptions - Optional RPC options including per-call profiling.
- * @returns Promise that resolves to the loaded model ID.
- * @throws {ModelTypeRequiredError} When `modelType` cannot be inferred from `modelSrc` at runtime.
- * @example
- * ```typescript
- * await loadModel({ modelSrc: LLAMA_3_2_1B_INST_Q4_0, modelConfig: { ctx_size: 2048 } });
- * await loadModel({ modelSrc: WHISPER_TINY });
- * ```
- */
-export declare function loadModel<S extends ModelDescriptor>(options: LoadModelDescriptorParam<S>, rpcOptions?: RPCOptions): Promise<string> & {
-    requestId: string;
-};
-/**
- * Loads a machine learning model from a local path, remote URL, or Hyperdrive key.
- *
- * This function supports multiple model types: LLM (Large Language Model), Whisper (speech recognition),
- * embeddings, NMT (translation), and TTS. It can handle both local file paths and Hyperdrive URLs (pear://).
- *
- * When `onProgress` is provided, the function uses streaming to provide real-time download progress.
- * Otherwise, it uses a simple request-response pattern for faster execution.
- *
- * @overloadLabel "Load new model"
- * @param options - An object that defines all configuration parameters required for loading the model, including:
- *   - modelSrc: The location from which the model weights are fetched (local path, remote URL, or Hyperdrive URL)
- *   - modelType: The canonical type of model ("llamacpp-completion",
- *     "whispercpp-transcription", "llamacpp-embedding", "nmtcpp-translation",
- *     "tts-ggml", ...). May be omitted when `modelSrc` is a registry descriptor
- *     that already carries the engine.
- *   - modelConfig: Model-specific configuration options (companion sources, model parameters, etc.)
- *   - fallbackSrc: For a built-in catalog model, an HTTP URL or local file path to load from when the registry is unreachable (validated against the model checksum)
- *   - onProgress: Callback for download progress updates
- *   - logger: Logger instance for model operation logs
- * @param rpcOptions - Optional RPC options including per-call profiling configuration
- *
- * @returns Promise that resolves to the model ID (either the provided modelSrc or a generated ID)
- *
- * @throws {QvacErrorBase} When model loading fails, with details in the error message
- * @throws {QvacErrorBase} When streaming ends unexpectedly (only when using onProgress)
- * @throws {QvacErrorBase} When receiving an invalid response type from the server
- *
- * @example
- * ```typescript
- * // Local file path - absolute path
- * const localModelId = await loadModel({
- *   modelSrc: "/home/user/models/llama-7b.gguf",
- *   modelType: "llamacpp-completion",
- *   modelConfig: { ctx_size: 2048 }
- * });
- *
- * // Local file path - relative path
- * const relativeModelId = await loadModel({
- *   modelSrc: "./models/whisper-base.gguf",
- *   modelType: "whispercpp-transcription"
- * });
- *
- * // Hyperdrive URL with key and path
- * const hyperdriveId = await loadModel({
- *   modelSrc: "pear://<hyperdrive-key>/llama-7b.gguf",
- *   modelType: "llamacpp-completion",
- *   modelConfig: { ctx_size: 2048 }
- * });
- *
- * // Remote HTTP/HTTPS URL with progress tracking
- * const remoteId = await loadModel({
- *   modelSrc: "https://huggingface.co/TheBloke/Llama-2-7B-Chat-GGUF/resolve/main/llama-2-7b-chat.Q4_K_M.gguf",
- *   modelType: "llamacpp-completion",
- *   onProgress: (progress) => {
- *     console.log(`Downloaded: ${progress.percentage}%`);
- *   }
- * });
- *
- * // Multimodal model with projection
- * const multimodalId = await loadModel({
- *   modelSrc: "https://huggingface.co/.../main-model.gguf",
- *   modelType: "llamacpp-completion",
- *   modelConfig: {
- *     ctx_size: 512,
- *     projectionModelSrc: "https://huggingface.co/.../projection-model.gguf"
- *   },
- *   onProgress: (progress) => {
- *     console.log(`Loading: ${progress.percentage}%`);
- *   }
- * });
- *
- * // Whisper with VAD model
- * const whisperId = await loadModel({
- *   modelSrc: "https://huggingface.co/.../whisper-model.gguf",
- *   modelType: "whispercpp-transcription",
- *   modelConfig: {
- *     mode: "caption",
- *     output_format: "plaintext",
- *     min_seconds: 2,
- *     max_seconds: 6,
- *     vadModelSrc: "https://huggingface.co/.../vad-model.bin"
- *   }
- * });
- *
- * // Load with automatic logging - logs from the model will be forwarded to your logger
- * import { getLogger } from "../../logging/index.js";
- * const logger = getLogger("my-app");
- *
- * const modelId = await loadModel({
- *   modelSrc: "/path/to/model.gguf",
- *   modelType: "llamacpp-completion",
- *   logger // Pass logger in options
- * });
- *
- * // Catalog model with an alternate source used when the registry is unreachable
- * import { LLAMA_3_2_1B_INST_Q4_0 } from "@qvac/sdk";
- * const resilientId = await loadModel({
- *   modelSrc: LLAMA_3_2_1B_INST_Q4_0,
- *   fallbackSrc: "https://mirror.example.com/llama-3.2-1b-instruct-q4_0.gguf"
- * });
- * ```
- */
-export declare function loadModel(options: LoadModelOptions, rpcOptions?: RPCOptions): Promise<string> & {
-    requestId: string;
-};
-/**
- * Loads a custom plugin model (any non-built-in `modelType` string).
- * `modelConfig` is plugin-defined; the SDK does not narrow it.
- *
- * @overloadLabel "Custom plugin"
- * @param options - Custom plugin load options. `modelType` can be any
- *   string registered by a plugin; `modelConfig` is forwarded to the
- *   plugin's `loadModel` handler unchanged.
- * @param rpcOptions - Optional RPC options including per-call profiling.
- * @returns Promise that resolves to the loaded model ID.
- */
-export declare function loadModel<T extends string>(options: LoadCustomPluginModelOptions<T>, rpcOptions?: RPCOptions): Promise<string> & {
-    requestId: string;
-};
-/**
- * Hot-reloads configuration on an already loaded model.
- *
- * @overloadLabel "Hot-reload config"
- * @param options - Configuration for reloading config on an existing model:
- *   - modelId: The ID of an existing loaded model
- *   - modelType: The type of model (must match the loaded model)
- *   - modelConfig: New configuration to apply
- * @param rpcOptions - Optional RPC options including per-call profiling configuration
- *
- * @returns Promise that resolves to the model ID
- *
- * @throws {QvacErrorBase} When model reload fails, with details in the error message
- * @throws {QvacErrorBase} When receiving an invalid response type from the server
- *
- * @example
- * ```typescript
- * // Load new model
- * const modelId = await loadModel({
- *   modelSrc: "pear://<hyperdrive-key>/whisper-tiny.gguf",
- *   modelType: "whisper",
- *   modelConfig: { language: "en" },
- * });
- *
- * // Later, update the config without reloading the model
- * await loadModel({
- *   modelId,
- *   modelType: "whisper",
- *   modelConfig: { language: "es" },
- * });
- * ```
- */
-export declare function loadModel(options: ReloadConfigOptions, rpcOptions?: RPCOptions): Promise<string> & {
-    requestId: string;
-};
-//# sourceMappingURL=load-model.d.ts.map

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

@@ -1,130 +0,0 @@
-import { send, stream } from '../../client/rpc/rpc-client.js';
-import { startLoggingStreamForModel } from '../../client/logging-stream-registry.js';
-import { loadBuiltinToRequestSchema, loadCustomPluginToRequestSchema, reloadConfigOptionsToRequestSchema, isBuiltInModelType, isModelTypeAlias, normalizeModelType, inferModelTypeFromModelSrc, ModelType } from '../../schemas/index.js';
-import { ModelLoadFailedError, ModelTypeRequiredError, StreamEndedError, InvalidResponseError } from '../../utils/errors-client.js';
-import { assertModelSrcMatchesModelType } from '../../utils/load-model-validation.js';
-import { parseClientInput } from '../../client/parse-input.js';
-import { getClientLogger } from '../../logging/index.js';
-import { decoratePromise } from '../../utils/decorate-promise.js';
-import { generateClientRequestId } from '../../client/api/client-request-id.js';
-const logger = getClientLogger();
-function isReactNativeRuntime() {
-    const runtime = globalThis;
-    return runtime.navigator?.product === 'ReactNative';
-}
-let warnedLocalVideoModelLoad = false;
-export function loadModel(options, rpcOptions) {
-    // Generate a stable `requestId` once, synchronously, before kicking
-    // off any async work. The same id is:
-    //   - threaded onto the request envelope (`request.requestId`) so the
-    //     server's `registry.begin(...)` records it on the registry
-    //     entry; and
-    //   - attached to the returned promise via `decoratePromise` so the
-    //     caller can target this exact call with `cancel({ requestId })`
-    //     before `await` resolves. Generating client-side and surfacing
-    //     it synchronously is what closes the "stop-button race" gap for
-    //     `loadModel` / `downloadAsset` callers — same shape as the
-    //     `CompletionRun.requestId` contract.
-    const requestId = generateClientRequestId();
-    const inner = runLoadModel(options, requestId, rpcOptions);
-    return decoratePromise(inner, { requestId });
-}
-async function runLoadModel(options, requestId, rpcOptions) {
-    const isReloadConfig = 'modelId' in options && !('modelSrc' in options);
-    // Infer `modelType` from `modelSrc` when omitted; the schema still validates
-    // the resolved options below.
-    let resolvedOptions = options;
-    if (!isReloadConfig) {
-        let modelType = resolvedOptions['modelType'];
-        if (typeof modelType === 'string') {
-            assertModelSrcMatchesModelType(resolvedOptions['modelSrc'], modelType);
-        }
-        else if (modelType === undefined) {
-            const inferred = inferModelTypeFromModelSrc(resolvedOptions['modelSrc']);
-            if (!inferred) {
-                throw new ModelTypeRequiredError();
-            }
-            resolvedOptions = { ...resolvedOptions, modelType: inferred };
-            modelType = inferred;
-        }
-        if (typeof modelType === 'string' && isModelTypeAlias(modelType)) {
-            const canonical = normalizeModelType(modelType);
-            logger.warn(`Model type "${modelType}" is an alias and will be deprecated. Use "${canonical}" instead.`);
-        }
-        const canonicalModelType = typeof modelType === 'string' ? normalizeModelType(modelType) : modelType;
-        const modelConfig = resolvedOptions['modelConfig'];
-        if (isReactNativeRuntime() &&
-            canonicalModelType === ModelType.sdcppGeneration &&
-            modelConfig?.mode === 'video' &&
-            resolvedOptions['delegate'] === undefined &&
-            !warnedLocalVideoModelLoad) {
-            warnedLocalVideoModelLoad = true;
-            const message = 'QVAC video generation works on React Native, but loading the video ' +
-                'model on-device will usually fail or take several minutes — the video ' +
-                'diffusion models currently shipped by the SDK are too large to load ' +
-                'on typical mobile devices. Pass a `delegate` to `loadModel(...)` to ' +
-                'run generation on a desktop peer instead.';
-            logger.warn(message);
-        }
-    }
-    // Splice the client-generated `requestId` onto the resolved options so
-    // the wire envelope carries it. The server uses the same value as the
-    // registry-entry key — that match is what makes
-    // `cancel({ requestId: op.requestId })` a no-op when no match exists
-    // and a precise abort when it does.
-    resolvedOptions = { ...resolvedOptions, requestId };
-    const request = isReloadConfig
-        ? parseClientInput(reloadConfigOptionsToRequestSchema, resolvedOptions)
-        : isBuiltInModelType(resolvedOptions['modelType'])
-            ? parseClientInput(loadBuiltinToRequestSchema, resolvedOptions)
-            : parseClientInput(loadCustomPluginToRequestSchema, resolvedOptions);
-    const modelLogger = isReloadConfig
-        ? undefined
-        : resolvedOptions['logger'];
-    const onProgress = isReloadConfig
-        ? undefined
-        : resolvedOptions['onProgress'];
-    if (onProgress) {
-        // Use streaming for progress updates
-        for await (const response of stream(request, rpcOptions)) {
-            if (response.type === 'modelProgress') {
-                onProgress(response);
-            }
-            else if (response.type === 'loadModel') {
-                if (!response.success) {
-                    throw new ModelLoadFailedError(response.error);
-                }
-                const modelId = response.modelId;
-                // Start logging stream in the background if logger is provided, catch to avoid failing the entire loadModel operation
-                if (modelLogger) {
-                    try {
-                        startLoggingStreamForModel(modelId, modelLogger);
-                    }
-                    catch (error) {
-                        logger.warn(`Failed to start logging stream for model ${modelId}:`, error);
-                    }
-                }
-                return modelId;
-            }
-        }
-        throw new StreamEndedError();
-    }
-    // Use regular send for simple loading
-    const response = await send(request, rpcOptions);
-    if (response.type !== 'loadModel') {
-        throw new InvalidResponseError('loadModel');
-    }
-    if (!response.success) {
-        throw new ModelLoadFailedError(response.error);
-    }
-    const modelId = response.modelId;
-    if (modelLogger) {
-        try {
-            startLoggingStreamForModel(modelId, modelLogger);
-        }
-        catch (error) {
-            logger.warn(`Failed to start logging stream for model ${modelId}:`, error);
-        }
-    }
-    return modelId;
-}

package/dist/client/api/logging-stream.d.ts

@@ -1,24 +0,0 @@
-import type { LoggingStreamResponse, LoggingParams } from '../../schemas/logging-stream.js';
-/**
- * Opens a logging stream to receive real-time logs.
- *
- * @param params - The arguments for the logging stream
- * @param params.id - The unique identifier to stream logs for
- * @returns AsyncGenerator yielding logging stream responses
- * @throws {QvacErrorBase} When the response type is invalid or when the stream fails
- *
- * @example
- * ```typescript
- * // Open a logging stream for a model
- * const logStream = loggingStream({ id: 'my-model-id' });
- *
- * // Or stream SDK server logs
- * const sdkLogs = loggingStream({ id: SDK_LOG_ID });
- *
- * for await (const logMessage of logStream) {
- *   console.log(`[${logMessage.level}] ${logMessage.namespace}: ${logMessage.message}`);
- * }
- * ```
- */
-export declare function loggingStream(params: LoggingParams): AsyncGenerator<LoggingStreamResponse>;
-//# sourceMappingURL=logging-stream.d.ts.map

package/dist/client/api/logging-stream.js

@@ -1,36 +0,0 @@
-import { stream } from '../../client/rpc/rpc-client.js';
-import { InvalidResponseError } from '../../utils/errors-client.js';
-/**
- * Opens a logging stream to receive real-time logs.
- *
- * @param params - The arguments for the logging stream
- * @param params.id - The unique identifier to stream logs for
- * @returns AsyncGenerator yielding logging stream responses
- * @throws {QvacErrorBase} When the response type is invalid or when the stream fails
- *
- * @example
- * ```typescript
- * // Open a logging stream for a model
- * const logStream = loggingStream({ id: 'my-model-id' });
- *
- * // Or stream SDK server logs
- * const sdkLogs = loggingStream({ id: SDK_LOG_ID });
- *
- * for await (const logMessage of logStream) {
- *   console.log(`[${logMessage.level}] ${logMessage.namespace}: ${logMessage.message}`);
- * }
- * ```
- */
-export async function* loggingStream(params) {
-    const request = {
-        type: 'loggingStream',
-        ...params
-    };
-    const responseStream = stream(request);
-    for await (const response of responseStream) {
-        if (response.type !== 'loggingStream') {
-            throw new InvalidResponseError('loggingStream');
-        }
-        yield response;
-    }
-}

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

@@ -1,40 +0,0 @@
-import { type OCRClientParams, type OCRTextBlock, type OCRStats } from '../../schemas/index.js';
-/**
- * Performs Optical Character Recognition (OCR) on an image to extract text.
- *
- * @param params - The OCR parameters
- * @param params.modelId - The identifier of the loaded OCR model to use
- * @param params.image - Image input as either a file path (string) or image buffer
- * @param params.options - Optional OCR options (e.g., paragraph mode)
- * @param params.stream - Whether to stream blocks as they're detected (true) or return all at once (false). Defaults to false
- * @returns Object with blockStream generator, blocks promise, and stats promise
- * @example
- * ```typescript
- * // Load an OCR model first. Registry GGUF models resolve their pipeline
- * // and detector automatically:
- * //   EasyOCR (default): OCR_LATIN  (CRAFT detector auto-derived)
- * //   DocTR:             OCR_DOCTR  (DBNet detector auto-derived)
- * const modelId = await loadModel({
- *   modelSrc: OCR_LATIN.src,
- *   modelType: MODEL_TYPES.ggmlOcr,
- * });
- *
- * // Non-streaming mode (default) - get all blocks at once
- * const { blocks } = ocr({ modelId, image: "/path/to/image.png" });
- * for (const block of await blocks) {
- *   console.log(block.text, block.bbox, block.confidence);
- * }
- *
- * // Streaming mode - process blocks as they arrive
- * const { blockStream } = ocr({ modelId, image: imageBuffer, stream: true });
- * for await (const blocks of blockStream) {
- *   console.log("Detected:", blocks);
- * }
- * ```
- */
-export declare function ocr(params: OCRClientParams): {
-    blockStream: AsyncGenerator<OCRTextBlock[]>;
-    blocks: Promise<OCRTextBlock[]>;
-    stats: Promise<OCRStats | undefined>;
-};
-//# sourceMappingURL=ocr.d.ts.map

package/dist/client/api/ocr.js

@@ -1,97 +0,0 @@
-import { ocrStreamResponseSchema } from '../../schemas/index.js';
-import { stream as streamRpc } from '../../client/rpc/rpc-client.js';
-/**
- * Performs Optical Character Recognition (OCR) on an image to extract text.
- *
- * @param params - The OCR parameters
- * @param params.modelId - The identifier of the loaded OCR model to use
- * @param params.image - Image input as either a file path (string) or image buffer
- * @param params.options - Optional OCR options (e.g., paragraph mode)
- * @param params.stream - Whether to stream blocks as they're detected (true) or return all at once (false). Defaults to false
- * @returns Object with blockStream generator, blocks promise, and stats promise
- * @example
- * ```typescript
- * // Load an OCR model first. Registry GGUF models resolve their pipeline
- * // and detector automatically:
- * //   EasyOCR (default): OCR_LATIN  (CRAFT detector auto-derived)
- * //   DocTR:             OCR_DOCTR  (DBNet detector auto-derived)
- * const modelId = await loadModel({
- *   modelSrc: OCR_LATIN.src,
- *   modelType: MODEL_TYPES.ggmlOcr,
- * });
- *
- * // Non-streaming mode (default) - get all blocks at once
- * const { blocks } = ocr({ modelId, image: "/path/to/image.png" });
- * for (const block of await blocks) {
- *   console.log(block.text, block.bbox, block.confidence);
- * }
- *
- * // Streaming mode - process blocks as they arrive
- * const { blockStream } = ocr({ modelId, image: imageBuffer, stream: true });
- * for await (const blocks of blockStream) {
- *   console.log("Detected:", blocks);
- * }
- * ```
- */
-export function ocr(params) {
-    const request = {
-        type: 'ocrStream',
-        modelId: params.modelId,
-        image: typeof params.image === 'string'
-            ? { type: 'filePath', value: params.image }
-            : { type: 'base64', value: params.image.toString('base64') },
-        ...(params.options && { options: params.options })
-    };
-    let ocrStats;
-    let statsResolver = () => { };
-    const statsPromise = new Promise((resolve) => {
-        statsResolver = resolve;
-    });
-    if (params.stream) {
-        const blockStream = (async function* () {
-            for await (const response of streamRpc(request)) {
-                if (response.type === 'ocrStream') {
-                    const streamResponse = ocrStreamResponseSchema.parse(response);
-                    if (streamResponse.blocks && streamResponse.blocks.length > 0) {
-                        yield streamResponse.blocks;
-                    }
-                    if (streamResponse.done) {
-                        ocrStats = streamResponse.stats;
-                        statsResolver(ocrStats);
-                    }
-                }
-            }
-        })();
-        return {
-            blockStream,
-            blocks: Promise.resolve([]),
-            stats: statsPromise
-        };
-    }
-    else {
-        const blockStream = (async function* () {
-            // Empty generator for non-streaming mode
-        })();
-        const blocksPromise = (async () => {
-            let allBlocks = [];
-            for await (const response of streamRpc(request)) {
-                if (response.type === 'ocrStream') {
-                    const streamResponse = ocrStreamResponseSchema.parse(response);
-                    if (streamResponse.blocks) {
-                        allBlocks = allBlocks.concat(streamResponse.blocks);
-                    }
-                    if (streamResponse.done) {
-                        ocrStats = streamResponse.stats;
-                        statsResolver(ocrStats);
-                    }
-                }
-            }
-            return allBlocks;
-        })();
-        return {
-            blockStream,
-            blocks: blocksPromise,
-            stats: statsPromise
-        };
-    }
-}

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

@@ -1,24 +0,0 @@
-import { type ProvideParams } from '../../schemas/index.js';
-/**
- * Starts a provider service that offers QVAC capabilities to remote peers.
- *
- * Consumers connect directly to the provider via its public key using
- * `dht.connect(publicKey)`, so no topic or discovery configuration is needed.
- * The provider's keypair (and therefore its public key) can be controlled via
- * the `QVAC_HYPERSWARM_SEED` environment variable.
- *
- * Idempotent: calling more than once while a provider is already running
- * returns the same public key without re-listening on the DHT.
- *
- * @param params - Options object with optional firewall config
- * @param params.firewall - Optional firewall configuration to allow/deny specific public keys
- * @returns A promise that resolves to the provide response containing success status and public key
- * @throws {QvacErrorBase} When the response type is not "provide" or the request fails
- */
-export declare function startQVACProvider(params?: ProvideParams): Promise<{
-    type: "provide";
-    success: boolean;
-    error?: string | undefined;
-    publicKey?: string | undefined;
-}>;
-//# sourceMappingURL=provide.d.ts.map

package/dist/client/api/provide.js

@@ -1,33 +0,0 @@
-import {} from '../../schemas/index.js';
-import { send } from '../../client/rpc/rpc-client.js';
-import { InvalidResponseError, ProviderStartFailedError } from '../../utils/errors-client.js';
-/**
- * Starts a provider service that offers QVAC capabilities to remote peers.
- *
- * Consumers connect directly to the provider via its public key using
- * `dht.connect(publicKey)`, so no topic or discovery configuration is needed.
- * The provider's keypair (and therefore its public key) can be controlled via
- * the `QVAC_HYPERSWARM_SEED` environment variable.
- *
- * Idempotent: calling more than once while a provider is already running
- * returns the same public key without re-listening on the DHT.
- *
- * @param params - Options object with optional firewall config
- * @param params.firewall - Optional firewall configuration to allow/deny specific public keys
- * @returns A promise that resolves to the provide response containing success status and public key
- * @throws {QvacErrorBase} When the response type is not "provide" or the request fails
- */
-export async function startQVACProvider(params = {}) {
-    const request = {
-        type: 'provide',
-        firewall: params.firewall
-    };
-    const response = await send(request);
-    if (response.type !== 'provide') {
-        throw new InvalidResponseError('provide');
-    }
-    if (response.error) {
-        throw new ProviderStartFailedError(response.error);
-    }
-    return response;
-}