@qvac/sdk 0.18.1 → 0.19.0

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

@@ -0,0 +1,144 @@
+import { send, stream as streamRpc } from '../rpc/rpc-client.js';
+import { finetuneRunParamsSchema, finetuneRunRequestSchema, finetuneStopRequestSchema, finetuneGetStateParamsSchema, finetuneGetStateRequestSchema, finetuneProgressResponseSchema, finetuneResponseSchema } from '@qvac/inference/surface';
+import { InvalidResponseError, StreamEndedError } from '../../utils/errors-client.js';
+import { parseClientInput } from '../parse-input.js';
+import { generateClientRequestId } from './client-request-id.js';
+function isFinetuneReplyParams(params) {
+    return (params.operation === 'pause' || params.operation === 'cancel' || params.operation === 'getState');
+}
+function createFinetuneReplyRequest(params) {
+    if (params.operation === 'getState') {
+        const getStateParams = parseClientInput(finetuneGetStateParamsSchema, params);
+        return parseClientInput(finetuneGetStateRequestSchema, {
+            type: 'finetune',
+            ...getStateParams
+        });
+    }
+    return parseClientInput(finetuneStopRequestSchema, {
+        type: 'finetune',
+        modelId: params.modelId,
+        operation: params.operation
+    });
+}
+export function finetune(params, rpcOptions) {
+    if (isFinetuneReplyParams(params)) {
+        const request = createFinetuneReplyRequest(params);
+        const resultPromise = (async () => {
+            const response = await send(request, rpcOptions);
+            if (!response ||
+                typeof response !== 'object' ||
+                !('type' in response) ||
+                response.type !== 'finetune') {
+                throw new InvalidResponseError('finetune');
+            }
+            return finetuneResponseSchema.parse(response);
+        })();
+        resultPromise.catch(() => { });
+        return resultPromise;
+    }
+    const runParams = parseClientInput(finetuneRunParamsSchema, params);
+    // Client-side id so the run is cancellable via cancel({ requestId }) the
+    // moment the handle is returned. Surfaced on the handle below.
+    const requestId = generateClientRequestId();
+    let resultResolver = () => { };
+    let resultRejecter = () => { };
+    const resultPromise = new Promise((resolve, reject) => {
+        resultResolver = resolve;
+        resultRejecter = reject;
+    });
+    resultPromise.catch(() => { });
+    const progressQueue = [];
+    let progressDone = false;
+    let progressResolve = null;
+    let streamError = null;
+    const processResponses = async () => {
+        try {
+            let sawTerminalResponse = false;
+            const request = parseClientInput(finetuneRunRequestSchema, {
+                type: 'finetune',
+                ...runParams,
+                requestId,
+                withProgress: true
+            });
+            const responses = streamRpc(request, rpcOptions);
+            for await (const response of responses) {
+                if (response &&
+                    typeof response === 'object' &&
+                    'type' in response &&
+                    response.type === 'finetune:progress') {
+                    const progressResponse = finetuneProgressResponseSchema.parse(response);
+                    progressQueue.push({
+                        is_train: progressResponse.is_train,
+                        loss: progressResponse.loss,
+                        loss_uncertainty: progressResponse.loss_uncertainty,
+                        accuracy: progressResponse.accuracy,
+                        accuracy_uncertainty: progressResponse.accuracy_uncertainty,
+                        global_steps: progressResponse.global_steps,
+                        current_epoch: progressResponse.current_epoch,
+                        current_batch: progressResponse.current_batch,
+                        total_batches: progressResponse.total_batches,
+                        elapsed_ms: progressResponse.elapsed_ms,
+                        eta_ms: progressResponse.eta_ms
+                    });
+                    if (progressResolve) {
+                        progressResolve();
+                        progressResolve = null;
+                    }
+                    continue;
+                }
+                if (response &&
+                    typeof response === 'object' &&
+                    'type' in response &&
+                    response.type === 'finetune') {
+                    sawTerminalResponse = true;
+                    const finetuneResponse = finetuneResponseSchema.parse(response);
+                    resultResolver(finetuneResponse);
+                    progressDone = true;
+                    if (progressResolve) {
+                        progressResolve();
+                        progressResolve = null;
+                    }
+                }
+                else {
+                    throw new InvalidResponseError('finetune');
+                }
+            }
+            if (!sawTerminalResponse) {
+                throw new StreamEndedError();
+            }
+        }
+        catch (error) {
+            streamError = error instanceof Error ? error : new Error(String(error));
+            resultRejecter(error);
+            progressDone = true;
+            if (progressResolve) {
+                progressResolve();
+                progressResolve = null;
+            }
+        }
+    };
+    void processResponses();
+    const progressStream = (async function* () {
+        while (true) {
+            if (progressQueue.length > 0) {
+                yield progressQueue.shift();
+            }
+            else if (progressDone) {
+                if (streamError !== null) {
+                    throw streamError;
+                }
+                break;
+            }
+            else {
+                await new Promise((resolve) => {
+                    progressResolve = resolve;
+                });
+            }
+        }
+    })();
+    return {
+        progressStream,
+        result: resultPromise,
+        requestId
+    };
+}

