Equity Engine
A Russell 2000 screener that looks for large gaps between a defensible intrinsic value and
the market price. It prices all ~1,956 constituents every Friday morning for free, then
spends real analysis on ten names a week.
It recommends. You decide and you execute. There is no order-placement path anywhere in
this repository, by design.
How it works
Every Friday before the open, a GitHub Action prices the entire index and commits the
result. A scheduled Claude routine then reads that output, researches ten names, argues
against its own conclusions, and writes them into a permanent per-company record. The dashboard rebuilds
and Vercel redeploys on push.
The model is one two-stage DCF run in both directions. Backwards, it solves for the
5-year free-cash-flow growth rate that reproduces today's enterprise value — that is what
the market is already assuming. Forwards, it prices an assumption of our own. The
difference between those two numbers is the entire signal.
Ten names a week, split 6 / 4. Six by rotation, so the index eventually gets covered
end to end — at six a week a full pass takes roughly 326 weeks. Four by urgency — a hard
price move, a fresh 8-K, a sector-wide selloff, or an unusually wide gap — so a name that
halves while waiting its turn doesn't go unseen.
It refuses when it should. Roughly 40% of this universe cannot be honestly valued by a
free cash-flow model: banks and insurers (where debt is raw material, not financing) get a
residual-income model instead, and REITs and cash-burning biotech get no number at all.
Those names are marked, not guessed at.
Setup
pip install -r requirements.txt
export SEC_USER_AGENT="equity-engine <your-email>" # SEC 403s anonymous clients
python run.py screen --limit 40 # a quick slice to check everything works
python run.py pick
python run.py site && open public/index.html
For the scheduled version you need three things wired up:
- GitHub Action — set the
SEC_USER_AGENT repository secret under
Settings → Secrets and variables → Actions. The workflow runs Fridays at 10:23 UTC and
fails loudly if the data sources are unreachable.
- Vercel — point a project at this repo's
main branch. vercel.json already sets
public/ as the output directory; no build step is needed.
- The Claude routine — schedule an agent against this repo with the contents of
ROUTINE.md as its task, Fridays at 11:15 UTC (cron 15 11 * * 5), so it
starts after the screen has committed.
Layout
| path | what it is |
|---|
universe.csv | the frozen index: ticker, sector, and which valuation method applies |
edgar.py | SEC XBRL fundamentals, plus the durable extract in data/fundamentals.json |
prices.py | bulk end-of-day prices, returns, liquidity, beta |
valuation.py | the reverse DCF, the forward DCF, and the residual-income model |
screen.py | prices the whole universe — zero LLM tokens |
daily.py | picks the run's ten and records why each was picked |
brief.py | writes the self-contained research brief the analyst reads |
record.py | re-prices the analyst's assumption and commits it to memory |
research/ | append-only per-company record, organized by sector |
dashboard.py → public/ | the static site |
What it can't do
End-of-day prices only. Fundamentals come from annual filings and can be up to a year
stale. Nothing off-balance-sheet, no segment detail, nothing untagged in XBRL. A single
lumpy year still distorts a three-year cash-flow base — briefs flag the dispersion, but
flagging is not fixing. And the absolute size of any gap depends on the equity risk
premium and terminal growth chosen in config.py, which is why every gap is also reported
as a percentile against its own sector cohort.
Passing a screen is not an edge. Paper-trade it first.
