Skip to content

CavinKrenik/QRES_RaaS

BranchesTags

Repository files navigation

QRES — RaaS: Resource-Aware Decentralized Node Mesh

PyPI version PyPI - Python Version CI v21.0.0

DOI Paper Docs

no_std License Rust 2021

A decentralized, BFT-secure operating system for embedded sensor meshes achieving 4.98x-31.8x bandwidth compression via fixed-point model gossip.

RaaS (Resource-Aware Agentic Swarm) is a no_std Rust implementation of deterministic decentralized learning using Q16.16 fixed-point consensus. The reference implementation (QRES) achieves 4.98x-31.8x compression vs federated learning (dataset-dependent: SmoothSine 31.8x, Wafer 4.98x, ECG5000 4.98x), translating to ~99% reduction (8 KB/day vs 2.3 GB/day typical FL baseline) while tolerating 30% Byzantine attackers through coordinate-wise trimmed-mean aggregation and reputation-weighted consensus.

v21 Key Features:

  • TAAF Multimodal Fusion: Cross-modal temporal attention with event-driven sparse spiking (3.6% error improvement, 0.0351 RMSE)
  • Adaptive Byzantine Defense: Dynamic aggregation modes, regime hysteresis (96.9% fewer false transitions), stochastic auditing (100% Class C detection)
  • 7 Security Invariants: INV-1 through INV-7 including liveness guarantee (consensus within 150 rounds under 20% stragglers)
  • Reputation Scaling: Swarm-size adaptive exponents (2.0/3.0/3.5) with rep³ × 0.8 influence cap

See CHANGELOG.md for full version history or docs/INDEX.md for documentation.

Architectural Scope: Read SCOPE.md before deployment or evaluation. QRES is intentionally narrow.

Installation

pip install qres-raas

From source:

git clone https://github.com/CavinKrenik/QRES_RaaS.git
cd QRES_RaaS/bindings/python
pip install maturin
maturin develop --release

Quick Start

Get up and running with QRES in under 5 minutes.

Prerequisites

📦 Installation Requirements (click to expand)

Required:

Optional (for Python bindings):

  • Python 3.8+
  • pip and maturin (pip install maturin)

Platform Support: Linux, macOS, Windows (x86_64/ARM64), WASM, ESP32-C6 (no_std)

Rust: Compress & Decompress

use qres_core::{compress, decompress};

fn main() {
    let data = b"Hello, QRES! Deterministic compression via model gossip.";
    let compressed = compress(data).expect("compression failed");
    let decompressed = decompress(&compressed).expect("decompression failed");

    assert_eq!(data.as_slice(), decompressed.as_slice());
    println!("✓ Compression ratio: {:.2}x", data.len() as f32 / compressed.len() as f32);
}

Python: Adaptive Byzantine-Tolerant Swarm

from qres import QRES_API

# Initialize with hybrid mode (adaptive regime detection)
api = QRES_API(mode="hybrid")

# Compress data with usage hint for optimal predictor selection
data = b"Sensor readings: 23.5C, 45% humidity, 1013 hPa"
compressed = api.compress(data, usage_hint="iot")
decompressed = api.decompress(compressed)

assert data == decompressed
print(f"✓ Bandwidth saved: {len(data) - len(compressed)} bytes")

Installation:

# From source (development)
cd bindings/python && maturin develop --release

# From PyPI (coming soon)
# pip install qres-raas

Try the 100-Node IoT Demo

cd examples/virtual_iot_network
cargo run --release
# Open browser: http://localhost:8080
# Watch real-time convergence with Byzantine node injection

Next Steps:

System Architecture

High-Level Component View:

graph TD
    A[Client Applications] -->|API Calls| B[QRES Daemon]
    B -->|Compress/Decompress| C[qres_core Runtime]

    C --> D[Adaptive Compression]
    C --> E[Byzantine Consensus]
    C --> F[Energy Management]

    D -->|Model Bytecode| G[P2P Swarm Layer]
    E -->|Aggregation| G
    F -->|TWT Scheduling| G

    G --> H[Viral Gossip Protocol]
    G --> I[Reputation System]
    G --> J[ZK Proof Verification]

    H -->|libp2p| K[Peer Network]
    I -->|Adaptive Exponent| K
    J -->|Stochastic Audit| K

    K -->|Consensus Updates| C

    style C fill:#e1f5ff,stroke:#0066cc,stroke-width:3px
    style G fill:#fff4e1,stroke:#ff9900,stroke-width:2px
    style K fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
