@qvac/sdk 0.7.0 → 0.8.0

package/dist/profiling/exporters.d.ts

@@ -0,0 +1,10 @@
+/**
+ * JSON, table, and summary export utilities for profiling data.
+ */
+import type { ProfilerExport } from "./types";
+export declare function exportJSON(options?: {
+    includeRecentEvents?: boolean;
+}): ProfilerExport;
+export declare function exportTable(): string;
+export declare function exportSummary(): string;
+//# sourceMappingURL=exporters.d.ts.map

package/dist/profiling/exporters.js

@@ -0,0 +1,236 @@
+/**
+ * JSON, table, and summary export utilities for profiling data.
+ */
+import { getEffectiveConfig, getAggregates, getRecentEvents, } from "./controller.js";
+import { getDroppedCount, getEventCount } from "./aggregator.js";
+import { nowMs, getClockSource, isMonotonic } from "./clock.js";
+export function exportJSON(options) {
+    const config = getEffectiveConfig();
+    const includeRecent = options?.includeRecentEvents ?? true;
+    const result = {
+        config,
+        aggregates: getAggregates(),
+        exportedAt: nowMs(),
+    };
+    if (includeRecent && config.mode === "verbose") {
+        result.recentEvents = getRecentEvents();
+    }
+    return result;
+}
+function aggregateMatchingStats(aggregates, predicate) {
+    const matches = Object.entries(aggregates).filter(([key]) => predicate(key));
+    if (matches.length === 0) {
+        return undefined;
+    }
+    let count = 0;
+    let sum = 0;
+    let min = Infinity;
+    let max = -Infinity;
+    let last = 0;
+    for (const [, stats] of matches) {
+        count += stats.count;
+        sum += stats.sum;
+        if (stats.count > 0) {
+            if (stats.min < min)
+                min = stats.min;
+            if (stats.max > max)
+                max = stats.max;
+            last = stats.last;
+        }
+    }
+    return {
+        count,
+        min: count > 0 ? min : 0,
+        max: count > 0 ? max : 0,
+        avg: count > 0 ? sum / count : 0,
+        sum,
+        last,
+    };
+}
+function formatDuration(ms) {
+    if (ms < 1) {
+        return `${(ms * 1000).toFixed(0)}μs`;
+    }
+    if (ms < 1000) {
+        return `${ms.toFixed(1)}ms`;
+    }
+    if (ms < 60000) {
+        return `${(ms / 1000).toFixed(2)}s`;
+    }
+    return `${(ms / 60000).toFixed(2)}m`;
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes.toFixed(0)} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+function formatThroughput(bps) {
+    if (bps < 1024)
+        return `${bps.toFixed(0)} B/s`;
+    if (bps < 1024 * 1024)
+        return `${(bps / 1024).toFixed(1)} KB/s`;
+    if (bps < 1024 * 1024 * 1024)
+        return `${(bps / (1024 * 1024)).toFixed(2)} MB/s`;
+    return `${(bps / (1024 * 1024 * 1024)).toFixed(2)} GB/s`;
+}
+function formatNumber(n) {
+    if (Number.isInteger(n)) {
+        return n.toLocaleString();
+    }
+    if (n === 0)
+        return "0";
+    if (Math.abs(n) < 0.01)
+        return n.toExponential(2);
+    if (Math.abs(n) < 1)
+        return n.toFixed(3);
+    if (Math.abs(n) < 100)
+        return n.toFixed(2);
+    return n.toFixed(1);
+}
+function detectMetricType(metricName) {
+    const lowerName = metricName.toLowerCase();
+    if (lowerName.includes("bps") || lowerName.includes("speed")) {
+        return "throughput";
+    }
+    if (lowerName.includes("bytes") || lowerName.includes("downloaded") || lowerName.includes("size")) {
+        return "bytes";
+    }
+    if (lowerName.endsWith("time") ||
+        lowerName.endsWith("ms") ||
+        lowerName.endsWith("duration") ||
+        lowerName.includes("ttfb") ||
+        lowerName.includes("latency") ||
+        lowerName.includes("wait") ||
+        lowerName.includes("overhead") ||
+        lowerName.includes("parse") ||
+        lowerName.includes("stringify") ||
+        lowerName.includes("validation") ||
+        lowerName.includes("execution") ||
+        lowerName.includes("serialization") ||
+        lowerName.includes("connection")) {
+        return "duration";
+    }
+    if (lowerName.includes("count") || lowerName.includes("token")) {
+        return "number";
+    }
+    // Default to duration for unknown metrics (most profiling is timing)
+    return "duration";
+}
+function formatMetricValue(value, metricName) {
+    const type = detectMetricType(metricName);
+    switch (type) {
+        case "bytes":
+            return formatBytes(value);
+        case "throughput":
+            return formatThroughput(value);
+        case "number":
+            return formatNumber(value);
+        case "duration":
+        default:
+            return formatDuration(value);
+    }
+}
+function pad(s, len, align = "left") {
+    if (s.length >= len)
+        return s.substring(0, len);
+    const spaces = " ".repeat(len - s.length);
+    return align === "left" ? s + spaces : spaces + s;
+}
+export function exportTable() {
+    const aggregates = getAggregates();
+    const entries = Object.entries(aggregates);
+    if (entries.length === 0) {
+        return "No profiling data recorded.";
+    }
+    const metricWidth = 40;
+    const numWidth = 12;
+    const header = [
+        pad("Metric", metricWidth),
+        pad("Count", numWidth, "right"),
+        pad("Min", numWidth, "right"),
+        pad("Max", numWidth, "right"),
+        pad("Avg", numWidth, "right"),
+        pad("Total", numWidth, "right"),
+    ].join(" | ");
+    const separator = "-".repeat(header.length);
+    const rows = entries
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([metric, stats]) => {
+        return [
+            pad(metric, metricWidth),
+            pad(formatNumber(stats.count), numWidth, "right"),
+            pad(formatMetricValue(stats.min, metric), numWidth, "right"),
+            pad(formatMetricValue(stats.max, metric), numWidth, "right"),
+            pad(formatMetricValue(stats.avg, metric), numWidth, "right"),
+            pad(formatMetricValue(stats.sum, metric), numWidth, "right"),
+        ].join(" | ");
+    });
+    return [separator, header, separator, ...rows, separator].join("\n");
+}
+export function exportSummary() {
+    const aggregates = getAggregates();
+    const config = getEffectiveConfig();
+    const eventCount = getEventCount();
+    const droppedCount = getDroppedCount();
+    const lines = [
+        "=".repeat(60),
+        "PROFILER SUMMARY",
+        "=".repeat(60),
+        "",
+        "Session:",
+        `  Status:        ${config.enabled ? "enabled" : "disabled"}`,
+        `  Mode:          ${config.mode}`,
+        `  Clock:         ${getClockSource()} (monotonic: ${isMonotonic()})`,
+        `  Events:        ${eventCount.toLocaleString()}`,
+        `  Dropped:       ${droppedCount.toLocaleString()}`,
+        "",
+    ];
+    const keyMetrics = [
+        {
+            label: "RPC Total",
+            stats: aggregateMatchingStats(aggregates, (key) => key.endsWith(".totalClientTime")),
+        },
+        {
+            label: "Handler",
+            stats: aggregateMatchingStats(aggregates, (key) => key.endsWith(".server.handlerExecution") || !key.includes(".")),
+        },
+        {
+            label: "Model Load",
+            stats: aggregateMatchingStats(aggregates, (key) => key === "load.totalTime" || key.endsWith(".load.totalTime")),
+        },
+        {
+            label: "Download",
+            stats: aggregateMatchingStats(aggregates, (key) => key === "download.time" || key.endsWith(".download.time")),
+        },
+    ];
+    const hasMetrics = keyMetrics.some((m) => m.stats);
+    if (hasMetrics) {
+        lines.push("Key Metrics:");
+        lines.push("-".repeat(60));
+        lines.push("  " +
+            "Metric".padEnd(18) +
+            "Samples".padStart(10) +
+            "Avg".padStart(12) +
+            "Total".padStart(12));
+        lines.push("-".repeat(60));
+        for (const { label, stats } of keyMetrics) {
+            if (stats) {
+                const name = label.padEnd(18);
+                const samples = String(stats.count).padStart(10);
+                const avg = formatDuration(stats.avg).padStart(12);
+                const total = formatDuration(stats.sum).padStart(12);
+                lines.push(`  ${name}${samples}${avg}${total}`);
+            }
+        }
+    }
+    else {
+        lines.push("No metrics recorded yet.");
+    }
+    lines.push("");
+    lines.push("=".repeat(60));
+    return lines.join("\n");
+}

