Stock Alert Workflow

Automated earnings surprise → analyst rating → WhatsApp alert pipeline.

What It Does

1. Fetches recent earnings data from Yahoo Finance (or local scraper output)
2. Filters for EPS surprises exceeding a threshold (default 10%)
3. Searches analyst ratings for qualifying tickers (last 30 days: consensus, target prices, upgrades/downgrades)
4. Pushes a formatted WhatsApp alert via wacli

Quick Start

Full scan (all tracked tickers):

python3 {baseDir}/scripts/earnings_surprise_alert.py

Single ticker:

python3 {baseDir}/scripts/earnings_surprise_alert.py --ticker NVDA

Custom threshold:

python3 {baseDir}/scripts/earnings_surprise_alert.py --threshold 15

Dry run (print without sending):

python3 {baseDir}/scripts/earnings_surprise_alert.py --dry-run

Specific WhatsApp recipient:

python3 {baseDir}/scripts/earnings_surprise_alert.py --recipient "+1234567890"

Alert Format

🚨 *Earnings Surprise Alert*

📈 *NVDA* (NVIDIA Corporation)
   EPS Est: 2.07
   EPS Actual: 2.70
   Surprise: 🟢 +30.43%

📊 *Analyst Ratings (30d)*
   Consensus: 🟢32 🟡6 🔴0
   Target: $175.00 (↑+12.3%)
   Goldman Sachs: Upgrade → Buy (2026-04-28)
   Morgan Stanley: Reiterate → Overweight (2026-04-25)

_⚠️ Not financial advice_

Data Sources

Configuration

• Threshold: --threshold flag (default 10%)
• WhatsApp recipient: --recipient flag or wacli_configs/config.yaml default
• Scraper config: scrapers/yahoo_finance_earnings.yaml
• Search config: search/google_search_config.yaml

Scheduling

Run daily via cron after market close:

# Example: 5 PM ET on weekdays
0 17 * * 1-5 python3 /path/to/earnings_surprise_alert.py

Limitations

• Yahoo Finance unofficial API may require rate limiting
• Analyst rating data depends on Yahoo Finance coverage
• WhatsApp delivery requires wacli to be configured and authenticated
• US-listed stocks only