Avarice

A CNN-LSTM hybrid machine learning system for predicting optimal buy/sell signals on single-leg options contracts. Trains on historical data, backtests with realistic execution simulation, and supports live paper trading through Alpaca Markets.

Overview

Avarice uses a 3-stage CNN-LSTM-Attention neural network to classify options contracts as buy, hold, or sell based on 25 engineered features spanning Greeks, implied volatility metrics, and technical indicators on the underlying. The system targets the top 50 most liquid options tickers and enforces strict risk management rules.

Key capabilities:

• Black-Scholes Greeks computation with Newton-Raphson IV solver for historical data
• Walk-forward validation with anchored expanding windows (no future data leakage)
• Backtrader-based backtesting with slippage, commissions, and realistic order execution
• Paper trading via Alpaca Markets API with Half-Kelly position sizing
• Full CLI for every stage of the pipeline

Setup

Requirements

• Miniforge (mamba)
• Alpaca Markets API keys (free at alpaca.markets)

Installation

git clone <repo-url> && cd avarice

# Create environment
mamba env create -f environment.yml
mamba activate avarice

# Add your Alpaca API keys
echo "YOUR_API_KEY" > secrets/alpaca-key
echo "YOUR_SECRET_KEY" > secrets/alpaca-secret

Verify

pytest tests/ -v

Usage

All commands are run through the CLI:

mamba activate avarice

1. Fetch Historical Data

Download stock bars and option chain data from Alpaca:

# Dev set (5 tickers: SPY, QQQ, AAPL, TSLA, NVDA)
python -m avarice.main fetch-data --tickers dev --start-date 2024-02-01

# All 50 tickers
python -m avarice.main fetch-data --tickers all --start-date 2024-02-01

# Specific tickers
python -m avarice.main fetch-data --tickers "MSFT,GOOGL,META" --start-date 2024-02-01

2. Build Features

Compute the 25-feature matrix from cached data:

python -m avarice.main build-features --tickers dev

This runs the full feature pipeline: Greeks computation (via Black-Scholes when historical Greeks are missing), IV rank/percentile/skew, and technical indicators on the underlying.

3. Train Model

Train the CNN-LSTM with walk-forward validation:

python -m avarice.main train --device auto --tickers dev

--device auto selects CUDA > MPS > CPU. Training uses anchored expanding windows (~16 folds), early stopping, gradient clipping, and inverse-frequency class weighting. Checkpoints are saved to data/models/.

4. Backtest

Run a backtest on historical data with the trained model:

python -m avarice.main backtest --initial-cash 100000 --tickers dev

Produces a performance report (Sharpe ratio, max drawdown, win rate, profit factor) and saves an equity curve plot to data/models/equity_curve.png.

5. Paper Trade

Start live paper trading through Alpaca:

python -m avarice.main paper-trade --interval-minutes 15 --tickers dev

Runs trading cycles at the specified interval during market hours. Signals are generated, filtered, sized, and submitted as limit orders.

6. Check Status

python -m avarice.main status

Shows cached data counts, model checkpoints, and portfolio status.

Architecture

Model

Input (batch, 20, 25)
  -> CNN Block: Conv1d [32, 64, 128] channels, kernel=3, BatchNorm + ReLU + Dropout
  -> LSTM: 2 layers, hidden=128, dropout=0.3
  -> Attention: Linear(128->64) -> Tanh -> Linear(64->1) -> Softmax pooling
  -> Classifier: Linear(128->64->32->3) with ReLU + Dropout
Output: 3 classes [sell, hold, buy]

Confidence threshold of 0.65 — signals below this are discarded. The hold class acts as an uncertainty buffer.

25 Features

Category	Features
Greeks	delta, gamma, theta, vega, rho
Volatility	iv, iv_rank, iv_percentile, iv_skew
Contract	moneyness, dte_norm, bid_ask_spread_pct, volume_oi_ratio
Underlying TA	rsi_14, macd_signal, bb_position, atr_14, sma_20_dist, sma_50_dist, volume_ratio, roc_10, adx_14, stoch_k, stoch_d
Term Structure	term_structure_slope

Risk Management

Rule	Default
Max position size	5% of equity
Max total exposure	30% of equity
Max concurrent positions	10
Per-trade stop loss	2% of equity
Daily drawdown halt	5%
Signal confidence minimum	0.65
DTE range	7–45 days
Min open interest	100
Take profit	+50%
Stop loss	-50%
Position sizing	Half-Kelly

Project Structure

avarice/
├── environment.yml              # Mamba environment definition
├── secrets/                     # Alpaca API keys (gitignored)
├── avarice/
│   ├── main.py                  # CLI entrypoint
│   ├── config/                  # Tickers, hyperparameters, trading params, settings
│   ├── data/                    # Alpaca clients, caching, fetching, streaming, schemas
│   ├── features/                # Greeks, IV metrics, TA indicators, normalizer, pipeline
│   ├── model/                   # CNN-LSTM, dataset, trainer, inference, checkpoints
│   ├── signals/                 # Signal generation, filtering, position sizing
│   ├── backtesting/             # Backtrader engine, strategy, metrics, data feed
│   ├── paper_trading/           # Live engine, order manager, portfolio tracker
│   └── utils/                   # OCC symbols, market hours, logging
├── data/                        # Local data storage (gitignored)
│   ├── raw/                     # Parquet files from Alpaca
│   ├── processed/               # Feature matrices
│   └── models/                  # PyTorch checkpoints, plots
└── tests/                       # Unit tests (46 tests)

License

Private.