package/dist/profiling/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * QVAC SDK Profiler
+ *
+ * @example
+ * ```ts
+ * import { profiler } from "@qvac/sdk";
+ *
+ * profiler.enable({ mode: "summary" });
+ * // ... run SDK operations ...
+ * console.log(profiler.exportTable());
+ * profiler.disable();
+ * ```
+ */
+import * as controller from "./controller";
+import type { ProfilerRuntimeOptions, ProfilingEvent, ProfilerExport, AggregatedStats } from "./types";
+export declare const profiler: {
+    enable: (options?: ProfilerRuntimeOptions) => void;
+    disable: () => void;
+    isEnabled: () => boolean;
+    exportJSON: (options?: {
+        includeRecentEvents?: boolean;
+    }) => ProfilerExport;
+    exportTable: () => string;
+    exportSummary: () => string;
+    onRecord: (callback: (event: ProfilingEvent) => void) => () => void;
+    getConfig: () => controller.ResolvedProfilerConfig;
+    getAggregates: () => Record<string, AggregatedStats>;
+    clear: () => void;
+};
+export type { ProfilerRuntimeOptions, ProfilingEvent, ProfilerExport, AggregatedStats, ProfilingEventKind, } from "./types";
+export type { ProfilerMode } from "../schemas/index";
+export { nowMs } from "./clock";
+export { record, shouldProfile, shouldIncludeServerBreakdown, generateId, isEnabled, type ResolvedProfilerConfig, } from "./controller";
+export { createProfilingMeta, createProfilingDisabledMeta, injectProfilingMetaIntoObject, extractProfilingMeta, stripProfilingMeta, } from "./envelope";
+export { recordPhase, recordFailure, recordServerBreakdownPhases, recordDelegationBreakdownPhases, type BaseTimings, type BaseEvent, } from "./events";
+//# sourceMappingURL=index.d.ts.map

