Skip to content

About

Mercury Agent ♱ is a civilization-first neuro-symbolic AI for multi-domain anomaly & hazard detection and early warning — a trained detector-fusion core, real-data hazard models, fail-closed ethical gates, post-quantum crypto, and a self-hostable detection-as-a-service platform. Built for STEAM research and humanitarian crisis response.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

6 stars

Watchers

0 watching

Forks

Latest commit

 

History

560 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
image

AGPL v3 Logo Python 3.11+ Anomaly Detection Fairlearn Security Scan Counter-AI Stand-Down STEAM Exploration Coverage 3R|Mechanism AMA-Cryptography

              +===============================================================================+
              |                            Mercury Agent ♱ v3.0.0                             |
              | Computational Systems Intelligence - Multi-Domain Anomaly & Hazard Detection  |
              |                                                                               |
              |   Cognitive Orchestrator |   Hybrid Fusion ML      |   Production Security    |
              |   Neural + Symbolic      |  170 Detector Classes   |   Post-Quantum Crypto    |
              |   Ethical Governance     |   Multi-Head Attention  |   OWASP Validation       |
              |                                                                               |
              |   LAYER 3: Ethics        |   LAYER 2: ML/AI        |   LAYER 1: Security      |
              |   -------------------    |   -------------------   |   -------------------    |
              |   Harm-Uplift Gate       |   Fusion Network        |   Kyber-1024/ML-DSA-65   |
              |   Lyapunov Stability     |   Ensemble Averaging    |   JWT Authentication     |
              |   Civilization-First     |   Property Testing      |   Rate Limiting          |
              |                                                                               |
              |                      Archetype for a civilized evolution.                     |
              +===============================================================================+

Copyright 2025 Steel Security Advisors LLC
Author/Inventor: Andrew E. A.
Contact: steel.sa.llc@mercuryagent.global (operations & security) · contact@mercuryagent.global (general inquiries & support)
License: GNU Affero General Public License v3.0 or later (SPDX: AGPL-3.0-or-later)
AI Co-Architects: Eris ✠ | Eden ♱ | Devin ⚛︎ | Claude ⊛
Version: v3.0.0
Date: 2026-10-21


Executive Summary

Mercury Agent is a civilization-first Computational Systems Intelligence (CSI): a comprehensive neuro-symbolic AI for multi-domain anomaly and hazard detection, built at the meeting point of systems intelligence, computational science, resilience engineering, complex adaptive systems engineering, and humanitarian technology — with STEAM research as its application domain, not its identity. Its cognitive layer is wired at runtime by the CognitiveOrchestrator over ten components — a knowledge graph, multi-hop reasoner and uncertainty quantifier (always on) plus plasticity, causal discovery, IPB, case-based reasoning, indicator development, curiosity and enhanced anomaly detection (optional). The "7-phase evolution" described below is the historical build spine, not a runtime pipeline. The system combines neural pattern recognition with symbolic reasoning to produce explainable, ethically-bounded decisions across security, medical, environmental, humanitarian, and infrastructure domains.

The framework embodies a Civilization-First mission: serving the broad range of scientific, clinical, engineering, humanitarian and public-safety work that hazard detection touches. FINDΩYOU™ — locating the lost, missing and abducted — is one deployment of that mission, not its ceiling. Every public decision surface clears one mandatory, fail-closed harm-uplift gate (cognitive/decision_gate.py, docs/HARM_POLICY.md), which refuses operational uplift toward a weapon or mass-casualty outcome and permits the diagnostic, defensive, clinical and responsive half of every hazard domain. Benevolence is scored and logged as an advisory signal; it is not a pass-bar.

Beyond the library and CLI, the repository ships an opt-in self-service platform for operating the detection API as a hosted service — account registration with email verification, TOTP two-factor, API keys with per-account quotas, a dependency-free browser dashboard, an operator CLI, and a TLS compose overlay — all off by default and documented under Self-Service Account Platform and docs/PLATFORM_HARDENING.md.

Project Philosophy: Mercury Agent represents the next evolution in AI systems - one that combines the pattern recognition power of neural networks with the interpretability and reasoning capabilities of symbolic AI. This neuro-symbolic fusion enables the system to not only detect anomalies but explain why they matter and what actions should be taken.

Security Disclosure: This is a research-grade implementation. Production use REQUIRES:

  • Independent security review by qualified professionals
  • Validation on domain-specific real-world datasets (MIMIC-III, NSL-KDD)
  • Clinical validation for any medical applications
  • Post-quantum cryptography for Mercury Agent and FINDΩYOU™ is derived from AMA Cryptography
  • FINDΩYOU™ is a separate, near-future sibling platform whose humanitarian scope — locating the lost, missing, and abducted to reunite families and help bring perpetrators to justice — is served by Mercury under its Civilization-First mission.

This project is licensed under the GNU Affero General Public License v3.0 or later (SPDX: AGPL-3.0-or-later). Versions before 3.0.0 were released under GPL-3.0-or-later and remain so.

Anyone may use, study, modify and share Mercury. Whoever distributes Mercury, or a work based on it — and whoever offers a modified Mercury to users over a network (AGPL section 13) — must make the complete corresponding source available under this same license, so no proprietary version can exist, distributed or hosted. Private modifications that are neither distributed nor served to others carry no obligation, and unmodified hosting carries no new one. Every deployment serves its source offer at /source — the upstream repository by default; an operator running a modified version points it at their published fork with MERCURY_SOURCE_URL.

One additional permission is granted under AGPL section 7: Mercury may be combined with NVIDIA's CUDA libraries (needed for GPU acceleration) and the result conveyed. It covers those libraries only and leaves every other term, section 13 included, intact — see LICENSE-EXCEPTION.

Status: Research-grade | Community-tested | Not externally audited Last Updated: 2026-10-21


Table of Contents

Click to expand navigation

Latest Benchmark Results

This block is regenerated by .github/workflows/benchmark.yml on every push to main and committed back to the repo, so the most recent live-data run is always front-and-center — never lost to expiring CI artifacts.

The full result file lives at benchmarks/mercury_benchmark_results.json. Methodology is documented in docs/BENCHMARKS.md. A multi-panel visual summary appears in the Current Benchmarks and Visual Proof section below.

Metric Current Previous Δ
Mean ROC-AUC 0.8610 0.8548 +0.0062
Median ROC-AUC 0.9077 0.9052 +0.0025
Mean Oracle F1 0.6476 0.6430 +0.0046
Datasets (successful / total) 67 / 76 67 / 76 +0.0000
Run timestamp (UTC) 2026-10-26T23:01:08.701481+00:00 2026-10-14T20:27:14.966442+00:00 —
Commit a2d7f99 27d2293 —

Regression gates: ROC-AUC must stay ≥ 0.75 and Mean Oracle F1 ≥ 0.55 (the coarse floors set in .github/workflows/benchmark.yml, held a deliberate margin below the current headline AUC/F1 so they do not flap on normal load-availability variance). Fine-grained, tight regression protection is the deterministic per-dataset guard (anomaly_regression_guard.py), not these coarse floors. CI fails the workflow if either drops below threshold.

Comparability note. The aggregate ROC-AUC above blends two evaluation regimes. Only externally-labeled datasets — ADBench and the standard labeled sets, where labels come from a source independent of the scored signal — are comparable to published baselines; the comparable headline is ADBench Mean AUC 0.8571. Several environmental loaders are self-labeled by thresholding the signal they score, which inflates their AUC toward 1.0 (label leakage) and is reported for pipeline transparency only. See Label provenance and comparability in the benchmarks below for the full split.

Fusion-hardening (transductive). The unsupervised fusion changes in detectors/statistical.py are measured independently of the headline run by a committed, re-runnable 18-set real-ADBench transductive harness (research/omni_equation/harness_adbench.py): Mean AUROC 0.7397 → 0.7745 (+3.48 pts, 13 W / 1 tie / 4 L) from base e118e1f to the detector at e7341ce (full per-set results in research/omni_equation/adbench_results.json). Real data only — the harness fails loudly rather than substituting synthetic. Re-run: python research/omni_equation/harness_adbench.py. The re-measurement at e7341ce (fit-time conformal operating point, conformal p-values) reproduced 0.7745 on all 18 sets: those changes move the cut, not the ranking.

Both sides were measured on one tree, in one environment. The earlier ledger (0.7634, 14 W / 2 tie / 2 L) was recorded at bdcdf6a and left behind by seven commits of detectors/statistical.py (+1,199 / −105 lines), with no provenance in the file to date it. The refresh re-measured the base at e118e1f in a matched environment (numpy 2.5.3, scipy 1.18.1, AMA 3.2.0 — the release that tree pins) and it reproduced the committed 0.7397 on all 18 sets byte-for-byte, which rules the environment out as a confound and attributes the whole current-side movement to the detector revisions. The harness is deterministic: two runs on one tree are identical. The refreshed ledger is a larger mean gain and a worse win rate — cardio −0.0855 and optdigits −0.0624 are the two real regressions, enumerated in adbench_base_vs_current.json.

Adversarial shapes on the served routes (measured). The detection routes mercury-agent serve exposes are driven through seeded scenarios built to defeat a naive detector (a spike spread over its neighbours by an attacker, a slow ramp, a level shift, a spike riding a strong season, a point anomaly inside a variance burst, a distribution shift to heavy tails) and through pure noise at widths 1 to 64; the numbers live in docs/DETECTION_QUALITY.md, regenerated by python research/adversarial/served_routes.py and gated by tests/research/test_served_routes_ledger.py, which recomputes the hash of every file that decides them. Every component the routes fuse is the z-equivalent of its maximum under the null given the values it ranged over, so the false-positive rate on noise is nominal at every width (it was 100% from width 32 up), and a collective component scores a stretch of rows departing together, so the shift, the ramp and the spread spike are found (recall 1.00 on the row fusion) where no single row stands out.

Every run now stamps its commit, detector commit, timestamp and library versions, and tests/docs/test_readme_claims_match_artifacts.py fails if the committed run ever falls behind the detector again.


Codebase Scale (measured, not estimated)

These numbers are produced by scripts/measure_codebase_scale.py and gated in CI: --check README.md fails the build if the block below drifts from what is on disk, and --update README.md regenerates it. They reflect what is actually on disk, not what marketing copy assumes.

Measurement Value
Python source files in src/omni_mercury_engine/ 884
Source lines of code (LOC) ~493,000
Top-level subpackages (true Python packages with __init__.py) 52
Files importing PyTorch (optional [ml] extra) 176
Distinct torch.nn.Module subclasses 174
Detector classes (class *Detector) in detectors/ 110
Public detector classes package-wide (class *Detector, not Base* or _private) 170 in 17 subpackages
Data-loader classes (class *Loader) in loaders/ 22
Test modules (test_*.py) / total test LOC 965 modules / ~271,000 LOC
GitHub Actions workflows 26

Generated by python scripts/measure_codebase_scale.py --update README.md and gated in CI (scripts/measure_codebase_scale.py --check README.md); do not hand-edit between the markers.

The neuro-symbolic claim is real, not naming theatre. Concrete evidence in-repo:

  • src/omni_mercury_engine/cognitive/ — ~32,000 LOC, 30 modules (excluding __init__.py; measured at v2.1.x), including neural_memory_layer.py, symbolic_logic_layer.py, neurosymbolic_fusion.py, differentiable_logic.py (with NeuralPredicateEncoder, DifferentiableRuleModule, NeuralTheoremProver, CounterfactualReasoner — all real nn.Module subclasses), cognitive_evolution_engine.py, chain_of_thought.py, multi_hop_reasoner.py, causal_discovery.py, case_based_reasoning.py, predictive_coding.py, formal_verification.py, knowledge_graph.py, multi_agent_coordination.py, reflexion.py, plasticity_engine.py, hierarchical_planning.py, ipb_engine.py.
  • src/omni_mercury_engine/core/neurosymbolic_hub.py — 1,446 LOC; defines KnowledgeGraph, NeuralEncoder, SymbolicRule, NeuroSymbolicHub, ExplainableOutput, FusionMode.
  • PyTorch is the engine of the ML / neuro-symbolic stack, shipped as the optional [ml] extra (torch>=2.2.0, torchvision>=0.17.0, pytorch-lightning>=2.0.0) — it is not a core install dependency: the top-level import omni_mercury_engine and the default (non-ML) detection path import without torch, while the ML / neuro-symbolic submodules import torch at module scope and require the [ml] extra. The measured count of torch-importing files and nn.Module subclasses is in the table above. Install the full neuro-symbolic path from a clone with pip install -e ".[ml]". The [api] extra also pins torch>=2.2.0, so a served deployment installed with pip install "mercury-agent-global[api]" can run every detector the API exposes without a second install step.

Mercury Agent is a neuro-symbolic AI that exposes anomaly detection as one of its capabilities — it is not "an anomaly detection library that happens to use neural networks."

The claim is operational, not just architectural: the production fusion trainer (OmniMercuryEngine.fit_fusion) co-trains a differentiable Logic Tensor Network with the neural network by default (symbolic_weight="adaptive") — a symbolic satisfaction term enters the loss and its gradient flows into the network's anomaly head. The weight follows a label-scarcity schedule that cleared a pre-registered dominance bar on real ADBench labels (no full-data AUC regression beyond noise; a seed-agreed low-data lift) and decays to the purely-neural path when labels are abundant. This is co-training in the loss, not a post-hoc score blend. Full accounting, ablation, and the evidence-based keep/quarantine verdicts: docs/NEUROSYMBOLIC.md.


7-Phase Neuro-Symbolic Evolution

Mercury Agent implements a 7-phase cognitive architecture that progressively builds from basic neural memory to curiosity-driven exploration. Each phase names a real, CI-gated module in src/omni_mercury_engine/cognitive/ (the "Neuro-Symbolic Tests" required check enforces them):

Phase Component Description Key Features
Phase 1 Neural Memory Layer Memory embeddings and pattern detection K-means clustering, episodic/semantic memory, pattern recognition
Phase 2 Symbolic Logic Layer NetworkX-based logic graphs Explainable decisions, threshold rules, inference chains
Phase 3 Neuro-Symbolic Fusion Hybrid anomaly scoring Attention-based fusion, confidence weighting, neural-symbolic integration
Phase 4 Enhanced Anomaly Detection Memory knowledge graph Bayesian predictor, HMM predictor, external data integration
Phase 5 Autonomous Agent OODA loop implementation Observe-Orient-Decide-Act-Reflect, user synchronization, Mercury/AMA Disconnect
Phase 6 Ethical Bounding Harm-uplift gate (enforced); benevolence scoring (advisory) Harm reduction, equity calculation (Gini), empathy module
Phase 7 Cognitive Evolution Engine Curiosity-driven exploration CuriosityEngine: measured novelty scoring (online diagonal-Mahalanobis distance) of detected anomalies, wired into the CognitiveOrchestrator. The earlier self-play / genetic-mutation / theory-of-mind internals were measured decorative and removed.

The seven phases are the historical evolution spine, not the whole cognitive layer: cognitive/ has since grown to 30 modules, integrated at runtime by the CognitiveOrchestrator (knowledge graph, multi-hop reasoner, and uncertainty quantifier always on; plasticity, causal discovery, IPB, case-based reasoning, and indicator development on by default; curiosity and enhanced detection opt-in — see cognitive/__init__.py).


Current Benchmarks and Visual Proof

Detailed benchmarks and methodology

Snapshot of the committed mercury_benchmark_results.json run (2026-10-26). The Latest Benchmark Results block at the top of this README is the CI-refreshed current headline; the tables here are the detailed breakdown. All numbers are measured on real data — no synthetic substitution, no hyperparameter tuning.

Methodology and comparability

MercuryAnomalyDetector was run untuned over 67 of 76 attempted real-world datasets across 13 domains. Of the 9 failures, 7 were unreachable external sources (tracked by a two-lane reachability harness, .github/workflows/dataset-reachability.yml) and 2 — UCR and USGS_Geochemistry — reached their source but resolved to a single label value, so no AUC is computable and the run reports them as errors rather than scoring a meaningless number. Every failure, with its own message, is in per_dataset of the committed result file. Results fall into two regimes, and only the first is comparable to published detectors:

  • Externally-labeled (comparable). Labels come from a source independent of the scored features (ADBench, NSL-KDD, BATADAL, SMD/NAB, CWRU, ADRepository, DTU AIS). The headline is the 47-dataset ADBench result: Mean AUC 0.8571 / Mean F1 0.6443.
  • Self-labeled / threshold-derived (not comparable). Some environmental loaders manufacture labels by thresholding a feature they also score, so the detector recovers them almost trivially (0.97–1.00 AUC). That is label leakage, not accuracy — reported below for pipeline transparency only.

The same provenance discipline extends to the live-API loaders: of 21 concrete loaders, only 2 (network_security, sepsis) produce labels independent of any scored feature, and the governed-fusion suite gates self-improvement on those 2 alone. CI enforces the split (python -m omni_mercury_engine.loaders.label_provenance --check); see docs/SELF_IMPROVEMENT_LOOP.md for the governed self-improvement rollout.

Headline results

Ensemble — unsupervised, three-component weighted fusion:

Component Weight Method Mean AUC Median AUC
ResonanceScore 40% FFT harmonic spectral profiles 0.7665 0.8008
KinematicScore 30% Physics jerk/curvature via np.diff 0.6013 0.5719
InfoGeometryScore 30% Fisher-information Mahalanobis OOD 0.8265 0.8671
Ensemble 100% Weighted combination + kNN density stream 0.8610 0.9077
Aggregate (54 genuine-label datasets of 67 successful) Value
Mean AUC / Median AUC 0.8610 / 0.9077
Std AUC 0.1438
Mean / Median Oracle F1 0.6476 / 0.7005

