An end-to-end analytics project that detects unusual revenue behavior, identifies the numerical drivers behind anomalies, and generates business-friendly AI explanations.
The project combines statistical anomaly detection, revenue driver analysis, Gemini AI, and an interactive Streamlit dashboard.
Business teams often monitor KPIs such as revenue, orders, and sales volume manually.
This project builds an automated workflow that:
- Cleans transaction-level retail data
- Calculates daily business KPIs
- Detects statistically unusual revenue behavior
- Identifies the metrics associated with each anomaly
- Generates grounded AI explanations
- Presents the results in an interactive dashboard
The statistical model determines whether an observation is anomalous.
AI is used only to interpret the detected metrics and does not decide whether an anomaly exists.
The project uses the Online Retail II dataset.
The raw dataset contains more than one million transaction records across two years.
- Raw rows: 1,067,371
- Rows after duplicate removal: 1,033,036
- Valid sales rows: 1,007,914
- Return/cancellation rows: 22,496
- Total analysed sales revenue: £20,476,634.02
Operational records such as cancellations and returns are preserved separately instead of being silently deleted.
Transaction-level data is aggregated into 604 daily observations.
The main KPIs are:
- Daily Revenue
- Orders
- Units Sold
- Average Order Value
- Cancellation Count
- Cancelled Units
- Cancellation Value
Revenue anomalies are detected using two complementary historical baselines.
For each day, revenue is compared with the previous 7 observations.
The model calculates:
- Rolling mean
- Rolling standard deviation
- Revenue deviation percentage
- Rolling Z-score
Only previous observations are used.
Revenue is also compared with previous observations from the same day of the week.
For example, a Monday is compared only with earlier Mondays.
This helps account for weekly trading patterns.
Importantly, future observations are never used to score earlier dates, preventing look-ahead leakage.
A day is flagged when:
|Rolling Z-score| >= 3
OR
|Historical Weekday Z-score| >= 3
The production detector identified:
| Result | Count |
|---|---|
| Daily observations | 604 |
| Detected anomalies | 37 |
| Revenue Spikes | 26 |
| Critical Revenue Spikes | 7 |
| Revenue Drops | 4 |
Revenue is decomposed as:
Revenue
=
Orders
× Units Per Order
× Average Price Per Unit
For detected critical anomalies, each component is compared with its recent historical baseline.
The system identifies:
- Primary Driver
- Secondary Driver
- Offsetting Factor
A 20% deviation threshold is used when assigning driver labels.
These labels represent numerical associations with the anomaly and should not be interpreted as proof of business causation.
For 09 Dec 2011:
Revenue: £200,918.98
Revenue deviation: +221.9%
Primary Driver:
Units Per Order +666.9%
Offsetting Factor:
Orders -60.3%
The metrics therefore show that the revenue spike was associated with unusually large quantities per order despite substantially fewer orders.
The project uses the Gemini API to translate anomaly metrics into concise business explanations.
The AI receives only the calculated anomaly statistics and driver information.
Prompt guardrails instruct the model to:
- Use only supplied numerical evidence
- Avoid inventing business causes
- Avoid unsupported speculation
- Clearly state when the underlying cause is unknown
- Recommend reviewing underlying transactions when necessary
AI explanations are therefore an interpretation layer, not the anomaly detection engine.
The project also includes an automated monitoring and alerting workflow.
When the agent runs, it:
- Rebuilds the daily KPI dataset
- Detects revenue anomalies
- Identifies critical revenue spikes
- Checks whether each anomaly has already been alerted
- Generates a Gemini explanation only for new anomalies
- Sends a Gmail alert containing the anomaly details
- Records successfully sent alerts to prevent duplicates
The alert history is stored locally in:
outputs/alert_log.csv
This runtime file is excluded from GitHub.
Each anomaly is identified using its:
Date + Anomaly Type
Before sending an email, the agent checks the alert history.
If an anomaly was already processed:
Existing anomaly
↓
Reuse saved AI explanation
↓
No Gemini API call
↓
No duplicate email
If a new critical anomaly is detected:
New anomaly
↓
Generate Gemini explanation
↓
Send Gmail alert
↓
Record successful alert
This prevents unnecessary API usage and repeated notifications.
The complete pipeline can be executed with:
python run_agent.pyFor Windows automation, the repository also includes:
run_agent.bat
The batch file launches the project's virtual-environment Python interpreter and writes execution logs to:
outputs/agent_run.log
The project can be scheduled through Windows Task Scheduler.
In the current setup, the anomaly agent runs automatically every day at:
09:00 AM
This turns the project from a static analytics dashboard into an automated monitoring system.
The Streamlit dashboard provides:
- Total Revenue
- Total Orders
- Detected Anomalies
- Critical Revenue Spikes
An interactive revenue time-series chart displays detected anomalies directly on the revenue trend.
Users can select an anomaly and inspect:
- Revenue
- Revenue deviation
- Primary driver
- Secondary driver
- Offsetting factor
- AI-generated business explanation
The dashboard also provides a summary table of all critical anomalies and their identified driver signals.
- Python
- Pandas
- NumPy
- OpenPyXL
- Altair
- Streamlit
- Google Gemini API
- Jupyter Notebook
AI_Anomaly_Agent/
│
├── data/
│ └── online_retail_II.xlsx
│
├── notebooks/
│ └── 01_anomaly_analysis.ipynb
│
├── outputs/
│ ├── daily_kpis_final.csv
│ └── anomaly_report_final.csv
│
├── screenshots/
│ ├── dashboard_overview.png
│ ├── anomaly_investigation.png
│ └── critical_spikes.png
│
├── src/
│ ├── data_processing.py
│ ├── anomaly_detection.py
│ ├── driver_analysis.py
│ ├── ai_explanation.py
│ ├── alert_log.py
│ └── email_alert.py
│
├── app.py
├── run_agent.py
├── run_agent.bat
├── requirements.txt
├── .gitignore
└── README.md
Clone the repository:
git clone https://github.com/Aljesh/AI_Anomaly_Agent.git
cd AI_Anomaly_AgentCreate a virtual environment:
python -m venv .venvActivate it on Windows:
.venv\Scripts\activateInstall dependencies:
pip install -r requirements.txtFrom the project root:
python -m streamlit run app.pyThen open the local Streamlit URL shown in the terminal.
Usually:
http://localhost:8501
The dashboard can display previously generated AI explanations from the saved anomaly report without making a new API request.
To regenerate AI explanations, create a Gemini API key and store it as an environment variable:
GEMINI_API_KEY
Never commit API keys to GitHub.
Historical baselines only use observations available before the date being evaluated.
The rolling baseline uses the previous 7 observations, not necessarily seven consecutive calendar days.
The Z-score threshold of 3 and driver threshold of 20% are heuristic business-analysis thresholds rather than statistically optimized values.
The dataset does not contain verified anomaly labels.
Therefore, metrics such as model accuracy, precision, recall, and F1-score are not claimed.
The system identifies metrics associated with unusual revenue behavior.
It does not prove the underlying causal business explanation.
Transaction-level investigation is required to establish the actual cause.
This project demonstrates how traditional analytics and generative AI can work together:
Transaction Data
↓
Data Cleaning
↓
Daily KPI Calculation
↓
Statistical Anomaly Detection
↓
Revenue Driver Analysis
↓
Grounded AI Explanation
↓
Interactive Streamlit Dashboard
Statistical methods detect the anomaly.
Business decomposition explains the numerical pattern.
Generative AI communicates the findings in a manager-friendly format.
- Add anomaly validation using labelled or synthetic anomalies
- Investigate anomalies at product and country level
- Add configurable anomaly thresholds
- Add date-range filtering
- Add automated data refresh
- Deploy the dashboard to a cloud platform