@simulatte/doppler 0.1.0

package/src/debug/config.d.ts

@@ -0,0 +1,78 @@
+export interface LogLevels {
+  DEBUG: 0;
+  VERBOSE: 1;
+  INFO: 2;
+  WARN: 3;
+  ERROR: 4;
+  SILENT: 5;
+}
+
+export type LogLevelName = 'debug' | 'verbose' | 'info' | 'warn' | 'error' | 'silent';
+export type TraceCategory = 'loader' | 'kernels' | 'logits' | 'embed' | 'attn' | 'ffn' | 'kv' | 'sample' | 'buffers' | 'perf' | 'energy';
+
+export interface TraceOptions {
+  layers?: number[];
+  maxDecodeSteps?: number;
+  breakOnAnomaly?: boolean;
+}
+
+export interface DebugConfig {
+  logLevel?: {
+    defaultLogLevel?: LogLevelName;
+  };
+  trace?: {
+    enabled?: boolean;
+    categories?: TraceCategory[];
+    layers?: number[];
+    maxDecodeSteps?: number;
+  };
+  logHistory?: {
+    maxLogHistoryEntries?: number;
+  };
+}
+
+
+export interface LogHistoryEntry {
+  time: number;
+  perfTime: number;
+  level: string;
+  module: string;
+  message: string;
+  data?: unknown;
+}
+
+export const LOG_LEVELS: LogLevels;
+export const TRACE_CATEGORIES: readonly TraceCategory[];
+
+export let currentLogLevel: number;
+export let enabledModules: Set<string>;
+export let disabledModules: Set<string>;
+export let logHistory: LogHistoryEntry[];
+export let gpuDevice: GPUDevice | null;
+export let enabledTraceCategories: Set<TraceCategory>;
+export let traceLayerFilter: number[];
+export let traceDecodeStep: number;
+export let traceMaxDecodeSteps: number;
+export let traceBreakOnAnomaly: boolean;
+
+export function setLogLevel(level: LogLevelName): void;
+export function getLogLevel(): LogLevelName;
+export function setTrace(categories: string | TraceCategory[] | false, options?: TraceOptions): void;
+export function applyDebugConfig(config: DebugConfig): void;
+export function getLogHistoryLimit(): number;
+export function getTrace(): TraceCategory[];
+export function isTraceEnabled(category: TraceCategory, layerIdx?: number): boolean;
+export function incrementDecodeStep(): number;
+export function resetDecodeStep(): void;
+export function getDecodeStep(): number;
+export function shouldBreakOnAnomaly(): boolean;
+export function setSilentMode(enabled: boolean): void;
+export function isSilentMode(): boolean;
+/** @deprecated Use setSilentMode instead */
+export function setBenchmarkMode(enabled: boolean): void;
+/** @deprecated Use isSilentMode instead */
+export function isBenchmarkMode(): boolean;
+export function enableModules(...modules: string[]): void;
+export function disableModules(...modules: string[]): void;
+export function resetModuleFilters(): void;
+export function setGPUDevice(device: GPUDevice | null): void;

package/src/debug/config.js

