ruv-fann

Choose a package

These are five independent Cargo workspaces with 26 Rust packages and two public npm distributions. Running cargo test at the repository root tests the core crate; use the verification driver below to cover the other workspaces. Versions in this checkout are unpublished release candidates. The release inventory records their exact identities and separate registry observations.

Each family has a defined scope. Forecasting currently implements a univariate RNN and simple baselines; LSTM/GRU forecasting architectures return unsupported errors. Agent assignment records scheduling decisions; external task execution depends on the integration you supply. CUDA translation emits source and does not execute a GPU kernel. The native OpenCV bridge calls an installed C++ library, while the portable packages implement a smaller set of operations.

Try the neural-network core

Install Rust, then run the included example:

git clone https://github.com/ruvnet/ruv-FANN.git
cd ruv-FANN
cargo run --locked --example basic_usage

For the published crate, run cargo add ruv-fann in your application. To try changes from this checkout, use cargo add ruv-fann --path /path/to/ruv-FANN instead. Published API documentation describes the published version; new checkout APIs become available after a release.

This example uses explicit weights so you can check the result without training:

use ruv_fann::{ActivationFunction, NetworkBuilder};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut network = NetworkBuilder::<f32>::new()
        .input_layer(2)
        .output_layer_with_activation(1, ActivationFunction::Linear, 1.0)
        .build();

    // Two input weights, followed by the bias weight.
    network.set_weights(&[0.5, -0.25, 0.1])?;
    let outputs = network.run(&[1.0, 2.0])?;
    assert!((outputs[0] - 0.1).abs() < 1e-6);
    println!("Output: {}", outputs[0]);

    Ok(())
}

The calculation is 0.5 × 1.0 − 0.25 × 2.0 + 0.1 = 0.1. A real task needs suitable data and trained weights. Training examples and algorithms include backpropagation, RPROP, Quickprop, Adam, and AdamW.

For repeated inference, the checkout adds Network::run_into(inputs, outputs). Pass a mutable output slice whose length equals num_outputs(). It reuses that buffer and the network's stored neuron values. run() remains the convenient API that returns a vector. Check input and output lengths through the returned Result.

Prepare a network for repeated inference

After training, network.prepare() copies validated parameters into an immutable snapshot. Give each caller its own reusable workspace; several threads can share the same prepared network without sharing mutable neuron caches:

let prepared = network.prepare()?;
let mut workspace = prepared.workspace()?;
let mut output = vec![0.0; prepared.num_outputs()];
prepared.run_into(&[1.0, 2.0], &mut output, &mut workspace)?;

Hot calls allocate no memory. Changing the original network does not change the snapshot; prepare a new one after training or editing weights. Preparation rejects invalid graph indices, non-finite parameters and noncanonical bias state. The default estimated allocation budget is 64 MiB, including one workspace; this is not a process-memory limit. A failed call leaves the output slice unchanged.

Dense rows use contiguous scalar arithmetic; sparse and reordered connections retain their order. This path adds no external inference engine or quantization. Run the complete example with cargo run --locked --example prepared_inference. The current research review explains adoption choices and separate benchmark/evaluation requirements.

Run the same engines in WebAssembly

The ruv-swarm JavaScript package includes prepared inference and historical forecast intervals in its ordinary and SIMD WASM binaries. In Node.js 22.13+:

import { RuvSwarm } from 'ruv-swarm';
const runtime = await RuvSwarm.initialize();
const network = runtime.createNeuralNetwork([2, 1], 'Linear');
network.set_weights(Float64Array.of(2, -1));
const prepared = network.prepare();
network.free();
const output = new Float64Array(1);
prepared.run_into(Float64Array.of(3, 4), output); // [2]
prepared.free();