package/dist/src/client/api/get-loaded-model-info.d.ts

@@ -0,0 +1,26 @@
+import { type GetLoadedModelInfoParams, type LoadedModelInfo, type RPCOptions } from '@qvac/inference/surface';
+/**
+ * Returns introspection info for a loaded `modelId`.
+ *
+ * `info.modelType` and `info.handlers` are authoritative. Use them to preflight
+ * an SDK call before sending the actual RPC, e.g. confirm that a model supports
+ * `transcribeStream` before calling `transcribe()`.
+ *
+ * Throws `ModelNotFoundError` if no entry exists for `modelId`.
+ *
+ * @param params - The identifier of the loaded model to inspect.
+ * @param rpcOptions - Optional timeout, profiling, and connection settings.
+ * @returns The model's handler metadata.
+ * @throws {InvalidResponseError} When the worker returns an unexpected response.
+ * @throws {ModelNotFoundError} When no loaded model has the requested ID.
+ *
+ * @example
+ * ```typescript
+ * const info = await getLoadedModelInfo({ modelId });
+ * if (info.handlers.includes("completionStream")) {
+ *   // safe to call completion()
+ * }
+ * ```
+ */
+export declare function getLoadedModelInfo(params: GetLoadedModelInfoParams, rpcOptions?: RPCOptions): Promise<LoadedModelInfo>;
+//# sourceMappingURL=get-loaded-model-info.d.ts.map

package/dist/src/client/api/get-loaded-model-info.js

@@ -0,0 +1,37 @@
+import {} from '@qvac/inference/surface';
+import { send } from '../rpc/rpc-client.js';
+import { InvalidResponseError } from '../../utils/errors-client.js';
+/**
+ * Returns introspection info for a loaded `modelId`.
+ *
+ * `info.modelType` and `info.handlers` are authoritative. Use them to preflight
+ * an SDK call before sending the actual RPC, e.g. confirm that a model supports
+ * `transcribeStream` before calling `transcribe()`.
+ *
+ * Throws `ModelNotFoundError` if no entry exists for `modelId`.
+ *
+ * @param params - The identifier of the loaded model to inspect.
+ * @param rpcOptions - Optional timeout, profiling, and connection settings.
+ * @returns The model's handler metadata.
+ * @throws {InvalidResponseError} When the worker returns an unexpected response.
+ * @throws {ModelNotFoundError} When no loaded model has the requested ID.
+ *
+ * @example
+ * ```typescript
+ * const info = await getLoadedModelInfo({ modelId });
+ * if (info.handlers.includes("completionStream")) {
+ *   // safe to call completion()
+ * }
+ * ```
+ */
+export async function getLoadedModelInfo(params, rpcOptions) {
+    const request = {
+        type: 'getLoadedModelInfo',
+        modelId: params.modelId
+    };
+    const response = await send(request, rpcOptions);
+    if (response.type !== 'getLoadedModelInfo') {
+        throw new InvalidResponseError('getLoadedModelInfo');
+    }
+    return response.info;
+}

package/dist/src/client/api/get-model-info.d.ts

@@ -0,0 +1,11 @@
+import { type GetModelInfoParams, type ModelInfo } from '@qvac/inference/surface';
+/**
+ * Returns status information for a catalog model, including cache state and loaded instances.
+ *
+ * @param params - Query parameters.
+ * @param params.name - The model's registry name (as found in the SDK's built-in catalog) to look up.
+ * @returns A promise resolving to the model's status information (cache presence, loaded instances, size on disk, etc.).
+ * @throws {QvacErrorBase} When the response type is invalid (`InvalidResponseError`) or the RPC layer fails.
+ */
+export declare function getModelInfo(params: GetModelInfoParams): Promise<ModelInfo>;
+//# sourceMappingURL=get-model-info.d.ts.map

