@simulatte/doppler 0.1.0

package/src/inference/pipelines/text/debug-utils/tensor.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Tensor inspection utilities for kernel step debugging.
+ *
+ * Provides GPU buffer readback and statistics computation for debugging.
+ * These operations are expensive (require GPU sync) - use sparingly.
+ *
+ * Enable with setDebugCategories({ kernel: true }, { bufferStats: true })
+ * or use DEBUG_PRESETS.kernelStep
+ *
+ * @example
+ * // Enable kernel step debugging for layer 0 only
+ * setDebugCategories({ kernel: true }, { layers: [0], bufferStats: true });
+ *
+ * // In pipeline code:
+ * if (isKernelDebugEnabled(layerIdx)) {
+ *   await dumpTensor(outputBuffer, 'matmul_output', { layerIdx });
+ * }
+ *
+ * @module inference/pipelines/text/debug-utils/tensor
+ */
+
+import type { KVCache, SlidingWindowKVCache } from '../../../kv-cache.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Tensor statistics from GPU readback */
+export interface TensorStats {
+  shape: string;
+  dtype: string;
+  min: number;
+  max: number;
+  maxAbs: number;
+  mean: number;
+  nonZero: number;
+  total: number;
+  nanCount: number;
+  infCount: number;
+  sample: number[];
+}
+
+// ============================================================================
+// Tensor Inspection Functions
+// ============================================================================
+
+/**
+ * Dump a GPU tensor's contents for debugging.
+ * This is expensive (requires GPU sync + readback) - use sparingly.
+ *
+ * @param buffer - GPU buffer to inspect
+ * @param label - Descriptive label for logging
+ * @param options - Additional options
+ */
+export function dumpTensor(
+  buffer: GPUBuffer,
+  label: string,
+  options?: {
+    layerIdx?: number;
+    shape?: [number, number] | [number];
+    dtype?: 'f32' | 'f16' | 'bf16';
+    sampleCount?: number;
+    warnThreshold?: number;
+  }
+): Promise<TensorStats | null>;
+
+/**
+ * Dump stats for a single token row within a 2D [numTokens, rowSize] buffer.
+ * Use this when matching per-token reference implementations (e.g., HuggingFace hooks).
+ */
+export function dumpTokenVector(
+  buffer: GPUBuffer,
+  label: string,
+  options: {
+    layerIdx?: number;
+    tokenIdx: number;
+    rowSize: number;
+    dtype?: 'f32' | 'f16' | 'bf16';
+    sampleCount?: number;
+    warnThreshold?: number;
+  }
+): Promise<TensorStats | null>;
+
+/**
+ * Log a kernel step with optional tensor dump.
+ * Use this after kernel invocations to trace execution.
+ *
+ * @param kernelName - Name of the kernel (e.g., 'matmul', 'rmsnorm')
+ * @param info - Additional info to log
+ */
+export function logKernelStep(
+  kernelName: string,
+  info: {
+    layerIdx?: number;
+    M?: number;
+    N?: number;
+    K?: number;
+    size?: number;
+    label?: string;
+  }
+): void;
+
+/**
+ * Dump KV cache state for a specific layer.
+ * Reads both keys and values buffers and reports statistics.
+ *
+ * @param kvCache - KV cache instance
+ * @param layerIdx - Layer index to inspect
+ */
+export function dumpKVCache(
+  kvCache: KVCache | SlidingWindowKVCache,
+  layerIdx: number
+): Promise<{ keys: TensorStats | null; values: TensorStats | null } | null>;
+
+/**
+ * Check if kernel step debugging is enabled.
+ * Use this to gate expensive debug operations.
+ */
+export function isKernelDebugEnabled(layerIdx?: number): boolean;

package/src/inference/pipelines/text/debug-utils/tensor.js

