volvoxai 0.1.0

package/docs/textbook/ko/README.md

@@ -0,0 +1,83 @@
+# AI는 실제로 어떻게 동작하는가 — VolvoxAI 교과서
+
+*🌐 언어: [English](../README.md) · **한국어***
+
+> 이 저장소의 실제 코드를 바탕으로 신경망 **추론(inference)** 을 직접 따라가 보는 안내서입니다.
+> 동작하는 두 개의 모델 — **언어 모델**(TinyStories)과 **객체 탐지기**(EfficientDet-Lite0,
+> fp32 / fp16 / int8) — 을 골라, 하나의 입력이 답이 되기까지를 **연산 하나하나** 따라갑니다.
+
+이 책을 다 읽고 나면 어떤 최신 모델이든 **작은 수학 연산들의 그래프(graph)** 로 읽어낼 수 있고,
+각 연산이 실제로 무엇을 계산하는지 알게 되며, 그것을 실제 하드웨어에서 빠르게 돌리는 엔지니어링
+선택(메모리 배치, 양자화, GPU vs CPU)을 이해하게 됩니다. 이 책이 만드는 지식은 추론 메커니즘과
+런타임 엔지니어링입니다.
+
+---
+
+## 범위와 현재 빠진 부분
+
+이 교과서는 **추론(inference)** 에 집중합니다: 학습된 가중치를 로드하고, 모델 그래프를 실행하고,
+출력을 디코드하고, 가중치를 양자화하고, 연산을 브라우저/네이티브 백엔드에 매핑하는 것까지입니다.
+더 넓은 학습·연구 스택은 아직 다루지 않습니다:
+
+| 빠진 영역 | 현재 없는 것 |
+|---|---|
+| 학습 | 역전파, autograd, 손실 함수, Adam 같은 최적화기, 학습률 스케줄, 초기화, 정규화. |
+| 수학 기초 | 선형대수 유도, 연쇄 법칙/기울기를 위한 미적분, 확률, 정보 이론. |
+| 데이터 | 데이터셋 구성, 입력 파이프라인, 증강, 토크나이저 학습, train/validation/test 분할, 누수 점검. |
+| 평가와 실험 | 지표, 검증 방법론, ablation, 과적합, bias-variance 분석. |
+| 아키텍처 폭 | diffusion, GNN, RNN/LSTM, 강화학습, VAE/GAN, retrieval과 embedding, multimodal, MoE, SSM. |
+| 최신 LLM 학습 스택 | 사전학습, 지도 미세조정, LoRA/adapter, RLHF/DPO, 분산 학습, FlashAttention 내부. |
+| 연구 실무 | 논문 재현, 결과 유도, inductive bias 추론, scaling law. |
+
+7장에서 이 목록을 다음에 무엇을 추가해야 하는지에 대한 구체적 지도로 바꿉니다.
+
+---
+
+## 이 책을 읽는 방법
+
+각 장은 앞 장을 기반으로 합니다. 처음 읽을 때는 순서대로 읽으세요.
+
+1. **[기초](01-foundations.md)** — 추론이란 무엇인가. 텐서(tensor), 그래프, 연산(operation).
+   VolvoxAI의 멘탈 모델과 네 개의 "계층(tier)". 모델이 *설계도(blueprint)* 로 저장되는 방식.
+2. **[언어 모델 한 연산씩 (TinyStories)](02-tinystories-language-model.md)** —
+   문장 *"Once upon a time, Lily"* 가 GPT 스타일 트랜스포머(transformer)를 통과해 다음 단어를
+   예측하기까지. 토큰화 → 임베딩 → 어텐션 → 피드포워드 → 로짓 → 샘플링 → 반복.
+3. **[비전 모델 한 연산씩 (EfficientDet-Lite0)](03-efficientdet-vision-model.md)** —
+   320×320 사진이 합성곱 탐지기를 통과해 박스와 라벨을 내놓기까지.
+   백본 → 피처 피라미드 → 탐지 헤드 → 디코드.
+4. **[정밀도와 양자화 (fp32 / fp16 / int8)](04-precision-and-quantization.md)** —
+   숫자가 비트로 저장되는 방식, 같은 탐지기가 왜 세 가지 크기로 배포되는지, 그리고 int8 버전을
+   4배 작게 만드는 정확한 정수 연산.
+5. **[엔진 내부](05-inside-the-engine.md)** — VolvoxAI가 *브라우저*에서 그래프를 실행하는 방법:
+   네 개의 하드웨어 계층, *소박한(naive)* 커널에서 *빠른* 커널로의 도약, 그리고 연산 융합.
+6. **[네이티브 엔진](06-native-engine-architecture.md)** — *나머지 절반*: 같은 설계도를 CPU +
+   Vulkan/OpenGL/Metal/NNAPI 위에서 실행하는 독립형(freestanding) C 바이너리로, GPU 드라이버를
+   실행 시점에 로드합니다. 전체 이중 타깃(dual-target) 아키텍처와 그 설계 선택들.
+7. **[용어집과 다음 단계](07-glossary-and-next-steps.md)** — 모든 용어를 한곳에, 추천 학습 경로,
+   이 저장소를 활용한 실습 문제, 그리고 추론 너머의 현재 빈틈.
+
+> **다이어그램에 대하여.** 플로차트는 [Mermaid](https://mermaid.js.org/)로 작성되어 GitHub,
+> VS Code(Markdown Preview Mermaid 확장), 대부분의 마크다운 뷰어에서 이미지로 렌더링됩니다.
+> 데이터 배치를 보여주는 그림은 어디서든 보이도록 순수 ASCII로 그렸습니다.
+
+---
+
+## 한 문단 요약
+
+신경망은 마법도 아니고 두뇌도 아닙니다. 그것은 **고정된 산술 연산의 목록** — 대부분 곱하고
+더하기 — 을, 큰 숫자 격자(당신의 입력)에 또 다른 큰 숫자 격자(**가중치(weights)**, 학습 중에
+얻어진 값)를 사용해 적용하는 것입니다. 이 목록을 입력에서 출력까지 한 번 실행하는 것을
+**순전파(forward pass)** 또는 **추론(inference)** 이라고 합니다. VolvoxAI는 바로 이 일을 하는
+엔진입니다. 연산 목록(*그래프*)을 읽고, 가중치를 읽어, 출력을 계산합니다. 좋은 가중치를
+*발견하는* 별도의 더 어려운 과정인 학습(training)은 이 저장소에 없습니다. 우리는 **학습이 끝난
+모델을 답으로 바꾸는** 부분을 공부합니다.
+
+```mermaid
+flowchart LR
+    A["입력<br/>텍스트 또는 이미지"] --> B["숫자로 인코딩<br/>토큰 / 픽셀"]
+    B --> C["순전파<br/>수학 연산 그래프 + 가중치"]
+    C --> D["원시 출력<br/>로짓 / 박스"]
+    D --> E["의미로 디코딩<br/>다음 단어 / 라벨링된 박스"]
+```
+
+이제 **[1장: 기초](01-foundations.md)** 로 시작하세요.

package/docs/xnnpack_optimization_guide.md

@@ -0,0 +1,197 @@
+# XNNPACK-Level Microkernel Optimization Guide
+
+This document outlines the architectural roadmap and concrete code-level strategies required to elevate VolvoxAI's native CPU inference engine to XNNPACK-level performance across INT4, INT8, FP16, and FP32 data types.
+
+## 1. Architectural Paradigm Shift
+
+Currently, VolvoxAI relies on generic `Conv2D` and `QConv2D` implementations where a C compiler auto-vectorizes nested loops. To achieve XNNPACK-level speeds, we must transition to a **Microkernel Architecture**:
+
+1.  **NHWC Layout**: Keep all activations in NHWC format to ensure channels are contiguous in memory.
+2.  **Indirection Buffers**: Remove padding and bounds-checking from the inner loops.
+3.  **Weight Packing**: Pre-arrange weights in memory to perfectly match the target SIMD register width.
+4.  **Register Tiling (Microkernels)**: Hardcode loop unrolling to maximize register usage (e.g., computing a 4x8 output tile in 32 SIMD registers simultaneously) using specific intrinsics.
+
+---
+
+## 2. Indirection Buffers (Depthwise & Im2Col)
+
+**Problem:** Branching inside the MAC loop for padding (`if (x < 0 || x >= width)`) stalls the CPU pipeline.
+
+**Solution:** Precompute an array of pointers (the indirection buffer). Padded areas point to a pre-allocated zero-buffer. The microkernel strictly does pointer dereferencing and math.
+
+### Example: Setting up an Indirection Buffer
+```c
+// Pre-allocate a zero buffer for padding
+static const int8_t zero_buffer[MAX_CHANNELS] = {0};
+
+// Setup before the convolution
+const int8_t** indirection_buffer = malloc(output_height * output_width * kernel_size * sizeof(int8_t*));
+int idx = 0;
+for (int oy = 0; oy < output_height; oy++) {
+    for (int ox = 0; ox < output_width; ox++) {
+        for (int ky = 0; ky < kh; ky++) {
+            for (int kx = 0; kx < kw; kx++) {
+                int iy = oy * stride - pad_top + ky;
+                int ix = ox * stride - pad_left + kx;
+                if (iy >= 0 && iy < input_height && ix >= 0 && ix < input_width) {
+                    // Valid pixel pointer
+                    indirection_buffer[idx++] = input_image + (iy * input_width + ix) * channels;
+                } else {
+                    // Padding: Point to zero buffer. No branching in inner loop!
+                    indirection_buffer[idx++] = zero_buffer;
+                }
+            }
+        }
+    }
+}
+```
+
+---
+
+## 3. Data Type Specific Optimizations
+
+### 3.1 INT8: The Workhorse (VNNI / ARM sdot)
+
+For INT8, we must use dedicated dot-product instructions. ARM provides `sdot` (NEON) and Intel provides VNNI (AVX512/AVX2-VNNI). These instructions perform 4 MACs in a single cycle.
+
+**Weight Packing for INT8 (e.g., 8 output channels at a time, chunks of 4 input channels for dot product):**
+Weights are packed into blocks of `[OC/8, IC/4, 8, 4]`.
+
+**Microkernel Example: ARM NEON INT8 (Processing 4 Output pixels, 4 Output Channels)**
+```c
+#include <arm_neon.h>
+
+void microkernel_qconv2d_int8_neon_sdot(
+    const int8_t** input_pointers,
+    const int8_t* packed_weights,
+    int32_t* output_accumulators,
+    int kernel_elements,
+    int channels)
+{
+    // Initialize accumulators to bias + zero-point offsets
+    int32x4_t acc0 = vld1q_s32(output_accumulators + 0);
+    int32x4_t acc1 = vld1q_s32(output_accumulators + 4);
+    // ... setup for multiple output pixels
+
+    for (int k = 0; k < kernel_elements; k++) {
+        const int8_t* in_ptr = input_pointers[k];
+        for (int c = 0; c < channels; c += 4) {
+            // Load 4 input channels (broadcast to all output channels)
+            int8x8_t in_val = vld1_s8(in_ptr + c);
+            int8x16_t in_dup = vcombine_s8(in_val, in_val);
+
+            // Load packed weights: 4 channels x 8 output channels
+            int8x16_t w_val = vld1q_s8(packed_weights);
+            packed_weights += 16;
+
+            // Perform 4-way dot product: acc += sum(in[i] * w[i])
+            // Requires ARMv8.2-A Dot Product extension
+            acc0 = vdotq_s32(acc0, in_dup, w_val);
+            // ... repeat for other registers
+        }
+    }
+    // Fused requantization (int32 -> int8) happens here before writing to memory
+}
+```
+
+### 3.2 INT4: Extreme Memory Bandwidth Saving
+
+INT4 cuts memory bandwidth in half again compared to INT8, making it highly optimal for memory-bound LLM weights or heavily quantized vision models.
+
+**Challenge:** Most CPUs lack native INT4 MAC instructions.
+**Solution:** Decompress INT4 to INT8 *in registers* immediately upon loading, then feed into the INT8 microkernel.
+
+**Microkernel Strategy for INT4:**
+```c
+// Weights are packed 2-per-byte.
+// Load 128-bits of INT4 data (which represents 32 weights)
+uint8x16_t w_int4 = vld1q_u8(packed_int4_weights);
+
+// Decompress to INT8 using masking and shifting
+uint8x16_t mask = vdupq_n_u8(0x0F);
+uint8x16_t w_lo = vandq_u8(w_int4, mask);           // Extract lower nibbles
+uint8x16_t w_hi = vshrq_n_u8(w_int4, 4);            // Extract upper nibbles
+
+// Convert to signed int8 if using symmetric zero-point, then proceed with sdot
+// ... (feed w_lo and w_hi into vdotq_s32 as shown in the INT8 example)
+```
+
+### 3.3 FP16: Native Half-Precision (NEON / AVX512-FP16)
+
+Currently, VolvoxAI casts FP16 source models to FP32, doubling the memory bandwidth and cache footprint. Native FP16 execution solves this.
+
+**Hardware support:** ARMv8.2-A provides native `__fp16` arithmetic (`vmlaq_f16`).
+
+**Microkernel Example: ARM NEON FP16**
+```c
+#include <arm_neon.h>
+
+void microkernel_conv2d_fp16_neon(
+    const float16_t* input,
+    const float16_t* packed_weights,
+    float16_t* output)
+{
+    float16x8_t acc = vdupq_n_f16(0.0f); // 8 output channels
+
+    // Inner loop MAC
+    float16x8_t in_val = vdupq_n_f16(input[0]); // Broadcast 1 input to 8 weights
+    float16x8_t w_val = vld1q_f16(packed_weights);
+
+    // Native FP16 Fused-Multiply-Add
+    acc = vfmaq_f16(acc, in_val, w_val);
+
+    vst1q_f16(output, acc);
+}
+```
+
+### 3.4 FP32: Maximum Register Tiling (AVX2 / FMA)
+
+FP32 is inherently memory-heavy. To hide latency, we must use **Register Tiling**. An AVX2 CPU has 16 YMM registers. We use them strictly:
+- 1 for input broadcast
+- 3 for weights
+- 12 for accumulators (computing a `3x8` output tile simultaneously)
+
+**Microkernel Example: AVX2 FP32 (Processing 3 spatial pixels x 8 output channels)**
+```c
+#include <immintrin.h>
+
+void microkernel_conv2d_fp32_avx2(
+    const float* in_p0, const float* in_p1, const float* in_p2, // 3 input pixels
+    const float* packed_weights,
+    float* out_p0, float* out_p1, float* out_p2)
+{
+    // 3 pixels * 8 channels = 3 AVX2 registers for accumulation
+    __m256 acc0 = _mm256_setzero_ps();
+    __m256 acc1 = _mm256_setzero_ps();
+    __m256 acc2 = _mm256_setzero_ps();
+
+    for (int ic = 0; ic < input_channels; ic++) {
+        // Load weights for 8 output channels
+        __m256 w0 = _mm256_loadu_ps(packed_weights + ic * 8);
+
+        // Broadcast input channel 'ic' for each of the 3 pixels
+        __m256 in0 = _mm256_set1_ps(in_p0[ic]);
+        __m256 in1 = _mm256_set1_ps(in_p1[ic]);
+        __m256 in2 = _mm256_set1_ps(in_p2[ic]);
+
+        // Fused Multiply-Add
+        acc0 = _mm256_fmadd_ps(in0, w0, acc0);
+        acc1 = _mm256_fmadd_ps(in1, w0, acc1);
+        acc2 = _mm256_fmadd_ps(in2, w0, acc2);
+    }
+
+    // Apply ReLU and Store
+    _mm256_storeu_ps(out_p0, acc0);
+    _mm256_storeu_ps(out_p1, acc1);
+    _mm256_storeu_ps(out_p2, acc2);
+}
+```
+
+---
+
+## Conclusion & Action Plan
+
+To implement this in VolvoxAI:
+1. **Create an `indirection.c` module**: To pre-calculate pointer buffers during the graph build phase (not runtime).
+2. **Create a `pack_weights.c` module**: To permute weights offline during the `export_safetensors.py` step or at graph initialization.
+3. **Rewrite `quant_cpu_opt.c`**: Strip out the generic C loops. Replace them with discrete microkernels `vx_ukernel_qconv2d_int8_sdot`, `vx_ukernel_conv2d_fp32_avx2`, etc., routed dynamically based on CPU feature detection (`CPUID` / `getauxval`).

package/js/CPUEngine.js

@@ -0,0 +1,241 @@
+import { _cpuPReLU } from './ops/pReLU.js';
+import { _cpuExpand } from './ops/expand.js';
+import { _cpuDequantizeLinear } from './ops/dequantizeLinear.js';
+import { _cpuTanh } from './ops/tanh.js';
+import { _cpuRMSNorm } from './ops/rMSNorm.js';
+import { _cpuSiLU } from './ops/siLU.js';
+import { _cpuSub } from './ops/sub.js';
+import { _cpuLogSoftmax } from './ops/logSoftmax.js';
+import { _cpuSoftmax } from './ops/softmax.js';
+import { _cpuWhere } from './ops/where.js';
+import { _cpuPad } from './ops/pad.js';
+import { _cpuAveragePool2D } from './ops/averagePool2D.js';
+import { _cpuSlice } from './ops/slice.js';
+import { _cpuConvTranspose2D } from './ops/convTranspose2D.js';
+import { _cpuReduceSum } from './ops/reduceSum.js';
+import { _cpuReduceMean } from './ops/reduceMean.js';
+import { _cpuBatchNorm2D } from './ops/batchNorm2D.js';
+import { _cpuDiv } from './ops/div.js';
+import { _cpuNonMaxSuppression } from './ops/nonMaxSuppression.js';
+import { _cpuGather } from './ops/gather.js';
+import { _cpuGatherElements } from './ops/gatherElements.js';
+import { _cpuCrossAttention } from './ops/crossAttention.js';
+import { _cpuSpatialSoftargmaxY } from './ops/spatialSoftargmaxY.js';
+import { _cpuTranspose } from './ops/transpose.js';
+import { _cpuCrossSDPA } from './ops/crossSDPA.js';
+import { _cpuMeanHeight } from './ops/meanHeight.js';
+import { _cpuMaxPool2D } from './ops/maxPool2D.js';
+import { _cpuInterp1D } from './ops/interp1D.js';
+import { _cpuProfileX } from './ops/profileX.js';
+import { _cpuProfileY } from './ops/profileY.js';
+import { _cpuConcat2 } from './ops/concat2.js';
+import { _cpuUpsample2x } from './ops/upsample2x.js';
+import { _cpuSDPA } from './ops/sDPA.js';
+import { _cpuEmbedding } from './ops/embedding.js';
+import { _cpuMul } from './ops/mul.js';
+import { _cpuAdd } from './ops/add.js';
+import { _cpuGlobalAveragePool } from './ops/globalAveragePool.js';
+import { _cpuClip } from './ops/clip.js';
+import { _cpuReshape } from './ops/reshape.js';
+import { _cpuSplit } from './ops/split.js';
+import { _cpuResize } from './ops/resize.js';
+import { _cpuSigmoid } from './ops/sigmoid.js';
+import { _cpuHardSigmoid } from './ops/hardSigmoid.js';
+import { _cpuHardSwish } from './ops/hardSwish.js';
+import { _cpuReLU } from './ops/reLU.js';
+import { _cpuLeakyReLU } from './ops/leakyReLU.js';
+import { _cpuGELU } from './ops/gELU.js';
+import { _cpuLayerNorm } from './ops/layerNorm.js';
+import { _cpuConv2D } from './ops/conv2D.js';
+import { _cpuConv1D } from './ops/conv1D.js';
+import { _cpuMatMul } from './ops/matMul.js';
+import { _cpuCast } from './ops/cast.js';
+import { _cpuArgMax } from './ops/argMax.js';
+
+
+export class CPUEngine {
+  constructor() {
+    this.tensors = /* @__PURE__ */ new Map();
+    console.log("[VolvoxAI] CPU Fallback Engine ready.");
+  }
+  /**
+   * Allocates CPU memory (ArrayBuffers) for the graph's tensors.
+   */
+  allocateGraph(graph) {
+    this.graph = graph;
+    for (const [name, tensor] of graph.tensors.entries()) {
+      if (!tensor.buffer) {
+        if (tensor.dtype === "int8") {
+          tensor.buffer = new Int8Array(tensor.sizeBytes);
+        } else {
+          tensor.buffer = new Float32Array(tensor.sizeBytes / 4);
+        }
+      }
+    }
+  }
+  /**
+   * Executes the graph linearly on the CPU.
+   */
+  async execute(inputsOrGraph, maybeInputs) {
+    const graph = maybeInputs ? inputsOrGraph : this.graph;
+    const inputs = maybeInputs || inputsOrGraph;
+    for (const [name, data] of Object.entries(inputs)) {
+      const tensor = graph.tensors.get(name);
+      if (tensor && tensor.buffer) {
+        tensor.buffer.set(data);
+      }
+    }
+    for (const node of graph.nodes) {
+      this._runNode(node);
+    }
+    const result = {};
+    if (graph.outputNames && graph.outputNames.length > 0) {
+      for (const name of graph.outputNames) {
+        result[name] = graph.tensors.get(name).buffer;
+      }
+    } else {
+      const lastNode = graph.nodes[graph.nodes.length - 1];
+      for (const [key, t] of Object.entries(lastNode.outputs)) {
+        result[t.name] = graph.tensors.get(t.name).buffer;
+      }
+    }
+    return result;
+  }
+  _runNode(node) {
+    switch (node.opType) {
+      // --- Linear / attention ---
+      case "MatMul": return this._cpuMatMul(node);
+      case "LayerNorm": return this._cpuLayerNorm(node);
+      case "RMSNorm": return this._cpuRMSNorm(node);
+      case "Embedding": return this._cpuEmbedding(node);
+      case "SDPA": return this._cpuSDPA(node);
+      case "CrossSDPA": return this._cpuCrossSDPA(node);
+      case "CrossAttention": return this._cpuCrossAttention(node);
+
+      // --- Convolution / pooling ---
+      case "Conv2D": return this._cpuConv2D(node);
+      case "Conv1D": return this._cpuConv1D(node);
+      case "ConvTranspose2D": return this._cpuConvTranspose2D(node);
+      case "MaxPool2D": return this._cpuMaxPool2D(node);
+      case "AveragePool":
+      case "AveragePool2D": return this._cpuAveragePool2D(node);
+      case "GlobalAveragePool": return this._cpuGlobalAveragePool(node);
+      case "BatchNorm2D": return this._cpuBatchNorm2D(node);
+      case "ResizeNearest2D":
+      case "Resize": return this._cpuResize(node);
+      case "Upsample2x":
+      case "UpsampleNearest2D": return this._cpuUpsample2x(node);
+      case "Interp1D":
+      case "InterpLinear1D": return this._cpuInterp1D(node);
+
+      // --- Activations ---
+      case "ReLU": return this._cpuReLU(node);
+      case "LeakyReLU": return this._cpuLeakyReLU(node);
+      case "PReLU": return this._cpuPReLU(node);
+      case "GELU": return this._cpuGELU(node);
+      case "SiLU":
+      case "Swish": return this._cpuSiLU(node);
+      case "Sigmoid": return this._cpuSigmoid(node);
+      case "HardSwish": return this._cpuHardSwish(node);
+      case "HardSigmoid": return this._cpuHardSigmoid(node);
+      case "Tanh": return this._cpuTanh(node);
+      case "Clip": return this._cpuClip(node);
+
+      // --- Elementwise / reduction ---
+      case "Add": return this._cpuAdd(node);
+      case "Mul": return this._cpuMul(node);
+      case "Sub": return this._cpuSub(node);
+      case "Div": return this._cpuDiv(node);
+      case "Softmax": return this._cpuSoftmax(node);
+      case "LogSoftmax": return this._cpuLogSoftmax(node);
+      case "ReduceSum": return this._cpuReduceSum(node);
+      case "ReduceMean": return this._cpuReduceMean(node);
+      case "ArgMax": return this._cpuArgMax(node);
+
+      // --- Shape / gather / misc ---
+      case "Transpose": return this._cpuTranspose(node);
+      case "Concat":
+      case "Concat2": return this._cpuConcat2(node);
+      case "Split": return this._cpuSplit(node);
+      case "Slice": return this._cpuSlice(node);
+      case "Pad": return this._cpuPad(node);
+      case "Expand":
+      case "Broadcast": return this._cpuExpand(node);
+      case "Gather": return this._cpuGather(node);
+      case "GatherElements": return this._cpuGatherElements(node);
+      case "Where":
+      case "Mask": return this._cpuWhere(node);
+      case "Cast": return this._cpuCast(node);
+      case "DequantizeLinear": return this._cpuDequantizeLinear(node);
+      case "NonMaxSuppression": return this._cpuNonMaxSuppression(node);
+      case "SpatialSoftargmaxY": return this._cpuSpatialSoftargmaxY(node);
+      case "ProfileX": return this._cpuProfileX(node);
+      case "ProfileY": return this._cpuProfileY(node);
+      case "MeanHeight": return this._cpuMeanHeight(node);
+
+      // Shape-only ops just copy their data through to the output buffer.
+      case "Reshape":
+      case "Flatten":
+      case "Squeeze":
+      case "Unsqueeze":
+      case "Dropout":
+      case "Identity": return this._cpuReshape(node);
+
+      default:
+        console.warn(`[VolvoxAI CPU] Executing ${node.opType} is not implemented; node ${node.id} skipped.`);
+    }
+  }
+};
+CPUEngine.prototype._cpuWhere = _cpuWhere;
+CPUEngine.prototype._cpuPad = _cpuPad;
+CPUEngine.prototype._cpuAveragePool2D = _cpuAveragePool2D;
+CPUEngine.prototype._cpuSlice = _cpuSlice;
+CPUEngine.prototype._cpuConvTranspose2D = _cpuConvTranspose2D;
+CPUEngine.prototype._cpuReduceSum = _cpuReduceSum;
+CPUEngine.prototype._cpuReduceMean = _cpuReduceMean;
+CPUEngine.prototype._cpuBatchNorm2D = _cpuBatchNorm2D;
+CPUEngine.prototype._cpuSoftmax = _cpuSoftmax;
+CPUEngine.prototype._cpuLogSoftmax = _cpuLogSoftmax;
+CPUEngine.prototype._cpuSub = _cpuSub;
+CPUEngine.prototype._cpuSiLU = _cpuSiLU;
+CPUEngine.prototype._cpuRMSNorm = _cpuRMSNorm;
+CPUEngine.prototype._cpuTanh = _cpuTanh;
+CPUEngine.prototype._cpuDequantizeLinear = _cpuDequantizeLinear;
+CPUEngine.prototype._cpuExpand = _cpuExpand;
+CPUEngine.prototype._cpuPReLU = _cpuPReLU;
+CPUEngine.prototype._cpuDiv = _cpuDiv;
+CPUEngine.prototype._cpuNonMaxSuppression = _cpuNonMaxSuppression;
+CPUEngine.prototype._cpuGather = _cpuGather;
+CPUEngine.prototype._cpuGatherElements = _cpuGatherElements;
+CPUEngine.prototype._cpuCrossAttention = _cpuCrossAttention;
+CPUEngine.prototype._cpuSpatialSoftargmaxY = _cpuSpatialSoftargmaxY;
+CPUEngine.prototype._cpuTranspose = _cpuTranspose;
+CPUEngine.prototype._cpuCrossSDPA = _cpuCrossSDPA;
+CPUEngine.prototype._cpuMeanHeight = _cpuMeanHeight;
+CPUEngine.prototype._cpuMaxPool2D = _cpuMaxPool2D;
+CPUEngine.prototype._cpuInterp1D = _cpuInterp1D;
+CPUEngine.prototype._cpuProfileX = _cpuProfileX;
+CPUEngine.prototype._cpuProfileY = _cpuProfileY;
+CPUEngine.prototype._cpuConcat2 = _cpuConcat2;
+CPUEngine.prototype._cpuUpsample2x = _cpuUpsample2x;
+CPUEngine.prototype._cpuSDPA = _cpuSDPA;
+CPUEngine.prototype._cpuEmbedding = _cpuEmbedding;
+CPUEngine.prototype._cpuMul = _cpuMul;
+CPUEngine.prototype._cpuAdd = _cpuAdd;
+CPUEngine.prototype._cpuGlobalAveragePool = _cpuGlobalAveragePool;
+CPUEngine.prototype._cpuClip = _cpuClip;
+CPUEngine.prototype._cpuReshape = _cpuReshape;
+CPUEngine.prototype._cpuSplit = _cpuSplit;
+CPUEngine.prototype._cpuResize = _cpuResize;
+CPUEngine.prototype._cpuSigmoid = _cpuSigmoid;
+CPUEngine.prototype._cpuHardSigmoid = _cpuHardSigmoid;
+CPUEngine.prototype._cpuHardSwish = _cpuHardSwish;
+CPUEngine.prototype._cpuReLU = _cpuReLU;
+CPUEngine.prototype._cpuLeakyReLU = _cpuLeakyReLU;
+CPUEngine.prototype._cpuGELU = _cpuGELU;
+CPUEngine.prototype._cpuLayerNorm = _cpuLayerNorm;
+CPUEngine.prototype._cpuConv2D = _cpuConv2D;
+CPUEngine.prototype._cpuConv1D = _cpuConv1D;
+CPUEngine.prototype._cpuMatMul = _cpuMatMul;
+CPUEngine.prototype._cpuCast = _cpuCast;
+CPUEngine.prototype._cpuArgMax = _cpuArgMax;

package/js/Graph.js

@@ -0,0 +1,49 @@
+import { Tensor } from './Tensor.js';
+
+export class Graph {
+  constructor() {
+    this.nodes = [];
+    this.tensors = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Define an input tensor
+   */
+  addInput(name, shape, dtype = "float32") {
+    const tensor = new Tensor(name, shape, dtype, false);
+    this.tensors.set(name, tensor);
+    return tensor;
+  }
+  /**
+   * Define a weight tensor (learned parameter)
+   */
+  addWeight(name, shape, dtype = "float32") {
+    const tensor = new Tensor(name, shape, dtype, true);
+    this.tensors.set(name, tensor);
+    return tensor;
+  }
+  /**
+   * Add a computation operation to the graph
+   * @param {string} opType - e.g., 'MatMul', 'Conv2D', 'LayerNorm'
+   * @param {Object} inputs - Key-value pair of input names to Tensor objects
+   * @param {Object} outputs - Key-value pair of output names to Tensor shapes
+   * @param {Object} params - Uniform parameters for the shader (e.g., stride, kernel size)
+   */
+  addOp(opType, inputs, outputs, params = {}) {
+    const outTensors = {};
+    for (const [key, shape] of Object.entries(outputs)) {
+      const outName = `${opType}_${this.nodes.length}_out_${key}`;
+      const t = new Tensor(outName, shape, "float32", false);
+      this.tensors.set(outName, t);
+      outTensors[key] = t;
+    }
+    const node = {
+      id: this.nodes.length,
+      opType,
+      inputs,
+      outputs: outTensors,
+      params
+    };
+    this.nodes.push(node);
+    return outTensors;
+  }
+};