Dense-Armor¶

Dense-Armor is a library that learns from a robot's numbers (and from images and text) in three ways: one sample at a time, on a whole table at once, and with deep networks. It can spot strange readings, notice slow changes, protect against bad data and keep robot commands safe.

A library for three kinds of learning: online learning on robot, vision, and AI streams; machine learning on a whole dataset; and deep learning.

The three kinds of learning¶

	Online learning	Machine learning	Deep learning
It reads	one sample at a time, at control-loop speed	a whole table, with `fit` and `predict`	batches or a stream, through layers
Module	`dense_armor.utility.online`	`dense_armor.ml`	`dense_armor.utility.deep.neural`
It has	classifiers, regressors, trees, forests, bandits, anomaly and drift detectors, clustering, time series	statistics, preprocessing, linear models, trees, forests, ensembles, anomaly and change detection	layers, attention, convolutional and recurrent blocks, training, continual learning, decoder language models
Start with	Online learning	Machine learning	Deep learning

┌─────────────────────────────────────────────────────────────────────────────┐
│                                 APPLICATIONS                                │
│                                                                             │
│ Robot control, dynamics, URDF    Vision    LLM agents, tools    AI models   │
├─────────────────────────────────────────────────────────────────────────────┤
│                           THREE KINDS OF LEARNING                           │
│                                                                             │
│ ONLINE                   MACHINE LEARNING         DEEP LEARNING             │
│ one sample at a time     fit / predict on a       layers, attention,        │
│ classifiers, regressors  whole table              training, language        │
│ trees, anomaly, drift   statistics, linear,      models, continual         │
│ detectors, clustering    trees, ensembles         learning                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                PROTECTION (optional, around any online model)               │
│                                                                             │
│ Armor (1D series)    Orca (input + output)    Arbiter (per-point routing)   │
├─────────────────────────────────────────────────────────────────────────────┤
│                    SIGNALS & STATISTICS (the layer below)                   │
│                                                                             │
│ Signal   Streams   Datasets   Moments   Quantiles   Sketches   Metrics      │
├─────────────────────────────────────────────────────────────────────────────┤
│                            ROLES (the foundation)                           │
│                                                                             │
│ Root > Estimator > AnomalyDetector, Classifier, Regressor, Transformer,     │
│                    DriftDetector                                            │
└─────────────────────────────────────────────────────────────────────────────┘

The three kinds of learning are the core. The shield (Armor, Orca, Arbiter) is optional protection around an online model. Robot, vision, LLM and the AI models are the applications this core was built for.

Online learning in practice: four ways to use it, and where the shield goes¶

Four ways to use the online part, from the simplest to the most protected.

1 — Learn from a clean stream. You have a model and the data is trustworthy.

  sample ──► ESTIMATOR.learn_one(x, y) ──► updated
  sample ──► ESTIMATOR.predict_one(x)  ──► prediction

2 — Learn from a stream that can be corrupted. Add a shield. Same estimator, one wrapper.

  sample ──► [ SHIELD ] ──► ESTIMATOR.learn_one   (skipped if the sample is flagged)
                  │
                  └──► ESTIMATOR.predict_one     (always runs)

3 — Score each sample without learning. You only need a number: high means the sample does not look like the recent past.

  sample ──► [ DETECTOR.score_one ] ──► score ──► threshold ──► flag

4 — Score the joint vector, not the single channel. When several channels move together and a per-channel detector is blind to the combination.

  residual of every joint ──► [ MULTIVARIATE DETECTOR ] ──► score
                                looks at the joint vector
                                as one point in d dimensions

Recipe 1 is the online core. Recipe 2 adds the shield. Recipes 3 and 4 are the shield used on its own, for when you only need a detector.

Install¶

pip install dense-armor

The first learned model, in five lines¶

from dense_armor.utility.online.learn.online_dynamics import RecursiveLeastSquares

