@qvac/sdk 0.7.0 → 0.8.0

package/dist/server/rpc/handle-request.js

@@ -1,32 +1,71 @@
-import { requestSchema, normalizeModelType, } from "../../schemas/index.js";
+import { requestSchema, normalizeModelType, PROFILING_KEY, } from "../../schemas/index.js";
+import { nowMs } from "../../profiling/index.js";
 import { resolveModelConfig } from "../bare/registry/model-config-registry.js";
 import { sendErrorResponse } from "../error-handlers.js";
 import { RPCNoDataReceivedError, RPCUnknownRequestTypeError, } from "../../utils/errors-server.js";
 import { registry } from "./handler-registry.js";
 import { executeHandler, handleInitConfig, isInitConfigMessage, } from "./handler-utils.js";
+import { createServerProfiler } from "./profiling/index.js";
 export async function handleRequest(req) {
+    let profiler;
+    let validationStart = 0;
     try {
         const rawData = req.data?.toString();
         if (!rawData) {
             throw new RPCNoDataReceivedError();
         }
+        // Timing runs unconditionally since we can't know if client
+        // requested profiling until after parsing.
+        const parseStart = nowMs();
         const jsonData = JSON.parse(rawData);
+        const jsonParseMs = nowMs() - parseStart;
         // Handle internal config initialization (bypasses schema)
         if (isInitConfigMessage(jsonData)) {
             handleInitConfig(req, jsonData);
             return;
         }
-        const processedData = applyDeviceDefaultsToRequest(jsonData);
+        const { data: cleanData, profilingMeta } = extractProfilingMeta(jsonData);
+        profiler = createServerProfiler(profilingMeta);
+        profiler.markRequestParsed(jsonParseMs);
+        validationStart = nowMs();
+        const processedData = applyDeviceDefaultsToRequest(cleanData);
         const request = requestSchema.parse(processedData);
+        attachProfilingMetaToRequest(request, profilingMeta);
+        profiler.markRequestValidated(nowMs() - validationStart);
+        validationStart = 0;
         const entry = registry[request.type];
         if (!entry) {
             throw new RPCUnknownRequestTypeError(request.type);
         }
-        await executeHandler(req, request, entry);
+        await executeHandler(req, request, entry, profiler);
     }
     catch (error) {
-        sendErrorResponse(req, error);
+        if (profiler && validationStart > 0) {
+            profiler.markRequestValidated(nowMs() - validationStart);
+        }
+        sendErrorResponse(req, error, profiler);
+    }
+}
+function attachProfilingMetaToRequest(request, profilingMeta) {
+    if (!profilingMeta)
+        return;
+    Object.defineProperty(request, PROFILING_KEY, {
+        value: profilingMeta,
+        enumerable: false,
+        configurable: true,
+        writable: false,
+    });
+}
+function extractProfilingMeta(data) {
+    if (!data || typeof data !== "object" || !(PROFILING_KEY in data)) {
+        return { data, profilingMeta: undefined };
     }
+    const obj = data;
+    const { [PROFILING_KEY]: meta, ...rest } = obj;
+    return {
+        data: rest,
+        profilingMeta: meta,
+    };
 }
 /**
  * Apply device-specific config defaults to loadModel requests before schema parsing.

package/dist/server/rpc/handler-registry.js

@@ -6,6 +6,7 @@ import { handleLoadModelDelegated } from "./handlers/load-model-delegated.js";
 import { handleCompletionStreamDelegated } from "./handlers/completion-stream-delegated.js";
 import { getModelEntry } from "../bare/registry/model-registry.js";
 import { handleUnloadModel } from "./handlers/unload-model.js";
+import { handleUnloadModelDelegated } from "./handlers/unload-model-delegated.js";
 import { handleTranscribeStream } from "./handlers/transcribe-stream.js";
 import { handleEmbed } from "./handlers/embed.js";
 import { handleTranslate } from "./handlers/translate.js";
@@ -35,7 +36,12 @@ function isModelDelegated(request) {
 export const registry = {
     // Simple Reply handlers
     ping: { type: "reply", handler: handlePing },
-    unloadModel: { type: "reply", handler: handleUnloadModel },
+    unloadModel: {
+        type: "reply",
+        handler: handleUnloadModel,
+        delegatedHandler: handleUnloadModelDelegated,
+        isDelegated: isModelDelegated,
+    },
     embed: { type: "reply", handler: handleEmbed },
     cancel: { type: "reply", handler: cancelHandler },
     provide: { type: "reply", handler: provideHandler },

package/dist/server/rpc/handler-utils.d.ts

@@ -1,8 +1,9 @@
 import { type QvacConfig, type Request, type Response, type RuntimeContext } from "../../schemas/index";
 import type RPC from "bare-rpc";
-type ReplyHandler = (request: any) => Promise<Response> | Response;
-type StreamHandler = (request: any) => AsyncGenerator<Response>;
-type ProgressHandler = (request: any, onProgress?: (update: Response) => void) => Promise<Response>;
+import { type ServerProfiler } from "./profiling/index";
+type ReplyHandler = (request: any, ...args: any[]) => Promise<Response> | Response;
+type StreamHandler = (request: any, ...args: any[]) => AsyncGenerator<Response>;
+type ProgressHandler = (request: any, ...args: any[]) => Promise<Response>;
 export type HandlerEntry = {
     type: "reply" | "stream";
     handler: ReplyHandler | StreamHandler | ProgressHandler;
@@ -10,7 +11,7 @@ export type HandlerEntry = {
     isDelegated?: (request: Request) => boolean;
     supportsProgress?: boolean | ((request: Request) => boolean);
 };
-export declare function executeHandler(req: RPC.IncomingRequest, request: Request, entry: HandlerEntry): Promise<void>;
+export declare function executeHandler(req: RPC.IncomingRequest, request: Request, entry: HandlerEntry, profiler: ServerProfiler): Promise<void>;
 type InitConfigMessage = {
     type: "__init_config";
     config: QvacConfig;

package/dist/server/rpc/handler-utils.js

@@ -1,65 +1,106 @@
-import { responseSchema, } from "../../schemas/index.js";
+import { PROFILING_KEY, } from "../../schemas/index.js";
 import { sendErrorResponse, sendStreamErrorResponse, } from "../error-handlers.js";
 import { setSDKConfig } from "../bare/registry/config-registry.js";
 import { setRuntimeContext } from "../bare/registry/runtime-context-registry.js";
-function writeToStream(stream, response) {
-    stream.write(JSON.stringify(responseSchema.parse(response)) + "\n", "utf-8");
+import {} from "./profiling/index.js";
+function getProfilingMetaFromRequest(request) {
+    if (PROFILING_KEY in request) {
+        return request[PROFILING_KEY];
+    }
+    return undefined;
 }
-async function executeReplyHandler(req, request, handler) {
+async function executeReplyHandler(req, request, handler, profiler, isDelegated) {
+    profiler.startHandler();
     try {
-        const response = await handler(request);
-        req.reply(JSON.stringify(responseSchema.parse(response)), "utf-8");
+        let response;
+        if (isDelegated) {
+            const profilingMeta = getProfilingMetaFromRequest(request);
+            response = await handler(request, profilingMeta ? { profilingMeta } : undefined);
+        }
+        else {
+            response = await handler(request);
+        }
+        profiler.endHandler();
+        req.reply(profiler.serialize(response, true), "utf-8");
     }
     catch (error) {
-        sendErrorResponse(req, error);
+        profiler.endHandler();
+        sendErrorResponse(req, error, profiler);
     }
 }
-async function executeStreamHandler(req, request, handler) {
+async function executeStreamHandler(req, request, handler, profiler, isDelegated) {
     const stream = req.createResponseStream();
+    profiler.startHandler();
     try {
-        for await (const response of handler(request)) {
-            stream.write(JSON.stringify(responseSchema.parse(response)) + "\n", "utf-8");
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let generator;
+        if (isDelegated) {
+            const profilingMeta = getProfilingMetaFromRequest(request);
+            generator = handler(request, profilingMeta ? { profilingMeta } : undefined);
+        }
+        else {
+            generator = handler(request);
+        }
+        for await (const response of generator) {
+            stream.write(profiler.serialize(response, false) + "\n", "utf-8");
+        }
+        profiler.endHandler();
+        const trailer = profiler.serialize();
+        if (trailer) {
+            stream.write(trailer + "\n", "utf-8");
         }
         stream.end();
     }
     catch (error) {
-        sendStreamErrorResponse(stream, error);
+        profiler.endHandler();
+        sendStreamErrorResponse(stream, error, profiler);
     }
 }
-async function executeProgressHandler(req, request, handler) {
+async function executeProgressHandler(req, request, handler, profiler, isDelegated) {
     const stream = req.createResponseStream();
+    profiler.startHandler();
+    const progressCallback = (update) => {
+        stream.write(profiler.serialize(update, false) + "\n", "utf-8");
+    };
     try {
-        const response = await handler(request, (update) => writeToStream(stream, update));
-        writeToStream(stream, response);
+        let response;
+        if (isDelegated) {
+            const profilingMeta = getProfilingMetaFromRequest(request);
+            const options = { progressCallback };
+            if (profilingMeta) {
+                options.profilingMeta = profilingMeta;
+            }
+            response = await handler(request, options);
+        }
+        else {
+            response = await handler(request, progressCallback);
+        }
+        profiler.endHandler();
+        stream.write(profiler.serialize(response, true) + "\n", "utf-8");
         stream.end();
     }
     catch (error) {
-        sendStreamErrorResponse(stream, error);
+        profiler.endHandler();
+        sendStreamErrorResponse(stream, error, profiler);
     }
 }
 // Unified handler executor with delegation and progress support
-export async function executeHandler(req, request, entry) {
-    const handler = entry.delegatedHandler && entry.isDelegated?.(request)
-        ? entry.delegatedHandler
-        : entry.handler;
+export async function executeHandler(req, request, entry, profiler) {
+    const isDelegated = !!(entry.delegatedHandler && entry.isDelegated?.(request));
+    const handler = isDelegated ? entry.delegatedHandler : entry.handler;
     const wantsProgress = "withProgress" in request &&
         request.withProgress &&
         (typeof entry.supportsProgress === "function"
             ? entry.supportsProgress(request)
             : entry.supportsProgress);
-    try {
-        if (entry.type === "stream") {
-            await executeStreamHandler(req, request, handler);
-        }
-        else if (wantsProgress) {
-            await executeProgressHandler(req, request, handler);
-        }
-        else {
-            await executeReplyHandler(req, request, handler);
-        }
+    if (entry.type === "stream") {
+        await executeStreamHandler(req, request, handler, profiler, isDelegated);
     }
-    catch (error) {
-        sendErrorResponse(req, error);
+    else if (wantsProgress) {
+        await executeProgressHandler(req, request, handler, profiler, isDelegated);
+    }
+    else {
+        await executeReplyHandler(req, request, handler, profiler, isDelegated);
     }
 }
 export function isInitConfigMessage(data) {

package/dist/server/rpc/handlers/completion-stream-delegated.d.ts

@@ -1,3 +1,5 @@
 import type { CompletionStreamRequest, CompletionStreamResponse } from "../../../schemas/index";
-export declare function handleCompletionStreamDelegated(request: CompletionStreamRequest): AsyncGenerator<CompletionStreamResponse>;
+import type { DelegatedHandlerOptions } from "../profiling/index";
+export type HandleCompletionStreamDelegatedOptions = DelegatedHandlerOptions;
+export declare function handleCompletionStreamDelegated(request: CompletionStreamRequest, options?: HandleCompletionStreamDelegatedOptions): AsyncGenerator<CompletionStreamResponse>;
 //# sourceMappingURL=completion-stream-delegated.d.ts.map

package/dist/server/rpc/handlers/completion-stream-delegated.js

@@ -4,7 +4,8 @@ import { stream } from "../delegate-transport.js";
 import { ModelIsDelegatedError } from "../../../utils/errors-server.js";
 import { getServerLogger } from "../../../logging/index.js";
 const logger = getServerLogger();
-export async function* handleCompletionStreamDelegated(request) {
+export async function* handleCompletionStreamDelegated(request, options) {
+    const { profilingMeta } = options ?? {};
     // Get delegation info from model registry
     const entry = getModelEntry(request.modelId);
     if (!entry?.isDelegated || !entry.delegated) {
@@ -15,8 +16,16 @@ export async function* handleCompletionStreamDelegated(request) {
         logger.debug(`📤 Sending delegated completionStream request to provider: ${providerPublicKey}${timeout ? `, timeout: ${timeout}ms` : ""}`);
         // Create RPC instance for this HyperSwarm peer
         const rpc = await getRPC(topic, providerPublicKey, { timeout });
+        // Build delegate options with profiling metadata
+        const delegateOpts = { peerKey: providerPublicKey };
+        if (profilingMeta) {
+            delegateOpts.profilingMeta = profilingMeta;
+        }
+        if (timeout) {
+            delegateOpts.timeout = timeout;
+        }
         // Use the regular stream function with the HyperSwarm RPC instance
-        const responseStream = stream(request, rpc, { timeout });
+        const responseStream = stream(request, rpc, delegateOpts);
         // Yield each response from the stream
         for await (const response of responseStream) {
             yield response;

package/dist/server/rpc/handlers/download-asset.js

@@ -1,15 +1,67 @@
-import { resolveModelPath } from "./load-model/resolve.js";
+import { PROFILING_KEY, OPERATION_EVENT_KEY, } from "../../../schemas/index.js";
+import { resolveModelPath, resolveModelPathWithStats, } from "./load-model/resolve.js";
+import { nowMs, generateProfileId } from "../../../profiling/clock.js";
 import { getServerLogger } from "../../../logging/index.js";
 const logger = getServerLogger();
 export async function handleDownloadAsset(request, progressCallback) {
     const { assetSrc, seed } = request;
+    const profilingMeta = request[PROFILING_KEY];
+    const profilingEnabled = profilingMeta?.enabled !== false && !!profilingMeta;
     try {
-        await resolveModelPath(assetSrc, progressCallback, seed);
-        return {
+        const totalDownloadStart = profilingEnabled ? nowMs() : 0;
+        let sourceType;
+        let downloadStats;
+        if (profilingEnabled) {
+            const result = await resolveModelPathWithStats(assetSrc, progressCallback, seed);
+            sourceType = result.sourceType;
+            downloadStats = result.downloadStats;
+        }
+        else {
+            await resolveModelPath(assetSrc, progressCallback, seed);
+        }
+        const response = {
             type: "downloadAsset",
             success: true,
             assetId: assetSrc,
         };
+        if (profilingEnabled) {
+            const totalDownloadTimeMs = nowMs() - totalDownloadStart;
+            const profileId = profilingMeta?.id ?? generateProfileId();
+            const gauges = {
+                totalDownloadTime: totalDownloadTimeMs,
+            };
+            if (downloadStats) {
+                if (downloadStats.downloadTimeMs !== undefined) {
+                    gauges["downloadTime"] = downloadStats.downloadTimeMs;
+                }
+                if (downloadStats.totalBytesDownloaded !== undefined) {
+                    gauges["totalBytesDownloaded"] = downloadStats.totalBytesDownloaded;
+                }
+                if (downloadStats.downloadSpeedBps !== undefined) {
+                    gauges["downloadSpeedBps"] = downloadStats.downloadSpeedBps;
+                }
+                if (downloadStats.checksumValidationTimeMs !== undefined) {
+                    gauges["checksumValidationTime"] = downloadStats.checksumValidationTimeMs;
+                }
+            }
+            const tags = {};
+            if (sourceType) {
+                tags["sourceType"] = sourceType;
+            }
+            if (downloadStats?.cacheHit !== undefined) {
+                tags["cacheHit"] = downloadStats.cacheHit ? "true" : "false";
+            }
+            const operationEvent = {
+                op: "downloadAsset",
+                kind: "handler",
+                ms: totalDownloadTimeMs,
+                profileId,
+                gauges: Object.keys(gauges).length > 0 ? gauges : undefined,
+                tags: Object.keys(tags).length > 0 ? tags : undefined,
+            };
+            response[OPERATION_EVENT_KEY] = operationEvent;
+        }
+        return response;
     }
     catch (error) {
         logger.error("Error downloading asset:", error);

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

@@ -0,0 +1,6 @@
+import type { ModelProgressUpdate } from "../../../../schemas/index";
+import type { DownloadResult } from "./types";
+export declare function downloadModelFromHttpWithStats(url: string, progressCallback?: (progress: ModelProgressUpdate) => void): Promise<DownloadResult>;
+export declare function downloadModelFromRegistryWithStats(registryPath: string, registrySource: string, progressCallback?: (progress: ModelProgressUpdate) => void, expectedChecksum?: string): Promise<DownloadResult>;
+export declare function downloadModelFromHyperdriveWithStats(hyperdriveKey: string, modelFileName: string, seed?: boolean, progressCallback?: (progress: ModelProgressUpdate) => void): Promise<DownloadResult>;
+//# sourceMappingURL=download-stats.d.ts.map

package/dist/server/rpc/handlers/load-model/download-stats.js

@@ -0,0 +1,87 @@
+import { downloadModelFromHttp } from "./http.js";
+import { downloadModelFromRegistry } from "./registry.js";
+import { downloadModelFromHyperdrive } from "./hyperdrive.js";
+import { nowMs } from "../../../../profiling/index.js";
+function createStatsCollector() {
+    return {
+        maxBytesDownloaded: 0,
+        startTimeMs: nowMs(),
+        cacheHit: undefined,
+        checksumValidationTimeMsTotal: 0,
+    };
+}
+function createHooks(collector) {
+    return {
+        markCacheHit: () => {
+            if (collector.cacheHit === undefined) {
+                collector.cacheHit = true;
+                collector.maxBytesDownloaded = 0;
+            }
+        },
+        markCacheMiss: () => {
+            collector.cacheHit = false;
+        },
+        addChecksumValidationTimeMs: (durationMs) => {
+            collector.checksumValidationTimeMsTotal += durationMs;
+        },
+    };
+}
+function wrapProgressCallback(collector, originalCallback) {
+    return (progress) => {
+        // Don't track bytes for cache hits (they're not real network transfer)
+        if (collector.cacheHit !== true) {
+            const downloaded = progress.onnxInfo?.overallDownloaded ??
+                progress.shardInfo?.overallDownloaded ??
+                progress.downloaded ??
+                0;
+            collector.maxBytesDownloaded = Math.max(collector.maxBytesDownloaded, downloaded);
+        }
+        originalCallback?.(progress);
+    };
+}
+function computeStats(collector) {
+    const downloadTimeMs = nowMs() - collector.startTimeMs;
+    const totalBytesDownloaded = collector.maxBytesDownloaded;
+    const stats = {};
+    if (collector.cacheHit !== undefined) {
+        stats.cacheHit = collector.cacheHit;
+    }
+    if (collector.checksumValidationTimeMsTotal > 0) {
+        stats.checksumValidationTimeMs = collector.checksumValidationTimeMsTotal;
+    }
+    if (collector.cacheHit === true) {
+        return Object.keys(stats).length > 0 ? stats : undefined;
+    }
+    if (totalBytesDownloaded > 0) {
+        stats.downloadTimeMs = downloadTimeMs;
+        stats.totalBytesDownloaded = totalBytesDownloaded;
+        if (downloadTimeMs > 0) {
+            stats.downloadSpeedBps = (totalBytesDownloaded * 1000) / downloadTimeMs;
+        }
+    }
+    return Object.keys(stats).length > 0 ? stats : undefined;
+}
+export async function downloadModelFromHttpWithStats(url, progressCallback) {
+    const collector = createStatsCollector();
+    const hooks = createHooks(collector);
+    const wrappedCallback = wrapProgressCallback(collector, progressCallback);
+    const path = await downloadModelFromHttp(url, wrappedCallback, hooks);
+    const stats = computeStats(collector);
+    return stats ? { path, stats } : { path };
+}
+export async function downloadModelFromRegistryWithStats(registryPath, registrySource, progressCallback, expectedChecksum) {
+    const collector = createStatsCollector();
+    const hooks = createHooks(collector);
+    const wrappedCallback = wrapProgressCallback(collector, progressCallback);
+    const path = await downloadModelFromRegistry(registryPath, registrySource, wrappedCallback, expectedChecksum, hooks);
+    const stats = computeStats(collector);
+    return stats ? { path, stats } : { path };
+}
+export async function downloadModelFromHyperdriveWithStats(hyperdriveKey, modelFileName, seed, progressCallback) {
+    const collector = createStatsCollector();
+    const hooks = createHooks(collector);
+    const wrappedCallback = wrapProgressCallback(collector, progressCallback);
+    const path = await downloadModelFromHyperdrive(hyperdriveKey, modelFileName, seed, wrappedCallback, hooks);
+    const stats = computeStats(collector);
+    return stats ? { path, stats } : { path };
+}