package/dist/src/client/api/get-model-info.js

@@ -0,0 +1,22 @@
+import {} from '@qvac/inference/surface';
+import { send } from '../rpc/rpc-client.js';
+import { InvalidResponseError } from '../../utils/errors-client.js';
+/**
+ * Returns status information for a catalog model, including cache state and loaded instances.
+ *
+ * @param params - Query parameters.
+ * @param params.name - The model's registry name (as found in the SDK's built-in catalog) to look up.
+ * @returns A promise resolving to the model's status information (cache presence, loaded instances, size on disk, etc.).
+ * @throws {QvacErrorBase} When the response type is invalid (`InvalidResponseError`) or the RPC layer fails.
+ */
+export async function getModelInfo(params) {
+    const request = {
+        type: 'getModelInfo',
+        name: params.name
+    };
+    const response = await send(request);
+    if (response.type !== 'getModelInfo') {
+        throw new InvalidResponseError('getModelInfo');
+    }
+    return response.modelInfo;
+}

package/dist/src/client/api/get-system-resources.d.ts

@@ -0,0 +1,3 @@
+import { type GetSystemResourcesInput, type SystemResources } from '@qvac/inference/surface';
+export declare function getSystemResources(input?: GetSystemResourcesInput): Promise<SystemResources>;
+//# sourceMappingURL=get-system-resources.d.ts.map

package/dist/src/client/api/get-system-resources.js

@@ -0,0 +1,17 @@
+import {} from '@qvac/inference/surface';
+import { send } from '../rpc/rpc-client.js';
+import { InvalidResponseError } from '../../utils/errors-client.js';
+export async function getSystemResources(input) {
+    const request = {
+        type: 'getSystemResources',
+        ...(input?.sample !== undefined && { sample: input.sample })
+    };
+    const response = await send(request);
+    if (response.type !== 'getSystemResources') {
+        throw new InvalidResponseError('getSystemResources');
+    }
+    return {
+        capabilities: response.capabilities,
+        ...(response.sample && { sample: response.sample })
+    };
+}

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

@@ -0,0 +1,13 @@
+import { type HeartbeatResponse } from '@qvac/inference/surface';
+/**
+ * Checks whether the local SDK worker is responsive by sending a heartbeat
+ * round-trip.
+ *
+ * @returns A promise that resolves to a heartbeat response.
+ * @throws {QvacErrorBase} When the response is invalid.
+ *
+ * @example
+ * await heartbeat();
+ */
+export declare function heartbeat(): Promise<HeartbeatResponse>;
+//# sourceMappingURL=heartbeat.d.ts.map

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

@@ -0,0 +1,21 @@
+import {} from '@qvac/inference/surface';
+import { send } from '../rpc/rpc-client.js';
+import { InvalidResponseError } from '../../utils/errors-client.js';
+/**
+ * Checks whether the local SDK worker is responsive by sending a heartbeat
+ * round-trip.
+ *
+ * @returns A promise that resolves to a heartbeat response.
+ * @throws {QvacErrorBase} When the response is invalid.
+ *
+ * @example
+ * await heartbeat();
+ */
+export async function heartbeat() {
+    const request = { type: 'heartbeat' };
+    const response = await send(request);
+    if (response.type !== 'heartbeat') {
+        throw new InvalidResponseError('heartbeat');
+    }
+    return response;
+}

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

