@qvac/sdk 0.5.0 → 0.6.1

package/dist/server/rpc/handlers/rag.d.ts

@@ -1,3 +1,3 @@
-import type { RagRequest, RagResponse } from "../../../schemas/index";
-export declare function handleRag(request: RagRequest): Promise<RagResponse>;
+import type { RagRequest, RagResponse, RagProgressUpdate } from "../../../schemas/index";
+export declare function handleRag(request: RagRequest, onProgress?: (update: RagProgressUpdate) => void): Promise<RagResponse>;
 //# sourceMappingURL=rag.d.ts.map

package/dist/server/rpc/handlers/rag.js

@@ -1,11 +1,43 @@
-import { saveEmbeddings, search, deleteEmbeddings, } from "../../bare/rag-hyperdb/index.js";
-import { getServerLogger } from "../../../logging/index.js";
-const logger = getServerLogger();
-export async function handleRag(request) {
-    try {
-        switch (request.operation) {
-            case "saveEmbeddings": {
-                const result = await saveEmbeddings(request);
+import { chunk, ingest, reindex, saveEmbeddings, search, deleteEmbeddings, listWorkspaces, closeWorkspace, deleteWorkspace, DEFAULT_WORKSPACE, registerRagOperation, unregisterRagOperation, } from "../../bare/rag-hyperdb/index.js";
+function createHandlerOptions(operation, workspace, onProgress) {
+    const signal = registerRagOperation(workspace, operation);
+    const options = { signal };
+    if (onProgress) {
+        options.onProgress = (stage, current, total) => onProgress({
+            type: "rag:progress",
+            operation,
+            workspace,
+            stage,
+            current,
+            total,
+            timestamp: Date.now(),
+        });
+    }
+    return options;
+}
+function omitOnProgress(obj) {
+    const { onProgress, withProgress, ...rest } = obj;
+    void onProgress;
+    void withProgress;
+    return rest;
+}
+export async function handleRag(request, onProgress) {
+    switch (request.operation) {
+        case "chunk": {
+            const chunks = await chunk(request);
+            return {
+                type: "rag",
+                operation: request.operation,
+                success: true,
+                chunks,
+            };
+        }
+        case "ingest": {
+            const workspace = request.workspace ?? DEFAULT_WORKSPACE;
+            const handlerOptions = createHandlerOptions("ingest", workspace, onProgress);
+            const params = omitOnProgress(request);
+            try {
+                const result = await ingest(params, handlerOptions);
                 return {
                     type: "rag",
                     operation: request.operation,
@@ -14,53 +46,85 @@ export async function handleRag(request) {
                     droppedIndices: result.droppedIndices,
                 };
             }
-            case "search": {
-                const results = await search(request);
+            finally {
+                unregisterRagOperation(workspace);
+            }
+        }
+        case "saveEmbeddings": {
+            const workspace = request.workspace ?? DEFAULT_WORKSPACE;
+            const handlerOptions = createHandlerOptions("saveEmbeddings", workspace, onProgress);
+            const params = omitOnProgress(request);
+            try {
+                const processed = await saveEmbeddings(params, handlerOptions);
                 return {
                     type: "rag",
                     operation: request.operation,
                     success: true,
-                    results,
+                    processed,
                 };
             }
-            case "deleteEmbeddings": {
-                const success = await deleteEmbeddings(request);
+            finally {
+                unregisterRagOperation(workspace);
+            }
+        }
+        case "search": {
+            const results = await search(request);
+            return {
+                type: "rag",
+                operation: request.operation,
+                success: true,
+                results,
+            };
+        }
+        case "deleteEmbeddings": {
+            await deleteEmbeddings(request);
+            return {
+                type: "rag",
+                operation: request.operation,
+                success: true,
+            };
+        }
+        case "reindex": {
+            const workspace = request.workspace ?? DEFAULT_WORKSPACE;
+            const handlerOptions = createHandlerOptions("reindex", workspace, onProgress);
+            const params = omitOnProgress(request);
+            try {
+                const result = await reindex(params, handlerOptions);
                 return {
                     type: "rag",
                     operation: request.operation,
-                    success,
+                    success: true,
+                    result,
                 };
             }
+            finally {
+                unregisterRagOperation(workspace);
+            }
         }
-    }
-    catch (error) {
-        logger.error("Error in RAG handler:", error);
-        const baseError = {
-            type: "rag",
-            success: false,
-            error: error instanceof Error ? error.message : "Unknown error",
-        };
-        switch (request.operation) {
-            case "saveEmbeddings":
-                return {
-                    ...baseError,
-                    operation: request.operation,
-                    processed: [],
-                    droppedIndices: [],
-                };
-            case "search":
-                return {
-                    ...baseError,
-                    operation: request.operation,
-                    results: [],
-                };
-            case "deleteEmbeddings":
-                return {
-                    ...baseError,
-                    operation: request.operation,
-                };
-            default:
-                throw error;
+        case "listWorkspaces": {
+            const workspaces = listWorkspaces();
+            return {
+                type: "rag",
+                operation: request.operation,
+                success: true,
+                workspaces,
+            };
+        }
+        case "closeWorkspace": {
+            await closeWorkspace(request);
+            return {
+                type: "rag",
+                operation: request.operation,
+                success: true,
+            };
+        }
+        case "deleteWorkspace": {
+            await deleteWorkspace(request);
+            return {
+                type: "rag",
+                operation: request.operation,
+                success: true,
+            };
         }
     }
 }

package/dist/server/rpc/handlers/text-to-speech.js

@@ -1,4 +1,4 @@
-import { textToSpeech } from "../../bare/addons/tts/index.js";
+import { textToSpeech } from "../../bare/addons/onnx-tts/index.js";
 export async function* handleTextToSpeech(request) {
     const stream = textToSpeech(request);
     for await (const response of stream) {

package/dist/server/rpc/handlers/transcribe-stream.js

@@ -1,4 +1,4 @@
-import { transcribeStream } from "../../bare/addons/whispercpp/index.js";
+import { transcribeStream } from "../../bare/addons/whispercpp-transcription/index.js";
 import { getServerLogger } from "../../../logging/index.js";
 const logger = getServerLogger();
 export async function* handleTranscribeStream(request) {

package/dist/server/rpc/handlers/translate.js

@@ -1,21 +1,12 @@
-import { translate } from "../../bare/addons/translation/index.js";
+import { translate } from "../../bare/addons/nmtcpp-translation/index.js";
 import { getServerLogger } from "../../../logging/index.js";
 const logger = getServerLogger();
 export async function* handleTranslate(request) {
-    const { modelId, text, stream, modelType } = request;
-    const from = request.modelType === "llm" ? request.from : undefined;
-    const to = request.modelType === "llm" ? request.to : undefined;
-    const context = request.modelType === "llm" ? request.context : undefined;
     try {
-        const generator = translate({
-            modelId,
-            text,
-            from,
-            to: to,
-            stream,
-            modelType,
-            context,
-        });
+        // Remove the 'type' field from request and pass the rest to translate
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { type, ...translateParams } = request;
+        const generator = translate(translateParams);
         let stats;
         let done = false;
         let buffer = "";
@@ -27,7 +18,7 @@ export async function* handleTranslate(request) {
             }
             else {
                 buffer += result.value;
-                if (stream) {
+                if (translateParams.stream) {
                     yield {
                         type: "translate",
                         token: result.value,

package/dist/server/utils/archive.d.ts

@@ -0,0 +1,3 @@
+export declare function isArchiveUrl(url: string): boolean;
+export declare function extractAndValidateShardedArchive(archivePath: string, extractDir: string, signal?: AbortSignal): Promise<string>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/server/utils/archive.js

@@ -0,0 +1,171 @@
+import { promises as fsPromises } from "bare-fs";
+import path from "bare-path";
+import fs from "bare-fs";
+import { createGunzip } from "bare-zlib";
+import tarStream from "tar-stream";
+import { detectShardedModel, generateShardFilenames, extractTensorsFromShards, validateShardedModelCache, } from "./shard-utils.js";
+import { ModelLoadFailedError, ArchiveExtractionFailedError, ArchiveUnsupportedTypeError, ArchiveMissingShardsError, DownloadCancelledError, } from "../../utils/errors-server.js";
+import { getServerLogger } from "../../logging/index.js";
+import { SUPPORTED_ARCHIVE_EXTENSIONS, filenameToArchiveTypeSchema, } from "../../schemas/archive.js";
+const logger = getServerLogger();
+// Gzip magic bytes: 1f 8b 08
+const GZIP_MAGIC_0 = 0x1f;
+const GZIP_MAGIC_1 = 0x8b;
+const GZIP_MAGIC_2 = 0x08;
+export function isArchiveUrl(url) {
+    const filename = url.split("/").pop()?.split("?")[0]?.toLowerCase() || "";
+    return SUPPORTED_ARCHIVE_EXTENSIONS.some((ext) => filename.endsWith(ext));
+}
+// Whitelist of model file extensions to extract from archives
+const ALLOWED_MODEL_EXTENSIONS = [".gguf", ".tensors.txt"];
+function isModelFile(entryName) {
+    const basename = path.basename(entryName);
+    // Skip resource forks (._filename)
+    if (basename.startsWith("._")) {
+        return false;
+    }
+    return ALLOWED_MODEL_EXTENSIONS.some((ext) => basename.toLowerCase().endsWith(ext));
+}
+async function isGzip(archivePath) {
+    return new Promise((resolve, reject) => {
+        const stream = fs.createReadStream(archivePath, { start: 0, end: 2 });
+        const chunks = [];
+        stream.on("data", (chunk) => {
+            chunks.push(chunk);
+        });
+        stream.on("end", () => {
+            stream.destroy();
+            const buffer = Buffer.concat(chunks);
+            // Check for gzip magic bytes
+            const isGzipped = buffer[0] === GZIP_MAGIC_0 &&
+                buffer[1] === GZIP_MAGIC_1 &&
+                buffer[2] === GZIP_MAGIC_2;
+            resolve(isGzipped);
+        });
+        stream.on("error", reject);
+    });
+}
+async function extractArchive(archivePath, extractDir, signal) {
+    const parseResult = filenameToArchiveTypeSchema.safeParse(archivePath);
+    const extensionType = parseResult.success ? parseResult.data : null;
+    if (!extensionType) {
+        throw new ArchiveUnsupportedTypeError(archivePath);
+    }
+    if (signal?.aborted) {
+        throw new DownloadCancelledError();
+    }
+    // Detect actual format from magic bytes (extension might be wrong)
+    const isGzipped = await isGzip(archivePath);
+    const actualType = isGzipped ? "tar.gz" : "tar";
+    if (actualType !== extensionType) {
+        logger.warn(`⚠️ Archive extension suggests ${extensionType} but content is ${actualType}`);
+    }
+    await fsPromises.mkdir(extractDir, { recursive: true });
+    await extractTarStream(archivePath, extractDir, isGzipped, signal);
+}
+async function extractTarStream(archivePath, extractDir, useGunzip, signal) {
+    const extract = tarStream.extract();
+    const gunzip = useGunzip ? createGunzip() : null;
+    return new Promise((resolve, reject) => {
+        let aborted = false;
+        let readStream = null;
+        const cleanup = () => {
+            aborted = true;
+            readStream?.destroy();
+            gunzip?.destroy();
+            extract.destroy();
+        };
+        if (signal) {
+            signal.addEventListener("abort", () => {
+                cleanup();
+                reject(new DownloadCancelledError());
+            });
+        }
+        extract.on("entry", (header, stream, next) => {
+            if (aborted) {
+                stream.resume();
+                return;
+            }
+            if (!isModelFile(header.name)) {
+                stream.resume();
+                next();
+                return;
+            }
+            const filePath = path.join(extractDir, header.name);
+            if (header.type === "file") {
+                const dir = path.dirname(filePath);
+                fs.mkdirSync(dir, { recursive: true });
+                const writeStream = fs.createWriteStream(filePath);
+                stream.pipe(writeStream);
+                writeStream.on("finish", next);
+                writeStream.on("error", reject);
+            }
+            else {
+                stream.on("end", next);
+                stream.resume();
+            }
+        });
+        extract.on("finish", resolve);
+        extract.on("error", reject);
+        if (gunzip) {
+            gunzip.on("error", reject);
+        }
+        readStream = fs.createReadStream(archivePath);
+        if (gunzip) {
+            readStream.pipe(gunzip).pipe(extract);
+        }
+        else {
+            readStream.pipe(extract);
+        }
+    });
+}
+export async function extractAndValidateShardedArchive(archivePath, extractDir, signal) {
+    // Check if shards already extracted
+    try {
+        const existingFiles = await fsPromises.readdir(extractDir);
+        const existingShard = existingFiles.find((f) => detectShardedModel(String(f)).isSharded);
+        if (existingShard) {
+            const isComplete = await validateShardedModelCache(extractDir, String(existingShard));
+            if (isComplete) {
+                logger.info(`✅ Archive already extracted: ${extractDir}`);
+                const shardFilenames = generateShardFilenames(String(existingShard));
+                return path.join(extractDir, shardFilenames[0]);
+            }
+            logger.warn(`⚠️ Incomplete extraction found, re-extracting archive`);
+        }
+    }
+    catch {
+        // Directory doesn't exist, proceed with extraction
+    }
+    logger.info(`Extracting archive: ${path.basename(archivePath)}`);
+    try {
+        await extractArchive(archivePath, extractDir, signal);
+    }
+    catch (error) {
+        throw new ArchiveExtractionFailedError(archivePath, error);
+    }
+    const files = await fsPromises.readdir(extractDir);
+    const shardedFile = files.find((f) => detectShardedModel(String(f)).isSharded);
+    if (!shardedFile) {
+        throw new ModelLoadFailedError(`No sharded model files found in archive. Expected pattern: *-00001-of-0000X.*`);
+    }
+    const shardedFileName = String(shardedFile);
+    const shardInfo = detectShardedModel(shardedFileName);
+    if (!shardInfo.baseFilename) {
+        throw new ModelLoadFailedError(`Could not extract base filename from sharded model: ${shardedFileName}`);
+    }
+    const shardFilenames = generateShardFilenames(shardedFileName);
+    for (const shardFilename of shardFilenames) {
+        const filePath = path.join(extractDir, shardFilename);
+        try {
+            await fsPromises.access(filePath);
+        }
+        catch {
+            throw new ArchiveMissingShardsError(shardFilename);
+        }
+    }
+    // Generate tensors.txt if it doesn't exist
+    await extractTensorsFromShards(extractDir, shardedFileName);
+    logger.info(`Archive extracted to ${extractDir} successfully: ${files.length} files`);
+    return path.join(extractDir, shardFilenames[0]);
+}

package/dist/server/utils/audio/decoder.js

@@ -52,12 +52,12 @@ export async function decodeAudioToStream(inputPath, audioFormat = "s16le") {
                 }
             }
         })
-            .onError((errorMessage) => {
+            .onError((error) => {
             if (!hasEnded) {
                 hasEnded = true;
                 clearTimeout(timeoutId);
                 setImmediate(() => void decoder.unload());
-                outputStream.destroy(new Error(errorMessage));
+                outputStream.destroy(error);
             }
         });
         response.await().catch((error) => {

package/dist/server/utils/cache.d.ts

@@ -1,7 +1,7 @@
-import type { ShardMetadata } from "./shard-utils";
-export declare const getCacheDir: (subDir: string) => string;
-export declare const getModelsCacheDir: () => string;
-export declare const getKVCacheDir: () => string;
+import type { ShardFileMetadata } from "../../schemas/index";
+export declare function getCacheDir(subDir: string): string;
+export declare function getModelsCacheDir(): string;
+export declare function getKVCacheDir(): string;
 /**
  * Get cache directory for sharded model
  * Returns: cache/sharded/<hyperdriveKey>/
@@ -16,5 +16,5 @@ export declare function getShardPath(hyperdriveKey: string, shardFilename: strin
  * Check if all shards exist and are valid (size + checksum check)
  * Returns array of missing/invalid shard indices (0-based)
  */
-export declare function checkShardCompleteness(hyperdriveKey: string, shardFilenames: readonly string[], shardMetadata: readonly ShardMetadata[]): Promise<number[]>;
+export declare function checkShardCompleteness(hyperdriveKey: string, shardFilenames: readonly string[], shardMetadata: readonly ShardFileMetadata[]): Promise<number[]>;
 //# sourceMappingURL=cache.d.ts.map

package/dist/server/utils/cache.js

@@ -5,7 +5,7 @@ import { getConfiguredCacheDir } from "../bare/registry/config-registry.js";
 import { calculateFileChecksum } from "./checksum.js";
 import { getServerLogger } from "../../logging/index.js";
 const logger = getServerLogger();
-export const getCacheDir = (subDir) => {
+export function getCacheDir(subDir) {
     const homeDir = getEnv().HOME_DIR;
     const cacheDir = path.join(homeDir, ".qvac", subDir);
     try {
@@ -15,8 +15,8 @@ export const getCacheDir = (subDir) => {
         logger.error(`Error creating cache directory (${subDir}):`, error instanceof Error ? error.message : String(error));
     }
     return cacheDir;
-};
-export const getModelsCacheDir = () => {
+}
+export function getModelsCacheDir() {
     const configuredDir = getConfiguredCacheDir();
     try {
         fs.mkdirSync(configuredDir, { recursive: true });
@@ -25,10 +25,10 @@ export const getModelsCacheDir = () => {
         logger.error(`Error creating models cache directory:`, error instanceof Error ? error.message : String(error));
     }
     return configuredDir;
-};
-export const getKVCacheDir = () => {
+}
+export function getKVCacheDir() {
     return getCacheDir("kv-cache");
-};
+}
 /**
  * Get cache directory for sharded model
  * Returns: cache/sharded/<hyperdriveKey>/

package/dist/server/utils/config-transform.d.ts

@@ -1,3 +1,3 @@
-import type { ModelType } from "../../schemas/index";
-export declare function transformConfigForReload(modelType: ModelType, config: unknown): unknown;
+import { type ModelTypeInput } from "../../schemas/index";
+export declare function transformConfigForReload(modelType: ModelTypeInput, config: unknown): unknown;
 //# sourceMappingURL=config-transform.d.ts.map

package/dist/server/utils/config-transform.js

@@ -1,6 +1,8 @@
+import { normalizeModelType, ModelType, } from "../../schemas/index.js";
 export function transformConfigForReload(modelType, config) {
-    switch (modelType) {
-        case "whisper": {
+    const canonicalType = normalizeModelType(modelType);
+    switch (canonicalType) {
+        case ModelType.whispercppTranscription: {
             const whisperConfig = config;
             // eslint-disable-next-line @typescript-eslint/no-unused-vars
             const { contextParams, miscConfig, ...whisperParams } = whisperConfig;
@@ -9,10 +11,10 @@ export function transformConfigForReload(modelType, config) {
                 ...(miscConfig && { miscConfig }),
             };
         }
-        case "llm":
-        case "embeddings":
-        case "nmt":
-        case "tts":
+        case ModelType.llamacppCompletion:
+        case ModelType.llamacppEmbedding:
+        case ModelType.nmtcppTranslation:
+        case ModelType.onnxTts:
             // Return as-is for now
             return config;
         default:

package/dist/server/utils/formatting.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generate a short hash (16 characters) from any input string
+ */
+export declare function generateShortHash(input: string): string;
+/**
+ * Calculate progress percentage with bounds checking and consistent formatting
+ * @param current - Current progress value
+ * @param total - Total value
+ * @param decimals - Number of decimal places (default: 2)
+ * @returns Percentage clamped between 0-100 with fixed decimal places
+ */
+export declare function calculatePercentage(current: number, total: number, decimals?: number): number;
+//# sourceMappingURL=formatting.d.ts.map

package/dist/server/utils/formatting.js

@@ -0,0 +1,26 @@
+import crypto from "bare-crypto";
+/**
+ * Generate a short hash (16 characters) from any input string
+ */
+export function generateShortHash(input) {
+    const hash = crypto
+        .createHash("sha256")
+        .update(Buffer.from(input, "utf8"))
+        .digest("hex");
+    return hash.substring(0, 16);
+}
+/**
+ * Calculate progress percentage with bounds checking and consistent formatting
+ * @param current - Current progress value
+ * @param total - Total value
+ * @param decimals - Number of decimal places (default: 2)
+ * @returns Percentage clamped between 0-100 with fixed decimal places
+ */
+export function calculatePercentage(current, total, decimals = 2) {
+    if (total <= 0 || current < 0) {
+        return 0;
+    }
+    const rawPercentage = (current / total) * 100;
+    const clampedPercentage = Math.min(Math.max(rawPercentage, 0), 100);
+    return Number(clampedPercentage.toFixed(decimals));
+}

package/dist/server/utils/gguf-tensor-extractor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Extract tensor names from all GGUF shards and write to {baseFilename}.tensors.txt
+ * Required for sharded models to enable incremental/async loading
+ * @throws ModelLoadFailedError if any shard fails extraction
+ */
+export declare function extractAndWriteTensorsFile(shardDir: string, shardFilenames: string[], baseFilename: string): Promise<string>;
+/**
+ * Check if a file has a valid GGUF header structure.
+ * Returns true if the header parses successfully and contains tensor metadata.
+ *
+ * NOTE: This only validates the header structure, NOT that tensor data exists.
+ * A file can have a valid header but be incomplete.
+ */
+export declare function hasValidGGUFHeader(filePath: string): Promise<boolean>;
+//# sourceMappingURL=gguf-tensor-extractor.d.ts.map