Metadata-Version: 2.4
Name: sundew-algorithms
Version: 0.6.0
Summary: Sundew Algorithm — bio-inspired, energy-aware selective activation for edge AI systems.
Author-email: Oluwafemi Idiakhoa <oluwafemidiakhoa@gmail.com>
License: MIT License
        
        Copyright (c) ...
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        ...
        
Project-URL: Homepage, https://oluwafemidiakhoa.github.io
Project-URL: Repository, https://github.com/oluwafemidiakhoa/sundew_algorithms
Project-URL: Issues, https://github.com/oluwafemidiakhoa/sundew_algorithms/issues
Project-URL: Documentation, https://oluwafemidiakhoa.github.io
Project-URL: PyPI, https://pypi.org/project/sundew-algorithms/
Project-URL: DOI, https://doi.org/10.5281/zenodo.17118217
Project-URL: ORCID, https://orcid.org/0009-0008-7911-1171
Keywords: edge-ai,energy,gating,event-driven,ecg,computer-vision,adaptive-computation,selective-activation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: pandas>=1.5.0
Provides-Extra: dev
Requires-Dist: ruff>=0.13.0; extra == "dev"
Requires-Dist: mypy>=1.7; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: hypothesis>=6; extra == "dev"
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Provides-Extra: viz
Requires-Dist: matplotlib<4.0,>=3.7; extra == "viz"
Provides-Extra: video
Requires-Dist: opencv-python>=4.8; extra == "video"
Dynamic: license-file

﻿# Sundew Algorithms

Adaptive gating for energy-aware stream processing with reproducible evidence, layered precision uplift, and hardware readiness.

## Highlights
- Probe-aware presets (`custom_health_hd82`, `custom_breast_probe`) balance recall and energy; bootstrap confidence intervals capture statistical certainty.
- Layered classifier optional stage boosts precision to ~1.0 while preserving recall—plot available in `assets/layered_precision.png`.
- Stress-tested via ablations and adversarial streams with results logged in `data/results/ablation_study.csv` and `data/results/adversarial_runs/`.
- Hardware loop prepared: power capture template, runtime probe telemetry, and merge scripts connect simulation with device measurements.

![Layered Precision Uplift](assets/layered_precision.png)

## Run Everything
```
uv run python tools/run_full_evidence.py
```
This triggers the dataset suite, ablations, bootstrap metrics, layered classifier runs, and generates the precision plot.

Key artefacts land in `data/results/` and the main report (`docs/DATASET_BENCHMARK_REPORT.md`).

## Frequent Commands
- Dataset suite: `uv run python benchmarks/run_dataset_suite.py --presets tuned_v2 auto_tuned aggressive conservative energy_saver`
- Probe replay: `uv run python benchmarks/run_pipeline_dataset.py data/raw/breast_cancer_wisconsin_enriched.csv --preset custom_breast_probe --log data/results/runtime_probe_log.json`
- Layered classifier plot: `uv run python benchmarks/plot_layered_precision.py --out assets/layered_precision.png`
- Power capture (simulated): `uv run python tools/power_capture_template.py --events 569 --simulate`
- Merge runtime + power: `uv run python tools/merge_runtime_power.py`

## Evidence Sources
- `docs/DATASET_BENCHMARK_REPORT.md` – main metrics, probe trade-offs, bootstrap CIs.
- `docs/BREAST_CANCER_ACTION_PLAN.md` – enrichment tasks and probe telemetry.
- `docs/HARDWARE_VALIDATION_PLAN.md` & `docs/HARDWARE_REPLAY_CHECKLIST.md` – how to run on-device tests.
- `docs/LAYERED_CLASSIFIER_RESULTS.md` – precision uplift table for slides.
- `docs/STRESS_TEST_REPORT.md` – ablation and adversarial summaries.
- `docs/RUNTIME_MONITORING.md` – listener API and alert guidance.

## Preset Cheat Sheet
| Preset | Dataset | Recall | Savings | Notes |
| --- | --- | --- | --- | --- |
| custom_health_hd82 | Heart disease | ~0.196 | ~82% | Probe-free, bootstrap precision CI 0.679–0.828. |
| custom_breast_probe | Breast cancer | ~0.118 | ~77% | 19 probe activations (logged), enriched features. |
| auto_tuned | IoT/MIT BIH | dataset-dependent | 88–93% | General streaming baseline. |

## Validation Toolbox
- `benchmarks/run_ablation_study.py`
- `benchmarks/run_adversarial_stream.py`
- `benchmarks/bootstrap_metrics.py`

Reports and inspectable outputs live in `data/results/`.

## Hardware Workflow
1. Log Sundew telemetry with `benchmarks/run_pipeline_dataset.py`.
2. Capture watts using `tools/power_capture_template.py` (implement `read_power_sample`).
3. Merge via `tools/merge_runtime_power.py`.
4. Update docs with measured savings.

## Monitoring Hooks
`PipelineRuntime.add_listener(callback)` allows per-event logging. See `tools/runtime_monitor.py` for an example and `docs/RUNTIME_MONITORING.md` for alert ideas.

## Development Notes
- Tests: `uv run pytest`
- Extra deps: `uv pip install hypothesis matplotlib`
- Layered precision CSVs: `data/results/layered_precision*.csv`

## Citation
```
Idiakhoa, O. (2025). Adaptive Threshold Control for Energy-Efficient Stream Processing. Sundew Algorithms.
```
MIT License.
