@qvac/sdk 0.1.0-dev.1760648187.328e967

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

@@ -0,0 +1,42 @@
+import type { RagSearchResult, RagSaveEmbeddingsParams, RagSearchParams, RagDeleteEmbeddingsParams, RagSaveEmbeddingsResult } from "../../schemas/index";
+/**
+ * Saves document embeddings in the RAG vector database.
+ *
+ * @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[];
+}>;
+/**
+ * Searches for similar documents in the RAG vector database.
+ *
+ * @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 {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): Promise<RagSearchResult[]>;
+/**
+ * Deletes document embeddings from the RAG vector database.
+ *
+ * @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 {Error} When the response type is invalid or when the operation fails
+ * @returns boolean indicating success
+ */
+export declare function ragDeleteEmbeddings(params: RagDeleteEmbeddingsParams): Promise<true>;
+//# sourceMappingURL=rag.d.ts.map

package/dist/client/api/rag.js

@@ -0,0 +1,97 @@
+import { send } from "../rpc/rpc-client.js";
+// ============== Save Embeddings ==============
+/**
+ * Saves document embeddings in the RAG vector database.
+ *
+ * @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 async function ragSaveEmbeddings(params) {
+    const request = {
+        type: "rag",
+        operation: "saveEmbeddings",
+        ...params,
+    };
+    const response = await send(request);
+    if (response.type !== "rag") {
+        throw new Error("Invalid response type");
+    }
+    if (!response.success) {
+        throw new Error(response.error ?? "Failed to save embeddings");
+    }
+    if (response.operation !== "saveEmbeddings") {
+        throw new Error("Invalid operation in response");
+    }
+    return {
+        processed: response.processed,
+        droppedIndices: response.droppedIndices,
+    };
+}
+// ============== Search ==============
+/**
+ * Searches for similar documents in the RAG vector database.
+ *
+ * @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 {Error} When the response type is invalid or when the operation fails
+ * @returns Array of search results with id, content, and score
+ */
+export async function ragSearch(params) {
+    const request = {
+        type: "rag",
+        operation: "search",
+        ...params,
+        topK: params.topK ?? 5,
+        n: params.n ?? 3,
+    };
+    const response = await send(request);
+    if (response.type !== "rag") {
+        throw new Error("Invalid response type");
+    }
+    if (!response.success) {
+        throw new Error(response.error ?? "Failed to search");
+    }
+    if (response.operation !== "search") {
+        throw new Error("Invalid operation in response");
+    }
+    return response.results;
+}
+// ============== Delete Embeddings ==============
+/**
+ * Deletes document embeddings from the RAG vector database.
+ *
+ * @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 {Error} When the response type is invalid or when the operation fails
+ * @returns boolean indicating success
+ */
+export async function ragDeleteEmbeddings(params) {
+    const request = {
+        type: "rag",
+        operation: "deleteEmbeddings",
+        ...params,
+    };
+    const response = await send(request);
+    if (response.type !== "rag") {
+        throw new Error("Invalid response type");
+    }
+    if (!response.success) {
+        throw new Error(response.error ?? "Failed to delete embeddings");
+    }
+    if (response.operation !== "deleteEmbeddings") {
+        throw new Error("Invalid operation in response");
+    }
+    return response.success;
+}

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

@@ -0,0 +1,24 @@
+import { type TranscribeClientParams } from "../../schemas/index";
+/**
+ * This function streams audio transcription results in real-time, yielding
+ * text chunks as they become available from the model.
+ *
+ * @param params - The arguments for the transcription
+ * @param params.modelId - The identifier of the transcription model to use
+ * @param params.audioChunk - Audio input as either a file path (string) or audio buffer
+ * @yields {string} Text chunks as they are transcribed
+ * @throws {Error} When transcription fails with an error message
+ */
+export declare function transcribeStream(params: TranscribeClientParams): AsyncGenerator<string, void, unknown>;
+/**
+ * This function provides a simple interface for transcribing audio by
+ * collecting all streaming results into a single string response.
+ *
+ * @param params - The arguments for the transcription
+ * @param params.modelId - The identifier of the transcription model to use
+ * @param params.audioChunk - Audio input as either a file path (string) or audio buffer
+ * @returns {Promise<string>} The complete transcribed text
+ * @throws {Error} When transcription fails (propagated from transcribeStream)
+ */
+export declare function transcribe(params: TranscribeClientParams): Promise<string>;
+//# sourceMappingURL=transcribe.d.ts.map

package/dist/client/api/transcribe.js

