Metadata-Version: 2.4
Name: emion
Version: 1.0.0
Summary: Research-grade ION-DTN simulation framework with real BPv7, WLAN mobility, and per-node ML module attachment
Author: EmION Team
Author-email: Team DOMinators <dev@info-gallary.com>
License: MIT
Project-URL: Homepage, https://github.com/info-gallary/emion
Project-URL: Repository, https://github.com/info-gallary/emion.git
Project-URL: Documentation, https://github.com/info-gallary/emion/tree/main/docs
Project-URL: Issues, https://github.com/info-gallary/emion/issues
Keywords: dtn,ion,bpv7,simulation,space,networking,delay-tolerant,cgr,anomaly-detection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Networking
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.100.0; extra == "dashboard"
Requires-Dist: uvicorn>=0.20.0; extra == "dashboard"
Requires-Dist: websockets>=11.0; extra == "dashboard"
Requires-Dist: python-multipart>=0.0.6; extra == "dashboard"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: httpx>=0.24.0; extra == "test"
Provides-Extra: experiments
Requires-Dist: requests>=2.31.0; extra == "experiments"
Requires-Dist: websockets>=11.0; extra == "experiments"
Requires-Dist: psutil>=5.9.0; extra == "experiments"
Provides-Extra: ml
Requires-Dist: numpy>=1.24.0; extra == "ml"
Requires-Dist: scikit-learn>=1.3.0; extra == "ml"
Dynamic: author
Dynamic: license-file

# ⚛️ EmION — Research-Grade ION-DTN Simulation

> **Built with 💻 by Team DOMinators**

**EmION** is an authentic, research-grade Delay-Tolerant Networking (DTN) simulation framework. Unlike other simulators, EmION uses the **real NASA-JPL ION-DTN C-engine** and **Contact Graph Routing (CGR)** for 100% protocol authenticity — with a state-of-the-art visual dashboard and per-node ML module attachment.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-green.svg)](https://www.python.org)

---

## ✨ Key Features

| Feature | Description |
|---------|-------------|
| **Real ION-DTN** | Uses the actual NASA-JPL ION C-engine — not a simulator |
| **BPv7 + CGR** | Full Bundle Protocol v7 with Contact Graph Routing |
| **WLAN Mobility** | Spatial distance-based wireless link management |
| **XML Scenario Import** | Load CORE GUI `.xml` scenarios directly |
| **Scenario Briefing** | Plain-English mission summary from any loaded scenario |
| **Per-Node ML Modules** | Attach anomaly detectors, BPSec signers to specific nodes |
| **Auto-Feed Pipeline** | Nodes automatically stream telemetry to attached modules |
| **Visual Dashboard** | Real-time canvas with node LEDs, bundle animation, HUD overlays |
| **CFDP Support** | Authentic file delivery over DTN |

---

## 🌍 Platform Support

| Platform | Support | Notes |
|----------|---------|-------|
| **Linux (Ubuntu/Debian)** | ✅ Native | Recommended. Use `install.sh` |
| **Windows (WSL2)** | ✅ Supported | Ubuntu 22.04 on WSL2 |
| **Docker** | ✅ Containerized | Zero local setup |
| **Windows (Native)** | ❌ | Use WSL2 or Docker |

---

## 🚀 Installation

### From PyPI
```bash
pip install "emion[dashboard]"
```

### From Source
```bash
git clone https://github.com/info-gallary/emion.git
cd emion
pip install -e ".[dashboard]"
```

### For Testing
```bash
pip install -e ".[dashboard,test]"
```

### Full Environment (Linux/WSL)
```bash
chmod +x install.sh && ./install.sh
```

---

## 🛰️ Usage

### Launch the Dashboard
```bash
emion dashboard
```
Open **http://localhost:8420** in your browser.

### CLI
```bash
emion info       # ION system status
emion dashboard  # Start the visual dashboard
```

### Run Tests
```bash
pytest -q
```

For a reviewer-friendly quick pass:

```bash
pytest -q tests/test_scenario_import.py tests/test_dashboard_scenarios.py
```

### Run Automated Experiments
```bash
python3 scripts/run_experiments.py \
  --config examples/experiments/scalability_matrix.json \
  --output-dir artifacts/experiments_matrix
```

This writes per-scenario CSVs plus aggregate SVG plots under `artifacts/experiments_matrix/`.

## 📖 Documentation

- [Quickstart](docs/quickstart.md)
- [Architecture Overview](docs/architecture.md)
- [Dashboard API Reference](docs/api.md)
- [Custom XML Scenario Format](docs/scenario_format.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Reproducibility Guide](docs/reproducibility.md)

---

## 🧪 XML Scenario Import

Upload any CORE `.xml` scenario directly in the dashboard:

1. Open **Scenario Engine** in the sidebar
2. Drag-and-drop your `.xml` file (or click **Browse Files**)
3. A **Scenario Briefing** appears in the telemetry panel with a plain-English summary
4. Click **▶ Start** to begin the simulation

See [`examples/ion_mars/`](examples/ion_mars/) for a sample scenario.

For a reproducibility-oriented validation workflow, see [docs/reproducibility.md](docs/reproducibility.md).

Experiment configs are available in [`examples/experiments/`](examples/experiments/), including:

- `scalability_matrix.json`
- `robustness_matrix.json`
- `ml_matrix.json`
- `mars_actual_schedule.json`

---

## 📚 Citation

Citation metadata is available in [CITATION.cff](CITATION.cff).

---

## 🔌 Per-Node ML Modules

Attach ML inference modules (anomaly detectors, security analyzers) to **specific nodes**. The node automatically feeds all telemetry and bundle data to the attached module.

### Quick Start
1. Start your module (a FastAPI server with `/health` and `/analyze` endpoints)
2. In the dashboard sidebar → **ML MODULES**
3. Select a node → pick module type → enter the API URL → **Attach**
4. Watch the canvas LED indicators (🟢/🟡/🔴) change in real-time

### Module API Contract
Your module must expose:
- `GET /health` → `{"status": "ok"}`
- `POST /analyze` → receives `{"payload": ..., "metadata": {...}}`, returns `{"is_anomaly": bool, "score": float}`

See [`examples/anomaly_detector/`](examples/anomaly_detector/) for a reference implementation.

---

## 🐳 Docker

```bash
docker build -t emion .
docker run -p 8420:8420 emion
```

For a containerized experiment run:

```bash
docker compose run --rm --profile experiments runner
```

---

## 📦 Project Structure

```
emion/
├── emion/                  # Core Python package (BPv7, CGR, Dashboard)
│   ├── core/               # ION engine, scenarios, WLAN mobility
│   ├── dashboard/          # FastAPI server + static UI
│   ├── plugins/            # Module base classes (APIPlugin)
│   └── pyion/              # C-extension bindings for ION
├── examples/               # User-facing research examples
│   ├── ion_mars/           # CORE XML scenario (5 WLAN nodes)
│   ├── anomaly_detector/   # Sample ML inference module
│   └── core_services/      # CORE integration scripts
├── scripts/                # Maintenance & developer utilities
├── docs/                   # Coding guide & usage notebook
├── tests/                  # Test suite
├── Dockerfile              # Self-contained build
├── pyproject.toml          # Package config (v1.0)
├── LICENSE                 # MIT
└── CONTRIBUTING.md         # How to contribute
```

---

## 🤝 Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## 📜 License

MIT License — see [LICENSE](LICENSE).

---

**Authentic. Professional. Space-Ready.** ⚛️

Built by **Team DOMinators** using the real NASA-JPL ION-DTN engine.
