volvoxai 0.2.0 → 0.5.0

package/README.md

@@ -1,447 +1,285 @@
 # VolvoxAI
 
-**A zero-dependency, bare-metal deep learning engine for the
-browser, Node.js, and native Windows/Linux/macOS/Android targets.**
-
-> 🧭 **New here — want to *understand* how AI actually works, not just use a library?**
-> This repo doubles as a from-scratch **textbook** built on its own real code. Pick your path:
->
-> - 🌱 **Just curious what AI really is?** → [Start the **Idea track**](docs/textbook/README.md) — plain words, analogies, **no code or math required**. A motivated 11-year-old can follow it.
-> - 🔧 **Can code a little and want to see it run?** → [The **Build track**](docs/textbook/README.md) — the same ideas in graphs, JavaScript, and operators.
-> - 🔬 **A developer who wants the engine?** → [The **Deep track**](docs/textbook/README.md) + [ARCHITECTURE.md](ARCHITECTURE.md) — quantization, native, optimization, and training internals.
->
-> One book, three depths. Everything below this line is the **product / release reference** for people who just want to install and ship.
-
----
-
-VolvoxAI runs and trains neural-network graphs without shipping a full ML
-runtime. Load a small Volvox blueprint plus safetensors weights, or use the full
-entry to create an empty model, initialize its parameters, and build it entirely
-through the API.
-The resulting graph can run through WebNN, WebGPU, WASM SIMD, pure JS, or a
-freestanding native C binary.
-
-The project is built for small, inspectable model packages, constrained web
-apps, extensions, local tools, and edge devices where heavyweight runtimes such
-as ONNX Runtime Web or TensorFlow.js are too large or too opaque. Training is an
-explicit path: inference does not allocate gradients, optimizer state, or
-backward pipelines. The inference bundle has no training dependency; the full
-bundle adds training as a separate public entry.
+**A deep-learning runtime for browsers, Node.js, and native desktop, phone,
+and robot applications.**
 
-## Highlights
-
-- Runs in browsers, Node.js, and native applications through WebNN, WebGPU,
-  WASM, JavaScript CPU, native CPU, Vulkan, OpenGL, and Metal.
-- Compact current Linux x86-64 artifacts: 360 KiB WASM-only JS, 683 KiB
-  multi-backend inference JS, 174 KiB inference WASM, and 936 KiB native
-  inference; full training builds remain about 1–1.4 MiB.
-- No external ML runtime: models use inspectable `config.json` graphs and
-  safetensors weights.
-- Clean inference/training separation: inference builds contain no autograd,
-  optimizer state, backward shaders, or public training symbols.
-- Built-in model construction, training, LoRA, checkpointing, PTQ, and portable
-  W8A8 execution.
-- Extensible browser and native backend APIs with embedded native shaders and
-  portable CPU fallback.
-- Includes EfficientDet, TinyStories, multimodal examples, and a three-level
-  textbook.
-
-## Install
-
-```bash
-npm install volvoxai
-```
-
-For local development from this repository:
+VolvoxAI runs compact model packages without embedding a general-purpose ML
+framework. The JavaScript package has no runtime npm dependencies. Use it to recognize objects, process text, or adapt a small model on
+the device where the data is produced. The same graph and weights can run in a
+browser through WebAssembly or in a native C application.
 
-```bash
-npm install
-npm run typecheck
-npm run build:all
-```
+The engine supports both inference and training. A browser application can
+coordinate concurrent requests in one runtime; an edge service can schedule
+vision and language workloads with explicit request and result-memory budgets.
+Model-specific preprocessing, generation policy, and evaluation stay in the
+application.
 
-The TypeScript sources are checked before esbuild emits the six fixed-name
-JavaScript bundles; the build preserves an existing WASM sidecar. For version
-0.2.0, the complete browser release consists of:
+This repository is also a from-scratch textbook. Start with
+[How AI Actually Works](docs/textbook/README.md) ([한국어](docs/textbook/ko/README.md))
+to learn tensors, attention, training, quantization, and the engine itself.
+For a first run, follow the [quickstart](docs/quickstart.md).
 
