@qvac/sdk 0.7.1 → 0.8.1

package/dist/server/rpc/handlers/load-model/http.js

@@ -314,19 +314,20 @@ async function performHttpDownload(url, modelPath, downloadKey, progressCallback
         throw error instanceof Error ? error : new Error(String(error));
     }
 }
-export async function downloadModelFromHttp(url, progressCallback) {
+export async function downloadModelFromHttp(url, progressCallback, hooks) {
     const filename = extractFilenameFromUrl(url);
     if (isArchiveUrl(url)) {
-        return downloadShardedModelFromArchive(url, progressCallback);
+        return downloadShardedModelFromArchive(url, progressCallback, hooks);
     }
     const shardInfo = detectShardedModel(filename);
     if (shardInfo.isSharded && shardInfo.totalShards) {
-        return downloadShardedModelFromHttp(url, progressCallback);
+        return downloadShardedModelFromHttp(url, progressCallback, hooks);
     }
     const downloadKey = createHttpDownloadKey(url);
     const existing = getActiveDownload(downloadKey);
     if (existing) {
         logger.info(`📥 Reusing existing download for: ${downloadKey}`);
+        hooks?.markCacheMiss();
         return existing.promise;
     }
     const cacheDir = getModelsCacheDir();
@@ -339,6 +340,7 @@ export async function downloadModelFromHttp(url, progressCallback) {
             // Check if already cached
             const cachedPath = await validateCachedFile(modelPath, url, abortController.signal);
             if (cachedPath) {
+                hooks?.markCacheHit();
                 if (progressCallback) {
                     try {
                         const stats = await fsPromises.stat(cachedPath);
@@ -360,6 +362,7 @@ export async function downloadModelFromHttp(url, progressCallback) {
                 return cachedPath;
             }
             // Download the file
+            hooks?.markCacheMiss();
             await performHttpDownload(url, modelPath, downloadKey, progressCallback, abortController.signal);
             // Send final 100% progress update
             if (progressCallback) {
@@ -426,7 +429,7 @@ export async function downloadModelFromHttp(url, progressCallback) {
     registerDownload(downloadKey, downloadEntry);
     return downloadPromise;
 }
-async function downloadShardedModelFromHttp(shardUrl, progressCallback) {
+async function downloadShardedModelFromHttp(shardUrl, progressCallback, hooks) {
     const config = getSDKConfig();
     const concurrency = config.httpDownloadConcurrency ?? DEFAULT_CONCURRENCY;
     const { shardUrls: shardInfos, cacheKey } = parsePatternBasedShardUrl(shardUrl);
@@ -435,6 +438,7 @@ async function downloadShardedModelFromHttp(shardUrl, progressCallback) {
     const existing = getActiveDownload(downloadKey);
     if (existing) {
         logger.info(`📥 Reusing existing sharded download for: ${downloadKey}`);
+        hooks?.markCacheMiss();
         return existing.promise;
     }
     const abortController = new AbortController();
@@ -483,6 +487,12 @@ async function downloadShardedModelFromHttp(shardUrl, progressCallback) {
                 }
             }
             logger.info(`📥 ${shardsToDownload.length} of ${shardInfos.length} shards need downloading`);
+            if (shardsToDownload.length === 0) {
+                hooks?.markCacheHit();
+            }
+            else {
+                hooks?.markCacheMiss();
+            }
             await downloadShardsWithConcurrency(shardsToDownload, shardStates, concurrency, abortController.signal, downloadKey, overallTotal, progressCallback);
             logger.info(`✅ All ${shardInfos.length} shards downloaded successfully`);
             await extractTensorsFromShards(shardDir, shardInfos[0].filename);
@@ -523,7 +533,7 @@ async function downloadShardedModelFromHttp(shardUrl, progressCallback) {
     });
     return downloadPromise;
 }
-async function downloadShardedModelFromArchive(archiveUrl, progressCallback) {
+async function downloadShardedModelFromArchive(archiveUrl, progressCallback, hooks) {
     const filename = extractFilenameFromUrl(archiveUrl);
     const sourceHash = generateShortHash(archiveUrl);
     const downloadKey = `http-archive:${sourceHash}`;
@@ -531,6 +541,7 @@ async function downloadShardedModelFromArchive(archiveUrl, progressCallback) {
     const existing = getActiveDownload(downloadKey);
     if (existing) {
         logger.info(`📥 Reusing existing archive download for: ${downloadKey}`);
+        hooks?.markCacheMiss();
         return existing.promise;
     }
     const abortController = new AbortController();
@@ -542,12 +553,14 @@ async function downloadShardedModelFromArchive(archiveUrl, progressCallback) {
             const files = await fsPromises.readdir(extractDir);
             const shardedFile = files.find((f) => detectShardedModel(String(f)).isSharded);
             if (!shardedFile) {
+                hooks?.markCacheMiss();
                 return downloadAndExtractArchive();
             }
             const shardFilename = String(shardedFile);
             const allShardsExist = await checkAllShardsExist(extractDir, shardFilename);
             if (!allShardsExist) {
                 logger.warn(`⚠️ Incomplete shards found, re-downloading archive`);
+                hooks?.markCacheMiss();
                 return downloadAndExtractArchive();
             }
             const shardFilenames = generateShardFilenames(shardFilename);
@@ -555,6 +568,7 @@ async function downloadShardedModelFromArchive(archiveUrl, progressCallback) {
             const isComplete = await validateShardedModelCache(extractDir, shardFilename);
             if (isComplete) {
                 logger.info(`✅ Archive already extracted: ${extractDir}`);
+                hooks?.markCacheHit();
                 if (progressCallback) {
                     progressCallback({
                         type: "modelProgress",
@@ -570,6 +584,7 @@ async function downloadShardedModelFromArchive(archiveUrl, progressCallback) {
             try {
                 await extractTensorsFromShards(extractDir, shardFilename);
                 logger.info(`✅ Tensors extracted successfully`);
+                hooks?.markCacheHit();
                 if (progressCallback) {
                     progressCallback({
                         type: "modelProgress",
@@ -585,6 +600,7 @@ async function downloadShardedModelFromArchive(archiveUrl, progressCallback) {
                 logger.warn(`Failed to extract tensors, will re-download archive`, {
                     error,
                 });
+                hooks?.markCacheMiss();
                 return downloadAndExtractArchive();
             }
         }

package/dist/server/rpc/handlers/load-model/hyperdrive.d.ts

@@ -1,4 +1,5 @@
 import type { ModelProgressUpdate } from "../../../../schemas/index";
+import type { DownloadMetricsHooks } from "./types";
 export declare function deleteCorestoreDirectory(corestoreDir: string): Promise<void>;
-export declare function downloadModelFromHyperdrive(hyperdriveKey: string, modelFileName: string, seed?: boolean, progressCallback?: (progress: ModelProgressUpdate) => void, expectedChecksum?: string): Promise<string>;
+export declare function downloadModelFromHyperdrive(hyperdriveKey: string, modelFileName: string, seed?: boolean, progressCallback?: (progress: ModelProgressUpdate) => void, hooks?: DownloadMetricsHooks, expectedChecksum?: string): Promise<string>;
 //# sourceMappingURL=hyperdrive.d.ts.map

package/dist/server/rpc/handlers/load-model/hyperdrive.js

@@ -6,7 +6,7 @@ import Hyperdrive from "hyperdrive";
 import {} from "bare-stream";
 import { AbortController } from "bare-abort-controller";
 import { getEnv } from "../../../env.js";
-import { getModelsCacheDir, generateShortHash, detectShardedModel, getShardedModelCacheDir, getShardPath, checkShardCompleteness, calculateFileChecksum, extractTensorsFromShards, calculatePercentage, } from "../../../utils/index.js";
+import { getModelsCacheDir, generateShortHash, detectShardedModel, getShardedModelCacheDir, getShardPath, checkShardCompleteness, measureChecksum, extractTensorsFromShards, calculatePercentage, } from "../../../utils/index.js";
 import { getModelBySrc } from "../../../../models/registry/index.js";
 import { getActiveDownload, registerDownload, unregisterDownload, createHyperdriveDownloadKey, shouldClearCache, clearClearCacheFlag, } from "./download-manager.js";
 import { getSDKConfig } from "../../../bare/registry/config-registry.js";
@@ -142,7 +142,7 @@ async function validateFileExistence(drive, file) {
         totalBytes,
     };
 }
-async function validateCachedFile(modelPath, modelFileName, expectedSize, expectedChecksum) {
+async function validateCachedFile(modelPath, modelFileName, expectedSize, expectedChecksum, hooks) {
     try {
         await fsPromises.access(modelPath);
         const localStats = await fsPromises.stat(modelPath);
@@ -153,7 +153,7 @@ async function validateCachedFile(modelPath, modelFileName, expectedSize, expect
             logger.info(`✅ Model cached with correct size: ${modelPath}`);
             // Always validate checksum if provided, even when size matches
             if (expectedChecksum && expectedChecksum.length === 64) {
-                const checksum = await calculateFileChecksum(modelPath);
+                const checksum = await measureChecksum(modelPath, hooks);
                 if (checksum !== expectedChecksum) {
                     throw new ChecksumValidationFailedError(`${modelFileName}. Expected: ${expectedChecksum}. Actual: ${checksum}. File may be corrupted`);
                 }
@@ -170,7 +170,7 @@ async function validateCachedFile(modelPath, modelFileName, expectedSize, expect
         return null;
     }
 }
-async function downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, expectedChecksum, progressCallback, seed, signal) {
+async function downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, expectedChecksum, progressCallback, seed, signal, hooks) {
     // Check if already aborted
     if (signal?.aborted) {
         throw new DownloadCancelledError();
@@ -194,7 +194,7 @@ async function downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdri
             }
             : undefined;
         await downloadAndValidateFile(setup.drive, modelFileName, modelPath, 0, // Size will be determined from drive
-        expectedChecksum, progressContext, signal);
+        expectedChecksum, progressContext, signal, hooks);
         logger.info(`✅ Model downloaded successfully to ${modelPath}`);
         // Send final 100% progress update
         if (progressCallback) {
@@ -244,7 +244,7 @@ async function downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdri
         clearClearCacheFlag(downloadKey);
     }
 }
-async function downloadAndValidateFile(drive, sourceFileName, targetFilePath, expectedSize, expectedChecksum, progressContext, signal) {
+async function downloadAndValidateFile(drive, sourceFileName, targetFilePath, expectedSize, expectedChecksum, progressContext, signal, hooks) {
     const { entry, blobs, targetPath, blocksDownloaded, totalBlocks, totalBytes, } = await validateFileExistence(drive, sourceFileName);
     const blob = entry?.value?.blob;
     if (!blob) {
@@ -316,7 +316,7 @@ async function downloadAndValidateFile(drive, sourceFileName, targetFilePath, ex
         }
         // Validate checksum
         if (expectedChecksum && expectedChecksum.length === 64) {
-            const checksum = await calculateFileChecksum(targetFilePath);
+            const checksum = await measureChecksum(targetFilePath, hooks);
             if (checksum !== expectedChecksum) {
                 await fsPromises.unlink(targetFilePath);
                 throw new ChecksumValidationFailedError(`${path.basename(targetFilePath)}. Expected: ${expectedChecksum}. Actual: ${checksum}`);
@@ -361,7 +361,7 @@ function createManagedDownload(downloadKey, hyperdriveKey, modelFileName, downlo
     registerDownload(downloadKey, downloadEntry);
     return downloadPromise;
 }
-async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileName, shardMetadata, progressCallback, seed, signal) {
+async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileName, shardMetadata, progressCallback, seed, signal, hooks) {
     if (signal?.aborted) {
         throw new DownloadCancelledError();
     }
@@ -374,9 +374,10 @@ async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileNam
     const numberedShardCount = shardInfo.totalShards;
     logger.info(`Downloading sharded model with ${numberedShardCount} numbered shards + ${allFiles.length - numberedShardCount} companion files to ${shardDir}`);
     // Check which files need to be downloaded
-    const invalidIndices = await checkShardCompleteness(hyperdriveKey, allFiles, shardMetadata);
+    const invalidIndices = await checkShardCompleteness(hyperdriveKey, allFiles, shardMetadata, hooks ? (ms) => hooks.addChecksumValidationTimeMs(ms) : undefined);
     if (invalidIndices.length === 0) {
         logger.info(`✅ All ${allFiles.length} files already downloaded and validated`);
+        hooks?.markCacheHit();
         if (progressCallback) {
             const overallTotal = shardMetadata.reduce((sum, shard) => sum + shard.expectedSize, 0);
             const lastFile = allFiles[allFiles.length - 1];
@@ -400,6 +401,7 @@ async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileNam
         return getShardPath(hyperdriveKey, allFiles[0]);
     }
     logger.info(`📥 Need to download ${invalidIndices.length} of ${allFiles.length} files`);
+    hooks?.markCacheMiss();
     // Setup hyperdrive once for all shards
     const corestoreDir = getCorestoreDir(hyperdriveKey);
     const setup = await setupHyperdrive(hyperdriveKey, corestoreDir);
@@ -462,7 +464,7 @@ async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileNam
                     },
                 }
                 : undefined;
-            await downloadAndValidateFile(setup.drive, file, filePath, fileMeta.expectedSize, fileMeta.sha256Checksum, progressContext, signal);
+            await downloadAndValidateFile(setup.drive, file, filePath, fileMeta.expectedSize, fileMeta.sha256Checksum, progressContext, signal, hooks);
             if (signal?.aborted) {
                 throw new DownloadCancelledError();
             }
@@ -516,17 +518,18 @@ async function downloadShardedFilesToFilesystem(hyperdriveKey, firstShardFileNam
     }
     return getShardPath(hyperdriveKey, allFiles[0]);
 }
-export async function downloadModelFromHyperdrive(hyperdriveKey, modelFileName, seed, progressCallback, expectedChecksum) {
+export async function downloadModelFromHyperdrive(hyperdriveKey, modelFileName, seed, progressCallback, hooks, expectedChecksum) {
     const downloadKey = createHyperdriveDownloadKey(hyperdriveKey, modelFileName);
     // Check if already downloading
     const existing = getActiveDownload(downloadKey);
     if (existing) {
+        hooks?.markCacheMiss();
         return existing.promise;
     }
     const shardInfo = detectShardedModel(modelFileName);
     const model = getModelBySrc(modelFileName, hyperdriveKey);
     if (shardInfo.isSharded && model?.shardMetadata) {
-        return createManagedDownload(downloadKey, hyperdriveKey, modelFileName, (signal) => downloadShardedFilesToFilesystem(hyperdriveKey, modelFileName, model.shardMetadata, progressCallback, seed, signal), progressCallback);
+        return createManagedDownload(downloadKey, hyperdriveKey, modelFileName, (signal) => downloadShardedFilesToFilesystem(hyperdriveKey, modelFileName, model.shardMetadata, progressCallback, seed, signal, hooks), progressCallback);
     }
     // Non-sharded model download
     const corestoreDir = getCorestoreDir(hyperdriveKey);
@@ -535,8 +538,9 @@ export async function downloadModelFromHyperdrive(hyperdriveKey, modelFileName,
     const modelPath = path.join(cacheDir, `${sourceHash}_${modelFileName}`);
     // First, check if we already have a valid cached file (only if we have model metadata)
     if (model) {
-        const cachedPath = await validateCachedFile(modelPath, modelFileName, model.expectedSize, expectedChecksum || model.sha256Checksum);
+        const cachedPath = await validateCachedFile(modelPath, modelFileName, model.expectedSize, expectedChecksum || model.sha256Checksum, hooks);
         if (cachedPath) {
+            hooks?.markCacheHit();
             if (progressCallback) {
                 progressCallback({
                     type: "modelProgress",
@@ -553,9 +557,10 @@ export async function downloadModelFromHyperdrive(hyperdriveKey, modelFileName,
             return cachedPath;
         }
     }
+    hooks?.markCacheMiss();
     return createManagedDownload(downloadKey, hyperdriveKey, modelFileName, async (signal) => {
         const checksumToValidate = expectedChecksum || model?.sha256Checksum || "";
-        await downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, checksumToValidate, progressCallback, seed, signal);
+        await downloadSingleFileToFilesystem(modelPath, modelFileName, hyperdriveKey, corestoreDir, downloadKey, checksumToValidate, progressCallback, seed, signal, hooks);
         return modelPath;
     }, progressCallback);
 }

package/dist/server/rpc/handlers/load-model/registry.d.ts

@@ -1,4 +1,5 @@
 import type { ModelProgressUpdate } from "../../../../schemas/index";
+import type { DownloadMetricsHooks } from "./types";
 /**
  * Download a model from the QVAC Registry.
  *
@@ -6,5 +7,5 @@ import type { ModelProgressUpdate } from "../../../../schemas/index";
  * skips the registry metadata sync entirely. Falls back to metadata-based
  * download for unknown models.
  */
-export declare function downloadModelFromRegistry(registryPath: string, registrySource: string, progressCallback?: (progress: ModelProgressUpdate) => void, expectedChecksum?: string): Promise<string>;
+export declare function downloadModelFromRegistry(registryPath: string, registrySource: string, progressCallback?: (progress: ModelProgressUpdate) => void, expectedChecksum?: string, hooks?: DownloadMetricsHooks): Promise<string>;
 //# sourceMappingURL=registry.d.ts.map