model = RecursiveLeastSquares(lam=1.0, feature_keys=["one", "q", "qd"])
for t, (x, y) in enumerate(stream):
    model.learn_one({"one": 1.0, "q": q[t], "qd": qd[t]}, tau[t])

Each call to learn_one updates the model with the new sample. No epochs, no batches.

The first protected model, in five lines¶

from dense_armor.roles import AnomalyGate, Protected
from dense_armor.utility.online.anomaly.hst import HalfSpaceTrees
from dense_armor.utility.online.learn.online_dynamics import RecursiveLeastSquares

detector = AnomalyGate(HalfSpaceTrees(n_trees=25, depth=8, window=200))
model = Protected(
    model=RecursiveLeastSquares(lam=1.0, feature_keys=["one"]),
    detector=detector,
    fallback=0.0,
)
for t, (x, y) in enumerate(stream):
    model.learn_one({"one": 1.0}, tau[t])

Same call as before, but when the detector flags the sample as anomalous, learn_one on the inner model is skipped and the prediction falls back to the last clean value. A payload fault no longer poisons the model's state.

What is in here¶

Deep learning — networks built from layers, with a gradient that can be checked.

Foundations, layers and chains — the smallest pieces of a network, and how to join them.
Convolution and pooling, recurrent layers and attention — patterns in an image, memory of the past samples, and a step that looks at every other step.
Training — schedules, mini-batches and the trainer with weight decay and early stopping.
Continuous training — online estimators, Hedge Backpropagation, a background learner.
Encoders and decoders — compress a stream into a few numbers or integers and expand it back or into a forecast.
Deep — the pieces a deep network needs beyond the layers.
Composable attention — cross-attention and the fusion of two sensors.
Continual learning — how to keep a network from forgetting the past, and how to measure what it remembers.
Mixture of experts and test-time compute — use only part of the parameters on each sample, spend more compute at inference.
Decoder language models — the decoder block, the next-token loss and generate.
Language-model training — a 14.2-million-parameter decoder trained on a GPU, with its baselines.
Rotary decoder — RMSNorm, rotary attention and SwiGLU, and generation against a static key/value cache.
Stable variance in float32 — a variance that is exactly zero on identical values.

Machine learning — the classes of dense_armor.ml, which read a whole table at once with fit(X, y). The overview has one page per family: anomaly detection, Naive Bayes, change detection, ensembles, forests, linear models, multiclass, multi-output, nearest neighbours, preprocessing, distributions, statistics and sketches, decision trees and vision. The pages in machine learning against online learning compare the two on the same data.

Online learning — the core. Models that learn one sample at a time.

Optimizers — SGD, AdaGrad, Adam, FTRLProximal, OnlineNewtonStep, each in object and pure JAX form.
Linear models — LinearRegression, LogisticRegression, BayesianLinearRegression, PayloadEstimator.
Calibration — online Platt scaling: honest probabilities from any classifier.
Metric learning — OASIS, LEGO, POLA, and a k-NN classifier that learns its distance.
Online classifiers — robot-state classifiers that adapt when the data drifts.
Online dynamics — learns, sample by sample, the torque the URDF model misses.
Clustering — k-means online, DenStream.
Trees — Hoeffding, Hoeffding Anytime, Hoeffding Adaptive with per-node ADWIN, Mondrian forests with uncertainty, stochastic gradient trees.

Shielding — the protection that sits between the data and the learning.

Armor — wearable shield for a single 1D series.
Orca — full input + output shield for an entire model.
Hybrid engine and adaptive engine — the two causal engines the shields sit on.

Detection — one number per sample, high means the sample does not look like the recent past.

Arbiter — classifies each point as clean / spike / regime against a wide causal reference window, then routes it.
Streaming — a per-sample port of Arbiter's causal deviation check, plus native multi-channel wrappers.
Robust filters — Chauvenet, Tukey, Hampel, sigma clipping on whole series, plus pressure_valve.
Curvature — a bounded proximity-to-reference score in [0, 1).
CUSUM and ARL theory — accumulates small, sustained deviations, plus a closed-form pre-flight estimate of detection and false-alarm latency.
Drift detectors — ADWIN, KSWIN, Page–Hinkley, and the CUSUM family.

