@qvac/sdk 0.9.2 → 0.10.0

package/dist/client/api/diffusion.js

@@ -1,16 +1,31 @@
 import { diffusionStreamResponseSchema, } from "../../schemas/index.js";
 import { stream as streamRpc } from "../rpc/rpc-client.js";
-import { decodeBase64 } from "../../utils/encoding.js";
+import { decodeBase64, encodeBase64 } from "../../utils/encoding.js";
 /**
- * Generate images using a loaded diffusion model.
+ * Generates images using a loaded diffusion model.
+ *
+ * @param params - Diffusion request parameters (model, prompt, dimensions, sampler, seed, etc.).
+ * @returns A result object exposing `progressStream` (async iterator of `{ step, totalSteps, elapsedMs }`), `outputs` (promise of the generated image buffers), and `stats` (promise of generation statistics).
+ *
+ * Supports both txt2img (no `init_image`) and img2img (with `init_image`).
  *
  * @example
  * ```typescript
- * // Basic usage
+ * // txt2img
  * const { outputs, stats } = diffusion({ modelId, prompt: "a cat" });
  * const buffers = await outputs;
  * fs.writeFileSync("output.png", buffers[0]);
  *
+ * // img2img (SD/SDXL — SDEdit)
+ * const initImage = fs.readFileSync("input.png");
+ * const { outputs } = diffusion({ modelId, prompt: "oil painting style", init_image: initImage, strength: 0.7 });
+ *
+ * // img2img (FLUX.2 — in-context conditioning)
+ * // IMPORTANT: FLUX img2img requires `prediction: "flux2_flow"` to be set on the
+ * // model config at loadModel time (e.g. `loadModel(src, { modelType: "diffusion",
+ * // modelConfig: { prediction: "flux2_flow" } })`).
+ * const { outputs } = diffusion({ modelId, prompt: "turn into watercolor", init_image: initImage });
+ *
  * // With progress tracking
  * const { progressStream, outputs } = diffusion({ modelId, prompt: "a cat" });
  * for await (const { step, totalSteps } of progressStream) {
@@ -20,9 +35,11 @@ import { decodeBase64 } from "../../utils/encoding.js";
  * ```
  */
 export function diffusion(params) {
+    const { init_image, ...rest } = params;
     const request = {
+        ...rest,
+        ...(init_image !== undefined && { init_image: encodeBase64(init_image) }),
         type: "diffusionStream",
-        ...params,
     };
     let statsResolver = () => { };
     let statsRejecter = () => { };

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

@@ -2,10 +2,12 @@ import { type EmbedStats, type RPCOptions } from "../../schemas/index";
 /**
  * Generates embeddings for a single text using a specified model.
  *
+ * @overloadLabel "Single text"
  * @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
  * @param options - Optional RPC options including per-call profiling
+ * @returns A promise resolving to an object with `embedding` (a single `number[]` vector) and optional `stats` performance data.
  * @throws {QvacErrorBase} When the response type is invalid or when the embedding fails
  */
 export declare function embed(params: {
@@ -18,10 +20,12 @@ export declare function embed(params: {
 /**
  * Generates embeddings for multiple texts using a specified model.
  *
+ * @overloadLabel "Multiple texts"
  * @param params - The parameters for the embedding
  * @param params.modelId - The identifier of the embedding model to use
  * @param params.text - The input texts to embed
  * @param options - Optional RPC options including per-call profiling
+ * @returns A promise resolving to an object with `embedding` (one `number[]` vector per input text, i.e. `number[][]`) and optional `stats` performance data.
  * @throws {QvacErrorBase} When the response type is invalid or when the embedding fails
  */
 export declare function embed(params: {

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

@@ -63,7 +63,28 @@ type FinetuneReplyParams = FinetuneStopParams | FinetuneGetStateParams;
  * console.log(pauseResult.status);
  * ```
  */
+/**
+ * Run / start / resume a finetune job. Returns a handle with a streaming
+ * `progressStream` and a terminal `result` promise.
+ *
+ * @overloadLabel "Run / start / resume"
+ * @param params - The finetuning run parameters (see the function-level
+ *   docs for the full breakdown of `params.options`).
+ * @param rpcOptions - Optional RPC transport options.
+ * @returns A `FinetuneHandle` with `progressStream` (yields per-step loss
+ *   metrics) and `result` (resolves once the run terminates).
+ */
 export declare function finetune(params: FinetuneRunParams, rpcOptions?: RPCOptions): FinetuneHandle;
+/**
+ * Stop / pause / cancel an in-flight finetune, or query its current state.
+ *
+ * @overloadLabel "Stop / getState / pause / cancel"
+ * @param params - Finetune control parameters; `params.operation` selects
+ *   `pause`, `cancel`, or `getState`.
+ * @param rpcOptions - Optional RPC transport options.
+ * @returns A promise that resolves to the current `FinetuneResult`
+ *   (status + last-known progress).
+ */
 export declare function finetune(params: FinetuneReplyParams, rpcOptions?: RPCOptions): Promise<FinetuneResult>;
 export {};
 //# sourceMappingURL=finetune.d.ts.map

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

@@ -0,0 +1,25 @@
+import { type GetLoadedModelInfoParams, type LoadedModelInfo } from "../../schemas/index";
+import { type RPCOptions } from "../../schemas/common";
+/**
+ * Returns introspection info for a loaded `modelId` (local or delegated).
+ *
+ * For local models, `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()`.
+ *
+ * For delegated models, only `modelId`, `isDelegated: true`, `providerInfo`,
+ * and `handlers: []` are populated. Preflight against a delegated model is
+ * best-effort and falls through to the provider's error response.
+ *
+ * Throws `ModelNotFoundError` if no entry exists for `modelId`.
+ *
+ * @example
+ * ```typescript
+ * const info = await getLoadedModelInfo({ modelId });
+ * if (info.isDelegated || info.handlers.includes("completionStream")) {
+ *   // safe to call completion(); delegated path defers to provider
+ * }
+ * ```
+ */
+export declare function getLoadedModelInfo(params: GetLoadedModelInfoParams, rpcOptions?: RPCOptions): Promise<LoadedModelInfo>;
+//# sourceMappingURL=get-loaded-model-info.d.ts.map

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

@@ -0,0 +1,36 @@
+import {} from "../../schemas/index.js";
+import {} from "../../schemas/common.js";
+import { send } from "../rpc/rpc-client.js";
+import { InvalidResponseError } from "../../utils/errors-client.js";
+/**
+ * Returns introspection info for a loaded `modelId` (local or delegated).
+ *
+ * For local models, `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()`.
+ *
+ * For delegated models, only `modelId`, `isDelegated: true`, `providerInfo`,
+ * and `handlers: []` are populated. Preflight against a delegated model is
+ * best-effort and falls through to the provider's error response.
+ *
+ * Throws `ModelNotFoundError` if no entry exists for `modelId`.
+ *
+ * @example
+ * ```typescript
+ * const info = await getLoadedModelInfo({ modelId });
+ * if (info.isDelegated || info.handlers.includes("completionStream")) {
+ *   // safe to call completion(); delegated path defers to provider
+ * }
+ * ```
+ */
+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/client/api/get-model-info.d.ts

@@ -1,10 +1,18 @@
 import { type GetModelInfoParams } from "../../schemas/index";
+/**
+ * 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<{
     name: string;
     modelId: string;
     expectedSize: number;
     sha256Checksum: string;
-    addon: "llm" | "whisper" | "embeddings" | "nmt" | "parakeet" | "tts" | "ocr" | "diffusion" | "vad" | "other";
+    addon: "embeddings" | "llm" | "whisper" | "nmt" | "parakeet" | "tts" | "ocr" | "diffusion" | "vad" | "other";
     isCached: boolean;
     isLoaded: boolean;
     cacheFiles: {

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

@@ -1,6 +1,14 @@
 import {} from "../../schemas/index.js";
 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",

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

@@ -5,7 +5,7 @@ import type { DelegateBase } from "../../schemas/delegate";
  * Can also be used to check if the local SDK worker is responsive.
  *
  * @param params - Delegation target to check
- * @param params.delegate - The provider to check (topic + publicKey + optional timeout)
+ * @param params.delegate - The provider to check (providerPublicKey + optional timeout)
  * @returns A promise that resolves to a heartbeat response if the provider is reachable.
  * @throws {QvacErrorBase} When the provider is unreachable or the response is invalid.
  *
@@ -13,7 +13,7 @@ import type { DelegateBase } from "../../schemas/delegate";
  * // Check if a delegated provider is online
  * try {
  *   await heartbeat({
- *     delegate: { topic: "topicHex", providerPublicKey: "peerHex", timeout: 3000 },
+ *     delegate: { providerPublicKey: "peerHex", timeout: 3000 },
  *   });
  *   console.log("Provider is online");
  * } catch {

package/dist/client/api/heartbeat.js

@@ -6,7 +6,7 @@ import { InvalidResponseError } from "../../utils/errors-client.js";
  * Can also be used to check if the local SDK worker is responsive.
  *
  * @param params - Delegation target to check
- * @param params.delegate - The provider to check (topic + publicKey + optional timeout)
+ * @param params.delegate - The provider to check (providerPublicKey + optional timeout)
  * @returns A promise that resolves to a heartbeat response if the provider is reachable.
  * @throws {QvacErrorBase} When the provider is unreachable or the response is invalid.
  *
@@ -14,7 +14,7 @@ import { InvalidResponseError } from "../../utils/errors-client.js";
  * // Check if a delegated provider is online
  * try {
  *   await heartbeat({
- *     delegate: { topic: "topicHex", providerPublicKey: "peerHex", timeout: 3000 },
+ *     delegate: { providerPublicKey: "peerHex", timeout: 3000 },
  *   });
  *   console.log("Provider is online");
  * } catch {

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

@@ -13,12 +13,14 @@ 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 { textToSpeech } from "./text-to-speech";
+export { textToSpeech, textToSpeechStream } from "./text-to-speech";
 export { getModelInfo } from "./get-model-info";
+export { getLoadedModelInfo } from "./get-loaded-model-info";
 export { ocr } from "./ocr";
 export { invokePlugin, invokePluginStream } from "./invoke-plugin";
 export { diffusion, type DiffusionProgressTick } from "./diffusion";
 export { modelRegistryList, modelRegistrySearch, modelRegistryGetModel, type ModelRegistrySearchParams, } from "./registry";
 export { suspend } from "./suspend";
 export { resume } from "./resume";
+export { state } from "./state";
 //# sourceMappingURL=index.d.ts.map

package/dist/client/api/index.js

@@ -13,11 +13,13 @@ 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 { textToSpeech } from "./text-to-speech.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 { ocr } from "./ocr.js";
 export { invokePlugin, invokePluginStream } from "./invoke-plugin.js";
 export { diffusion } from "./diffusion.js";
 export { modelRegistryList, modelRegistrySearch, modelRegistryGetModel, } from "./registry.js";
 export { suspend } from "./suspend.js";
 export { resume } from "./resume.js";
+export { state } from "./state.js";

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

@@ -6,10 +6,26 @@ export interface InvokePluginOptions<TParams = unknown> {
 }
 /**
  * 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/client/api/invoke-plugin.js

@@ -2,6 +2,14 @@ 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 = {
@@ -18,6 +26,14 @@ export async function invokePlugin(options, rpcOptions) {
 }
 /**
  * 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 = {

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

@@ -1,4 +1,23 @@
-import { type LoadModelOptions, type ReloadConfigOptions, type RPCOptions } from "../../schemas/index";
+import { type LoadModelOptions, type LoadCustomPluginModelOptions, type LoadModelDescriptorParam, type ReloadConfigOptions, type RPCOptions, type ModelDescriptor } from "../../schemas/index";
+/**
+ * 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>;
 /**
  * Loads a machine learning model from a local path, remote URL, or Hyperdrive key.
  *
@@ -8,6 +27,7 @@ import { type LoadModelOptions, type ReloadConfigOptions, type RPCOptions } from
  * 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 type of model ("llm", "whisper", "embeddings", "nmt", or "tts")
@@ -28,7 +48,7 @@ import { type LoadModelOptions, type ReloadConfigOptions, type RPCOptions } from
  * const localModelId = await loadModel({
  *   modelSrc: "/home/user/models/llama-7b.gguf",
  *   modelType: "llm",
- *   modelConfig: { contextSize: 2048 }
+ *   modelConfig: { ctx_size: 2048 }
  * });
  *
  * // Local file path - relative path
@@ -41,7 +61,7 @@ import { type LoadModelOptions, type ReloadConfigOptions, type RPCOptions } from
  * const hyperdriveId = await loadModel({
  *   modelSrc: "pear://<hyperdrive-key>/llama-7b.gguf",
  *   modelType: "llm",
- *   modelConfig: { contextSize: 2048 }
+ *   modelConfig: { ctx_size: 2048 }
  * });
  *
  * // Remote HTTP/HTTPS URL with progress tracking
@@ -91,9 +111,22 @@ import { type LoadModelOptions, type ReloadConfigOptions, type RPCOptions } from
  * ```
  */
 export declare function loadModel(options: LoadModelOptions, rpcOptions?: RPCOptions): Promise<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>;
 /**
  * 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)

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

@@ -1,21 +1,42 @@
 import { send, stream } from "../rpc/rpc-client.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 { loadModelOptionsToRequestSchema, reloadConfigOptionsToRequestSchema, isModelTypeAlias, normalizeModelType, inferModelTypeFromModelSrc, } from "../../schemas/index.js";
+import { ModelLoadFailedError, ModelTypeRequiredError, StreamEndedError, InvalidResponseError, } from "../../utils/errors-client.js";
+import { assertModelSrcMatchesModelType } from "../../utils/load-model-validation.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.`);
+    // 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 request = isReloadConfig
-        ? reloadConfigOptionsToRequestSchema.parse(options)
-        : loadModelOptionsToRequestSchema.parse(options);
-    const modelLogger = isReloadConfig ? undefined : options.logger;
-    const onProgress = isReloadConfig ? undefined : options.onProgress;
+        ? reloadConfigOptionsToRequestSchema.parse(resolvedOptions)
+        : loadModelOptionsToRequestSchema.parse(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)) {

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

@@ -1,15 +1,21 @@
 import { type ProvideParams } from "../../schemas/index";
 /**
  * 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.
  *
- * @param options - Options object with required topic, optional seed, and optional firewall config
- * @param options.topic - Topic hex string for peer discovery
- * @param options.firewall - Optional firewall configuration to allow/deny specific public keys
+ * 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<{
+export declare function startQVACProvider(params?: ProvideParams): Promise<{
     type: "provide";
     success: boolean;
     error?: string | undefined;

package/dist/client/api/provide.js

@@ -3,18 +3,23 @@ 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.
  *
- * @param options - Options object with required topic, optional seed, and optional firewall config
- * @param options.topic - Topic hex string for peer discovery
- * @param options.firewall - Optional firewall configuration to allow/deny specific public keys
+ * 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) {
+export async function startQVACProvider(params = {}) {
     const request = {
         type: "provide",
-        topic: params.topic,
         firewall: params.firewall,
     };
     const response = await send(request);

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

@@ -6,6 +6,7 @@ import type { RagChunkParams, RagDoc, RagIngestParams, RagSaveEmbeddingsParams,
  * @param params - The parameters for chunking
  * @param params.documents - Documents to chunk (string or array)
  * @param params.chunkOpts - Chunking options (chunkSize, chunkOverlap, chunkStrategy)
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
  * @returns Array of chunk results with id and content
  * @throws {RAGChunkFailedError} When the operation fails
  *
@@ -37,6 +38,7 @@ export declare function ragChunk(params: RagChunkParams, options?: RPCOptions):
  * @param params.workspace - Workspace for isolated storage (default: "default"). Created if it doesn't exist.
  * @param params.onProgress - Progress callback (stage, current, total)
  * @param params.progressInterval - Minimum interval between progress updates in ms
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
  * @returns Processing results and dropped indices
  * @throws {RAGSaveFailedError} When the operation fails
  * @throws {StreamEndedError} When streaming ends unexpectedly (only when using onProgress)
@@ -76,6 +78,7 @@ export declare function ragIngest(params: RagIngestParams, options?: RPCOptions)
  * @param params.workspace - Workspace for isolated storage (default: "default"). Created if it doesn't exist.
  * @param params.onProgress - Progress callback (stage, current, total)
  * @param params.progressInterval - Minimum interval between progress updates in ms
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
  * @returns Array of save results
  * @throws {RAGSaveFailedError} When the operation fails
  * @throws {StreamEndedError} When streaming ends unexpectedly (only when using onProgress)
@@ -109,6 +112,7 @@ export declare function ragSaveEmbeddings(params: RagSaveEmbeddingsParams, optio
  * @param params.topK - Number of top results to retrieve (default: 5)
  * @param params.n - Number of centroids to use for IVF index search (default: 3)
  * @param params.workspace - Workspace to search in (default: "default").
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
  * @returns Array of search results with id, content, and score. Empty array if workspace doesn't exist.
  * @throws {RAGSearchFailedError} When the operation fails
  *
@@ -131,6 +135,7 @@ export declare function ragSearch(params: RagSearchParams, options?: RPCOptions)
  * @param params - The parameters for deleting embeddings
  * @param params.ids - Array of document IDs to delete
  * @param params.workspace - Workspace to delete from (default: "default")
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
  * @throws {RAGDeleteFailedError} When the operation fails or workspace doesn't exist
  *
  * @example
@@ -155,6 +160,7 @@ export declare function ragDeleteEmbeddings(params: RagDeleteEmbeddingsParams, o
  * @param params - The parameters for reindexing
  * @param params.workspace - Workspace to reindex (default: "default"). Must already exist.
  * @param params.onProgress - Progress callback (stage, current, total)
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
  * @returns Reindex result with `reindexed` boolean and optional `details`
  * @throws {RAGSaveFailedError} When the operation fails or workspace doesn't exist
  * @throws {StreamEndedError} When streaming ends unexpectedly (only when using onProgress)
@@ -188,6 +194,7 @@ export declare function ragReindex(params: RagReindexParams, options?: RPCOption
  * the workspace is currently loaded in memory and holding active resources
  * (Corestore, HyperDB adapter, and possibly a RAG instance).
  *
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
  * @returns Array of workspace info with name and open status
  * @throws {RAGListWorkspacesFailedError} When the operation fails
  *
@@ -208,6 +215,7 @@ export declare function ragListWorkspaces(options?: RPCOptions): Promise<RagWork
  * @param params - The parameters for closing
  * @param params.workspace - Name of the workspace to close (default: "default")
  * @param params.deleteOnClose - If true, deletes the workspace data from disk after closing (default: false)
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
  * @throws {RAGCloseWorkspaceFailedError} When the operation fails
  *
  * @example
@@ -226,6 +234,7 @@ export declare function ragCloseWorkspace(params?: RagCloseWorkspaceParams, opti
  *
  * @param params - The parameters for deletion
  * @param params.workspace - Name of the workspace to delete
+ * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
  * @throws {RAGDeleteFailedError} When the workspace doesn't exist or is currently loaded
  *
  * @example