package/dist/profiling/index.js

@@ -0,0 +1,31 @@
+/**
+ * QVAC SDK Profiler
+ *
+ * @example
+ * ```ts
+ * import { profiler } from "@qvac/sdk";
+ *
+ * profiler.enable({ mode: "summary" });
+ * // ... run SDK operations ...
+ * console.log(profiler.exportTable());
+ * profiler.disable();
+ * ```
+ */
+import * as controller from "./controller.js";
+import * as exporters from "./exporters.js";
+export const profiler = {
+    enable: (options) => controller.enable(options),
+    disable: () => controller.disable(),
+    isEnabled: () => controller.isEnabled(),
+    exportJSON: (options) => exporters.exportJSON(options),
+    exportTable: () => exporters.exportTable(),
+    exportSummary: () => exporters.exportSummary(),
+    onRecord: (callback) => controller.onRecord(callback),
+    getConfig: () => controller.getEffectiveConfig(),
+    getAggregates: () => controller.getAggregates(),
+    clear: () => controller.clear(),
+};
+export { nowMs } from "./clock.js";
+export { record, shouldProfile, shouldIncludeServerBreakdown, generateId, isEnabled, } from "./controller.js";
+export { createProfilingMeta, createProfilingDisabledMeta, injectProfilingMetaIntoObject, extractProfilingMeta, stripProfilingMeta, } from "./envelope.js";
+export { recordPhase, recordFailure, recordServerBreakdownPhases, recordDelegationBreakdownPhases, } from "./events.js";

package/dist/profiling/ring-buffer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * O(1) bounded buffer for event storage.
+ * Oldest events are overwritten when full.
+ */
+export interface RingBufferState<T> {
+    buffer: (T | undefined)[];
+    capacity: number;
+    head: number;
+    size: number;
+    totalPushed: number;
+}
+export declare function createRingBuffer<T>(capacity: number): RingBufferState<T>;
+export declare function ringBufferPush<T>(state: RingBufferState<T>, item: T): T | undefined;
+export declare function ringBufferToArray<T>(state: RingBufferState<T>): T[];
+export declare function ringBufferGetRecent<T>(state: RingBufferState<T>, count: number): T[];
+export declare function ringBufferClear<T>(state: RingBufferState<T>): void;
+export declare function ringBufferDroppedCount<T>(state: RingBufferState<T>): number;
+export declare function ringBufferResize<T>(state: RingBufferState<T>, newCapacity: number): RingBufferState<T>;
+//# sourceMappingURL=ring-buffer.d.ts.map

package/dist/profiling/ring-buffer.js