@@ -0,0 +1,37 @@
+export { loadModel } from './load-model.js';
+export { downloadAsset } from './download-asset.js';
+export { batchCompletion } from './batch-completion.js';
+export { completion } from './completion-stream.js';
+export { deleteCache } from './delete-cache.js';
+export { unloadModel } from './unload-model.js';
+export { loggingStream } from './logging-stream.js';
+export { subscribeServerLogs, type ServerLogHandler } from './subscribe-logs.js';
+export { heartbeat } from './heartbeat.js';
+export { transcribe, transcribeStream } from './transcribe.js';
+export { bciTranscribe, bciTranscribeStream } from './bci-transcribe.js';
+export { embed } from './embed.js';
+export { finetune, type FinetuneHandle } from './finetune.js';
+export { translate } from './translate.js';
+export { cancel } from './cancel.js';
+export { ragChunk, ragIngest, ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings, ragReindex, ragListWorkspaces, ragCloseWorkspace, ragDeleteWorkspace } from './rag.js';
+export { textToSpeech, textToSpeechStream } from './text-to-speech.js';
+export { getModelInfo } from './get-model-info.js';
+export { getLoadedModelInfo } from './get-loaded-model-info.js';
+export { getSystemResources } from './get-system-resources.js';
+export { assessModelFit } from './assess-model-fit.js';
+export { ocr } from './ocr.js';
+export { invokePlugin, invokePluginStream } from './invoke-plugin.js';
+export { diffusion, type DiffusionProgressTick } from './diffusion.js';
+export { classify } from './classify.js';
+export { video, type VideoProgressTick } from './video.js';
+export { upscale } from './upscale.js';
+export { worldCreateScene, worldStep } from './world.js';
+export { type WorldStepResult, type WorldStepProgressTick, type WorldSceneResult, type WorldSceneResultWithPack } from './world-result.js';
+export { modelRegistryList, modelRegistrySearch, modelRegistryGetModel, type ModelRegistrySearchParams } from './registry.js';
+export { suspend } from './suspend.js';
+export { resume } from './resume.js';
+export { state } from './state.js';
+export { vla, vlaHparams, vlaSetEmbodiment } from './vla.js';
+export { vlaPreprocessImage, vlaPadState, VLA_DEFAULT_IMAGE_SIZE } from './vla-helpers.js';
+export { audioGen } from './audio-gen.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,36 @@
+export { loadModel } from './load-model.js';
+export { downloadAsset } from './download-asset.js';
+export { batchCompletion } from './batch-completion.js';
+export { completion } from './completion-stream.js';
+export { deleteCache } from './delete-cache.js';
+export { unloadModel } from './unload-model.js';
+export { loggingStream } from './logging-stream.js';
+export { subscribeServerLogs } from './subscribe-logs.js';
+export { heartbeat } from './heartbeat.js';
+export { transcribe, transcribeStream } from './transcribe.js';
+export { bciTranscribe, bciTranscribeStream } from './bci-transcribe.js';
+export { embed } from './embed.js';
+export { finetune } from './finetune.js';
+export { translate } from './translate.js';
+export { cancel } from './cancel.js';
+export { ragChunk, ragIngest, ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings, ragReindex, ragListWorkspaces, ragCloseWorkspace, ragDeleteWorkspace } from './rag.js';
+export { textToSpeech, textToSpeechStream } from './text-to-speech.js';
+export { getModelInfo } from './get-model-info.js';
+export { getLoadedModelInfo } from './get-loaded-model-info.js';
+export { getSystemResources } from './get-system-resources.js';
+export { assessModelFit } from './assess-model-fit.js';
+export { ocr } from './ocr.js';
+export { invokePlugin, invokePluginStream } from './invoke-plugin.js';
+export { diffusion } from './diffusion.js';
+export { classify } from './classify.js';
+export { video } from './video.js';
+export { upscale } from './upscale.js';
+export { worldCreateScene, worldStep } from './world.js';
+export {} from './world-result.js';
+export { modelRegistryList, modelRegistrySearch, modelRegistryGetModel } from './registry.js';
+export { suspend } from './suspend.js';
+export { resume } from './resume.js';
+export { state } from './state.js';
+export { vla, vlaHparams, vlaSetEmbodiment } from './vla.js';
+export { vlaPreprocessImage, vlaPadState, VLA_DEFAULT_IMAGE_SIZE } from './vla-helpers.js';
+export { audioGen } from './audio-gen.js';

package/dist/src/client/api/invoke-plugin.d.ts

@@ -0,0 +1,31 @@
+import type { RPCOptions } from '@qvac/inference/surface';
+export interface InvokePluginOptions<TParams = unknown> {
+    modelId: string;
+    handler: string;
+    params: TParams;
+}
+/**
+ * Invoke a non-streaming plugin handler.
+ *
+ * @param options - Invocation payload.
+ * @param options.modelId - The identifier of the model instance that owns the plugin.
+ * @param options.handler - Name of the plugin handler to invoke.
+ * @param options.params - Handler-specific parameters, passed through to the plugin.
+ * @param rpcOptions - Optional RPC options (timeout, profiling, force new connection, etc.).
+ * @returns A promise resolving to the handler's result payload (typed via the `TResponse` generic).
+ * @throws {QvacErrorBase} When the response type is invalid (`InvalidResponseError`) or the RPC layer fails.
+ */
+export declare function invokePlugin<TResponse = unknown, TParams = unknown>(options: InvokePluginOptions<TParams>, rpcOptions?: RPCOptions): Promise<TResponse>;
+/**
+ * Invoke a streaming plugin handler.
+ *
+ * @param options - Invocation payload.
+ * @param options.modelId - The identifier of the model instance that owns the plugin.
+ * @param options.handler - Name of the plugin stream handler to invoke.
+ * @param options.params - Handler-specific parameters, passed through to the plugin.
+ * @param rpcOptions - Optional RPC options (timeout, profiling, force new connection, etc.).
+ * @returns An async generator yielding chunk payloads (typed via the `TResponse` generic) until the stream completes.
+ * @throws {QvacErrorBase} When an intermediate response has the wrong type (`InvalidResponseError`) or the RPC layer fails.
+ */
+export declare function invokePluginStream<TResponse = unknown, TParams = unknown>(options: InvokePluginOptions<TParams>, rpcOptions?: RPCOptions): AsyncGenerator<TResponse>;
+//# sourceMappingURL=invoke-plugin.d.ts.map