Multivariate anomaly detectors — when several channels move together.

Online Robust Mahalanobis — distance from a robust median under the median covariation matrix.
LODA — rare bins in many random 1D projections.
Half-Space Trees — sparse regions of the joint space.
Online Isolation Forest — depth needed to isolate a point.
One-Class SGD (SONAR) — signed distance from a learned kernel boundary with a formal error bound.

Signals and statistics — the layer the estimators live on.

Streams and datasets — CSV, ROS bag, array, merge by time, shuffle; the Casper, DriftStream and SyntheticArm datasets.
Shared-memory containers — let worker processes read a very large list without every worker copying it.
Statistics — moments, robust statistics, streaming quantiles (t-digest, DDSketch), dependence, sketches.
Preprocessing — scalers per feature and per joint, text tokenisation, selection, resampling.
Metrics and evaluation — classification, regression, intervals, rolling, ROC-AUC, prequential, event-based (Tatbul PRF, NAB, detection delay).

Robot — the physical side of the library.

Control — rate limiter, CBF filter, trajectory generation, kinematic controller.
Dynamics — rigid-body dynamics from a URDF, passivity-CBF controller, full 6-DoF controller, xacro and mimic joints.
Benchmark — CASPER on the UR3e.

Vision, video and tracking — from a frame with a timestamp to objects, joints and events.

Vision — HOG, moments, Lucas–Kanade optical flow, colour features, patch descriptors, visual vocabulary.
Frames — the frame with a timestamp, the currency of every video.
Features — what a frame carries: edges and their direction.
Optical flow — how far things moved between two frames.
Reduce — fewer numbers, same meaning: random projection, PCA, the whole chain.
Motion in time — energy, global shift, scene changes.
Tracking — objects without a detector, signals, joints.
Kinematics — landmarks, kinematics, registration.
Quality — frame quality, sync, event cameras, visualisation, benchmark.
Patches — PatchFeatures and PatchMemory (native PatchCore), reservoir and coreset.

Applications — pipelines that chain the blocks above on a synthetic stream.

Finance — streaming pipelines for risk, execution and fraud detection.
Drones — one page per question about a flying robot: actuator fault, sensor consistency, battery endurance, link health, visual landing and others.

Tools — the parts that do not participate in the anomaly shield.

Toolkit — op compiler, memory guard, profiler, logging and provenance export, audio / HDF5 / NetCDF I/O.
MCP server — estimators exposed as LLM tools.
API reference — the base classes every estimator builds on.

Honest results¶

Adversarial robustness (see test/test_boundA-E.py for the actual attack code, not just the reported numbers):

attack	type	defense
PGD / BIM / MI-FGSM	gradient, 1000 steps	mitigated, V_max 0.013–0.078
Affine / elastic	geometric, 50k iter	contained, V_inf 0.05–0.14
Fourier broadband	frequency domain, 50k FFT iter	99.77 %+
Carlini-Wagner (L2)	optimization	78.96 %
Carlini-Wagner (L∞)	optimization	64.39 % — weakest point found so far
DeepFool	optimization	78.79 %

C&W in L∞ norm is the attack that breaks through the most. Root cause understood, not yet fixed: it builds a spatially-smooth perturbation across the whole grid in one shot, and no purely local coherence check (comparing a point to its immediate neighbours) can distinguish genuinely-smooth structure from adversarially-smooth structure without an external reference. See the README for the full "known limits" list.

Citation¶

If you use Dense-Armor in a paper, cite the Zenodo release:

@software{dense_armor,
  author  = {tatopenn-cell},
  title   = {Dense-Armor: Robot-AI Online Learning with Shielding},
  year    = {2026},
  doi     = {10.5281/zenodo.23340608},
  url     = {https://github.com/tatopenn-cell/Dense-Armor}
}