@@ -0,0 +1,268 @@
+
+
+import { readBuffer } from '../../../../memory/buffer-pool.js';
+import { log } from '../../../../debug/index.js';
+import { isEnabled } from './config.js';
+import { decodeReadback } from './utils.js';
+import { selectRuleValue } from '../../../../rules/rule-registry.js';
+
+// ============================================================================
+// Tensor Inspection Functions
+// ============================================================================
+
+
+export async function dumpTensor(buffer, label, options = {}) {
+  if (!isEnabled('kernel', options.layerIdx)) return null;
+
+  const { shape, dtype = 'f32', sampleCount = 8, warnThreshold = 10000 } = options;
+
+  try {
+    const data = await readBuffer(buffer);
+    const arr = decodeReadback(data, dtype);
+
+    let min = Infinity;
+    let max = -Infinity;
+    let sum = 0;
+    let nanCount = 0;
+    let infCount = 0;
+    let nonZero = 0;
+
+    for (let i = 0; i < arr.length; i++) {
+      const v = arr[i];
+      if (Number.isNaN(v)) {
+        nanCount++;
+      } else if (!Number.isFinite(v)) {
+        infCount++;
+      } else {
+        if (v < min) min = v;
+        if (v > max) max = v;
+        sum += v;
+        if (v !== 0) nonZero++;
+      }
+    }
+
+    const maxAbs = Math.max(Math.abs(min), Math.abs(max));
+    const mean = sum / (arr.length - nanCount - infCount);
+    const sample = Array.from(arr.slice(0, sampleCount));
+
+    const shapeStr = shape ? `[${shape.join('x')}]` : `[${arr.length}]`;
+
+
+    const stats = {
+      shape: shapeStr,
+      dtype,
+      min,
+      max,
+      maxAbs,
+      mean,
+      nonZero,
+      total: arr.length,
+      nanCount,
+      infCount,
+      sample,
+    };
+
+    // Format log message
+    const tag = options.layerIdx !== undefined
+      ? `[KERNEL][L${options.layerIdx}]`
+      : '[KERNEL]';
+
+    let msg = `${tag} ${label} ${shapeStr}`;
+    msg += ` min=${min.toFixed(3)} max=${max.toFixed(3)} maxAbs=${maxAbs.toFixed(3)}`;
+    msg += ` mean=${mean.toFixed(3)} nonZero=${nonZero}/${arr.length}`;
+
+    if (nanCount > 0) msg += ` NaN=${nanCount}`;
+    if (infCount > 0) msg += ` Inf=${infCount}`;
+
+    msg += `\n  sample=[${sample.map(v => v.toFixed(4)).join(', ')}]`;
+
+    // Warnings
+    if (maxAbs > warnThreshold) {
+      msg += `\n  △ VALUE EXPLOSION: maxAbs=${maxAbs.toFixed(1)} > ${warnThreshold}`;
+    }
+    if (nanCount > 0 || infCount > 0) {
+      msg += `\n  △ NUMERICAL INSTABILITY: ${nanCount} NaN, ${infCount} Inf`;
+    }
+    if (nonZero === 0 && arr.length > 0) {
+      msg += `\n  △ ALL ZEROS`;
+    }
+
+    log.debug('Debug', msg);
+    return stats;
+  } catch (e) {
+    log.error('Kernel', `${label} ERROR: ${e}`);
+    return null;
+  }
+}
+
+
+export async function dumpTokenVector(buffer, label, options) {
+  if (!isEnabled('kernel', options.layerIdx)) return null;
+
+  const {
+    tokenIdx,
+    rowSize,
+    dtype = 'f32',
+    sampleCount = 8,
+    warnThreshold = 10000,
+  } = options;
+
+  try {
+    const data = await readBuffer(buffer);
+    const arr = decodeReadback(data, dtype);
+
+    const offset = tokenIdx * rowSize;
+    const end = offset + rowSize;
+    if (offset < 0 || end > arr.length) {
+      log.error('Kernel', `${label} ERROR: token slice out of bounds (tokenIdx=${tokenIdx}, rowSize=${rowSize}, len=${arr.length})`);
+      return null;
+    }
+
+    const row = arr.subarray(offset, end);
+
+    let min = Infinity;
+    let max = -Infinity;
+    let sum = 0;
+    let nanCount = 0;
+    let infCount = 0;
+    let nonZero = 0;
+
+    for (let i = 0; i < row.length; i++) {
+      const v = row[i];
+      if (Number.isNaN(v)) {
+        nanCount++;
+      } else if (!Number.isFinite(v)) {
+        infCount++;
+      } else {
+        if (v < min) min = v;
+        if (v > max) max = v;
+        sum += v;
+        if (v !== 0) nonZero++;
+      }
+    }
+
+    const maxAbs = Math.max(Math.abs(min), Math.abs(max));
+    const denom = row.length - nanCount - infCount;
+    const mean = denom > 0 ? sum / denom : 0;
+    const sample = Array.from(row.slice(0, sampleCount));
+
+    const shapeStr = `[t${tokenIdx}x${rowSize}]`;
+
+
+    const stats = {
+      shape: shapeStr,
+      dtype,
+      min,
+      max,
+      maxAbs,
+      mean,
+      nonZero,
+      total: row.length,
+      nanCount,
+      infCount,
+      sample,
+    };
+
+    const tag = options.layerIdx !== undefined
+      ? `[KERNEL][L${options.layerIdx}]`
+      : '[KERNEL]';
+
+    let msg = `${tag} ${label} ${shapeStr}`;
+    msg += ` min=${min.toFixed(3)} max=${max.toFixed(3)} maxAbs=${maxAbs.toFixed(3)}`;
+    msg += ` mean=${mean.toFixed(3)} nonZero=${nonZero}/${row.length}`;
+
+    if (nanCount > 0) msg += ` NaN=${nanCount}`;
+    if (infCount > 0) msg += ` Inf=${infCount}`;
+
+    msg += `\n  sample=[${sample.map(v => v.toFixed(4)).join(', ')}]`;
+
+    if (maxAbs > warnThreshold) {
+      msg += `\n  △ VALUE EXPLOSION: maxAbs=${maxAbs.toFixed(1)} > ${warnThreshold}`;
+    }
+    if (nanCount > 0 || infCount > 0) {
+      msg += `\n  △ NUMERICAL INSTABILITY: ${nanCount} NaN, ${infCount} Inf`;
+    }
+    if (nonZero === 0 && row.length > 0) {
+      msg += `\n  △ ALL ZEROS`;
+    }
+
+    log.debug('Debug', msg);
+    return stats;
+  } catch (e) {
+    log.error('Kernel', `${label} ERROR: ${e}`);
+    return null;
+  }
+}
+
+
+export function logKernelStep(kernelName, info) {
+  if (!isEnabled('kernel', info.layerIdx)) return;
+
+  const tag = info.layerIdx !== undefined
+    ? `[KERNEL][L${info.layerIdx}]`
+    : '[KERNEL]';
+
+  let msg = `${tag} ${kernelName}`;
+  if (info.label) msg += ` (${info.label})`;
+  if (info.M !== undefined) msg += ` M=${info.M}`;
+  if (info.N !== undefined) msg += ` N=${info.N}`;
+  if (info.K !== undefined) msg += ` K=${info.K}`;
+  if (info.size !== undefined) msg += ` size=${info.size}`;
+
+  log.debug('Debug', msg);
+}
+
+
+export async function dumpKVCache(kvCache, layerIdx) {
+  if (!isEnabled('kernel', layerIdx) && !isEnabled('kv', layerIdx)) return null;
+
+  const tag = `[KV][L${layerIdx}]`;
+
+  try {
+    if (!kvCache?.hasGPUCache?.()) {
+      log.debug('Debug', `${tag} No GPU cache available`);
+      return null;
+    }
+
+    const gpuBuffers = kvCache.getGPUBuffers(layerIdx);
+    if (!gpuBuffers) {
+      log.debug('Debug', `${tag} No buffers for layer ${layerIdx}`);
+      return null;
+    }
+
+    const { keysGPU, valuesGPU, seqLen } = gpuBuffers;
+    const numHeads = kvCache.numHeads || 0;
+    const headDim = kvCache.headDim || 0;
+
+    log.debug('Debug', `${tag} seqLen=${seqLen} numHeads=${numHeads} headDim=${headDim}`);
+
+    const kvDtype = selectRuleValue('inference', 'dtype', 'f16OrF32FromDtype', {
+      dtype: kvCache.kvDtype,
+    });
+    const keysStats = keysGPU
+      ? await dumpTensor(keysGPU, 'K_cache', {
+        layerIdx,
+        shape: [seqLen, numHeads * headDim],
+        dtype: kvDtype,
+      })
+      : null;
+
+    const valuesStats = valuesGPU
+      ? await dumpTensor(valuesGPU, 'V_cache', {
+        layerIdx,
+        shape: [seqLen, numHeads * headDim],
+        dtype: kvDtype,
+      })
+      : null;
+
+    return { keys: keysStats, values: valuesStats };
+  } catch (e) {
+    log.error('Debug', `${tag} ERROR: ${e}`);
+    return null;
+  }
+}
+
+
+export function isKernelDebugEnabled(layerIdx) {
+  return isEnabled('kernel', layerIdx);
+}