-```text
-dist/0.2.0/volvoxai.js            # readable inference
-dist/0.2.0/volvoxai.min.js        # minified inference
-dist/0.2.0/volvoxai.full.js       # readable inference + training
-dist/0.2.0/volvoxai.full.min.js   # minified inference + training
-dist/0.2.0/volvoxai.wasm.js       # readable WASM-only inference + training/PTQ
-dist/0.2.0/volvoxai.wasm.min.js   # minified WASM-only inference + training/PTQ
-dist/0.2.0/volvoxai.wasm          # forward kernels used by the WASM backend
-dist/0.2.0/volvoxai.full.wasm     # forward kernels plus C training/PTQ ABIs
-```
-
-`volvoxai.wasm` deliberately exports no training symbol. `volvoxai.full.wasm`
-keeps every forward export and adds C loss, backward, gradient utility, SGD, and
-AdamW operators plus generic PTQ observation, affine quantization, weight
-packing, and bias packing. Quantized LoRA synchronization is one higher-level
-use of those reusable kernels. From a clean checkout, the reproducible Docker
-build creates all eight files:
+## Highlights
 
-```bash
-make build_web
+- **One model package across platforms.** Inspectable `graph.json` and
+  SafeTensors weights describe the computation and its data.
+- **CPU and GPU execution.** Browser/Node WASM SIMD, browser WebGPU, and native
+  CPU with optional Vulkan, OpenGL/OpenGL ES, CUDA, and Metal backends.
+- **Bounded dynamic shapes.** Name a dimension such as sequence length and give
+  it finite bounds. The compiler checks the supported domain; each request
+  supplies its actual shape without rebuilding the model.
+- **Independent sessions and stable results.** Reuse a compiled model across
+  execution contexts. Each context owns its shape and decode state, and each
+  result retains its own named output snapshot until released.
+- **Scheduling and batching.** Run a single request directly, or use bounded
+  queues, priorities, deadlines, and compatible-request batching. Decode
+  contexts support row execution and paged KV caches on qualified routes.
+- **On-device training.** The full profile provides SGD/AdamW, gradient
+  accumulation, checkpoints, and LoRA authoring. Training updates private
+  weights; an explicit commit publishes them for new inference compilations.
+- **Post-training quantization.** Calibrate a float model and produce an explicit
+  W8A8 package, then measure its accuracy and latency against the original.
+- **Separate inference and full builds.** Inference artifacts exclude compiled
+  training code, optimizer state, and training shaders.
+
+Support depends on the operator, dtype, shape, and selected backend. See the
+[operator guide](docs/operation_list.md) and [validation coverage](docs/c-runtime-validation.md)
+for the tested domains.
+
+## Install and choose a profile
+
+```sh
+npm install volvoxai
 ```
 
-The npm `prepack` check rejects a missing sidecar or stale extra artifact.
-`npm run build:all` bundles JavaScript but cannot compile C/WASM from a clean
-checkout; use `make build_web` before `npm pack` or `npm publish`.
-
-## Browser Usage
-
-```javascript
-import { VolvoxAI } from './dist/0.2.0/volvoxai.js';
+| Your application needs | JavaScript entry | WASM companion |
+| --- | --- | --- |
+| CPU inference, text processing, graph construction, scheduling | `volvoxai/lite` | `volvoxai.lite.wasm` |
+| WebGPU inference, training, or PTQ | `volvoxai` | `volvoxai.wasm` |
 
-const engine = await VolvoxAI.init(); // auto: WebNN, WebGPU, WASM, CPU
-const graph = await engine.loadGraph('./models/my-model/model.safetensors');
-const executor = await engine.compile(graph);
+Both entries run WASM CPU inference. WebGPU belongs to the **full** entry (`volvoxai`).
+Serve the matching WASM file beside the JavaScript bundle, or supply `wasmUrl`
+when your bundler or CDN puts it elsewhere. See [browser and Node deployment](docs/browser-runtime.md).
 
