@qvac/sdk 0.8.0 → 1.0.0

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

@@ -1,237 +1,42 @@
-import type { RagChunkParams, RagDoc, RagIngestParams, RagSaveEmbeddingsParams, RagSaveEmbeddingsResult, RagSearchParams, RagSearchResult, RagDeleteEmbeddingsParams, RagReindexParams, RagReindexResult, RagWorkspaceInfo, RagCloseWorkspaceParams, RagDeleteWorkspaceParams, RPCOptions } from "../../schemas/index";
+import type { RagSearchResult, RagSaveEmbeddingsParams, RagSearchParams, RagDeleteEmbeddingsParams, RagSaveEmbeddingsResult } from "../../schemas/index";
 /**
- * Chunks documents into smaller pieces for embedding.
- * Part of the segregated flow: ragChunk() → embed() → ragSaveEmbeddings()
+ * Saves document embeddings in the RAG vector database.
  *
- * @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, options?: RPCOptions): 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, options?: RPCOptions): Promise<{
+ * @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 {Error} 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<{
     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, options?: RPCOptions): 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 - 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",
- * });
- * ```
+ * @param params.workspace - Optional workspace for isolated storage
+ * @throws {Error} When the response type is invalid or when the operation fails
+ * @returns Array of search results with id, content, and score
  */
-export declare function ragSearch(params: RagSearchParams, options?: RPCOptions): Promise<RagSearchResult[]>;
+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 - 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, options?: RPCOptions): 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, options?: RPCOptions): 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(options?: RPCOptions): 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, options?: RPCOptions): 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" });
- * ```
+ * @param params.workspace - Optional workspace for isolated storage
+ * @throws {Error} When the response type is invalid or when the operation fails
+ * @returns boolean indicating success
  */
-export declare function ragDeleteWorkspace(params: RagDeleteWorkspaceParams, options?: RPCOptions): Promise<void>;
+export declare function ragDeleteEmbeddings(params: RagDeleteEmbeddingsParams): Promise<true>;
 //# sourceMappingURL=rag.d.ts.map