@qvac/sdk 0.9.1 → 0.10.0

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;

package/dist/client/api/stop-provider.js

@@ -2,17 +2,23 @@ import {} from "../../schemas/index.js";
 import { send } from "../rpc/rpc-client.js";
 import { InvalidResponseError, ProviderStopFailedError, } from "../../utils/errors-client.js";
 /**
- * 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 async function stopQVACProvider(params) {
+export async function stopQVACProvider() {
     const request = {
         type: "stopProvide",
-        topic: params.topic,
     };
     const response = await send(request);
     if (response.type !== "stopProvide") {

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

@@ -1,13 +1,31 @@
 /**
- * Suspends all active Hyperswarm and Corestore resources
+ * Suspends the SDK runtime: pauses all registered Hyperswarm and Corestore
+ * resources and engages the lifecycle gate so non-lifecycle operations are
+ * blocked until `resume()` is called.
  *
- * Idempotent — calling while already suspended is a no-op.
+ * Safe to call from any lifecycle state — `suspend()` is never blocked by the
+ * lifecycle gate (along with `resume()` and `state()`). Idempotent.
  *
- * @throws {RPCError} When one or more resources fail to suspend (partial failure).
+ * After `suspend()` resolves, runtime state is `"suspended"` and any non-
+ * lifecycle SDK operation throws `LifecycleOperationBlockedError` until
+ * `resume()` is called.
+ *
+ * In-flight operations started before suspend:
+ *   - P2P / Hyperdrive downloads: stall cleanly, continue after `resume()`
+ *   - HTTP downloads: bypass suspend entirely (bytes keep flowing)
+ *   - Local native inference: runs to completion regardless
+ *   - Delegated reply RPCs: stall, then auto-recover after `resume()`
+ *     (subject to delegate `timeout`)
+ *   - Delegated stream RPCs: severed, consumer iterator hangs silently;
+ *     re-issue after `resume()` works normally.
+ *
+ * @throws {RPCError} When one or more resources fail to suspend. The runtime
+ *   still commits to `"suspended"` so callers can recover with `resume()`.
  *
  * @example
  * // Background handler
  * await suspend();
+ * console.log(await state()); // "suspended"
  */
 export declare function suspend(): Promise<void>;
 //# sourceMappingURL=suspend.d.ts.map

package/dist/client/api/suspend.js