-const inputs = {
-  images: new Float32Array(1 * 224 * 224 * 3),
-};
+For repository development, build both JavaScript entries and their companions:
 
-const output = await executor.execute(inputs);
+```sh
+make build_web
 ```
 
-Every input referenced by a blueprint node must be declared in `config.inputs`,
-loaded as a named weight, or produced by an earlier node. The loader does not
-invent a default image input or shape for an undeclared name.
-
-On WebGPU, `execute()` currently returns a `GPUBuffer` for the final node's first
-output. The executor owns GPU buffers; core `Tensor` objects contain portable
-descriptors and optional CPU storage, not device handles. WASM and CPU return a
-map keyed by `graph.outputNames`. All four browser engines share the versioned
-backend lifecycle, named registration hook, and decode-session facade described
-in [Browser and Node runtime](docs/browser-runtime.md#javascript-backend-contract).
+This uses the repository's Docker toolchain. [Quickstart](docs/quickstart.md)
+explains prerequisites, local builds, and the first runnable example.
 
-### WASM-only Chrome extensions, training, and PTQ
+## Model packages
 
-For a Manifest V3 extension that needs no CPU, WebNN, WebGPU, or shader code,
-ship exactly one JavaScript variant, the full WASM sidecar, and the model:
+A typical package contains:
 
 ```text
-vendor/volvoxai.wasm.min.js
-vendor/volvoxai.full.wasm
-model/config.json
-model/model.safetensors
+graph.json
+model.safetensors
 ```
 
-`volvoxai.wasm.min.js` names the only selectable backend, not a forward-only
-capability set. It uses `volvoxai.full.wasm` because updating LoRA A/B still
-requires backward propagation through the surrounding graph. The ordinary
-`volvoxai.wasm` sidecar remains forward-only for the standard inference entry.
-The `./wasm` and `./wasm/min` package subpaths are browser-only and deliberately
-omit Node's filesystem loader; Node applications should use `.` or `./full`
-and select the WASM backend.
+The graph describes named inputs, operations, output tensors, and dimension
+bounds. SafeTensors stores the weights; larger packages may use several shards.
+Every graph has the exact `"format": "volvox-graph/v1"` discriminator.
+A static graph uses an empty `dimensions` object; a dynamic graph declares each
+symbol's finite range. See the [model format](docs/model-format.md).
 
-```javascript
-import { VolvoxAI } from './vendor/volvoxai.wasm.min.js';
-
-const runtime = await VolvoxAI.init(
-  'wasm',
-  chrome.runtime.getURL('vendor/volvoxai.full.wasm'),
-);
-const graph = await runtime.loadGraph(
-  chrome.runtime.getURL('model/model.safetensors'),
-);
-const executor = await runtime.compile(graph);
-
-const step = await runtime.trainLoRAStep(graph, {
-  inputs: teacherForcedInputs,
-  logitsTensor: 'logits',
-  targets: correctedTokenIds,
-  trainableTensors: ['decoder.lora_a', 'decoder.lora_b'],
-  updateMode: 'adamw',
-  optimizer: { learningRate: 1e-4 },
-});
-
-// Applied updates refresh packed WASM weights, so this executor observes A/B.
-const corrected = await executor.execute(nextInputs);
+Recreate the example models from their public sources:
+
+```sh
+make models_deps
+make models_efficientdet
+make models_tinystories
+make validate_model_packages
 ```
 
-The same runtime exposes the existing stateless C PTQ implementation as a
-generic typed toolkit, independent of LoRA:
+Weights are not committed. [Models and exporters](docs/models.md) explains the
+sources and export options. The browser demos are
+[EfficientDet](examples/efficientdet_lite0.html) and [TinyStories](examples/tinystories.html).
 
-```javascript
-const ptq = await runtime.createPTQ();
-try {
-  const observer = ptq.createObserver();
-  observer.observe(calibrationValues); // Float32Array; repeat for more samples
-
-  const parameters = observer.parameters({
-    dtype: 'int8',
-    scheme: 'symmetric',
-  });
-  const activation = ptq.quantize(values, parameters);
-  const weight = ptq.packWeight(weightValues, [outputSize, inputSize], { axis: 0 });
-  const bias = ptq.packBias(biasValues, parameters.scale, weight.scales);
-} finally {
-  ptq.dispose();
-}
-```
+## Web inference
 
-These calls run in a private scratch WASM instance and return caller-owned
-typed arrays. They do not rewrite a graph or choose how an application stores
-or deploys the result. Reuse one toolkit across related operations and call
-`dispose()` when finished so its isolated WASM memory can be garbage-collected.
-Developers may use it for calibration, conversion, custom model builders, or
-their own update workflow. Browser safetensors and graph/package authoring
-remain JavaScript orchestration rather than C file I/O.
-
-The model must represent LoRA A/B as explicit initialized F32 graph weights and
-wire them through its low-rank MatMul/Add branch. Listing only those names in
-`trainableTensors` freezes the base model. A corrected answer string is
-application policy: tokenize it and construct teacher-forced model inputs,
-target token IDs, and any loss mask before calling `trainLoRAStep()`.
-Immutable staged adapter snapshots are deployment/routing objects, not
-autograd parameters; checkpoint or export the updated explicit graph factors
-after training.
-
-To retain an existing W8A8 inference topology, use a separate supported F32
-training graph as the persistent master and bind its A/B factors to the I8
-factor weights already present in the inference graph:
+The lifecycle is **create a runtime → load a model → compile → run → read outputs**.
+This small ReLU graph needs no downloaded weights. Save the example as an `.mjs`
+file in an installed project or this repository and run it with Node:
 
 ```javascript
-const trainer = await runtime.createQuantizedLoRATrainer(
-  f32TrainingGraph,
-  w8InferenceGraph,
-  {
-    bindings: [
-      { master: 'decoder.lora_a', target: 'decoder.lora_a.i8', transpose: true },
-      { master: 'decoder.lora_b', target: 'decoder.lora_b.i8', transpose: true },
-    ],
-  },
-);
+import { EngineHost, VxInferenceServiceClient, pb } from 'volvoxai';
 
+const host = new EngineHost();
+const inference = new VxInferenceServiceClient(host);
 try {
-  // Use this once only when starting from a W8 snapshot without an F32
-  // checkpoint. Do not dequantize again after training begins.
-  await trainer.initializeMastersFromQuantized();
-
-  await trainer.trainStep({
-    inputs: teacherForcedInputs,
-    logitsTensor: 'logits',
-    targets: correctedTokenIds,
-    trainableTensors: ['decoder.lora_a', 'decoder.lora_b'],
-    updateMode: 'adamw',
-    optimizer: { learningRate: 1e-4 },
-  });
-
-  const corrected = await trainer.engine.execute(nextQuantizedInputs);
+  const runtime = await inference.createRuntime(new pb.CreateRuntimeRequest());
+  const graphDocument = new TextEncoder().encode(JSON.stringify({
+    format: 'volvox-graph/v1', dimensions: {},
+    inputs: { x: { dtype: 'float32', shape: [2] } },
+    nodes: [{
+      id: 'relu', opType: 'ReLU', inputs: { input: 'x' },
+      outputs: { out: { tensor: 'y', dtype: 'float32', shape: [2] } },
+      params: {},
+    }],
+    outputs: ['y'],
+  }));
+  const model = await inference.loadModel(new pb.LoadModelRequest({
+    runtimeId: runtime.runtimeId,
+    package: new pb.ModelPackage({ graphDocument }),
+  }));
+  const compiled = await inference.compileModel(new pb.CompileModelRequest({
+    modelId: model.modelId,
+  }));
+  const values = Float32Array.of(-2, 3);
+  const result = await inference.run(new pb.RunRequest({
+    compiledModelId: compiled.compiledModelId,
+    inputs: [new pb.Tensor({
+      name: 'x', dtype: pb.DataType.DATA_TYPE_F32, shape: [2n],
+      inline: new Uint8Array(values.buffer, values.byteOffset, values.byteLength),
+    })],
+  }));
+  const output = await inference.readOutput(new pb.ReadOutputRequest({
+    resultId: result.resultId, name: 'y',
+  }));
+  console.log(Array.from(new Float32Array(output.tensor.inline.slice().buffer)));
+  // [0, 3]
 } finally {
-  await trainer.dispose();
+  await host.close();
 }
 ```
 
-The C conversion helper transposes the builder's IN_OUT factors into canonical
-OUT_IN I8 weights and recomputes symmetric axis-0 scales. The JavaScript trainer
-stages every converted factor before atomically updating the graph, then
-refreshes the WASM raw bytes, scale metadata, and packed Q8 caches without
-changing nodes or activation descriptors. Version 0.2.0 requires I8 targets
-with zero points of zero and all-zero I32 LoRA biases. Persist the F32
-checkpoint and optimizer state as the resumable authority; the W8 graph is an
-inference snapshot. After restoring an F32 checkpoint, call `trainer.sync()`
-instead of `initializeMastersFromQuantized()`.
-
-This is F32-master LoRA requantization, not QAT or backward support for a deep
-W8A8 graph. `QLinear`/`QGemm` are still rejected by strict WASM training, so
-the separate training graph must provide the supported F32 backward path. The
-inference graph must already contain its quantized LoRA branch; this API does
-not rewrite graph topology.
-
-The extension must package all executable code locally and enable WebAssembly
-for extension pages. Use an ES-module service worker and this CSP:
-
-```json
-{
-  "manifest_version": 3,
-  "background": { "service_worker": "service-worker.js", "type": "module" },
-  "content_security_policy": {
-    "extension_pages": "script-src 'self' 'wasm-unsafe-eval'; object-src 'self';"
-  }
-}
-```
+`pb` contains the request, response, and enum types. Tensor shapes use `bigint`
+values such as `2n`; tensor data is an exact byte view. Inputs always state their
+name, dtype, and concrete shape so the engine can validate the whole batch.
 
-The WASM-only release bundle contains no dynamic `import()`, which Chrome
-extension service workers do not support. `web_accessible_resources` is not
-needed when only extension-owned pages/workers fetch the packaged model and
-sidecar; declare the narrow resources explicitly if a normal web page must
-fetch them. See [Browser and Node runtime](docs/browser-runtime.md#wasm-only-manifest-v3-extensions)
-for complete packaging notes.
+For a downloaded model, supply `graphPath` and `weightPaths`, or load their bytes
+into `ModelPackage`. `GetModelInfo` reports the required inputs and outputs.
+The [browser runtime guide](docs/browser-runtime.md) shows both forms, WebGPU
+selection, result polling, and session cleanup. The repository also includes
+[a minimal inference script](examples/call_inference.mjs).
 
-## Training from APIs
+## Scheduling and generation
 
-Use the full entry when calling training, checkpoint, or gradient-accumulation
-APIs:
+DIRECT is the default for one-shot inference. Choose SCHEDULED explicitly when
+several producers need queue admission and arbitration in the same Runtime.
+Only requests for a compatible compiled route can share a physical batch;
+batching is useful when the graph preserves each request's independence.
 
-```javascript
-import { VolvoxAI } from './dist/0.2.0/volvoxai.full.js';
-```
+For text generation, prefill a context with a prompt and then advance it one
+step at a time. Its KV cache retains previous attention state. Paged caches can
+share prefixes and retire individual lanes. `DecodeGenerate` handles a supported
+fixed-count greedy feedback loop; sampling, stop conditions, and task policy
+remain application decisions. See [scheduling and dynamic batching](docs/scheduling-and-dynamic-batching-design.md).
 
-In this module, the familiar `VolvoxAI`, `Graph`, and `ModelBuilder` exports are
-the training-capable variants; the explicit `TrainingVolvoxAI`,
-`TrainingGraph`, and `TrainingModelBuilder` names are also available.
-Initializers, optimizer state, and training-only builder helpers are deliberately
-absent from the inference entry.
-
-Models can start from an empty graph and initialized weights; no PyTorch export
-or seed safetensors file is required. The JavaScript builder provides generic
-GroupNorm, MoE and routed bottleneck adapters, deterministic Dropout, and
-explicit trainable-tensor selection. The repository's
-`examples/seq2seq_training/Seq2SeqBuilder.js` composes those primitives into an
-encoder-decoder with multimodal source features and teacher forcing; that
-model-family policy is not exported by either package entry.
-
-`trainStep()` accepts either the legacy single cross-entropy target or a
-`losses` list with independent logits, targets, weights, masks, and normalizers.
-Repeated logits tensors are allowed and their gradients add. Accumulation has
-reset/flush controls, and `maxGradNorm` clips one global norm over all trainable
-tensors. JavaScript CPU and WebGPU regenerate the same SDPA/CrossSDPA
-attention-dropout mask in forward and backward; inference never applies it.
-
-For an explicit C-backed browser training path, initialize the full entry with
-the full sidecar and set `backend: "wasm"`. It is strict: its current portable
-contracts are listed in [the operation status reference](docs/operation_list.md).
-Unsupported or non-canonical layouts are rejected before any model state
-changes, including ambiguous square linear layouts.
-
-Native CPU, Vulkan, OpenGL compute, and Metal support deterministic standalone
-Dropout training while keeping inference as an identity. Their SDPA/CrossSDPA
-training paths also implement after-softmax attention-probability dropout and
-regenerate the mask during backward; unsupported GPU layouts fall back to the
-matching complete native CPU path. See
-[model construction, routing, and training](docs/model_builder_training.md) and
-the [operation matrix](docs/operation_list.md) for exact backend limits.
-
-## Native Usage
-
-```bash
-make build_native
-
-# inference-only executable
-./native/volvoxai --help
+## Full-profile training
 
-# inference + training executable
-./native/volvoxai-full --help
-```
+Training follows **construct/load → train → evaluate → commit or roll back → save**.
+The Trainer owns private parameters, gradients, and optimizer state. Existing
+compiled inference models keep their earlier weights after a commit; compile
+again when you want to serve the new revision.
 
-The fixed release executables stay model-agnostic: both expose `run`, and only
-`volvoxai-full` additionally exposes `train`. They do not choose vocabulary
-files, decode images, or implement generation and task postprocessing.
+Use `FullEngineHost` and `VxTrainingServiceClient` from `volvoxai/full`.
+The [training guide](docs/model_builder_training.md) walks through building a
+small classifier, running AdamW, saving a checkpoint, and resuming it.
+It also covers multiple losses, accumulation, shape-cache limits, and LoRA.
 
-Generic tensor execution:
+The [quantization guide](docs/quantization.md) continues from a float package to
+calibration and W8A8 export. Full WASM supports the complete PTQ workflow using
+bytes; your browser application chooses how to save them.
 
-```bash
-./native/volvoxai run models/tinystories_1m \
-  --input tokens=models/tinystories_1m/tokens.i32 \
-  --input positions=models/tinystories_1m/positions.i32 \
-  --output logits=out.f32 \
-  --row 4
-```
+## Native use
 
-Raw input and output filenames must end in the declared storage dtype suffix:
-`.f32`, `.f16`, `.i32`, `.i8`, or `.u8`. Row output is currently F32-only.
-
-Generic cross-entropy training is available only in the full executable:
-
-```bash
-./native/volvoxai-full train models/my_model \
-  --input input=batch.f32 \
-  --targets targets.i32 \
-  --logits logits \
-  --trainable classifier.weight \
-  --trainable classifier.bias \
-  --steps 10 \
-  --learning-rate 0.001 \
-  --output-weights trained.safetensors \
-  --output-optimizer optimizer.safetensors
+```sh
+make build_native_profiles
+./native/volvoxai-lite --help
+./native/volvoxai --help
 ```
 
-Use `--input-optimizer` to resume saved optimizer state. Run
-`./native/volvoxai-full train --help` for all optimizer and backend options.
-
-Model-facing native task wrappers are an opt-in example:
+Both executables run named raw tensors. Full additionally provides `train`.
+For example, after the [quickstart](docs/quickstart.md#4-run-tinystories-from-native-c)
+prepares a TinyStories package and six I32 tokens and positions:
 
-```bash
-make -C examples native_task_cli
-
-examples/target/bin/volvoxai-tasks generate models/tinystories_1m \
-  --prompt "Once upon a time, Lily" \
-  --max-new 50
+```sh
+./native/volvoxai-lite run models/tinystories_1m \
+  --input 'tokens[1,6]=build/quickstart/tokens.i32' \
+  --input 'positions[1,6]=build/quickstart/positions.i32' \
+  --output logits=build/quickstart/logits.f32
 ```
 
-That example owns image decoding, vocabulary-file selection, generation loops,
-and the `generate`, `classify`, `detect`, `ctc`, `seq2seq`, and `chat` commands.
-
-Native executables do not need a shader directory. For shader development,
-point `VOLVOXAI_SHADER_DIR` at a generated directory containing `spv/`,
-`glsl/`, `gles/`, and `metal/`; VolvoxAI logs once when that override is used.
+Use the [native guide](docs/native-runtime.md) for input preparation, CPU threads,
+backend selection, embedding, and macOS/Android builds. The
+[task CLI](examples/native_task_cli/README.md) adds image decoding and detection.
+Native releases embed shaders; `VOLVOXAI_SHADER_DIR` provides a development
+override and logs once when used.
 
-## Example Models
+## Python
 
-Model weights are not committed. Regenerate the example packages from public
-sources:
+The [Python package](python/README.md) provides native CPU/GPU inference,
+training, quantization, tokenization, graph planning and scheduling through the
+same generated API. Linux x86_64 wheels bundle inference/full libraries and the
+loader, with CUDA, Vulkan and OpenGL backends. They also include ONNX conversion
+and a PTQ command-line workflow.
 
-```bash
-make models_deps
-make models_efficientdet
-make models_tinystories
+```sh
+make build_wheel
+python3 -m pip install dist/python/0.5.0/*.whl
 ```
 
-See [docs/models.md](docs/models.md) for export details.
+For an exported model with one input, `InferenceSession` handles loading,
+compilation, NumPy input/output and cleanup. CPU and automatic thread selection
+are the defaults; FP32/INT8 precision comes from the model:
 
-## Repository Layout
+```python
+import numpy as np
+import volvoxai as vx
 
-```text
-ts/core/             TypeScript inference graph/data objects and model-agnostic orchestration
-ts/ops/              TypeScript operators plus graph validation and normalization
-ts/backends/         TypeScript CPU, WASM, WebGPU, and WebNN execution/device resources
-ts/training/         TypeScript training graphs/builders, autograd, optimizers, checkpoints
-examples/             Model-specific applications and reference integrations
-shaders/inference/   Forward WGSL sources
-shaders/training/    Backward and training WGSL sources
-native/include/      Public C APIs
-native/src/shader_store.*  Lazy embedded-shader asset loader
-native/src/runtime/  Model state, graph, memory, and execution
-native/src/kernels/  Portable and optimized CPU/WASM kernels
-native/src/backends/ Vulkan, OpenGL, Metal, and NNAPI integrations
-native/src/training/ Training-specific orchestration
-native/cli/          Fixed model-agnostic command-line applications
-native/tests/        Native tests
-runtime/             Rust service wrapper around the C engine
+with vx.InferenceSession("path/to/model") as session:
+    outputs = session.run(np.load("input.npy"))
+```
+
+Use `AsyncInferenceSession` for asyncio, `vx.quantize` for streaming NumPy
+calibration, and `TrainingSession` for training, saving and checkpoint resumption.
+These workflows select the appropriate library and raise Python exceptions.
+`InferenceSession.run_tensors()` retains CPU/CUDA results, reuses them as
+inputs, and shares compatible buffers with PyTorch through DLPack.
+`run()` continues to return NumPy arrays; GPU array libraries remain optional.
+See the Python guide for full workflows, supported environments and PyPI
+publishing. Python artifacts live outside the fixed npm release directory.
+
+## Documentation and API reference
+
+The [documentation index](docs/README.md) separates learning material from
+integration and engine-development guides. Useful starting points:
+
+- [Quickstart](docs/quickstart.md) and [textbook](docs/textbook/README.md)
+- [Model format](docs/model-format.md) and [operator support](docs/operation_list.md)
+- [Architecture](ARCHITECTURE.md) and [backend development](docs/backend-sdk.md)
+- [Testing](docs/testing.md) and [profiling](docs/profiling.md)
+
+The schema in [volvoxai.proto](proto/volvoxai.proto) defines the shared API for
+applications and AI agents. For field-level lookup and programmatic discovery,
+use [API discovery](docs/api-discovery.md) and the generated
+[inference](docs/generated/api-contract.inference.md) / [full](docs/generated/api-contract.full.md)
+references. [Runtime integration](runtime/README.md) covers C/Python bindings
+and regeneration. These references complement the task-oriented guides above.
+
+## Build and verify
+
+```sh
+npm ci
+npm run build:all             # build JS first; this removes stale WASM companions
+make build_wasm              # both WASM profiles
+make build_native_profiles   # both native profiles
+npm run test:proto-api
+npm run test:wasm-ptq
+npm run test:wasm-training-smoke
+make test_native
+npm run check:release
 ```
 
-See [ARCHITECTURE.md](ARCHITECTURE.md) for dependency and build-composition
-rules.
-
-## Documentation
-
-- [Quickstart](docs/quickstart.md)
-- [Browser and Node runtime](docs/browser-runtime.md)
-- [Native runtime](docs/native-runtime.md)
-- [Custom backend SDK](docs/backend-sdk.md)
-- [Model format](docs/model-format.md)
-- [W8A8 safetensors companion scales](docs/w8a8-safetensors.md)
-- [Post-training quantization](docs/quantization.md)
-- [Model construction, routing, and training](docs/model_builder_training.md)
-- [Models and exporters](docs/models.md)
-- [Operation support matrix](docs/operation_list.md)
-- [Testing and validation](docs/testing.md)
-- [Roadmap](docs/roadmap.md)
-- [Textbook walkthrough](docs/textbook/README.md) ([한국어](docs/textbook/ko/README.md))
-- [EfficientDet benchmark notes](docs/efficientdet_tflite_vs_volvoxai.md)
-
-## Current Status
-
-VolvoxAI can run real browser and native inference paths, but it is still early.
-Known gaps include WebGPU multi-output readback, broader WebNN coverage, additional
-native/WebGPU shaders for a few fallback ops, browser-side generation helpers,
-and formal CI wiring for the existing smoke tests.
-
-See [docs/roadmap.md](docs/roadmap.md) for the detailed list.
+The fixed release inventory is four JS files (`volvoxai.lite.js`, `volvoxai.lite.min.js`,
+`volvoxai.js`, `volvoxai.min.js`) and two WASM files (`volvoxai.lite.wasm`,
+`volvoxai.wasm`) under `dist/<package-version>/`, plus `native/volvoxai-lite`
+and `native/volvoxai`. See [testing](docs/testing.md) for release gates and
+[deployment](docs/browser-runtime.md#packaging-and-browser-extensions) for runtime ZIPs and extensions.
 
 ## License