Loading

Data Flow:

  1. Client submits data → 2. Daemon compresses using local model → 3. Core runtime applies fixed-point predictor (Q16.16) → 4. Residual gossiped via P2P → 5. Byzantine-tolerant aggregation updates model → 6. Reputation-weighted consensus converges → 7. New model distributed via viral protocol

Key Properties:

  • Determinism: Q16.16 fixed-point math ensures bit-perfect consensus across architectures
  • Bandwidth: Model gossip (KB) vs data gossip (GB) = 4.98x-31.8x compression
  • Security: Coordinate-wise trimmed mean + ZK proofs tolerate 30% Byzantine attackers
  • Energy: TWT scheduling + regime-aware silence = 82% radio sleep time in Calm regime

For detailed subsystem diagrams (TAAF fusion pipeline, regime state machine internals, P2P protocol layers), see docs/reference/ARCHITECTURE.md.

Core Systems Constraints

See RAAS_MANIFEST.md for the full technical thesis.

stateDiagram-v2
    [*] --> Calm
    Calm --> PreStorm : entropy derivative > threshold
    PreStorm --> Storm : raw entropy > critical
    Storm --> Calm : entropy subsides
    PreStorm --> Calm : false alarm

    note right of Calm
        TWT Sleep: 4h intervals
        Gossip: utility-gated
        Energy: recharging
    end note

    note right of PreStorm
        TWT Sleep: 10min intervals
        Gossip: broadcast if energy > 30%
        Sentinel: emergency wake ready
    end note

    note right of Storm
        TWT Sleep: 30s intervals
        Gossip: full coordination
        Adaptation: aggressive (LR 0.2)
    end note
Loading
Pillar Mechanism Result
Determinism Q16.16 fixed-point arithmetic (I16F16) Bit-perfect consensus across ARM/x86/RISC-V/WASM
Bandwidth Deterministic rematerialization + model bytecode gossip 4.98x-31.8x compression vs FL (dataset-dependent); ~99% reduction baseline (8 KB/day vs 2.3 GB/day)
Energy SNN-inspired sparse accounting + TWT radio scheduling 21.9x advantage over ANN swarms; >80% sleep time in Calm regime

Verified Performance (v20.0 "Distributed Prediction Engine")

Consensus Evolution

Metric Result Context
Convergence <30 epochs to consensus Verified on 100-node swarms with noise injection
Bandwidth 4.98x-31.8x compression vs FL (dataset-dependent) SmoothSine 31.8x, Wafer 4.98x, ECG5000 4.98x; baseline ~99% reduction (8 KB/day vs 2.3 GB typical FL)
Scalability 10,000 nodes (100% success) Azure Standard_D2s, verified Jan 2026
Compression 4.98x-31.8x (dataset-dependent) SmoothSine 31.8x, Wafer 4.98x, ECG5000 4.98x
Memory < 1 KB per node overhead no_std + alloc, O(1) per node
Byzantine Tolerance Drift < 5% at 30% coordinated bias Coordinate-wise trimmed mean
Energy 21.9x advantage (SNN vs ANN) Verified in simulation collapse test
TWT Sleep Savings 82% reduction in radio energy MockRadio verified over 24h simulated period
Multimodal RMSE 0.0351 (3.6% gain over v19) 10/10 verification tests green
Max Drift 0.0005 Across all tested configurations
Non-Volatile State Persistence 4% error delta, 8 cycles Zero catastrophic knowledge loss
Adaptive Exponent 3.5 for >50 nodes, Gini <0.7 24 configs tested, no echo chambers

v20.0.1 Adaptive Defense Milestone

Byzantine Resistance Enhancements verified against Class C coordinated cartels:

Metric Result Verification
Class C Cartel Detection 100% detection rate 10 cartel scenarios, 390 honest nodes
False Positive Rate 0% Zero honest nodes falsely banned
Bandwidth Overhead 2.0% Stochastic auditing cost
Detection Timing Mean: 82.3 rounds First=31, Last=174, σ=37.2
Adaptive Aggregation Savings 13.8% overhead reduction vs. static trimmed-mean
Regime Hysteresis Improvement 96.9% false-positive reduction Asymmetric confirmation thresholds