runtime.createPreparedNetwork(networkJson) also imports native Rust Network<f64> JSON, retaining sparse connection order and all native activations. runtime.createConformalCalibrator(config) fits the shared residual engine with explicit past observations. Its timestamps are safe-integer Unix milliseconds. See the JavaScript guide for formats and limits, or serve the browser example over HTTP. The browser imports the generated WASM bindings directly.

run_into reuses Rust numeric buffers and the output array; JavaScript boundary checks and copies still have a cost. The native f32 benchmark below does not measure browser or Node.js latency. Historical intervals retain their documented time-series coverage limitations. The WASM results show measured timings and the tradeoff for very small networks.

For many samples, create a fixed-capacity batch workspace. Native Rust supports both f32 and f64; input and output slices contain one row after another:

let mut batch = prepared.batch_workspace(2, 1024 * 1024)?;
let inputs = [1.0, 2.0, 3.0, 4.0]; // two rows for a two-input network
let mut outputs = vec![0.0; 2 * prepared.num_outputs()];
prepared.run_batch_into(&inputs, &mut outputs, 2, &mut batch)?;

The JavaScript API exposes prepared.create_batch(capacity) and batch.run_into(inputs, outputs, rows). It reuses numeric buffers and can keep running after the original prepared handle is freed. The SIMD build processes independent samples in parallel without reordering any sample's weighted sum.

Pick the features you need

See Cargo.toml for the precise feature dependency graph. Native Rust gpu tests use software Vulkan. Browser tests load the built Rust WASM bridge and verify matrix results, all 21 activations, invalid inputs, and device lifecycle with Chromium/SwiftShader. A separate harness directly checks all seven WGSL modules and Adam/AdamW updates. These checks establish numerical behavior on software adapters. Physical GPU throughput and every experimental training combination remain unevaluated. See the core review for limits, tolerances, and commands.

Build and test

Use a current stable Rust toolchain for full-repository development. The core declares Rust 1.81; the swarm and all four OpenCV packages declare Rust 1.88. Python 3.11 or newer runs the verification tools. Node 22.13 or newer covers the root tooling and swarm distribution; the standalone CUDA wrapper requires Node 22.12 or newer.

The full OpenCV workspace also needs a C++17 compiler, pkg-config, libclang, and OpenCV 4.4 or newer development files. On Debian/Ubuntu these are typically g++, pkg-config, libclang-dev, and libopencv-dev. See the native setup guide for a checked user-owned prefix option. Portable OpenCV packages can be tested with --exclude opencv-sys. Swarm's SQLite npm addon may also need a C++ build toolchain.

# Inventory every Cargo workspace and npm distribution.
python3 scripts/verify-packages.py --inventory

# Check and test registered libraries, binaries, tests, examples, and benchmarks.
# Install the native OpenCV prerequisites first.
python3 scripts/verify-packages.py --check
python3 scripts/verify-packages.py --test

# Audit all five Cargo lockfiles (requires cargo-audit).
python3 scripts/verify-packages.py --audit

# Validate README links and the SVG diagram sources.
python3 scripts/verify-packages.py --docs

The driver uses --workspace --all-targets, enables all features for swarm and forecasting, and selects CUDA's portable serde configuration. It also runs the targeted safety regressions and reports every failed command. GPU/browser execution, npm consumers, and Cargo archive verification have separate gates recorded in the modernization report. An inventory or successful metadata resolution is not a passing test suite.

For work on the core alone:

cargo test --locked --lib
cargo test --locked --doc
cargo check --locked --no-default-features
cargo bench --locked --bench neural_network

To build and test the Rust browser GPU bridge, install wasm-pack, the root npm dependencies, and Playwright's Chromium, then run node scripts/verify-rust-browser-gpu.cjs --build. This checks generated Rust WASM through the public browser API. The bridge accepts Float32Array inputs and implements compute rather than canvas rendering or browser agent orchestration.

For a single family, pass --workspace neuro-divergent to the verification driver or use its manifest directly. The family guide explains optional features and native libraries. Run JavaScript commands from the relevant npm directory; the repository root is an integration harness. See each npm guide for a clean install, genuine artifact build, tests, and packed-consumer validation.

