S&P 500 / NASDAQ Screener
Instructions
Step 1 — Load the universe
references/sp500-constituents.md and references/nasdaq100-constituents.md hold dated snapshots; scripts/provider.py parses them into the symbol list.
Step 2 — Parse the filter
Supported: indicator thresholds (RSI < 30), moving-average relations (price > EMA200), fundamentals (P/E < 15), sector filters. See references/screening-criteria.md.
Step 3 — Batch-compute per symbol
Run: python scripts/screen.py --index sp500 --filter "rsi<30" It batch-fetches EOD closes via scripts/provider.py (retry-with-backoff then raise; a symbol with no data is skipped, not faked) and computes RSI/EMA per symbol with scripts/indicators.py.
Step 4 — Rank and return
Table: symbol, matched criteria, the ranking metric, sector. Note the constituent-snapshot date.
Examples
User says: "S&P 500 names oversold on RSI, sorted by market cap" Result: ranked table of symbols with RSI < 30, largest first.
User says: "chart the 15 most-oversold NASDAQ-100 names" Result: the ranked table plus an optional interactive HTML bar chart (scripts/chart.py) — one accent-hued bar per symbol, direct-labelled with the RSI value, with per-bar hover and a table view.
Visualization (optional)
A chart is produced only when it clarifies the answer or the user asks — never forced, never as ASCII. When it helps, scripts/chart.py renders a self-contained interactive HTML bar chart: the matched symbols ranked by the filter metric, one accent-hued (--s1) bar each with a direct symbol + value label, a recessive axis, per-bar hover, a table view, and a light/dark toggle. The ranked text table stays the primary output.
Gotchas
- Constituent lists drift on rebalance — output notes the snapshot date.
- A full 500-symbol scan is heavy; cap and cache.
Troubleshooting
Error: "Scan too slow / rate limited"
Cause: per-symbol live calls across the whole universe. Solution: batch, cache EOD locally, cap universe size per query.
Bundled Resources
- scripts/screen.py — ranked JSON screen over an index universe (primary path).
- scripts/provider.py — robust batch fetch + universe load + filter/rank.
- scripts/indicators.py — pure-Python RSI/EMA/MACD used by the screen.
- scripts/chart.py — optional interactive HTML ranked-bar chart.
- scripts/viz.py — self-contained HTML/SVG chart generator (reused palette).
- references/sp500-constituents.md, references/nasdaq100-constituents.md — dated snapshots.
- references/screening-criteria.md — supported filter grammar.