@qvac/sdk 0.5.0 → 0.6.1

package/dist/client/api/rag.js

@@ -1,32 +1,122 @@
-import { send } from "../rpc/rpc-client.js";
-import { InvalidResponseError, InvalidOperationError, RAGSaveFailedError, RAGSearchFailedError, RAGDeleteFailedError, } from "../../utils/errors-client.js";
-// ============== Save Embeddings ==============
+import { send, stream } from "../rpc/rpc-client.js";
+import { InvalidResponseError, InvalidOperationError, StreamEndedError, RAGChunkFailedError, RAGSaveFailedError, RAGSearchFailedError, RAGDeleteFailedError, RAGCloseWorkspaceFailedError, RAGListWorkspacesFailedError, } from "../../utils/errors-client.js";
+// ============== Chunk ==============
 /**
- * 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
+ * @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 async function ragSaveEmbeddings(params) {
+export async function ragChunk(params) {
     const request = {
         type: "rag",
-        operation: "saveEmbeddings",
+        operation: "chunk",
         ...params,
     };
     const response = await send(request);
     if (response.type !== "rag") {
         throw new InvalidResponseError("rag");
     }
+    if (!response.success) {
+        throw new RAGChunkFailedError(response.error);
+    }
+    if (response.operation !== "chunk") {
+        throw new InvalidOperationError();
+    }
+    return response.chunks;
+}
+// ============== Ingest ==============
+/**
+ * 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 async function ragIngest(params) {
+    const { onProgress, ...requestParams } = params;
+    const request = {
+        type: "rag",
+        operation: "ingest",
+        ...requestParams,
+        chunk: requestParams.chunk ?? true,
+        withProgress: onProgress ? true : undefined,
+    };
+    if (onProgress) {
+        // Use streaming for progress updates
+        for await (const event of stream(request)) {
+            if (event.type === "rag:progress" && event.operation === "ingest") {
+                const progress = event;
+                onProgress(progress.stage, progress.current, progress.total);
+                continue;
+            }
+            if (event.type === "rag" && event.operation === "ingest") {
+                if (!event.success) {
+                    throw new RAGSaveFailedError(event.error);
+                }
+                return {
+                    processed: event.processed,
+                    droppedIndices: event.droppedIndices,
+                };
+            }
+        }
+        throw new StreamEndedError();
+    }
+    const response = await send(request);
+    if (response.type !== "rag") {
+        throw new InvalidResponseError("rag");
+    }
     if (!response.success) {
         throw new RAGSaveFailedError(response.error);
     }
-    if (response.operation !== "saveEmbeddings") {
+    if (response.operation !== "ingest") {
         throw new InvalidOperationError();
     }
     return {
@@ -34,18 +124,101 @@ export async function ragSaveEmbeddings(params) {
         droppedIndices: response.droppedIndices,
     };
 }
+// ============== SaveEmbeddings ==============
+/**
+ * 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 async function ragSaveEmbeddings(params) {
+    const { onProgress, ...requestParams } = params;
+    const request = {
+        type: "rag",
+        operation: "saveEmbeddings",
+        ...requestParams,
+        withProgress: onProgress ? true : undefined,
+    };
+    if (onProgress) {
+        for await (const event of stream(request)) {
+            if (event.type === "rag:progress" &&
+                event.operation === "saveEmbeddings") {
+                const progress = event;
+                onProgress(progress.stage, progress.current, progress.total);
+                continue;
+            }
+            if (event.type === "rag" && event.operation === "saveEmbeddings") {
+                if (!event.success) {
+                    throw new RAGSaveFailedError(event.error);
+                }
+                return event.processed;
+            }
+        }
+        throw new StreamEndedError();
+    }
+    const response = await send(request);
+    if (response.type !== "rag") {
+        throw new InvalidResponseError("rag");
+    }
+    if (!response.success) {
+        throw new RAGSaveFailedError(response.error);
+    }
+    if (response.operation !== "saveEmbeddings") {
+        throw new InvalidOperationError();
+    }
+    return response.processed;
+}
 // ============== Search ==============
 /**
  * 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 async function ragSearch(params) {
     const request = {
@@ -71,12 +244,20 @@ export async function ragSearch(params) {
 /**
  * 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 async function ragDeleteEmbeddings(params) {
     const request = {
@@ -94,5 +275,183 @@ export async function ragDeleteEmbeddings(params) {
     if (response.operation !== "deleteEmbeddings") {
         throw new InvalidOperationError();
     }
-    return response.success;
+}
+// ============== Reindex ==============
+/**
+ * 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 async function ragReindex(params) {
+    const { onProgress, ...requestParams } = params;
+    const request = {
+        type: "rag",
+        operation: "reindex",
+        ...requestParams,
+        withProgress: onProgress ? true : undefined,
+    };
+    if (onProgress) {
+        for await (const event of stream(request)) {
+            if (event.type === "rag:progress" && event.operation === "reindex") {
+                const progress = event;
+                onProgress(progress.stage, progress.current, progress.total);
+                continue;
+            }
+            if (event.type === "rag" && event.operation === "reindex") {
+                if (!event.success) {
+                    throw new RAGSaveFailedError(event.error);
+                }
+                return event.result;
+            }
+        }
+        throw new StreamEndedError();
+    }
+    const response = await send(request);
+    if (response.type !== "rag") {
+        throw new InvalidResponseError("rag");
+    }
+    if (!response.success) {
+        throw new RAGSaveFailedError(response.error);
+    }
+    if (response.operation !== "reindex") {
+        throw new InvalidOperationError();
+    }
+    return response.result;
+}
+// ============== List Workspaces ==============
+/**
+ * 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 async function ragListWorkspaces() {
+    const request = {
+        type: "rag",
+        operation: "listWorkspaces",
+    };
+    const response = await send(request);
+    if (response.type !== "rag") {
+        throw new InvalidResponseError("rag");
+    }
+    if (!response.success) {
+        throw new RAGListWorkspacesFailedError(response.error);
+    }
+    if (response.operation !== "listWorkspaces") {
+        throw new InvalidOperationError();
+    }
+    return response.workspaces;
+}
+// ============== Close Workspace ==============
+/**
+ * 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 async function ragCloseWorkspace(params) {
+    const request = {
+        type: "rag",
+        operation: "closeWorkspace",
+        ...params,
+    };
+    const response = await send(request);
+    if (response.type !== "rag") {
+        throw new InvalidResponseError("rag");
+    }
+    if (!response.success) {
+        throw new RAGCloseWorkspaceFailedError(response.error);
+    }
+    if (response.operation !== "closeWorkspace") {
+        throw new InvalidOperationError();
+    }
+}
+// ============== Delete Workspace ==============
+/**
+ * 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 async function ragDeleteWorkspace(params) {
+    const request = {
+        type: "rag",
+        operation: "deleteWorkspace",
+        ...params,
+    };
+    const response = await send(request);
+    if (response.type !== "rag") {
+        throw new InvalidResponseError("rag");
+    }
+    if (!response.success) {
+        throw new RAGDeleteFailedError(response.error);
+    }
+    if (response.operation !== "deleteWorkspace") {
+        throw new InvalidOperationError();
+    }
 }

package/dist/client/api/translate.js

@@ -1,5 +1,5 @@
 import { stream as streamRpc } from "../rpc/rpc-client.js";
-import { translateResponseSchema, } from "../../schemas/index.js";
+import { translateResponseSchema, normalizeModelType, ModelType, } from "../../schemas/index.js";
 import { detectOne } from "@qvac/langdetect-text";
 import { TranslationFailedError } from "../../utils/errors-client.js";
 /**
@@ -43,21 +43,20 @@ import { TranslationFailedError } from "../../utils/errors-client.js";
  * ```
  */
 export function translate(params) {
-    let sourceLanguage = params.modelType === "llm" ? params.from : undefined;
-    if (!sourceLanguage) {
-        const modelType = params.modelType;
-        if (modelType === "llm") {
-            const detected = detectOne(params.text);
-            if (detected.code === "und" || detected.language === "Undetermined") {
-                throw new TranslationFailedError("Could not detect the source language. Please specify the 'from' parameter explicitly.");
-            }
-            sourceLanguage = detected.language;
+    const canonicalModelType = normalizeModelType(params.modelType);
+    const isLlm = canonicalModelType === ModelType.llamacppCompletion;
+    let sourceLanguage = isLlm ? params.from : undefined;
+    if (!sourceLanguage && isLlm) {
+        const detected = detectOne(params.text);
+        if (detected.code === "und" || detected.language === "Undetermined") {
+            throw new TranslationFailedError("Could not detect the source language. Please specify the 'from' parameter explicitly.");
         }
+        sourceLanguage = detected.language;
     }
     const request = {
         type: "translate",
         ...params,
-        ...(params.modelType === "llm" && {
+        ...(isLlm && {
             from: sourceLanguage,
         }),
     };

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

@@ -34,6 +34,6 @@ export async function unloadModel(params) {
     if (response.hasActiveModels === false &&
         response.hasActiveProviders === false) {
         logger.info("🧹 No models or providers active, automatically closing RPC connection...");
-        await close();
+        close();
     }
 }

package/dist/client/init-hooks.d.ts

@@ -1,16 +1,17 @@
-import type { QvacConfig } from "../schemas/index";
+import type { QvacConfig, RuntimeContext } from "../schemas/index";
 type ResolveConfigFn = () => Promise<QvacConfig | undefined>;
 interface RPCClient {
     request(command: number): any;
 }
 /**
- * Loads configuration from file and sends it to the worker during initialization.
+ * Initializes SDK configuration and runtime context.
  * Config is loaded once and becomes immutable on the worker side.
  *
  * @param rpc - The RPC client instance
  * @param resolveConfig - Runtime-specific config resolver function
+ * @param runtimeContext - Optional runtime context (platform, device info)
  */
-export declare function initializeConfig(rpc: RPCClient, resolveConfig: ResolveConfigFn): Promise<void>;
+export declare function initializeConfig(rpc: RPCClient, resolveConfig: ResolveConfigFn, runtimeContext?: RuntimeContext): Promise<void>;
 /**
  * Legacy function for backward compatibility
  * @deprecated Use initializeConfig instead

package/dist/client/init-hooks.js

@@ -1,50 +1,59 @@
 import { getClientLogger, setGlobalLogLevel, setGlobalConsoleOutput, } from "../logging/index.js";
 const logger = getClientLogger();
+function applyClientLoggerSettings(config) {
+    if (config.loggerLevel !== undefined) {
+        setGlobalLogLevel(config.loggerLevel);
+    }
+    if (config.loggerConsoleOutput !== undefined) {
+        setGlobalConsoleOutput(config.loggerConsoleOutput);
+    }
+}
+async function sendInitMessage(rpc, config, runtimeContext) {
+    const initMessage = {
+        type: "__init_config",
+        config,
+        runtimeContext,
+    };
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const req = rpc.request(1);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+    req.send(JSON.stringify(initMessage), "utf8");
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+    const response = await req.reply("utf8");
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-argument
+    const parsed = JSON.parse(response.toString());
+    if (!parsed.success) {
+        throw new Error(parsed.error ?? "Unknown error");
+    }
+}
 /**
- * Loads configuration from file and sends it to the worker during initialization.
+ * Initializes SDK configuration and runtime context.
  * Config is loaded once and becomes immutable on the worker side.
  *
  * @param rpc - The RPC client instance
  * @param resolveConfig - Runtime-specific config resolver function
+ * @param runtimeContext - Optional runtime context (platform, device info)
  */
-export async function initializeConfig(rpc, resolveConfig) {
+export async function initializeConfig(rpc, resolveConfig, runtimeContext) {
     const config = await resolveConfig();
-    if (!config) {
-        // No config found - worker will use defaults
+    // Nothing to initialize
+    if (!config && !runtimeContext) {
         return;
     }
-    // Apply logger settings on client
-    if (config.loggerLevel !== undefined) {
-        setGlobalLogLevel(config.loggerLevel);
+    // Apply client-side logger settings
+    if (config) {
+        applyClientLoggerSettings(config);
+        logger.info("📦 Initializing SDK config");
     }
-    if (config.loggerConsoleOutput !== undefined) {
-        setGlobalConsoleOutput(config.loggerConsoleOutput);
+    if (runtimeContext) {
+        logger.info("📱 Runtime context:", runtimeContext);
     }
-    logger.info("📦 Initializing config:", config);
     try {
-        // Send config to worker via internal init message
-        // This bypasses the normal RPC flow since it's part of initialization
-        const initMessage = {
-            type: "__init_config",
-            config,
-        };
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-        const req = rpc.request(1);
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
-        req.send(JSON.stringify(initMessage), "utf8");
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
-        const response = await req.reply("utf8");
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-argument
-        const parsed = JSON.parse(response.toString());
-        if (!parsed.success) {
-            logger.error("❌ Failed to initialize config:", parsed.error);
-        }
-        else {
-            logger.info("✅ Config successfully initialized");
-        }
+        await sendInitMessage(rpc, config, runtimeContext);
+        logger.info("✅ Initialization complete");
     }
     catch (error) {
-        logger.error("❌ Error initializing config:", error);
+        logger.error("❌ Initialization failed:", error);
     }
 }
 /**