value-dividend-screener

value-dividend-screener identifies high-quality US dividend stocks by combining value characteristics (P/E under 20, P/B under 2), attractive yields (3%+), and consistent multi-year growth in dividends, revenue, and EPS. It solves the problem of dividend-trap and value-trap avoidance by layering quality and sustainability filters (payout ratios, free-cash-flow coverage, debt-to-equity, current ratio, ROE, and profit margins) on top of the basic screen, then ranking candidates by a composite quality score.

The skill implements a two-stage workflow driven by a Python script (`scripts/screen_dividend_stocks.py`). Stage one optionally uses the FINVIZ Elite API to pre-filter the universe cheaply; stage two runs detailed fundamental analysis through the Financial Modeling Prep (FMP) API, computing 3-year CAGRs, sustainability flags, and a 0-100 composite score before emitting a ranked JSON report. Using FINVIZ pre-screening is documented to cut FMP API calls by around 90%, which matters for free-tier users. Configuration covers top-N output, custom output paths, and explicit key passing. A reference methodology document details every threshold and scoring rule, and a test suite exercises the FMP integration.

It is aimed at income and value investors, portfolio builders, and quantitatively minded traders who want a reproducible, criteria-driven screen rather than ad hoc stock picking. API keys are read from environment variables (FMP_API_KEY, FINVIZ_API_KEY) following standard setup practice, and the tooling only reads market data — it performs no trading, ordering, or account actions.