Zacks Bull of the Day Tracker

A Python-based web application that daily scrapes Zacks Bull of the Day recommendations, tracks stock performance metrics from recommendation dates, and analyzes analyst performance.

Features

• Daily Scraping: Automatically scrapes new Zacks Bull of the Day recommendations
• Performance Tracking: Calculates growth metrics (4W, 13W, 6M, 1Y, YTD) from recommendation date
• Analyst Performance: Tracks and ranks analysts by their recommendation success rates
• Multiple Recommendations: Handles stocks recommended multiple times with timeline view
• Sector Categorization: Filter and analyze by sector
• Web Dashboard: Interactive dashboard with filtering and search
• Extensible Metrics: Easy to add new metrics via configuration

Requirements

• Python 3.9 or higher
• Internet connection
• ~500MB disk space

Installation

1. Clone or Download Project

cd "c:\Users\usdoss02\Satish-Playground\zach bull"

2. Install Dependencies

pip install -r requirements.txt

Note: Selenium requires ChromeDriver. Selenium 4.6+ will automatically download it, but you need Google Chrome browser installed. See docs/SELENIUM_SETUP.md for details.

3. Verify Installation

python -c "import yfinance; import flask; print('Dependencies installed successfully!')"

Quick Start

1. Initialize Database

The database will be created automatically on first run. You can also test it:

python -c "from src.data_manager import DataManager; dm = DataManager('./data/recommendations.db'); print('Database initialized!')"

2. Run Daily Job (Manual Test)

python run_daily.py

This will:

• Scrape new recommendations from Zacks
• Fetch stock prices and calculate metrics
• Save everything to the database
• Update analyst performance stats

3. Start Web Server

python app.py

Then open your browser to: http://localhost:5000

Configuration

Edit config/config.yaml to customize:

• Scraping settings: URLs, rate limits, retries
• Growth metrics: Enable/disable periods, adjust days
• Additional metrics: Add new metrics from yfinance
• Web server: Host, port, debug mode

Daily Execution Setup

Windows Task Scheduler

1. Open Task Scheduler
2. Create Basic Task
3. Name: "Zacks Bull Tracker Daily"
4. Trigger: Daily at 9:00 AM
5. Action: Start a program
6. Program: python
7. Arguments: C:\Users\usdoss02\Satish-Playground\zach bull\run_daily.py
8. Start in: C:\Users\usdoss02\Satish-Playground\zach bull

Linux/Mac Cron

crontab -e

Add this line (runs daily at 9 AM):

0 9 * * * cd /path/to/zach-bull && /usr/bin/python3 run_daily.py >> logs/cron.log 2>&1

Project Structure

zach-bull/
├── config/              # Configuration files
├── src/                 # Python source code
│   ├── scraper.py      # Web scraper
│   ├── stock_analyzer.py # Stock price & metrics
│   ├── analyst_tracker.py # Analyst performance
│   ├── data_manager.py  # Database operations
│   ├── main.py         # Daily orchestration
│   ├── api/            # API routes
│   └── metrics/        # Extensible metrics system
├── web/                 # Frontend
│   ├── templates/      # HTML templates
│   └── static/         # CSS, JS
├── data/               # Database and logs
├── reports/            # Generated reports
└── run_daily.py        # Daily job entry point

Usage

Web Dashboard

1. Start server: python app.py
2. Open browser: http://localhost:5000
3. Use filters to find stocks
4. Click on stocks to see detailed timeline
5. View analyst performance pages

API Endpoints

• GET /api/stocks - List all stocks (with filters)
• GET /api/stocks/<symbol> - Stock detail
• GET /api/analysts - List all analysts
• GET /api/analysts/<name> - Analyst detail
• GET /api/sectors - List all sectors
• GET /api/metrics - Available metrics

Command Line

# Run daily job manually
python run_daily.py

# Start web server
python app.py

Adding New Metrics

Edit config/config.yaml:

additional_metrics:
  metrics:
    - name: "new_metric"
      source: "yfinance"
      field: "fieldName"
      label: "Display Label"
      type: "float"
      enabled: true

The metric will automatically appear in the API and frontend!

Troubleshooting

Scraper fails to get data / Bot Detection

Important: Zacks website uses bot protection. The scraper now uses Selenium by default to bypass this.

If Selenium fails:

1. Install ChromeDriver: See docs/SELENIUM_SETUP.md for installation instructions
2. Check Chrome version: Make sure Chrome browser is installed and updated
3. Manual entry: Manually add sample data for testing (see docs/SCRAPING_NOTES.md)

See docs/SELENIUM_SETUP.md for Selenium setup and troubleshooting.

Scraper fails to get data

• Check internet connection
• Verify Zacks website is accessible
• Check rate limiting settings in config
• Check if bot protection is blocking requests (see docs/SCRAPING_NOTES.md)

Stock price not found

• Symbol might be incorrect
• Stock might be delisted
• Check yfinance API status

Database errors

• Ensure data directory exists
• Check file permissions
• Verify SQLite is working

Web server won't start

• Check if port 5000 is available
• Verify Flask is installed
• Check config.yaml syntax

Development

Running Tests

# Run all tests (when implemented)
python -m pytest tests/

Code Structure

• scraper.py: Handles web scraping with BeautifulSoup
• stock_analyzer.py: Fetches prices and calculates metrics using yfinance
• data_manager.py: SQLite database operations
• analyst_tracker.py: Calculates analyst performance
• main.py: Orchestrates daily workflow
• app.py: Flask web application

Data Storage

• Database: SQLite file at data/recommendations.db
• Logs: data/daily_logs/app.log
• Reports: reports/analyst_performance/YYYY-MM-DD.txt

Performance

• Daily job: Typically 5-15 minutes
• Database size: Grows with recommendations (~1KB per recommendation)
• Web server: Handles 100+ concurrent requests

Security Notes

• No authentication required (local use)
• Web scraping respects rate limits
• No sensitive data stored
• For production: Add authentication, use HTTPS

License

This project is for personal/educational use.

Support

For issues or questions:

1. Check logs in data/daily_logs/app.log
2. Review configuration in config/config.yaml
3. Verify all dependencies are installed

Next Steps

1. Run daily job to collect data
2. Access dashboard to view results
3. Customize metrics in config.yaml
4. Add features as needed

---

Happy Tracking! 📈