@@ -0,0 +1,235 @@
+import { DEFAULT_LOG_HISTORY_CONFIG } from '../config/schema/debug.schema.js';
+
+// Log level values (higher = less verbose)
+export const LOG_LEVELS = {
+  DEBUG: 0,
+  VERBOSE: 1,
+  INFO: 2,
+  WARN: 3,
+  ERROR: 4,
+  SILENT: 5,
+};
+
+// Trace categories
+export const TRACE_CATEGORIES = [
+  'loader',
+  'kernels',
+  'logits',
+  'embed',
+  'attn',
+  'ffn',
+  'kv',
+  'sample',
+  'buffers',
+  'perf',
+  'energy',
+];
+
+// Global state
+export let currentLogLevel = LOG_LEVELS.INFO;
+let logHistoryLimit = DEFAULT_LOG_HISTORY_CONFIG.maxLogHistoryEntries;
+export let enabledModules = new Set();
+export let disabledModules = new Set();
+export let logHistory = [];
+
+// GPU device reference for tensor inspection
+export let gpuDevice = null;
+
+// Trace categories state
+export let enabledTraceCategories = new Set();
+export let traceLayerFilter = [];
+export let traceDecodeStep = 0;
+export let traceMaxDecodeSteps = 0;
+export let traceBreakOnAnomaly = false;
+
+// Benchmark mode state (silent mode)
+let silentMode = false;
+const originalConsoleLog = console.log;
+const originalConsoleDebug = console.debug;
+const originalConsoleInfo = console.info;
+const originalConsoleWarn = console.warn;
+let warnedBenchmarkMode = false;
+
+export function setLogLevel(level) {
+  const levelMap = {
+    debug: LOG_LEVELS.DEBUG,
+    verbose: LOG_LEVELS.VERBOSE,
+    info: LOG_LEVELS.INFO,
+    warn: LOG_LEVELS.WARN,
+    error: LOG_LEVELS.ERROR,
+    silent: LOG_LEVELS.SILENT,
+  };
+  currentLogLevel = levelMap[level.toLowerCase()] ?? LOG_LEVELS.INFO;
+  console.log(`[Doppler] Log level set to: ${level.toUpperCase()}`);
+}
+
+export function getLogLevel() {
+  for (const [name, value] of Object.entries(LOG_LEVELS)) {
+    if (value === currentLogLevel) return name.toLowerCase();
+  }
+  return 'info';
+}
+
+export function setTrace(categories, options) {
+  if (categories === false) {
+    enabledTraceCategories.clear();
+    console.log('[Doppler] Trace disabled');
+    return;
+  }
+
+  const catArray = typeof categories === 'string'
+    ? categories.split(',').map(s => s.trim())
+    : categories;
+
+  enabledTraceCategories.clear();
+
+  const hasAll = catArray.includes('all');
+  if (hasAll) {
+    for (const cat of TRACE_CATEGORIES) {
+      enabledTraceCategories.add(cat);
+    }
+  }
+
+  for (const cat of catArray) {
+    if (cat === 'all') continue;
+
+    if (cat.startsWith('-')) {
+      const exclude = cat.slice(1);
+      enabledTraceCategories.delete(exclude);
+    } else if (TRACE_CATEGORIES.includes(cat)) {
+      enabledTraceCategories.add(cat);
+    }
+  }
+
+  if (options?.layers) {
+    traceLayerFilter = options.layers;
+  }
+  if (options?.maxDecodeSteps !== undefined) {
+    traceMaxDecodeSteps = options.maxDecodeSteps;
+  }
+  if (options?.breakOnAnomaly !== undefined) {
+    traceBreakOnAnomaly = options.breakOnAnomaly;
+  }
+
+  const enabled = [...enabledTraceCategories].join(',') || 'none';
+  console.log(`[Doppler] Trace categories: ${enabled}`);
+}
+
+export function applyDebugConfig(config) {
+  const logHistoryConfig = config?.logHistory ?? DEFAULT_LOG_HISTORY_CONFIG;
+  logHistoryLimit = logHistoryConfig.maxLogHistoryEntries ?? DEFAULT_LOG_HISTORY_CONFIG.maxLogHistoryEntries;
+
+  if (config.logLevel?.defaultLogLevel) {
+    const desired = config.logLevel.defaultLogLevel;
+    if (desired && desired !== getLogLevel()) {
+      setLogLevel(desired);
+    }
+  }
+
+  if (config.trace?.enabled) {
+    const categories = config.trace.categories?.length
+      ? config.trace.categories.join(',')
+      : 'all';
+    setTrace(categories, {
+      layers: config.trace.layers ?? undefined,
+      maxDecodeSteps: config.trace.maxDecodeSteps || undefined,
+    });
+  } else if (getTrace().length > 0) {
+    setTrace(false);
+  }
+}
+
+export function getLogHistoryLimit() {
+  return logHistoryLimit;
+}
+
+export function getTrace() {
+  return [...enabledTraceCategories];
+}
+
+export function isTraceEnabled(category, layerIdx) {
+  if (!enabledTraceCategories.has(category)) return false;
+
+  if (layerIdx !== undefined && traceLayerFilter.length > 0) {
+    if (!traceLayerFilter.includes(layerIdx)) return false;
+  }
+
+  if (traceMaxDecodeSteps > 0 && traceDecodeStep > traceMaxDecodeSteps) {
+    return false;
+  }
+
+  return true;
+}
+
+export function incrementDecodeStep() {
+  return ++traceDecodeStep;
+}
+
+export function resetDecodeStep() {
+  traceDecodeStep = 0;
+}
+
+export function getDecodeStep() {
+  return traceDecodeStep;
+}
+
+export function shouldBreakOnAnomaly() {
+  return traceBreakOnAnomaly;
+}
+
+export function setSilentMode(enabled) {
+  silentMode = enabled;
+  if (enabled) {
+    const noop = () => {};
+    console.log = noop;
+    console.debug = noop;
+    console.info = noop;
+    originalConsoleLog('[Doppler] Silent mode enabled - logging silenced');
+  } else {
+    console.log = originalConsoleLog;
+    console.debug = originalConsoleDebug;
+    console.info = originalConsoleInfo;
+    console.log('[Doppler] Silent mode disabled - logging restored');
+  }
+}
+
+export function isSilentMode() {
+  return silentMode;
+}
+
+export function setBenchmarkMode(enabled) {
+  if (!warnedBenchmarkMode) {
+    warnedBenchmarkMode = true;
+    originalConsoleWarn('[Doppler] setBenchmarkMode is deprecated; use setSilentMode instead.');
+  }
+  setSilentMode(enabled);
+}
+
+export function isBenchmarkMode() {
+  if (!warnedBenchmarkMode) {
+    warnedBenchmarkMode = true;
+    originalConsoleWarn('[Doppler] isBenchmarkMode is deprecated; use isSilentMode instead.');
+  }
+  return isSilentMode();
+}
+
+export function enableModules(...modules) {
+  enabledModules = new Set(modules.map((m) => m.toLowerCase()));
+  console.log(`[Doppler] Enabled modules: ${modules.join(', ')}`);
+}
+
+export function disableModules(...modules) {
+  for (const m of modules) {
+    disabledModules.add(m.toLowerCase());
+  }
+  console.log(`[Doppler] Disabled modules: ${modules.join(', ')}`);
+}
+
+export function resetModuleFilters() {
+  enabledModules.clear();
+  disabledModules.clear();
+}
+
+export function setGPUDevice(device) {
+  gpuDevice = device;
+}