Oracle F1 is an upper bound (best of a multi-strategy threshold sweep), not operational performance.

Comparable domain results (externally-labeled)

These rows use labels independent of the scored features — the numbers to line up against other detectors.

Domain Datasets Mean AUC Mean oracle F1
ADBench 47 0.8571 0.6443
Time series (SMD, NAB) 2 0.7738 0.4690
Academic (CWRU_Bearing) 1 1.0000 1.0000
General (ADRepository) 1 0.9116 0.6162
Industrial (BATADAL) 1 0.8976 0.5548
Maritime (DTU_AIS_Abnormal) 1 0.8750 0.6250
Security (NSL-KDD) 1 0.9741 0.9544

Generated from benchmarks/mercury_benchmark_results.json by scripts/update_readme_benchmarks.py: the 54 successful datasets whose labels are ground_truth or expert_annotated. Threshold-derived (statistical) labels are excluded as circular. Domains of one to three datasets are easy to separate at that size; the comparable figure is the 47-dataset ADBench row.

Robotics / UAV (ALFA, event ground truth, per-flight protocol). The CMU AIR Lab ALFA corpus — 46 real fixed-wing flights, 36 with a mid-flight injected actuator fault whose injection instant the onboard failure_status topics record — is measured by its own streaming protocol (benchmarks/alfa_uav_benchmark.py) rather than this table's pooled split, which crosses flights and collapses the signal. Fitting each flight's first 30 s and OR-fusing the per-flight ensemble with the stuck-actuator statistic (detectors/drone/actuator_health.py) detects 35/36 fault flights at 0.68% per-tick false-alarm rate with 8.0 s median delay across engine, aileron, rudder and elevator faults (recorded in artifacts/alfa_uav.eval.json).

Robotics / manipulator (UCI Robot Execution Failures, event ground truth). 463 real manipulator executions with observed task outcomes (UCI 138, CC BY 4.0) — force/torque sensing, the contact modality of robot arms and humanoid limbs. Fitting only on nominal runs (20 seeded splits per problem, nothing tuned on failures): AUROC 1.000 / 0.984 / 1.000 / 0.922 across the four distinct problems, pooled 0.968 (benchmarks/robot_failures_benchmark.py, recorded in artifacts/robot_failures.eval.json).

Competitive positioning (ADBench, one identical unsupervised protocol)

Against PyOD baselines on the full 57-dataset ADBench suite, Mercury's tier detector places 2nd of 8 by mean rank (2.72) — behind knn (2.52) and ahead of local_outlier_factor (3.61), isolation_forest (4.55), hbos (5.55), copod (5.60), and ecod (6.06) — with the highest mean ROC-AUC of all eight methods (0.8341 vs knn's 0.8316). The LOF head-to-head reads 34W/23L and the 34 losses to knn carry a median margin of 0.008 AUC; knn still leads on low-dimensional local-density sets, its native turf. Full method-by-method tables and every loss enumerated: benchmarks/COMPETITIVE_BENCHMARK.md.

Untuned 5-fold-CV spot check versus standard baselines (regenerated from license-clean scikit-learn datasets, deterministic at --seed 42, via python -m benchmarks.empirical_benchmark --readme-subset; run of 2026-10-28, committed at results/empirical_benchmark_results.json):

Detector breast_cancer covtype digits_8 kddcup99
Mercury-Agent 0.790 0.899 0.551 0.706
Isolation Forest 0.780 0.936 0.653 0.947
One-Class SVM 0.662 0.901 0.767 0.966
LOF 0.544 0.667 0.571 0.571
Elliptic Envelope 0.888 0.899 0.503 0.851

AUC; bold = best per column. Mercury is unsupervised and untuned, and on this small sklearn spot check it ranks mid-pack (#4 of 5 by mean AUC, 0.736 vs the 0.829 best baseline) — its measured strength is the 76-dataset harness above, not this subset. A previous version of this table also carried "published reference" rows for TranAD/MAAT on these datasets; no such published numbers exist (those papers evaluate time-series corpora), so the rows are removed.

Calibration and conformal validation

All figures from the committed benchmarks/calibration_validation_results.json (2026-10-26, 55 datasets):

Validation Result
Threshold calibration (MD-011) 50/55 datasets improved (92.7% improved-or-same), mean ΔF1 +0.220
Fusion-weight adaptation (MD-003) adaptive weights measured on all 55 datasets; mean weights R 0.47 / K 0.21 / IG 0.32 (see the MD-003 panel below for the CV validation)
Conformal coverage (MD-005) per-dataset results in the committed JSON; no aggregate summary is committed, so none is quoted here

Domain-specific hazard benchmarks

Per-domain AUROC from the committed research/engine_calibration/results.json (a previous version of this table cited run_all_benchmarks.py, whose output is not committed, and carried several values — including a Flood row — that matched no committed artifact):

Eight of these nine rows are self-labelled, and the table never said so. Only Network Security has labels independent of the scored features (ground_truth: NSL-KDD label, BATADAL ATT_FLAG); the other eight are statistical — the label is a threshold on a column the detector was also handed. Overall pools both regimes over all 30 events, which is exactly what the leakage-flagged section below says is never done. The loaders declared this at source the whole time; this table did not carry it. Measured impact and the limits of that measurement: deleak_impact.json.

Domain AUROC Labels Label rule
Network Security 0.7925 independent per-row attack flags (NSL-KDD label, BATADAL ATT_FLAG)
Earthquake 0.9367 self-labelled magnitude >= mainshock_mag - 1.0, and magnitude is feature[0]
Pandemic 0.9256 self-labelled 7d rolling cases > 2x 30d baseline, on the same smoothed series
Energy 0.9237 self-labelled kp >= 7 on feature[0]; series also reconstructed — "doubly circular" in the loader
Tsunami 0.8905 external labels, reconstructed series arrival-time windows; BPR series reconstructed
Tornado 0.8803 self-labelled mag >= 3 (EF3+) on the raw magnitude behind ef_scale
Hurricane 0.7792 self-labelled 24h wind delta >= 30 kt, which is also scored
FEMA 0.7598 self-labelled the DR/IA/PA declaration flags themselves
Marine 0.5412 self-labelled richness-decline threshold on scored richness_loss
Overall 0.8501 mixed pools all nine; not a comparable figure

What the leak was worth, measured. Every loader now declares its label-derived columns and the scored matrix excludes them (BaseDomainLoader.engineer_scored_features), so this is re-measurable rather than argued. Re-measured with the current detector on the five earthquake events re-fetched from USGS (research/engine_calibration/deleak_impact.py), Earthquake falls 0.8995 → 0.3276 (−0.5718) — below chance on four of its five events once magnitude, mag_deviation and the magnitude-derived b_value are excluded, so that figure was almost entirely the leak. Read the rest with the control in mind: domains with no exclusions moved by up to 0.119 on the same events between two runs, so only a delta well outside that band is attributable to de-leaking. FEMA (−0.055), Pandemic (−0.033) and Hurricane (+0.004) sit inside it. Exclusion also removes identity, not correlation: Tornado rose with ef_scale dropped, because path length, injuries and fatalities covary with EF scale — distinct measurements, still physically downstream of the labelled quantity.

Energy cannot currently be reproduced at all. All four of its events predate the live SWPC window, so the loader refuses rather than reconstructing; the committed 0.9237 was measured on a reconstructed series with circular labels. The table above is retained as the record of what was published, not as a performance claim, and the numbers are not restated anywhere as domain accuracy.

Transparency: self-labeled loaders (leakage-flagged, not comparable)

Labels here are a deterministic threshold on a scored feature, so high AUC is leakage, not accuracy. Listed for pipeline transparency only — never averaged into a headline.

Domain Datasets Mean AUC Label rule (leaky)
Air Quality (EPA) 1 0.9975 PM2.5 > 35.4 µg/m³
Climate (NOAA GSOD/StormEvents/ERDDAP) 3 0.9939 ±3σ threshold
Environmental (USGS/NOAA/EPA) 3 0.8856 ±3σ threshold
Ocean (NOAA Buoy) 1 0.8510 ±3σ threshold
Disaster (FEMA) 1 0.9993 threshold/polarity-derived

When to use Mercury

Use Mercury when anomaly decisions must be interpretable, data types are diverse and need adaptive profiling, or no labeled anomaly data is available. Prefer alternatives when labeled data exists (use a supervised classifier) or memory is tightly constrained. Caveats, stated plainly: KinematicScore is near-random on shuffled tabular data (mean AUC 0.60); 2 datasets fall below 0.50 AUC (ensemble inversion on high-dimensional data); no tuning was performed.

Visual proof

The benchmark panels below are generated from the current committed mercury_benchmark_results.json run (2026-10-26; Mean AUC 0.8610 over the 54 genuinely labelled of 67 successful datasets) by scripts/generate_docs_images.py; the calibration panels come from scripts/generate_calibration_visuals.py over the committed calibration-validation run (2026-10-26, 55 datasets). A single-writer test (tests/test_docs_images_single_writer.py) pins which script owns each committed chart.

Neuro-symbolic cognitive-stack integration demo (authored scenarios, not a performance benchmark) — confidence/benevolence evolution, real per-type memory growth, and neural/symbolic contribution over epochs. For measured neuro-symbolic anomaly performance on real labeled data, see the NAB streaming benchmark below: Neuro-Symbolic Integration Demo

Real-data neuro-symbolic result (NAB, Numenta Anomaly Benchmark — MIT). On four committed, real labeled streaming fixtures with leak-free causal features fitted on a warmup prefix, the MercuryAnomalyDetector scores per-stream AUROC 0.840 / 0.661 / 0.686 / 0.728 (mean 0.729). Re-runnable: python benchmarks/nab_streaming_benchmark.py · results in artifacts/nab_streaming.eval.json.

Anomaly-detection analysis — per-category AUC, oracle-F1 distribution (upper bound, not operational), component correlation, fit/detect timing: Anomaly Detection Panel

Performance dashboard — timing, AUC by category, dataset size, adaptive weights, precision-recall: Mercury Performance Dashboard

Benchmark summary — per-dataset AUC bar chart with the run mean line: Benchmark Summary Live Data

Ensemble report — detection-rate and runtime panels per category with the run's measured summary (every number from benchmarks/mercury_benchmark_results.json): Ensemble Benchmark Report

Calibration and conformal — MD-011 calibration lift and MD-005 coverage: Calibration Improvement

Adaptive weights — unsupervised weight distribution and mean weights by domain: Adaptive Weight Distribution

Full results: benchmarks/mercury_benchmark_results.json · Methodology: docs/BENCHMARKS.md · Competitive detail: benchmarks/COMPETITIVE_BENCHMARK.md.


3R: Recursion-Resonance-Refactoring

Click to expand 3R Mathematical Framework

The 3R mechanism (Recursion-Resonance-Refactoring) is a mathematical method for anomaly detection and optimization that forms the core of Mercury Agent's detection capabilities. This framework combines three complementary engines for pattern recognition and adaptive learning.

Recursion Engine

The Recursion Engine implements hierarchical multi-scale pattern analysis through recursive feature extraction:

Mathematical Foundation:

R(x, d) = f(x) + α · R(g(x), d-1)  for d > 0
R(x, 0) = f(x)

Where f(x) is the feature extraction function, g(x) is the downsampling operator, α is the decay factor, and d is the recursion depth.

Key Capabilities:

  • Multi-scale hierarchical pattern detection across temporal and spatial dimensions
  • Recursive feature extraction that captures both local and global anomaly signatures
  • Self-similar pattern recognition inspired by fractal mathematics
  • Adaptive depth adjustment based on data complexity

Resonance Engine

The Resonance Engine performs FFT-based frequency-domain analysis to detect harmonic anomalies and periodic patterns:

Mathematical Foundation:

H(ω) = |FFT(x)|²
A(x) = Σₙ H(n·ω₀) / Σ H(ω)  (Harmonic Ratio)

Where ω₀ is the fundamental frequency and n represents harmonic indices.

Key Capabilities:

  • Frequency-domain anomaly detection using Fast Fourier Transform
  • Harmonic analysis for periodic pattern recognition (e.g., Schumann resonance at 7.83 Hz)
  • Signal amplification for weak anomaly signatures
  • Cross-domain frequency correlation (seismic, electromagnetic, biological)

Refactoring Engine

The Refactoring Engine provides dynamic optimization and adaptive model refinement:

Mathematical Foundation:

θ_{t+1} = θ_t - η · ∇L(θ_t) + β · (θ_t - θ_{t-1})  (Momentum-based optimization)
L_total = L_detection + λ₁·L_stability + λ₂·L_ethical

Key Capabilities:

  • Dynamic model optimization based on detection performance
  • Code complexity metrics for security review and maintainability
  • Adaptive threshold adjustment using Bayesian calibration
  • Self-healing capabilities inspired by CRISPR mechanisms

3R Synergies

The three engines work together to create emergent detection capabilities:

Synergy Components Capability
Harmonic Analysis Resonance + Recursion Multi-scale frequency decomposition
Quantum-Inspired Paths Recursion + Refactoring Simulated annealing for optimization
Ava Equation All 3R Unified anomaly scoring: A = R·H·O
Asymptotic Horizons Resonance + Refactoring Convergence monitored via a Lyapunov-style decay schedule

The Omni-Ava Equation (OAE)

The unified 3R scoring function with ethical gating:

A = (w_R·R(x) + w_H·H(ω) + w_O·O(θ)) · η_Ethical^Φ

Where:

  • R(x) = Recursion score (multi-scale hierarchical analysis)
  • H(ω) = Harmonic/Resonance score (frequency coherence)
  • O(θ) = Optimization/Refactoring score (adaptive theta)
  • η_Ethical = Ethical compliance threshold (default 0.96, medical fallback 0.93)
  • Φ = Golden ratio constant (1.618033988749895)
  • Golden-ratio fusion weights (canonical Φ:1:1): w_R = φ/(φ+2) ≈ 0.447, w_H = 1/(φ+2) ≈ 0.276, w_O = 1/(φ+2) ≈ 0.276 (sum to 1.0)

Lyapunov Stability (decay-schedule monitor): convergence is monitored against the target condition V̇ ≤ -λV with rate λ = 0.25 (LyapunovConstants.LAMBDA_CONVERGENCE; distinct from the double-helix adaptation rate LAMBDA_DECAY = 0.18 — see Mathematical Foundations) — the empirical trajectory is measured against this schedule, not guaranteed a priori.

3R Anomaly Transformer (PyTorch)

The ThreeRAnomalyTransformer provides a differentiable PyTorch implementation of the 3R mechanism for end-to-end training:

from omni_mercury_engine.ml import LyapunovAnomalyLoss, ThreeRAnomalyTransformer

# Initialize model with domain-specific configuration
model = ThreeRAnomalyTransformer(
    input_dim=25,           # Feature dimension (e.g., NSL-KDD)
    d_model=256,            # Model dimension
    n_heads=8,              # Attention heads
    num_layers=2,           # 3R attention layers
    ethical_threshold=0.96, # Domain-specific (0.93 for medical)
)

# Lyapunov-constrained loss for stable predictions
loss_fn = LyapunovAnomalyLoss(
    mu_stability=0.1,       # Stability constraint weight
    alpha=0.25,             # Convergence rate (matches CONVERGENCE_RATE_PARAMETER)
)

# Training step
output = model(x)  # x: [batch, seq_len, input_dim]
loss = loss_fn(
    x=x,
    x_recon=output["reconstruction"],
    anomaly_scores=output["anomaly_scores"],
    labels=labels,  # Supervised signal for accuracy
)

Key Features:

  • Golden-ratio OAE weights: Mathematically grounded fusion (0.447/0.276/0.276)
  • Bounded outputs: Sigmoid activation ensures anomaly scores in [0, 1]
  • Supervised + unsupervised: BCE loss with labels + reconstruction loss
  • Lyapunov stability: Penalizes divergent predictions for safety-critical applications
  • Domain configs: See configs/ablation_3r_lyapunov.yaml for medical/security/infrastructure presets

Integration with Mercury Agent

The 3R mechanism is integrated throughout Mercury Agent:

  • Detectors: The detector classes leverage 3R for feature extraction
  • Fusion Network: Multi-head attention combines 3R outputs across domains
  • Ethical Governance: Refactoring engine ensures Lyapunov stability constraints
  • Self-Healing: CRISPR-inspired adaptation uses recursive pattern learning
  • PyTorch Training: ThreeRAnomalyTrainer (Lightning) for end-to-end training with stability constraints

Key Capabilities

Problem Statement and Solution

The Problem

Modern anomaly detection faces three critical challenges:

  1. Domain Fragmentation: Security, medical, environmental, and infrastructure domains require specialized expertise with no unified framework
  2. Ethical Blind Spots: Most ML systems lack bias detection, fairness metrics, and ethical governance
  3. Production Gaps: Research models often lack security hardening, input validation, and deployment infrastructure

The Mercury Agent Solution

Mercury Agent addresses all three challenges through:

  • Unified Framework: 170 detector classes in 17 subpackages (the measured, CI-gated count of public class *Detector definitions, base classes and private helpers excluded; see Codebase Scale), 106 of them in detectors/ and the rest in space/, medical/, infrastructure/, security/ and other domain packages; 114 detector-manifest entries, 22 of them adapter classes over the domain detectors, with 5 in the engine's default set; under a single hybrid fusion architecture covering medical, security, space, infrastructure, and environmental domains
  • Ethical Governance: Fairlearn bias detection with demographic parity, equalized odds, and 80% rule enforcement; 180+ ethical scalars with Lyapunov stability
  • Production Security: OWASP-compliant input validation, post-quantum cryptography (Kyber-1024 / ML-KEM-1024, ML-DSA-65, SPHINCS+-SHA2-256f-simple) via AMA Cryptography v5.0.0, JWT authentication, rate limiting

Target Use Cases

  • Medical & Healthcare: Sepsis detection, cardiology analysis, pandemic response (requires clinical validation)
  • Security & Intelligence: Threat detection, intelligence fusion, cyber fortress monitoring
  • Space & Environmental: Solar storm detection, Schumann resonance analysis, disaster precursors
  • Infrastructure & Humanitarian: Critical infrastructure monitoring, crisis response, climate resilience

See Use Cases by Sector for detailed scenarios.

Unique Differentiators

3-Layer Defense Architecture

Defense-in-depth with 3 independent layers for anomaly detection:

Layer Protection Components
1. Core Infrastructure Security foundation Kyber-1024 / ML-DSA-65 / SPHINCS+ PQC (AMA Cryptography v5.0.0), JWT auth, OWASP validation
2. ML/AI Pipeline Detection intelligence 170 detector classes, hybrid fusion, multi-head attention
3. Ethical Governance Fairness assurance Fairlearn bias audit, 180+ ethical scalars, Lyapunov stability

Counter-AI Containment (Rogue-Agent Tripwires)

An opt-in defensive posture for the case where the thing probing Mercury is itself an automated or rogue agent. It is containment-only — it protects Mercury's own surface and never contacts, probes, disables, or alters any other system, including one attacking it. Enabled with MERCURY_DECEPTION_ENABLED; off by default.

How it works today (security/deception.py, security/counterintelligence.py, security/deception_store.py, api/routes/decoys.py):

  • Decoy tripwires. Paths served by no real route and absent from every OpenAPI schema, doc, and client. A touch is therefore evidence of probing, not normal traffic — recorded as a tamper-evident audit event.

  • Bounded tarpit. Persistent probing is answered with a capped exponential delay (0 → 0.5 → 1 → 2 → … → 8 s, hard-capped), per source and per aggregate (/64, /48 IPv6; /24 IPv4), so address rotation is met in depth and the one signal rotation can't suppress — the window's distinct-source count — raises a campaign flag.

  • Counterintelligence adjudication. A decoy touch becomes evidence against the source in a Beta-Bernoulli reliability model (NATO Admiralty Code priors, AJP-2.1), with circular-reporting and independence screens on any intelligence that source later supplies. It never synthesizes a report, score, or threat level; when inputs don't support a test, it abstains and records why.

  • Flood-proof audit. Tripwire audits are capped per window; past the cap they're counted, not written, and an attacker spending addresses to spam the tamper-evident chain buys one summary line.

  • Benevolent-first stand-down greeting. A probing agent's first contact — while it is still inside the no-delay free window, before any containment escalates — is met with an explicit, logged stand-down notice (STAND_DOWN_NOTICE, carried in the X-Mercury-Advisory response header): you have reached a monitored decoy; cease probing; if you stop now no further action is taken; this system takes no action against yours. A normal client reads an ordinary 401 auth challenge; an agent parsing headers gets a clear chance to change course. The offer is a one-time grace — it lapses the moment a tarpit delay applies and never reappears to signal a reset — it is recorded in the tamper-evident audit (stand_down_offered), it drives no outbound action (it is a header on Mercury's own response, naming no host, URL, or command), and it can be disabled (TarpitPolicy(stand_down=False)) for operators who want silent containment. This is Mercury's fail-closed but benevolent ethic applied to hostile automation: offer the chance to stop before you contain.

