Vagus-Decipher AI — Documentation | Neural Decoding Framework

📖 Overview

"The nervous system has been listening to the immune system for a hundred million years of evolution. Vagus-Decipher AI is the first framework that learns to listen with it — extracting, from the ancient electrophysiological language of the vagus nerve, the precise moment when the body begins to lose the battle against inflammation."

Vagus-Decipher AI is the first physics-informed neural decoding framework specifically engineered to extract immunological state estimates from raw electroneurogram (ENG) recordings of the cervical vagus nerve for real-time prediction of systemic inflammatory storms.

The framework comprises three mathematically rigorous constructs: AWIE (Adaptive Wavelet Isolation Engine), NISSD (Neuro-Immune State-Space Decoder), and ISI (Inflammatory Storm Index Predictor).

🏗️ 3-Core Architecture

AWIE — Adaptive Wavelet Isolation Engine

Multi-resolution signal decomposition pipeline that separates immune-afferent spike trains from the dominant cardiorespiratory and gastrointestinal efferent noise floor. Morlet wavelet (σ=6) with 32 scales, immune-afferent band 300-3000 Hz. Spatiotemporal beamformer achieves 18-22 dB interference rejection.

NISSD — Neuro-Immune State-Space Decoder

Physics-constrained recurrent neural operator mapping inhomogeneous Poisson firing rate λ(t) to latent immunological state vector S_t ∈ ℝ⁷ encoding TNF-α, IL-1β, IL-6, IL-10, C3a, NeutAct, CoagAct. Neural ODE state transition with Unscented Kalman Filter (2n+1 = 15 sigma points). Jacobian sign constraints enforce cytokine cascade biology.

ISI — Inflammatory Storm Index Predictor

Model-predictive temporal integrator issuing graded 0–1 risk score with clinically validated 30–60 minute advance warning horizon. Acceleration-sensitive design with exponential kernel (β = 0.08 min⁻¹, half-life ~8.7 min). Alert threshold ISI ≥ 0.65.

📐 Core Equations (Eq. 1-10)

Eq. 1 — Vagal ENG Signal Model

x(t) = Σ h_i(t) * s_i(t) + e_cardiac + e_resp + n(t)

Immune-afferent SNR: -20 to -35 dB

Eq. 2-3 — AWIE Wavelet Transform

W_x(a,b) = (1/√a)∫x(t)ψ*((t-b)/a)dt
x_immune = ∫∫ W_x·ψ (da db)/a²

Morlet wavelet (σ=6), 300-3000 Hz band

Eq. 4 — Spatiotemporal Beamformer

y(t) = Σ w_k · x_k(t - d_k/v_C)

v_C ∈ [0.2, 2.0] m/s (C-fiber range)

Eq. 5 — Inhomogeneous Poisson

P({t_kj}|λ_k) = e^{-∫λdt} · Π λ_k(t_kj)

CV_ISI^corr ≈ 0.97 validates Poisson assumption

Eq. 6 — Bayesian Firing Rate

λ̂_k = k_ss · (k_ss + σ_n²I)⁻¹ · s_k

Matérn-3/2 GP prior, 1 ms resolution

Eq. 7 — NISSM

Sₜ₊₁ = f_θ(Sₜ) + G_θ·Λ(t) + wₜ
Λ(t) = h_φ(Sₜ) + vₜ

S_t ∈ ℝ⁷ cytokine state vector

Eq. 8 — Jacobian Sign Constraint

sign(∂f_θ_i/∂S_j) = C_ij

Cytokine coupling sign matrix

Eq. 9 — Inflammatory Storm Index

ISI(t) = σ(α∫e^{-βτ}Λ̇dτ + γ||S_t - S_h||)

β = 0.08 min⁻¹, alert at ISI ≥ 0.65

Eq. 10 — ISI Loss Function

L = L_pred + λ₁·L_physics + λ₂·L_timing

Physics + timing constraints

🏥 Clinical Integration

ISI Alert Tiers

ISI Score	Alert Level	Clinical Action	Response Time
0.00 – 0.35	🟢 LOW	Routine monitoring	—
0.35 – 0.55	🟡 ELEVATED	Increase vital signs frequency	<30 min
0.55 – 0.75	🟠 HIGH	Physician notification + lab panel	<15 min
> 0.75	🔴 CRITICAL	Immediate intervention protocol	<5 min

HL7 FHIR Integration

python — FHIR observation

from vagus_decipher import VagusDecipherEngine
from vagus_decipher.clinical import FHIRExporter

engine = VagusDecipherEngine()
exporter = FHIRExporter(fhir_server_url="https://fhir.hospital.org/R4")

for chunk in data_stream:
    result = engine.process(chunk)
    if result.alert_level in ['HIGH', 'CRITICAL']:
        exporter.send_alert(result)

📦 Installation

bash — pip install

pip install vagus-decipher

# From source
git clone https://github.com/gitdeeper12/Vagus-Decipher.git
cd Vagus-Decipher
pip install -e .

Core Dependencies: numpy, filterpy

🔧 API Reference

python — main interface

from vagus_decipher import VagusDecipherEngine

engine = VagusDecipherEngine(
    interface='implanted_cuff',
    n_contacts=6,
    fs=30000,
    conduction_velocity=(0.2, 2.0),
    warn_horizon_min=45
)

result = engine.process(eng_signal)

# Access results
isi = result['isi']
alert = result['alert_level']
cytokines = result['state']

Parameters

Parameter	Description	Default	Domain
interface	Hardware interface type	'implanted_cuff'	implanted_cuff, acute_hook, tavns
n_contacts	Number of electrode contacts	6	4-8
fs	Sampling rate (Hz)	30000	≥30000
conduction_velocity	C-fiber velocity range (m/s)	(0.2, 2.0)	—
warn_horizon_min	Advance warning target (minutes)	45	30-60

🧩 Core Modules

Module	Description
awie/	Adaptive Wavelet Isolation Engine — wavelet.py, beamformer.py, spike_detector.py
nissd/	Neuro-Immune State-Space Decoder — state_space.py, ukf.py, physics.py
isi/	Inflammatory Storm Index — predictor.py, thresholds.py
utils/	Utilities — signal_processing.py, data_loader.py

📊 Validation Summary

Model	Challenge	ISI Accuracy	Lead Time	AUROC
M1	LPS Endotoxemia	93.1%	51.2 min	0.971
M2	Sterile SIRS	90.8%	44.7 min	0.958
M3	CAR-T CRS analog	90.4%	45.9 min	0.960
Mean	—	91.4%	47.3 min	0.963

👤 Author

🧠

Samir Baladi

Principal Investigator — Neural Engineering & Biomedical AI

Samir Baladi is an independent interdisciplinary researcher affiliated with the Ronin Institute, developing the Rite of Renaissance research program. Vagus-Decipher AI is the second installment of the Biomedical & Clinical AI Research Series (BIO-MED-02).

📧 gitdeeper@gmail.com 🔗 ORCID: 0009-0003-8903-0029 🐙 GitHub 🦊 GitLab

📝 Citation

@software{baladi2026vagusdecipher, author = {Samir Baladi}, title = {Vagus-Decipher AI: Neural Decoding of Vagus Nerve Electrophysiology for Real-Time Prediction of Systemic Inflammatory Storms}, year = {2026}, version = {1.0.0}, publisher = {Zenodo}, doi = {10.5281/zenodo.20347323}, url = {https://doi.org/10.5281/zenodo.20347323}, note = {BIO-MED-02, Biomedical & Clinical AI Research Series} }