Performance and research

Measure the workload you intend to deploy. Record the commit, compiler, CPU or GPU, target features, model shape, batch size, thread count, warm-up, and numeric tolerance. Compare identical inputs and weights, and include allocation and transfer costs in end-to-end results. Criterion output is written under target/criterion/.

The latest comparison uses actual Float64 WASM in Node and Chromium. A 128-row SIMD batch produced these mean per-row latencies, including JavaScript validation and copies. Speed ratios compare repeated prepared single calls in the same binary; setup and compilation are outside the timings.

These single-host results are workload-specific. One-row batches can be slower; the native f32/f64 comparison also shows small-batch regressions. Release WASM uses optimization level 3 and checked arithmetic: compared with the size profile, the binaries grow by about 65 KB each. All measured inference outputs match, and old/new calibration JSON is byte-identical. The full results include raw samples, confidence intervals, native calibration results, and reproduction commands. See the research review for adoption choices and the earlier modernization report for package verification.

Verify frozen builds with Rune

Rune now checks a runnable product built from this repository's actual core. The integration pins Rune's source revision and lockfile, builds it locally, then freezes a plan, replays it and rebuilds in a fresh target directory. The digest-bound executable exercises f32/f64 batches and historical calibration; separate release tests cover the core library.

python3 scripts/rune.py plan --repo .
python3 scripts/rune.py --help

Setup and dependency fetching are explicit steps. Verification uses Cargo offline, records zero model calls, and rejects stale source, a changed plan or a corrupted stored artifact. It copies source into an isolated directory and leaves project files and existing locks intact. This is build provenance and correctness evidence; it does not measure a performance gain or provide an OS sandbox. The setup guide explains the commands and scope. The Rune workflow runs on relevant pushes/PRs and is also part of the full release acceptance gate.

Tune WASM batching with MetaHarness

The private MetaHarness tool uses the real Darwin numeric optimizer to search batch sizes for the shipped WASM. Every candidate processes the same rows and must reproduce every reference output. A fresh paired measurement checks the candidate after search; a faster search sample alone is not enough for a recommendation.

npm ci --prefix tools/metaharness --ignore-scripts --omit=optional
node tools/metaharness/src/cli.mjs plan --repo .
node tools/metaharness/src/cli.mjs optimize --repo . --variant simd --model medium --baseline-batch-rows 128 --output /tmp/ruv-fann-tuning

Use POSIX (Linux or macOS) and Node 22.13+. Set the baseline to your current batch size (the default is one row). Use a new output directory for each run. The loop bounds evaluations, time and output, reuses identical observations, and records raw timings and confidence intervals. It changes batch configuration inside the experiment, without editing source or applying the result to production. The optional score command is a static metadata assessment, separate from runtime tests.

The detailed workflow explains installation, presets, receipts and limits. The CI gate executes real core/SIMD trials on supported Node versions without requiring a speedup on shared runners. No model service or provider key is needed.

The measured results include the 128-row control: no confirmed gain over that existing setting, which the loop correctly retained.

Contribute

Choose a package, reproduce the issue, and add a regression test for a behavior change. Run that package's checks and the relevant integration checks before opening a pull request. Include the commands and results so another contributor can reproduce them.

Model files, training data, plugins, and network messages cross trust boundaries. Changes to those inputs should validate dimensions and resource use before allocating, return useful errors, and preserve format compatibility or document a migration. See the deserialization decision and migration notes.

Credits and license

Thanks to the contributors listed in CONTRIBUTORS.md, including Ocean (@ohdearquant), Bron (@syndicate604), Jed (@jedarden), and Shep (@elsheppo), and to the FANN, Rust, NeuralForecast, Tokio, Serde, and WebAssembly communities.

See the repository LICENSE and each package's manifest for licensing information.