Complete reference for the QRES Neural Swarm Operating System platform.
Start here to understand the system design and key concepts:
- Specification (SPEC.md) — Formal specification of all subsystems, protocols, and constraints. Begin with the three-layer architecture section.
- API Reference (API_REFERENCE.md) — Comprehensive API documentation for qres_core, qres_daemon, and qres_wasm bindings.
- Implementation Status (IMPLEMENTATION_STATUS.md) — Detailed progress tracking for all phases. Shows what is stable vs. in-development.
Deep dives into the science and mathematics:
- Theory (THEORY.md) — Complete mathematical framework for spiking neural networks, entropy thresholds, and regime switching.
- SNN Energy Analysis (SNN_ENERGY_ANALYSIS.md) — Hardware efficiency analysis comparing SNNs to traditional ANNs. Key insight: 1000x less energy per inference.
- Technical Deep Dives (TECHNICAL_DEEP_DIVES.md) — Detailed explorations of specific subsystems (fixed-point math, gossip protocols, MTU physics).
- Related Work (RELATED_WORK.md) — Survey of federated learning, decentralized AI, and edge computing literature.
Step-by-step guides for specific integration tasks:
- P2P Implementation (P2P_IMPLEMENTATION.md) — How to implement gossip protocols for gene propagation. Covers both ESP32 and x86 targets.
- Security Implementation Guide (SECURITY_IMPLEMENTATION_GUIDE.md) — Cryptographic signing, proof verification, and threat model mitigation.
- Benchmarks (BENCHMARKS.md) — Local microbenchmarks for fixed-point arithmetic, compression algorithms, and neural inference.
- Cloud Benchmark Results (CLOUD_BENCHMARK_RESULTS.md) — Large-scale swarm experiments on AWS/Azure showing convergence rates and bandwidth usage.
Guidelines for contributing and maintaining the project:
- Contributing (CONTRIBUTING.md) — Development setup, code style, testing standards, and pull request process.
- Security Roadmap (SECURITY_ROADMAP.md) — Planned security audits, cryptography upgrades, and threat model refinements.
Decisions that shaped the system:
- ADR-001: SNN vs ANN — Why we chose spiking neural networks over traditional artificial neural networks.
- ADR-002: Signature Scheme — Why we use Curve25519 with zero-knowledge proofs instead of threshold cryptography.
- ADR-003: PRNG Sync — How deterministic pseudo-random number generation ensures cross-platform consensus.
- Completed Milestones (COMPLETED_MILESTONES.md) — Chronological record of v1.0 through v18.0 releases and their features.
- Release Notes (releases/RELEASE_NOTES.md) — Detailed changelog for the latest stable release.
- Bibliography (references.bib) — Academic citations for all referenced papers and systems.
- See CITATION.cff in root for BibTeX format.
First Time Here?
- Read ../README.md (root README) for the executive summary
- Skim SPEC.md section 1 (Three-Layer Architecture)
- Watch the GIF in the root README
- Run the simulator:
cargo run -p swarm_sim --release
Want to Contribute?
- Read CONTRIBUTING.md
- Check IMPLEMENTATION_STATUS.md for open tasks
- Review relevant ADRs if changing core systems
Deploying to Edge Hardware?
- Read P2P_IMPLEMENTATION.md
- Consult SECURITY_IMPLEMENTATION_GUIDE.md
- Review API_REFERENCE.md for qres_daemon API
Understanding Performance?
- Check BENCHMARKS.md for local results
- Read CLOUD_BENCHMARK_RESULTS.md for swarm-scale data
- Review SNN_ENERGY_ANALYSIS.md for hardware efficiency
Latest Stable Version: v18.0 Status: Stable. The pivot from v17.0 (Deterministic Compression) to v18.0 (Neural Swarm Architecture) is complete and verified in simulation.