analyze-stock-kpi
Library-based stock KPI CLI: per-ticker fundamentals via yfinance plus a daily CNN Fear & Greed sentiment snapshot — no API keys, no scraping.
What
- Per-ticker fundamentals from yfinance — ~35 fields plus computed enrichments and
seven 0–100 composite "qte77 Score" proxies — persisted to
results/fundamentals/<UTC>.json.
- A daily CNN Fear & Greed sentiment snapshot (headline + subindicators) at
results/series/cnn_fg/YYYY.json, refreshed by a GitHub Actions cron.
- 9 bundled universes — watchlists, regional lists, aggregated best/worst — driven by an
inline list, a file, or a preset.
- A 13-column rich CLI table (P/E, PEG, Beta, ROE/ROA, Current, Sortino, Score, …)
with an optional composite-score breakdown.
- A static live dashboard (deployed to
GitHub Pages). It opens on Latest picks, the best and worst 25 stocks by qte77 Score
with the date they were last updated, under a collapsible Market mood bar (CNN F&G,
long-term context, 5s10s). Below it, Genuine decisions: a hypothetical, point-in-time
backtested long/short 25/25 book since 2026-05-31, with SPY's total return as a
reference line and one plain sentence on how it has done; its metrics, rebalance log (when,
why, and which names changed) and caveats are behind How it's tested. A second,
reconstructed backfill series since 2023 is its own collapsed section (an
approximation, never mixed with the genuine decisions). Both are equal-weight, shown gross
and net of a 10 bp turnover cost, across six rebalance cadences (see
ADR-0013). A sortable table of every
universe with row-click KPI detail sits behind "Browse all stocks" (a quick search,
/,
opens it filtered), and a collapsed Methodology section closes the page.
- No API keys, no scraping — keyless public sources only.
How
make setup_dev # uv sync (dev + test groups)
make run UNIVERSE=qte77-watchlist # fundamentals -> results/fundamentals/<UTC>.json
make run TICKERS=AAPL,MSFT # ad-hoc tickers (SHOW_SCORES=1 appends score columns)
make help # list available recipes
make validate # lint + types + complexity + md + tests
make preview # dashboard at http://localhost:8000/analyze-stock-kpi/ (PORT=8000)
CLI args double as env vars with the SSK_ prefix (e.g. SSK_TICKERS=AAPL,MSFT).
Per-ticker Sortino is reported at fixed 1y/3y/5y/10y/20y/30y windows plus an
optional operator-chosen frame via --sortino-from YYYY-MM-DD [--sortino-to YYYY-MM-DD] (--sortino-to defaults to each ticker's latest close), e.g.:
uv run python -m analyze_stock_kpi --tickers AAPL --sortino-from 2015-01-01 --sortino-to 2020-12-31
The dashboard keeps its state in the URL, so views can be shared. A parameter is omitted
while it has its default value, and clearing a filter in the UI removes it from the URL:
| Parameter | Values | Default |
|---|
universe | comma-separated universe ids, e.g. sp500 | the first universe |
date | snapshot date YYYY-MM-DD | latest |
sort / sortDir | a column key, e.g. composite_scores.screener_score / 1 = ascending | Score, descending |
filter | ticker/name text filter | none |
sector | sector name (from the donut) | none |
view | simple or detailed | simple |
ltFgWindow / ycWindow | 1y, 5y, 10y, all (a non-default value opens the Market mood panel on its long-term tab) | all |
theme | light, dark, system | the last choice (stored in the browser), else system |
base | data origin URL, e.g. a fork's raw.githubusercontent.com/<owner>/<repo>/data | this deployment's own data branch |
A non-default table parameter (universe, date, sort/sortDir, filter, sector,
view) opens the collapsed "Browse all stocks" section on load, so a shared table view is
visible straight away. The Methodology topics have stable anchors for linking: #methodology,
#why-charts, #why-universes, #backtest-rules and #decisions. On the page, / focuses
the quick search, and the arrow keys (plus Home/End) move between tabs.
See docs/architecture.md for the module map, the persisted
FundamentalsSnapshot fields, the composite-score formulas, and the universe presets.
Why
Fundamentals-plus-sentiment dashboards usually sit behind a paid data terminal or a
fragile scraping layer. analyze-stock-kpi fills the gap between a raw yfinance REPL and
a paid feed: a reproducible, keyless CLI + dashboard over public sources, versioned to
a data branch so the demo and the numbers stay auditable. See
docs/UserStory.md for product intent and non-goals.
References
License
Apache 2.0