@@ -0,0 +1,52 @@
+import { transcribeStreamResponseSchema, } from "../../schemas/index.js";
+import { stream } from "../rpc/rpc-client.js";
+/**
+ * This function streams audio transcription results in real-time, yielding
+ * text chunks as they become available from the model.
+ *
+ * @param params - The arguments for the transcription
+ * @param params.modelId - The identifier of the transcription model to use
+ * @param params.audioChunk - Audio input as either a file path (string) or audio buffer
+ * @yields {string} Text chunks as they are transcribed
+ * @throws {Error} When transcription fails with an error message
+ */
+export async function* transcribeStream(params) {
+    const request = {
+        type: "transcribeStream",
+        modelId: params.modelId,
+        audioChunk: typeof params.audioChunk === "string"
+            ? params.audioChunk // File path - send directly
+            : params.audioChunk.toString("base64"), // Buffer - encode to base64
+    };
+    for await (const response of stream(request)) {
+        if (response.type === "transcribeStream") {
+            const streamResponse = transcribeStreamResponseSchema.parse(response);
+            if (streamResponse.error) {
+                throw new Error(`Transcription failed: ${streamResponse.error}`);
+            }
+            if (streamResponse.text) {
+                yield streamResponse.text;
+            }
+            if (streamResponse.done) {
+                break;
+            }
+        }
+    }
+}
+/**
+ * This function provides a simple interface for transcribing audio by
+ * collecting all streaming results into a single string response.
+ *
+ * @param params - The arguments for the transcription
+ * @param params.modelId - The identifier of the transcription model to use
+ * @param params.audioChunk - Audio input as either a file path (string) or audio buffer
+ * @returns {Promise<string>} The complete transcribed text
+ * @throws {Error} When transcription fails (propagated from transcribeStream)
+ */
+export async function transcribe(params) {
+    let fullText = "";
+    for await (const textChunk of transcribeStream(params)) {
+        fullText += textChunk;
+    }
+    return fullText;
+}

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

@@ -0,0 +1,47 @@
+import { type TranslateClientParams, type TranslationStats } from "../../schemas/index";
+/**
+ * Translates text from one language to another using a specified translation model.
+ * Supports both NMT (Neural Machine Translation) and LLM models.
+ *
+ * @param params - Translation configuration object
+ * @param params.modelId - The identifier of the translation model to use
+ * @param params.text - The input text to translate
+ * @param params.from - Source language code (optional)
+ * @param params.to - Target language code
+ * @param params.stream - Whether to stream tokens (true) or return complete response (false). Defaults to true.
+ * @returns Object with tokenStream generator and text/stats properties
+ * @throws {Error} When translation fails with an error message or when language detection fails
+ * @example
+ * ```typescript
+ * // Streaming mode (default)
+ * const result = translate({
+ *   modelId: "modelId",
+ *   text: "Hello world",
+ *   from: "en",
+ *   to: "es"
+ *   modelType: "llm",
+ * });
+ *
+ * for await (const token of result.tokenStream) {
+ *   console.log(token);
+ * }
+ *
+ * // Non-streaming mode
+ * const response = translate({
+ *   modelId: "modelId",
+ *   text: "Hello world",
+ *   from: "en",
+ *   to: "es"
+ *   modelType: "llm",
+ *   stream: false,
+ * });
+ *
+ * console.log(await response.text);
+ * ```
+ */
+export declare function translate(params: TranslateClientParams): {
+    tokenStream: AsyncGenerator<string>;
+    stats: Promise<TranslationStats | undefined>;
+    text: Promise<string>;
+};
+//# sourceMappingURL=translate.d.ts.map

package/dist/client/api/translate.js

