# Design: Extended Strategies + Fundamental Data

**Date:** 2026-02-23
**Status:** Approved

## Summary

Add 6 new trading strategies and a fundamental data pipeline to the existing 3-strategy ensemble. Introduces fundamental analysis data (EPS, P/E, PEG, etc.) from three providers with rotation and DB-backed caching, plus additional technical indicators computed from existing OHLCV bars.

**Result:** 9-strategy weighted ensemble (3 existing + 6 new).

---

## 1. Fundamental Data Provider System

### 1.1 Architecture

New module `shared/fundamentals/` with a provider abstraction:

```
FundamentalsProvider (ABC)
├── AlphaVantageProvider  (25 req/day free tier)
├── FMPProvider           (250 req/day free tier)
├── YahooFinanceProvider  (no API key, yfinance library)
└── RotatingProvider      (wraps all three, rotates on rate limit)
```

### 1.2 Provider Interface

```python
class FundamentalsProvider(ABC):
    @abstractmethod
    async def fetch(self, ticker: str) -> FundamentalsSnapshot | None:
        """Fetch fundamental data for a single ticker."""

class RotatingProvider(FundamentalsProvider):
    """Tries providers in order, rotating to the next on rate limit or error."""
    def __init__(self, providers: list[FundamentalsProvider]): ...
    async def fetch(self, ticker: str) -> FundamentalsSnapshot | None: ...
```

### 1.3 Data Model

```python
class FundamentalsSnapshot(BaseModel):
    ticker: str
    eps_ttm: float | None = None          # Earnings per share (trailing 12 months)
    pe_ratio: float | None = None         # Price-to-earnings ratio
    peg_ratio: float | None = None        # Price/earnings-to-growth ratio
    revenue_growth_yoy: float | None = None  # Year-over-year revenue growth (decimal)
    profit_margin: float | None = None    # Net profit margin (decimal)
    debt_to_equity: float | None = None   # Total debt / shareholder equity
    market_cap: float | None = None       # Total market capitalization
    fetched_at: datetime                  # When this data was fetched
```

### 1.4 DB-Backed Caching

- New `fundamentals` table (Alembic migration required).
- On startup: load from DB. If `fetched_at` is within 24h, skip API calls.
- Daily refresh: background task re-fetches and updates DB.
- Prevents wasting free-tier API calls during local dev / restarts.

### 1.5 Configuration

New `.env` variables:
```
TRADING_ALPHA_VANTAGE_API_KEY=<key>
TRADING_FMP_API_KEY=<key>
TRADING_FUNDAMENTALS_CACHE_TTL_HOURS=24
```

No API key needed for Yahoo Finance (yfinance library).

---

## 2. New Technical Indicators

Computed in `MarketDataManager.get_snapshot()` from the existing OHLCV rolling window. No new data source needed.

### 2.1 Indicators

| Indicator | Computation | Added to MarketSnapshot |
|-----------|-------------|------------------------|
| MACD | EMA-12 minus EMA-26 | `macd: float \| None` |
| MACD Signal | EMA-9 of MACD line | `macd_signal: float \| None` |
| MACD Histogram | MACD minus signal | `macd_histogram: float \| None` |
| Bollinger Upper | SMA-20 + 2σ | `bollinger_upper: float \| None` |
| Bollinger Mid | SMA-20 | `bollinger_mid: float \| None` |
| Bollinger Lower | SMA-20 − 2σ | `bollinger_lower: float \| None` |
| VWAP | Cumulative(price × volume) / cumulative(volume) | `vwap: float \| None` |
| ATR (14) | Average true range, 14-period | `atr: float \| None` |
| EMA-9 | 9-period exponential moving average | `ema_9: float \| None` |
| EMA-21 | 21-period exponential moving average | `ema_21: float \| None` |
| SMA-200 | 200-period simple moving average | `sma_200: float \| None` |

### 2.2 Historical Bars Increase

`TRADING_HISTORICAL_BARS` bumped from 100 → 250 to support SMA-200 computation.

---

## 3. New Strategies (6 total)

