@qvac/sdk 0.9.2 → 0.10.1

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

package/dist/client/api/rag.js

@@ -8,6 +8,7 @@ import { InvalidResponseError, InvalidOperationError, StreamEndedError, RAGChunk
  * @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
  *
@@ -57,6 +58,7 @@ export async function ragChunk(params, options) {
  * @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)
@@ -137,6 +139,7 @@ export async function ragIngest(params, options) {
  * @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)
@@ -207,6 +210,7 @@ export async function ragSaveEmbeddings(params, options) {
  * @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
  *
@@ -249,6 +253,7 @@ export async function ragSearch(params, options) {
  * @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
@@ -290,6 +295,7 @@ export async function ragDeleteEmbeddings(params, options) {
  * @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)
@@ -359,6 +365,7 @@ export async function ragReindex(params, options) {
  * 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
  *
@@ -396,6 +403,7 @@ export async function ragListWorkspaces(options) {
  * @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
@@ -431,6 +439,7 @@ export async function ragCloseWorkspace(params, options) {
  *
  * @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

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

@@ -7,8 +7,34 @@ export interface ModelRegistrySearchParams {
     modelType?: ModelRegistryEntryAddon;
     addon?: ModelRegistryEntryAddon;
 }
+/**
+ * Returns all available models from the QVAC distributed model registry.
+ *
+ * @returns A promise resolving to an array of `ModelRegistryEntry` describing every model the SDK's connected registry knows about.
+ * @throws {ModelRegistryQueryFailedError} When the registry query fails.
+ */
 declare function modelRegistryList(): Promise<ModelRegistryEntry[]>;
+/**
+ * Searches the model registry with optional filters for model type, engine, and quantization.
+ *
+ * @param params - Search filters (all optional).
+ * @param params.filter - Free-text filter matched against model metadata.
+ * @param params.engine - Inference engine identifier (e.g., `"llamacpp-completion"`).
+ * @param params.quantization - Quantization identifier (e.g., `"Q4_K_M"`).
+ * @param params.modelType - Alias for `addon`; kept for backward compatibility.
+ * @param params.addon - Model addon / category to restrict results to.
+ * @returns A promise resolving to the matching `ModelRegistryEntry` entries.
+ * @throws {ModelRegistryQueryFailedError} When the registry query fails.
+ */
 declare function modelRegistrySearch(params?: ModelRegistrySearchParams): Promise<ModelRegistryEntry[]>;
+/**
+ * Fetches a single model entry from the registry by its path and source.
+ *
+ * @param registryPath - Registry-relative path of the model to fetch.
+ * @param registrySource - Registry source identifier (e.g., `"huggingface"`, `"local"`).
+ * @returns A promise resolving to the matching `ModelRegistryEntry`.
+ * @throws {ModelRegistryQueryFailedError} When the model cannot be located or the registry query fails.
+ */
 declare function modelRegistryGetModel(registryPath: string, registrySource: string): Promise<ModelRegistryEntry>;
 export { modelRegistryList, modelRegistrySearch, modelRegistryGetModel };
 //# sourceMappingURL=registry.d.ts.map

package/dist/client/api/registry.js

@@ -5,6 +5,12 @@ function validateRegistryResponse(response, fallbackError) {
         throw new ModelRegistryQueryFailedError(response.error ?? fallbackError ?? "Unknown registry error");
     }
 }
+/**
+ * Returns all available models from the QVAC distributed model registry.
+ *
+ * @returns A promise resolving to an array of `ModelRegistryEntry` describing every model the SDK's connected registry knows about.
+ * @throws {ModelRegistryQueryFailedError} When the registry query fails.
+ */
 async function modelRegistryList() {
     const request = {
         type: "modelRegistryList",
@@ -13,6 +19,18 @@ async function modelRegistryList() {
     validateRegistryResponse(response);
     return response.models;
 }
+/**
+ * Searches the model registry with optional filters for model type, engine, and quantization.
+ *
+ * @param params - Search filters (all optional).
+ * @param params.filter - Free-text filter matched against model metadata.
+ * @param params.engine - Inference engine identifier (e.g., `"llamacpp-completion"`).
+ * @param params.quantization - Quantization identifier (e.g., `"Q4_K_M"`).
+ * @param params.modelType - Alias for `addon`; kept for backward compatibility.
+ * @param params.addon - Model addon / category to restrict results to.
+ * @returns A promise resolving to the matching `ModelRegistryEntry` entries.
+ * @throws {ModelRegistryQueryFailedError} When the registry query fails.
+ */
 async function modelRegistrySearch(params = {}) {
     const { modelType, ...rest } = params;
     const request = {
@@ -24,6 +42,14 @@ async function modelRegistrySearch(params = {}) {
     validateRegistryResponse(response);
     return response.models;
 }
+/**
+ * Fetches a single model entry from the registry by its path and source.
+ *
+ * @param registryPath - Registry-relative path of the model to fetch.
+ * @param registrySource - Registry source identifier (e.g., `"huggingface"`, `"local"`).
+ * @returns A promise resolving to the matching `ModelRegistryEntry`.
+ * @throws {ModelRegistryQueryFailedError} When the model cannot be located or the registry query fails.
+ */
 async function modelRegistryGetModel(registryPath, registrySource) {
     const request = {
         type: "modelRegistryGetModel",

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

@@ -1,14 +1,30 @@
 /**
- * Resumes all suspended Hyperswarm and Corestore resources
+ * Resumes the SDK runtime: restores all suspended Hyperswarm and Corestore
+ * resources and releases the lifecycle gate so all SDK operations are allowed
+ * again.
  *
- * Idempotent — calling while already active is a no-op.
- * Also serves as the recovery path after a partial suspend failure.
+ * Safe to call from any lifecycle state — `resume()` is never blocked by the
+ * lifecycle gate (along with `suspend()` and `state()`). Idempotent. Also
+ * serves as the recovery path after a partial suspend failure.
  *
- * @throws {RPCError} When one or more resources fail to resume.
+ * After `resume()` resolves successfully, runtime state is `"active"` and
+ * non-lifecycle SDK operations are accepted normally.
+ *
+ * Behavior of in-flight operations from before the previous `suspend()`:
+ *   - P2P / Hyperdrive downloads: continue automatically once their underlying
+ *     swarm/corestore is restored
+ *   - Delegated reply RPCs: auto-recover once the swarm reconnects
+ *     (subject to delegate `timeout`)
+ *   - Delegated stream RPCs: not recovered — re-issue after `resume()` works normally.
+ *
+ * @throws {RPCError} When one or more resources fail to resume. On partial
+ *   failure the runtime stays `"suspended"` (operations remain blocked) so
+ *   callers can retry `resume()`.
  *
  * @example
  * // Foreground handler
  * await resume();
+ * console.log(await state()); // "active"
  */
 export declare function resume(): Promise<void>;
 //# sourceMappingURL=resume.d.ts.map

package/dist/client/api/resume.js

@@ -1,16 +1,32 @@
 import { send } from "../rpc/rpc-client.js";
 import { InvalidResponseError } from "../../utils/errors-client.js";
 /**
- * Resumes all suspended Hyperswarm and Corestore resources
+ * Resumes the SDK runtime: restores all suspended Hyperswarm and Corestore
+ * resources and releases the lifecycle gate so all SDK operations are allowed
+ * again.
  *
- * Idempotent — calling while already active is a no-op.
- * Also serves as the recovery path after a partial suspend failure.
+ * Safe to call from any lifecycle state — `resume()` is never blocked by the
+ * lifecycle gate (along with `suspend()` and `state()`). Idempotent. Also
+ * serves as the recovery path after a partial suspend failure.
  *
- * @throws {RPCError} When one or more resources fail to resume.
+ * After `resume()` resolves successfully, runtime state is `"active"` and
+ * non-lifecycle SDK operations are accepted normally.
+ *
+ * Behavior of in-flight operations from before the previous `suspend()`:
+ *   - P2P / Hyperdrive downloads: continue automatically once their underlying
+ *     swarm/corestore is restored
+ *   - Delegated reply RPCs: auto-recover once the swarm reconnects
+ *     (subject to delegate `timeout`)
+ *   - Delegated stream RPCs: not recovered — re-issue after `resume()` works normally.
+ *
+ * @throws {RPCError} When one or more resources fail to resume. On partial
+ *   failure the runtime stays `"suspended"` (operations remain blocked) so
+ *   callers can retry `resume()`.
  *
  * @example
  * // Foreground handler
  * await resume();
+ * console.log(await state()); // "active"
  */
 export async function resume() {
     const response = await send({ type: "resume" });

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

@@ -0,0 +1,23 @@
+import type { LifecycleState } from "../../schemas/index";
+/**
+ * Returns the current runtime lifecycle state.
+ *
+ * Safe to call from any lifecycle state — `state()` is never blocked by the
+ * lifecycle gate (along with `suspend()` and `resume()`).
+ *
+ * @returns The current lifecycle state:
+ *   - `"active"`: all SDK operations are allowed
+ *   - `"suspending"` | `"suspended"` | `"resuming"`: non-lifecycle operations
+ *     throw `LifecycleOperationBlockedError`
+ *
+ * @throws {InvalidResponseError} When the response envelope does not match the request type.
+ *
+ * @example
+ * // Branch on lifecycle state before issuing work
+ * const current = await state();
+ * if (current !== "active") {
+ *   await resume();
+ * }
+ */
+export declare function state(): Promise<LifecycleState>;
+//# sourceMappingURL=state.d.ts.map

package/dist/client/api/state.js

@@ -0,0 +1,29 @@
+import { send } from "../rpc/rpc-client.js";
+import { InvalidResponseError } from "../../utils/errors-client.js";
+/**
+ * Returns the current runtime lifecycle state.
+ *
+ * Safe to call from any lifecycle state — `state()` is never blocked by the
+ * lifecycle gate (along with `suspend()` and `resume()`).
+ *
+ * @returns The current lifecycle state:
+ *   - `"active"`: all SDK operations are allowed
+ *   - `"suspending"` | `"suspended"` | `"resuming"`: non-lifecycle operations
+ *     throw `LifecycleOperationBlockedError`
+ *
+ * @throws {InvalidResponseError} When the response envelope does not match the request type.
+ *
+ * @example
+ * // Branch on lifecycle state before issuing work
+ * const current = await state();
+ * if (current !== "active") {
+ *   await resume();
+ * }
+ */
+export async function state() {
+    const response = await send({ type: "state" });
+    if (response.type !== "state") {
+        throw new InvalidResponseError("state");
+    }
+    return response.state;
+}

package/dist/client/api/stop-provider.d.ts

@@ -1,13 +1,19 @@
-import { type StopProvideParams } from "../../schemas/index";
 /**
- * Stops a running provider service and leaves the specified topic.
+ * Stops the running provider service.
+ *
+ * After this call returns, incoming peer connections are dropped at the RPC
+ * layer and remote `loadModel`/`completion`/etc. requests will no longer be
+ * served. The keyPair stays bound on the DHT (a `swarm.listen()` cannot be
+ * undone without tearing down the shared swarm), so peers may still open a
+ * raw socket — but those sockets are immediately destroyed and no RPC server
+ * is mounted on them.
+ *
+ * Idempotent: calling more than once with no provider running is a no-op.
  *
- * @param options - Options object with required topic
- * @param options.topic - Topic hex string to leave
  * @returns A promise that resolves to the stop provide response containing success status
  * @throws {QvacErrorBase} When the response type is not "stopProvide" or the request fails
  */
-export declare function stopQVACProvider(params: StopProvideParams): Promise<{
+export declare function stopQVACProvider(): Promise<{
     type: "stopProvide";
     success: boolean;
     error?: string | undefined;