{"id":51280128,"url":"https://github.com/ruvnet/ruv-neural","last_synced_at":"2026-06-30T01:02:45.620Z","repository":{"id":364166472,"uuid":"1266708706","full_name":"ruvnet/ruv-neural","owner":"ruvnet","description":"The open closed-loop OS for gamma-entrainment research — a Rust/WASM/edge harness to measure, adapt \u0026 compare 40 Hz multisensory stimulation protocols with signed, reproducible evidence. Research-grade, not a medical device.","archived":false,"fork":false,"pushed_at":"2026-06-29T23:10:29.000Z","size":1611,"stargazers_count":20,"open_issues_count":1,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-30T00:17:00.060Z","etag":null,"topics":["bci","brain-computer-interface","brain-mapping","closed-loop","dsp","eeg","gamma-entrainment","graph-theory","magnetometry","minimum-cut","neural-decoding","neurofeedback","neuroscience","neurotechnology","nv-center","protocol-optimization","real-time","rust","signal-processing","topology"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ruvnet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY_REVIEW.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-11T22:04:23.000Z","updated_at":"2026-06-29T23:10:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ruvnet/ruv-neural","commit_stats":null,"previous_names":["ruvnet/ruv-neural"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ruvnet/ruv-neural","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Fruv-neural","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Fruv-neural/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Fruv-neural/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Fruv-neural/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ruvnet","download_url":"https://codeload.github.com/ruvnet/ruv-neural/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruvnet%2Fruv-neural/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34948227,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bci","brain-computer-interface","brain-mapping","closed-loop","dsp","eeg","gamma-entrainment","graph-theory","magnetometry","minimum-cut","neural-decoding","neurofeedback","neuroscience","neurotechnology","nv-center","protocol-optimization","real-time","rust","signal-processing","topology"],"created_at":"2026-06-30T01:02:44.964Z","updated_at":"2026-06-30T01:02:45.612Z","avatar_url":"https://github.com/ruvnet.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rUv Neural — the open closed-loop OS for gamma-entrainment research\n\n\u003csub\u003e**Keywords:** 40 Hz gamma entrainment (GENUS) · multisensory stimulation ·\nclosed-loop neuromodulation · protocol optimization · sensory stimulation ·\nneurofeedback · EEG signal processing · HRV · brain-network connectivity · graph\ntheory · minimum cut · NV-diamond magnetometry · OPM · quantum sensing ·\nneurotechnology · reproducible research · Rust · ESP32 · WebAssembly\u003c/sub\u003e\n\n[![crates.io](https://img.shields.io/crates/v/ruv-neural-core.svg)](https://crates.io/crates/ruv-neural-core)\n[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)]()\n[![Rust](https://img.shields.io/badge/rust-1.75+-orange.svg)]()\n[![Tests](https://img.shields.io/badge/tests-398%20passed-brightgreen.svg)]()\n[![Status](https://img.shields.io/badge/status-research%20harness%20—%20not%20a%20medical%20device-important.svg)]()\n\n---\n\n**rUv Neural is the open, closed-loop operating system for gamma-entrainment\nresearch** — a research-grade harness to **measure, adapt, and compare** 40 Hz\nsensory-stimulation protocols, with auditable, reproducible, cryptographically\nsigned evidence. Built in Rust; runs native, in the browser (WASM), and on the\nedge (ESP32).\n\n\u003e **Not a medical device. Not a cure. Not a wellness toy.** rUv Neural makes **no\n\u003e efficacy claim.** It is *evidence infrastructure* for studying whether, when, and\n\u003e for whom sensory gamma stimulation does anything — and for running those\n\u003e protocols safely and reproducibly.\n\n[![rUv Neural web console — local-first evidence verification](docs/images/overview.png)](apps/ruv-neural-ui)\n\n\u003csub\u003eThe in-browser console plays back **signed evidence bundles** and re-verifies\nthem entirely locally — no backend, no accounts, no data leaves the page.\n[See the full UI ↓](#web-console--ruv-neural-ui)\u003c/sub\u003e\n\n## Contents\n\n[Thesis](#the-thesis--the-wave-is-protocol-optimization) ·\n[Five primitives](#five-primitives) · [Who it's for](#who-its-for) ·\n[Why now](#why-now--the-research-wave) · [The wedge](#the-wedge--40-hz-protocol-workbench) ·\n[Ethics](#ethics--responsible-use) · [Closed loop (Ruflo)](#closed-loop-sensory-neuromodulation-ruflo) ·\n[Web console](#web-console--ruv-neural-ui) · [How it observes](#how-it-observes--brain-network-topology) ·\n[Architecture](#architecture) · [Crate map](#crate-map) ·\n[Hardware BOM](#hardware-parts-list) · [Witness verification](#cryptographic-witness-verification)\n\n## The thesis — the wave is protocol *optimization*\n\nThe coming wave isn't another 40 Hz blinking light — it's **protocol\noptimization**, and that is a *measurement, adaptation, and comparison* problem.\nThe questions researchers actually have to answer, and where rUv Neural sits on\neach:\n\n| Problem | rUv Neural position |\n|---|---|\n| Which modality works best? | light · sound · vibration · phase-locked multimodal |\n| Who responds? | responder profiling (per-person state embedding) |\n| When should stimulation happen? | sleep · rest · task · circadian window |\n| How much is enough? | dose · duration · intensity |\n| Is entrainment real? | EEG · HRV · motion · sleep · cognition |\n| Is it safe? | photosensitivity · comfort · adherence · signed audit logs |\n\n## Five primitives\n\n1. **Stimulus engine** — 40 Hz light, audio, haptic; phase-locked multimodal output with verified delivery receipts. → [`ruv-neural-stim`](ruv-neural-stim)\n2. **Closed-loop controller** — adapt intensity, duty cycle, modality, and timing from the measured response, inside a hard safety envelope. → [`ruv-neural-loop`](ruv-neural-loop)\n3. **Response measurement** — EEG optional; also HRV, sleep, actigraphy, reaction time, adherence, subjective state. → [`ruv-neural-biosense`](ruv-neural-biosense) + the [topology pipeline](#how-it-observes--brain-network-topology)\n4. **Protocol registry** — versioned protocols with receipts: frequency, waveform, lux, SPL, vibration amplitude, duration, time of day.\n5. **Research evidence layer** — link protocols to papers, trials, results, safety notes, and reproducibility metadata — hash-chained and Ed25519-signed.\n\n\u003e **Companion tool — [`ruvn`](https://github.com/ruvnet/ruvn):** an AI research agent that turns a question into a **graded, cited evidence dossier** (searches → grades every source A/B/C/D → synthesizes from the best → fact-checks → cites). It's the practical front-end for the evidence layer above. Install `npm i -g @ruvnet/ruvn` ([npm](https://www.npmjs.com/package/@ruvnet/ruvn)), then run `ruvn`.\n\n## Who it's for\n\n| User | Value |\n|---|---|\n| **Labs** | reproducible stimulation protocols |\n| **Startups** | faster device iteration |\n| **Clinicians** | structured observational data |\n| **Care homes** | safe, supervised pilots |\n| **Researchers** | multimodal protocol comparison |\n| **Developers** | Rust / WASM / edge SDK |\n\n## Why now — the research wave\n\nMIT and others report that multisensory 40 Hz stimulation may activate glymphatic\nclearance pathways and affect amyloid and tau biology **in animal models**. Human\nevidence is promising but still **mixed**, with large sham-controlled trials (such\nas Cognito's pivotal study) ongoing.¹\n\nThat uncertainty **is the opportunity.** The field doesn't need another device\nclaiming fixed efficacy — it needs a system for **measuring, adapting, and\ncomparing** protocols. rUv Neural is that harness: the bridge between cheap sensory\nhardware, serious neuroscience, and auditable adaptive protocols.\n\n\u003csub\u003e¹ Multisensory gamma stimulation \u0026 glymphatic clearance —\n[Nature (2024)](https://www.nature.com/articles/s41586-024-07132-6). Human\nefficacy remains under active, sham-controlled investigation; nothing here is a\nclinical claim.\u003c/sub\u003e\n\n## The wedge — 40 Hz Protocol Workbench\n\nThe first demo turns a protocol into reproducible evidence:\n\n- **Inputs** — frequency, modality, duration, intensity, time of day, safety limits\n- **Outputs** — entrainment proxy, HRV shift, adherence, sleep impact, cognitive-microtask score, signed protocol receipt\n- **Acceptance test** — run 7 days of mock or real sessions and generate a reproducible report: protocol version, delivered-waveform hash, safety events, adherence, and response trend\n\n---\n\n## Ethics \u0026 Responsible Use\n\n\u003e **This technology interfaces with human neural data. Use it responsibly.**\n\u003e\n\u003e - **Informed consent** is required before collecting neural data from any participant\n\u003e - **Never** deploy brain-computer interfaces without IRB/ethics board approval\n\u003e - **Data privacy**: Neural signals are among the most sensitive personal data categories. Encrypt at rest, anonymize before sharing, and comply with GDPR/HIPAA as applicable\n\u003e - **Clinical use** requires FDA/CE clearance and must be supervised by licensed medical professionals\n\u003e - **Do not** use this software for covert monitoring, interrogation, lie detection, or any application that violates human autonomy\n\u003e - **Dual-use awareness**: The same technology that helps paralyzed patients communicate can be misused for surveillance. Design with safeguards\n\u003e - This software is provided for **research and educational purposes**. The authors accept no liability for misuse\n\u003e\n\u003e See [IEEE Neuroethics Framework](https://standards.ieee.org/industry-connections/ec/neuroethics/) and the [Morningside Group Neurorights](https://nri.ntc.columbia.edu/content/neurorights) initiative for guidance.\n\n---\n\n## How it observes — brain-network topology\n\n\"Is entrainment real?\" needs a response signal. rUv Neural's measurement core is a\nmodular Rust pipeline that turns multi-channel neural data — EEG, or magnetic fields\nfrom quantum sensors (NV-diamond, OPM) — into a **dynamic connectivity graph**, then\napplies **minimum-cut** algorithms to surface topology events: when brain networks\nform, dissolve, merge, or split. That topology stream is the entrainment /\ncognitive-response proxy the closed loop adapts to.\n\n**This is not mind-reading.** It does not touch words, memories, or private\nthoughts — it measures *how* cognition organizes itself (its live network\n*topology*), not *what* you are thinking. Think Google Maps for cognition.\n\n\u003e **Honest scope.** Validated today on **EEG** and a **deterministic simulator** —\n\u003e not yet clinically validated on a population. The quantum-sensor front-end\n\u003e (NV-diamond / OPM) is the **research frontier**: magnetometry-grade hardware is a\n\u003e five-figure instrument (see [the BOM reality check](#core-nv-diamond-magnetometer-single-odmr-channel)),\n\u003e so EEG and the simulator are the practical paths to build against.\n\n## Closed-Loop Sensory Neuromodulation (Ruflo)\n\n\u003e **Research-grade wellness \u0026 cognitive-state platform — not a medical device.**\n\u003e Only safe external sensory channels are used. Transcranial/implanted\n\u003e neuromodulation (TMS, tDCS/tACS, focused ultrasound, DBS, VNS) is **out of\n\u003e scope** — that is medical-device territory requiring clinical validation,\n\u003e dosing controls, contraindication screening, and regulatory review.\n\u003e See [ADR-0001](docs/adr/0001-scope.md).\n\nBeyond *observing* topology, rUv Neural can *gently steer* cognitive state with a\n**closed loop**: detect the state, deliver a verified sensory stimulus, measure\nthe physiological response, adapt conservatively, and **stop safely** the moment\nthe response leaves an allowed envelope.\n\n| Channel | Role | Crate |\n|---------|------|-------|\n| 40 Hz light / audio / haptic | sensory entrainment (GENUS) | [`ruv-neural-stim`](ruv-neural-stim) |\n| HRV · breathing · motion · sleep | response sensing | [`ruv-neural-biosense`](ruv-neural-biosense) |\n| personal state embedding (ruVector) | per-person state fusion | [`ruv-neural-loop`](ruv-neural-loop) |\n| protocol selection · guardrails · audit trail (Ruflo) | closed-loop control | [`ruv-neural-loop`](ruv-neural-loop) |\n\n```text\n  observe ─▶ embed (ruVector) ─▶ estimate state ─▶ SAFETY ENVELOPE\n                                                       │\n                            within ──────────────────┴────── breach\n                               │                                 │\n                     select protocol \u0026 dose               fail-safe STOP\n                               │                            (intensity 0)\n                     deliver VERIFIED stimulus ──▶ audit (hash-chained, signed)\n```\n\n**Acceptance test** ([ADR-0011](docs/adr/0011-acceptance-test.md)): the system can\n*identify a target state, deliver a **verified** stimulus, measure a response, and\nstop safely when the response moves outside the allowed envelope* — encoded as\n`SessionReport::passes_acceptance()` and asserted in\n[`ruv-neural-loop/tests/closed_loop_acceptance.rs`](ruv-neural-loop/tests/closed_loop_acceptance.rs).\n\n```bash\n# Drive a closed-loop session toward a relaxed state, then write signed evidence\ncargo run -p ruv-neural-cli -- neuromod --target relaxed --seed 11 \\\n    --output report.json --audit audit.json --sign\n\n# Demonstrate the fail-safe stop: inject an arousal spike mid-session\ncargo run -p ruv-neural-cli -- neuromod --target relaxed --perturb 5\n\n# Export a portable evidence bundle and verify it with the reference verifier\n# (the same checks the web console runs in-browser — verdict matches byte-for-byte)\ncargo run -p ruv-neural-cli -- neuromod --target relaxed --bundle bundle.json --sign\ncargo run -p ruv-neural-cli -- verify-bundle -i bundle.json   # → VERDICT: PASS\n```\n\n```rust\nuse ruv_neural_loop::*;\nuse ruv_neural_stim::StimulusGenerator;\n\nlet mut controller = ClosedLoopController::new(\n    ControllerConfig::default(),\n    TargetState::relaxed(),\n    StimulusGenerator::conservative(),       // sensory-safety limits enforced\n    SafetyEnvelope::default(),                // fail-safe stop bounds\n    Box::new(GammaEntrainmentProtocol::audio_haptic()),\n);\nlet mut sim = LoopSimulation::responsive(11, 10.0); // closed-loop subject model\nsim.run(\u0026mut controller, 64);\n\nlet report = controller.report();\nassert!(report.passes_acceptance());          // verified delivery + safe outcome\nassert!(controller.sign_session().verify());   // Ed25519-attested audit head\n```\n\nDesign decisions are documented as Architecture Decision Records in\n[`docs/adr/`](docs/adr/0000-template.md); the drive-to-validated iteration log is\nin [`docs/closed-loop-loop-log.md`](docs/closed-loop-loop-log.md).\n\n### Web console — rUv Neural UI\n\nA **static, local-first** web console ([`apps/ruv-neural-ui`](apps/ruv-neural-ui),\n[ADR-0014](docs/adr/0014-web-console.md)) makes Ruflo understandable in five\nminutes and **verifies the evidence entirely in your browser** — no backend, no\naccounts, no health data leaves the page. It plays back real, signed evidence\nbundles (`ruv-neural neuromod --bundle … --sign`) in **Demo** mode and verifies\nany imported bundle in **Replay** mode: schema validity, a **recomputed** hash\nchain, receipt integrity + frequency tolerance, fail-safe-stop semantics, the\nEd25519 signature, and the acceptance result. The Rust exporter and the\nTypeScript verifier hash from the *same* fixed-precision canonical string, so the\nchain is reproduced, not trusted.\n\n| Overview — session summary + local verification | Live session — convergence |\n|---|---|\n| ![Overview](docs/images/overview.png) | ![Live session](docs/images/session.png) |\n\n| Stimulus verifier — verified 40 Hz receipts | Safety envelope — fail-safe stop |\n|---|---|\n| ![Stimulus verifier](docs/images/stimulus.png) | ![Safety envelope](docs/images/safety.png) |\n\nA **gated Real mode** (Phase 4) adds explicit opt-in/consent + contraindication\nscreening, a Web Serial bridge (with an in-browser mock device so the flow is\ndemonstrable without hardware), a hardware-validation handshake, an\nalways-visible emergency stop, an enforced intensity ceiling, and a\nhash-chained device-event log — all local-only, off by default. A guided\n**Research workflow** (Phase 5) walks consent → contraindication → baseline →\nprotocol → verified session → survey → **signed evidence export**, re-verifiable\nin Replay mode, with nothing uploaded.\n\n| Real mode — gated local hardware | Research workflow — signed study export |\n|---|---|\n| ![Real mode](docs/images/realmode.png) | ![Research workflow](docs/images/research.png) |\n\n```bash\ncd apps/ruv-neural-ui\nnpm install\nnpm run test      # vitest — schema + verifier + tamper-detection (Rust↔TS hash parity)\nnpm run dev       # local dev server\nnpm run build     # static build → dist/ (deploys to GitHub Pages)\n```\n\n## Hardware Parts List\n\nBelow is a reference bill of materials for building a basic multi-channel neural sensing rig.\nPrices are approximate (2026). Links are for reference only — equivalent components from any\nvendor will work.\n\n### Core: NV Diamond Magnetometer (single ODMR channel)\n\nODMR works by pumping a nitrogen-vacancy diamond with green (532 nm) light,\nsweeping a ~2.87 GHz microwave field across the NV spin resonance, and reading\nthe red fluorescence dip on a photodiode. Verified, currently-purchasable parts\n(confirm price/stock at checkout — some are quote/lead-time items):\n\n| Component | Qty | Approx Price | Vendor / Link | Notes |\n|-----------|-----|-------------|------|-------|\n| **NV-doped CVD diamond** (research grade) | 1 | ~$1,440 | [Element Six DNV-B1, 3.0×3.0×0.5 mm](https://e6cvd.com/us/application/all/dnv-b1-3-0mmx3-0mm-0-5mm.html) | The real sensing element: ~800 ppb engineered N, NV ensemble for magnetometry. Quote/lead-time item — **not** a $45 commodity. |\n| **NV diamond** (budget / demo grade) | 1 | ~$200–500 (quote) | [Adámas Nanotechnologies NV diamond plates](https://www.adamasnano.com/diamond-plates) | HPHT plates (100–300 ppm N) for education/R\u0026D. Brighter but worse spin coherence (T2) → lower sensitivity. Enough to *see* an ODMR dip. |\n| **532 nm pump laser** (lab grade) | 1 | ~$1,000–2,000 | [Thorlabs 532 nm DPSS lasers](https://www.thorlabs.com/532-nm-diode-pumped-solid-state-dpss-lasers) | Real ODMR wants 50–150 mW CW. (Thorlabs' compact [CPS532](https://www.thorlabs.com/thorproduct.cfm?partnumber=CPS532) is only 4.5 mW — too weak.) |\n| **532 nm pump laser** (budget) | 1 | ~$30–80 | [Laserlands 532 nm DPSS module](https://www.laserlands.net/diode-laser-module/532nm-dpss-green-laser-module.html) | A 50–100 mW DPSS \"pointer\" module works for a demo; poor power stability. **Class 3B — eye hazard, wear goggles.** |\n| **2.87 GHz microwave source** | 1 | ~$20–35 | [ADF4351 PLL board, 35 MHz–4.4 GHz](https://www.amazon.com/Frequency-Synthesizer-Development-Generator-35M-4-4GHz/dp/B0BCWVHFT1) | Honest cheap real part — covers 2.87 GHz, SPI-controlled, SMA output. |\n| **RF amplifier** (usually needed) | 1 | ~$93 | [Mini-Circuits ZX60-V63+ (50 MHz–6 GHz)](https://www.minicircuits.com/WebStore/dashboard.html?model=ZX60-V63%2B) | ADF4351 outputs only ~0 to +5 dBm; a ~20 dB gain block drives the NV spins through the loop. |\n| **Microwave delivery loop** | 1 | ~$5–15 | hand-wound copper loop + [SMA pigtail (Digikey)](https://www.digikey.com) | ~1–2 mm copper loop against the diamond, fed by SMA. DIY. |\n| **Long-pass optical filter** (essential) | 1 | ~$120 | [Thorlabs FEL0600, Ø1″ 600 nm long-pass](https://www.thorlabs.com/thorproduct.cfm?partnumber=FEL0600) | Blocks the 532 nm pump, passes NV red fluorescence (637–700 nm). Without it the pump swamps the detector — no ODMR contrast. |\n| **Focusing / collection lens** | 1 | ~$30 | [Thorlabs ACL2520U aspheric, f=20 mm, NA 0.60](https://www.thorlabs.com/thorproduct.cfm?partnumber=ACL2520U) | High-NA lens to focus the pump and collect fluorescence. |\n| **Photodiode + transimpedance amp** | 1 | ~$400 | [Thorlabs PDA36A2 switchable-gain Si detector](https://www.thorlabs.com/thorproduct.cfm?partnumber=PDA36A2) | Si photodiode + built-in switchable-gain TIA in one unit. DIY op-amp TIA (OPA381/OPA657) + bare Si photodiode is the ~$20–40 budget alternative. |\n\n\u003e **Reality check — NV-diamond magnetometry is research-grade hardware, not a\n\u003e $45 hobby part.** The microwave source is genuinely cheap (ADF4351, ~$20–35),\n\u003e but **the diamond and the optics dominate the cost.** A magnetometry-grade\n\u003e CVD diamond (Element Six DNV-B1) is ~$1,440, not $45; even an education-grade\n\u003e HPHT plate runs into the hundreds and trades away the spin coherence that\n\u003e gives you sensitivity. Add the essential long-pass filter (~$120), a high-NA\n\u003e lens, an amplified photodiode/TIA (~$400), and a pump laser strong enough to\n\u003e actually excite the NVs (50–100 mW — a real lab DPSS head is ~$1–2k). Honest\n\u003e figure: **the cheapest credible single-channel ODMR demo rig is several\n\u003e hundred dollars at the very low end (demo diamond, pointer laser, DIY\n\u003e electronics) and realistically ~$3,000–5,000 for a research-quality channel.**\n\u003e A 16-channel NV array is a serious scientific instrument — multiplied\n\u003e diamonds, lasers, optics and detection electronics, comfortably a five-figure\n\u003e build. **If you just want to develop the software, use the EEG path below or\n\u003e the built-in simulator** — they exercise the same pipeline without the\n\u003e quantum-optics bench.\n\n### Alternative: OPM (Optically Pumped Magnetometer)\n\n| Component | Qty | Approx Price | Link | Notes |\n|-----------|-----|-------------|------|-------|\n| Rb Vapor Cell (25mm, AR coated) | 8 | $35 ea | [AliExpress: Rubidium Vapor Cell](https://www.aliexpress.com/w/wholesale-rubidium-vapor-cell.html) | SERF-mode magnetometry |\n| 795nm VCSEL Laser | 8 | $8 ea | [AliExpress: 795nm VCSEL](https://www.aliexpress.com/w/wholesale-795nm-vcsel-laser.html) | D1 line pump for Rb |\n| Balanced Photodetector | 8 | $15 ea | [AliExpress: Balanced Photodetector](https://www.aliexpress.com/w/wholesale-balanced-photodetector.html) | Differential detection |\n| Magnetic Shielding Mu-Metal Cylinder | 1 | $120 | [AliExpress: Mu-Metal Shield](https://www.aliexpress.com/w/wholesale-mu-metal-magnetic-shield.html) | 3-layer, \u003e60dB attenuation |\n\n### Alternative: EEG (Electroencephalography)\n\n| Component | Qty | Approx Price | Link | Notes |\n|-----------|-----|-------------|------|-------|\n| Ag/AgCl EEG Electrodes (10-20 system) | 21 | $2 ea | [AliExpress: EEG Electrode AgCl](https://www.aliexpress.com/w/wholesale-eeg-electrode-ag-agcl.html) | Reusable cup electrodes |\n| EEG Cap (10-20 placement, size M) | 1 | $45 | [AliExpress: EEG Cap 10-20](https://www.aliexpress.com/w/wholesale-eeg-cap-10-20.html) | Pre-wired 21-channel |\n| Conductive EEG Gel (250ml) | 1 | $8 | [AliExpress: EEG Gel](https://www.aliexpress.com/w/wholesale-eeg-conductive-gel.html) | Low impedance contact |\n| ADS1299 EEG AFE Board (8-ch) | 3 | $35 ea | [AliExpress: ADS1299 Board](https://www.aliexpress.com/w/wholesale-ads1299-eeg-board.html) | 24-bit, 250 SPS, TI analog front-end |\n\n### Data Acquisition \u0026 Processing\n\n| Component | Qty | Approx Price | Link | Notes |\n|-----------|-----|-------------|------|-------|\n| ESP32-S3 DevKit (16MB Flash, 8MB PSRAM) | 4 | $8 ea | [AliExpress: ESP32-S3 DevKit](https://www.aliexpress.com/w/wholesale-esp32-s3-devkit.html) | ADC readout + TDM sync |\n| ADS1256 24-bit ADC Module | 2 | $12 ea | [AliExpress: ADS1256 Module](https://www.aliexpress.com/w/wholesale-ads1256-module.html) | High-resolution for NV/OPM |\n| USB-C Hub (4 port, USB 3.0) | 1 | $10 | [AliExpress: USB-C Hub](https://www.aliexpress.com/w/wholesale-usb-c-hub-4-port.html) | Connect ESP32 nodes to host |\n| Shielded USB Cable (30cm, ferrite) | 4 | $3 ea | [AliExpress: Shielded USB Cable](https://www.aliexpress.com/w/wholesale-shielded-usb-cable-ferrite.html) | Reduce EMI |\n| Host PC or Raspberry Pi 5 (8GB) | 1 | $80 | [AliExpress: Raspberry Pi 5](https://www.aliexpress.com/w/wholesale-raspberry-pi-5-8gb.html) | Runs the rUv Neural pipeline |\n\n### Assembly Tools\n\n| Component | Qty | Approx Price | Link | Notes |\n|-----------|-----|-------------|------|-------|\n| Soldering Station (adjustable temp) | 1 | $25 | [AliExpress: Soldering Station](https://www.aliexpress.com/w/wholesale-soldering-station-adjustable.html) | For sensor board assembly |\n| Breadboard + Jumper Wire Kit | 1 | $8 | [AliExpress: Breadboard Kit](https://www.aliexpress.com/w/wholesale-breadboard-jumper-wire-kit.html) | Prototyping |\n| 3D Printed Sensor Mount (STL provided) | 1 | — | Print locally | Holds diamond chips in array |\n\n**Estimated total cost (honest):** a single-channel NV ODMR rig is ~$700–1,000\n(demo-grade diamond + budget laser + DIY electronics) to ~$3,000–5,000\n(research grade); a 16-channel NV array is a five-figure scientific instrument\n(see the NV reality check above). OPM is similarly lab-grade. **EEG is the\npractical path at ~$200**, and the built-in **simulator costs nothing** — both\nexercise the full pipeline.\n\n### Assembly Instructions\n\n1. **Sensor Array**\n   - Mount NV diamond chips (or OPM vapor cells, or EEG electrodes) in the 3D-printed helmet/mount\n   - For NV: align 532nm laser to each chip, position photodiodes for fluorescence collection\n   - For OPM: install Rb cells inside mu-metal shield, align 795nm VCSELs\n   - For EEG: apply conductive gel, place electrodes per 10-20 system\n\n2. **Signal Chain**\n   - Connect sensor outputs to ADS1256 (NV/OPM) or ADS1299 (EEG) ADC boards\n   - Wire ADC SPI bus to ESP32-S3 GPIO (MOSI=11, MISO=13, SCK=12, CS=10)\n   - Flash ESP32 with `ruv-neural-esp32` firmware: `cargo flash --chip esp32s3`\n\n3. **TDM Synchronization**\n   - Connect GPIO 4 across all ESP32 nodes as a shared sync line\n   - The `TdmScheduler` assigns non-overlapping time slots automatically\n   - Set `sync_tolerance_us: 1000` in the aggregator config\n\n4. **Host Software**\n   - Install Rust 1.75+ and build: `cargo build --workspace --release`\n   - Run the pipeline: `cargo run -p ruv-neural-cli --release -- pipeline --channels 16 --duration 60`\n   - Or use individual crates as a library (see [Use as Library](#use-as-library))\n\n5. **Verification**\n   - Generate a witness bundle: `cargo run -p ruv-neural-cli -- witness --output witness.json`\n   - Verify Ed25519 signature: `cargo run -p ruv-neural-cli -- witness --verify witness.json`\n   - Expected output: `VERDICT: PASS` (51 capability attestations, 398 tests)\n\n## Architecture\n\n```\n                         rUv Neural Pipeline\n    ================================================================\n\n    +------------------+     +-------------------+     +------------------+\n    |                  |     |                   |     |                  |\n    |  SENSOR LAYER    |----\u003e|  SIGNAL LAYER     |----\u003e|  GRAPH LAYER     |\n    |                  |     |                   |     |                  |\n    |  NV Diamond      |     |  Bandpass Filter  |     |  PLV / Coherence |\n    |  OPM             |     |  Artifact Reject  |     |  Brain Regions   |\n    |  EEG             |     |  Hilbert Phase    |     |  Connectivity    |\n    |  Simulated       |     |  Spectral (PSD)   |     |  Matrix          |\n    |                  |     |                   |     |                  |\n    +------------------+     +-------------------+     +--------+---------+\n                                                                |\n                                                                v\n    +------------------+     +-------------------+     +------------------+\n    |                  |     |                   |     |                  |\n    |  DECODE LAYER    |\u003c----|  MEMORY LAYER     |\u003c----|  MINCUT LAYER    |\n    |                  |     |                   |     |                  |\n    |  Cognitive State |     |  HNSW Index       |     |  Stoer-Wagner    |\n    |  Classification  |     |  Pattern Store    |     |  Normalized Cut  |\n    |  BCI Output      |     |  Drift Detection  |     |  Spectral Cut    |\n    |  Transition Log  |     |  Temporal Window  |     |  Coherence Detect|\n    |                  |     |                   |     |                  |\n    +------------------+     +-------------------+     +------------------+\n                                      ^\n                                      |\n                              +-------+--------+\n                              |                |\n                              |  EMBED LAYER   |\n                              |                |\n                              |  Spectral Pos. |\n                              |  Topology Vec  |\n                              |  Node2Vec      |\n                              |  RVF Export     |\n                              |                |\n                              +----------------+\n\n    Peripheral Crates:\n    +----------+   +----------+   +----------+\n    | ESP32    |   | WASM     |   | VIZ      |\n    | Edge     |   | Browser  |   | ASCII    |\n    | Preproc  |   | Bindings |   | Render   |\n    +----------+   +----------+   +----------+\n```\n\n## Crate Map\n\nAll crates are published on [crates.io](https://crates.io/search?q=ruv-neural):\n\n| Crate | crates.io | Description | Dependencies |\n|-------|-----------|-------------|--------------|\n| [`ruv-neural-core`](https://crates.io/crates/ruv-neural-core) | [![crates.io](https://img.shields.io/crates/v/ruv-neural-core.svg)](https://crates.io/crates/ruv-neural-core) | Core types, traits, errors, RVF format | None |\n| [`ruv-neural-sensor`](https://crates.io/crates/ruv-neural-sensor) | [![crates.io](https://img.shields.io/crates/v/ruv-neural-sensor.svg)](https://crates.io/crates/ruv-neural-sensor) | NV diamond, OPM, EEG sensor interfaces | core |\n| [`ruv-neural-signal`](https://crates.io/crates/ruv-neural-signal) | [![crates.io](https://img.shields.io/crates/v/ruv-neural-signal.svg)](https://crates.io/crates/ruv-neural-signal) | DSP: filtering, spectral, connectivity | core |\n| [`ruv-neural-graph`](https://crates.io/crates/ruv-neural-graph) | [![crates.io](https://img.shields.io/crates/v/ruv-neural-graph.svg)](https://crates.io/crates/ruv-neural-graph) | Brain connectivity graph construction | core, signal |\n| [`ruv-neural-mincut`](https://crates.io/crates/ruv-neural-mincut) | [![crates.io](https://img.shields.io/crates/v/ruv-neural-mincut.svg)](https://crates.io/crates/ruv-neural-mincut) | Dynamic minimum cut topology analysis | core |\n| [`ruv-neural-embed`](https://crates.io/crates/ruv-neural-embed) | [![crates.io](https://img.shields.io/crates/v/ruv-neural-embed.svg)](https://crates.io/crates/ruv-neural-embed) | RuVector graph embeddings | core |\n| [`ruv-neural-memory`](https://crates.io/crates/ruv-neural-memory) | [![crates.io](https://img.shields.io/crates/v/ruv-neural-memory.svg)](https://crates.io/crates/ruv-neural-memory) | Persistent neural state memory + HNSW | core |\n| [`ruv-neural-decoder`](https://crates.io/crates/ruv-neural-decoder) | [![crates.io](https://img.shields.io/crates/v/ruv-neural-decoder.svg)](https://crates.io/crates/ruv-neural-decoder) | Cognitive state classification + BCI | core |\n| [`ruv-neural-brain2text`](ruv-neural-brain2text) | — | Non-invasive brain-to-text bridge (Brain2Qwerty / SpanishBCBL) + evolutionary optimizer | core, signal |\n| [`ruv-neural-stim`](https://crates.io/crates/ruv-neural-stim) | [![crates.io](https://img.shields.io/crates/v/ruv-neural-stim.svg)](https://crates.io/crates/ruv-neural-stim) | 40 Hz light/audio/haptic stimulus synthesis + verified delivery receipts | core |\n| [`ruv-neural-biosense`](https://crates.io/crates/ruv-neural-biosense) | [![crates.io](https://img.shields.io/crates/v/ruv-neural-biosense.svg)](https://crates.io/crates/ruv-neural-biosense) | Physiological response sensing (HRV, respiration, motion, sleep) | core |\n| [`ruv-neural-loop`](https://crates.io/crates/ruv-neural-loop) | [![crates.io](https://img.shields.io/crates/v/ruv-neural-loop.svg)](https://crates.io/crates/ruv-neural-loop) | Ruflo closed-loop controller: safety envelope, dosing, audit trail | core, stim, biosense, embed |\n| [`ruv-neural-esp32`](https://crates.io/crates/ruv-neural-esp32) | [![crates.io](https://img.shields.io/crates/v/ruv-neural-esp32.svg)](https://crates.io/crates/ruv-neural-esp32) | ESP32 edge sensor integration | core |\n| `ruv-neural-wasm` | — | WebAssembly browser bindings | core |\n| [`ruv-neural-viz`](https://crates.io/crates/ruv-neural-viz) | [![crates.io](https://img.shields.io/crates/v/ruv-neural-viz.svg)](https://crates.io/crates/ruv-neural-viz) | Visualization and ASCII rendering | core, graph, mincut |\n| [`ruv-neural-cli`](https://crates.io/crates/ruv-neural-cli) | [![crates.io](https://img.shields.io/crates/v/ruv-neural-cli.svg)](https://crates.io/crates/ruv-neural-cli) | CLI tool (`ruv-neural` binary) | all |\n\n## Dependency Graph\n\n```\n                    ruv-neural-core\n                    (types, traits, errors)\n                   /    |    |    \\     \\\n                  /     |    |     \\     \\\n                 v      v    v      v     v\n           sensor  signal  embed  esp32  (wasm)\n                          |\n                          v\n                  graph --|------\u003e viz\n                  |\n                  v\n               mincut\n                  |\n                  v\n         decoder \u003c--- memory \u003c--- embed\n                  |\n                  v\n                 cli (depends on all)\n```\n\n## Quick Start\n\n### Build\n\n```bash\ncd v2/crates/ruv-neural\ncargo build --workspace\ncargo test --workspace\n```\n\n### Run CLI\n\n```bash\ncargo run -p ruv-neural-cli -- simulate --channels 64 --duration 10\ncargo run -p ruv-neural-cli -- pipeline --channels 32 --duration 5 --dashboard\ncargo run -p ruv-neural-cli -- mincut --input brain_graph.json\n```\n\n### Install from crates.io\n\n```bash\n# Add individual crates as needed\ncargo add ruv-neural-core\ncargo add ruv-neural-sensor\ncargo add ruv-neural-signal\ncargo add ruv-neural-mincut\ncargo add ruv-neural-embed\ncargo add ruv-neural-memory\ncargo add ruv-neural-decoder\ncargo add ruv-neural-graph\ncargo add ruv-neural-viz\ncargo add ruv-neural-esp32\ncargo add ruv-neural-cli\n```\n\n### Use as Library\n\n```rust\nuse ruv_neural_core::*;\nuse ruv_neural_sensor::simulator::SimulatedSensorArray;\nuse ruv_neural_signal::PreprocessingPipeline;\nuse ruv_neural_mincut::DynamicMincutTracker;\nuse ruv_neural_embed::NeuralEmbedding;\n\n// Create simulated sensor array (64 channels, 1000 Hz)\nlet mut sensor = SimulatedSensorArray::new(64, 1000.0);\nlet data = sensor.acquire(1000)?;\n\n// Preprocess: bandpass filter + artifact rejection\nlet pipeline = PreprocessingPipeline::default();\nlet clean = pipeline.process(\u0026data)?;\n\n// Compute connectivity and build graph\nlet connectivity = ruv_neural_signal::compute_all_pairs(\n    \u0026clean,\n    ruv_neural_signal::ConnectivityMetric::PhaseLockingValue,\n);\n\n// Track topology changes via dynamic mincut\nlet mut tracker = DynamicMincutTracker::new();\nlet result = tracker.update(\u0026graph)?;\nprintln!(\n    \"Mincut: {:.3}, Partitions: {} | {}\",\n    result.cut_value,\n    result.partition_a.len(),\n    result.partition_b.len()\n);\n\n// Generate embedding for downstream classification\nlet embedding = NeuralEmbedding::new(\n    result.to_feature_vector(),\n    data.timestamp,\n    \"spectral\",\n)?;\nprintln!(\"Embedding dim: {}\", embedding.dimension);\n```\n\n## Mix and Match\n\nEach crate is independently usable. Common combinations:\n\n- **Sensor + Signal** -- Data acquisition and preprocessing only\n- **Graph + Mincut** -- Graph analysis without sensor dependency\n- **Embed + Memory** -- Embedding storage without real-time pipeline\n- **Core + WASM** -- Browser-based graph visualization\n- **ESP32 alone** -- Edge preprocessing on embedded hardware\n- **Signal + Embed** -- Feature extraction pipeline without graph construction\n- **Mincut + Viz** -- Topology analysis with ASCII dashboard output\n\n## Platform Support\n\n| Platform | Status | Crates Available |\n|----------|--------|-----------------|\n| Linux x86_64 | Full | All 15 |\n| macOS ARM64 | Full | All 15 |\n| Windows x86_64 | Full | All 15 |\n| WASM (browser) | Partial | core, wasm, viz |\n| ESP32 (no_std) | Partial | core, esp32 |\n\n**Note:** The `ruv-neural-wasm` crate is excluded from the default workspace members.\nBuild it separately with:\n\n```bash\ncargo build -p ruv-neural-wasm --target wasm32-unknown-unknown --release\n```\n\n## Key Algorithms\n\n### Signal Processing (`ruv-neural-signal`)\n\n- **Butterworth IIR filters** in second-order sections (SOS) form\n- **Welch PSD** estimation with configurable window and overlap\n- **Hilbert transform** for instantaneous phase extraction\n- **Artifact detection** -- eye blink, muscle, cardiac artifact rejection\n- **Connectivity metrics** -- PLV, coherence, imaginary coherence, AEC\n\n### Minimum Cut Analysis (`ruv-neural-mincut`)\n\n- **Stoer-Wagner** -- Global minimum cut in O(V^3)\n- **Normalized cut** (Shi-Malik) -- Spectral bisection via the Fiedler vector\n- **Multiway cut** -- Recursive normalized cut for k-module detection\n- **Spectral cut** -- Cheeger constant and spectral bisection bounds\n- **Dynamic tracking** -- Temporal topology transition detection\n- **Coherence events** -- Network formation, dissolution, merger, split\n\n### Embeddings (`ruv-neural-embed`)\n\n- **Spectral** -- Laplacian eigenvector positional encoding\n- **Topology** -- Hand-crafted topological feature vectors\n- **Node2Vec** -- Random-walk co-occurrence embeddings\n- **Combined** -- Weighted concatenation of multiple methods\n- **Temporal** -- Sliding-window context-enriched embeddings\n- **RVF export** -- Serialization to RuVector `.rvf` format\n\n## RVF Format\n\nRuVector File (RVF) is a binary format for neural data interchange:\n\n```\n+--------+--------+---------+----------+----------+\n| Magic  | Version| Type    | Payload  | Checksum |\n| RVF\\x01| u8     | u8      | [u8; N]  | u32      |\n+--------+--------+---------+----------+----------+\n```\n\n- **Magic bytes**: `RVF\\x01`\n- **Supported types**: brain graphs, embeddings, topology metrics, time series\n- **Binary format** for efficient storage and streaming\n- **Compatible** with the broader RuVector ecosystem\n\n## Cryptographic Witness Verification\n\nrUv Neural includes an Ed25519-signed capability attestation system. Every build can\ngenerate a witness bundle that cryptographically proves which capabilities are present\nand that all tests passed.\n\n```bash\n# Generate a signed witness bundle\ncargo run -p ruv-neural-cli -- witness --output witness-bundle.json\n\n# Verify (any third party can do this)\ncargo run -p ruv-neural-cli -- witness --verify witness-bundle.json\n```\n\nThe bundle contains:\n- **51 capability attestations** covering all 15 crates\n- **SHA-256 digest** of the capability matrix\n- **Ed25519 signature** (unique per generation)\n- **Public key** for independent verification\n- Test count and pass/fail status\n\nTampered bundles are detected — modifying any attestation invalidates the digest and\nsignature verification returns `FAIL`.\n\n## Testing\n\n```bash\n# Run all workspace tests\ncargo test --workspace\n\n# Run a specific crate's tests\ncargo test -p ruv-neural-mincut\n\n# Run with logging enabled\nRUST_LOG=debug cargo test --workspace -- --nocapture\n\n# Run benchmarks (requires nightly or criterion)\ncargo bench -p ruv-neural-mincut\n```\n\n## Crate Publishing Order\n\nCrates must be published in dependency order:\n\n1. `ruv-neural-core` (no internal deps)\n2. `ruv-neural-sensor` (depends on core)\n3. `ruv-neural-signal` (depends on core)\n4. `ruv-neural-esp32` (depends on core)\n5. `ruv-neural-graph` (depends on core, signal)\n6. `ruv-neural-embed` (depends on core)\n7. `ruv-neural-mincut` (depends on core)\n8. `ruv-neural-viz` (depends on core, graph)\n9. `ruv-neural-memory` (depends on core, embed)\n10. `ruv-neural-decoder` (depends on core, embed)\n11. `ruv-neural-stim` (depends on core)\n12. `ruv-neural-biosense` (depends on core)\n13. `ruv-neural-loop` (depends on core, stim, biosense, embed)\n14. `ruv-neural-wasm` (depends on core)\n15. `ruv-neural-cli` (depends on all)\n\n## License\n\nMIT OR Apache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruvnet%2Fruv-neural","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruvnet%2Fruv-neural","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruvnet%2Fruv-neural/lists"}