@qvac/sdk 0.5.0 → 0.6.1

package/README.md

@@ -135,11 +135,12 @@ try {
 - Translation: between different languages.
 - Text-to-Speech: TTS via ONNX.
 - Multimodal: via [`llama.cpp`] — i.e., process and understand multiple types of media within the same conversation context.
-- RAG: out-of-the-box retrieval-augmented generation workflow.
+- RAG: retrieval-augmented generation with progress streaming, cancellation, and workspace management.
 - Delegated inference: perform peer-to-peer edge inference via Holepunch stack.
 
 ### Utilities
 
+- Configuration: customize SDK behavior via config files (`qvac.config.json`, `.js`, or `.ts`).
 - Logging: visibility into what's happening inside your models during loading, inference, and other operations.
 - Download Lifecycle: pause and resume model downloads.
 - Blind Relays: establish peer connections through NAT/firewalls by routing traffic through relay nodes.
@@ -180,11 +181,19 @@ bun run examples/path/to/example.ts
 ### Embeddings
 
 - Single and batch embeddings: [`examples/embed-hyperdrive.ts`](examples/embed-hyperdrive.ts)
-- RAG with HyperDB: [`examples/rag/rag-hyperdb.ts`](examples/rag/rag-hyperdb.ts)
-- RAG with workspaces: [`examples/rag/rag-hyperdb-workspaces.ts`](examples/rag/rag-hyperdb-workspaces.ts) _(Demonstrates workspace isolation and chunking)_
-- RAG with LanceDB (desktop only): [`examples/rag/rag-lancedb.ts`](examples/rag/rag-lancedb.ts)
-- RAG with ChromaDB (desktop only): [`examples/rag/rag-chromadb.ts`](examples/rag/rag-chromadb.ts) _(Note: Requires ChromaDB server running)_
-- RAG with SQLite-Vector (desktop only): [`examples/rag/rag-sqlite.ts`](examples/rag/rag-sqlite.ts) _(Note: Uses SQLite-Vector WASM)_
+
+**RAG with HyperDB** (cross-platform):
+
+- Ingest (full pipeline): [`examples/rag/rag-hyperdb/ingest.ts`](examples/rag/rag-hyperdb/ingest.ts)
+- Segregated pipeline: [`examples/rag/rag-hyperdb/pipeline.ts`](examples/rag/rag-hyperdb/pipeline.ts) _(Segregated flow: chunk → embed → save)_
+- Workspaces: [`examples/rag/rag-hyperdb/workspaces.ts`](examples/rag/rag-hyperdb/workspaces.ts) _(Workspace lifecycle: list, close, delete)_
+- Cancellation: [`examples/rag/rag-hyperdb/cancellation.ts`](examples/rag/rag-hyperdb/cancellation.ts) _(progress + cancel)_
+
+**RAG with other backends** (desktop only):
+
+- LanceDB: [`examples/rag/rag-lancedb.ts`](examples/rag/rag-lancedb.ts)
+- ChromaDB: [`examples/rag/rag-chromadb.ts`](examples/rag/rag-chromadb.ts) _(requires ChromaDB server)_
+- SQLite-Vector: [`examples/rag/rag-sqlite.ts`](examples/rag/rag-sqlite.ts) _(SQLite-Vector WASM)_
 
 ### Translation
 
@@ -232,6 +241,29 @@ for await (const log of loggingStream({ id: modelId })) {
 - Log streaming: [`examples/logging-streaming.ts`](examples/logging-streaming.ts)
 - Log with custom file transport: [`examples/logging-file-transport.ts`](examples/logging-file-transport.ts)
 
+### Configuration
+
+Customize SDK behavior using a config file. The SDK auto-discovers `qvac.config.{json,js,ts}` in your project root, or you can specify a path via `QVAC_CONFIG_PATH` environment variable.
+
+**Supported formats:**
+
+- `qvac.config.json` - JSON format
+- `qvac.config.js` - JavaScript with `export default`
+- `qvac.config.ts` - TypeScript with `export default`
+
+**Available options:**
+
+| Option                    | Type       | Default          | Description                                         |
+| ------------------------- | ---------- | ---------------- | --------------------------------------------------- |
+| `cacheDirectory`          | `string`   | `~/.qvac/models` | Where models and assets are stored                  |
+| `swarmRelays`             | `string[]` | `[]`             | Hyperswarm relay public keys for P2P                |
+| `loggerLevel`             | `string`   | `"info"`         | Log level: `"error"`, `"warn"`, `"info"`, `"debug"` |
+| `loggerConsoleOutput`     | `boolean`  | `true`           | Enable/disable console output                       |
+| `httpDownloadConcurrency` | `number`   | `3`              | Max concurrent HTTP downloads for sharded models    |
+| `httpConnectionTimeoutMs` | `number`   | `10000`          | HTTP connection timeout in milliseconds             |
+
+- Config usage example: [`examples/default-config-usage.ts`](examples/default-config-usage.ts)
+
 ### Download Lifecycle
 
 - Pause and resume download: [`examples/download-with-cancel.ts`](examples/download-with-cancel.ts)
@@ -241,18 +273,23 @@ for await (const log of loggingStream({ id: modelId })) {
 Blind relays help establish peer connections through NAT/firewalls by routing traffic through relay nodes.
 
 - Model downloads via Hyperdrive: [`examples/download-with-blind-relays.ts`](./examples/download-with-blind-relays.ts)
-- Delegated inference: You can reuse the same pattern for delegated inference by calling `setConfig({ swarmRelays: [...relayPublicKeys] })` before starting your provider/consumer.
+- Delegated inference: You can reuse the same pattern for delegated inference by adding `swarmRelays` to your config file before starting your provider/consumer.
 
 > [!NOTE]
 > The examples use mock relay keys. For real deployments, you **must** use your own relay servers or trusted public relays.
 
 ### Sharded Models
 
-- Load sharded models from Hyperdrive: [`examples/llamacpp-sharded.ts`](examples/llamacpp-sharded.ts)
-- Load models from local filesystem: [`examples/llamacpp-filesystem.ts`](examples/llamacpp-filesystem.ts)
+Sharded models are split into multiple files following the pattern: `<name>-00001-of-0000X.<ext>`. The SDK automatically downloads and loads all parts with detailed progress tracking.
 
-> [!NOTE]
-> Sharded models automatically download all parts sequentially with detailed progress tracking per shard. For local sharded models, pass the path to the first shard file (e.g., `model-00001-of-00005.gguf`), and remaining shards will be loaded automatically.
+**Supported formats:**
+
+- Archives (`.tar`, `.tar.gz`, `.tgz`): HTTP or local with automatic extraction
+- HTTP sharded URL: pass the download URL of any shard and the SDK will fetch the remaining shards
+- Hyperdrive: use any sharded Hyperdrive model source
+- Local shards: pass the path to any shard file. _(Note: All shards must be in the same directory)_
+
+See: [`examples/llamacpp-sharded.ts`](examples/llamacpp-sharded.ts)
 
 ## Basic flow
 

package/bare-imports.json

@@ -0,0 +1,35 @@
+{
+  "#rpc": {
+    "react-native": "./dist/client/rpc/expo-rpc-client.js",
+    "bare": "./dist/client/rpc/bare-client.js",
+    "default": "./dist/client/rpc/node-rpc-client.js"
+  },
+  "child_process": {
+    "bare": "bare-subprocess",
+    "default": "child_process"
+  },
+  "crypto": {
+    "bare": "bare-crypto",
+    "default": "crypto"
+  },
+  "fs": {
+    "bare": "bare-fs",
+    "default": "fs"
+  },
+  "os": {
+    "bare": "bare-os",
+    "default": "os"
+  },
+  "path": {
+    "bare": "bare-path",
+    "default": "path"
+  },
+  "process": {
+    "bare": "bare-process",
+    "default": "process"
+  },
+  "readline": {
+    "bare": "bare-readline",
+    "default": "readline"
+  }
+}

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

@@ -3,10 +3,11 @@ import { type CancelParams } from "../../schemas/index";
  * Cancels an ongoing operation.
  *
  * @param params - The parameters for the cancellation
- * @param params.operation - The type of operation to cancel ("inference" or "download")
+ * @param params.operation - The type of operation to cancel ("inference", "downloadAsset", or "rag")
  * @param params.modelId - The model ID (required for inference cancellation)
  * @param params.downloadKey - The download key (required for download cancellation)
  * @param params.clearCache - If true, deletes the partial download file (default: false)
+ * @param params.workspace - The RAG workspace to cancel (optional, defaults to "default")
  * @throws {QvacErrorBase} When the response type is invalid or when the cancellation fails
  *
  * @example
@@ -15,11 +16,19 @@ import { type CancelParams } from "../../schemas/index";
  *
  * @example
  * // Pause download (preserves partial file for automatic resume)
- * await cancel({ operation: "download", downloadKey: "download-key" });
+ * await cancel({ operation: "downloadAsset", downloadKey: "download-key" });
  *
  * @example
  * // Cancel download completely (deletes partial file)
- * await cancel({ operation: "download", downloadKey: "download-key", clearCache: true });
+ * await cancel({ operation: "downloadAsset", downloadKey: "download-key", clearCache: true });
+ *
+ * @example
+ * // Cancel RAG operation on default workspace
+ * await cancel({ operation: "rag" });
+ *
+ * @example
+ * // Cancel RAG operation on specific workspace
+ * await cancel({ operation: "rag", workspace: "my-workspace" });
  */
 export declare function cancel(params: CancelParams): Promise<void>;
 //# sourceMappingURL=cancel.d.ts.map

package/dist/client/api/cancel.js

@@ -5,10 +5,11 @@ import { InvalidResponseError, CancelFailedError } from "../../utils/errors-clie
  * Cancels an ongoing operation.
  *
  * @param params - The parameters for the cancellation
- * @param params.operation - The type of operation to cancel ("inference" or "download")
+ * @param params.operation - The type of operation to cancel ("inference", "downloadAsset", or "rag")
  * @param params.modelId - The model ID (required for inference cancellation)
  * @param params.downloadKey - The download key (required for download cancellation)
  * @param params.clearCache - If true, deletes the partial download file (default: false)
+ * @param params.workspace - The RAG workspace to cancel (optional, defaults to "default")
  * @throws {QvacErrorBase} When the response type is invalid or when the cancellation fails
  *
  * @example
@@ -17,11 +18,19 @@ import { InvalidResponseError, CancelFailedError } from "../../utils/errors-clie
  *
  * @example
  * // Pause download (preserves partial file for automatic resume)
- * await cancel({ operation: "download", downloadKey: "download-key" });
+ * await cancel({ operation: "downloadAsset", downloadKey: "download-key" });
  *
  * @example
  * // Cancel download completely (deletes partial file)
- * await cancel({ operation: "download", downloadKey: "download-key", clearCache: true });
+ * await cancel({ operation: "downloadAsset", downloadKey: "download-key", clearCache: true });
+ *
+ * @example
+ * // Cancel RAG operation on default workspace
+ * await cancel({ operation: "rag" });
+ *
+ * @example
+ * // Cancel RAG operation on specific workspace
+ * await cancel({ operation: "rag", workspace: "my-workspace" });
  */
 export async function cancel(params) {
     const request = {

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

@@ -1,12 +1,12 @@
 import { type GetModelInfoParams } from "../../schemas/index";
-export declare const getModelInfo: (params: GetModelInfoParams) => Promise<{
+export declare function getModelInfo(params: GetModelInfoParams): Promise<{
     name: string;
     modelId: string;
     hyperdriveKey: string;
     hyperbeeKey: string;
     expectedSize: number;
     sha256Checksum: string;
-    addon: "llm" | "whisper" | "embeddings" | "nmt" | "tts" | "vad";
+    addon: "llamacpp-completion" | "whispercpp-transcription" | "llamacpp-embedding" | "nmtcpp-translation" | "onnx-tts" | "onnx-ocr" | "vad";
     isCached: boolean;
     isLoaded: boolean;
     cacheFiles: {

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

@@ -1,7 +1,7 @@
 import {} from "../../schemas/index.js";
 import { send } from "../rpc/rpc-client.js";
 import { InvalidResponseError } from "../../utils/errors-client.js";
-export const getModelInfo = async (params) => {
+export async function getModelInfo(params) {
     const request = {
         type: "getModelInfo",
         name: params.name,
@@ -11,4 +11,4 @@ export const getModelInfo = async (params) => {
         throw new InvalidResponseError("getModelInfo");
     }
     return response.modelInfo;
-};
+}

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

@@ -11,7 +11,8 @@ export { translate } from "./translate";
 export { cancel } from "./cancel";
 export { startQVACProvider } from "./provide";
 export { stopQVACProvider } from "./stop-provider";
-export { ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings } from "./rag";
+export { ragChunk, ragIngest, ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings, ragReindex, ragListWorkspaces, ragCloseWorkspace, ragDeleteWorkspace, } from "./rag";
 export { textToSpeech } from "./text-to-speech";
 export { getModelInfo } from "./get-model-info";
+export { ocr } from "./ocr";
 //# sourceMappingURL=index.d.ts.map

package/dist/client/api/index.js

@@ -11,6 +11,7 @@ export { translate } from "./translate.js";
 export { cancel } from "./cancel.js";
 export { startQVACProvider } from "./provide.js";
 export { stopQVACProvider } from "./stop-provider.js";
-export { ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings } from "./rag.js";
+export { ragChunk, ragIngest, ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings, ragReindex, ragListWorkspaces, ragCloseWorkspace, ragDeleteWorkspace, } from "./rag.js";
 export { textToSpeech } from "./text-to-speech.js";
 export { getModelInfo } from "./get-model-info.js";
+export { ocr } from "./ocr.js";

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

@@ -1,11 +1,16 @@
 import { send, stream } from "../rpc/rpc-client.js";
 import { startLoggingStreamForModel } from "../logging-stream-registry.js";
-import { loadModelOptionsToRequestSchema, reloadConfigOptionsToRequestSchema, } from "../../schemas/index.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) {
     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);

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

@@ -0,0 +1,31 @@
+import { type OCRClientParams, type OCRTextBlock, type OCRStats } from "../../schemas/index";
+/**
+ * Performs Optical Character Recognition (OCR) on an image to extract text.
+ *
+ * @param params - The OCR parameters
+ * @param params.modelId - The identifier of the loaded OCR model to use
+ * @param params.image - Image input as either a file path (string) or image buffer
+ * @param params.options - Optional OCR options (e.g., paragraph mode)
+ * @param params.stream - Whether to stream blocks as they're detected (true) or return all at once (false). Defaults to false
+ * @returns Object with blockStream generator, blocks promise, and stats promise
+ * @example
+ * ```typescript
+ * // Non-streaming mode (default) - get all blocks at once
+ * const { blocks } = ocr({ modelId, image: "/path/to/image.png" });
+ * for (const block of await blocks) {
+ *   console.log(block.text, block.bbox, block.confidence);
+ * }
+ *
+ * // Streaming mode - process blocks as they arrive
+ * const { blockStream } = ocr({ modelId, image: imageBuffer, stream: true });
+ * for await (const blocks of blockStream) {
+ *   console.log("Detected:", blocks);
+ * }
+ * ```
+ */
+export declare function ocr(params: OCRClientParams): {
+    blockStream: AsyncGenerator<OCRTextBlock[]>;
+    blocks: Promise<OCRTextBlock[]>;
+    stats: Promise<OCRStats | undefined>;
+};
+//# sourceMappingURL=ocr.d.ts.map

package/dist/client/api/ocr.js

@@ -0,0 +1,88 @@
+import { ocrStreamResponseSchema, } from "../../schemas/index.js";
+import { stream as streamRpc } from "../rpc/rpc-client.js";
+/**
+ * Performs Optical Character Recognition (OCR) on an image to extract text.
+ *
+ * @param params - The OCR parameters
+ * @param params.modelId - The identifier of the loaded OCR model to use
+ * @param params.image - Image input as either a file path (string) or image buffer
+ * @param params.options - Optional OCR options (e.g., paragraph mode)
+ * @param params.stream - Whether to stream blocks as they're detected (true) or return all at once (false). Defaults to false
+ * @returns Object with blockStream generator, blocks promise, and stats promise
+ * @example
+ * ```typescript
+ * // Non-streaming mode (default) - get all blocks at once
+ * const { blocks } = ocr({ modelId, image: "/path/to/image.png" });
+ * for (const block of await blocks) {
+ *   console.log(block.text, block.bbox, block.confidence);
+ * }
+ *
+ * // Streaming mode - process blocks as they arrive
+ * const { blockStream } = ocr({ modelId, image: imageBuffer, stream: true });
+ * for await (const blocks of blockStream) {
+ *   console.log("Detected:", blocks);
+ * }
+ * ```
+ */
+export function ocr(params) {
+    const request = {
+        type: "ocrStream",
+        modelId: params.modelId,
+        image: typeof params.image === "string"
+            ? { type: "filePath", value: params.image }
+            : { type: "base64", value: params.image.toString("base64") },
+        ...(params.options && { options: params.options }),
+    };
+    let ocrStats;
+    let statsResolver = () => { };
+    const statsPromise = new Promise((resolve) => {
+        statsResolver = resolve;
+    });
+    if (params.stream) {
+        const blockStream = (async function* () {
+            for await (const response of streamRpc(request)) {
+                if (response.type === "ocrStream") {
+                    const streamResponse = ocrStreamResponseSchema.parse(response);
+                    if (streamResponse.blocks && streamResponse.blocks.length > 0) {
+                        yield streamResponse.blocks;
+                    }
+                    if (streamResponse.done) {
+                        ocrStats = streamResponse.stats;
+                        statsResolver(ocrStats);
+                    }
+                }
+            }
+        })();
+        return {
+            blockStream,
+            blocks: Promise.resolve([]),
+            stats: statsPromise,
+        };
+    }
+    else {
+        const blockStream = (async function* () {
+            // Empty generator for non-streaming mode
+        })();
+        const blocksPromise = (async () => {
+            let allBlocks = [];
+            for await (const response of streamRpc(request)) {
+                if (response.type === "ocrStream") {
+                    const streamResponse = ocrStreamResponseSchema.parse(response);
+                    if (streamResponse.blocks) {
+                        allBlocks = allBlocks.concat(streamResponse.blocks);
+                    }
+                    if (streamResponse.done) {
+                        ocrStats = streamResponse.stats;
+                        statsResolver(ocrStats);
+                    }
+                }
+            }
+            return allBlocks;
+        })();
+        return {
+            blockStream,
+            blocks: blocksPromise,
+            stats: statsPromise,
+        };
+    }
+}

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

@@ -1,42 +1,237 @@
-import type { RagSearchResult, RagSaveEmbeddingsParams, RagSearchParams, RagDeleteEmbeddingsParams, RagSaveEmbeddingsResult } from "../../schemas/index";
+import type { RagChunkParams, RagDoc, RagIngestParams, RagSaveEmbeddingsParams, RagSaveEmbeddingsResult, RagSearchParams, RagSearchResult, RagDeleteEmbeddingsParams, RagReindexParams, RagReindexResult, RagWorkspaceInfo, RagCloseWorkspaceParams, RagDeleteWorkspaceParams } from "../../schemas/index";
 /**
- * Saves document embeddings in the RAG vector database.
+ * Chunks documents into smaller pieces for embedding.
+ * Part of the segregated flow: ragChunk() → embed() → ragSaveEmbeddings()
  *
- * @param params - The parameters for saving embeddings
- * @param params.modelId - The identifier of the embedding model to use
- * @param params.documents - The documents to embed and save (string or array of strings)
- * @param params.chunk - Whether to chunk the documents before embedding (default: false)
- * @param params.chunkOpts - Options for chunking documents
- * @param params.workspace - Optional workspace for isolated storage
- * @throws {QvacErrorBase} When the response type is invalid or when the operation fails
- * @returns The processed results and dropped indices
- */
-export declare function ragSaveEmbeddings(params: RagSaveEmbeddingsParams): Promise<{
+ * @param params - The parameters for chunking
+ * @param params.documents - Documents to chunk (string or array)
+ * @param params.chunkOpts - Chunking options (chunkSize, chunkOverlap, chunkStrategy)
+ * @returns Array of chunk results with id and content
+ * @throws {RAGChunkFailedError} When the operation fails
+ *
+ * @example
+ * ```typescript
+ * const chunks = await ragChunk({
+ *   documents: ["Long document text here..."],
+ *   chunkOpts: {
+ *     chunkSize: 256,
+ *     chunkOverlap: 50,
+ *     chunkStrategy: "paragraph",
+ *   },
+ * });
+ * ```
+ */
+export declare function ragChunk(params: RagChunkParams): Promise<RagDoc[]>;
+/**
+ * Ingests documents into the RAG vector database.
+ * Full pipeline: chunk → embed → save
+ *
+ * **Workspace lifecycle:** This operation implicitly opens (or creates) the workspace.
+ * The workspace remains open until closed.
+ *
+ * @param params - The parameters for ingestion
+ * @param params.modelId - The embedding model identifier
+ * @param params.documents - Documents to ingest (string or array)
+ * @param params.chunk - Whether to chunk documents (default: true)
+ * @param params.chunkOpts - Chunking 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
+ * @returns Processing results and dropped indices
+ * @throws {RAGSaveFailedError} When the operation fails
+ * @throws {StreamEndedError} When streaming ends unexpectedly (only when using onProgress)
+ *
+ * @example
+ * ```typescript
+ * // Simple ingest
+ * const result = await ragIngest({
+ *   modelId,
+ *   documents: ["Document 1", "Document 2"],
+ * });
+ *
+ * // With progress tracking
+ * const result = await ragIngest({
+ *   modelId,
+ *   documents: ["Document 1", "Document 2"],
+ *   workspace: "my-docs",
+ *   onProgress: (stage, current, total) => {
+ *     console.log(`[${stage}] ${current}/${total}`);
+ *   },
+ * });
+ * ```
+ */
+export declare function ragIngest(params: RagIngestParams): Promise<{
     processed: RagSaveEmbeddingsResult[];
     droppedIndices: number[];
 }>;
+/**
+ * Saves pre-embedded documents to the RAG vector database.
+ * Part of the segregated flow: chunk() → embed() → saveEmbeddings()
+ *
+ * **Workspace lifecycle:** This operation implicitly opens (or creates) the workspace.
+ * The workspace remains open until closed.
+ *
+ * @param params - The parameters for saving
+ * @param params.documents - Pre-embedded documents (must have id, content, embedding, embeddingModelId)
+ * @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
+ * @returns Array of save results
+ * @throws {RAGSaveFailedError} When the operation fails
+ * @throws {StreamEndedError} When streaming ends unexpectedly (only when using onProgress)
+ *
+ * @example
+ * ```typescript
+ * // Segregated flow
+ * const chunks = await ragChunk({ documents: ["text1", "text2"] });
+ * const embeddings = await embed({ modelId, text: chunks.map(c => c.content) });
+ * const embeddedDocs = chunks.map((chunk, i) => ({
+ *   ...chunk,
+ *   embedding: embeddings[i],
+ *   embeddingModelId: modelId,
+ * }));
+ * const result = await ragSaveEmbeddings({
+ *   documents: embeddedDocs,
+ *   workspace: "my-workspace",
+ * });
+ * ```
+ */
+export declare function ragSaveEmbeddings(params: RagSaveEmbeddingsParams): Promise<RagSaveEmbeddingsResult[]>;
 /**
  * Searches for similar documents in the RAG vector database.
  *
+ * **Workspace lifecycle:** This operation requires an existing workspace. If the workspace
+ * doesn't exist, returns an empty array.
+ *
  * @param params - The parameters for searching
  * @param params.modelId - The identifier of the embedding model to use
  * @param params.query - The search query text
  * @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 - Optional workspace for isolated storage
- * @throws {QvacErrorBase} When the response type is invalid or when the operation fails
- * @returns Array of search results with id, content, and score
+ * @param params.workspace - Workspace to search in (default: "default").
+ * @returns Array of search results with id, content, and score. Empty array if workspace doesn't exist.
+ * @throws {RAGSearchFailedError} When the operation fails
+ *
+ * @example
+ * ```typescript
+ * const results = await ragSearch({
+ *   modelId,
+ *   query: "AI and machine learning",
+ *   topK: 5,
+ *   workspace: "my-docs",
+ * });
+ * ```
  */
 export declare function ragSearch(params: RagSearchParams): Promise<RagSearchResult[]>;
 /**
  * Deletes document embeddings from the RAG vector database.
  *
+ * **Workspace lifecycle:** This operation requires an existing workspace.
+ *
  * @param params - The parameters for deleting embeddings
- * @param params.modelId - The identifier of the embedding model (must match workspace model)
  * @param params.ids - Array of document IDs to delete
- * @param params.workspace - Optional workspace for isolated storage
- * @throws {QvacErrorBase} When the response type is invalid or when the operation fails
- * @returns boolean indicating success
+ * @param params.workspace - Workspace to delete from (default: "default")
+ * @throws {RAGDeleteFailedError} When the operation fails or workspace doesn't exist
+ *
+ * @example
+ * ```typescript
+ * await ragDeleteEmbeddings({
+ *   ids: ["doc-1", "doc-2"],
+ *   workspace: "my-docs",
+ * });
+ * ```
+ */
+export declare function ragDeleteEmbeddings(params: RagDeleteEmbeddingsParams): Promise<void>;
+/**
+ * Reindexes the RAG database to optimize search performance.
+ * For HyperDB, this rebalances centroids using k-means clustering.
+ *
+ * **Workspace lifecycle:** This operation requires an existing workspace.
+ *
+ * **Note:** Reindex requires a minimum number of documents to perform clustering.
+ * For HyperDB, this is 16 documents by default. If there are insufficient documents,
+ * `reindexed` will be `false` with `details` explaining the reason.
+ *
+ * @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)
+ * @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)
+ *
+ * @example
+ * ```typescript
+ * // Simple reindex
+ * const result = await ragReindex({
+ *   workspace: "my-docs",
+ * });
+ *
+ * // Check result
+ * if (!result.reindexed) {
+ *   console.log("Reindex skipped:", result.details?.reason);
+ * }
+ *
+ * // With progress tracking
+ * const result = await ragReindex({
+ *   workspace: "my-docs",
+ *   onProgress: (stage, current, total) => {
+ *     console.log(`[${stage}] ${current}/${total}`);
+ *   },
+ * });
+ * ```
+ */
+export declare function ragReindex(params: RagReindexParams): Promise<RagReindexResult>;
+/**
+ * Lists all RAG workspaces with their open status.
+ *
+ * Returns all workspaces that exist on disk. The `open` field indicates whether
+ * the workspace is currently loaded in memory and holding active resources
+ * (Corestore, HyperDB adapter, and possibly a RAG instance).
+ *
+ * @returns Array of workspace info with name and open status
+ * @throws {RAGListWorkspacesFailedError} When the operation fails
+ *
+ * @example
+ * ```typescript
+ * const workspaces = await ragListWorkspaces();
+ * // [{ name: "default", open: true }, { name: "my-docs", open: false }]
+ * ```
+ */
+export declare function ragListWorkspaces(): Promise<RagWorkspaceInfo[]>;
+/**
+ * Closes a RAG workspace, releasing in-memory resources (Corestore, HyperDB adapter, RAG instance).
+ *
+ * **Workspace lifecycle:** Workspaces are implicitly opened.
+ * This function explicitly closes them, releasing memory and file locks. The workspace data
+ * remains on disk unless `deleteOnClose` is set to true.
+ *
+ * @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)
+ * @throws {RAGCloseWorkspaceFailedError} When the operation fails
+ *
+ * @example
+ * ```typescript
+ * // Close a specific workspace
+ * await ragCloseWorkspace({ workspace: "my-docs" });
+ *
+ * // Close and delete in one call
+ * await ragCloseWorkspace({ workspace: "my-docs", deleteOnClose: true });
+ * ```
+ */
+export declare function ragCloseWorkspace(params?: RagCloseWorkspaceParams): Promise<void>;
+/**
+ * Deletes a RAG workspace and all its data.
+ * The workspace must not be currently loaded/in-use.
+ *
+ * @param params - The parameters for deletion
+ * @param params.workspace - Name of the workspace to delete
+ * @throws {RAGDeleteFailedError} When the workspace doesn't exist or is currently loaded
+ *
+ * @example
+ * ```typescript
+ * await ragDeleteWorkspace({ workspace: "my-docs" });
+ * ```
  */
-export declare function ragDeleteEmbeddings(params: RagDeleteEmbeddingsParams): Promise<true>;
+export declare function ragDeleteWorkspace(params: RagDeleteWorkspaceParams): Promise<void>;
 //# sourceMappingURL=rag.d.ts.map