Universal Adaptive Decision Engine (U-ADE)

A single AI system that adapts to changing environments by detecting concept drift, adapting models incrementally, adjusting thresholds dynamically, and explaining decisions over time.

Key Features

• Concept Drift Detection: Implements various algorithms like ADWIN, DDM, and Multi-variate Drift Detection to identify shifts in data distribution over time.
• Incremental Model Adaptation: Adapts machine learning models (e.g., Simple Averaging, Incremental Naive Bayes) to new data concepts without retraining from scratch, allowing for continuous learning.
• Dynamic Threshold Adjustment: Automatically adjusts drift detection thresholds based on model performance, enhancing adaptability and reducing false positives/negatives.
• Explainable Decisions: Provides insights into why and how decisions are made, particularly during periods of change.
• Expanded CLI Tooling: A comprehensive command-line interface for configuring, running, and analyzing drift detection experiments.
• Visualization Tools: Integration with matplotlib to generate and save plots of data streams and highlighted drift events, aiding in visual analysis.
• Web Dashboard: An interactive Flask-based web application for real-time monitoring and visualization of data streams and concept drift.
• Robust Error Handling & Recovery: Custom exception classes and structured error management ensure graceful degradation and clear diagnostics.

Installation

To set up the development environment, follow these steps:

1. Create and Activate Conda Environment:

   conda create -n u-ade-env python=3.9 -y
   conda activate u-ade-env

2. Install Dependencies: All required dependencies, including numpy, PyYAML, matplotlib, and Flask, along with the project itself, can be installed using pip:

   pip install -e .

   (Note: The pip install -e . command will automatically install all dependencies listed in pyproject.toml.)

Usage

U-ADE can be used via its command-line interface (CLI) for batch processing and plotting, or through its interactive web dashboard for real-time monitoring.

CLI Usage

The CLI tool uade allows you to run drift detection experiments with various configurations.

Basic Drift Detection (e.g., ADWIN with a CSV file):

uade --detector_type adwin --input_file data.csv --log_level INFO

Using an Incremental Naive Bayes Model with ADWIN:

uade --detector_type adwin --model_type incremental_naive_bayes --input_file data.csv --log_level DEBUG

Multi-variate Drift Detection with plotting to a file:

uade --detector_type multi_variate --detector_kwargs '{"num_features": 2}' --input_file temp_multivariate_data.csv --multivariate_input --plot --plot_output_file multivariate_drift.png

Processing in-memory data (scalar):

uade --detector_type ddm --input_data '[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.1, 0.2, 0.3, 0.9, 0.8, 0.7]' --plot

Web Dashboard Usage

The interactive web dashboard provides a visual interface for monitoring data streams and detected drifts in real-time.

1. Start the Flask Development Server: Navigate to the project root directory and run:

   conda run -n u-ade-env env FLASK_APP=src/u_ade/dashboard/app.py flask run --host=0.0.0.0

   This will start the server, typically accessible at http://127.0.0.1:5000/.

2. Access the Dashboard: Open your web browser and navigate to http://127.0.0.1:5000/. You can then start a simulated stream or send individual data points to see real-time drift detection and visualization.

Running Tests

To ensure the integrity and correctness of the U-ADE system, you can run all provided unit and integration tests:

conda run -n u-ade-env python3 -m unittest tests/test_drift_detection.py tests/test_api.py tests/test_integration.py tests/test_model_adaptation.py tests/test_streams.py

Known Issues

• filelock Vulnerability: Version 3.19.1 of the filelock dependency (which is installed in Python 3.9 environments) contains known vulnerabilities (GHSA-w853-jp5j-5j7f, GHSA-qmgc-5h2g-mvrw). Patched versions require Python 3.10 or newer. A long-term solution involves upgrading the Python environment. More details can be found in SECURITY.md.

Contributing

We welcome contributions! Please refer to our (forthcoming) CONTRIBUTING.md for guidelines.

License

This project is licensed under the LICENSE file.