@simulatte/doppler 0.1.8 → 0.2.0

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

@@ -1,119 +0,0 @@
-/**
- * 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

@@ -1,268 +0,0 @@
-
-
-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

@@ -1,77 +0,0 @@
-/**
- * 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

@@ -1,139 +0,0 @@
-
-
-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

@@ -1,42 +0,0 @@
-/**
- * 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

@@ -1,34 +0,0 @@
-
-
-// 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';