@simulatte/doppler 0.1.8 → 0.2.0

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

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

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

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

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

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

@@ -1,152 +0,0 @@
-
-
-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);
-}