Protocol: Stochastic auditing samples 3% of updates per round, cross-validating reputation scores against cryptographic ZK proofs. Cartels exhibiting coordinated bias patterns are detected via statistical outlier analysis (Grubbs' test, α=0.01) and isolated within mean 82.3 rounds.

See CLASS_C_DEFENSE.md for full specification.

Architecture

QRES_RaaS/
├── crates/
│   ├── qres_core/           # no_std deterministic core (Core Runtime + Persistent Storage Layer)
│   │   ├── adaptive/        # Regime detection, silence protocol
│   │   ├── cortex/          # SwarmNeuron trait, LinearNeuron, model bytecode storage
│   │   ├── consensus/       # Byzantine-tolerant aggregation (Krum, trimmed mean)
│   │   ├── power/           # TWT scheduler, reputation-weighted sleep
│   │   ├── packet/          # MTU fragmentation, GhostUpdate gossip
│   │   ├── semantic.rs      # HSTP semantic envelopes (JSON-LD, RDF, W3C DID)
│   │   └── ...              # ZK proofs, secure aggregation, privacy, reputation
│   ├── qres_daemon/         # P2P edge daemon (libp2p gossipsub + REST API)
│   ├── qres_sim/            # Simulation and evaluation engine for swarm dynamics
│   └── qres_wasm/           # WebAssembly bindings for browser deployment
├── tools/
│   └── swarm_sim/           # Legacy Bevy 3D simulator (pre-qres_sim)
├── evaluation/
│   └── benchmarks/          # Performance harness and cloud benchmark results
├── examples/
│   └── virtual_iot_network/ # 100-node demo with noise injection
├── docs/                    # Specifications, guides, ADRs, verification reports
│   └── power/               # TWT integration documentation
└── RAAS_MANIFEST.md         # Resource-Aware Swarm thesis

The Core Runtime: qres_core

A no_std Rust library. All consensus math uses Q16.16 fixed-point (I16F16) for bit-perfect determinism across x86, ARM, RISC-V, and WASM. Key subsystems:

  • Regime Detection — 3-point moving-average entropy with predictive PreStorm trigger
  • Strategic Silence — Utility-gated gossip: broadcast = (entropy * reputation) > (cost * bias)
  • TWT Power Scheduling — Reputation-weighted sleep intervals with gossip batching
  • Byzantine Aggregation — Coordinate-wise trimmed mean, BFP-16 block floating point
  • Zero-Knowledge Integrity — Non-interactive Sigma protocol over Edwards curves
  • Secure Aggregation — Pairwise x25519 masking with wrapping cancellation
  • Energy Accounting — Deterministic energy pools with hardware-calibrated profiles
  • Semantic Middleware — HSTP-aligned JSON-LD envelopes with W3C DID and RDF provenance for cross-swarm model bytecode discovery (IEEE 7007-2021)

The Mind: swarm_sim

Bevy-based 3D simulator demonstrating emergent swarm behavior: model bytecode gossip, noise-zone storms, mutation cascades, and Non-Volatile State Persistence evolution. Up to 100 nodes in 10x10 grid with force-directed physics, HDR bloom, and real-time HUD metrics.

The Persistent Storage Layer: Trait-Based Persistence

Trait-based storage (GeneStorage) enabling learned strategies to survive reboots. Disk, cloud, or IPFS backends. Evolved model bytecode packets auto-load on spawn.

Power Management: TWT Integration

QRES coordinates Wi-Fi 6 Target Wake Time scheduling with regime-aware silence:

Regime TWT Interval Sleep Power Active Power
Calm 4 hours (rep-weighted) 35 mW 230 mW
PreStorm 10 minutes (rep-weighted) 35 mW 230 mW
Storm 30 seconds (rep-weighted) 35 mW 230 mW

Reputation-weighted intervals stagger wake times across the swarm, preventing blind spots. High-reputation nodes sleep longer (proven reliable); low-reputation nodes wake 5x more often (must contribute). Currently in simulation mode via MockRadio; hardware integration targets ESP32-C6 native TWT.

See: docs/power/TWT_INTEGRATION.md

Hardware Compatibility

Tier Platform TWT Support Status
Tier 1 ESP32-C6 Native Wi-Fi 6 / TWT Target (no_std core ready)
Tier 2 Raspberry Pi Zero 2 W Simulated TWT / Linux edge Calibration-ready (energy profiles defined)
Tier 3 RISC-V Custom Silicon Theoretical no_std core compiles; awaiting hardware
Tier 4 x86_64 / WASM Simulation only Full test suite, cloud benchmarks verified

All tiers share the same qres_core binary. Hardware-specific behavior is isolated behind EnergyProfile constants and the MockRadio/real-radio abstraction.

Getting Started

Prerequisites

  • Rust 1.70+ (install via rustup)
  • Cargo (included with Rust)

Build & Test

# Core crate (no_std)
cargo build -p qres_core --no-default-features --release

# Full test suite (134 tests passing: unit + integration + v20 verification)
cargo test -p qres_core --features std

# TWT scheduler tests specifically
cargo test -p qres_core --features std -- power::

# Daemon (P2P edge node)
cargo build -p qres_daemon --release

# 3D Simulator
cargo run -p swarm_sim --release

# Generate local API docs (opens in browser)
make doc

Tip: The Makefile provides convenience targets for all common operations: make test, make clippy, make bench, make coverage, make build-release, and more. Run make help for the full list.

Run the Neural Swarm Simulator

Neural Swarm Visualization

cargo run -p swarm_sim --release
Key Action
Left-click + drag Orbit camera
Scroll wheel Zoom in/out
Spacebar Toggle auto-rotation
R Reset simulation

Documentation

Category Files
Specification SPEC.md, API_REFERENCE.md
Theory Archived in RaaS_Extras/docs/theory/
Power Management TWT_INTEGRATION.md
Implementation P2P_IMPLEMENTATION.md, SECURITY_GUIDE.md
Benchmarks BENCHMARKS.md, CLOUD_RESULTS.md
Adaptive Tuning META_TUNING.md, SENSITIVITY_ANALYSIS.md
Formal Verification FORMAL_SPEC.md (TLA+ regime transition, Q2 2026 model checking)
Interoperability semantic.rs (HSTP envelopes, JSON-LD, W3C DID, RDF provenance)
Process CONTRIBUTING.md, SCOPE.md, SECURITY_ROADMAP.md
RaaS Thesis RAAS_MANIFEST.md

Contributing

See CONTRIBUTING.md for development workflow, code style, and architecture decision records.

License

Dual-licensed under MIT or Apache-2.0, at your option.

Citation

@software{qres2026,
  author = {Krenik, Cavin},
  title = {QRES: Resource-Aware Agentic Swarm},
  url = {https://github.com/CavinKrenik/QRES_RaaS},
  doi = {10.5281/zenodo.18474976},
  year = {2026}
}

Publications

Paper DOI PDF
Deterministic Rematerialization: Convergent Evolution in Cloud Kernels and Edge Swarms DOI —
RaaS: Resource-Aware Agentic Swarm DOI Zenodo | Local

Reproducibility & Data

This repository contains the full artifacts, data, and source for the RaaS paper:

Status: v20.0 "Distributed Prediction Engine" - Simulation-Hardened. Multimodal TAAF with event-driven sparse spiking (0.0351 RMSE, 3.6% gain over v19). Adaptive reputation exponent (2.0/3.0/3.5 by swarm size). Influence-capped at rep^3 * 0.8. HSTP semantic middleware for cross-swarm model bytecode discovery (JSON-LD + W3C DID + RDF provenance). TLA+ formal specification drafted (Q2 2026 model checking target). Cryptographically secure (ZK-proofs), energy-aware (TWT scheduling). Ready for hardware-in-the-loop deployment on ESP32-C6.

About

Resource-Aware Agentic Swarm

Topics

rust iot byzantine-fault-tolerance edge-ai edge-ai-agents

Resources

Readme

License

Unknown, MIT licenses found

Licenses found

Unknown
LICENSE-APACHE
MIT
LICENSE-MIT

Code of conduct

Code of conduct
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 4

v21.0.0 Latest
Feb 6, 2026
+ 3 releases

Packages

 
 
 

Contributors

Languages