@@ -0,0 +1,114 @@
+import { stream as streamRpc } from "../rpc/rpc-client.js";
+import { translateResponseSchema, } from "../../schemas/index.js";
+import { detectOne } from "@qvac/langdetect-text";
+/**
+ * Translates text from one language to another using a specified translation model.
+ * Supports both NMT (Neural Machine Translation) and LLM models.
+ *
+ * @param params - Translation configuration object
+ * @param params.modelId - The identifier of the translation model to use
+ * @param params.text - The input text to translate
+ * @param params.from - Source language code (optional)
+ * @param params.to - Target language code
+ * @param params.stream - Whether to stream tokens (true) or return complete response (false). Defaults to true.
+ * @returns Object with tokenStream generator and text/stats properties
+ * @throws {Error} When translation fails with an error message or when language detection fails
+ * @example
+ * ```typescript
+ * // Streaming mode (default)
+ * const result = translate({
+ *   modelId: "modelId",
+ *   text: "Hello world",
+ *   from: "en",
+ *   to: "es"
+ *   modelType: "llm",
+ * });
+ *
+ * for await (const token of result.tokenStream) {
+ *   console.log(token);
+ * }
+ *
+ * // Non-streaming mode
+ * const response = translate({
+ *   modelId: "modelId",
+ *   text: "Hello world",
+ *   from: "en",
+ *   to: "es"
+ *   modelType: "llm",
+ *   stream: false,
+ * });
+ *
+ * console.log(await response.text);
+ * ```
+ */
+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 Error("Could not detect the source language. Please specify the 'from' parameter explicitly.");
+            }
+            sourceLanguage = detected.language;
+        }
+    }
+    const request = {
+        type: "translate",
+        ...params,
+        ...(params.modelType === "llm" && {
+            from: sourceLanguage,
+        }),
+    };
+    let stats;
+    let statsResolver = () => { };
+    const statsPromise = new Promise((resolve) => {
+        statsResolver = resolve;
+    });
+    if (params.stream) {
+        const tokenStream = (async function* () {
+            for await (const response of streamRpc(request)) {
+                if (response.type === "translate") {
+                    const streamResponse = translateResponseSchema.parse(response);
+                    if (!streamResponse.done) {
+                        yield streamResponse.token;
+                    }
+                    else {
+                        stats = streamResponse.stats;
+                        statsResolver(stats);
+                    }
+                }
+            }
+        })();
+        const textPromise = Promise.resolve("");
+        return {
+            tokenStream,
+            text: textPromise,
+            stats: statsPromise,
+        };
+    }
+    else {
+        const tokenStream = (async function* () {
+            //Empty generator for non-streaming mode
+        })();
+        const textPromise = (async () => {
+            let buffer = "";
+            for await (const response of streamRpc(request)) {
+                if (response.type === "translate") {
+                    const streamResponse = translateResponseSchema.parse(response);
+                    buffer += streamResponse.token;
+                    if (streamResponse.done) {
+                        stats = streamResponse.stats;
+                        statsResolver(stats);
+                    }
+                }
+            }
+            return buffer;
+        })();
+        return {
+            tokenStream,
+            text: textPromise,
+            stats: statsPromise,
+        };
+    }
+}

package/dist/client/api/unload-model.d.ts

@@ -0,0 +1,11 @@
+import { type UnloadModelParams } from "../../schemas/index";
+/**
+ * Unloads a previously loaded model from the server.
+ *
+ * @param params - The parameters for unloading the model
+ * @param params.modelId - The unique identifier of the model to unload
+ * @param params.clearStorage - Whether to clear the storage for the model
+ * @throws {Error} When the response type is invalid or when the unload operation fails
+ */
+export declare function unloadModel(params: UnloadModelParams): Promise<void>;
+//# sourceMappingURL=unload-model.d.ts.map

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

@@ -0,0 +1,26 @@
+import {} from "../../schemas/index.js";
+import { send } from "../rpc/rpc-client.js";
+import { stopLoggingStreamForModel } from "../logging-stream-registry.js";
+/**
+ * Unloads a previously loaded model from the server.
+ *
+ * @param params - The parameters for unloading the model
+ * @param params.modelId - The unique identifier of the model to unload
+ * @param params.clearStorage - Whether to clear the storage for the model
+ * @throws {Error} When the response type is invalid or when the unload operation fails
+ */
+export async function unloadModel(params) {
+    const request = {
+        type: "unloadModel",
+        modelId: params.modelId,
+        clearStorage: params.clearStorage ?? false,
+    };
+    const response = await send(request);
+    if (response.type !== "unloadModel") {
+        throw new Error("Invalid response type");
+    }
+    if (!response.success) {
+        throw new Error("Failed to unload model");
+    }
+    stopLoggingStreamForModel(params.modelId);
+}

package/dist/client/index.d.ts

@@ -0,0 +1,2 @@
+export { send, stream } from "./rpc/rpc-client";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.js

@@ -0,0 +1 @@
+export { send, stream } from "./rpc/rpc-client.js";

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

@@ -0,0 +1,5 @@
+import { type Logger } from "../logging/index";
+export declare function startLoggingStreamForModel(modelId: string, logger: Logger): void;
+export declare function stopLoggingStreamForModel(modelId: string): void;
+export declare function hasActiveStreamForModel(modelId: string): boolean;
+//# sourceMappingURL=logging-stream-registry.d.ts.map

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

