# Multi-Strategy Stock Screener

A stock screener that scores companies through four investing philosophies and
ranks them into a single composite. Free data (Yahoo Finance via `yfinance`),
Python + Streamlit dashboard.

> **Educational / analytical tool — not investment advice.** Scores are
> relative fits to hand-tuned metric bands, *not* buy/sell signals. Free Yahoo
> fundamentals can be stale or missing. Always verify before acting.

## The four lenses

| Lens | Philosophy | Key signals |
|------|------------|-------------|
| **Buffett** | Quality-value, durable moats | ROE, low debt/equity, margins, FCF yield, P/E, margin of safety vs a rough DCF |
| **Burry** | Deep-value / contrarian | EV/EBITDA, P/B, P/S, FCF yield, closeness to 52w low, net-cash (net-net proxy) |
| **Roaring Kitty** | Deep value + catalyst + squeeze | short % of float, days-to-cover, value base, turning 1-month momentum |
| **Simons** | Quantitative (price/volume only) | mean-reversion z-score, RSI, 12-1 momentum, 6-month Sharpe |

Each lens outputs a 0–100 score. The sidebar lets you reweight the composite to
match your own conviction, and the deep-dive panel shows every sub-signal.

## Setup

```bash
cd finance-tool
python -m venv .venv
.venv\Scripts\activate            # Windows (PowerShell/CMD)
# source .venv/bin/activate       # macOS/Linux
pip install -r requirements.txt
```

## Run

```bash
streamlit run app.py
```

Then open http://localhost:8501. Pick a universe (Fallback 40 names, or the full
S&P 500), set weights, and click **Run screen** — or type specific tickers in the
sidebar box (e.g. `AAPL, GME, BRK-B`).

Tip: Yahoo rate-limits large scans. Start with the 40-name fallback or a subset
of the S&P 500, then widen.

## Project layout

```
finance-tool/
├── app.py                     # Streamlit dashboard
├── theme.py                   # Risk-of-Rain pixel skin + pixel-art Gup mascot
├── .streamlit/config.toml     # dark base theme (matches the canvas-rendered grid)
├── smoke_test.py              # offline logic test (no network)
├── requirements.txt
└── screener/
    ├── data.py                # yfinance access, normalised into StockData
    ├── universe.py            # ticker lists (S&P 500 + fallback)
    ├── scoring.py             # signal / normalisation primitives
    ├── engine.py              # run all strategies across a universe
    └── strategies/
        ├── buffett.py
        ├── burry.py
        ├── kitty.py
        └── simons.py
```

## Test

```bash
python smoke_test.py    # validates each lens scores a good profile > a bad one
```

## Roadmap (next slices)

- [ ] **Crash-risk dashboard** — market-wide indicators (Shiller CAPE, Buffett
      Indicator = market cap / GDP, yield-curve inversion, credit spreads, VIX,
      margin debt) via FRED, combined into a composite risk gauge. *This is risk
      monitoring, not crash prediction — no tool can reliably time crashes.*
- [ ] Backtesting — how each lens's top-N would have performed historically.
- [ ] SEC EDGAR fundamentals to fill gaps where Yahoo is thin.
- [ ] Swap-in adapter for a paid data provider (Polygon/Tiingo/FMP).
- [ ] Per-lens intrinsic-value / DCF detail views.

## How scoring works

Each strategy converts raw metrics into 0..1 sub-scores using
`higher_better` / `lower_better` ramps (see `scoring.py`), weights them, and
rescales to 0..100. Missing data is excluded from the weighted average, so
absent fields don't unfairly sink (or inflate) a stock. The composite is the mean of the four
lenses; the sidebar "Weighted" column applies your custom weights.
```