All strategies implement `BaseStrategy.evaluate(ticker, market, sentiment) -> TradeSignal | None`.

### 3.1 Value Strategy (fundamental)

**File:** `shared/strategies/value.py`
**Name:** `"value"`

Uses fundamental data (EPS, P/E, PEG, profit margin, debt-to-equity).

| Condition | Signal |
|-----------|--------|
| PEG < 1.0 AND P/E < 25 AND EPS growth > 0 | LONG |
| PEG > 3.0 OR (P/E > 50 AND negative EPS growth) | SHORT |
| Strength: composite of how far metrics deviate from thresholds | 0–1 |

Fundamentals data passed via a new optional `fundamentals` field on `MarketSnapshot`:
```python
fundamentals: FundamentalsSnapshot | None = None
```

### 3.2 MACD Crossover Strategy (technical)

**File:** `shared/strategies/macd_crossover.py`
**Name:** `"macd_crossover"`

| Condition | Signal |
|-----------|--------|
| MACD crosses above signal line AND histogram > 0 | LONG |
| MACD crosses below signal line AND histogram < 0 | SHORT |
| Strength: abs(histogram) normalized by ATR | 0–1 |

Requires tracking previous MACD/signal values to detect crossovers. Stores last state per ticker in instance dict.

### 3.3 Bollinger Bands Breakout Strategy (technical)

**File:** `shared/strategies/bollinger_breakout.py`
**Name:** `"bollinger_breakout"`

| Condition | Signal |
|-----------|--------|
| Price above upper band + volume > 1.5× average | LONG (momentum breakout) |
| Price below lower band | LONG (mean reversion bounce) |
| Price was above upper band, now back inside | SHORT (failed breakout) |
| Strength: distance from band / band width | 0–1 |

### 3.4 VWAP Strategy (technical, intraday)

**File:** `shared/strategies/vwap.py`
**Name:** `"vwap"`

| Condition | Signal |
|-----------|--------|
| Price crosses above VWAP with increasing volume | LONG |
| Price crosses below VWAP with increasing volume | SHORT |
| Strength: distance from VWAP as % of price, weighted by volume ratio | 0–1 |

### 3.5 Liquidity Strategy (volume-based)

**File:** `shared/strategies/liquidity.py`
**Name:** `"liquidity"`

| Indicator | Computation |
|-----------|-------------|
| Relative Volume | Current volume / 20-bar average volume |
| Volume Trend | Slope of volume over recent bars |
| Volume-Price Divergence | Price moving without volume confirmation |

| Condition | Signal |
|-----------|--------|
| Relative volume > 2.0 AND price rising AND volume trend increasing | LONG |
| Relative volume > 2.0 AND price falling AND volume trend increasing | SHORT |
| Relative volume < 0.5 (thin liquidity) | Neutral — skip |
| Price rising on declining volume (divergence) | SHORT (weak rally) |
| Strength: relative volume magnitude, clamped to [0, 1] | 0–1 |

### 3.6 MA Stack Strategy (trend alignment)

**File:** `shared/strategies/ma_stack.py`
**Name:** `"ma_stack"`

Reads the full 5-MA stack: EMA-9, EMA-21, SMA-50, SMA-200 (plus price).

| Condition | Signal |
|-----------|--------|
| Full bull alignment: price > EMA-9 > EMA-21 > SMA-50 > SMA-200 | LONG, high strength |
| Partial bull: price > EMA-9 > EMA-21, below SMA-200 | LONG, lower strength |
| Full bear alignment: price < EMA-9 < EMA-21 < SMA-50 < SMA-200 | SHORT, high strength |
| Golden cross: SMA-50 crosses above SMA-200 | LONG boost |
| Death cross: SMA-50 crosses below SMA-200 | SHORT boost |
| MAs tangled / no clear order | Neutral — no signal |
| Strength: alignment count / 5, adjusted by fan spread | 0–1 |

---

## 4. Updated Ensemble

### 4.1 Default Weights (equal, 9 strategies)