@@ -0,0 +1,60 @@
+import {} from "../logging/index.js";
+import { loggingStream } from "./api/logging-stream.js";
+const activeStreams = new Map();
+export function startLoggingStreamForModel(modelId, logger) {
+    if (activeStreams.has(modelId)) {
+        console.warn(`Logging stream already active for model ${modelId}`);
+        return;
+    }
+    const streamIterator = loggingStream({ modelId });
+    activeStreams.set(modelId, { logger, streamIterator });
+    try {
+        void (async () => {
+            try {
+                for await (const logMessage of streamIterator) {
+                    const logLevel = logMessage.level;
+                    switch (logLevel) {
+                        case "error":
+                            logger.error(`[${logMessage.namespace}]`, logMessage.message);
+                            break;
+                        case "warn":
+                            logger.warn(`[${logMessage.namespace}]`, logMessage.message);
+                            break;
+                        case "info":
+                            logger.info(`[${logMessage.namespace}]`, logMessage.message);
+                            break;
+                        case "debug":
+                            logger.debug(`[${logMessage.namespace}]`, logMessage.message);
+                            break;
+                        default:
+                            logger.info(`[${logMessage.namespace}]`, logMessage.message);
+                    }
+                }
+            }
+            catch (error) {
+                console.error(`Logging stream error for model ${modelId}:`, error);
+            }
+            finally {
+                activeStreams.delete(modelId);
+            }
+        })();
+    }
+    catch (error) {
+        console.error(`Failed to start logging stream for model ${modelId}:`, error);
+        activeStreams.delete(modelId);
+        throw error;
+    }
+}
+export function stopLoggingStreamForModel(modelId) {
+    const stream = activeStreams.get(modelId);
+    if (stream) {
+        activeStreams.delete(modelId);
+        // Terminate the stream iterator - this will close the RPC connection
+        // and the server-side async generator will automatically terminate
+        void stream.streamIterator.return(undefined);
+        console.debug(`Stopped logging stream for model ${modelId}`);
+    }
+}
+export function hasActiveStreamForModel(modelId) {
+    return activeStreams.has(modelId);
+}

package/dist/client/rpc/bare-client.d.ts

@@ -0,0 +1,112 @@
+import type { Request, Response } from "../../schemas/index";
+export declare function send<T extends Request>(request: T): Promise<Response>;
+export declare function stream<T extends Request>(request: T): AsyncGenerator<{
+    type: "cancel";
+    success: boolean;
+    error?: string | undefined;
+} | {
+    type: "completionStream";
+    token: string;
+    done?: boolean | undefined;
+    stats?: {
+        timeToFirstToken: number;
+        tokensPerSecond: number;
+    } | undefined;
+    error?: string | undefined;
+} | {
+    type: "modelProgress";
+    downloaded: number;
+    total: number;
+    percentage: number;
+    downloadKey: string;
+} | {
+    type: "loadModel";
+    success: boolean;
+    modelId?: string | undefined;
+    error?: string | undefined;
+} | {
+    type: "downloadAsset";
+    success: boolean;
+    assetId?: string | undefined;
+    error?: string | undefined;
+} | {
+    type: "embed";
+    success: boolean;
+    embedding: number[];
+    error?: string | undefined;
+} | {
+    type: "loggingStream";
+    modelId: string;
+    level: "error" | "warn" | "info" | "debug" | "off";
+    namespace: string;
+    message: string;
+    timestamp: number;
+} | {
+    type: "provide";
+    success: boolean;
+    error?: string | undefined;
+    publicKey?: string | undefined;
+} | {
+    type: "unloadModel";
+    success: boolean;
+    error?: string | undefined;
+} | {
+    type: "pong";
+    number: number;
+} | {
+    type: "transcribeStream";
+    text?: string | undefined;
+    done?: boolean | undefined;
+    error?: string | undefined;
+} | {
+    type: "translate";
+    token: string;
+    done?: boolean | undefined;
+    stats?: {
+        processedTokens: number;
+        processingTime: number;
+    } | undefined;
+    error?: string | undefined;
+} | {
+    type: "error";
+    message: string;
+    stack?: string | undefined;
+    timestamp?: string | undefined;
+    name?: string | undefined;
+    code?: number | undefined;
+    cause?: unknown;
+} | {
+    type: "rag";
+    success: boolean;
+    operation: "saveEmbeddings";
+    processed: {
+        status: "fulfilled" | "rejected";
+        id?: string | undefined;
+        error?: string | undefined;
+    }[];
+    droppedIndices: number[];
+    error?: string | undefined;
+} | {
+    type: "rag";
+    success: boolean;
+    operation: "search";
+    results: {
+        id: string;
+        content: string;
+        score: number;
+    }[];
+    error?: string | undefined;
+} | {
+    type: "rag";
+    success: boolean;
+    operation: "deleteEmbeddings";
+    error?: string | undefined;
+}, void, any>;
+export declare function getRPC(): {
+    request(): {
+        send(payload: string): void;
+        reply(): Promise<Buffer<ArrayBuffer>>;
+        createResponseStream(): AsyncGenerator<Buffer<ArrayBuffer>, void, unknown>;
+    };
+};
+//# sourceMappingURL=bare-client.d.ts.map