@@ -1,15 +1,33 @@
 import { send } from "../rpc/rpc-client.js";
 import { InvalidResponseError } from "../../utils/errors-client.js";
 /**
- * Suspends all active Hyperswarm and Corestore resources
+ * Suspends the SDK runtime: pauses all registered Hyperswarm and Corestore
+ * resources and engages the lifecycle gate so non-lifecycle operations are
+ * blocked until `resume()` is called.
  *
- * Idempotent — calling while already suspended is a no-op.
+ * Safe to call from any lifecycle state — `suspend()` is never blocked by the
+ * lifecycle gate (along with `resume()` and `state()`). Idempotent.
  *
- * @throws {RPCError} When one or more resources fail to suspend (partial failure).
+ * After `suspend()` resolves, runtime state is `"suspended"` and any non-
+ * lifecycle SDK operation throws `LifecycleOperationBlockedError` until
+ * `resume()` is called.
+ *
+ * In-flight operations started before suspend:
+ *   - P2P / Hyperdrive downloads: stall cleanly, continue after `resume()`
+ *   - HTTP downloads: bypass suspend entirely (bytes keep flowing)
+ *   - Local native inference: runs to completion regardless
+ *   - Delegated reply RPCs: stall, then auto-recover after `resume()`
+ *     (subject to delegate `timeout`)
+ *   - Delegated stream RPCs: severed, consumer iterator hangs silently;
+ *     re-issue after `resume()` works normally.
+ *
+ * @throws {RPCError} When one or more resources fail to suspend. The runtime
+ *   still commits to `"suspended"` so callers can recover with `resume()`.
  *
  * @example
  * // Background handler
  * await suspend();
+ * console.log(await state()); // "suspended"
  */
 export async function suspend() {
     const response = await send({ type: "suspend" });

package/dist/client/api/text-to-speech.d.ts

@@ -1,7 +1,65 @@
-import { type TtsClientParams, type RPCOptions } from "../../schemas/index";
-export declare function textToSpeech(params: TtsClientParams, options?: RPCOptions): {
-    bufferStream: AsyncGenerator<number>;
-    buffer: Promise<number[]>;
-    done: Promise<boolean>;
-};
+import { type TtsClientParamsInput, type RPCOptions, type TtsResponse, type TextToSpeechStreamClientParams, type TextToSpeechStreamSession, type TextToSpeechStreamResult } from "../../schemas/index";
+/**
+ * Fan-out queue that lets multiple consumers iterate the same TTS response
+ * stream independently. Items are retained only until every active subscriber
+ * has consumed them, then trimmed from the queue.
+ *
+ * The source is injected as an `AsyncIterable<TtsResponse>` so this class can
+ * be unit-tested directly against the real implementation (without mocking
+ * the RPC layer). Production callsites adapt `streamRpc(...)` via
+ * `ttsResponseSource()` below.
+ *
+ * Exported for test use; not part of the public SDK surface.
+ */
+export declare class TtsMulticast {
+    private readonly queue;
+    private readonly waiters;
+    private readonly subscriberIndexes;
+    private ended;
+    private fatal;
+    private readonly resolvePumpDone;
+    private readonly rejectPumpDone;
+    readonly done: Promise<boolean>;
+    constructor(source: AsyncIterable<TtsResponse>);
+    subscribe(): AsyncGenerator<TtsResponse>;
+    private notify;
+    private trimConsumed;
+    private unsubscribe;
+    private pump;
+    private drain;
+}
+/**
+ * Converts text to speech audio using a loaded TTS model.
+ *
+ * Three modes selected by `params.stream` and `params.sentenceStream`:
+ *
+ * - `stream: false` (default) — collect all PCM samples and resolve once via
+ *   `result.buffer` (`Promise<number[]>`). `bufferStream` is empty.
+ * - `stream: true` — yield PCM samples through `result.bufferStream`
+ *   (`AsyncGenerator<number>`) as they arrive. `buffer` resolves to an empty
+ *   array.
+ * - `stream: true, sentenceStream: true` — also exposes `result.chunkUpdates`
+ *   (`AsyncGenerator<TtsSentenceChunkUpdate>`) so callers can mux per-sentence
+ *   metadata with the audio. Multiple consumers can iterate the response
+ *   independently via the underlying `TtsMulticast`.
+ *
+ * `result.done` resolves to `true` when synthesis completes cleanly, `false`
+ * if the consumer breaks out before the terminal frame, or rejects on a
+ * pipeline error. Awaiting `done` is safe even when no stream is iterated.
+ *
+ * @param params - TTS request parameters (see `TtsClientParamsInput`).
+ * @param options - Optional RPC options (timeout, profiling, force new connection).
+ * @returns A `TextToSpeechStreamResult` with `bufferStream`, `buffer`, `done`,
+ *          and (when `sentenceStream: true`) `chunkUpdates`.
+ * @throws {TextToSpeechStreamFailedError} When `sentenceStream: true` is paired
+ *         with `stream: false`, or when the underlying RPC stream errors.
+ */
+export declare function textToSpeech(params: TtsClientParamsInput, options?: RPCOptions): TextToSpeechStreamResult;
+/**
+ * Duplex session: write UTF-8 text fragments (e.g. LLM token deltas) via `write`. Each string or
+ * Buffer should be a complete UTF-8 fragment. The worker forwards them to ONNX TTS `runStreaming`
+ * (optional sentence accumulation via request fields). Iterate the session for `TextToSpeechStreamResponse`
+ * lines (PCM in `buffer`, optional `chunkIndex` / `sentenceChunk`) until `done`.
+ */
+export declare function textToSpeechStream(params: TextToSpeechStreamClientParams, options?: RPCOptions): Promise<TextToSpeechStreamSession>;
 //# sourceMappingURL=text-to-speech.d.ts.map