Anomaly Detection & Explanation Agent

Project overview

Analysts and investors have to manually scan charts to catch abnormal price action. This tool flags statistically rare movements automatically and surfaces them with context, so the question shifts from "did anything unusual happen?" to "here's what happened, and here's what to check next."

Source: Yahoo Finance via the yfinance Python library, offering free, real, live daily OHLCV (open/high/low/close/volume) data.

Scope: Two years of daily trading history for AAPL, refreshed automatically.

Storage: SQLite, with separate tables for raw prices and flagged anomalies.

Methodology

Detect

Rolling 20-day mean and standard deviation of daily % price change; a day is flagged when it falls beyond a 2.5 standard deviation threshold from its own recent trailing behavior, not a fixed % cutoff, so the model adapts to each stock's normal volatility.

Explain

Each flagged anomaly is sent to Google Gemini with statistical context (z-score, % change, day of week), generating a short explanation plus a suggested next step for investigation.

Auto-refresh

The dashboard checks for new trading days on each visit (capped hourly) and automatically explains any newly-flagged anomaly.

Findings

When I checked where the flagged anomalies actually landed, they clustered around known high-volatility periods instead of showing up randomly. That told me the detection method was picking up something real, not just noise.
It's flagging roughly 1 event every ~22 trading days, which felt like the right balance to me: loose enough to catch real moves, tight enough that it's not crying wolf on every average trading day.
The biggest move it caught was -9.25% in a single day (z-score -4.58), a genuine outlier, not the kind of thing a shaky threshold stumbles into by accident.

Recommendations

The data pipeline, detection logic, and dashboard are fully built and live. Where I'm still stuck: the AI-explanation layer fails intermittently once deployed, and I'm working through Streamlit's live logs to track down why before I call it done. Next on my list: upgrading to Gemini's Google Search grounding so the explanations can point to real news events instead of just statistical context, once I get billing set up for it.

What this demonstrates

Adaptive statistical detection, not a fixed threshold; the model adjusts to each asset's own volatility.
Practical LLM integration through deliberate prompt design with real statistical context.
End-to-end deployment discipline, including honest tracking of what's still being debugged.