package/src/debug/history.d.ts

@@ -0,0 +1,65 @@
+/**
+ * DOPPLER Debug Module - Log History and Snapshots
+ *
+ * Tools for retrieving log history and creating debug snapshots.
+ *
+ * @module debug/history
+ */
+
+import type { LogEntry, TraceCategory } from './config.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Log history filter
+ */
+export interface LogHistoryFilter {
+  level?: string;
+  module?: string;
+  last?: number;
+}
+
+/**
+ * Debug snapshot
+ */
+export interface DebugSnapshot {
+  timestamp: string;
+  logLevel: string | undefined;
+  traceCategories: TraceCategory[];
+  enabledModules: string[];
+  disabledModules: string[];
+  recentLogs: Array<{
+    time: string;
+    level: string;
+    module: string;
+    message: string;
+  }>;
+  errorCount: number;
+  warnCount: number;
+}
+
+// ============================================================================
+// History Functions
+// ============================================================================
+
+/**
+ * Get log history for debugging.
+ */
+export declare function getLogHistory(filter?: LogHistoryFilter): LogEntry[];
+
+/**
+ * Clear log history.
+ */
+export declare function clearLogHistory(): void;
+
+/**
+ * Print a summary of recent logs.
+ */
+export declare function printLogSummary(count?: number): void;
+
+/**
+ * Export a debug snapshot for bug reports.
+ */
+export declare function getDebugSnapshot(): DebugSnapshot;

package/src/debug/history.js

@@ -0,0 +1,71 @@
+
+
+import {
+  LOG_LEVELS,
+  currentLogLevel,
+  enabledTraceCategories,
+  enabledModules,
+  disabledModules,
+  logHistory,
+} from './config.js';
+
+// ============================================================================
+// History Functions
+// ============================================================================
+
+
+export function getLogHistory(filter = {}) {
+  let history = [...logHistory];
+
+  if (filter.level) {
+    history = history.filter((h) => h.level === filter.level.toUpperCase());
+  }
+
+  if (filter.module) {
+    const m = filter.module.toLowerCase();
+    history = history.filter((h) => h.module.toLowerCase().includes(m));
+  }
+
+  if (filter.last) {
+    history = history.slice(-filter.last);
+  }
+
+  return history;
+}
+
+
+export function clearLogHistory() {
+  logHistory.length = 0;
+}
+
+
+export function printLogSummary(count = 20) {
+  const recent = logHistory.slice(-count);
+  console.log('=== Recent Logs ===');
+  for (const entry of recent) {
+    const time = entry.perfTime.toFixed(1);
+    console.log(`[${time}ms][${entry.level}][${entry.module}] ${entry.message}`);
+  }
+  console.log('===================');
+}
+
+
+export function getDebugSnapshot() {
+  return {
+    timestamp: new Date().toISOString(),
+    logLevel: Object.keys(LOG_LEVELS).find(
+      (k) => LOG_LEVELS[k] === currentLogLevel
+    ),
+    traceCategories: [...enabledTraceCategories],
+    enabledModules: [...enabledModules],
+    disabledModules: [...disabledModules],
+    recentLogs: logHistory.slice(-50).map((e) => ({
+      time: e.perfTime.toFixed(1),
+      level: e.level,
+      module: e.module,
+      message: e.message,
+    })),
+    errorCount: logHistory.filter((e) => e.level === 'ERROR').length,
+    warnCount: logHistory.filter((e) => e.level === 'WARN').length,
+  };
+}

