Neura (neuranet-ai) 🚀

AI-Powered Network Health Diagnostics & Actionable Remediation Engine

Neura is a lightweight, client-side network diagnostic tool that uses machine learning (Random Forest classification) and multi-target system probes to identify the exact root cause of network issues—distinguishing between local Wi-Fi attenuation, DNS server bottlenecks, upstream ISP outages, and network congestion/bufferbloat.

Neura also includes an Actionable Remediation Advisor that outputs OS-specific, copy-paste terminal command snippets (for Windows, macOS, and Linux) to resolve issues quickly.

---

🛠️ Key Features

• Cross-Platform Telemetry Collection: Measures round-trip ping latency, packet loss, population jitter ($\sigma$), DNS resolution time, Wi-Fi RSSI (dBm), link rates (Mbps), and bandwidth throughput.
• Random Forest Diagnostic Classifier: Evaluates 10 network telemetry features to produce calibrated diagnostic probabilities across 5 failure categories.
• Actionable Remediation Advisor: Provides step-by-step quick fixes, severity scoring (CRITICAL, HIGH, MEDIUM, LOW, INFO), and native terminal command snippets.
• 100% Read-Only Security Guarantee: Neura never automatically executes shell commands. Suggested terminal commands are displayed purely as formatted text for manual user evaluation, eliminating command injection risks.
• Rich Terminal Dashboard & JSON API: Displays real-time ASCII dashboards or outputs machine-readable JSON for integration into automated daemons.

---

📦 Installation

Install the package globally via pip:

pip install neuranet-ai

---

🚀 Quick Start & CLI Usage

1. Run Live Network Diagnosis & Remediation

Diagnose your current network status and get immediate copy-paste remediation advice:

neura diagnose

2. Continuous Real-Time Diagnostics

Monitor network health continuously every 5 seconds (Ctrl+C to stop):

neura diagnose --live --continuous --interval 5

3. Output Machine-Readable JSON

Generate structured JSON diagnosis payloads for scripting or API integration:

neura diagnose --json

4. Collect Network Health Logs

Run a background telemetry collector that logs observations to network_log.csv every 15 seconds:

neura-collect --interval 15 --out network_log.csv

5. Train / Fine-Tune Model

Train a custom Random Forest model using your own collected network logs:

neura train --real network_log.csv --out network_classifier.joblib

---

📊 Diagnostic Classes & Physical Precedence

Neura classifies network observations into 5 mutually exclusive states, evaluated with physical priority:

Failure State	Root Cause & Network Behavior	Diagnostic Metric Threshold
isp_outage	Upstream WAN disruption	Packet Loss $\ge 30%$, Latency $\ge 250\text{ms}$, or Ping Timeout
dns_issue	Domain name resolution failure	DNS Resolution Time $\ge 250\text{ms}$ or lookup timeout
wifi_weak_signal	Local 802.11 RF attenuation	Wi-Fi RSSI $\le -75\text{ dBm}$ or degraded link speed
congestion	Network congestion / bufferbloat	Jitter $\ge 12\text{ms}$ or Download $< 20\text{ Mbps}$ (under low loss)
healthy	Baseline operational status	Low ping, zero loss, fast DNS resolution, strong Wi-Fi signal

---

🖥️ Example Terminal Output

================================================================
                    NEURA NETWORK DIAGNOSTIC                    
================================================================
Timestamp:   2026-09-14T21:00:00
Diagnosis:   [DNS ISSUE] (Confidence: 88.0%)
Summary:     Domain name resolution bottleneck: slow lookup times or resolver failure.
----------------------------------------------------------------
Observed Telemetry:
  - Ping Latency:    25.0 ms (Jitter: 1.5 ms, Loss: 0.0%)
  - DNS Resolution:  450.0 ms
  - Physical Link:   Wi-Fi (-50.0 dBm, 866.0 Mbps)
  - Throughput:      120.0 Mbps down / 45.0 Mbps up
----------------------------------------------------------------
Model Confidence Distribution:
  [=================   ]  88.0%  dns_issue
  [==                  ]  12.0%  healthy
  [                    ]   0.0%  congestion
  [                    ]   0.0%  isp_outage
  [                    ]   0.0%  wifi_weak_signal
================================================================

+--------------------------------------------------------------+
|  ACTIONABLE REMEDIATION ADVISOR [HIGH]                       |
+--------------------------------------------------------------+
  Issue Summary: Domain Name Resolution Bottleneck (DNS Latency: 450.0 ms)
  Target OS:     Windows
----------------------------------------------------------------
  Recommended Quick Fixes:
    1. Flush your local operating system DNS resolver cache.
    2. Configure static public DNS resolvers (Cloudflare 1.1.1.1 / Google 8.8.8.8).
----------------------------------------------------------------
  Suggested Terminal Commands (Windows Copy-Paste Snippets):
  (Note: Review commands carefully before executing in shell)
    > ipconfig /flushdns
    > netsh interface ip set dns name="Wi-Fi" static 1.1.1.1 primary
----------------------------------------------------------------
  Deep Diagnostic Commands:
    $ nslookup www.google.com 1.1.1.1
----------------------------------------------------------------
  Preventive Maintenance Tips:
    - Configure secondary backup DNS resolvers on your primary router.
+--------------------------------------------------------------+

---

🐍 Python API Usage

You can also import Neura as a Python module in your own applications:

from core_logic.classifier import NetworkIssueClassifier
from core_logic.collector import collect_sample
from core_logic.remediator import get_remediation_plan

# 1. Acquire telemetry sample
sample = collect_sample(do_speedtest=False)

# 2. Load diagnostic model & classify
classifier = NetworkIssueClassifier.load()
diagnosis = classifier.diagnose_sample(sample)

print(f"Diagnosis: {diagnosis['diagnosis']} ({diagnosis['top_probability'] * 100:.1f}% confidence)")

# 3. Obtain remediation advice
plan = get_remediation_plan(diagnosis, sample, target_os="Windows")
print("Headline:", plan.headline)
print("Copy-Paste Commands:", plan.copy_paste_commands)

---

📄 License

Distributed under the MIT License. See LICENSE for more information.