```python
_DEFAULT_WEIGHTS = {
    "momentum": 0.111,
    "mean_reversion": 0.111,
    "news_driven": 0.111,
    "value": 0.111,
    "macd_crossover": 0.111,
    "bollinger_breakout": 0.111,
    "vwap": 0.111,
    "liquidity": 0.112,
    "ma_stack": 0.111,
}
```

### 4.2 Learning Engine

The existing learning engine (multi-armed bandit) will automatically adjust weights for the new strategies based on trade outcomes. No changes needed to the learning engine itself — it already handles arbitrary strategy names.

### 4.3 Strategy Seeding

`scripts/seed_strategies.py` updated to seed all 9 strategies into the `strategies` DB table.

---

## 5. Integration Points

### 5.1 Signal Generator Changes

1. Import and instantiate all 6 new strategies in `run()`.
2. Add fundamentals fetching as a background task (daily refresh).
3. Inject `FundamentalsSnapshot` into `MarketSnapshot.fundamentals` before calling ensemble.
4. Update `_DEFAULT_WEIGHTS` to include all 9 strategies.

### 5.2 MarketDataManager Changes

1. Add EMA computation method (exponential moving average).
2. Compute MACD, Bollinger, VWAP, ATR, EMA-9, EMA-21, SMA-200 in `get_snapshot()`.
3. Track previous MACD state for crossover detection (or let strategy handle it).

### 5.3 Schema Changes

1. Add new optional fields to `MarketSnapshot` (all technical indicators + fundamentals).
2. Add `FundamentalsSnapshot` Pydantic model.

### 5.4 Database Changes

1. New `fundamentals` table (Alembic migration).
2. Seed 6 new strategies via `seed_strategies.py`.

### 5.5 Configuration Changes

```env
TRADING_ALPHA_VANTAGE_API_KEY=M0I3TWB6VKU0UF51
TRADING_FMP_API_KEY=34zqbQFeRxYvPtzp3Y5QLKPVPztkZyfK
TRADING_FUNDAMENTALS_CACHE_TTL_HOURS=24
TRADING_HISTORICAL_BARS=250
```

### 5.6 Dependencies

```toml
# pyproject.toml — new deps
yfinance     # Yahoo Finance fundamentals (no API key)
# httpx/aiohttp already available for Alpha Vantage + FMP REST calls
```

---

## 6. File Changes Summary

### New Files
- `shared/fundamentals/__init__.py`
- `shared/fundamentals/base.py` — `FundamentalsProvider` ABC + `FundamentalsSnapshot`
- `shared/fundamentals/alpha_vantage.py` — Alpha Vantage provider
- `shared/fundamentals/fmp.py` — Financial Modeling Prep provider
- `shared/fundamentals/yahoo.py` — Yahoo Finance provider (yfinance)
- `shared/fundamentals/rotating.py` — `RotatingProvider` with failover
- `shared/strategies/value.py` — Value strategy
- `shared/strategies/macd_crossover.py` — MACD Crossover strategy
- `shared/strategies/bollinger_breakout.py` — Bollinger Breakout strategy
- `shared/strategies/vwap.py` — VWAP strategy
- `shared/strategies/liquidity.py` — Liquidity strategy
- `shared/strategies/ma_stack.py` — MA Stack strategy
- `alembic/versions/xxx_add_fundamentals_table.py` — Migration
- `tests/test_fundamentals.py` — Unit tests for providers
- `tests/test_new_strategies.py` — Unit tests for 6 new strategies
- `tests/test_indicators.py` — Unit tests for technical indicator computations

### Modified Files
- `shared/schemas/trading.py` — Add indicator fields to `MarketSnapshot`
- `services/signal_generator/market_data.py` — Add EMA, MACD, Bollinger, VWAP, ATR, SMA-200 computations
- `services/signal_generator/main.py` — Import new strategies, add fundamentals fetching, update weights
- `shared/strategies/__init__.py` — Export new strategies
- `scripts/seed_strategies.py` — Seed 6 new strategies
- `.env` — Add API keys and config
- `pyproject.toml` — Add yfinance dependency
- `shared/models/trading.py` — Add `Fundamentals` DB model (or new file in models/)