package/src/debug/index.d.ts

@@ -0,0 +1,268 @@
+/**
+ * DOPPLER Debug Module - Unified Logging and Tracing
+ *
+ * Single source of truth for all logging and debugging.
+ *
+ * ## Log Levels (verbosity - how much to show)
+ *   silent  - nothing
+ *   error   - errors only
+ *   warn    - errors + warnings
+ *   info    - normal operation (default)
+ *   verbose - detailed info
+ *   debug   - everything
+ *
+ * ## Trace Categories (what to show when tracing)
+ *   loader  - model loading (shards, weights)
+ *   kernels - GPU kernel execution
+ *   logits  - logit computation
+ *   embed   - embedding layer
+ *   attn    - attention computation
+ *   ffn     - feed-forward network
+ *   kv      - KV cache operations
+ *   sample  - token sampling
+ *   buffers - GPU buffer stats (expensive!)
+ *   perf    - timing info
+ *   all     - everything
+ *
+ * ## Usage
+ *   import { log, trace, setLogLevel, setTrace } from '../debug/index.js';
+ *
+ *   // Log levels (verbosity)
+ *   log.info('Pipeline', 'Model loaded');
+ *   log.verbose('Loader', 'Shard 0 from OPFS');
+ *   log.debug('Attention', `heads=${numHeads}`);
+ *
+ *   // Trace categories (only logs if category enabled)
+ *   trace.loader('Loading shard 0 from OPFS');
+ *   trace.kernels('matmul M=1 K=1152 N=1024');
+ *   trace.logits({ min: -2.3, max: 15.7 });
+ *
+ *   // Configure
+ *   setLogLevel('verbose');
+ *   setTrace('kernels,logits');       // enable specific
+ *   setTrace('all,-buffers');         // all except buffers
+ *   setTrace(false);                  // disable all
+ *
+ * ## Config-Only Overrides
+ *   Configure log level and trace categories via runtime config.
+ *
+ * @module debug
+ */
+
+// ============================================================================
+// Re-exports from signals.js
+// ============================================================================
+
+export {
+  SIGNALS,
+  SignalType,
+  DonePayload,
+  signalDone,
+  signalResult,
+  signalError,
+  signalProgress,
+} from './signals.js';
+
+// ============================================================================
+// Re-exports from config.js
+// ============================================================================
+
+export {
+  // Types and constants
+  LOG_LEVELS,
+  TRACE_CATEGORIES,
+  LogLevel,
+  LogLevelValue,
+  TraceCategory,
+  LogEntry,
+  // Configuration functions
+  setLogLevel,
+  getLogLevel,
+  setTrace,
+  getTrace,
+  applyDebugConfig,
+  isTraceEnabled,
+  incrementDecodeStep,
+  resetDecodeStep,
+  getDecodeStep,
+  shouldBreakOnAnomaly,
+  setSilentMode,
+  isSilentMode,
+  setBenchmarkMode,
+  isBenchmarkMode,
+  enableModules,
+  disableModules,
+  resetModuleFilters,
+  setGPUDevice,
+} from './config.js';
+
+// ============================================================================
+// Re-exports from log.js
+// ============================================================================
+
+export { log } from './log.js';
+
+// ============================================================================
+// Re-exports from trace.js
+// ============================================================================
+
+export { trace } from './trace.js';
+
+// ============================================================================
+// Re-exports from tensor.js
+// ============================================================================
+
+export {
+  tensor,
+  TensorStats,
+  TensorCompareResult,
+  TensorHealthResult,
+  TensorInspectOptions,
+} from './tensor.js';
+
+// ============================================================================
+// Re-exports from perf.js
+// ============================================================================
+
+export { perf } from './perf.js';
+
+// ============================================================================
+// Re-exports from history.js
+// ============================================================================
+
+export {
+  getLogHistory,
+  clearLogHistory,
+  printLogSummary,
+  getDebugSnapshot,
+  LogHistoryFilter,
+  DebugSnapshot,
+} from './history.js';
+
+// ============================================================================
+// Browser Console Global API
+// ============================================================================
+
+import { log } from './log.js';
+import { trace } from './trace.js';
+import { tensor } from './tensor.js';
+import { perf } from './perf.js';
+import {
+  SIGNALS,
+  signalDone,
+  signalResult,
+  signalError,
+  signalProgress,
+} from './signals.js';
+import {
+  setLogLevel,
+  getLogLevel,
+  setTrace,
+  getTrace,
+  isTraceEnabled,
+  setSilentMode,
+  isSilentMode,
+  setBenchmarkMode,
+  isBenchmarkMode,
+} from './config.js';
+import {
+  getLogHistory,
+  printLogSummary,
+  getDebugSnapshot,
+} from './history.js';
+
+/**
+ * DOPPLER debug API exposed to browser console.
+ */
+export interface DopplerDebugAPI {
+  // Trace categories
+  trace: typeof trace;
+  setTrace: typeof setTrace;
+  getTrace: typeof getTrace;
+  // Log levels
+  log: typeof log;
+  setLogLevel: typeof setLogLevel;
+  getLogLevel: typeof getLogLevel;
+  // Tensor inspection
+  tensor: typeof tensor;
+  inspect: typeof tensor.inspect;
+  // Performance
+  perf: typeof perf;
+  // Other
+  setSilentMode: typeof setSilentMode;
+  isSilentMode: typeof isSilentMode;
+  setBenchmarkMode: typeof setBenchmarkMode;
+  isBenchmarkMode: typeof isBenchmarkMode;
+  // History
+  getLogHistory: typeof getLogHistory;
+  printLogSummary: typeof printLogSummary;
+  getDebugSnapshot: typeof getDebugSnapshot;
+  // Completion signals
+  SIGNALS: typeof SIGNALS;
+  signalDone: typeof signalDone;
+  signalResult: typeof signalResult;
+  signalError: typeof signalError;
+  signalProgress: typeof signalProgress;
+}
+
+// ============================================================================
+// Default Export
+// ============================================================================
+
+declare const _default: {
+  log: typeof log;
+  trace: typeof trace;
+  tensor: typeof tensor;
+  perf: typeof perf;
+  setLogLevel: typeof setLogLevel;
+  getLogLevel: typeof getLogLevel;
+  setTrace: typeof setTrace;
+  getTrace: typeof getTrace;
+  isTraceEnabled: typeof isTraceEnabled;
+  setSilentMode: typeof setSilentMode;
+  isSilentMode: typeof isSilentMode;
+  setBenchmarkMode: typeof setBenchmarkMode;
+  isBenchmarkMode: typeof isBenchmarkMode;
+  setGPUDevice: (device: GPUDevice) => void;
+  enableModules: (...modules: string[]) => void;
+  disableModules: (...modules: string[]) => void;
+  resetModuleFilters: () => void;
+  getLogHistory: typeof getLogHistory;
+  clearLogHistory: () => void;
+  printLogSummary: typeof printLogSummary;
+  getDebugSnapshot: typeof getDebugSnapshot;
+  LOG_LEVELS: {
+    readonly DEBUG: 0;
+    readonly VERBOSE: 1;
+    readonly INFO: 2;
+    readonly WARN: 3;
+    readonly ERROR: 4;
+    readonly SILENT: 5;
+  };
+  TRACE_CATEGORIES: readonly [
+    'loader',
+    'kernels',
+    'logits',
+    'embed',
+    'attn',
+    'ffn',
+    'kv',
+    'sample',
+    'buffers',
+    'perf',
+  ];
+  // Completion signals
+  SIGNALS: typeof SIGNALS;
+  signalDone: typeof signalDone;
+  signalResult: typeof signalResult;
+  signalError: typeof signalError;
+  signalProgress: typeof signalProgress;
+};
+
+export default _default;
+
+declare global {
+  interface Window {
+    DOPPLER?: DopplerDebugAPI;
+  }
+}