package/src/inference/pipelines/text/debug-utils/utils.d.ts

@@ -0,0 +1,77 @@
+/**
+ * General utilities for pipeline debugging.
+ *
+ * Provides math helpers, buffer decoding, health checks, and preset configurations.
+ *
+ * @module inference/pipelines/text/debug-utils/utils
+ */
+
+import type { DebugCategory } from './config.js';
+
+// ============================================================================
+// Math Helpers
+// ============================================================================
+
+/**
+ * Convert a 16-bit float (IEEE 754 half-precision) to 32-bit float.
+ */
+export function f16ToF32(h: number): number;
+
+/**
+ * Decode a GPU readback buffer to Float32Array.
+ * Handles f16, bf16, and f32 dtypes.
+ */
+export function decodeReadback(buffer: ArrayBuffer, dtype: 'f16' | 'f32' | 'bf16'): Float32Array;
+
+// ============================================================================
+// Health Checks
+// ============================================================================
+
+/**
+ * Analyze logits array for numerical issues.
+ * Returns counts of NaN, Inf, non-zero values, and the max absolute value.
+ */
+export function getLogitsHealth(logits: Float32Array): {
+  nanCount: number;
+  infCount: number;
+  nonZeroCount: number;
+  maxAbs: number;
+};
+
+// ============================================================================
+// Buffer Stats (Expensive)
+// ============================================================================
+
+/**
+ * Read GPU buffer and compute stats. Only use when bufferStats is enabled.
+ */
+export function getBufferStats(
+  buffer: GPUBuffer
+): Promise<{ min: number; max: number; maxAbs: number; sample: number[]; nanCount: number } | null>;
+
+// ============================================================================
+// Debug Presets
+// ============================================================================
+
+/**
+ * Preset debug configurations for common debugging scenarios.
+ */
+export const DEBUG_PRESETS: {
+  /** Quick check: just embedding and final logits */
+  quick: Partial<Record<DebugCategory, boolean>>;
+
+  /** Layer tracing: watch values flow through layers */
+  layers: Partial<Record<DebugCategory, boolean>>;
+
+  /** Attention focus: debug attention computation */
+  attention: Partial<Record<DebugCategory, boolean>>;
+
+  /** Full trace: everything (very verbose) */
+  full: Partial<Record<DebugCategory, boolean>>;
+
+  /** Performance only: timing info */
+  perf: Partial<Record<DebugCategory, boolean>>;
+
+  /** Kernel step debugging: inspect tensor state after every kernel (very slow!) */
+  kernelStep: Partial<Record<DebugCategory, boolean>>;
+};

