S&P 500 Momentum Tracker

A Python toolkit to track S&P 500 stocks hitting 52-week highs and all-time highs, analyze momentum patterns, and generate AI-driven recommendations (global and tech-screen views).

Features

• Momentum Tracking: Track how many times each stock hits 52W High or ATH over time
• Price & Volume Analysis: Monitor 1-day, 1-week, and 1-year price/volume changes
• AI Analysis (two reports): LangChain + GPT — all S&P at-highs (ai_analysis.md) and Information Technology + Communication Services only (ai_tech_analysis.md)
• History Augmentation: Names with strong cumulative hits but not “at high” today can still appear, ranked by % 1Y, market cap, and hits (see agent.py)

Project Structure

File	Description
tracker.py	Main orchestrator — snapshot, history, AI (passes full universe to agent for augmentation)
snapshot.py	Fetches current quotes, 52W high, ATH, price/volume changes
agent.py	LangChain + GPT — builds tables, generates global and tech AI markdown
high_history.py	Tracks momentum (hit count and dates) for each stock over time
tech_universe.py	Loads tech_tickers.txt and filters DataFrames for the tech report
fetch_tickers.py	Fetches full S&P 500 ticker list from Wikipedia → ticker.txt
fetch_tech_tickers.py	Fetches GICS Information Technology + Communication Services members → tech_tickers.txt
ticker.txt	List of S&P 500 tickers
tech_tickers.txt	Tech-screen tickers (IT + Communication Services); refresh with python fetch_tech_tickers.py
requirements.txt	Python dependencies

Output Files

All outputs are saved to the output/ directory:

File	Description
snapshot.txt	Latest stock data table
high_history.json	Momentum history (hit counts and dates)
high_history.txt	Human-readable momentum history
ai_analysis.md	Global AI analysis — all at-highs universe (newest at top)
ai_tech_analysis.md	Tech screen — IT + Communication Services only (newest at top)

Installation

pip install -r requirements.txt

Set your OpenAI API key (e.g. in the environment, or as required by your agent setup).

Usage

Main Tracker (tracker.py)

The main entry point that orchestrates the full pipeline.

# Full run: fetch prices, update history, generate AI (global + tech)
python tracker.py

# Use cached snapshot (skip yfinance API for prices)
python tracker.py --use-cache

# Specify a date for historical tracking
python tracker.py --date 2025-02-07

# History only: update high_history.json, skip AI
python tracker.py --history-only

# Analyze only: cached snapshot + high_history, regenerate both AI reports (no yfinance)
python tracker.py --analyze-only

Note: If no stocks are at 52W/ATH on the snapshot date, the tracker exits before AI. You need a snapshot with at least one at-high name to produce the markdown files.

Command-Line Options

Option	Short	Description
--use-cache	-c	Use cached snapshot.txt instead of fetching from yfinance API
--date DATE	-d	Date for tracking (YYYY-MM-DD). Defaults to today
--history-only	-H	Only update high_history.json, skip AI analysis
--analyze-only	-a	Use cached snapshot.txt and high_history.json, run AI only (no yfinance)

Individual Modules

# Fetch S&P 500 tickers and save to ticker.txt
python fetch_tickers.py

# Fetch IT + Communication Services tickers into tech_tickers.txt
python fetch_tech_tickers.py

# Fetch current quotes and save snapshot
python snapshot.py

# View high history summary
python high_history.py

Workflow Examples

Daily Run

python tracker.py

Fetches latest prices, updates momentum history, and writes both ai_analysis.md and ai_tech_analysis.md (if tech_tickers.txt exists and data qualifies).

Backfill Historical Data

python tracker.py --date 2025-02-01 --history-only

Use --history-only to backfill momentum data without running AI.

Re-run AI Analysis

python tracker.py --analyze-only

Regenerates both AI markdown files from snapshot.txt and high_history.json without calling yfinance for prices.

AI Analysis

The model uses hit frequency, % 1D / % 1W / % 1Y, volume vs prior day, distance from highs, and the “At high today” column (augmented names from history). The tech report restricts the table to tickers in tech_tickers.txt (GICS Information Technology and Communication Services).

Tech screen tickers (GICS)

• IT and Communication Services are both included so names like Alphabet (GOOG/GOOGL) and Meta (META) appear, since GICS classifies them under Communication Services, not IT.
• Refresh the list when the S&P 500 index changes: python fetch_tech_tickers.py.