@qvac/sdk 0.8.1 → 1.0.0

package/dist/client/api/embed.js

@@ -1,14 +1,24 @@
 import { send } from "../rpc/rpc-client.js";
 import {} from "../../schemas/index.js";
-import { InvalidResponseError } from "../../utils/errors-client.js";
-export async function embed(params, options) {
+/**
+ * Generates embeddings for a given text using a specified model.
+ *
+ * @param params - The parameters for the embedding
+ * @param params.modelId - The identifier of the embedding model to use
+ * @param params.text - The input text to embed
+ * @throws {Error} When the response type is invalid or when the embedding fails
+ */
+export async function embed(params) {
     const request = {
         type: "embed",
         ...params,
     };
-    const response = await send(request, options);
+    const response = await send(request);
     if (response.type !== "embed") {
-        throw new InvalidResponseError("embed");
+        throw new Error("Invalid response type");
+    }
+    if (!response.success) {
+        throw new Error(response.error ?? "Failed to embed");
     }
     return response.embedding;
 }

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

@@ -4,17 +4,13 @@ export { completion } from "./completion-stream";
 export { deleteCache } from "./delete-cache";
 export { unloadModel } from "./unload-model";
 export { loggingStream } from "./logging-stream";
-export { heartbeat } from "./heartbeat";
+export { ping } from "./ping";
 export { transcribe, transcribeStream } from "./transcribe";
 export { embed } from "./embed";
 export { translate } from "./translate";
 export { cancel } from "./cancel";
 export { startQVACProvider } from "./provide";
 export { stopQVACProvider } from "./stop-provider";
-export { ragChunk, ragIngest, ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings, ragReindex, ragListWorkspaces, ragCloseWorkspace, ragDeleteWorkspace, } from "./rag";
+export { ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings } from "./rag";
 export { textToSpeech } from "./text-to-speech";
-export { getModelInfo } from "./get-model-info";
-export { ocr } from "./ocr";
-export { invokePlugin, invokePluginStream } from "./invoke-plugin";
-export { modelRegistryList, modelRegistrySearch, modelRegistryGetModel, type ModelRegistrySearchParams, } from "./registry";
 //# sourceMappingURL=index.d.ts.map

package/dist/client/api/index.js

@@ -4,16 +4,12 @@ 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 { heartbeat } from "./heartbeat.js";
+export { ping } from "./ping.js";
 export { transcribe, transcribeStream } from "./transcribe.js";
 export { embed } from "./embed.js";
 export { translate } from "./translate.js";
 export { cancel } from "./cancel.js";
 export { startQVACProvider } from "./provide.js";
 export { stopQVACProvider } from "./stop-provider.js";
-export { ragChunk, ragIngest, ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings, ragReindex, ragListWorkspaces, ragCloseWorkspace, ragDeleteWorkspace, } from "./rag.js";
+export { ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings } from "./rag.js";
 export { textToSpeech } from "./text-to-speech.js";
-export { getModelInfo } from "./get-model-info.js";
-export { ocr } from "./ocr.js";
-export { invokePlugin, invokePluginStream } from "./invoke-plugin.js";
-export { modelRegistryList, modelRegistrySearch, modelRegistryGetModel, } from "./registry.js";

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

@@ -1,26 +1,29 @@
-import { type LoadModelOptions, type ReloadConfigOptions, type RPCOptions } from "../../schemas/index";
+import { type Logger } from "../../logging/index";
+import { type LoadModelOptions as BaseLoadModelOptions } from "../../schemas/index";
+export type LoadModelOptions = BaseLoadModelOptions & {
+    logger?: Logger;
+};
 /**
  * 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://).
+ * This function supports three model types: LLM (Large Language Model), Whisper (speech recognition),
+ * and embeddings. 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.
  *
  * @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 type of model ("llm", "whisper", "embeddings", "nmt", or "tts")
- *   - modelConfig: Model-specific configuration options (companion sources, model parameters, etc.)
- *   - onProgress: Callback for download progress updates
- *   - logger: Logger instance for model operation logs
- * @param rpcOptions - Optional RPC options including per-call profiling configuration
+ *   - modelType: The type of model ("llm", "whisper", "embeddings", or "nmt")
+ *   - modelConfig: Model-specific configuration options
+ *   - projectionModelSrc: (LLM only) Projection model source for multimodal models
+ *   - vadModelSrc: (Whisper only) VAD model source for voice activity detection
  *
  * @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
+ * @throws {Error} When model loading fails, with details in the error message
+ * @throws {Error} When streaming ends unexpectedly (only when using onProgress)
+ * @throws {Error} When receiving an invalid response type from the server
  *
  * @example
  * ```typescript
@@ -57,10 +60,8 @@ import { type LoadModelOptions, type ReloadConfigOptions, type RPCOptions } from
  * const multimodalId = await loadModel({
  *   modelSrc: "https://huggingface.co/.../main-model.gguf",
  *   modelType: "llm",
- *   modelConfig: {
- *     ctx_size: 512,
- *     projectionModelSrc: "https://huggingface.co/.../projection-model.gguf"
- *   },
+ *   projectionModelSrc: "https://huggingface.co/.../projection-model.gguf",
+ *   modelConfig: { ctx_size: 512 },
  *   onProgress: (progress) => {
  *     console.log(`Loading: ${progress.percentage}%`);
  *   }
@@ -70,12 +71,12 @@ import { type LoadModelOptions, type ReloadConfigOptions, type RPCOptions } from
  * const whisperId = await loadModel({
  *   modelSrc: "https://huggingface.co/.../whisper-model.gguf",
  *   modelType: "whisper",
+ *   vadModelSrc: "https://huggingface.co/.../vad-model.bin",
  *   modelConfig: {
  *     mode: "caption",
  *     output_format: "plaintext",
  *     min_seconds: 2,
- *     max_seconds: 6,
- *     vadModelSrc: "https://huggingface.co/.../vad-model.bin"
+ *     max_seconds: 6
  *   }
  * });
  *
@@ -88,39 +89,10 @@ import { type LoadModelOptions, type ReloadConfigOptions, type RPCOptions } from
  *   modelType: "llm",
  *   logger // Pass logger in options
  * });
- * ```
- */
-export declare function loadModel(options: LoadModelOptions, rpcOptions?: RPCOptions): Promise<string>;
-/**
- * Hot-reloads configuration on an already loaded model.
  *
- * @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" },
- * });
+ * // Now any logs from the model operations will appear in your logger automatically
+ * // No need to manually manage logging streams!
  * ```
  */
-export declare function loadModel(options: ReloadConfigOptions, rpcOptions?: RPCOptions): Promise<string>;
+export declare function loadModel(options: LoadModelOptions): Promise<string>;
 //# sourceMappingURL=load-model.d.ts.map

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

@@ -1,62 +1,156 @@
 import { send, stream } from "../rpc/rpc-client.js";
+import {} from "../../logging/index.js";
 import { startLoggingStreamForModel } from "../logging-stream-registry.js";
-import { loadModelOptionsToRequestSchema, reloadConfigOptionsToRequestSchema, isModelTypeAlias, normalizeModelType, } from "../../schemas/index.js";
-import { ModelLoadFailedError, StreamEndedError, InvalidResponseError, } from "../../utils/errors-client.js";
-import { getClientLogger } from "../../logging/index.js";
-const logger = getClientLogger();
-export async function loadModel(options, rpcOptions) {
-    const isReloadConfig = "modelId" in options && !("modelSrc" in options);
-    // Warn about deprecated alias usage
-    if (!isReloadConfig && isModelTypeAlias(options.modelType)) {
-        const canonical = normalizeModelType(options.modelType);
-        logger.warn(`Model type "${options.modelType}" is an alias and will be deprecated. Use "${canonical}" instead.`);
-    }
-    const request = isReloadConfig
-        ? reloadConfigOptionsToRequestSchema.parse(options)
-        : loadModelOptionsToRequestSchema.parse(options);
-    const modelLogger = isReloadConfig ? undefined : options.logger;
-    const onProgress = isReloadConfig ? undefined : options.onProgress;
-    if (onProgress) {
+import { loadModelRequestSchema, } from "../../schemas/index.js";
+/**
+ * Loads a machine learning model from a local path, remote URL, or Hyperdrive key.
+ *
+ * This function supports three model types: LLM (Large Language Model), Whisper (speech recognition),
+ * and embeddings. 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.
+ *
+ * @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 type of model ("llm", "whisper", "embeddings", or "nmt")
+ *   - modelConfig: Model-specific configuration options
+ *   - projectionModelSrc: (LLM only) Projection model source for multimodal models
+ *   - vadModelSrc: (Whisper only) VAD model source for voice activity detection
+ *
+ * @returns Promise that resolves to the model ID (either the provided modelSrc or a generated ID)
+ *
+ * @throws {Error} When model loading fails, with details in the error message
+ * @throws {Error} When streaming ends unexpectedly (only when using onProgress)
+ * @throws {Error} 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: "llm",
+ *   modelConfig: { contextSize: 2048 }
+ * });
+ *
+ * // Local file path - relative path
+ * const relativeModelId = await loadModel({
+ *   modelSrc: "./models/whisper-base.gguf",
+ *   modelType: "whisper"
+ * });
+ *
+ * // Hyperdrive URL with key and path
+ * const hyperdriveId = await loadModel({
+ *   modelSrc: "pear://<hyperdrive-key>/llama-7b.gguf",
+ *   modelType: "llm",
+ *   modelConfig: { contextSize: 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: "llm",
+ *   onProgress: (progress) => {
+ *     console.log(`Downloaded: ${progress.percentage}%`);
+ *   }
+ * });
+ *
+ * // Multimodal model with projection
+ * const multimodalId = await loadModel({
+ *   modelSrc: "https://huggingface.co/.../main-model.gguf",
+ *   modelType: "llm",
+ *   projectionModelSrc: "https://huggingface.co/.../projection-model.gguf",
+ *   modelConfig: { ctx_size: 512 },
+ *   onProgress: (progress) => {
+ *     console.log(`Loading: ${progress.percentage}%`);
+ *   }
+ * });
+ *
+ * // Whisper with VAD model
+ * const whisperId = await loadModel({
+ *   modelSrc: "https://huggingface.co/.../whisper-model.gguf",
+ *   modelType: "whisper",
+ *   vadModelSrc: "https://huggingface.co/.../vad-model.bin",
+ *   modelConfig: {
+ *     mode: "caption",
+ *     output_format: "plaintext",
+ *     min_seconds: 2,
+ *     max_seconds: 6
+ *   }
+ * });
+ *
+ * // 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: "llm",
+ *   logger // Pass logger in options
+ * });
+ *
+ * // Now any logs from the model operations will appear in your logger automatically
+ * // No need to manually manage logging streams!
+ * ```
+ */
+export async function loadModel(options) {
+    const { logger, modelSrc } = options;
+    const request = loadModelRequestSchema.parse({
+        type: "loadModel",
+        modelSrc: modelSrc,
+        projectionModelSrc: options.modelType === "llm" ? options.projectionModelSrc : undefined,
+        vadModelSrc: options.modelType === "whisper" ? options.vadModelSrc : undefined,
+        configSrc: options.modelType === "tts" ? options.configSrc : undefined,
+        eSpeakDataPath: options.modelType === "tts" ? options.eSpeakDataPath : undefined,
+        withProgress: !!options.onProgress,
+        seed: options.seed,
+        modelType: options.modelType,
+        modelConfig: options.modelConfig ?? {},
+        delegate: options.delegate,
+    });
+    if (options.onProgress) {
         // Use streaming for progress updates
-        for await (const response of stream(request, rpcOptions)) {
+        for await (const response of stream(request)) {
             if (response.type === "modelProgress") {
-                onProgress(response);
+                options.onProgress(response);
             }
             else if (response.type === "loadModel") {
                 if (!response.success) {
-                    throw new ModelLoadFailedError(response.error);
+                    throw new Error(response.error ?? "Failed to load model");
                 }
-                const modelId = response.modelId;
+                const modelId = response.modelId ?? modelSrc;
                 // Start logging stream in the background if logger is provided, catch to avoid failing the entire loadModel operation
-                if (modelLogger) {
+                if (logger) {
                     try {
-                        startLoggingStreamForModel(modelId, modelLogger);
+                        startLoggingStreamForModel(modelId, logger);
                     }
                     catch (error) {
-                        logger.warn(`Failed to start logging stream for model ${modelId}:`, error);
+                        console.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);
+        throw new Error("Stream ended without final response");
     }
-    const modelId = response.modelId;
-    if (modelLogger) {
-        try {
-            startLoggingStreamForModel(modelId, modelLogger);
+    else {
+        // Use regular send for simple loading
+        const response = await send(request);
+        if (response.type !== "loadModel") {
+            throw new Error("Invalid response type");
         }
-        catch (error) {
-            logger.warn(`Failed to start logging stream for model ${modelId}:`, error);
+        if (!response.success) {
+            throw new Error(response.error ?? "Failed to load model");
+        }
+        const modelId = response.modelId ?? modelSrc;
+        if (logger) {
+            try {
+                startLoggingStreamForModel(modelId, logger);
+            }
+            catch (error) {
+                console.warn(`Failed to start logging stream for model ${modelId}:`, error);
+            }
         }
+        return modelId;
     }
-    return modelId;
 }

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

@@ -1,19 +1,16 @@
 import type { LoggingStreamResponse, LoggingParams } from "../../schemas/logging-stream";
 /**
- * Opens a logging stream to receive real-time logs.
+ * Opens a logging stream for a specific model to receive real-time logs.
  *
  * @param params - The arguments for the logging stream
- * @param params.id - The unique identifier to stream logs for
+ * @param params.modelId - The unique identifier of the model to stream logs for
  * @returns AsyncGenerator yielding logging stream responses
- * @throws {QvacErrorBase} When the response type is invalid or when the stream fails
+ * @throws {Error} 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 });
+ * const logStream = loggingStream({ modelId: 'my-model-id' });
  *
  * for await (const logMessage of logStream) {
  *   console.log(`[${logMessage.level}] ${logMessage.namespace}: ${logMessage.message}`);

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

@@ -1,20 +1,16 @@
 import { stream } from "../rpc/rpc-client.js";
-import { InvalidResponseError } from "../../utils/errors-client.js";
 /**
- * Opens a logging stream to receive real-time logs.
+ * Opens a logging stream for a specific model to receive real-time logs.
  *
  * @param params - The arguments for the logging stream
- * @param params.id - The unique identifier to stream logs for
+ * @param params.modelId - The unique identifier of the model to stream logs for
  * @returns AsyncGenerator yielding logging stream responses
- * @throws {QvacErrorBase} When the response type is invalid or when the stream fails
+ * @throws {Error} 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 });
+ * const logStream = loggingStream({ modelId: 'my-model-id' });
  *
  * for await (const logMessage of logStream) {
  *   console.log(`[${logMessage.level}] ${logMessage.namespace}: ${logMessage.message}`);
@@ -29,7 +25,7 @@ export async function* loggingStream(params) {
     const responseStream = stream(request);
     for await (const response of responseStream) {
         if (response.type !== "loggingStream") {
-            throw new InvalidResponseError("loggingStream");
+            throw new Error("Invalid response type");
         }
         yield response;
     }

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

@@ -0,0 +1,11 @@
+/**
+ * Sends a ping request to the server and returns the pong response.
+ *
+ * @returns A promise that resolves to a pong response containing a number.
+ * @throws {Error} When the response type is not "pong".
+ */
+export declare function ping(): Promise<{
+    type: "pong";
+    number: number;
+}>;
+//# sourceMappingURL=ping.d.ts.map

package/dist/client/api/ping.js

@@ -0,0 +1,18 @@
+import {} from "../../schemas/index.js";
+import { send } from "../rpc/rpc-client.js";
+/**
+ * Sends a ping request to the server and returns the pong response.
+ *
+ * @returns A promise that resolves to a pong response containing a number.
+ * @throws {Error} When the response type is not "pong".
+ */
+export async function ping() {
+    const request = {
+        type: "ping",
+    };
+    const response = await send(request);
+    if (response.type !== "pong") {
+        throw new Error("Invalid response type");
+    }
+    return response;
+}

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

@@ -7,7 +7,7 @@ import { type ProvideParams } from "../../schemas/index";
  * @param options.topic - Topic hex string for peer discovery
  * @param options.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
+ * @throws {Error} When the response type is not "provide" or the request fails
  */
 export declare function startQVACProvider(params: ProvideParams): Promise<{
     type: "provide";

package/dist/client/api/provide.js

@@ -1,6 +1,5 @@
 import {} from "../../schemas/index.js";
 import { send } from "../rpc/rpc-client.js";
-import { InvalidResponseError, ProviderStartFailedError, } from "../../utils/errors-client.js";
 /**
  * Starts a provider service that offers QVAC capabilities to remote peers.
  * The provider's keypair can be controlled via the seed option or QVAC_HYPERSWARM_SEED environment variable.
@@ -9,7 +8,7 @@ import { InvalidResponseError, ProviderStartFailedError, } from "../../utils/err
  * @param options.topic - Topic hex string for peer discovery
  * @param options.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
+ * @throws {Error} When the response type is not "provide" or the request fails
  */
 export async function startQVACProvider(params) {
     const request = {
@@ -19,10 +18,10 @@ export async function startQVACProvider(params) {
     };
     const response = await send(request);
     if (response.type !== "provide") {
-        throw new InvalidResponseError("provide");
+        throw new Error("Invalid response type");
     }
     if (response.error) {
-        throw new ProviderStartFailedError(response.error);
+        throw new Error(response.error);
     }
     return response;
 }