package/dist/src/client/api/invoke-plugin.js

@@ -0,0 +1,54 @@
+import { send, stream } from '../rpc/rpc-client.js';
+import { InvalidResponseError } from '../../utils/errors-client.js';
+/**
+ * Invoke a non-streaming plugin handler.
+ *
+ * @param options - Invocation payload.
+ * @param options.modelId - The identifier of the model instance that owns the plugin.
+ * @param options.handler - Name of the plugin handler to invoke.
+ * @param options.params - Handler-specific parameters, passed through to the plugin.
+ * @param rpcOptions - Optional RPC options (timeout, profiling, force new connection, etc.).
+ * @returns A promise resolving to the handler's result payload (typed via the `TResponse` generic).
+ * @throws {QvacErrorBase} When the response type is invalid (`InvalidResponseError`) or the RPC layer fails.
+ */
+export async function invokePlugin(options, rpcOptions) {
+    const request = {
+        type: 'pluginInvoke',
+        modelId: options.modelId,
+        handler: options.handler,
+        params: options.params
+    };
+    const response = await send(request, rpcOptions);
+    if (response.type !== 'pluginInvoke') {
+        throw new InvalidResponseError('pluginInvoke');
+    }
+    return response.result;
+}
+/**
+ * Invoke a streaming plugin handler.
+ *
+ * @param options - Invocation payload.
+ * @param options.modelId - The identifier of the model instance that owns the plugin.
+ * @param options.handler - Name of the plugin stream handler to invoke.
+ * @param options.params - Handler-specific parameters, passed through to the plugin.
+ * @param rpcOptions - Optional RPC options (timeout, profiling, force new connection, etc.).
+ * @returns An async generator yielding chunk payloads (typed via the `TResponse` generic) until the stream completes.
+ * @throws {QvacErrorBase} When an intermediate response has the wrong type (`InvalidResponseError`) or the RPC layer fails.
+ */
+export async function* invokePluginStream(options, rpcOptions) {
+    const request = {
+        type: 'pluginInvokeStream',
+        modelId: options.modelId,
+        handler: options.handler,
+        params: options.params
+    };
+    for await (const chunk of stream(request, rpcOptions)) {
+        const response = chunk;
+        if (response.type !== 'pluginInvokeStream') {
+            throw new InvalidResponseError('pluginInvokeStream');
+        }
+        if (!response.done) {
+            yield response.result;
+        }
+    }
+}

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

@@ -0,0 +1,184 @@
+import { type LoadModelOptions, type LoadCustomPluginModelOptions, type LoadModelDescriptorParam, type ReloadConfigOptions, type RPCOptions, type ModelDescriptor } from '@qvac/inference/surface';
+/**
+ * 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).
+ *     Hugging Face URLs (huggingface.co / hf.co) are verified against the Hub's SHA-256, and their transport is
+ *     hardened (plaintext http:// and https://→http:// downgrades rejected, loopback excepted). Other HTTP(S) URLs
+ *     are downloaded as-is and unverified (bring-your-own — plaintext on any host is allowed). Set
+ *     `requireHttpChecksum` in the SDK config to reject Hugging Face downloads that expose no usable checksum.
+ *   - 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)
+ *   - requireHttpChecksum: Per-call override — reject a Hugging Face HTTP download that exposes no usable SHA-256 instead of downloading it unverified. Defaults to the engine config (false).
+ *   - requireSecureTransport: Per-call override — reject plaintext http:// and HTTPS→HTTP downgrades for every HTTP source (loopback exempt); when unset, only Hugging Face transport is hardened. Defaults to the engine config (false).
+ *   - 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