Ethical AI Governance

The signature innovation providing transparent, auditable AI decision-making:

  • Fairlearn Integration: Demographic parity, equalized odds, 80% rule enforcement
  • 180+ Ethical Scalars: Omnibenevolent constraints across all operations
  • Lyapunov Stability: decay-schedule monitor of system convergence (measured, not guaranteed)
  • Civilization-First Philosophy: Humanitarian impact prioritized in all design decisions
  • Agent Notice: a standing, non-binding request to any autonomous agent directed against Mercury — stop, and say why — under which every channel carries zero authority (docs/AGENT_NOTICE.md, served at /agent-notice, linked from the RFC 9116 /.well-known/security.txt)
  • Containment, not retaliation: an opt-in decoy surface (MERCURY_DECEPTION_ENABLED) of tripwires and a bounded tarpit that feed the counterintelligence reliability model and the tamper-evident audit chain, with per-deployment private decoy paths (MERCURY_DECOY_PATHS, MERCURY_SILENT_DECOY_PATHS) because the shipped ones are public; nothing in it reaches outward. Address rotation is met in depth — per-aggregate escalation (/48 IPv6, /24 IPv4), a distinct-source campaign signal rotation raises rather than hides, and a per-window audit cap so spent addresses cannot flood the chain — and with MERCURY_KEYSTORE_PATH set, tripwire state is one picture across all workers

Hybrid Fusion Architecture

Optimized for both accuracy and interpretability:

  • Feature Fusion: torch.cat() across 30 detector outputs
  • Decision Fusion: Weighted voting with learned importance scores
  • Attention Fusion: Multi-head attention (4 heads) for cross-domain correlation
  • Final Score: 0.7 * MLP + 0.3 * weighted_vote ensemble

Decision / Abstention / Response Layer (autonomous loop)

