quantwise 1.2.0 → 1.2.2

package/.claude/skills/value-dividend-screener/references/fmp_api_guide.md

@@ -0,0 +1,348 @@
+# Financial Modeling Prep (FMP) API Guide
+
+## Overview
+
+Financial Modeling Prep provides comprehensive financial data APIs for stocks, forex, cryptocurrencies, and more. This guide focuses on endpoints used for dividend stock screening.
+
+## API Key Setup
+
+### Obtaining an API Key
+
+1. Visit https://financialmodelingprep.com/developer/docs
+2. Sign up for a free account
+3. Navigate to Dashboard → API Keys
+4. Copy your API key
+
+### Free Tier Limits
+
+- **250 requests per day**
+- **Rate limit**: ~5 requests per second
+- **No credit card required**
+- Sufficient for daily/weekly screening runs
+
+### Paid Tiers (Optional)
+
+- **Starter ($14/month)**: 500 requests/day
+- **Professional ($29/month)**: 1,000 requests/day
+- **Enterprise ($99/month)**: 10,000 requests/day
+
+## Setting API Key
+
+### Method 1: Environment Variable (Recommended)
+
+**Linux/macOS:**
+```bash
+export FMP_API_KEY=your_api_key_here
+```
+
+**Windows (Command Prompt):**
+```cmd
+set FMP_API_KEY=your_api_key_here
+```
+
+**Windows (PowerShell):**
+```powershell
+$env:FMP_API_KEY="your_api_key_here"
+```
+
+**Persistent (add to shell profile):**
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+echo 'export FMP_API_KEY=your_api_key_here' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Method 2: Command-Line Argument
+
+```bash
+python3 scripts/screen_dividend_stocks.py --api-key your_api_key_here
+```
+
+## Key Endpoints Used
+
+### 1. Stock Screener
+
+**Endpoint:** `/v3/stock-screener`
+
+**Purpose:** Initial filtering by dividend yield, P/E, P/B, market cap
+
+**Parameters:**
+- `dividendYieldMoreThan`: Minimum dividend yield (e.g., 3.5)
+- `priceEarningRatioLowerThan`: Maximum P/E ratio (e.g., 20)
+- `priceToBookRatioLowerThan`: Maximum P/B ratio (e.g., 2)
+- `marketCapMoreThan`: Minimum market cap (e.g., 2000000000 = $2B)
+- `exchange`: Exchanges to include (e.g., "NASDAQ,NYSE")
+- `limit`: Max results (default: 1000)
+
+**Example Request:**
+```
+https://financialmodelingprep.com/api/v3/stock-screener?
+  dividendYieldMoreThan=3.5&
+  priceEarningRatioLowerThan=20&
+  priceToBookRatioLowerThan=2&
+  marketCapMoreThan=2000000000&
+  exchange=NASDAQ,NYSE&
+  limit=1000&
+  apikey=YOUR_API_KEY
+```
+
+**Response Format:**
+```json
+[
+  {
+    "symbol": "T",
+    "companyName": "AT&T Inc.",
+    "marketCap": 150000000000,
+    "sector": "Communication Services",
+    "industry": "Telecom Services",
+    "beta": 0.65,
+    "price": 20.50,
+    "lastAnnualDividend": 1.11,
+    "volume": 35000000,
+    "exchange": "NYSE",
+    "exchangeShortName": "NYSE",
+    "country": "US",
+    "isEtf": false,
+    "isActivelyTrading": true,
+    "dividendYield": 0.0541,
+    "pe": 7.5,
+    "priceToBook": 1.2
+  }
+]
+```
+
+### 2. Income Statement
+
+**Endpoint:** `/v3/income-statement/{symbol}`
+
+**Purpose:** Revenue, EPS, net income analysis
+
+**Parameters:**
+- `symbol`: Stock ticker (e.g., "AAPL")
+- `limit`: Number of periods (e.g., 5 for 5 years)
+- `period`: "annual" or "quarter"
+
+**Example Request:**
+```
+https://financialmodelingprep.com/api/v3/income-statement/AAPL?
+  limit=5&
+  apikey=YOUR_API_KEY
+```
+
+**Key Fields Used:**
+- `revenue`: Total revenue
+- `eps`: Earnings per share
+- `netIncome`: Net income
+- `date`: Fiscal period end date
+
+### 3. Balance Sheet Statement
+
+**Endpoint:** `/v3/balance-sheet-statement/{symbol}`
+
+**Purpose:** Debt, equity, liquidity analysis
+
+**Parameters:**
+- `symbol`: Stock ticker
+- `limit`: Number of periods
+
+**Key Fields Used:**
+- `totalDebt`: Total debt (short-term + long-term)
+- `totalStockholdersEquity`: Shareholders' equity
+- `totalCurrentAssets`: Current assets
+- `totalCurrentLiabilities`: Current liabilities
+
+### 4. Cash Flow Statement
+
+**Endpoint:** `/v3/cash-flow-statement/{symbol}`
+
+**Purpose:** Free cash flow, dividends paid analysis
+
+**Parameters:**
+- `symbol`: Stock ticker
+- `limit`: Number of periods
+
+**Key Fields Used:**
+- `operatingCashFlow`: Cash from operations
+- `capitalExpenditure`: Capex (negative value)
+- `dividendsPaid`: Dividends paid (negative value)
+- `freeCashFlow`: OCF - Capex
+
+### 5. Key Metrics
+
+**Endpoint:** `/v3/key-metrics/{symbol}`
+
+**Purpose:** ROE, ROA, and other quality metrics
+
+**Parameters:**
+- `symbol`: Stock ticker
+- `limit`: Number of periods
+
+**Key Fields Used:**
+- `roe`: Return on Equity (decimal, e.g., 0.15 = 15%)
+- `roa`: Return on Assets
+- `roic`: Return on Invested Capital
+- `debtToEquity`: Debt-to-equity ratio
+- `currentRatio`: Current ratio
+
+### 6. Historical Dividend
+
+**Endpoint:** `/v3/historical-price-full/stock_dividend/{symbol}`
+
+**Purpose:** Dividend history for growth rate calculation
+
+**Example Request:**
+```
+https://financialmodelingprep.com/api/v3/historical-price-full/stock_dividend/AAPL?
+  apikey=YOUR_API_KEY
+```
+
+**Response Format:**
+```json
+{
+  "symbol": "AAPL",
+  "historical": [
+    {
+      "date": "2024-11-08",
+      "label": "November 08, 24",
+      "adjDividend": 0.25,
+      "dividend": 0.25,
+      "recordDate": "2024-11-11",
+      "paymentDate": "2024-11-14",
+      "declarationDate": "2024-10-31"
+    }
+  ]
+}
+```
+
+## Rate Limiting Strategy
+
+### Built-in Protection
+
+The screening script includes rate limiting:
+- **0.3 second delay** between requests (~3 requests/second)
+- **Automatic retry** on 429 (rate limit exceeded) with 60-second backoff
+- **Timeout**: 30 seconds per request
+
+### Managing Request Budget
+
+For free tier (250 requests/day):
+
+**Requests per stock analyzed:**
+- Stock Screener: 1 request (returns 100-1000 stocks)
+- Income Statement: 1 request per symbol
+- Balance Sheet: 1 request per symbol
+- Cash Flow: 1 request per symbol
+- Key Metrics: 1 request per symbol
+- Dividend History: 1 request per symbol
+
+**Total: 5 requests per symbol + 1 screener request**
+
+**Budget allocation:**
+- Initial screener: 1 request
+- Detailed analysis: 5 × N stocks = 5N requests
+- **Maximum stocks per run**: (250 - 1) / 5 = ~49 stocks
+
+**Script default**: Analyzes first 100 candidates but typically finds ~20-30 that pass all criteria
+
+### Best Practices
+
+1. **Run during off-peak hours**: Lower chance of rate limits
+2. **Space out runs**: Once daily or weekly, not multiple times per hour
+3. **Cache results**: Save JSON output and analyze locally
+4. **Upgrade if needed**: If screening large universes frequently, consider paid tier
+
+## Error Handling
+
+### Common Errors
+
+**1. Invalid API Key**
+```json
+{
+  "Error Message": "Invalid API KEY. Please retry or visit our documentation."
+}
+```
+**Solution**: Check API key, verify it's active in FMP dashboard
+
+**2. Rate Limit Exceeded (429)**
+```json
+{
+  "Error Message": "You have exceeded the rate limit. Please wait."
+}
+```
+**Solution**: Script automatically retries after 60 seconds
+
+**3. Symbol Not Found**
+```json
+{
+  "Error Message": "Invalid ticker symbol"
+}
+```
+**Solution**: Script skips symbol and continues (expected for delisted/invalid tickers)
+
+**4. Insufficient Data**
+- Empty array returned for financial statements
+**Solution**: Script skips symbol (common for newly listed stocks or incomplete data)
+
+### Debugging
+
+**Check request count:**
+```bash
+# Count API calls in script output
+python3 scripts/screen_dividend_stocks.py 2>&1 | grep "Analyzing" | wc -l
+```
+
+**Verbose mode (add to script if needed):**
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+## Data Quality Considerations
+
+### Data Freshness
+
+- **Annual statements**: Updated after fiscal year end (delays possible)
+- **Quarterly data**: Available ~1-2 months after quarter end
+- **Real-time prices**: Updated during market hours
+- **Dividend history**: Updated after declaration/payment
+
+### Data Gaps
+
+Some stocks may have:
+- **Incomplete history**: < 4 years of data (newly public companies)
+- **Missing dividends**: Not all dividend-paying stocks report via API
+- **Inconsistent metrics**: Different accounting standards, restatements
+
+**Script behavior**: Skips stocks with insufficient data (requires 4+ years)
+
+### Data Accuracy
+
+FMP sources data from:
+- SEC EDGAR filings (US companies)
+- Company investor relations
+- Exchange data feeds
+
+**Note**: Always verify critical investment decisions with company filings (10-K, 10-Q)
+
+## API Documentation
+
+**Official Docs**: https://financialmodelingprep.com/developer/docs
+
+**Key Sections:**
+- Stock Fundamentals API
+- Stock Screener API
+- Historical Dividend API
+- Ratios API
+
+**Support**: support@financialmodelingprep.com
+
+## Alternative Data Sources
+
+If FMP limits are restrictive:
+
+1. **Alpha Vantage**: Free tier, 500 requests/day
+2. **Yahoo Finance (yfinance)**: Free, unlimited (but less reliable)
+3. **Quandl/Nasdaq Data Link**: Free tier available
+4. **IEX Cloud**: Free tier, 50k messages/month
+
+**Note**: Alternative sources may require script modifications for different data formats.