package/src/inference/pipelines/text/debug-utils/utils.js

@@ -0,0 +1,139 @@
+
+
+import { readBuffer } from '../../../../memory/buffer-pool.js';
+import { isBufferStatsEnabled } from './config.js';
+
+// ============================================================================
+// Math Helpers
+// ============================================================================
+
+
+export function f16ToF32(h) {
+  const sign = (h >> 15) & 0x1;
+  const exp = (h >> 10) & 0x1f;
+  const mant = h & 0x3ff;
+
+  if (exp === 0) {
+    if (mant === 0) return sign ? -0 : 0;
+    const f = mant / 1024 * Math.pow(2, -14);
+    return sign ? -f : f;
+  }
+  if (exp === 31) {
+    return mant ? NaN : (sign ? -Infinity : Infinity);
+  }
+
+  const f = (1 + mant / 1024) * Math.pow(2, exp - 15);
+  return sign ? -f : f;
+}
+
+
+export function decodeReadback(buffer, dtype) {
+  if (dtype === 'f32') {
+    return new Float32Array(buffer);
+  }
+  const src = new Uint16Array(buffer);
+  const out = new Float32Array(src.length);
+  if (dtype === 'bf16') {
+    const tmp = new Uint32Array(1);
+    const f32View = new Float32Array(tmp.buffer);
+    for (let i = 0; i < src.length; i++) {
+      tmp[0] = src[i] << 16;
+      out[i] = f32View[0];
+    }
+    return out;
+  }
+  for (let i = 0; i < src.length; i++) {
+    out[i] = f16ToF32(src[i]);
+  }
+  return out;
+}
+
+// ============================================================================
+// Health Checks
+// ============================================================================
+
+
+export function getLogitsHealth(logits) {
+  let nanCount = 0;
+  let infCount = 0;
+  let nonZeroCount = 0;
+  let maxAbs = 0;
+
+  for (let i = 0; i < logits.length; i++) {
+    const v = logits[i];
+    if (Number.isNaN(v)) {
+      nanCount++;
+      continue;
+    }
+    if (!Number.isFinite(v)) {
+      infCount++;
+      continue;
+    }
+    if (v !== 0) {
+      nonZeroCount++;
+      const abs = Math.abs(v);
+      if (abs > maxAbs) maxAbs = abs;
+    }
+  }
+
+  return { nanCount, infCount, nonZeroCount, maxAbs };
+}
+
+// ============================================================================
+// Buffer Stats (Expensive)
+// ============================================================================
+
+
+export async function getBufferStats(buffer) {
+  if (!isBufferStatsEnabled()) return null;
+
+  try {
+    const data = await readBuffer(buffer);
+    const arr = new Float32Array(data);
+    let min = Infinity;
+    let max = -Infinity;
+    let nanCount = 0;
+
+    for (let i = 0; i < arr.length; i++) {
+      const v = arr[i];
+      if (!Number.isFinite(v)) {
+        nanCount++;
+      } else {
+        if (v < min) min = v;
+        if (v > max) max = v;
+      }
+    }
+
+    const maxAbs = Math.max(Math.abs(min), Math.abs(max));
+    const sample = Array.from(arr.slice(0, 5));
+
+    return { min, max, maxAbs, sample, nanCount };
+  } catch {
+    return null;
+  }
+}
+
+// ============================================================================
+// Debug Presets
+// ============================================================================
+
+
+export const DEBUG_PRESETS = {
+  
+  quick: { embed: true, logits: true, sample: true },
+
+  
+  layers: { layer: true },
+
+  
+  attention: { attn: true, kv: true },
+
+  
+  full: { all: true },
+
+  
+  perf: { perf: true },
+
+  
+  kernelStep: { kernel: true },
+};