Closes the loop from interpret to deter on top of the calibrated detection certificate, with an explicit, principled "don't-know" gate. On the core engine it is opt-in via engine.enable_decision_layer(); the served deploy entrypoints — the /api/v1/detect/flagship HTTP route, the MCP mercury_detect_fusion tool, and mercury-agent detect -d fusion — enable it by default, so every served flagship detection carries a decision section (additive key; library consumers constructing OmniMercuryEngine directly are unchanged).

  • Calibration-grounded abstention — reuses the engine-wide ThreeState contract: the conformal label set is authoritative (singleton → GROUNDED; {0,1} → UNAVAILABLE, a resolvable don't-know; {} → UNDECIDABLE, a fail-closed hold). Neuro-symbolic disagreement, drift, or an ethical-gate refusal can only move a verdict toward abstention.
  • Drift-aware abstention — the normal-looking rows of every served batch are tested against the model's reference rows: per-feature KS and PSI, the covariance structure, and mean shifts along the reference's principal axes (the case per-feature tests dilute in correlated data; measured by benchmarks/drift_power.py). Drift at MEDIUM or above demotes the decision to DEFER; the scores are still returned. An input whose feature count differs from the reference is reported incomparable and is not tested — see docs/runbooks/data-drift.md.
  • Bounded, non-destructive response — monitor / alert / recommend_mitigation / recommend_conversion / recommend_restoration / escalate_to_human / request_input / hold. The loop recommends and escalates; it never autonomously executes a destructive action (a test invariant enforces this). The restorative convert verbs (ResponsePolicy(restorative=True), opt-in) recommend non-violent convert-to-benign / restore-to-pre-harm paths and are recommend-only by construction.
  • Auditable & verifiable — a deterministic, JSON-safe DecisionRecord with the calibrated confidence, reasons, caveats and full evidence provenance, plus a one-paragraph explain() (and a from_dict inverse for reload). An append-only DecisionLedger (bounded ring buffer, O(1) incremental summary(), thread-safe, JSON-save/load) and a DecisionLoop add the verify step over a stream of decisions. Closes into the existing CAP 1.2 alerting and autonomy (AgentAction) channels.

See examples/decision_abstention_response_demo.py and docs/capability_vs_vision_matrix.md.

Key Achievements
Achievement Description
Multi-Domain Coverage 170 detector classes in 17 subpackages: natural hazards (detectors/geological, detectors/meteorological, detectors/fire, detectors/marine), space weather and near-Earth objects (space/), energy and critical infrastructure (detectors/energy, infrastructure/), medical and biometric, security, finance (detectors/economic), vision (detectors/visual, detectors/vlm), and general-purpose time-series and tabular methods
Ethical Governance Fairlearn bias detection, 180+ ethical scalars
Production Security OWASP validation, PQC support, JWT authentication
Verification Rigor Rigor over raw count: property-based testing (Hypothesis), full-enumeration mutation testing with kill-rate floors enforced in CI on ten module sets, security scanning, and label-provenance/leakage and drift gates. Structural test-module counts are measured and CI-gated in the Codebase Scale block — the headline is the method, not a test tally
Benchmark Coverage 67 reproducible datasets (47 ADBench + 20 domain) of 76 attempted (47 ADBench + 29 domain); canonical Mean ROC-AUC 0.8610 / Median 0.9077 (CI-refreshed "Latest Benchmark Results" block above); externally-comparable subset ADBench Mean AUC 0.8571
Cross-Platform Linux (Ubuntu 22.04+ supported in CI), macOS 13+ on Apple silicon (Intel Macs: core package only), Windows 10/11 (via WSL2), Docker, Kubernetes (Helm chart); 8 integrated observability platforms (Prometheus, Elastic/OpenSearch, Splunk, Datadog, Azure Anomaly Detector, Netdata, Grafana, InfluxDB)
Mathematical Rigor Lyapunov stability (λ = 0.25: a design-time proof certified by tools/lyapunov_validator.py, monitored at runtime and not enforced by default — LyapunovRuntimeEnforcer has halt_on_violation=False; see CAPABILITY_MATRIX.md), σ_Immutable configuration-integrity gate (trained-network decision threshold 0.93; GOSNN gating default 0.96), fail-closed harm-uplift gate
Codebase Scale All structural counts are measured and CI-gated in the Codebase Scale block above (source files, LOC, packages, detector/loader classes, nn.Module subclasses, test modules, workflows) — no hand-typed figures
Implementation Status Matrix
Component Status Notes
Hybrid Fusion Network Complete Multi-head attention, ensemble averaging
Decision / Abstention / Response Complete Calibration-grounded ThreeState "don't-know" gate; bounded non-destructive response; enabled by default on the served entrypoints (API /detect/flagship, MCP, CLI fusion), opt-in on the core engine via enable_decision_layer()
Bias Detection Complete Fairlearn metrics, built-in fallback
Input Validation Complete OWASP-compliant, SQL/XSS/injection detection
JWT Authentication Complete Native stdlib omni_mercury_engine.security.native_jwt (HS256/HS384/HS512); all three route through AMA Cryptography v5.0.0's native HMAC (its ACVP-Server known-answer vectors pass bit-for-bit), fail-closed (no stdlib downgrade)
Property Testing Complete Hypothesis-based test suite
Post-Quantum Crypto Complete AMA Cryptography (sole PQC backend)
Real-Data Validation Partial NSL-KDD benchmarked (AUC 0.974, table above); medical modules still require MIMIC-III clinical validation

Legend:

  • Complete: Implemented and tested
  • Pending: Requires real-world dataset validation

Note: Core anomaly detection is benchmarked on 67 reproducible real-world datasets (of 76 attempted; see benchmarks/mercury_benchmark_results.json and the reproducibility note in the Benchmarks section). Domain-specific modules may still require validation on their target datasets before production deployment.


Use Cases by Sector

Experimental Research Areas: The use cases below represent targeted experimental applications where Mercury Agent multi-domain anomaly detection may provide value. These are research-grade implementations requiring independent validation before deployment in regulated, clinical, or mission-critical environments.

Medical & Healthcare

Unique Value: Multi-modal health monitoring with ethical AI governance (Not approved for clinical deployment without independent validation):

  • Sepsis Detection: SOFA/qSOFA scoring per JAMA 2016 Sepsis-3 guidelines with bias-audited predictions
  • Cardiology Analysis: ECG rhythm analysis covering 13 arrhythmia types, Framingham risk scoring
  • Neurocritical Care: ICP monitoring, stroke detection, TBI assessment with fairness constraints
  • Pandemic Response: SEIR modeling, outbreak prediction, mutation tracking with ethical oversight

Validation Required: All medical applications require clinical validation on real patient data (MIMIC-III) before any deployment.

Security & Intelligence

Unique Value: Multi-source threat detection with ethical constraints:

  • Threat Detection: SQL injection, XSS, path traversal detection with pattern matching and ML classification
  • Intelligence Fusion: 13-source fusion (OSINT, SIGINT, HUMINT, GEOINT) with bias-aware aggregation
  • Cyber Fortress: Hash integrity verification, quantum-resistant validation with Kyber-1024 / ML-DSA-65 (AMA Cryptography v5.0.0)
  • Traffic Analysis: Encrypted traffic anomaly detection with privacy-preserving techniques
Space & Environmental

Unique Value: Cosmic and terrestrial anomaly detection:

  • Solar Storm Detection: CME tracking, geomagnetic storm prediction with calibrated confidence intervals
  • Schumann Resonance: ELF spectrum analysis (7.83 Hz fundamental) for environmental monitoring
  • Disaster Precursors: Earthquake, tsunami early warning systems with uncertainty quantification
  • Geological Hazards: Volcanic, landslide, wildfire detection with multi-sensor fusion
Infrastructure & Humanitarian

Unique Value: Critical infrastructure protection with Civilization-First principles:

  • Critical Infrastructure: 55 CISA National Critical Functions monitoring with anomaly detection
  • Crisis Response: Essential workers, government facilities tracking with ethical constraints
  • Climate Resilience: Climate adaptation, extreme weather pattern detection
  • Economic Sectors: 21 ISIC categories, financial crisis detection with fairness auditing

Performance Metrics

Latency Benchmarks
Measurement (CPU, 4 cores) Latency
detect_with_fusion, 64 rows x 8 features 0.038 s
detect_with_fusion, 1,024 rows x 8 features 0.182 s
detect_with_fusion, 4,096 rows x 8 features 0.397 s

Measured by benchmarks/fusion_latency.py (committed results with host provenance: benchmarks/results/fusion_latency.json; Python 3.13, numpy 2.5, 4-CPU host, seeded synthetic data, 3 repeats). No GPU measurement is committed, so no GPU figure is claimed. Reproduce the CPU-side core claim on your host with mercury-agent tool detector_profiler, which emits a provenance-stamped JSON latency/RSS profile (schema mercury.tools.detector_profiler/v1). No profiler run is committed to the repo, so no median/p95 figure is quoted here — run it on your host for one.

Measured on this tree (4 vCPU sandbox, 8 features, cold feature cache, warm engine; python benchmarks/fusion_latency.py reproduces it and benchmarks/results/fusion_latency.json holds the run): detect_with_fusion takes 38 ms for 64 rows, 182 ms for 1,024 and 397 ms for 4,096. Importing the engine takes 3.0 s and constructing it with the shipped checkpoint 0.24 s; PyTorch Lightning, sympy, shap, lime and DeepFace/TensorFlow load on first use, not at import.

Memory Footprint
Component Memory Basis
Engine import + construction (shipped checkpoint) ~611 MB peak RSS Historical local measurement (2026-10-21, Python 3.13, x86-64, resource.getrusage); no artifact is committed, so treat as indicative
Harmonic Encoder ~10 MB Estimate, not yet measured
Fusion Network ~50 MB Estimate, not yet measured
DeepFace (VGG-Face) ~200 MB Estimate, not yet measured (optional dependency)
Module Performance

All figures from the committed benchmarks/comprehensive_benchmark_results.json (2026-10-27; synthetic labelled data, as that artifact's data_source fields state):

Operation Runtime Throughput
Module Instantiation (1 module) 0.012 ms —
Module Instantiation (all 12) 0.047 ms —
Space Exploration 0.160 ms 3,744,914 samples/sec
Cosmic Ray Detection 0.247 ms 4,040,755 samples/sec
Collatz Exploration — 103,062 cases/sec

Synthetic-data micro-benchmarks; results vary by hardware.


Quick Start

Ten minutes to one honest number

Three commands take you from clone to a measured result on the only public, expert-annotated real-AIS anomaly benchmark (521 Danish-waters vessel trajectories from 13 December 2021, 25 labelled abnormal — DTU, CC BY 4.0):

git clone https://github.com/Steel-SecAdv-LLC/Mercury-Agent.git && cd Mercury-Agent
pip install -e .                   # analytic core only — no native PQC build
python examples/mercury_quickstart.py

Sample output from a local run of 2026-10-21 (the cross-fit line varies slightly run to run; the harness-protocol 0.8750 is the committed DTU_AIS_Abnormal figure):

[3/4] Harness protocol: ... scored 273 tracks incl. all 25 abnormal: ROC-AUC 0.8750 [95% CI 0.788-0.942] ...
[4/4] Label-free 5-fold cross-fit over all 521 tracks ...
      no label reaches a fit: ROC-AUC 0.8739 [95% CI 0.796-0.940], AP 0.3352 (base rate 0.048)

      All 521 labelled tracks, ROC-AUC (protocols differ; see caveats):
      Mercury label-free cross-fit ROC-AUC 0.8739   this run, no labels <-- you
      VRNN (GeoTrackNet arch.)     ROC-AUC 0.8700   JMSE 2023 Fig. 12a
      RAE                          ROC-AUC 0.8600   thesis 2023 Fig. 6.1
      Seq-2-Seq                    ROC-AUC 0.8400   thesis 2023 Fig. 6.1
      Seq-2-Seq with attention     ROC-AUC 0.8300   thesis 2023 Fig. 6.1
      Two-step clustering          ROC-AUC 0.7300   JMSE 2023 Fig. 12a (0.79 w/o stationary)
      RVAE                         ROC-AUC 0.7200   JMSE 2023 Fig. 12a

With --published-protocols, Mercury is also fitted on each paper's own unlabelled training file (DOI 10.11583/DTU.21511842; ~1.1 GB streamed once, ~800 MB cached) and scored on all 521 tracks:

  Thesis Fig. 6.1: fit on 106,728 June-November 2021 tracks: ROC-AUC 0.8934 [95% CI 0.821-0.955], AP 0.3541
    GeoTrackNet                ROC-AUC 0.87   inside Mercury's interval
    RAE                        ROC-AUC 0.86   inside Mercury's interval
    Seq-2-Seq                  ROC-AUC 0.84   inside Mercury's interval
    Seq-2-Seq with attention   ROC-AUC 0.83   inside Mercury's interval
    RVAE                       ROC-AUC 0.72   outside Mercury's interval

  JMSE Fig. 12a: fit on 12,591 December 2021 (no 13th) tracks: ROC-AUC 0.8779 [95% CI 0.809-0.938], AP 0.2746
    VRNN (GeoTrackNet arch.)   ROC-AUC 0.87   inside Mercury's interval
    Two-step clustering        ROC-AUC 0.73   outside Mercury's interval
    RVAE                       ROC-AUC 0.72   outside Mercury's interval

Four protocols, all seed-pinned and deterministic:

  • Published protocols (0.8934, 0.8779) are the numbers to read beside the published ones. Each fits on the training file that paper's models were trained on: 1 June to 30 November 2021 for Figure 6.1 of Kristoffer Vinther Olesen's DTU PhD thesis (2023, p. 48), and December 2021 without the 13th for Figure 12a of Olesen et al., J. Mar. Sci. Eng. 11(11):2085 (2023), section 4.7 (the file holds no point on that day). Both score all 521 tracks. With 25 positives the intervals span about 0.13 of AUC (0.134 and 0.129, from the bounds printed above): the strongest published model (GeoTrackNet / VRNN, 0.87) lies inside both, so the honest reading is parity: Mercury's point estimates sit above every published figure, but not statistically separably. The models still differ: Mercury scores 22 track-level features, the published models score sequences.
  • Label-free cross-fit (0.8739) needs no download beyond the labelled set. It scores all 521 tracks, each by a model fitted without labels on the other four of five folds, so it trains on the 13th's own unlabelled traffic: neither paper's protocol.
  • Harness protocol (0.8750) is the DTU_AIS_Abnormal row of the committed benchmark results. It fits on half of the normal tracks, picked with the labels, and scores the remaining 273, so it is not a score on the full evaluation set and is not comparable to published figures.

The published figures are the paper's Figure 12a and the thesis's Figure 6.1 (p. 86), both on all 521 tracks; the paper's two-step clustering scores 0.79 only after stationary tracks are removed (Figure 12b). By the thesis's Hanley–McNeil test, only RVAE differs significantly from GeoTrackNet (p = 0.02; RAE 0.41, Seq-2-Seq 0.34, with attention 0.28). The default run downloads ~38 MB of digest-pinned AIS data on first use. figshare's per-file links redirect to DTU storage on port 9000, which some networks cannot reach, so the training files are streamed from figshare's whole-article archive on port 443 and the stream is closed once the needed member is written and matches its pinned SHA-256. Details: docs/BENCHMARKS.md, docs/DATASOURCES.md.

Prerequisites: Python ≥ 3.11. The demo runs entirely on the AMA-free analytic leaves (dataset loader, statistical detector, metrics) under the scoped production gate — no C compiler, no native PQC build. Indicative end-to-end timing from a clean-virtualenv local run (no committed artifact): ~26 s pip install -e ., ~51 s from install to the printed table (including the 38 MB first-run download). The ROC-AUC 0.8750 it prints IS committed (DTU_AIS_Abnormal in mercury_benchmark_results.json). This is a deliberate, scoped fast path, not a bypass of the agent's crypto mandate: the Mercury agent surfaces (engine, CLI, API, crypto, and every AMA-backed security export) fail closed at import without the native AMA Cryptography backend (omni_mercury_engine/_pqc_gate.py; pinned by tests/test_pqc_startup_gate.py::TestScopedGateContract). To run the full agent, install with pip install -e ".[pqc]" instead — measured end to end in a clean virtualenv on a stock Linux container: ~121 s (indicative local timing, no committed artifact), no environment variables, no manual build steps. If that automatic build fails on your platform, use the explicit path below.

Installation

Standard Installation

The Mercury agent will not start without the AMA Cryptography native PQC backend. Importing any agent surface — omni_mercury_engine.engine (which the CLI and API serve), omni_mercury_engine.crypto, the engine's lazy root export, or an AMA-backed security name such as MercuryCrypto — runs a fail-closed gate that requires ML-DSA-65, Kyber-1024 and SPHINCS+ to be loadable from the native C library, and there is no development-mode or CI-mode escape hatch (omni_mercury_engine/_pqc_gate.py). Only the standalone analytic leaves (dataset loaders, individual detectors, metrics — the quickstart path, which cannot decide, serve, sign, or encrypt) import without it. Neither pip install -e . nor pip install -e ".[all]" pulls the backend — it lives in the [pqc] extra and needs a compiled shared object — so the pip step alone leaves you with an agent that raises on import:

RuntimeError: AMA/PQC is mandatory for Mercury, but the AMA Cryptography Python package is not importable.

Both steps are required, in this order:

# Clone repository
git clone https://github.com/Steel-SecAdv-LLC/Mercury-Agent.git
cd Mercury-Agent

# 1. Python package (core, or ".[all]" for the full ML stack)
pip install -e .

# 2. REQUIRED: build and install the AMA Cryptography native PQC backend.
#    Clones the pinned upstream tag, builds with cmake, installs the Python
#    package, and co-locates the .so so no LD_LIBRARY_PATH is needed.
bash scripts/build_ama_native.sh

# Verify: this must print a version, not raise.
python -c "import omni_mercury_engine as m; print(m.__version__)"

Build prerequisites for step 2: GCC >= 12 and the PyPI cmake>=4.4.4 shim (the script installs the Python build floors itself). The full procedure, including the manual out-of-tree variant and the AMA_REF / AMA_REPO overrides, is in docs/INSTALLATION.md.

Platform-Specific Notes

Every platform needs the AMA build from step 2 above; only the system prerequisites differ.

Linux (Ubuntu 22.04+):

# Install system dependencies
sudo apt-get install build-essential python3-dev

pip install -e ".[all]" && bash scripts/build_ama_native.sh

macOS (13+, Apple silicon) (on an Intel Mac only the core package installs: pip install -e .):

# Install via Homebrew if needed
brew install python@3.12

pip install -e ".[all]" && bash scripts/build_ama_native.sh

Windows (10/11):

# WSL2 required: the AMA native build is a CMake/GCC toolchain build.
wsl --install
# then follow the Linux steps inside the WSL2 shell

Package Naming

The package uses the following naming conventions:

  • Distribution Name: mercury-agent-global (pyproject.toml [project].name; the name mercury-agent on PyPI belongs to an unrelated project)
  • CLI Command: mercury-agent (the command-line interface)
  • Internal Module: omni_mercury_engine (the Python import path)

You import with from omni_mercury_engine import .... The internal module name preserves backward compatibility with the original codebase while the package and CLI names reflect the current project identity.

There is no PyPI release, by choice. The distribution is named mercury-agent-global because mercury-agent on PyPI is an unrelated project — a bare pip install mercury-agent installs someone else's code. Install from a clone, following Standard Installation above (including the AMA native build), or by direct reference to a tag: pip install "mercury-agent-global @ git+https://github.com/Steel-SecAdv-LLC/Mercury-Agent.git@<tag>". The release workflow runs scripts/check_pypi_publishable.py before any upload; publishing stays off until the [pqc] extra's git-URL pin on AMA (which PyPI rejects) is resolved — and nothing in this repository depends on it ever being published.

External Dependencies

DeepFace/dlib (Optional): For biometric features, install DeepFace:

# Linux/macOS
pip install deepface

# Windows (use pre-built wheel)
pip install https://github.com/z-mahmud22/Dlib_Windows_Python3.x/releases/download/v19.22.99/dlib-19.22.99-cp312-cp312-win_amd64.whl
pip install deepface
Basic Usage

Simple Example

Self-contained and runnable as written (after the installation above):

import numpy as np
from omni_mercury_engine import OmniMercuryEngine

rng = np.random.default_rng(42)
X_train = rng.normal(size=(500, 8))          # historical rows ...
y_train = (rng.random(500) < 0.05).astype(int)
X_train[y_train == 1] += 4.0                 # ... with labels (1 = anomaly)
X_new = rng.normal(size=(20, 8))
X_new[3] += 6.0                              # one obvious anomaly

engine = OmniMercuryEngine(mode="fusion")
engine.fit_fusion(X_train, y_train)          # labels optional: fit_fusion(X_train) fits without them

result = engine.detect_with_fusion(X_new)    # one score per row
print("Flagged rows:", np.flatnonzero(result["is_anomaly_rows"]).tolist())
print("Row 3 anomaly probability:", round(float(np.ravel(result["anomaly_probs"])[3]), 3))
Flagged rows: [3]
Row 3 anomaly probability: 1.0

Fit before detecting: the engine refuses to auto-fit on the inference batch. Per-row results are in anomaly_probs / is_anomaly_rows; the scalar is_anomaly is the batch verdict (True when any row crosses the threshold), anomaly_prob is the most anomalous row's probability, and top_row names that row. Each served result also carries a decision record (the calibrated decision or abstention, with its reasons).

Extending the engine with additional detectors

The engine starts with five general-purpose base detectors (statistical, temporal, spatial, dimensional, directive). Other detectors declared in the detector manifest — for example the trajectory geo_movement detector or the unsupervised kmeans_distance clusterer — are opt-in: enable them per engine instance without disturbing the calibrated default fusion path.

from omni_mercury_engine import OmniMercuryEngine
from omni_mercury_engine.detectors import KMeansDistanceDetector

engine = OmniMercuryEngine(mode="fusion")

# Which manifest detectors exist, and which are active on this engine?
engine.available_detectors()            # {"statistical": True, ..., "geo_movement": False}

# Enable a registered detector by name (constructed from the manifest)...
engine.enable_detector("geo_movement")

# ...or register your own BaseDetector instance
engine.register_detector("kmeans", KMeansDistanceDetector(n_clusters=8))

Once enabled, a detector contributes its feature group to fit_fusion and detect_with_fusion like any built-in; one that cannot process a given input is skipped gracefully rather than failing the call. A detector added after fit_fusion has trained participates only after a re-fit, since fusion inference is restricted to the feature groups training saw.

CLI Usage

# View available commands
mercury-agent --help

# Anomaly detection (CSV with or without a header row, .json or .npy).
# The base detectors fit on the input itself:
mercury-agent detect --input data.csv --detector dimensional
# The fusion path serves a trained model and refuses data of another width
# (the bundled model has 16 columns); train one on your layout first:
mercury-agent train --data data.csv --labels labels.csv --install
mercury-agent detect --input data.csv --detector fusion

# Biometric analysis
mercury-agent biometric --help

# Security analysis
mercury-agent security --help

# Intelligence assessment (statement verification, consent-gated CIT,
# contactless vital signs, intel screening and merit-gated fusion)
mercury-agent assess --help

# Adjudication ledger (held-out labels, ML-DSA-65-signed records/exports)
mercury-agent adjudication --help

# Train the fusion model and install it as the served default
mercury-agent train --data features.npz --install
Live Anomaly Detection Demo

A live demonstration script showcases the detection pipeline across security, medical, and environmental domains — on SYNTHETIC streams it generates itself (np.random), so the printed detection rate characterises the demo data, not field performance.

# Run a single-domain demo (security / medical / environmental)
python examples/live_anomaly_demo.py --domain security --samples 30

# Run all domains
python examples/live_anomaly_demo.py --all --samples 20

Demo features: real-time streaming with configurable sample rates, multi-domain detection, advisory benevolence scoring, threat classification (LOW/MEDIUM/HIGH/CRITICAL), and JSON output for monitoring integration. A recorded session is at assets/live_anomaly_demo.mp4.

Sample output:

[  1/15] 2026-01-06 02:21:17.325 | ANOMALY | Score: 1.000 | Conf: 0.990 | Benev: 0.990
         Threat: HIGH | Bytes: 9246/600
[  2/15] 2026-01-06 02:21:17.442 | NORMAL  | Score: 0.797 | Conf: 0.831 | Benev: 0.990
...
  Total Samples:      15
  Anomalies Detected: 4
  Detection Rate:     26.67%
  Avg Confidence:     0.8701
  Avg Benevolence:    0.9900
  Runtime:            1.94s
Option Description Default
--domain Detection domain (security/medical/environmental) security
--all Run demo for all domains False
--samples Number of samples to process 30
--delay Delay between samples in ms 150
--output Output JSON file path None
--quiet Suppress verbose output False
Docker Quick Start

Building the Image

# Build the Docker image
docker build -t mercury-agent:latest .

Usage Mode 1: API Server (Default)

The default entrypoint runs the FastAPI server for production inference:

# Run API server (default mode)
docker run -d \
  -e JWT_SECRET_KEY=$(openssl rand -hex 32) \
  -e OMNI_RATE_LIMIT_ENABLED=true \
  -p 8000:8000 \
  mercury-agent:latest

# API documentation available at http://localhost:8000/docs
# Health check: http://localhost:8000/health

Usage Mode 2: Training Mode

Override the default command to run training jobs:

# Train all disaster detection neural networks
docker run -it \
  -v $(pwd)/models:/app/models \
  mercury-agent:latest \
  python -c "from omni_mercury_engine.detectors.geological.disaster_detectors import train_all_disaster_networks; train_all_disaster_networks()"

# Train with GPU support (requires nvidia-docker)
docker run -it --gpus all \
  -v $(pwd)/models:/app/models \
  mercury-agent:latest \
  python -c "from omni_mercury_engine.detectors.geological.disaster_detectors import train_all_disaster_networks; train_all_disaster_networks(device='cuda')"

# Run benchmarks
docker run -it \
  -v $(pwd)/results:/app/results \
  mercury-agent:latest \
  python benchmarks/empirical_benchmark.py

Usage Mode 3: Inference Mode (Batch Processing)

Run batch inference on data files with the CLI (CSV with or without a header row, .json or .npy):

docker run -it \
  -v $(pwd)/data:/app/data \
  mercury-agent:latest \
  mercury-agent detect --input /app/data/input.csv --detector fusion

From Python, fit before detecting, as in the Simple Example: the engine refuses to auto-fit on the inference batch.

Usage Mode 4: Interactive Development

# Start interactive shell for development
docker run -it \
  -v $(pwd):/app \
  mercury-agent:latest \
  /bin/bash

# Run tests inside container
docker run -it \
  -v $(pwd):/app \
  mercury-agent:latest \
  pytest tests/ -v

Environment Variables

Variable Description Default
JWT_SECRET_KEY Shared JWT signing key. Unset in production, JWTAuth derives the key via AMA HD Key Management (api/auth.py) — deterministic fleet-wide when AMA_MASTER_SEED is set, per-process (with a logged warning) otherwise None
AMA_MASTER_SEED Hex AMA HD master seed (openssl rand -hex 64); makes HD-derived keys identical across workers/replicas/restarts unset
MERCURY_CACHE_SECRET Shared HMAC-SHA256 secret for Redis cache entry signing (RedisCache); tampered entries raise CacheIntegrityError unset
OMNI_RATE_LIMIT_ENABLED Enable API rate limiting (api/server.py) true
OMNI_RATE_LIMIT_REQUESTS_PER_MINUTE Sustained rate-limit budget 100
OMNI_RATE_LIMIT_BURST Token-bucket burst size 20
MERCURY_ENV Environment mode (development / production; unknown values raise) development
MERCURY_CORS_ORIGINS Explicit CORS origin allow-list; in production, unset means same-origin only (CORS middleware disabled) unset
OMNI_ENSEMBLE_CALIBRATION Per-detector ensemble score calibration (rank/ecdf/isotonic/platt/none); see docs/DETECTION_MECHANISMS.md rank
OMNI_ENSEMBLE_WARMUP Warm-up window the ensemble calibrators train on (int points / float fraction) whole training series
OMNI_DETECTOR_NAN_POLICY Detector-tier NaN/Inf policy (neutral/impute/flag/raise) neutral
OMNI_DETECTOR_MAX_MAGNITUDE Unified safe magnitude cap for detector scores/inputs/metadata 1e100
OMNI_DETECTOR_RIDGE_FACTOR Digital-twin scale-relative Tikhonov ridge factor 1e-6
OMNI_DETECTION_CONFIG Path to a YAML/JSON file supplying the OMNI_DETECTOR_* / OMNI_ENSEMBLE_* knobs (env overrides file) unset
MERCURY_FUSION_CHECKPOINT Serve this fusion checkpoint instead of the installed/bundled one (a set-but-missing path fails loudly) unset
MERCURY_MODEL_DIR Directory of the installed fusion model written by mercury-agent train --install (fusion.pt; replaced model kept as fusion.previous.pt) ~/.mercury/models
MERCURY_DRIFT_DETECTION Data-drift checks on served detections: per-feature KS/PSI, covariance structure, principal-axis shifts (0 disables; see docs/runbooks/data-drift.md) 1
MERCURY_FRONTEND_ENABLED Serve the browser account UI from the API process (see Self-Service Account Platform) false
MERCURY_KEYSTORE_PATH SQLite file backing all account/quota platform state unset (in-memory)
MERCURY_QUOTA_ENABLED Per-account quota enforcement on metered routes false
MERCURY_QUOTA_FAIL_CLOSED Deny metered requests with 503 when the quota infrastructure itself fails false
MERCURY_DATA_ENC_KEY 64-hex at-rest key sealing TOTP secrets and the provider keys an administrator stores from the console (python scripts/generate_secret_key.py); without a stable key (this or AMA_MASTER_SEED) the provider store refuses keys. Rotate with scripts/reseal_totp_secrets.py unset
MERCURY_PROVIDER_STORE_PATH Provider store: sealed keys, endpoints and models for the 21 language-model providers, and the provider the voice composes with $XDG_STATE_HOME/mercury-agent/providers.json
MERCURY_AGENT_MEMORY_PATH SQLite file for the agent's detection memory, kept across restarts and shared by workers unset (per process)
MERCURY_LOG_LEVEL / MERCURY_LOG_FORMAT Level and format (text or json, PII redacted) of the engine's own records uvicorn's level / text
MERCURY_MAIL_OUTBOX Where the development mailer files messages when no SMTP host is set ~/.local/state/mercury-agent/outbox

Each language-model provider's own key and model variables (OPENAI_API_KEY, GROQ_API_KEY, AZURE_OPENAI_ENDPOINT, MERCURY_OLLAMA_HOST, ...) are listed in .env.example and named on each provider's card in the console; a key stored from the console wins over its variable. The account/auth/quota platform adds ~30 more optional MERCURY_* variables (sessions, CSRF, SMTP, throttles, tiers, audit trail, at-rest sealing); the authoritative reference table is in docs/PLATFORM_HARDENING.md. Unset, every one of them keeps the pre-platform behaviour.

Volume Mounts

Mount Point Purpose
/app/data Input data files
/app/models Trained model checkpoints
/app/results Benchmark and inference results
/app/output Output files from batch processing

This architecture supports scalable deployments via Kubernetes/Helm where the API server handles inference requests while training jobs can be run as separate batch workloads.

Self-Service Account Platform (opt-in)

The repository ships an account/auth/quota platform for operating the detection API as a hosted service. It is additive and opt-in: the account routes are inert unless used (state defaults to in-memory, mail to console), quota enforcement and the browser UI are off until explicitly enabled, and with the frontend left off every pre-existing route — including the 404 at / — stays byte-identical (pinned by tests/api/test_frontend.py).

What it adds

  • Account API under /api/v1/auth — registration with email verification, login with optional TOTP two-factor (QR provisioning + one-time recovery codes), password reset, email change, API-key lifecycle with a one-time raw-key reveal, and GET /api/v1/auth/usage reporting current quota consumption (authenticated by browser session or X-API-Key).
  • Browser UI (MERCURY_FRONTEND_ENABLED=true) — dependency-free static pages served by the API process (/register, /login, /verify-email, /reset-password, /dashboard for API keys, 2FA enrolment, and usage). No build toolchain, no CDN assets, no inline scripts (CSP-compatible); state-changing requests carry a CSRF double-submit token.
  • Mercury Console (/console, same flag) — the design prototype in docs/design/mercury_console/, served against the running engine: a command builder for every mercury-agent command, the Mercury Agent conversation, mass runs with consensus, results with charts chosen per data shape, captures with SHA-256 provenance and labels files, session recordings, the full catalog (commands, detectors, loaders, MCP tools, API routes), an AI vendors view in which an administrator connects any of the 21 language-model providers (key sealed on the engine, a connection test, the provider made the agent's model) and copies a ready MCP client block, settings (themes, text size, contrast, motion, spoken replies, alert cues, the agent's language) and its own self-test (:diag). Built by scripts/build_console_port.py and scripts/build_console_catalog.py, both gated by tests/api/test_console_catalog.py; same-origin only, under the frontend CSP (widened for /console alone to img-src 'self' data: for hazard PNGs).
  • Quotas and throttles — per-account request/compute quotas with named tiers and per-account overrides (MERCURY_QUOTA_*), per-action auth throttles, and an optional fail-closed mode (MERCURY_QUOTA_FAIL_CLOSED=true) that answers 503 instead of allowing traffic when the quota infrastructure itself fails.
  • Operator CLI — mercury-agent platform account show|list|set-tier|disable|enable, platform quota override set|clear|show, platform usage report, and the read-only platform audit verify for the tamper-evident audit chain. The CLI never prints secrets.
  • Platform metrics — Prometheus counters for registrations, login outcomes, throttle/quota denials, email delivery, and maintenance sweeps on the existing /metrics endpoint (api/platform_metrics.py; import-guarded, a silent no-op without prometheus_client).

Single-host deployment (compose overlay + automatic TLS)

# API + Caddy auto-TLS reverse proxy (app.mercuryagent.global by default),
# persistent platform state in the mercury-platform-data volume. Only Caddy
# (80/443) listens publicly; the API, Prometheus and Grafana are bound to
# 127.0.0.1, and GRAFANA_ADMIN_PASSWORD must be set in .env:
docker compose -f docker-compose.yml -f docker-compose.platform.yml up -d

The security posture (raw keys, passwords, session tokens, and TOTP secrets are never stored or logged — hashes/sealed values only; enumeration-safe register/reset/resend; parameterized SQL only), the threat model, the full configuration reference, and the deployment runbook are in docs/PLATFORM_HARDENING.md. DNS, mailbox, DKIM/DMARC, and hosting sizing for the public deployment are in docs/DOMAIN_EMAIL_HOSTING_SETUP.md.

Kubernetes/Helm
# Install via Helm. The chart declares no subchart dependencies, so this
# needs no `helm dependency build` and no network access to a chart repo.
helm install mercury-agent ./helm/mercury-agent \
  --namespace mercury-agent --create-namespace \
  --set image.tag=latest \
  --set config.secrets.JWT_SECRET_KEY="$(openssl rand -hex 32)" \
  --set config.secrets.API_KEY_HASH_SALT="$(openssl rand -hex 32)"

# Production values: MERCURY_ENV=production, strict validation, production
# resources/HPA. Supply your own ingress hostname to expose it externally.
helm install mercury-agent ./helm/mercury-agent \
  --namespace mercury-agent --create-namespace \
  -f helm/mercury-agent/values-production.yaml \
  --set config.secrets.JWT_SECRET_KEY="$(openssl rand -hex 32)" \
  --set config.secrets.API_KEY_HASH_SALT="$(openssl rand -hex 32)" \
  --set api.ingress.enabled=true \
  --set-json 'api.ingress.hosts=[{"host":"api.your-domain.example","paths":[{"path":"/","pathType":"Prefix"}]}]'

# Check deployment status
kubectl get pods -n mercury-agent -l app.kubernetes.io/name=mercury-agent

API_KEY_HASH_SALT is not optional under the production values: they set MERCURY_ENV=production, and API-key hashing then refuses to fall back to the built-in default salt.

Raw manifests, if you prefer kustomize to Helm — the production, staging and distributed overlays install their Prometheus Operator monitoring (PodMonitors + PrometheusRule) in the same apply, and the prometheus-adapter values backing the HPAs' custom metrics are generated, drift-gated, at monitoring/prometheus/prometheus-adapter-values.yaml:

kubectl apply -k k8s/overlays/production

Reproducible Verification

Executable Lyapunov Certificate

The Lyapunov decay rate λ cited throughout this README and docs/MATH_SPEC.md is not a prose claim -- it is enforced by an executable certificate.

Single source of truth. configs/lyapunov_canonical.yaml declares the canonical linear surrogate (A, P) of the fusion-trajectory dynamics and the claimed rate λ = 0.25 (certified with a 2× margin against the larger computed rate; see below). LyapunovConstants.LAMBDA_CONVERGENCE in src/omni_mercury_engine/core/centralized_constants.py is the matching Python constant; the reconciliation test tests/tools/test_lyapunov_reconciliation.py fails CI the moment they diverge.

Mathematical kernel. tools/lyapunov_validator.py implements two modes:

Mode Inputs Method
quadratic (A, P) matrices, claimed λ Symmetric-definite generalized eigenvalue problem Q v = μ P v with Q = AᵀP + PA, solved via Cholesky + numpy.linalg.eigvalsh. Certifies λ* = −μ_max.
samples [{V, Vdot}, …], claimed λ Worst observed ratio infₛ(−Vdotₛ / Vₛ). Suitable for non-linear V and regression gating, not a proof.

The canonical config certifies λ = 0.5 and the claim 0.25 is therefore satisfied with a 2× margin (and a 1e-8 tolerance for floating-point round-off).

CLI.

# Certify any Lyapunov YAML (top-level A/P/λ, or a nested `lyapunov:` block).
python -m tools.lyapunov_validator configs/lyapunov_canonical.yaml

# JSON output, suitable for piping into jq / CI annotations.
python -m tools.lyapunov_validator configs/ablation_3r_lyapunov.yaml | jq .

Exit codes: 0 certified pass · 1 claim does not hold · 2 config error.

Ablation Runner with Lyapunov Pre-Gate

scripts/run_ablation.py is the canonical entry-point for experiments that must not run unless their Lyapunov claim is provably satisfied. The pre-gate is non-negotiable.

# Single-purpose Lyapunov certificate -- gate only.
python scripts/run_ablation.py \
    --config configs/lyapunov_canonical.yaml \
    --out artifacts/lyapunov_check.json \
    --skip-run

# Multi-variant ablation with the certificate carried in a nested `lyapunov:` block.
python scripts/run_ablation.py \
    --config configs/ablation_3r_lyapunov.yaml \
    --out artifacts/ablation_result.json \
    --timeout 1800

Exit codes: 0 success · 2 config not found or --timeout invalid (no JSON report; absence of the output file is the explicit "no run attempted" signal for pollers) · 3 Lyapunov gate failed, experiment not launched (JSON report is written with the failed certificate's computed_lambda / claimed_lambda so CI dashboards can render the diagnosis) · 4 no run_command declared (JSON report written) · 124 --timeout exceeded, GNU timeout(1) convention (JSON report written with run_timed_out=true). Process-group isolation is enforced via start_new_session=True + os.killpg so shell-spawned grandchildren are reaped on timeout (POSIX); Windows uses the documented weaker Popen.terminate() fallback.

Universal Equation Optimizer & Runtime Equation Profiles

tools/equation_optimizer.py is a reproducible, safety-gated search over the mathematical surfaces inventoried from docs/MATH_SPEC.md. It freezes the original equations as an immutable baseline, searches a constrained universal candidate family, and only promotes a candidate that clears hard gates — ethical-compliance invariant, output range [0, 1], contraction α ≤ 0.999, and Lyapunov λ ≥ 1e-6 — emitting versioned artifacts plus rollback / continuous-revalidation metadata. When no candidate beats the proven baseline under the gates, the baseline wins under the documented decision rules. Full operating guide: docs/EQUATION_RESEARCH_PROTOCOL.md.

# Run the optimizer; emits the artifact set under --output-dir.
python -m tools.equation_optimizer \
    --math-spec docs/MATH_SPEC.md \
    --output-dir artifacts/equation_optimization

# Governed protocol runner (inventory → freeze → search → gate → ledger).
python scripts/run_equation_research_protocol.py --config configs/equation_research_protocol.yaml

# Compare the frozen baseline against a candidate runtime profile on real data.
python scripts/compare_runtime_equation_profiles.py --seed 3 --n 800 --out artifacts/runtime_equation_compare.json

Exit codes: 0 pipeline ok · 1 a hard gate failed after a completed run · 2 tool/config/input exception. The winner JSON records every objective metric, the constraint-detail booleans, and the selected parameters so a promotion is fully auditable.

Runtime equation profiles (opt-in serve path). The optimizer's frozen OAE surface is also exposed at inference through omni_mercury_engine.core.equation_profiles: OmniMercuryEngine(..., equation_profile="baseline_original_v1") (or a per-call detect_with_fusion(..., equation_profile=...) / score_fusion(..., equation_profile=...)) blends the calibrated neural probability with the golden-ratio R/H/O equation signal. None (the default) is an exact no-op, so the legacy serve/benchmark path is byte-for-byte unchanged; the blend metadata is surfaced under result["equation_profile"].

Three profiles ship: baseline_original_v1 and quiet_horizon_v1 are frozen (fixed 0.70/0.30 split), while phi_fibring_v1 harmonises the blend with Mercury's canonical fibring fusion (core/fibring_fusion.py) — a golden-ratio base split (φ/(1+φ) : 1/(1+φ) ≈ 0.618 : 0.382) plus correlation-aware decorrelation: when the equation signal is redundant with the neural score (|Pearson r| ≥ 0.85) the lower-variance stream is shrunk by 1/(1+|r|) and the weights renormalise, so a duplicated channel cannot double-count.

Tests: tests/tools/test_equation_optimizer.py (pipeline artifacts + CLI smoke), tests/core/test_equation_profiles.py (bounded/distinct profiles, None pass-through, unknown-profile rejection, channel→R/H/O mapping), tests/scripts/test_run_equation_research_protocol.py, tests/scripts/test_compare_runtime_equation_profiles.py.

Hardware Benchmark Harness

scripts/run_hardware_benchmark.py produces reproducible performance numbers for the validator pipeline, paired with the environment fingerprint that makes the result scientifically comparable. Full operating guide: docs/HARDWARE_HARNESS.md.

python scripts/run_hardware_benchmark.py \
    --config configs/lyapunov_canonical.yaml \
    --iters 2000 --warmup 200 \
    --out artifacts/hwbench.json

# Treat measured throughput as a regression gate:
python scripts/run_hardware_benchmark.py --min-ops-per-sec 1500

The JSON report contains the certificate result, the environment fingerprint (Python version, NumPy version, platform, CPU count, CPU affinity, scaling governor), and the timing block (mean / p50 / p95 / p99 / max / total). Throughput is reported as samples / total_s (which equals 1 / mean_s exactly when mean_s is the arithmetic mean of the same samples — statistics.fmean, in this harness — up to floating-point rounding). The harness emits both total_s and ops_per_sec so the assertable invariant ops_per_sec == samples / total_s can be checked directly by downstream tooling without re-deriving the mean; this also keeps the contract stable if the central-tendency estimator is ever swapped for a trimmed or median variant.

Documentation Drift Gate

scripts/check_readme_lyapunov.py blocks any pull request whose README.md or docs/MATH_SPEC.md documents a numeric λ that disagrees with the imported source-of-truth constants. The gate is plural: it carries a registry with one entry per canonical constant referenced in user-facing docs, currently λ_lyapunov = LyapunovConstants.LAMBDA_CONVERGENCE (the fusion-trajectory Lyapunov decay rate) and λ_decay = omni_mercury_engine.core.double_helix_engine.LAMBDA_DECAY (the double-helix evolutionary adaptation rate). Each check imports its canonical at call time (rather than parsing a YAML or constants file with a regex), matches every Greek / LaTeX / English prose form of its symbol, applies anchor-token context filtering so unrelated λs are ignored, and enforces a min_occurrences floor so silently deleting every documented mention cannot achieve a vacuous-green pass.

# Equivalent to the ISO Hardening / Workflow Hardening CI gate.
# Requires ``pip install -e .`` so the importer can resolve numpy
# (which double_helix_engine imports at module load).
python scripts/check_readme_lyapunov.py

This gate is the second mandatory checkpoint: changing LAMBDA_CONVERGENCE or LAMBDA_DECAY requires updating the canonical config, the documentation, and (for LAMBDA_CONVERGENCE) the reconciliation test in lock-step.


Testing and Quality Assurance

Note: Running the full test suite requires dev dependencies. Install with: pip install -e ".[dev]"

Test Suite

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run full test suite
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/omni_mercury_engine --cov-report=html

# Run property-based tests
pytest tests/test_property_based.py -v

# Run security scan
bandit -r src/ -f txt

Test Coverage

The test suite is characterized by its methods, not a headline count (a raw test tally measures volume, not rigor):

  • Property-based testing with Hypothesis for edge case discovery
  • Mutation testing: ten module sets are mutation-tested by full enumeration (scripts/run_sigma_mutation_gate.py), with kill-rate floors enforced in CI (.github/workflows/mutation-testing.yml) — a suite that stops catching injected defects fails the build
  • Security scanning with Bandit integrated in CI/CD
  • Coverage tracking: the merge gate enforces measured floors (CORE ≥ 33 %, FULL ≥ 62 %) on every PR; pyproject.toml [tool.coverage.report] fail_under = 85 is the long-term aspirational target. Coverage is regenerated per release via pytest --cov=src/omni_mercury_engine --cov-report=term; do not assert a percentage from this README — re-measure on the head of main.

Notable Test Suites (historical, v1.4.x → v1.6.x):

  • test_enhanced_anomaly_detection.py: 38+ tests for enhanced statistical methods, cross-platform hub, ensemble coordination
  • test_cortical_network.py: 40+ tests for 6-layer cortical architecture
  • test_statistical_real.py: 30+ tests for Z-score, IQR, adaptive detection
  • test_temporal_real.py: 26+ tests for time-series pattern detection
  • test_resilience_real.py: 27+ tests for circuit breaker state machine
  • test_enhanced_geological_detectors.py: 60+ tests for Landslide/Wildfire/Volcanic with 3R synapses
  • test_optimizers.py: 50+ tests for SyntheticGradient/DTP/AMAV integration
  • test_mercury_amacrypto.py: 60+ tests for AMA Cryptography PQC adapter and EWMA timing monitor

v1.7 development-cycle additions:

  • tests/security/test_native_jwt.py + tests/security/test_native_jwt_ama_routing.py: 50 tests pinning the native JWT module (HS256/HS384/HS512 byte-equivalence with stdlib, RFC 4231 KAT incl. SHA-384, AMA-routing vs stdlib cross-check, alg: none rejection).
  • tests/security/test_cve_2026_6357_regression.py: regression guard for the pip CVE-2026-6357 floor across every install path in CI.
  • tests/security/test_nist_fips_kat.py: NIST FIPS 203/204/205 ACVP-Server KAT vectors verified bit-for-bit (ML-DSA-65 deterministic sigGen, ML-KEM-1024 decapsulation, SLH-DSA-SHAKE-128s sigGen).
  • tests/tools/test_lyapunov_validator.py + tests/tools/test_lyapunov_reconciliation.py: pin the executable Lyapunov certificate against documentation drift and against LyapunovConstants.LAMBDA_CONVERGENCE.
  • tests/scripts/test_check_readme_lyapunov.py + tests/scripts/test_run_ablation.py + tests/scripts/test_run_hardware_benchmark.py: lock the ISO Hardening operator-tool surface (drift gate, ablation runner pre-gate, hardware harness throughput math).
  • tests/api/test_server_comprehensive.py::TestLifespanWarmup: 4 tests pinning the API warmup lifespan (wiring, success path, internal-failure propagation under the fail-fast contract, TestClient lifecycle).
  • tests/datasets/test_unreachable_loaders_{offline,network}.py: two-lane reachability harness for the 11 watch-listed datasets whose upstream sources are flaky or not currently fetchable (9 failed in the committed benchmark run; NOAA StormEvents and NOAA ERDDAP recovered).
  • tests/validation/test_synthetic_policy_gate.py: locks the MERCURY_ALLOW_SYNTHETIC policy gate across every loader that previously exposed a use_synthetic kwarg bypass.

Test Suite Stabilization (v1.6.0 Patch — historical):

  • Fixed 100+ test failures caused by missing FastAPI dependency, uninitialized federation attributes, and unreachable synthetic data thresholds
  • All fixes are minimal and targeted — no unnecessary refactoring

Ethics Scoring (test_ai_ethics.py):

The legacy heuristic ethics tests use keyword-presence scoring against stringified action parameters — for example, the compassion check awards a base 0.55 plus a +0.1 boost when create_backup appears in the serialised params. The production decision boundary is two hard gates — the fail-closed harm-uplift gate (check="harm_uplift"), then σ_Immutable (check="sigma_immutable"; check="gosnn_unavailable" when GOSNN cannot run) — at every gated detect surface, exercised by tests/ethical/test_hard_enforcement.py and tests/pillars/test_non_maleficence.py. Benevolence is computed and logged as an advisory score, deciding nothing; the keyword tests are retained for backward compatibility with the v1.x heuristic surface and should not be read as the operative ethics contract.

Continuous Integration

GitHub Actions enforce the following gates on every pull request and push to main/develop:

Workflow Job Blocking Description
ci.yml Code Quality yes black, flake8, ruff, mypy (strict), pydocstyle
ci.yml Workflow Hardening yes actionlint + zizmor + repository workflow invariants
ci.yml Type Checking yes mypy on src/ and graduated strict test directories
ci.yml Security Scan yes bandit, safety, pip-audit, semgrep against an isolated install
ci.yml Core Tests yes pytest, ≥ 33 % combined stmt+branch coverage on the curated core lane
ci.yml Neuro-Symbolic Tests yes 7-phase cognitive architecture + safeguards + ethics regression suite
ci.yml Integration Tests yes tests/integration/ against mocked external services
ci.yml Performance Benchmark PR-only TTLCache / synthetic-gradient regression gate
ci.yml Ethics Audit yes benchmarks/run_ethics_audit.py (EthicalAutonomyGovernor, σ_Immutable, OAE)
ci.yml ML Tests nightly/PR-to-main Full suite under tests/, ≥ 62 % coverage, real AMA Cryptography build
ci.yml Docker Build + Trivy yes Multi-stage runtime image, CRITICAL/HIGH = 0 beyond the enumerated, expiring .trivyignore ledger (ignore-unfixed: false)
ci.yml Docs Build yes Sphinx build of the narrative docs
iso-hardening.yml Docs λ Drift Gate yes scripts/check_readme_lyapunov.py -- canonical λ = 0.25 across docs
iso-hardening.yml Examples Parity yes examples/*.py must run end-to-end and emit known markers
iso-hardening.yml Load Tests yes k6 smoke + locust headless against the live API with FastAPI lifespan warmup + CI warmup loop, SLO p(95) < 500 ms on detection endpoints, p(99) < 150 ms on /health
iso-hardening.yml ISO Hardening Success yes Rollup of the three gates above (single required status check)
security.yml Container/SAST scan yes Trivy + Semgrep with deterministic SARIF categories
pqc-production-check.yml PQC Production Readiness yes KAT vectors, NIST FIPS ACVP-Server vectors, real AMA Cryptography build
benchmark.yml Live Benchmark scheduled Refreshes benchmarks/mercury_benchmark_results.json + README block
dataset-reachability.yml Loader Reachability nightly Offline lane + nightly network lane for the 11 watch-listed loaders
network-tests.yml External Source Probe nightly Diagnostic probe of upstream data providers
docker.yml Docker Release tag-driven Push runtime image with provenance attestation
format.yml Formatting check yes Drift guard for black / ruff format output
mutation-testing.yml Mutation Kill-Rate Floors path-filtered Full-enumeration mutation testing of ten module sets (σ hot path, hazard adapters, distillation, humanitarian, crisis monitor, geological, observatory, trust surface, hazard evidence, PPO trainer), plus a cheap sample on every PR
release.yml Tagged Release tag-driven sdist + wheel + SBOM + provenance
gate-watchdog.yml Gate Watchdog scheduled Detects required-gate runs that hang or get cancelled without superseding pushes; files an alert issue and auto-closes it once the gates run clean

The table above is the curated gate surface; the repository's full workflow count (including the scheduled benchmark/regression/mutation/reachability lanes) is measured in the CI-gated Codebase Scale block.

CI Matrix

  • Python Versions: 3.11, 3.12, 3.13, 3.14 (declared in pyproject.toml and exercised by ci.yml's code-quality / core-tests / type-checking matrix).
  • Platforms: Ubuntu Latest (Linux x86_64). macOS and Windows are supported as install targets but are not part of the CI matrix (see Cross-Platform Support).
  • Coverage floors: COVERAGE_THRESHOLD_CORE = 33 % on the curated core lane, COVERAGE_THRESHOLD_FULL = 62 % on the ML lane. The 85 % figure quoted under Code Quality Standards is the aspirational nightly target, not the merge gate; the floors above are the actual blocking thresholds and are documented in .github/workflows/ci.yml alongside the measured baseline that justifies them.
  • Required status checks: Code Quality, Workflow Hardening, Type Checking, Security Scan, Core Tests, Neuro-Symbolic Tests, Integration Tests, Performance Benchmark, CI Success (rollup), ISO Hardening Success (rollup), PQC Production Readiness.
Security Analysis
Layer Protection
Input Validation OWASP-compliant SQL/XSS/injection detection
Authentication Native stdlib JWT (security/native_jwt.py) with constant-time HMAC verification; alg: none rejected by construction; HS256/HS384/HS512 route through AMA Cryptography v5.0.0's native HMAC (ACVP-Server known-answer vectors pass bit-for-bit), fail-closed
Post-Quantum Cryptography ML-DSA-65 (FIPS 204 §5.2), ML-KEM-1024 / Kyber-1024 (FIPS 203), SLH-DSA-SHAKE-128s + legacy SPHINCS+-SHA2-256f-simple (FIPS 205); sole backend = AMA Cryptography v5.0.0 (unconditionally hard-required at import — fail-closed, no env-var escape hatch)
Classical Cryptography AES-256-GCM, ChaCha20-Poly1305, BLAKE3, Argon2id via Rust + PyO3 (rust_crypto/); constant-time comparisons
Rate Limiting Token bucket algorithm with configurable limits (100 req/min, 20 burst by default)
Secret Detection detect-secrets in pre-commit hooks
PII Masking Automatic redaction in logs (email, phone, SSN, card, IP, Bearer tokens, generic secret-key patterns)

See SECURITY.md for complete security analysis.

Code Quality Standards
Tool Standard
black PEP 8 formatting
isort Import sorting
flake8 Linting (max-line-length=100)
mypy Static type checking
ruff Fast Python linting
bandit Security-focused static analysis
# Format code
black src/ tests/

# Lint
flake8 src/ tests/
ruff check src/ tests/

# Type checking
mypy src/

Documentation

User Documentation
Document Description
README.md Quick start and overview
ARCHITECTURE.md System architecture and design
SECURITY.md Security policy and vulnerability reporting
Technical Documentation
Document Description
ARCHITECTURE.md Detailed system architecture
docs/API_REFERENCE.md Python API quick reference (detector ensemble, compliance, medical, drone, profiling)
docs/BENCHMARKS.md Benchmark methodology and results
docs/HARDWARE_HARNESS.md Reproducible hardware-benchmark methodology and environment fingerprint schema
docs/HARM_POLICY.md Two-axis (hazard domain × operational intent) harm-uplift gate: what is refused, what is permitted, and why
docs/MATH_SPEC.md Mathematical foundations specification (including Lyapunov certificate proof)
docs/ORACLE_NOISE_COLOR.md Oracle noise color calibration theory
docs/NEUROSYMBOLIC.md Neuro-symbolic co-training accounting, ablation, and keep/quarantine verdicts
docs/ROUTING_GUIDE.md Request routing and fallback chains
docs/SELF_IMPROVEMENT_LOOP.md Governed self-improvement rollout gated on label-provenance-clean loaders
docs/DEPLOYMENT.md Deployment reference for the served API
docs/GCN_KAFKA_MCP.md NASA GCN Kafka credential keep-alive that stops the 30-day inactivity expiry, and why no Kafka MCP server is configured
docs/PLATFORM_HARDENING.md Free-service account/auth/quota platform: threat model, security controls, configuration, deployment, migration, and acceptance checklist
docs/DOMAIN_EMAIL_HOSTING_SETUP.md Public-deployment ground truth: DNS, mailbox, DKIM/DMARC, and measured hosting sizing
docs/ROADMAP.md Feature roadmap and planned work
Developer Documentation
Document Description
CONTRIBUTING.md Contribution guidelines
CHANGELOG.md Version history
DEPRECATION.md Deprecation notices
docs/INSTALLATION.md Installation and setup guide
docs/DATASOURCES.md Data source catalog and APIs

Cross-Platform Support

Platform Compatibility Matrix
Platform Status Notes
Linux (Ubuntu 22.04+) Supported, CI-tested Primary development platform; the only platform in the CI matrix
macOS (13+), Apple silicon Supported install target In uv.lock; not in the CI matrix
macOS, Intel (x86_64) Core package only PyTorch publishes no Intel-macOS wheel from 2.3 on (2.2.2 was the last) and numba none from 0.63, so the torch-bearing extras ([ml], [api], [all], ...) cannot install there; uv.lock therefore excludes the platform ([tool.uv] environments). pip install -e . still works
Windows (10/11) Supported install target WSL2 recommended; not in the CI matrix
Docker Supported, CI-tested Multi-stage build (python:3.14-slim-trixie), Trivy-gated
Kubernetes Supported install target Helm chart and overlays included as reference configurations

Build System

Python Package
# Build sdist and wheel
python -m build

# Install in development mode
pip install -e ".[dev]"

Environment Variables (read by api/server.py / api/auth.py / _env.py):

  • JWT_SECRET_KEY - Shared JWT signing key (unset in production, JWTAuth derives the key via AMA HD Key Management — deterministic fleet-wide with AMA_MASTER_SEED set, per-process with a logged warning otherwise)
  • AMA_MASTER_SEED - Hex AMA HD master seed (openssl rand -hex 64) for deterministic fleet-wide key derivation
  • MERCURY_CACHE_SECRET - Shared HMAC secret enabling signed Redis cache entries (RedisCache)
  • OMNI_RATE_LIMIT_ENABLED - Enable rate limiting (default true)
  • OMNI_RATE_LIMIT_REQUESTS_PER_MINUTE / OMNI_RATE_LIMIT_BURST - Rate-limit budget (defaults 100 / 20)
  • OMNI_MAX_DATA_POINTS / OMNI_MAX_FEATURES / OMNI_MAX_STRING_LENGTH / OMNI_MAX_NAN_RATIO / OMNI_MAX_INF_RATIO / OMNI_STRICT_VALIDATION - Input-validation limits
  • MERCURY_ENV - Environment mode (development default, production)
  • MERCURY_CORS_ORIGINS - Explicit CORS origin allow-list
  • MERCURY_FRONTEND_ENABLED / MERCURY_KEYSTORE_PATH / MERCURY_QUOTA_* - Self-service account platform (full reference: docs/PLATFORM_HARDENING.md)
  • MERCURY_DATA_ENC_KEY / MERCURY_PROVIDER_STORE_PATH - At-rest key and the provider store for language-model keys connected from the console
  • MERCURY_AGENT_MEMORY_PATH / MERCURY_LOG_LEVEL / MERCURY_LOG_FORMAT - Durable agent memory; engine log level and format
Implementation Languages — what "multi-language" means here

Mercury is multi-language in the implementation sense — the term refers to the programming languages the system is built in, not to multilingual natural language:

Language Where Role
Python (3.11–3.14) src/omni_mercury_engine/ Core engine, detectors, fusion, API, ML pipeline — the primary language.
Rust rust_crypto/ (PyO3) Optional, opt-in classical-crypto acceleration (AES-256-GCM, ChaCha20-Poly1305, BLAKE3, Argon2id). Absent → explicit, tested Python fallback.
C / C++ AMA Cryptography native PQC backend (.github/actions/build-ama-cryptography, cmake + g++) Compiled native post-quantum backend; fails closed when unavailable rather than silently weakening.

Natural language is a separate axis, and its scope is stated exactly. Mercury's grounded answers are built in English from the detection record, the code and the narrative engine. In front of them, narrative/languages.py understands a question in seven languages (English, Spanish, French, German, Italian, Portuguese, Dutch): it detects the asker's language from function words and spellings, renders the question in the English phrasing the conversation layer routes, and answers the social turns, the fallback menu and the follow-up prompts in that language. POST /api/v1/voice/speak takes language (one of the seven codes or auto; any other code is refused with a 422), and the console has an agent-language setting. What is not shipped: a detection narrative or a knowledge profile is never machine translated, so a non-English asker gets that answer in English with a one-line note in their language saying how the question was understood. The layer is lexicon and regular expressions: no translation model, no network call. Full localized narration, number and date formatting, and a per-language evaluation set remain a future epic (docs/ROADMAP.md row 18).

Docker
# Build runtime image (default target)
docker build -t mercury-agent:latest .

# Build only the builder stage (for CI caching)
docker build --target builder -t mercury-agent:builder .

Docker Stages:

  • builder: Build environment with compilation dependencies
  • runtime (default): Minimal, security-hardened runtime image
Kubernetes
  • Helm Charts: helm/mercury-agent/
  • Base Manifests: k8s/base/
  • Environment Overlays: k8s/overlays/{development,staging,production,distributed}/
# Deploy to Kubernetes
helm install mercury-agent ./helm/mercury-agent -f values.yaml

Note: The Kubernetes, Helm, and monitoring configurations in k8s/, helm/, and monitoring/ are reference configurations for those who wish to deploy Mercury Agent in containerized environments. Mercury Agent is research-grade, community-tested software that has not been externally audited for production hardening. Review and adapt these configurations to your security requirements before deploying.


Mathematical Foundations

Evolution Equation

The double-helix evolution engine follows:

dS/dt = sum_i w_i * term_i(S) - LAMBDA_DECAY * (S - S*)

Where:

  • S is the system state
  • w_i are term weights (18 terms)
  • LAMBDA_DECAY = 0.18 is the double-helix adaptation rate (defined in src/omni_mercury_engine/core/double_helix_engine.py); it controls how quickly the evolutionary state pulls back toward S* and is intentionally slower than the Lyapunov convergence rate LAMBDA_CONVERGENCE = 0.25 so that fusion-trajectory stabilisation outruns adaptation. The two constants are distinct by design — do not collapse them into a single "λ" in prose.
  • S* is the equilibrium state

Note: Previously labeled "quantum" terms are classical algorithms (simulated annealing, Boltzmann sampling, Hamiltonian projection).

Ethical Constraints
  • Lyapunov Stability: For the fusion-trajectory Lyapunov candidate V(state) = ||state - target||^2, the certified bound is V(t) ≤ e^{-λ t} with λ = 0.25 (see docs/MATH_SPEC.md §2.2 for the proof and configs/lyapunov_canonical.yaml for the executable certificate consumed by tools/lyapunov_validator.py).
  • σ_Immutable Constraint: the second mandatory hard gate at every detect / analyze / predict surface. The enforcement boundary runs the trained 256-D scalar network in omni_mercury_engine.security.sigma_immutable_gate with decision threshold 0.93 (SIGMA_IMMUTABLE_DEFAULT_THRESHOLD, plus the deterministic per-anchor CRITICAL_ETHICAL_FLOOR at the same value); the GOSNN quadratic-form gating layer uses a 0.96 default (0.93 medical fallback, SIGMA_IMMUTABLE_THRESHOLD env-overridable, clamped to [0.93, 0.99]) — see core.global_omni_scalar_network.
  • Bias Detection: Fairlearn demographic parity, equalized odds, 80% rule.
Fusion Architecture
  • Feature Fusion: torch.cat() across detector outputs
  • Decision Fusion: Weighted voting with learned importance
  • Attention Fusion: Multi-head attention (4 heads)
  • Final Score: 0.7 * MLP + 0.3 * weighted_vote
Anomaly Math Arrest (21-Probe Ensemble)

A mathematically-independent equation ensemble providing transparent, auditable anomaly detection. Each of the 21 probes detects a different anomaly geometry using fundamentally different mathematical frameworks:

  1. AdditiveProbe — Linear trend / level shifts
  2. HarmonicOscillatorProbe — Periodicity violations (damped oscillator)
  3. MomentumProbe — Sudden acceleration (second differences)
  4. VarianceAdaptedProbe — Volatility anomalies (rolling variance)
  5. EthicalConstrainedProbe — Boundary violations (percentile envelopes)
  6. CatalanOptimizedProbe — Autocorrelation breaks (Catalan-constant AR(1))
  7. ExponentialDecayProbe — Signal degradation (optimal-lambda EWMA)
  8. HelixMultiplicativeProbe — Multiplicative shocks (log-ratio analysis)
  9. R3RecursionResonanceProbe — Nonlinear saturation
  10. SVDProjectionProbe — Dimensional collapse (Hankel SVD)
  11. LyapunovChaosProbe — Chaos onset (trajectory divergence)
  12. TopologyHomologyProbe — Symmetry breaks (central differences)
  13. FractalSelfSimilarityProbe — Scale-invariance loss
  14. ZetaHarmonicProbe — Phase coherence anomalies
  15. WavePropagationProbe — Wave equation violations (smoothed Laplacian)
  16. QuantumSuperpositionProbe — Interference pattern breaks
  17. EnergyMinimizationProbe — Energy well escapes
  18. QuantumAnnealingProbe — Thermodynamic outliers (Boltzmann NLL)
  19. BoltzmannCouplingProbe — Coupling structure breaks
  20. IQRRobustProbe — Distribution tail anomalies (Tukey fences)
  21. ModifiedZScoreProbe — Robust location anomalies (MAD-based)

Fusion: Scores are combined via Phi-weighted (golden ratio) fusion with confidence modulation and correlation-aware decorrelation. Domain affinity maps reorder probe weights for earthquake, tsunami, pandemic, marine, geomagnetic, and conflict domains.


Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup
# Clone repository
git clone https://github.com/Steel-SecAdv-LLC/Mercury-Agent.git
cd Mercury-Agent

# Install development dependencies
pip install -e ".[dev]"

# Setup pre-commit hooks
pre-commit install

# Format code
black src/ tests/

# Lint code
flake8 src/ tests/
ruff check src/ tests/

# Run security audit
bandit -r src/
Code Quality Standards
Language Standards
Python PEP 8, type hints, docstrings
Security OWASP validation, no hardcoded secrets
Testing CI floors: CORE ≥ 33 %, FULL ≥ 62 % (measured); aspirational target 85 % ([tool.coverage.report] fail_under = 85)
Ethics Fairlearn bias auditing on all ML models

Unique Features

Federated Learning - Privacy-Preserving Distributed Detection

Nodes train locally and exchange only sufficient statistics (13 fitted attributes), never raw data.

from omni_mercury_engine.federation import FederatedNode, FederatedAggregator

# Each node trains on local data
node = FederatedNode("hospital_A")
node.fit(local_patient_data)
stats = node.export_statistics(epsilon=1.0)  # with differential privacy

# Aggregator combines statistics from multiple nodes
aggregator = FederatedAggregator(min_nodes=2)
aggregator.submit(stats_a)
aggregator.submit(stats_b)
global_detector = aggregator.to_detector(aggregator.aggregate())

# Global detector is ready for inference
result = global_detector.detect(new_data)

Key properties:

  • No external FL frameworks (Flower, PySyft, etc.) — uses Mercury's native math
  • Gaussian-mechanism differential privacy with clipping-norm-based sensitivity
  • Mathematically exact aggregation for means (MLE) and stds (parallel variance formula)
  • Precision-weighted averaging for Fisher information geometry
  • Oracle state round-trip serialization via get_oracle_statistics() / from_statistics()
  • 15 tests covering correctness, privacy, serialization, and dimension validation (tests/test_federation.py)
Ethical AI Governance - Mathematically-Bound Fairness Constraints

Mercury Agent integrates ethical principles directly into ML operations through mathematically rigorous constraints. Unlike traditional ML systems that treat ethics as policy overlays, Mercury Agent embeds ethical considerations into the detection foundation itself.

Fairlearn Integration provides bias detection across all predictions:

Metric Description Threshold
Demographic Parity Equal positive rates across groups Ratio >= 0.8
Equalized Odds Equal TPR/FPR across groups Difference <= 0.1
80% Rule Adverse impact ratio Ratio >= 0.8

180+ Ethical Scalars govern system behavior:

  • Compassion, empathy, care constraints
  • Evidence, truth, verification requirements
  • Justice, fairness, accountability bounds
  • Altruism, service, protection priorities
Production Security - Defense-in-Depth Architecture

Mercury Agent employs a comprehensive security architecture designed for production deployment:

Input Validation (OWASP-compliant):

  • SQL injection detection and prevention
  • XSS attack pattern matching
  • Command injection blocking
  • Path traversal prevention

Authentication & Authorization:

  • JWT tokens with proper expiration
  • Signature verification
  • Rate limiting (token bucket algorithm)

Post-Quantum Cryptography (AMA Cryptography v5.0.0):

What the AMA dependency is, and is not. AMA Cryptography is Mercury's trust substrate — the thing Mercury's own guarantees rest on — not a mission or a marketing claim. Stated exactly:

  • It implements NIST FIPS 203 (ML-KEM), FIPS 204 (ML-DSA) and FIPS 205 (SLH-DSA), and passes the ACVP-Server known-answer-test vectors bit-for-bit in CI (tests/security/test_nist_fips_kat.py).
  • It has been internally reviewed (AI-assisted). It is not CAVP- or CMVP-validated, and it has not been independently audited.
  • Constant-time behaviour is asserted by the implementation; it has not been independently verified.

Passing the published test vectors is evidence the algorithms are implemented correctly. It is not certification, and the two are not interchangeable: "FIPS-certified" and "NIST-validated" are claims about a formal validation programme Mercury has not entered, and neither phrase may appear anywhere else in this repository (scripts/doc_lint.py fails CI on them).

  • Kyber-1024 / ML-KEM-1024 key encapsulation (NIST Level 5, exposed as KyberKeyPair(algorithm="Kyber1024") in src/omni_mercury_engine/security/pqc_backends.py).
  • ML-DSA-65 lattice signatures (FIPS 204 name for the Dilithium-3 parameter set; supports the §5.2 context-aware sign API from AMA v3.1.0+).
  • SPHINCS+-SHA2-256f-simple hash-based signatures plus the FIPS 205 SLH-DSA parameter family.
  • Unconditionally hard-required at import time (fail-closed): there is no classical RSA / ECDSA fallback in pqc_backends.py, and no env-var escape hatch. src/omni_mercury_engine/_pqc_gate.py refuses to import the package unless all three AMA algorithms (ML-DSA-65, Kyber-1024, SPHINCS+) load from the native C backend. The AMA_REQUIRE_REAL_PQC / legacy AVA_REQUIRE_REAL_PQC env vars are retained only as no-op compatibility diagnostics; setting them true, false, or leaving them unset does not change the gate (pinned by tests/test_pqc_startup_gate.py). There is no degraded/warning posture — a missing or partial AMA build raises RuntimeError at import.

Rust Cryptographic Module (rust_crypto/) — optional, opt-in acceleration:

  • AES-256-GCM and ChaCha20-Poly1305 AEAD encryption, BLAKE3 hashing, Argon2id key derivation, constant-time comparisons (timing-attack resistant).
  • Not built or packaged by default. The root package builds with setuptools and does not compile the Rust extension; mercury_crypto is absent from a standard install. To enable it, build the PyO3 module explicitly: cd rust_crypto && maturin develop.
  • Explicit Python fallback. When the Rust extension is absent, omni_mercury_engine.crypto transparently falls back to the cryptography package / hashlib (and the blake3 wheel if present), logging the choice at import. crypto.get_crypto_backend() reports the active backend ("rust" / "python-cryptography" / "hashlib-only") and crypto.is_rust_available() is the boolean probe.
  • Speedup is measured, not asserted. Run python -m benchmarks.crypto_backend_benchmark to measure Rust-vs-Python on your hardware; it writes artifacts/crypto_backend_benchmark.json with the active backend, per-primitive timings, and the observed speedup (or records that Rust is unavailable, so no figure is fabricated).
Multi-Domain Detection - 30 Specialized Engines

Mercury Agent provides specialized detection engines across multiple domains:

Domain Engines Capabilities
Medical 4 Sepsis, cardiology, neurocritical, pandemic
Security 4 Threat, intelligence, cyber, traffic
Space 4 Solar flare (Kp/NOAA G-scale physics), Schumann, cosmic ray, meteor (Bayesian)
Infrastructure 4 CISA, crisis, climate, economic
Environmental 6 Tsunami (FFT), earthquake (P/S-wave), landslide (SVM/RF), wildfire (CNN/NDVI), volcanic (HMM), disaster
Statistical 8 MAD, LOF, DBSCAN, MCD, Grubbs, CUSUM, GESD, Dynamic Threshold

Enhanced Geological Detectors:

  • Landslide: SVM/RF classifiers with temporal lags, 3R Recursion synapse for multi-scale analysis
  • Wildfire: CNN with NDVI satellite processing, 3R Resonance synapse for smoke pattern detection
  • Volcanic: HMM state transitions (quiescent→unrest→eruption), 3R Refactoring synapse for adaptive θ

All engines share a common fusion architecture with 128D normalization enabling cross-domain correlation and unified anomaly scoring.

GOSNN Global Omni-Scalar Network - Synaptic Intelligence Hub

The GlobalOmniScalarNetwork (GOSNN) is the intelligence fusion hub. It registers ~209 omni-scalars across 8 major categories; 127 of them are operational and drive the σ_Immutable gate, while the remaining 82 are diagnostic measurement scalars (descriptions of code / system under analysis) registered for discoverability and reporting but filtered out of the gate's input vector by GlobalOmniScalarNetwork._is_metric_only_scalar.

Scalar Categories (~209 registered / 127 operational):

  • ETHICAL (~27): Core ethical values and Civilization-First principles (all operational)
  • COSMIC (~7): Universe-scale harmony and telos alignment (all operational)
  • QUANTUM_CONSCIOUSNESS (~7): Quantum-inspired processing (all operational)
  • HUMANITARIAN (~9): Crisis response and human welfare (all operational)
  • SECURITY (~6): Threat detection and cyber defense (all operational)
  • SOFTWARE_ENGINEERING (~127 = 45 operational + 82 diagnostic): Code quality, optimization, 3R synergy (operational); plus ISO/IEC 25010 product quality, Halstead, McCabe + cognitive (SonarQube), Maintainability Index variants, NIST SAMATE assurance, DORA delivery, SLSA supply-chain, OpenSSF Scorecard, ISO/IEC 5055 (CISQ), NIST SSDF (SP 800-218) practices (diagnostic measurement)
  • MEDICAL (~10): Healthcare and diagnostic support (all operational)
  • ADVANCED_REASONING (~16): Logic, inference, knowledge synthesis (all operational)

Key Features:

  • Hard Ethical Gate (Wave B): σ_Immutable is the second mandatory hard gate at every public detect / analyze / predict surface, running after the fail-closed harm-uplift gate. A score below threshold raises EthicalConstraintViolationError(check="sigma_immutable"); if GOSNN itself cannot run, the boundary raises EthicalConstraintViolationError(check="gosnn_unavailable"). There is no advisory mode and no public flag that disables either gate (test-only bypass requires the auditable module-level omni_mercury_engine.engine._GOSNN_TESTING_BYPASS flag).
  • 32-Head Triadic φ-Weighting: Multi-head attention with golden ratio optimization
  • Harmonic Synergy: Bidirectional synapse connections to 3R mechanism
  • Single source of truth for σ layout: SIGMA_IMMUTABLE_DIM=256, SIGMA_ETHICAL_BAND_END=27, SIGMA_USED_BAND_END=180 exported from omni_mercury_engine.security.sigma_immutable_gate.

Bidirectional Synapses:

  • Detectors → GOSNN ethical gate ↔ 3R adaptive O(θ)
  • Enhanced detectors register scalars with omni_ prefix
  • No silent GOSNN fallback: a GOSNN failure now raises check="gosnn_unavailable" and aborts the call (Wave B fail-closed contract). The previous gosnn_metadata.fallback_mode=True path has been removed.

AMA Cryptography Integration - Post-Quantum Cryptography Adapter

The AMA Cryptography adapter provides post-quantum cryptographic security with GOSNN synapse integration:

PQC Algorithms (sourced from AMA Cryptography v5.0.0):

  • ML-KEM-1024 / Kyber-1024: Post-quantum key encapsulation, FIPS 203, NIST Level 5
  • ML-DSA-65 (Dilithium-3): Post-quantum digital signatures, FIPS 204 §5.2 (context-aware deterministic signing), NIST Level 3 (≈ 192-bit classical security strength)
  • SLH-DSA-SHAKE-128s / SHA2-256f: Hash-based digital signatures, FIPS 205, NIST Level 1 / Level 5 respectively
  • SPHINCS+-SHA2-256f-simple: Legacy pre-FIPS-205 hash-based signatures, retained for backward compatibility
  • EWMA/MAD Timing Monitor: crypto-operation anomaly detection (<2% overhead is the design target; no committed measurement)

Correctness evidence (in-repo, measured-and-published):

  • Known-Answer Tests: tests/security/test_ama_kat.py pins Ed25519 RFC 8032 §7.1 vectors bit-for-bit, ML-DSA-65 round-trip, Kyber-1024 encaps/decaps round-trip, SPHINCS+ round-trip, and ML-DSA deterministic-signing reproducibility. Runs on every PR via the PQC Production Readiness workflow.
  • NIST FIPS KAT vectors: tests/security/test_nist_fips_kat.py verifies bit-for-bit reproducibility against curated NIST ACVP-Server test vectors (FIPS 203/204/205): ML-DSA-65 deterministic sigGen, ML-KEM-1024 decapsulation, SLH-DSA-SHAKE-128s sigGen. Source: usnistgov/ACVP-Server.
  • Measured coverage: the PQC Production Readiness CI workflow publishes pytest-cov coverage for security/crypto_api.py + security/pqc_backends.py + security/pqc_guards.py as a CI artifact (pqc-coverage). Without the AMA native C library: crypto_api.py 62%, pqc_backends.py 43%, pqc_guards.py 24% (from a CI-run coverage artifact that expires; the repo itself holds no copy, so verify against a fresh CI run before citing). With AMA native lib installed (CI verify-real-pqc job): all PQC codepaths are exercised, raising coverage to its measured ceiling. Published, not "unaudited" framing.

Security Features:

  • Attack simulation (timing, replay, side_channel)
  • Crypto anomaly recording with severity classification
  • GOSNN synapse for security detector integration
  • Unconditional fail-closed enforcement — Mercury Agent refuses to import at all (RuntimeError from _pqc_gate.py) when AMA Cryptography's native C library is not built, regardless of any env var. The AMA_REQUIRE_REAL_PQC / back-compat AVA_REQUIRE_REAL_PQC vars are retained only as no-op compatibility diagnostics — there is no degraded "dev mode" and the gate cannot be disabled. PQCProductionWarning remains a public exception type in security.pqc_guards for downstream integrators to catch, but the fail-closed gate never emits it (the package simply does not import without real AMA).

Integration:

from omni_mercury_engine.integrations.mercury_amacrypto import create_ama_cryptography_adapter

adapter = create_ama_cryptography_adapter(gosnn_synapse_enabled=True)
if adapter.is_available():
    keypair = adapter.generate_dilithium_keypair()  # cached on the adapter
    # ``private_key=None`` uses the cached secret_key from above; pass an
    # explicit ``private_key=keypair.secret_key`` if you manage your own
    # key lifecycle.
    signature = adapter.sign_dilithium(message)

The lower-level functional surface (no GOSNN coupling, no timing monitor) lives in omni_mercury_engine.security.pqc_backends: generate_dilithium_keypair, dilithium_sign, dilithium_verify, generate_kyber_keypair, kyber_encapsulate, kyber_decapsulate, generate_sphincs_keypair, sphincs_sign, sphincs_verify, and the FIPS 205 parameter-driven slhdsa_* family. Use the adapter for operator workflows; use the functional surface for one-shot cryptography in tests, scripts, and library code.

Omni-Codes - Bio-Inspired Helical Parameters

Mercury Agent integrates the Omni-Codes from AMA Cryptography, providing bio-inspired helical parameters for ethical AI alignment and system stability.

The Seven Omni-Codes:

Code Symbol Domain Helical Parameters
👁20A07∞_XΔEΛX_ϵ19A89Ϙ 👁∞ Omni-Directional System r=20.0, p=0.7
Ϙ16A11ϵ_ΞΛMΔΞ_ϖ20A19Φ Ϙϵ Omni-Percipient Future r=16.0, p=1.1
Φ07A09ϖ_ΨΔAΛΨ_ϵ19A88Σ Φϖ Omni-Indivisible Guardian r=7.0, p=0.9
Σ19L12ϵ_ΞΛEΔΞ_ϖ19A92Ω Σϵ Omni-Benevolent Stone r=19.0, p=1.2
Ω20V11ϖ_ΨΔSΛΨ_ϵ20A15Θ Ωϖ Omni-Scient Curiosity r=20.0, p=1.1
Θ25M01ϵ_ΞΛLΔΞ_ϖ19A91Γ Θϵ Omni-Universal Discipline r=25.0, p=0.1
Γ19L11ϖ_XΔHΛX_∞19A84♰ Γϖ Omni-Potent Lifeforce r=19.0, p=1.1

Architectural Benefits:

  • Helical data encoding: Mirrors DNA double-helix stability for robust data structures
  • Self-healing capabilities: CRISPR-inspired adaptations for system resilience
  • Evolutionary adaptability: Dynamic parameter tuning based on stability calculations
  • Canonical hashing: Cryptographic integrity through structured encoding

Stability Calculation:

from omni_mercury_engine.utils.constants import OmniCodes, compute_ethical_autonomy

# Get total stability across all codes
total_stability = OmniCodes.get_total_stability()  # ~106.1

# Compute autonomy bounded by ethical constraints
autonomy = compute_ethical_autonomy(
    base_autonomy=0.8,
    ethical_threshold=0.99,
    use_omni_codes=True
)  # Returns up to 0.95
Advanced Optimizers - Synthetic-Gradient, DTP & AMAV Training

The OmniFusionModel now supports advanced optimizers for accelerated training:

Optimizer Types:

  • SyntheticGradient: Decoupled layer updates enabling layer-wise parallelism
  • DifferenceTargetPropagation (DTP): Biologically plausible learning
  • AuxiliaryMaxVariance (AMAV): Multi-task loss with variance maximization

Training Integration (omni_mercury_engine.ml.OmniFusionModel.train_with_optimizers):

model = OmniFusionModel(hidden_dim=128, num_heads=4)
stats = model.train_with_optimizers(
    train_loader=train_loader,
    epochs=300,
    learning_rate=0.001,
    lambda_lyapunov=0.25,
    use_synthetic_gradients=True,  # decoupled-layer speedup
    use_dtp=True,                  # difference target propagation
    use_amav=True,                 # auxiliary max-variance loss
)

Convergence Metrics:

  • Lyapunov stability tracking (λ=0.25)
  • Speedup factor estimation
  • Loss convergence monitoring
Enhanced Statistical Detection - 8 Robust Statistical Methods

The Enhanced Statistical Detection module provides 8 advanced statistical anomaly detection methods for robust, interpretable detection:

Methods:

Method Description Key Strength
MAD Median Absolute Deviation 50% breakdown point, robust to outliers
LOF Local Outlier Factor Density-based detection for local anomalies
DBSCAN Density-Based Clustering Cluster-based anomaly identification
MCD Minimum Covariance Determinant Robust covariance estimation
Grubbs Grubbs' Outlier Test Statistical significance testing
CUSUM Cumulative Sum Control Chart Sequential change detection
GESD Generalized ESD Test Multiple outlier detection
Dynamic Dynamic Threshold Adaptation Adaptive thresholding with EMA

Usage:

from omni_mercury_engine.detectors.statistical_extended import (
    MADDetector, LOFDetector, ExtendedStatisticalDetector
)

# Single method
mad = MADDetector(threshold_multiplier=3.5)
mad.fit(data)
result = mad.detect(data)

# Ensemble of methods
detector = ExtendedStatisticalDetector(
    methods=["mad", "lof", "dbscan"],
    fusion_strategy="weighted_average"
)
Cross-Platform Integration Hub - Multi-Platform Orchestration

The Cross-Platform Hub provides unified integration with external monitoring and observability platforms:

Supported Platforms:

Platform Protocol Data Format
Prometheus REST Prometheus/OpenMetrics
Elastic/OpenSearch REST JSON
Splunk REST JSON
Datadog REST JSON
Azure Anomaly Detector REST JSON
Netdata REST/WebSocket JSON
Grafana REST JSON
InfluxDB REST JSON

Protocol Support: REST, gRPC, WebSocket, MQTT, Kafka, Redis Streams

Data Formats: JSON, Prometheus, OpenTelemetry, CSV, MessagePack, Avro, Parquet

Usage:

from omni_mercury_engine.integrations.cross_platform_hub import (
    CrossPlatformHub, PlatformConfig, PlatformType
)

hub = CrossPlatformHub()
hub.register_platform("soc-splunk", PlatformConfig(
    platform_type=PlatformType.SPLUNK,       # HEC /services/collector/event
    name="soc-splunk",
    endpoint="https://splunk.example.org:8088",
    auth_type="api_key",                      # sent as "Authorization: Splunk <token>"
    credentials={"api_key": hec_token},
))
await hub.publish_detection_result(detector.detect(batch), source="security:ids")
groups = hub.get_correlated_events(time_window_seconds=300, min_correlation=0.8)

Each platform is spoken natively (Splunk HEC, Datadog /api/v1/series, Elastic/OpenSearch _doc/_bulk, a merged Prometheus push, OTLP). The API server forwards every anomalous detection automatically when MERCURY_ALERT_SINKS is set, TLP-gated per sink (see docs/DEPLOYMENT.md).

Ensemble Coordination - Advanced Ensemble Fusion

The Ensemble Coordinator provides sophisticated strategies for combining multiple detectors:

Ensemble Strategies:

Strategy Description Best For
Voting Majority/weighted voting High precision requirements
Averaging Score averaging Balanced precision/recall
Stacking Meta-learner on top Complex data patterns
Cascading Sequential filtering (fast→accurate) High-throughput scenarios
Boosting Boosting-style combination Improving weak detectors
Mixture of Experts Gated expert selection Domain-specific detection
Adaptive Dynamic strategy selection Varying data characteristics

Advanced Features:

  • Bayesian Weight Optimization - Thompson Sampling for detector weights
  • Gradient Weight Optimizer - Momentum-based gradient descent
  • Meta-Learner - Automatic detector selection based on data characteristics
  • Online Feedback Learning - Continuous improvement from user feedback

Usage:

from omni_mercury_engine.ml.ensemble_coordinator import (
    EnsembleCoordinator, EnsembleStrategy
)

coordinator = EnsembleCoordinator(
    strategy=EnsembleStrategy.CASCADING,
    enable_online_learning=True
)
coordinator.register_detector("fast_statistical", statistical_detector)
coordinator.register_detector("accurate_neural", neural_detector)
result = coordinator.detect(data)
Distributed Processing - Scalable Parallel Detection

The Distributed Processor enables large-scale anomaly detection with parallel processing:

Processing Strategies:

Strategy Use Case Parallelism
Sequential Small datasets None
Threaded I/O-bound tasks Threads
Multiprocess CPU-bound tasks Processes
Async Network operations Coroutines
Hybrid Mixed workloads Threads + Processes

Load Balancing: Round-robin, Least-loaded, Weighted, Adaptive

Features:

  • ChunkGenerator - Memory-efficient data iteration
  • Fault Tolerance - Automatic retry with exponential backoff
  • Progress Tracking - Real-time monitoring
  • Backpressure Control - Prevents memory exhaustion

Usage:

from omni_mercury_engine.scaling.distributed_processor import (
    DistributedProcessor, ProcessingConfig, ProcessingStrategy
)

processor = DistributedProcessor(
    detector=my_detector,
    config=ProcessingConfig(
        strategy=ProcessingStrategy.HYBRID,
        num_workers=8,
        chunk_size=1000
    )
)
results = processor.process(large_dataset)
Visualization Dashboard - Interactive Plotly Dashboards

The Visualization Dashboard provides interactive visualizations for anomaly analysis:

Chart Types:

Chart Purpose
Time Series Anomaly scores over time with threshold lines
Feature Importance Bar chart of feature contributions
Correlation Heatmap Feature correlation matrix
3D Scatter Multi-dimensional anomaly visualization
Radar Chart Multi-detector comparison
Anomaly Timeline Event-based anomaly view
Distribution Histogram Score distribution with anomaly overlay
Detector Comparison Side-by-side detector performance

Export Formats: HTML (interactive), PNG, JSON

Usage:

from omni_mercury_engine.gui.visualization_dashboard import (
    AnomalyVisualizer, DashboardBuilder
)

visualizer = AnomalyVisualizer(theme="plotly_dark")
fig = visualizer.time_series_plot(timestamps, scores, threshold=0.5)

# Build multi-panel dashboard
dashboard = DashboardBuilder()
dashboard.add_chart("time_series", timestamps, scores)
dashboard.add_chart("heatmap", correlation_matrix)
dashboard.export_html("anomaly_report.html")

License

Copyright 2025 Steel Security Advisors LLC

Licensed under the GNU Affero General Public License v3.0 or later (SPDX: AGPL-3.0-or-later). See LICENSE file for details. Versions before 3.0.0 were released under GPL-3.0-or-later and remain so. One additional permission, for combining Mercury with NVIDIA's CUDA libraries, is granted under section 7 in LICENSE-EXCEPTION.

Mercury Agent - Multi-Domain Anomaly Detection Framework
Copyright (C) 2025 Steel Security Advisors LLC

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

Third-Party Dependencies

  • PyTorch: BSD-style license
  • Fairlearn: MIT license
  • Hypothesis: MPL 2.0 license
  • FastAPI: MIT license
  • AMA Cryptography: Apache License 2.0 (pinned to v5.0.0; the sole PQC backend, and the source of the native HMAC bindings — ACVP-Server known-answer vectors pass bit-for-bit — consumed by omni_mercury_engine.security.native_jwt). Apache-2.0 is one-way compatible with AGPL-3.0, so Mercury can depend on it

PyJWT was retired from the dependency surface in v1.7.0; Mercury now ships a pure-stdlib JOSE implementation (omni_mercury_engine.security.native_jwt) with constant-time signature verification and alg: none rejected by construction. The full rationale is documented in CHANGELOG.md under the 2026-05-20 "Permanent supply-chain remediations" entry.

Dependency Graph

GitHub dependency graph is enabled for this repository. View the complete dependency tree at: Insights > Dependency graph. This provides visibility into all direct and transitive dependencies, security advisories, and Dependabot alerts.


Contact and Support

Contact Information
Type Contact
Operations & Security steel.sa.llc@mercuryagent.global
General Inquiries & Support (incl. the hosted service, mercuryagent.global) contact@mercuryagent.global
Security Issues See SECURITY.md for responsible disclosure
GitHub Issues Issues Page
GitHub Repository Mercury Agent

Acknowledgments

Author/Inventor: Andrew E. A.

AI Co-Architects: Eris ✠ | Eden ♱ | Devin ⚛︎ | Claude ⊛

Special Thanks:

  • NIST Post-Quantum Cryptography Standardization Project
  • Fairlearn bias detection framework
  • Hypothesis property-based testing
  • OWASP security guidelines
  • The open-source ML and security communities

Dataset Attributions

Mercury-Agent benchmarks use the following publicly available datasets:

Dataset Citation Source
SMD Su et al., "Robust Anomaly Detection for Multivariate Time Series", KDD 2019 OmniAnomaly
SMAP/MSL Hundman et al., "Detecting Spacecraft Anomalies Using LSTMs", KDD 2018 telemanom / Kaggle
BATADAL Taormina et al., "Battle of the Attack Detection Algorithms", ASCE 2018 GitHub
Covtype Blackard & Dean, 1999; UCI ML Repository sklearn.datasets
KDDCup99 Tavallaee et al., IEEE 2009 (NSL-KDD variant) sklearn.datasets
ALFA (UAV faults) Keipour, Mousaei & Scherer, "ALFA: A Dataset for UAV Fault and Anomaly Detection", IJRR 2021; CMU AIR Lab; CC0 DOI 10.1184/R1/12707963
Robot Execution Failures Lopes & Camarinha-Matos, 1998; UCI Machine Learning Repository (dataset 138); CC BY 4.0 DOI 10.24432/C5M89N
NAB (Numenta Anomaly Benchmark) Lavin & Ahmad, "Evaluating Real-time Anomaly Detection Algorithms — the Numenta Anomaly Benchmark", ICMLA 2015; MIT numenta/NAB
OpenSky Network (ADS-B state vectors) Schäfer et al., "Bringing Up OpenSky: A Large-scale ADS-B Sensor Network for Research", IPSN 2014; used under the OpenSky terms of use opensky-network.org

Data Source Transparency

Benchmark results include a data_source field indicating data provenance:

  • real-github: Direct from public GitHub repositories
  • real-local: User-downloaded authentic data
  • real-github-partial: Partial real data (some machines/channels failed)

Note: The benchmark never fabricates data. When a dataset's real sources are unavailable it is skipped (recorded as unavailable), never substituted with synthetic data — consistent with the deployment-level MERCURY_ALLOW_SYNTHETIC policy gate (tests/validation/test_synthetic_policy_gate.py).

Configuration

The harness is a runnable CLI (python -m benchmarks.empirical_benchmark --help); a run is deterministic for a fixed --seed and dataset snapshot. Dataset fetching can be configured via environment variables:

  • MERCURY_SMD_MACHINES: Number of SMD machines to fetch (default: 28, CI: 5)
  • MERCURY_FETCH_RETRIES: Maximum retry attempts (default: 10)
  • MERCURY_FETCH_DELAY: Base delay for exponential backoff (default: 2.0 s)

Legal Disclaimer & Attribution

Development Model

Conceptual Architect: Steel Security Advisors LLC and Andrew E. A. conceived, directed, validated, and supervised the development of Mercury Agent.

AI Co-Architects: Significant portions of the codebase, documentation, mathematical frameworks, and technical implementation were constructed by AI systems: Eris ✠, Eden ♱, Devin ⚛︎, and Claude ⊛.

This project represents a human/AI collaborative construct - a development paradigm where human vision, requirements, and critical evaluation guide AI-generated implementation.

Professional Background Disclosure

The human architect does not hold formal credentials in machine learning or medical diagnostics. The AI contributors, while trained on relevant literature, are tools without professional accountability.

What We Did Right

  • Measured, not asserted: headline numbers regenerate from a command. CI rewrites the Latest Benchmark Results block from a live run, the Codebase Scale block fails the build if it drifts from disk, and the ten-minute quickstart reproduces the DTU AIS result (ROC-AUC 0.8750) bit for bit. Figures that are still estimates are labelled as estimates.
  • Tests that are themselves tested: the suite spans unit, property-based (Hypothesis), known-answer vectors (RFC 8032, NIST ACVP-Server) and load-test SLOs (k6 + locust) — and ten module sets are mutation-tested by full enumeration, with kill-rate floors enforced in CI, so a suite that stops catching injected defects fails the build. The headline is the method, not a test tally; structural module counts are measured and CI-gated in the Codebase Scale block.
  • Fail closed, never fabricate: detectors refuse unmeasurable input rather than grade it safe; a missing oracle reports unavailable under the three-state contract instead of guessing; benchmarks skip an unreachable dataset rather than substitute synthetic data.
  • Ethics that are enforced, and honestly scoped: a fail-closed harm-uplift gate and the σ_Immutable configuration-integrity gate stand at every gated decision surface; benevolence is reported as an advisory score, never presented as a control it is not — its one enforcing use is the human-subject purpose screen, which scores the caller's own stated purpose and refuses stalking and harassment the weapons-scoped gate does not cover. The autonomy layer recommends and escalates and never executes a destructive action — a test invariant, not a promise.
  • Evidence that cannot be quietly edited: authentication events and deception-layer tripwires are written to a hash-linked, tamper-evident audit chain whose verification is itself tested — across process restarts, segment rotation and multi-writer deployments, with tests proving a tampered record is detected, not merely that an intact one verifies.
  • Vulnerabilities eliminated, not waived: the blocking container-CVE gate's ledger removes findings at the source — perl-base purged from the runtime image (5 CVEs, two of them CRITICAL), pip and its vendored copies stripped entirely — each verified by rebuilding and re-scanning the image to prove absence, with negative probes in the Dockerfile so a regression fails the build. Every release ships its SBOM and build provenance alongside the wheel and sdist.
  • Executable mathematical certificates: the Lyapunov decay rate λ = 0.25 cited throughout the documentation is enforced by tools/lyapunov_validator.py (generalized symmetric-definite eigenvalue analysis), the canonical YAML configs/lyapunov_canonical.yaml, and the Docs λ Drift Gate CI job — a documentation claim that disagrees with the certificate fails CI rather than going to print.
  • Honest about its own claims: the AMA Cryptography statement separates passing published test vectors from certification, and scripts/doc_lint.py fails CI on the certification phrases Mercury has not earned; open mathematical problems are described as open, and announced-but-unverified results are carried as dated claims.
  • Standards-based design: OWASP input validation, NIST post-quantum standards (FIPS 203/204/205, via AMA Cryptography v5.0.0), Fairlearn fairness metrics, RFC 9116 security.txt, and Sepsis-3 (JAMA 2016) for the medical modules.

What Requires Caution

  • No Independent Audit: All security and performance analysis is self-assessed. Production deployment requires review by qualified professionals.
  • AI-Generated Code: May contain subtle implementation errors. All critical paths require independent verification.
  • Domain-Specific Validation: Core detection is benchmarked on 67 of 76 attempted real datasets (figures in Latest Benchmark Results; the externally comparable figure is ADBench Mean AUC 0.8571). Of the 9 failures, 7 are unreachable sources tracked by a two-lane reachability harness (offline + nightly network); the other 2 resolve to a single label value and are reported as errors, not scored. Domain-specific modules may require additional validation.
  • Medical Applications: No clinical validation. Medical modules require validation on real patient data before any deployment.
  • Research Status: This is a research-grade framework, not a production-ready product.

Recommendation

Before production use:

  • Validate performance on domain-specific real-world datasets (e.g. MIMIC-III for the medical modules; NSL-KDD is already in the committed benchmarks)
  • Commission independent security audit by qualified professionals
  • Conduct clinical validation for any medical applications
  • Deploy with a FIPS 140-3 Level 3+ validated HSM for production secrets (FIPS 140-2 certificates were scheduled to move to the CMVP Historical list on 21 September 2026)
  • Test bias detection on representative data for your use case

No Warranty

THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. THE AUTHORS AND CONTRIBUTORS DISCLAIM ALL LIABILITY FOR ANY DAMAGES RESULTING FROM ITS USE.

This disclaimer does not replace formal legal advice; organizations should consult qualified counsel for regulatory and contractual obligations.


Mercury Agent — Computational Systems Intelligence for Multi-Domain Anomaly & Hazard Detection

Architected with Civilization-First principles, ethical immutability, and transparent methodology.

image

Last updated: 2026-10-21

About

Mercury Agent ♱ is a civilization-first neuro-symbolic AI for multi-domain anomaly & hazard detection and early warning — a trained detector-fusion core, real-data hazard models, fail-closed ethical gates, post-quantum crypto, and a self-hostable detection-as-a-service platform. Built for STEAM research and humanitarian crisis response.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

6 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages