dense-armor 1.1.27

Robot-AI Online Shielding & Learning

A library for online learning on robot, vision, and AI streams, one sample at a time, with streaming statistics and protection, drift and anomaly detection, and safe robot commands.

📖 Full documentation, API reference, quick guide →

Who is this for

Python developers working on systems where data arrives one sample at a time and the model has to learn or stay stable while it runs: robot control loops, sensor pipelines, agent runtimes, any streaming workload. If you train on a fixed dataset and then deploy, this library is probably not what you need.

Use cases

The primitives are domain-agnostic: anything that ingests data one sample at a time and has to react when the stream changes. Robotics is where the library has been tested most, but the layers above and below the model are the same shape everywhere.

What it expects from you

No specific model. Any estimator that follows the same contract: learn_one(x, y) updates the model from one sample, predict_one(x) returns a prediction, transform_one(x) returns a transform or a residual, score_one(x) returns an anomaly score (high = anomalous), update(x) advances a drift detector. Inputs and outputs are dicts of numpy-compatible scalars or arrays. Runs on CPU or GPU through JAX. A shield can wrap any callable from tensor to tensor.

What changes when you use it

• The model keeps learning even when the stream has NaN, spikes, or missing samples — they are cleaned before the model sees them, and every correction reports how far it moved.
• Concept drift is caught by an explicit detector instead of silently degrading accuracy.
• Anomalies come back as a score, one sample at a time.
• Robot commands are bounded (rate limits, control barrier functions) before they reach the actuator.
• Predictions can carry a calibrated uncertainty interval.

What it does

Dense-Armor is a Python library for online learning. Every estimator learns one sample at a time, at control-loop speed, on JAX: nothing is retrained in batch, nothing revisits the past. The same learn_one / predict_one / transform_one contract runs on a table, a time series, a robot joint stream, a video frame, a token stream, and a shield can sit in front of any of them.

Quickstart

As a quick example, we'll train an online Gaussian naive Bayes classifier to classify a drift stream with 5 features and one sudden concept change. Here's a look at the first observation in the dataset.

>>> from dense_armor.utility.datasets import DriftStream

>>> dataset = DriftStream(n_samples=2000, n_features=5, n_drifts=1, kind="sudden", seed=0)

>>> for x, y in dataset.stream():
...     print(x.to_dict())
...     print(y)
...     break
{'x0': 0.00889176732883129, 'x1': 0.7559062648510446, 'x2': -2.788269695138754, 'x3': 0.0168051027297742, 'x4': 1.9630566360240487}
0

Now let's run the model on the dataset in a streaming fashion. We sequentially interleave predictions and model updates. Meanwhile, we update a performance metric to see how well the model is doing.

>>> from dense_armor.utility.learn.online_classifiers import OnlineGaussianNB
>>> from dense_armor.utility.metrics import Accuracy

>>> model = OnlineGaussianNB()

>>> metric = Accuracy()

>>> for x, y in dataset.stream():
...     y_pred = model.predict_one(x)
...     if y_pred is not None:
...         metric.update(y, y_pred)
...     model.learn_one(x, y)

>>> metric
Accuracy(n=1999, value=0.9989994997498749)

Of course, this is just a contrived example. Check the getting started section of the documentation for a more thorough tutorial.

On a robot

A joint torque stream from SyntheticArm (real Panda URDF, real rigid-body dynamics) carries a 1e6 spike at sample 50. A rate-limited follower caps the applied jump at max_vel per step, so a downstream controller never sees the spike:

from pathlib import Path
import numpy as np
from dense_armor.utility.datasets import SyntheticArm
from dense_armor.utility.control.rate_limiter import rate_limited_follower

ds = SyntheticArm(
    Path("test/fixtures/urdf/panda.urdf"),
    period_s=1.0, rate_hz=50.0, n_cycles=2,
    fault_at_s=None, fault=None, seed=0,
)
tau = np.array([float(sig["tau_1"]) for sig, _ in ds.stream()])
tau[50] = 1e6

safe = rate_limited_follower(tau, max_vel=2.0, max_accel=1.0)
print(round(float(np.max(np.abs(tau))), 1), round(float(np.max(np.abs(safe))), 1))

1000000.0 272.2

RigidBodyModel loads dynamics from the same URDF (.xacro and <mimic> joints included), quintic_trajectory generates a minimum-jerk path, and cbf_safety_filter enforces a spatial barrier around an obstacle.

Install

pip install dense-armor                 # core: numpy + jax
pip install "dense-armor[vision]"       # + OpenCV frame readers
pip install "dense-armor[ros]"          # + rosbag readers
pip install "dense-armor[audio,data]"   # + WAV, HDF5, NetCDF
pip install "dense-armor[mcp]"          # + MCP server for LLM agents
pip install "dense-armor[quantum]"      # + Dense-Evolution (NISQ simulator)

Works on Python 3.10+. JAX is the backend for every estimator.

Features

Dense-Armor provides online implementations of the following families of algorithms:

• Linear models, with a wide array of optimizers
• Decision trees and online forests
• Clustering
• Anomaly detection
• Drift detection
• Time series (AR, VAR, Kalman, adaptive Kalman, cycle residual)
• Online classifiers
• Online dynamics
• Calibration and metric learning
• Imbalanced learning
• Vision (frame features, patches, vocabulary, online reduction)
• Robot control (rate limits, control barrier functions, trajectories, kinematic tracking)
• Robot dynamics (URDF, passivity + CBF controllers)
• Shielding (1D series cleanup, input/output shield, per-point routing)

Dense-Armor also provides other online utilities:

• Feature extraction and selection
• Online statistics and sketches
• Metrics for streams and robots
• Preprocessing
• Streams (CSV, arrays, rosbag, frame folders, merge by time, shuffle)
• Built-in datasets
• Progressive model validation
• Model pipelines
• LLM bridge (embeddings as features, estimators as JSON tools)
• Checks (check_estimator, p99 budget, memory growth, clone, pickle, state dict, roc_auc)
• Core engine (DynamicAICodegen JIT compiler, ImageChunker, UniversalMemoryGuard, AdaptiveSignalStabilizer, AIHardwareProfiler, StochasticAdversarialNoise)

Check out the API for a comprehensive overview.

Should I be using Dense-Armor?

The answer is probably no. Most of the time, batch learning does the job just fine. An online approach fits when:

• you want a model that learns from new data without revisiting past data
• you want a model that is robust to concept drift
• the production context is event-based, not batch-based, and you want the code to look like it
• you want the model to be protected from corrupted input, NaN, spikes, or slow drift without retraining it
• you work with a real robot and need command-side safety in the same library that learns the model

Some specifics:

• It focuses on clarity and user experience, more than on raw speed.
• It runs on JAX, so the same code runs on CPU, GPU or TPU.
• It plays nicely with the rest of Python's ecosystem: numpy in, numpy out.

Useful links

• Documentation
• Getting started
• API reference
• Changelog
• Package releases
• Sister project (Dense-Evolution)
• DOI

Contributing

Contributions are welcome. The library is built to be extended one estimator at a time, following the same interface (learn_one / predict_one / transform_one) and the same checks (dense_armor.checks).

Citation

@software{pennacchio_dense_armor,
  author    = {Pennacchio, Salvatore},
  title     = {Dense-Armor: Robot-AI Online Shielding \\& Learning},
  year      = 2026,
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.23265098}
}

License

Business Source License 1.1 — free non-commercial use, converts to Apache 2.0 on 2029-06-01. See LICENSE.md.

© 2026 Salvatore Pennacchio <jtatopenn@libero.it>

Twin project of Dense-Evolution (NISQ quantum circuit simulator).