@simulatte/doppler 0.1.0

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

@@ -0,0 +1,144 @@
+/**
+ * Debug configuration management for pipeline tracing.
+ *
+ * Manages debug categories, layer filters, and decode step tracking.
+ * Enable via: setDebugCategories({ embed: true, layer: true })
+ *
+ * Categories:
+ * - embed: Embedding layer output
+ * - layer: Per-layer entry/exit, hidden state stats
+ * - attn: Attention computation details
+ * - ffn: FFN computation details
+ * - kv: KV cache operations
+ * - logits: Logits computation and top-k
+ * - sample: Sampling decisions
+ * - io: GPU buffer read/writes
+ * - perf: Timing and benchmarks
+ * - kernel: Kernel step debugging - inspect tensor state after each kernel (SLOW!)
+ * - all: Enable everything (use sparingly)
+ *
+ * @module inference/pipelines/text/debug-utils/config
+ */
+
+import type { PipelineDebugConfigSchema } from '../../../../config/schema/index.js';
+
+// ============================================================================
+// Debug Configuration Types
+// ============================================================================
+
+export type DebugCategory =
+  | 'embed'
+  | 'layer'
+  | 'attn'
+  | 'ffn'
+  | 'kv'
+  | 'logits'
+  | 'sample'
+  | 'io'
+  | 'perf'
+  | 'kernel'
+  | 'all';
+
+export interface DebugConfig {
+  /** Which categories are enabled */
+  categories: Partial<Record<DebugCategory, boolean>>;
+  /** Only log these layer indices (empty = all) */
+  layers?: number[];
+  /** Only log first N decode steps (0 = all) */
+  maxDecodeSteps?: number;
+  /** Warn if maxAbs exceeds this */
+  maxAbsThreshold?: number;
+  /** Log GPU buffer stats (expensive - requires readback) */
+  bufferStats?: boolean;
+}
+
+// ============================================================================
+// Configuration API
+// ============================================================================
+
+/**
+ * Set debug categories. Merges with existing config.
+ *
+ * @example
+ * setDebugCategories({ embed: true, layer: true });
+ * setDebugCategories({ all: true }); // Enable everything
+ * setDebugCategories({ all: true, io: false }); // All except io
+ */
+export function setDebugCategories(
+  categories: Partial<Record<DebugCategory, boolean>>,
+  options?: Partial<Omit<DebugConfig, 'categories'>>
+): void;
+
+/**
+ * Reset debug config to defaults (all off).
+ */
+export function resetDebugConfig(): void;
+
+/**
+ * Apply pipeline debug config (runtime.shared.debug.pipeline) to debug-utils.
+ */
+export function applyPipelineDebugConfig(pipeline?: PipelineDebugConfigSchema | null): void;
+
+/**
+ * Get current debug config (for inspection).
+ */
+export function getDebugConfig(): DebugConfig;
+
+// ============================================================================
+// Decode Step Tracking
+// ============================================================================
+
+/**
+ * Increment decode step counter.
+ */
+export function incrementDecodeStep(): number;
+
+/**
+ * Reset decode step counter (call at start of generation).
+ */
+export function resetDecodeStep(): void;
+
+/**
+ * Get current decode step.
+ */
+export function getDecodeStep(): number;
+
+// ============================================================================
+// Layer Filtering
+// ============================================================================
+
+/**
+ * Check if a layer should be debugged based on debugLayers config.
+ * @param layerIdx - The layer index to check
+ * @param debugLayers - Array of layer indices to debug, null means none, undefined/empty means hardcoded defaults
+ * @returns true if the layer should be debugged
+ */
+export function shouldDebugLayerOutput(layerIdx: number, debugLayers: number[] | null | undefined): boolean;
+
+// ============================================================================
+// Internal Helpers (exported for use by other debug-utils modules)
+// ============================================================================
+
+/**
+ * Check if a debug category is enabled for the given layer.
+ * @internal
+ */
+export function isEnabled(category: DebugCategory, layerIdx?: number): boolean;
+
+/**
+ * Format a debug tag with category, layer, and step info.
+ * @internal
+ */
+export function formatTag(category: string, layerIdx?: number, step?: number): string;
+
+/**
+ * Check if buffer stats collection is enabled.
+ * @internal
+ */
+export function isBufferStatsEnabled(): boolean;
+
+/**
+ * Get max abs threshold for explosion warnings.
+ * @internal
+ */
+export function getMaxAbsThreshold(): number;

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