package/.claude/skills/value-dividend-screener/references/screening_methodology.md

@@ -0,0 +1,315 @@
+# Value Dividend Stock Screening Methodology
+
+## Overview
+
+This screening methodology identifies high-quality dividend stocks that combine:
+- **Value characteristics**: Reasonable valuations (low P/E, P/B)
+- **Income generation**: Attractive dividend yields (>=3.5%)
+- **Growth profile**: Consistent dividend, revenue, and EPS growth
+- **Quality metrics**: Strong profitability, financial health, and dividend sustainability
+
+## Screening Criteria
+
+### Phase 1: Initial Quantitative Filters
+
+#### 1. Dividend Yield >= 3.5%
+**Rationale**: Provides meaningful income above typical market yields (S&P 500 average: ~1.5-2%)
+
+**Calculation**:
+```
+Dividend Yield = (Annual Dividends per Share / Current Stock Price) × 100
+```
+
+**Threshold Logic**:
+- 3.5%+ provides attractive income
+- Not so high as to signal dividend risk (>8% often unsustainable)
+- Balances income and growth potential
+
+#### 2. P/E Ratio <= 20
+**Rationale**: Identifies stocks trading at reasonable multiples relative to earnings
+
+**Calculation**:
+```
+P/E Ratio = Market Price per Share / Earnings per Share (TTM)
+```
+
+**Threshold Logic**:
+- S&P 500 historical average: ~15-18x
+- P/E <= 20 indicates value territory
+- Excludes overvalued growth stocks
+- Focuses on mature, profitable companies
+
+#### 3. P/B Ratio <= 2.0
+**Rationale**: Ensures stock price is reasonable relative to book value
+
+**Calculation**:
+```
+P/B Ratio = Market Price per Share / Book Value per Share
+```
+
+**Threshold Logic**:
+- P/B <= 2.0 suggests reasonable valuation
+- Avoids paying excessive premium over net assets
+- Particularly relevant for asset-heavy businesses
+
+### Phase 2: Growth Quality Filters
+
+#### 4. Dividend Growth: 3-Year CAGR >= 5%
+**Rationale**: Identifies companies with consistent dividend-raising track record
+
+**Calculation**:
+```
+Dividend CAGR = [(End Dividend / Start Dividend)^(1/3) - 1] × 100
+```
+
+**Threshold Logic**:
+- 5% annual growth compounds meaningfully over time
+- Demonstrates management confidence in cash flows
+- Protects against inflation (long-term average: 2-3%)
+- Signals business health and shareholder commitment
+
+**Consistency Check**:
+- No dividend cuts in the period
+- Allows one year of flat dividends (economic cycles)
+- Cuts signal financial stress or strategy changes
+
+#### 5. Revenue Growth: Positive 3-Year Trend
+**Rationale**: Confirms top-line growth supports dividend sustainability
+
+**Evaluation**:
+- Revenue in Year 3 > Revenue in Year 1
+- Allows one year of decline (cyclical businesses, one-time events)
+- Overall upward trajectory required
+
+**Why Not a Fixed %**:
+- Different industries have different growth rates
+- Mature dividend stocks may have modest but stable growth
+- Focus is on **trend direction** rather than absolute rate
+
+#### 6. EPS Growth: Positive 3-Year Trend
+**Rationale**: Ensures earnings power is expanding, not eroding
+
+**Evaluation**:
+- EPS in Year 3 > EPS in Year 1
+- Allows one year of decline
+- Overall upward trajectory required
+
+**Significance**:
+- Earnings fund dividends
+- EPS growth = potential for future dividend increases
+- Distinguishes quality companies from dividend traps
+
+### Phase 3: Quality & Sustainability Analysis
+
+#### 7. Dividend Sustainability Metrics
+
+**A. Payout Ratio**
+```
+Payout Ratio = (Dividends Paid / Net Income) × 100
+```
+
+**Healthy Range**: 30-70%
+- < 30%: Conservative, room for growth
+- 30-70%: Balanced, sustainable
+- > 80%: Caution, limited flexibility
+
+**B. Free Cash Flow Payout Ratio**
+```
+FCF Payout Ratio = (Dividends Paid / Free Cash Flow) × 100
+where FCF = Operating Cash Flow - Capital Expenditures
+```
+
+**Healthy Range**: < 100%
+- FCF is the true source of sustainable dividends
+- < 100%: Dividends covered by actual cash generation
+- > 100%: Unsustainable, funded by debt or asset sales
+
+**Sustainability Flag**: ✅ if Payout Ratio < 80% AND FCF Payout Ratio < 100%
+
+#### 8. Financial Health Metrics
+
+**A. Debt-to-Equity Ratio**
+```
+D/E Ratio = Total Debt / Shareholders' Equity
+```
+
+**Healthy Range**: < 2.0
+- Lower is generally better
+- Varies by industry (utilities typically higher)
+- < 2.0: Reasonable leverage, not overleveraged
+
+**B. Current Ratio**
+```
+Current Ratio = Current Assets / Current Liabilities
+```
+
+**Healthy Range**: > 1.0 (ideally > 1.5)
+- > 1.0: Can cover short-term obligations
+- > 1.5: Strong liquidity cushion
+- < 1.0: Liquidity risk
+
+**Health Flag**: ✅ if D/E < 2.0 AND Current Ratio > 1.0
+
+#### 9. Quality Score (0-100)
+
+**Components**:
+
+**A. Return on Equity (ROE)** - Max 50 points
+```
+ROE = Net Income / Shareholders' Equity
+
+Points = min((ROE% / 20%) × 50, 50)
+```
+
+- 20%+ ROE = 50 points (excellent capital efficiency)
+- 10% ROE = 25 points (average)
+- < 5% ROE = poor capital returns
+
+**B. Net Profit Margin** - Max 50 points
+```
+Profit Margin = (Net Income / Revenue) × 100
+
+Points = min((Margin% / 15%) × 50, 50)
+```
+
+- 15%+ margin = 50 points (highly profitable)
+- 7.5% margin = 25 points (average)
+- < 3% margin = low profitability
+
+**Quality Score Interpretation**:
+- 80-100: Excellent quality (high profitability, efficiency)
+- 60-79: Good quality
+- 40-59: Average quality
+- < 40: Below average quality
+
+## Composite Scoring System
+
+### Purpose
+Rank stocks by overall attractiveness, balancing value, growth, and quality.
+
+### Score Components (Total: 100 points)
+
+1. **Dividend Growth** (Max 20 points)
+   - 10%+ CAGR = 20 points
+   - 5% CAGR = 10 points
+   - Linear scaling
+
+2. **Revenue Growth** (Max 15 points)
+   - 10%+ CAGR = 15 points
+   - 5% CAGR = 7.5 points
+   - Linear scaling
+
+3. **EPS Growth** (Max 15 points)
+   - 15%+ CAGR = 15 points
+   - 7.5% CAGR = 7.5 points
+   - Linear scaling
+
+4. **Dividend Sustainability** (10 points)
+   - Pass (sustainable) = 10 points
+   - Fail = 0 points
+
+5. **Financial Health** (10 points)
+   - Pass (healthy) = 10 points
+   - Fail = 0 points
+
+6. **Quality Score** (Max 30 points)
+   - Quality Score × 0.3
+   - 100 quality = 30 points
+   - 50 quality = 15 points
+
+### Interpretation
+
+- **80-100**: Exceptional (high growth, quality, sustainability)
+- **60-79**: Strong (solid all-around profile)
+- **40-59**: Good (meets criteria, some trade-offs)
+- **20-39**: Acceptable (passes filters but lower quality)
+- **< 20**: Marginal (barely meets criteria)
+
+## Investment Philosophy
+
+### Why This Approach Works
+
+1. **Value + Growth + Quality**: Combines three proven factor premiums
+2. **Dividend Focus**: Signals management discipline and cash generation
+3. **Sustainability Screen**: Avoids dividend traps and value traps
+4. **Growth Requirements**: Ensures businesses are healthy, not declining
+5. **Quality Filters**: Identifies durable competitive advantages
+
+### What This Strategy Avoids
+
+1. **Dividend Traps**: High yields from struggling companies (growth filters catch these)
+2. **Value Traps**: Cheap stocks that stay cheap (quality metrics catch these)
+3. **Overvaluation**: Growth stocks trading at expensive multiples (P/E, P/B filters)
+4. **Financial Risk**: Overleveraged or illiquid companies (health metrics)
+
+### Ideal Candidate Profile
+
+A stock scoring highly in this screen typically:
+- Operates in stable, mature industry
+- Has sustainable competitive advantage (moat)
+- Generates consistent free cash flow
+- Committed to shareholder returns (dividends)
+- Trades at reasonable valuation (not hyped)
+- Growing modestly but consistently
+- Strong balance sheet and profitability
+
+Examples: Dividend Aristocrats, quality REITs (if included), stable utilities, consumer staples leaders
+
+## Usage Notes
+
+### Limitations
+
+1. **Market Cap Bias**: Typically finds large/mid-cap stocks (small-caps less likely to meet all criteria)
+2. **Sector Bias**: May overweight certain sectors (utilities, consumer staples, REITs)
+3. **Excludes High Growth**: Tech and growth stocks generally won't qualify (by design)
+4. **Historical Performance**: Past growth doesn't guarantee future results
+5. **Economic Sensitivity**: Some qualified stocks may be cyclical
+
+### Best Practices
+
+1. **Diversification**: Don't concentrate in top 5; spread across top 20
+2. **Sector Balance**: Monitor sector exposure, avoid overconcentration
+3. **Rescreen Regularly**: Quarterly or semi-annually; fundamentals change
+4. **Valuation Check**: Just because it passed doesn't mean buy at any price
+5. **Dividend Safety**: Monitor payout ratios and cash flows quarterly
+6. **Hold for Long Term**: This is a quality dividend growth strategy, not trading
+
+### When to Sell
+
+1. **Dividend Cut**: Immediate red flag; review business health
+2. **Deteriorating Fundamentals**: Revenue/EPS declining multiple quarters
+3. **Payout Ratio > 100%**: Dividend unsustainable
+4. **Debt Spike**: Leverage increasing significantly without clear reason
+5. **Better Opportunities**: Capital allocation to higher-scoring stocks
+6. **Valuation Extreme**: Stock becomes significantly overvalued (P/E > 30, for example)
+
+## Historical Context
+
+### Why 3.5% Yield Threshold?
+
+- **US 10-Year Treasury**: Historically 2-4%
+- **S&P 500 Dividend Yield**: 1.5-2%
+- **Equity Risk Premium**: 3.5% provides ~1.5-2% premium over Treasuries
+- **Tax Efficiency**: Qualified dividends taxed favorably vs. bonds
+
+### Why P/E <= 20?
+
+- **S&P 500 Historical Average**: ~15-18x
+- **Fair Value Range**: 15-20x for mature, stable businesses
+- **Margin of Safety**: Leaves room for multiple compression
+- **Cyclically Adjusted**: Not overpaying at peak earnings
+
+### Why 5% Dividend CAGR?
+
+- **Inflation Protection**: Beats long-term inflation (2-3%)
+- **Real Income Growth**: Provides rising purchasing power
+- **Achievable**: Sustainable for quality companies
+- **Compound Power**: 5% doubles in 14.4 years
+
+## References
+
+- Benjamin Graham: "The Intelligent Investor" (value investing principles)
+- Jeremy Siegel: "The Future for Investors" (dividend growth research)
+- CFA Institute: Equity Valuation standards
+- S&P Dow Jones Indices: Dividend Aristocrats methodology
+- Morningstar: Dividend Sustainability Research