package/src/inference/pipelines/text/debug-utils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Debug utilities for pipeline tracing.
+ *
+ * Toggleable log categories for surgical debugging without noise.
+ * Enable via: setDebugCategories({ embed: true, layer: true })
+ *
+ * @module inference/pipelines/text/debug-utils
+ */
+
+// Public aggregation entrypoint
+export {
+  type DebugCategory,
+  type DebugConfig,
+  setDebugCategories,
+  resetDebugConfig,
+  applyPipelineDebugConfig,
+  getDebugConfig,
+  incrementDecodeStep,
+  resetDecodeStep,
+  getDecodeStep,
+  shouldDebugLayerOutput,
+  logEmbed,
+  logLayer,
+  logAttn,
+  logFFN,
+  logKV,
+  logLogits,
+  logSample,
+  logIO,
+  logPerf,
+  type TensorStats,
+  dumpTensor,
+  dumpTokenVector,
+  dumpKVCache,
+  logKernelStep,
+  isKernelDebugEnabled,
+  f16ToF32,
+  decodeReadback,
+  getLogitsHealth,
+  getBufferStats,
+  DEBUG_PRESETS,
+} from './debug-utils/index.js';

package/src/inference/pipelines/text/debug-utils.js

@@ -0,0 +1,34 @@
+
+
+// Public aggregation entrypoint.
+// Implementation is split into debug-utils/ submodules.
+
+export {
+  setDebugCategories,
+  resetDebugConfig,
+  applyPipelineDebugConfig,
+  getDebugConfig,
+  incrementDecodeStep,
+  resetDecodeStep,
+  getDecodeStep,
+  shouldDebugLayerOutput,
+  logEmbed,
+  logLayer,
+  logAttn,
+  logFFN,
+  logKV,
+  logLogits,
+  logSample,
+  logIO,
+  logPerf,
+  dumpTensor,
+  dumpTokenVector,
+  dumpKVCache,
+  logKernelStep,
+  isKernelDebugEnabled,
+  f16ToF32,
+  decodeReadback,
+  getLogitsHealth,
+  getBufferStats,
+  DEBUG_PRESETS,
+} from './debug-utils/index.js';