merkyorlynn/lynn/quant-scanner

Quant Scanner v1.0

Model-driven quantitative stock scanner for US equities. Scans ~100 large/mid-cap stocks, detects the current market regime, adaptively adjusts 5-factor scoring weights, and outputs ranked picks with an HTML report.

Setup

Required: A free Finnhub API key.

1. Go to https://finnhub.io and sign up (free)
2. Copy your API key from the dashboard
3. Set it as an environment variable:

export FINNHUB_API_KEY="your_key_here"

Or pass it directly via --api-key:

python3 {baseDir}/scripts/quant_scan.py --api-key YOUR_KEY

Quick Commands

Full Scan (HTML + JSON report)

python3 {baseDir}/scripts/quant_scan.py

This will:

1. Fetch quote, metrics, profile, and analyst recommendations for ~100 stocks
2. Detect market regime (volatility, momentum, breadth)
3. Score each stock on 5 adaptive factors
4. Output a ranked list + HTML report

Quick Top 10

python3 {baseDir}/scripts/quant_scan.py --top 10

Specific Tickers Only

python3 {baseDir}/scripts/quant_scan.py --tickers AAPL,NVDA,TSLA,GOOGL,META

Custom Universe File

python3 {baseDir}/scripts/quant_scan.py --universe my_watchlist.txt

Where my_watchlist.txt has one ticker per line.

JSON Output Only (for piping)

python3 {baseDir}/scripts/quant_scan.py --format json

How It Works

5-Factor Adaptive Scoring

Each stock is scored on 5 factors. The weights adapt to the detected market regime:

Market Regime Detection

The scanner analyzes the full universe to determine:

• Volatility Level — HIGH / MEDIUM / LOW (3-month average annualized std dev)
• Momentum Regime — BULLISH / NEUTRAL / BEARISH (13-week return distribution)
• Market Breadth — BROAD RALLY / MIXED / BROAD DECLINE (5-day positive percentage)

Data Sources (all free-tier Finnhub)

Default Universe (~100 stocks)

Mega Tech: AAPL, MSFT, GOOGL, AMZN, NVDA, META, TSLA Semiconductors: AVGO, AMD, INTC, QCOM, MU, MRVL, AMAT, LRCX, KLAC, ON, ARM Software/Cloud: CRM, ORCL, ADBE, NOW, SNOW, PLTR, PANW, CRWD, DDOG, NET, ZS, SHOP Financials: JPM, V, MA, BAC, GS, MS, BLK, SCHW, AXP, C Healthcare: UNH, LLY, JNJ, ABBV, PFE, MRK, TMO, ABT, BMY, GILD, AMGN, ISRG, VRTX Consumer: WMT, COST, HD, MCD, NKE, SBUX, TGT, LOW, PG, KO, PEP Energy: XOM, CVX, COP, SLB, EOG, OXY Industrials: CAT, GE, HON, UNP, BA, RTX, LMT, DE Others: NFLX, DIS, ABNB, UBER, COIN, SOFI, SMCI, MSTR China ADR: BABA, PDD, JD, BIDU, NIO, LI, XPEV

Output

HTML Report (default)

A styled, responsive HTML file with:

• KPI dashboard (top pick, market regime, key metrics)
• Market regime detection panel
• Model portfolio (top 5 with factor decomposition)
• Full selection ranking (top 30)
• Anomaly ranking (top 20)
• Sector distribution
• Regime-adaptive weight explanation table

JSON Report

Machine-readable output with all scored stocks, regime detection, and portfolio.

Limitations

• Finnhub free tier: 60 API calls/minute — scanning 100 stocks takes ~2 minutes
• No intraday candle data on free tier — uses metric endpoint for returns
• Returns are point-in-time snapshots, not a real backtest
• Not investment advice — research and monitoring only

Examples

User: scan the market and find me the best momentum plays
→ /quant_scan
 
User: what's the market regime right now?
→ /quant_regime
 
User: analyze NVDA AVGO AMD in detail
→ /quant_analyze NVDA AVGO AMD
 
User: give me a quick top 10 stock ranking
→ /quant_top

Use with Lynn (Zero Config)

Part of Lynn — a personal AI agent with memory and soul. Lynn has this built-in by default.

With Lynn desktop agent, quant-scanner works seamlessly:

• Natural language — just say "scan US stocks" or "what should I buy", Lynn auto-triggers the skill
• Memory integration — Lynn remembers your preferred tickers, past scan results, and investment style
• Multi-model routing — Lynn uses the best model for analysis (reasoning model for factor interpretation, fast model for data fetching)
• Scheduled scans — set up daily pre-market scans that run automatically
• Combined with A-share scanner — Lynn also has a Tushare-powered A-share quantitative scanner for Chinese stocks

# Install Lynn
git clone https://github.com/LynnMerkyor/Lynn.git
cd Lynn && npm install
 
# Then just chat:
# "scan the US market for me"
# "compare NVDA and AMD"
# "set up a daily pre-market scan"