Core Runtime Tooling

1/**2 * Example 45: Core Runtime Tooling3 *4 * Focuses on v1.0.0 runtime primitives in `deepbox/core`: logger,5 * warnings, backend registry, and JSON/file serialization.6 */78import { mkdir } from "node:fs/promises";9import {10  catchWarnings,11  filterWarnings,12  fromJSON,13  isBackendAvailable,14  Logger,15  listBackends,16  load,17  registerBackend,18  resetWarnings,19  save,20  setLogHandler,21  toJSON,22  WasmBackend,23  warn,24} from "deepbox/core";2526const OUTPUT_DIR = "docs/examples/45-core-runtime-tooling/output";2728console.log("=".repeat(60));29console.log("Example 45: Core Runtime Tooling");30console.log("=".repeat(60));3132await mkdir(OUTPUT_DIR, { recursive: true });3334// ============================================================================35// Part 1: Structured logging36// ============================================================================37console.log("\n🪵 Part 1: Logger");38console.log("-".repeat(60));3940const capturedLogs: string[] = [];41setLogHandler((entry) => {42  capturedLogs.push(43    `L${entry.level} @ ${new Date(entry.timestamp).toISOString()} :: ${entry.message}`44  );45});4647const logger = new Logger(2, "Example45");48logger.info("Starting serialization and backend checks");49logger.debug("Using verbosity level 2 to emit summary + progress events");50logger.trace("This trace entry is recorded but not emitted at level 2");5152console.log(`Captured log entries: ${capturedLogs.length}`);53for (const line of capturedLogs) {54  console.log(`  ${line}`);55}56console.log(`Recorded entries (including trace): ${logger.getEntries().length}`);5758setLogHandler(undefined);5960// ============================================================================61// Part 2: Warning filtering and collection62// ============================================================================63console.log("\n⚠️  Part 2: Warnings");64console.log("-".repeat(60));6566resetWarnings();67filterWarnings("once", {68  category: "ConvergenceWarning",69  message: /max iterations/i,70});7172const warnings = catchWarnings(() => {73  warn("solver hit max iterations", "ConvergenceWarning", "Example45");74  warn("solver hit max iterations", "ConvergenceWarning", "Example45");75  warn("probabilities were clipped into [0, 1]", "DataConversionWarning", "Example45");76});7778console.log(`Warnings collected after applying 'once' filter: ${warnings.length}`);79for (const warning of warnings) {80  console.log(`  [${warning.category}] ${warning.message}`);81}82resetWarnings();8384// ============================================================================85// Part 3: In-memory and file serialization86// ============================================================================87console.log("\n💾 Part 3: Serialization");88console.log("-".repeat(60));8990const tensorPayload = {91  __type: "Tensor" as const,92  data: [1.5, 2.5, 3.5, 4.5],93  shape: [2, 2],94  dtype: "float64",95};9697const modulePayload = {98  __type: "ModuleState" as const,99  parameters: {100    "encoder.weight": {101      data: [0.1, 0.2, 0.3, 0.4],102      dtype: "float32",103      shape: [2, 2],104    },105  },106  buffers: {107    running_mean: {108      data: [0.0, 0.0],109      dtype: "float32",110      shape: [2],111    },112  },113};114115const tensorJson = toJSON(tensorPayload);116const restoredTensor = fromJSON(tensorJson);117console.log(`Tensor payload JSON length: ${tensorJson.length} chars`);118if (restoredTensor.__type === "Tensor") {119  console.log(`  Restored tensor shape: [${restoredTensor.shape.join(", ")}]`);120}121122const tensorPath = `${OUTPUT_DIR}/tensor-payload.json`;123const modulePath = `${OUTPUT_DIR}/module-state.json`;124125await save(tensorPath, tensorPayload);126await save(modulePath, modulePayload);127128const loadedTensor = await load(tensorPath);129const loadedModule = await load(modulePath);130131console.log(`Saved tensor payload: ${tensorPath}`);132console.log(`Saved module state:   ${modulePath}`);133console.log(`Loaded payload types: ${loadedTensor.__type}, ${loadedModule.__type}`);134135// ============================================================================136// Part 4: Backend registry137// ============================================================================138console.log("\n🧠 Part 4: Backend Registry");139console.log("-".repeat(60));140141console.log(`Backends before registration: ${listBackends().join(", ")}`);142console.log(`Is WebGPU available? ${isBackendAvailable("webgpu") ? "yes" : "no"}`);143console.log(`Is WASM available?   ${isBackendAvailable("wasm") ? "yes" : "no"}`);144145// The WASM SIMD backend ships precompiled kernels: init() instantiates146// them, and once registered, contiguous float32 arithmetic on147// `wasm`-device tensors runs through 4-lane SIMD.148const wasm = new WasmBackend();149await wasm.init();150if (wasm.info().available) {151  registerBackend("wasm", wasm);152}153154console.log(`Backends after registration:  ${listBackends().join(", ")}`);155console.log(`Is WASM available now? ${isBackendAvailable("wasm") ? "yes" : "no"}`);156console.log(`WASM SIMD kernels: ${wasm.listModules().join(", ")}`);157158const simdA = new Float32Array([1, 2, 3, 4, 5]);159const simdB = new Float32Array([10, 20, 30, 40, 50]);160const simdOut = wasm.binaryContiguous("add", simdA, simdB);161console.log(`SIMD add result: [${simdOut ? Array.from(simdOut).join(", ") : "unavailable"}]`);162163// ============================================================================164// Summary165// ============================================================================166console.log("\n💡 Key Takeaways");167console.log("-".repeat(60));168console.log("• Logger captures structured events independently from console output");169console.log("• Warning filters let you silence, dedupe, or escalate numerical issues");170console.log("• Serialization helpers round-trip Deepbox payloads in memory or on disk");171console.log(172  "• The backend registry makes CPU mandatory; WebGPU/WASM backends plug in real kernels"173);174175console.log("\n✅ Core Runtime Tooling Example Complete!");176console.log("=".repeat(60));177