@qvac/sdk 0.18.2 → 0.19.0

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

@@ -1,24 +0,0 @@
-import type { LoggingStreamResponse, LoggingParams } from '../../schemas/logging-stream.js';
-/**
- * Opens a logging stream to receive real-time logs.
- *
- * @param params - The arguments for the logging stream
- * @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({ 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}`);
- * }
- * ```
- */
-export declare function loggingStream(params: LoggingParams): AsyncGenerator<LoggingStreamResponse>;
-//# sourceMappingURL=logging-stream.d.ts.map

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

@@ -1,36 +0,0 @@
-import { stream } from '../../client/rpc/rpc-client.js';
-import { InvalidResponseError } from '../../utils/errors-client.js';
-/**
- * Opens a logging stream to receive real-time logs.
- *
- * @param params - The arguments for the logging stream
- * @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({ 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}`);
- * }
- * ```
- */
-export async function* loggingStream(params) {
-    const request = {
-        type: 'loggingStream',
-        ...params
-    };
-    const responseStream = stream(request);
-    for await (const response of responseStream) {
-        if (response.type !== 'loggingStream') {
-            throw new InvalidResponseError('loggingStream');
-        }
-        yield response;
-    }
-}

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

@@ -1,40 +0,0 @@
-import { type OCRClientParams, type OCRTextBlock, type OCRStats } from '../../schemas/index.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
- * // Load an OCR model first. Registry GGUF models resolve their pipeline
- * // and detector automatically:
- * //   EasyOCR (default): OCR_LATIN  (CRAFT detector auto-derived)
- * //   DocTR:             OCR_DOCTR  (DBNet detector auto-derived)
- * const modelId = await loadModel({
- *   modelSrc: OCR_LATIN.src,
- *   modelType: MODEL_TYPES.ggmlOcr,
- * });
- *
- * // 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

@@ -1,97 +0,0 @@
-import { ocrStreamResponseSchema } from '../../schemas/index.js';
-import { stream as streamRpc } from '../../client/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
- * // Load an OCR model first. Registry GGUF models resolve their pipeline
- * // and detector automatically:
- * //   EasyOCR (default): OCR_LATIN  (CRAFT detector auto-derived)
- * //   DocTR:             OCR_DOCTR  (DBNet detector auto-derived)
- * const modelId = await loadModel({
- *   modelSrc: OCR_LATIN.src,
- *   modelType: MODEL_TYPES.ggmlOcr,
- * });
- *
- * // 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/provide.d.ts

@@ -1,24 +0,0 @@
-import { type ProvideParams } from '../../schemas/index.js';
-/**
- * Starts a provider service that offers QVAC capabilities to remote peers.
- *
- * Consumers connect directly to the provider via its public key using
- * `dht.connect(publicKey)`, so no topic or discovery configuration is needed.
- * The provider's keypair (and therefore its public key) can be controlled via
- * the `QVAC_HYPERSWARM_SEED` environment variable.
- *
- * Idempotent: calling more than once while a provider is already running
- * returns the same public key without re-listening on the DHT.
- *
- * @param params - Options object with optional firewall config
- * @param params.firewall - Optional firewall configuration to allow/deny specific public keys
- * @returns A promise that resolves to the provide response containing success status and public key
- * @throws {QvacErrorBase} When the response type is not "provide" or the request fails
- */
-export declare function startQVACProvider(params?: ProvideParams): Promise<{
-    type: "provide";
-    success: boolean;
-    error?: string | undefined;
-    publicKey?: string | undefined;
-}>;
-//# sourceMappingURL=provide.d.ts.map

package/dist/client/api/provide.js

@@ -1,33 +0,0 @@
-import {} from '../../schemas/index.js';
-import { send } from '../../client/rpc/rpc-client.js';
-import { InvalidResponseError, ProviderStartFailedError } from '../../utils/errors-client.js';
-/**
- * Starts a provider service that offers QVAC capabilities to remote peers.
- *
- * Consumers connect directly to the provider via its public key using
- * `dht.connect(publicKey)`, so no topic or discovery configuration is needed.
- * The provider's keypair (and therefore its public key) can be controlled via
- * the `QVAC_HYPERSWARM_SEED` environment variable.
- *
- * Idempotent: calling more than once while a provider is already running
- * returns the same public key without re-listening on the DHT.
- *
- * @param params - Options object with optional firewall config
- * @param params.firewall - Optional firewall configuration to allow/deny specific public keys
- * @returns A promise that resolves to the provide response containing success status and public key
- * @throws {QvacErrorBase} When the response type is not "provide" or the request fails
- */
-export async function startQVACProvider(params = {}) {
-    const request = {
-        type: 'provide',
-        firewall: params.firewall
-    };
-    const response = await send(request);
-    if (response.type !== 'provide') {
-        throw new InvalidResponseError('provide');
-    }
-    if (response.error) {
-        throw new ProviderStartFailedError(response.error);
-    }
-    return response;
-}

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

@@ -1,252 +0,0 @@
-import type { RagChunkParams, RagDoc, RagIngestParams, RagSaveEmbeddingsParams, RagSaveEmbeddingsResult, RagSearchParams, RagSearchResult, RagDeleteEmbeddingsParams, RagReindexParams, RagReindexResult, RagWorkspaceInfo, RagCloseWorkspaceParams, RagDeleteWorkspaceParams, RPCOptions } from '../../schemas/index.js';
-/**
- * Chunks documents into smaller pieces for embedding.
- * Part of the segregated flow: ragChunk() → embed() → ragSaveEmbeddings()
- *
- * @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
- *
- * @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
- * @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)
- *
- * @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<{
-    processed: RagSaveEmbeddingsResult[];
-    droppedIndices: number[];
-}> & {
-    requestId: string;
-};
-/**
- * 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
- * @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)
- *
- * @example
- * ```typescript
- * // Segregated flow
- * const chunks = await ragChunk({ documents: ["text1", "text2"] });
- * const { embedding: 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[]> & {
-    requestId: string;
-};
-/**
- * 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").
- * @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
- *
- * @example
- * ```typescript
- * const results = await ragSearch({
- *   modelId,
- *   query: "AI and machine learning",
- *   topK: 5,
- *   workspace: "my-docs",
- * });
- * ```
- */
-export declare function ragSearch(params: RagSearchParams, options?: RPCOptions): 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.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
- * ```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)
- * @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)
- *
- * @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> & {
-    requestId: string;
-};
-/**
- * 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).
- *
- * @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
- *
- * @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)
- * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
- * @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
- * @param options - Optional RPC options (timeout, profiling, force new connection, etc.).
- * @throws {RAGDeleteFailedError} When the workspace doesn't exist or is currently loaded
- *
- * @example
- * ```typescript
- * await ragDeleteWorkspace({ workspace: "my-docs" });
- * ```
- */
-export declare function ragDeleteWorkspace(params: RagDeleteWorkspaceParams, options?: RPCOptions): Promise<void>;
-//# sourceMappingURL=rag.d.ts.map