Dividend Picker

Screens Justin Law's U.S. Dividend Champions list with dividaat's 8-filter gate, adds HaSolidit deep-dive color from SEC EDGAR, and writes a grounded, human-readable report recommending which dividend-growth stocks to buy and flagging holdings that have deteriorated. It never trades or edits your portfolio automatically — it only recommends.

This README is written for Claude (the operator). It lists the exact commands.

Setup (once)

uv sync                 # create .venv and install deps
cp .env.example .env    # then edit .env: set EDGAR_USER_AGENT to "dividend-picker <your-email>"

EDGAR_USER_AGENT is required — SEC EDGAR rejects requests without a descriptive User-Agent containing a contact email.

The Champions list (automatic)

By default the tool pulls the live CCC dataset from dripinvesting.org's public JSON API (/wp-json/drip-investing/v1/stocks-dataset) — no login, no manual download. It keeps the 25+ year universe (stock_type Champion or King) and refreshes with the site. You don't need to do anything.

Overrides:

• CHAMPIONS_API_URL in .env — point at a different API URL.
• --champions PATH — use a downloaded spreadsheet (.xlsx/.xls/.csv) instead of the API (file-first parser with fuzzy header matching). Handy if the API is ever unavailable; drop the file at inputs/champions.xlsx or pass its path.

Run the flow (fixed steps)

These are the exact, repeatable steps to run the whole thing from scratch:

# 1. One-time setup (skip if already done)
uv sync
cp .env.example .env        # then set EDGAR_USER_AGENT="dividend-picker <your-email>"

# 2. Set your holdings — portfolio.json is private (gitignored); seed it from the template
cp portfolio.example.json portfolio.json   # then edit: set holdings to [] to start empty, or list what you own

# 3. Run the full screen (pulls the live list, screens, deep-dives, writes the report)
uv run dividend-picker run --all

# 4. Read the report
open outputs/$(date +%F)/report.md      # or just open outputs/<run-date>/report.md

The report is laid out as dividaat's own process: Step 1 hard screen → Step 2 narrow to finalists → Step 3 drill down the 1–2 finalists → suggested pick, then a full reference table and a per-company appendix.

Other commands:

uv run dividend-picker run --ticker MKC     # one company, end-to-end (smoke test)
uv run dividend-picker run --all --verbose  # DEBUG logging
uv run dividend-picker run --all --date 2026-09-02   # name the run folder explicitly
uv run pytest                                # run the test suite

Flags: --date YYYY-MM-DD (run-folder name, defaults to today), --verbose, and --champions PATH (use a downloaded spreadsheet instead of the live API).

Where output lands

outputs/<run-date>/
  report.md             <-- READ THIS: tables up top + full per-company detail below
  champions.csv         normalized snapshot of the list actually screened
  market_refs.json      S&P 500 yield & P/E thresholds used this run
  companies/<TICKER>/   (only gate survivors + your holdings are deep-dived)
    financials.json     EDGAR-derived metrics + HaSolidit computations
    filings/            downloaded official 10-K / 10-Q

Your portfolio lives in portfolio.json at the repo root and is only ever edited by you.

Tests

uv run pytest          # unit tests + ROP ground-truth smoke checks

The algorithm (summary)

1. Dividaat gate (hard pass/fail) — 8 filters: streak reaches back through the 2000 crisis (required years = run-year − 2000, e.g. ≥26 in 2026), yield > S&P 500 yield, P/E < S&P 500 P/E, payout < 60%, EPS growth (historical) > 0, market cap > $1B, debt/equity < 70%, dividend growth > 5% across 1/3/5/10y. Six come from the list feed (payout is derived from P/E, D/E from debt-to-capital); market cap and EPS growth are filled from SEC EDGAR during the deep-dive, then the gate is finalized.
2. HaSolidit color (survivors + holdings) — FCF payout coverage, margins & trend, ROIC/ROE, share-count trend, balance-sheet solvency, computed from SEC EDGAR companyfacts.
3. Valuation signal (advisory) — current yield vs. its history / P/E vs. its history → attractive / fair / rich, to prioritize buys.
4. Recommendation — BUY / WATCH / AVOID / SELL-FLAG, justified with the specific numbers.