Metadata-Version: 2.4
Name: neuranet-ai
Version: 0.1.1
Summary: AI-powered network issue troubleshooter and diagnostic engine
Author: Aditya Mishra
License: MIT
Project-URL: Homepage, https://github.com/adityamishra5214/Neura
Project-URL: Repository, https://github.com/adityamishra5214/Neura.git
Keywords: network,telemetry,ai,machine-learning,diagnostics,random-forest,troubleshooting
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: joblib>=1.3.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: speedtest-cli>=2.1.3
Dynamic: license-file

# Neura (`neuranet-ai`) 🚀

> **AI-Powered Network Health Diagnostics & Actionable Remediation Engine**

[![PyPI version](https://img.shields.io/pypi/v/neuranet-ai.svg)](https://pypi.org/project/neuranet-ai/)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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`:

```bash
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:

```bash
neura diagnose
```

### 2. Continuous Real-Time Diagnostics
Monitor network health continuously every 5 seconds (Ctrl+C to stop):

```bash
neura diagnose --live --continuous --interval 5
```

### 3. Output Machine-Readable JSON
Generate structured JSON diagnosis payloads for scripting or API integration:

```bash
neura diagnose --json
```

### 4. Collect Network Health Logs
Run a background telemetry collector that logs observations to `network_log.csv` every 15 seconds:

```bash
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:

```bash
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

```text
================================================================
                    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:

```python
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`](LICENSE) for more information.
