volvoxai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VolvoxAI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# VolvoxAI
+
+**A zero-dependency, bare-metal deep learning inference engine for the browser,
+Node.js, and native Windows/Linux/macOS/Android targets.**
+
+VolvoxAI runs exported neural-network graphs without shipping a full ML runtime.
+Train in PyTorch or another framework, export to a small Volvox blueprint plus
+safetensors weights, and run inference through WebNN, WebGPU, WASM SIMD, pure JS,
+or a freestanding native C binary.
+
+The project is inference-only. It 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.
+
+## Highlights
+
+- Browser tiers: WebNN, WebGPU, WASM SIMD, and pure-JS CPU fallback.
+- Zero runtime dependency path: vanilla JS plus WGSL with optional freestanding WASM.
+- Small runtime artifacts: about 167 KiB minified JS, 55 KiB WASM, and a
+  roughly 695 KiB native Linux executable in current builds.
+- Native runtime: freestanding C with dynamic Vulkan, OpenGL, Metal, and Android
+  NNAPI loading.
+- Optimization-focused internals: operator fusion, weight packing, quantized CPU
+  islands, vectorized WGSL/C kernels, and backend-specific dispatch.
+- Model format: `config.json` graph blueprint plus `model.safetensors` weights.
+- Shader source: WGSL for browser WebGPU and native shader generation.
+- Examples: EfficientDet Lite0 object detection and TinyStories-1M text generation.
+- License: MIT.
+
+## Install
+
+```bash
+npm install volvoxai
+```
+
+For local development from this repository:
+
+```bash
+npm install
+npm run build:all
+```
+
+The browser bundle is emitted to:
+
+```text
+dist/volvoxai.js
+dist/volvoxai.min.js
+```
+
+The WASM tier also needs `volvoxai.wasm`. The reproducible Docker build copies it
+into `dist/`:
+
+```bash
+make build_web
+```
+
+## Browser Usage
+
+```javascript
+import { VolvoxAI } from './volvoxai.js';
+
+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);
+
+const inputs = {
+  images: new Float32Array(1 * 224 * 224 * 3),
+};
+
+const output = await executor.execute(inputs);
+```
+
+On WebGPU, `execute()` currently returns a `GPUBuffer` for the final node's first
+output. WASM and CPU return a map keyed by `graph.outputNames`.
+
+## Native Usage
+
+```bash
+make build_native
+
+./native/volvoxai generate models/tinystories_1m \
+  --prompt "Once upon a time, Lily" \
+  --max-new 50
+```
+
+Generic tensor execution:
+
+```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 \
+  --last-token 4
+```
+
+## Example Models
+
+Model weights are not committed. Regenerate the example packages from public
+sources:
+
+```bash
+make models_deps
+make models_efficientdet
+make models_tinystories
+```
+
+See [docs/models.md](docs/models.md) for export details.
+
+## Repository Layout
+
+```text
+js/          Browser and Node engine implementation
+shaders/     WGSL compute shaders
+native/      Freestanding C engine and native backends
+runtime/     Rust service wrapper around the C engine
+examples/    Browser examples
+tools/       Export, shader, and test utilities
+docs/        Detailed documentation
+```
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md)
+- [Browser and Node runtime](docs/browser-runtime.md)
+- [Native runtime](docs/native-runtime.md)
+- [Model format](docs/model-format.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.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/bin/volvox.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { VolvoxAI } from '../js/index.js';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const program = new Command();
+
+program
+  .name('volvox')
+  .description('Volvox AI CLI for running local inference')
+  .version('0.1.0');
+
+program
+  .command('run')
+  .description('Run inference with a given model and input')
+  .requiredOption('-m, --model <path>', 'Path to the safetensors model file')
+  .option('-b, --backend <type>', 'Backend to use (wasm, cpu)', 'wasm')
+  .action(async (options) => {
+    try {
+      installFileFetchShim();
+      console.log(`[Volvox CLI] Initializing Engine (Backend: ${options.backend})...`);
+      const cliDir = path.dirname(fileURLToPath(import.meta.url));
+      const wasmPath = path.resolve(cliDir, '..', 'volvoxai.wasm');
+      const engine = await VolvoxAI.init(options.backend, wasmPath);
+
+      console.log(`[Volvox CLI] Loading Model: ${options.model}`);
+      if (!fs.existsSync(options.model)) {
+        console.error(`Error: Model file not found at ${options.model}`);
+        process.exit(1);
+      }
+      
+      const modelUrl = 'file://' + path.resolve(options.model);
+      const graph = await engine.loadGraph(modelUrl);
+      
+      console.log(`[Volvox CLI] Compiling Model...`);
+      const executor = await engine.compile(graph, modelUrl);
+
+      console.log(`[Volvox CLI] Model Ready! Provide input data via scripts for full inference.`);
+      // TODO: In a real CLI, we would parse JSON inputs or specific tensors,
+      // and call executor.execute(inputs).
+      
+    } catch (err) {
+      console.error('[Volvox CLI] Error during execution:', err);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('info')
+  .description('Print system and engine info')
+  .action(async () => {
+    console.log('Volvox AI Engine CLI');
+    console.log('Node.js:', process.version);
+    console.log('Available backends: wasm, cpu');
+  });
+
+program.parse();
+
+function installFileFetchShim() {
+  const nativeFetch = globalThis.fetch;
+  globalThis.fetch = async (url, init) => {
+    const href = typeof url === 'string' ? url : url?.url;
+    if (href && href.startsWith('file://')) {
+      const data = await fs.promises.readFile(fileURLToPath(href));
+      return new Response(data, { status: 200 });
+    }
+    return nativeFetch(url, init);
+  };
+}