Core Runtime Tooling

1/**2 * Example 45: Core Runtime Tooling3 *4 * Runtime tools in `deepbox/core`: the logger, warning filters, JSON and file5 * serialization, and the backend registry with the WASM SIMD backend.6 */7 8import { 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";25 26const OUTPUT_DIR = "docs/examples/45-core-runtime-tooling/output";27 28console.log("=".repeat(60));29console.log("Example 45: Core Runtime Tooling");30console.log("=".repeat(60));31 32await mkdir(OUTPUT_DIR, { recursive: true });33 34// ============================================================================35// Part 1: Structured logging36// ============================================================================37console.log("\nPart 1: Logger");38console.log("-".repeat(60));39 40const capturedLogs: string[] = [];41setLogHandler((entry) => {42  capturedLogs.push(43    `L${entry.level} @ ${new Date(entry.timestamp).toISOString()} :: ${entry.message}`44  );45});46 47const logger = new Logger(2, "Example45");48logger.info("Starting serialization and backend checks");49logger.debug("Level 2 emits summary and progress events");50logger.trace("This trace entry is recorded but not emitted at level 2");51 52console.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}`);57 58setLogHandler(undefined);59 60// ============================================================================61// Part 2: Warning filtering and collection62// ============================================================================63console.log("\nPart 2: Warnings");64console.log("-".repeat(60));65 66resetWarnings();67filterWarnings("once", {68  category: "ConvergenceWarning",69  message: /max iterations/i,70});71 72const 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});77 78console.log(`Warnings collected after applying 'once' filter: ${warnings.length}`);79for (const warning of warnings) {80  console.log(`  [${warning.category}] ${warning.message}`);81}82resetWarnings();83 84// ============================================================================85// Part 3: In-memory and file serialization86// ============================================================================87console.log("\nPart 3: Serialization");88console.log("-".repeat(60));89 90const tensorPayload = {91  __type: "Tensor" as const,92  data: [1.5, 2.5, 3.5, 4.5],93  shape: [2, 2],94  dtype: "float64",95};96 97const 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};114 115const 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}121 122const tensorPath = `${OUTPUT_DIR}/tensor-payload.json`;123const modulePath = `${OUTPUT_DIR}/module-state.json`;124 125await save(tensorPath, tensorPayload);126await save(modulePath, modulePayload);127 128const loadedTensor = await load(tensorPath);129const loadedModule = await load(modulePath);130 131console.log(`Saved tensor payload: ${tensorPath}`);132console.log(`Saved module state:   ${modulePath}`);133console.log(`Loaded payload types: ${loadedTensor.__type}, ${loadedModule.__type}`);134 135// ============================================================================136// Part 4: Backend registry137// ============================================================================138console.log("\nPart 4: Backend Registry");139console.log("-".repeat(60));140 141console.log(`Backends before registration: ${listBackends().join(", ")}`);142console.log(`WebGPU registered: ${isBackendAvailable("webgpu") ? "yes" : "no"}`);143console.log(`WASM registered:   ${isBackendAvailable("wasm") ? "yes" : "no"}`);144 145// The WASM SIMD backend ships precompiled kernels, and init() instantiates them.146// Once it is registered, same-shape contiguous float32 add, sub, mul and div on147// tensors with at least 512 elements run through 4-lane SIMD kernels. Every other148// op uses the normal CPU code and gives the same results.149const wasm = new WasmBackend();150await wasm.init();151if (wasm.info().available) {152  registerBackend("wasm", wasm);153}154 155console.log(`Backends after registration:  ${listBackends().join(", ")}`);156console.log(`WASM registered now: ${isBackendAvailable("wasm") ? "yes" : "no"}`);157console.log(`WASM SIMD kernels: ${wasm.listModules().join(", ")}`);158 159const simdA = new Float32Array([1, 2, 3, 4, 5]);160const simdB = new Float32Array([10, 20, 30, 40, 50]);161const simdOut = wasm.binaryContiguous("add", simdA, simdB);162console.log(`SIMD add result: [${simdOut ? Array.from(simdOut).join(", ") : "unavailable"}]`);163 164// ============================================================================165// Summary166// ============================================================================167console.log("\nKey Takeaways");168console.log("-".repeat(60));169console.log(170  "• Logger: structured entries that a handler can capture, separate from console output"171);172console.log("• Warning filters: silence, show once, or turn numerical warnings into errors");173console.log("• toJSON, fromJSON, save, load: round-trip payloads in memory or on disk");174console.log(175  "• Backend registry: CPU is always present. WebGPU and WASM are registered on request."176);177console.log(178  "• A device that cannot run an op throws a DeviceError. Move the tensor with await t.cpu()."179);180 181console.log("\nCore Runtime Tooling Example Complete!");182console.log("=".repeat(60));