@qvac/sdk 0.4.1 → 0.6.0

package/dist/client/api/logging-stream.d.ts

@@ -1,16 +1,19 @@
 import type { LoggingStreamResponse, LoggingParams } from "../../schemas/logging-stream";
 /**
- * Opens a logging stream for a specific model to receive real-time logs.
+ * Opens a logging stream to receive real-time logs.
  *
  * @param params - The arguments for the logging stream
- * @param params.modelId - The unique identifier of the model to stream logs for
+ * @param params.id - The unique identifier to stream logs for
  * @returns AsyncGenerator yielding logging stream responses
  * @throws {QvacErrorBase} When the response type is invalid or when the stream fails
  *
  * @example
  * ```typescript
  * // Open a logging stream for a model
- * const logStream = loggingStream({ modelId: 'my-model-id' });
+ * const logStream = loggingStream({ id: 'my-model-id' });
+ *
+ * // Or stream SDK server logs
+ * const sdkLogs = loggingStream({ id: SDK_LOG_ID });
  *
  * for await (const logMessage of logStream) {
  *   console.log(`[${logMessage.level}] ${logMessage.namespace}: ${logMessage.message}`);

package/dist/client/api/logging-stream.js

@@ -1,17 +1,20 @@
 import { stream } from "../rpc/rpc-client.js";
 import { InvalidResponseError } from "../../utils/errors-client.js";
 /**
- * Opens a logging stream for a specific model to receive real-time logs.
+ * Opens a logging stream to receive real-time logs.
  *
  * @param params - The arguments for the logging stream
- * @param params.modelId - The unique identifier of the model to stream logs for
+ * @param params.id - The unique identifier to stream logs for
  * @returns AsyncGenerator yielding logging stream responses
  * @throws {QvacErrorBase} When the response type is invalid or when the stream fails
  *
  * @example
  * ```typescript
  * // Open a logging stream for a model
- * const logStream = loggingStream({ modelId: 'my-model-id' });
+ * const logStream = loggingStream({ id: 'my-model-id' });
+ *
+ * // Or stream SDK server logs
+ * const sdkLogs = loggingStream({ id: SDK_LOG_ID });
  *
  * for await (const logMessage of logStream) {
  *   console.log(`[${logMessage.level}] ${logMessage.namespace}: ${logMessage.message}`);

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