# AgomaX
Drone anomaly detection with ensemble models and YAML rules. Phase 1 (offline) and Phase 2 (live ingestion + live learn) are implemented.
## Usage
### Dashboard
Python entrypoint:
```python
import agomax
agomax.dashboard() # optional: port=8501, theme="dark", debug=True
```
### Programmatic API
```python
from agomax import api
# Train and save a model
pack = api.train("agomax/data/base.csv", output_model_dir="models/default")
# Detect on a CSV with a saved model
results = api.detect_csv("agomax/data/live.csv", model_dir="models/default")
# Adjust thresholds programmatically
current = pack.thresholds
tuned = api.tune_thresholds(current, {"kmeans": current["values"]["kmeans"] + 1.0})
# Live mode (CSV tail)
for out in api.start_live("agomax/data/live.csv", "models/default", refresh_seconds=0.5):
print(out)
# Simulator test (requires DroneKit/SITL or a provided source config)
from agomax.live_drone import LiveSourceConfig
rep = api.run_simulator_test(None, duration_seconds=60, baseline_rows=200)
print(rep)
```
## Phase 2 E2E Simulator (SITL)
Automates an end-to-end validation using ArduPilot SITL via DroneKit, with a realistic long-run protocol:
- Warmup 200 rows (ignored)
- Baseline 1000 rows (train live baseline)
- Detection for remaining rows, target ~12 minutes @ 10Hz (~7200 rows)
- Robust live iterator with reconnects, exponential backoff, and heartbeat
- Schema/NaN guards before scoring
- Explainability: KMeans per-feature contributions combined with Rules violations
- Sanity warnings when anomaly rate is very high
File: `phase2_e2e_sim.py`
Prerequisites (install in your virtualenv):
- Python 3.9+
- Packages from `requirements.txt`
- Optional (for this simulator): `dronekit`, `dronekit-sitl`
Notes:
- No project config changes are required; the script writes outputs under `agomax/data` and `agomax/output`.
- You can adjust baseline length, detection length, and rate (Hz) by editing the call in the `__main__` block.
- If you have your own telemetry source (CSV/UDP/real drone), use the CLI instead of SITL (see below).
Expected outputs:
- `agomax/data/live_base.csv` — baseline window captured from live feed
- `agomax/data/live_profile.json` — thresholds and scaling info learned from baseline
- `agomax/data/live.csv` — baseline + detection portion combined
- `agomax/output/live_anomalies.csv` — indices and flags for the detection portion
- Console PASS/FAIL report with top contributing features
Troubleshooting:
- If you see `No module named pytest` during local testing, install dev deps or run without tests.
- If SITL fails to start, ensure `dronekit-sitl` is installed and accessible in your environment.
Run (default long-run ~12 minutes):
```bash
/Users/shaguntembhurne/AgomaX/.venv/bin/python /Users/shaguntembhurne/AgomaX/phase2_e2e_sim.py
```
Tune parameters by editing the `__main__` call or importing `run_phase2_e2e(...)`.
## Live CLI
A minimal CLI is available:
- `agomax baseline` — captures a baseline from a chosen source and saves it to `agomax/data`
- `agomax live-drone` — learns from baseline then streams detections, printing basic stats
Sources supported: `csv_replay`, `udp_json`, `dronekit`. See `agomax/configs/live.yaml` for defaults.
## Streamlit Dashboard
Two pages are included:
- Offline Analysis — tune thresholds and rules, instant rescoring and visuals
- Live Monitoring — select source, start/stop, and view KPIs, timeline, and recent anomalies
## Development
- Python package metadata in `pyproject.toml`
- Tests under `tests/` and `agomax/tests/`
- Core modules in `agomax/core/`
- Live ingestion and pipeline in `agomax/live_drone.py`
- Config YAMLs in `agomax/configs/`
Raw data
{
"_id": null,
"home_page": null,
"name": "agomax",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "drone, anomaly-detection, streamlit, machine-learning, unsupervised, rules",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/91/f3/37991dfeed092f770628158a363acb53bcedf00f91fb072886455ffda3d2/agomax-0.2.1.tar.gz",
"platform": null,
"description": "# AgomaX\n\nDrone anomaly detection with ensemble models and YAML rules. Phase 1 (offline) and Phase 2 (live ingestion + live learn) are implemented.\n\n## Usage\n\n### Dashboard\n\nPython entrypoint:\n\n```python\nimport agomax\nagomax.dashboard() # optional: port=8501, theme=\"dark\", debug=True\n```\n\n### Programmatic API\n\n```python\nfrom agomax import api\n\n# Train and save a model\npack = api.train(\"agomax/data/base.csv\", output_model_dir=\"models/default\")\n\n# Detect on a CSV with a saved model\nresults = api.detect_csv(\"agomax/data/live.csv\", model_dir=\"models/default\")\n\n# Adjust thresholds programmatically\ncurrent = pack.thresholds\ntuned = api.tune_thresholds(current, {\"kmeans\": current[\"values\"][\"kmeans\"] + 1.0})\n\n# Live mode (CSV tail)\nfor out in api.start_live(\"agomax/data/live.csv\", \"models/default\", refresh_seconds=0.5):\n\tprint(out)\n\n# Simulator test (requires DroneKit/SITL or a provided source config)\nfrom agomax.live_drone import LiveSourceConfig\nrep = api.run_simulator_test(None, duration_seconds=60, baseline_rows=200)\nprint(rep)\n```\n\n## Phase 2 E2E Simulator (SITL)\n\nAutomates an end-to-end validation using ArduPilot SITL via DroneKit, with a realistic long-run protocol:\n- Warmup 200 rows (ignored)\n- Baseline 1000 rows (train live baseline)\n- Detection for remaining rows, target ~12 minutes @ 10Hz (~7200 rows)\n- Robust live iterator with reconnects, exponential backoff, and heartbeat\n- Schema/NaN guards before scoring\n- Explainability: KMeans per-feature contributions combined with Rules violations\n- Sanity warnings when anomaly rate is very high\n\nFile: `phase2_e2e_sim.py`\n\nPrerequisites (install in your virtualenv):\n- Python 3.9+\n- Packages from `requirements.txt`\n- Optional (for this simulator): `dronekit`, `dronekit-sitl`\n\nNotes:\n- No project config changes are required; the script writes outputs under `agomax/data` and `agomax/output`.\n- You can adjust baseline length, detection length, and rate (Hz) by editing the call in the `__main__` block.\n- If you have your own telemetry source (CSV/UDP/real drone), use the CLI instead of SITL (see below).\n\nExpected outputs:\n- `agomax/data/live_base.csv` \u2014 baseline window captured from live feed\n- `agomax/data/live_profile.json` \u2014 thresholds and scaling info learned from baseline\n- `agomax/data/live.csv` \u2014 baseline + detection portion combined\n- `agomax/output/live_anomalies.csv` \u2014 indices and flags for the detection portion\n- Console PASS/FAIL report with top contributing features\n\nTroubleshooting:\n- If you see `No module named pytest` during local testing, install dev deps or run without tests.\n- If SITL fails to start, ensure `dronekit-sitl` is installed and accessible in your environment.\n\nRun (default long-run ~12 minutes):\n\n```bash\n/Users/shaguntembhurne/AgomaX/.venv/bin/python /Users/shaguntembhurne/AgomaX/phase2_e2e_sim.py\n```\n\nTune parameters by editing the `__main__` call or importing `run_phase2_e2e(...)`.\n\n## Live CLI\n\nA minimal CLI is available:\n- `agomax baseline` \u2014 captures a baseline from a chosen source and saves it to `agomax/data`\n- `agomax live-drone` \u2014 learns from baseline then streams detections, printing basic stats\n\nSources supported: `csv_replay`, `udp_json`, `dronekit`. See `agomax/configs/live.yaml` for defaults.\n\n## Streamlit Dashboard\n\nTwo pages are included:\n- Offline Analysis \u2014 tune thresholds and rules, instant rescoring and visuals\n- Live Monitoring \u2014 select source, start/stop, and view KPIs, timeline, and recent anomalies\n\n## Development\n\n- Python package metadata in `pyproject.toml`\n- Tests under `tests/` and `agomax/tests/`\n- Core modules in `agomax/core/`\n- Live ingestion and pipeline in `agomax/live_drone.py`\n- Config YAMLs in `agomax/configs/`\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Drone anomaly detection with ensemble models and YAML rules",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://pypi.org/project/agomax/",
"Issues": "https://github.com/your-org/agomax/issues",
"Repository": "https://github.com/your-org/agomax"
},
"split_keywords": [
"drone",
" anomaly-detection",
" streamlit",
" machine-learning",
" unsupervised",
" rules"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6fcd77d60bdd4eb25da60c169566037045c207070cff40286648c088829a9260",
"md5": "3d0d4175a532550730ea1407ea9e3fdc",
"sha256": "ed45d17bbcaeec7632ed74a265eb61a92ac07e0c46227aba4da7a801b5addeb5"
},
"downloads": -1,
"filename": "agomax-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d0d4175a532550730ea1407ea9e3fdc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 433312,
"upload_time": "2025-08-14T12:38:12",
"upload_time_iso_8601": "2025-08-14T12:38:12.167218Z",
"url": "https://files.pythonhosted.org/packages/6f/cd/77d60bdd4eb25da60c169566037045c207070cff40286648c088829a9260/agomax-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "91f337991dfeed092f770628158a363acb53bcedf00f91fb072886455ffda3d2",
"md5": "60574097a9953cb5fcce06c1f2038f13",
"sha256": "6f70c7eb72b2ed106320c6ed602d65caed3337d1dd18db2c53f678ed1bd51ab2"
},
"downloads": -1,
"filename": "agomax-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "60574097a9953cb5fcce06c1f2038f13",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 437197,
"upload_time": "2025-08-14T12:38:14",
"upload_time_iso_8601": "2025-08-14T12:38:14.208969Z",
"url": "https://files.pythonhosted.org/packages/91/f3/37991dfeed092f770628158a363acb53bcedf00f91fb072886455ffda3d2/agomax-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 12:38:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "your-org",
"github_project": "agomax",
"github_not_found": true,
"lcname": "agomax"
}
JSON