@@ -0,0 +1,156 @@
+
+
+import { getRuntimeConfig } from '../../../../config/runtime.js';
+
+// ============================================================================
+// Module State
+// ============================================================================
+
+
+function readDefaultConfig() {
+  const pipeline = getRuntimeConfig().shared.debug.pipeline;
+  return {
+    categories: {},
+    layers: pipeline.layers ?? null,
+    maxDecodeSteps: pipeline.maxDecodeSteps,
+    maxAbsThreshold: pipeline.maxAbsThreshold,
+    bufferStats: pipeline.bufferStats,
+  };
+}
+
+
+let config = readDefaultConfig();
+let decodeStep = 0;
+
+// ============================================================================
+// Configuration API
+// ============================================================================
+
+
+export function setDebugCategories(categories, options) {
+  config = {
+    ...config,
+    ...options,
+    categories: { ...config.categories, ...categories },
+  };
+}
+
+
+export function resetDebugConfig() {
+  config = readDefaultConfig();
+  decodeStep = 0;
+}
+
+
+export function applyPipelineDebugConfig(pipeline) {
+  if (!pipeline) return;
+
+  const shouldEnable = pipeline.enabled || (pipeline.categories && pipeline.categories.length > 0);
+  if (!shouldEnable) {
+    resetDebugConfig();
+    return;
+  }
+
+  const categories = pipeline.categories && pipeline.categories.length > 0
+    ? pipeline.categories
+    : ['all'];
+
+  
+  const categoryMap = {};
+  if (categories.includes('all')) {
+    categoryMap.all = true;
+  } else {
+    for (const cat of categories) {
+      categoryMap[cat] = true;
+    }
+  }
+
+  setDebugCategories(categoryMap, {
+    layers: pipeline.layers ?? undefined,
+    maxDecodeSteps: pipeline.maxDecodeSteps ?? undefined,
+    maxAbsThreshold: pipeline.maxAbsThreshold ?? undefined,
+    bufferStats: pipeline.bufferStats ?? undefined,
+  });
+}
+
+
+export function getDebugConfig() {
+  return { ...config };
+}
+
+// ============================================================================
+// Decode Step Tracking
+// ============================================================================
+
+
+export function incrementDecodeStep() {
+  return ++decodeStep;
+}
+
+
+export function resetDecodeStep() {
+  decodeStep = 0;
+}
+
+
+export function getDecodeStep() {
+  return decodeStep;
+}
+
+// ============================================================================
+// Layer Filtering
+// ============================================================================
+
+
+export function shouldDebugLayerOutput(layerIdx, debugLayers) {
+  if (debugLayers === null) return false;
+  if (!Array.isArray(debugLayers) || debugLayers.length === 0) return true;
+  return debugLayers.includes(layerIdx);
+}
+
+// ============================================================================
+// Internal Helpers (exported for use by other debug-utils modules)
+// ============================================================================
+
+
+export function isEnabled(category, layerIdx) {
+  // Check if category is enabled
+  if (!config.categories.all && !config.categories[category]) {
+    return false;
+  }
+
+  // Check layer filter
+  if (layerIdx !== undefined && config.layers?.length) {
+    if (!config.layers.includes(layerIdx)) {
+      return false;
+    }
+  }
+
+  // Check decode step limit
+  if (config.maxDecodeSteps && decodeStep > config.maxDecodeSteps) {
+    // Only apply to non-prefill logs
+    if (decodeStep > 0) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+
+export function formatTag(category, layerIdx, step) {
+  let tag = `[${category.toUpperCase()}]`;
+  if (layerIdx !== undefined) tag += `[L${layerIdx}]`;
+  if (step !== undefined) tag += `[S${step}]`;
+  return tag;
+}
+
+
+export function isBufferStatsEnabled() {
+  return config.bufferStats;
+}
+
+
+export function getMaxAbsThreshold() {
+  return config.maxAbsThreshold;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Debug utilities for pipeline tracing.
+ *
+ * Re-exports all debug utilities from submodules.
+ *
+ * @module inference/pipelines/text/debug-utils
+ */
+
+// Configuration
+export {
+  type DebugCategory,
+  type DebugConfig,
+  setDebugCategories,
+  resetDebugConfig,
+  applyPipelineDebugConfig,
+  getDebugConfig,
+  incrementDecodeStep,
+  resetDecodeStep,
+  getDecodeStep,
+  shouldDebugLayerOutput,
+} from './config.js';
+
+// Logging
+export {
+  logEmbed,
+  logLayer,
+  logAttn,
+  logFFN,
+  logKV,
+  logLogits,
+  logSample,
+  logIO,
+  logPerf,
+} from './logging.js';
+
+// Tensor inspection
+export {
+  type TensorStats,
+  dumpTensor,
+  dumpTokenVector,
+  dumpKVCache,
+  logKernelStep,
+  isKernelDebugEnabled,
+} from './tensor.js';
+
+// Utilities
+export {
+  f16ToF32,
+  decodeReadback,
+  getLogitsHealth,
+  getBufferStats,
+  DEBUG_PRESETS,
+} from './utils.js';

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

@@ -0,0 +1,44 @@
+
+
+// Configuration
+export {
+  setDebugCategories,
+  resetDebugConfig,
+  applyPipelineDebugConfig,
+  getDebugConfig,
+  incrementDecodeStep,
+  resetDecodeStep,
+  getDecodeStep,
+  shouldDebugLayerOutput,
+} from './config.js';
+
+// Logging
+export {
+  logEmbed,
+  logLayer,
+  logAttn,
+  logFFN,
+  logKV,
+  logLogits,
+  logSample,
+  logIO,
+  logPerf,
+} from './logging.js';
+
+// Tensor inspection
+export {
+  dumpTensor,
+  dumpTokenVector,
+  dumpKVCache,
+  logKernelStep,
+  isKernelDebugEnabled,
+} from './tensor.js';
+
+// Utilities
+export {
+  f16ToF32,
+  decodeReadback,
+  getLogitsHealth,
+  getBufferStats,
+  DEBUG_PRESETS,
+} from './utils.js';

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

@@ -0,0 +1,106 @@
+/**
+ * Logging functions for pipeline debug tracing.
+ *
+ * Provides category-specific logging for each pipeline stage:
+ * embedding, layers, attention, FFN, KV cache, logits, sampling, I/O, and performance.
+ *
+ * Log format: [CATEGORY] message
+ * This enables post-filtering: grep -E "^\[LAYER\]|\[ATTN\]"
+ *
+ * @module inference/pipelines/text/debug-utils/logging
+ */
+
+// ============================================================================
+// Logging Functions
+// ============================================================================
+
+/**
+ * Log embedding info.
+ */
+export function logEmbed(
+  tokenIds: number[],
+  info: { maxAbs?: number; nonZero?: number; total?: number; sample?: number[] }
+): void;
+
+/**
+ * Log layer entry/exit.
+ */
+export function logLayer(
+  layerIdx: number,
+  phase: 'enter' | 'exit',
+  isPrefill: boolean,
+  info: { numTokens?: number; maxAbs?: number; sample?: number[] }
+): void;
+
+/**
+ * Log attention details.
+ */
+export function logAttn(
+  layerIdx: number,
+  isPrefill: boolean,
+  info: {
+    numTokens: number;
+    kvLen: number;
+    startPos?: number;
+    maxAbsQ?: number;
+    maxAbsK?: number;
+    maxAbsV?: number;
+    maxAbsOut?: number;
+  }
+): void;
+
+/**
+ * Log FFN details.
+ */
+export function logFFN(
+  layerIdx: number,
+  info: { maxAbsGate?: number; maxAbsUp?: number; maxAbsOut?: number }
+): void;
+
+/**
+ * Log KV cache operations.
+ */
+export function logKV(
+  layerIdx: number,
+  op: 'write' | 'read' | 'init' | 'clear',
+  info: { seqLen?: number; kvLen?: number; startPos?: number }
+): void;
+
+/**
+ * Log logits computation.
+ */
+export function logLogits(
+  phase: 'prefill' | 'decode',
+  info: {
+    min: number;
+    max: number;
+    topK?: Array<{ token: number | string; prob: number; text?: string }>;
+  }
+): void;
+
+/**
+ * Log sampling decision.
+ */
+export function logSample(
+  tokenId: number,
+  tokenText: string,
+  info: { prob?: number; temperature?: number; topK?: number }
+): void;
+
+/**
+ * Log GPU buffer I/O.
+ */
+export function logIO(
+  op: 'read' | 'write' | 'copy',
+  label: string,
+  bytes: number
+): void;
+
+/**
+ * Log performance timing.
+ */
+export function logPerf(
+  phase: string,
+  ms: number,
+  extra?: Record<string, number | string>
+): void;

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

@@ -0,0 +1,152 @@
+
+
+import { log } from '../../../../debug/index.js';
+import {
+  isEnabled,
+  formatTag,
+  getDecodeStep,
+  getMaxAbsThreshold,
+} from './config.js';
+
+// ============================================================================
+// Logging Functions
+// ============================================================================
+
+
+export function logEmbed(tokenIds, info) {
+  if (!isEnabled('embed')) return;
+
+  const tag = formatTag('embed');
+  const tokens = tokenIds.length > 3
+    ? `[${tokenIds.slice(0, 3).join(',')},...] (${tokenIds.length} total)`
+    : `[${tokenIds.join(',')}]`;
+
+  let msg = `${tag} tokens=${tokens}`;
+  if (info.maxAbs !== undefined) msg += ` maxAbs=${info.maxAbs.toFixed(2)}`;
+  if (info.nonZero !== undefined) msg += ` nonZero=${info.nonZero}/${info.total}`;
+  if (info.sample?.length) msg += ` sample=[${info.sample.map(v => v.toFixed(3)).join(',')}]`;
+
+  log.debug('Debug', msg);
+}
+
+
+export function logLayer(layerIdx, phase, isPrefill, info) {
+  if (!isEnabled('layer', layerIdx)) return;
+
+  const tag = formatTag('layer', layerIdx);
+  const decodeStep = getDecodeStep();
+  const mode = isPrefill ? 'prefill' : `decode:${decodeStep}`;
+
+  let msg = `${tag} ${phase} ${mode}`;
+  if (info.numTokens !== undefined) msg += ` n=${info.numTokens}`;
+  if (info.maxAbs !== undefined) msg += ` maxAbs=${info.maxAbs.toFixed(2)}`;
+  if (info.sample?.length) msg += ` sample=[${info.sample.map(v => v.toFixed(3)).join(',')}]`;
+
+  // Warn on explosion
+  const maxAbsThreshold = getMaxAbsThreshold();
+  if (info.maxAbs !== undefined && info.maxAbs > maxAbsThreshold) {
+    msg += ` △ EXPLOSION`;
+  }
+
+  log.debug('Debug', msg);
+}
+
+
+export function logAttn(layerIdx, isPrefill, info) {
+  if (!isEnabled('attn', layerIdx)) return;
+
+  const tag = formatTag('attn', layerIdx);
+  const decodeStep = getDecodeStep();
+  const mode = isPrefill ? 'prefill' : `decode:${decodeStep}`;
+
+  let msg = `${tag} ${mode} n=${info.numTokens} kvLen=${info.kvLen}`;
+  if (info.startPos !== undefined) msg += ` startPos=${info.startPos}`;
+  if (info.maxAbsQ !== undefined) msg += ` Q=${info.maxAbsQ.toFixed(1)}`;
+  if (info.maxAbsK !== undefined) msg += ` K=${info.maxAbsK.toFixed(1)}`;
+  if (info.maxAbsV !== undefined) msg += ` V=${info.maxAbsV.toFixed(1)}`;
+  if (info.maxAbsOut !== undefined) msg += ` out=${info.maxAbsOut.toFixed(1)}`;
+
+  log.debug('Debug', msg);
+}
+
+
+export function logFFN(layerIdx, info) {
+  if (!isEnabled('ffn', layerIdx)) return;
+
+  const tag = formatTag('ffn', layerIdx);
+  let msg = tag;
+  if (info.maxAbsGate !== undefined) msg += ` gate=${info.maxAbsGate.toFixed(1)}`;
+  if (info.maxAbsUp !== undefined) msg += ` up=${info.maxAbsUp.toFixed(1)}`;
+  if (info.maxAbsOut !== undefined) msg += ` out=${info.maxAbsOut.toFixed(1)}`;
+
+  log.debug('Debug', msg);
+}
+
+
+export function logKV(layerIdx, op, info) {
+  if (!isEnabled('kv', layerIdx)) return;
+
+  const tag = formatTag('kv', layerIdx);
+  let msg = `${tag} ${op}`;
+  if (info.seqLen !== undefined) msg += ` seqLen=${info.seqLen}`;
+  if (info.kvLen !== undefined) msg += ` kvLen=${info.kvLen}`;
+  if (info.startPos !== undefined) msg += ` startPos=${info.startPos}`;
+
+  log.debug('Debug', msg);
+}
+
+
+export function logLogits(phase, info) {
+  if (!isEnabled('logits')) return;
+
+  const decodeStep = getDecodeStep();
+  const tag = phase === 'prefill' ? '[LOGITS][PREFILL]' : `[LOGITS][S${decodeStep}]`;
+  let msg = `${tag} min=${info.min.toFixed(2)} max=${info.max.toFixed(2)}`;
+
+  if (info.topK?.length) {
+    const topStr = info.topK
+      .slice(0, 5)
+      .map(t => `"${t.text || t.token}"(${(t.prob * 100).toFixed(1)}%)`)
+      .join(', ');
+    msg += ` top-5: ${topStr}`;
+  }
+
+  log.debug('Debug', msg);
+}
+
+
+export function logSample(tokenId, tokenText, info) {
+  if (!isEnabled('sample')) return;
+
+  const decodeStep = getDecodeStep();
+  const tag = decodeStep === 0 ? '[SAMPLE][PREFILL]' : `[SAMPLE][S${decodeStep}]`;
+  let msg = `${tag} -> ${tokenId} "${tokenText}"`;
+  if (info.prob !== undefined) msg += ` p=${(info.prob * 100).toFixed(1)}%`;
+  if (info.temperature !== undefined) msg += ` T=${info.temperature}`;
+
+  log.debug('Debug', msg);
+}
+
+
+export function logIO(op, label, bytes) {
+  if (!isEnabled('io')) return;
+
+  const tag = '[IO]';
+  const kb = (bytes / 1024).toFixed(1);
+  log.debug('Debug', `${tag} ${op} ${label}: ${kb}KB`);
+}
+
+
+export function logPerf(phase, ms, extra) {
+  if (!isEnabled('perf')) return;
+
+  const tag = '[PERF]';
+  let msg = `${tag} ${phase}: ${ms.toFixed(1)}ms`;
+  if (extra) {
+    for (const [k, v] of Object.entries(extra)) {
+      msg += ` ${k}=${typeof v === 'number' ? v.toFixed(1) : v}`;
+    }
+  }
+
+  log.debug('Debug', msg);
+}