@@ -0,0 +1,83 @@
+/**
+ * O(1) bounded buffer for event storage.
+ * Oldest events are overwritten when full.
+ */
+import { ProfilerInvalidCapacityError } from "../utils/errors-client.js";
+export function createRingBuffer(capacity) {
+    if (capacity < 1) {
+        throw new ProfilerInvalidCapacityError(1);
+    }
+    return {
+        buffer: new Array(capacity),
+        capacity,
+        head: 0,
+        size: 0,
+        totalPushed: 0,
+    };
+}
+// Returns the overwritten item if buffer was full, undefined otherwise.
+export function ringBufferPush(state, item) {
+    const overwritten = state.size === state.capacity ? state.buffer[state.head] : undefined;
+    state.buffer[state.head] = item;
+    state.head = (state.head + 1) % state.capacity;
+    state.size = Math.min(state.size + 1, state.capacity);
+    state.totalPushed++;
+    return overwritten;
+}
+// Returns all items in chronological order (oldest first).
+export function ringBufferToArray(state) {
+    if (state.size === 0) {
+        return [];
+    }
+    const result = [];
+    const start = state.size === state.capacity
+        ? state.head // Full: head points to oldest
+        : 0;
+    for (let i = 0; i < state.size; i++) {
+        const index = (start + i) % state.capacity;
+        const item = state.buffer[index];
+        if (item !== undefined) {
+            result.push(item);
+        }
+    }
+    return result;
+}
+// Returns the most recent N items (newest first).
+export function ringBufferGetRecent(state, count) {
+    if (state.size === 0 || count <= 0) {
+        return [];
+    }
+    const actualCount = Math.min(count, state.size);
+    const result = [];
+    for (let i = 0; i < actualCount; i++) {
+        const index = (state.head - 1 - i + state.capacity) % state.capacity;
+        const item = state.buffer[index];
+        if (item !== undefined) {
+            result.push(item);
+        }
+    }
+    return result;
+}
+export function ringBufferClear(state) {
+    state.buffer = new Array(state.capacity);
+    state.head = 0;
+    state.size = 0;
+    state.totalPushed = 0;
+}
+export function ringBufferDroppedCount(state) {
+    return Math.max(0, state.totalPushed - state.capacity);
+}
+// Resizes the buffer, keeping the most recent items.
+export function ringBufferResize(state, newCapacity) {
+    if (newCapacity < 1) {
+        throw new ProfilerInvalidCapacityError(1);
+    }
+    const items = ringBufferToArray(state);
+    const itemsToKeep = items.slice(-newCapacity);
+    const newState = createRingBuffer(newCapacity);
+    for (const item of itemsToKeep) {
+        ringBufferPush(newState, item);
+    }
+    newState.totalPushed = state.totalPushed;
+    return newState;
+}

package/dist/profiling/types.d.ts

@@ -0,0 +1,47 @@
+export type ProfilingEventKind = "rpc" | "handler" | "download" | "load" | "delegation";
+export interface ProfilingEvent {
+    /** Timestamp when event was recorded (monotonic ms) */
+    ts: number;
+    op: string;
+    kind: ProfilingEventKind;
+    profileId?: string;
+    phase?: string;
+    ms?: number;
+    /** Count (e.g., chunks, tokens) */
+    count?: number;
+    bytes?: number;
+    /** Numeric gauges (e.g., throughput, token counters) */
+    gauges?: Record<string, number>;
+    /** String tags (e.g., handlerType, sourceType, modelId) */
+    tags?: Record<string, string>;
+}
+export interface ProfilerRuntimeOptions {
+    mode?: "summary" | "verbose";
+    includeServerBreakdown?: boolean;
+    operationFilters?: string[];
+}
+export interface AggregatedStats {
+    count: number;
+    min: number;
+    max: number;
+    avg: number;
+    sum: number;
+    last: number;
+}
+export interface ProfilerExport {
+    config: {
+        enabled: boolean;
+        mode: "summary" | "verbose";
+        includeServerBreakdown: boolean;
+        operationFilters: string[];
+        maxRecentEvents: number;
+    };
+    aggregates: Record<string, AggregatedStats>;
+    recentEvents?: ProfilingEvent[];
+    exportedAt: number;
+}
+export interface LoadTimingStats {
+    modelInitializationTimeMs?: number;
+    totalLoadTimeMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/profiling/types.js

@@ -0,0 +1 @@
+export {};