stonks-lab

Bilingual (Python + R) quantitative finance research platform for alpha discovery and value investing.

Features

Core Platform

• Data Layer: OpenBB integration, Parquet storage, DuckDB queries
• Python: Factor library, LightGBM ML, backtesting, live trading (Alpaca)
• R: GARCH (rugarch), Bayesian (brms), econometrics (urca/vars)
• Notebooks: Quarto for mixed Python/R research

Value Investing System (NEW)

• Quant Screener: Buffett-style fundamental screening (P/E, P/B, ROE, FCF, debt ratios)
• LLM Analysis: Claude-powered deep analysis of SEC filings, news, and investment theses
• Research CLI: Screen universes, analyze picks, generate reports
• Decision Support: Side-by-side comparison, thesis critique, position sizing

Quick Start

# Clone
git clone git@github.com:raold/stonks-lab.git
cd stonks-lab
git lfs pull

# Decrypt API keys (requires GPG key - see below)
git-crypt unlock

# Python environment
uv sync

# R environment
R -e "renv::restore()"

# Verify
uv run python -c "from stonks.db import query; print('OK')"
Rscript -e "source('R/db.R'); print('OK')"

Value Investing Workflow

# 1. Screen S&P 500 for value stocks
uv run python scripts/screen_value.py --universe sp500 --limit 30

# 2. Analyze a specific stock
uv run python scripts/analyze_pick.py AAPL --depth quick
uv run python scripts/analyze_pick.py AAPL --depth full  # Deep analysis

# 3. Generate research report for top picks
uv run python scripts/research_report.py --from-screen --top 5

# 4. Interactive research notebook
quarto preview notebooks/05_value_research.qmd

Screener Options

# Relaxed criteria (more stocks pass)
uv run python scripts/screen_value.py --relaxed --limit 50

# Custom symbols
uv run python scripts/screen_value.py --universe custom --symbols AAPL MSFT GOOGL

# Save results
uv run python scripts/screen_value.py --output data/value_picks.parquet

LLM Analysis (requires ANTHROPIC_API_KEY)

# Quick analysis for screening
uv run python scripts/analyze_pick.py AAPL

# Full deep dive (includes 10-K analysis)
uv run python scripts/analyze_pick.py AAPL --depth full --output analysis/aapl.json

API Keys Setup

API keys in config/settings.toml are encrypted with git-crypt.

Required Keys

Key	Purpose	Required For
ANTHROPIC_API_KEY	Claude API	LLM analysis
FMP_API_KEY	Financial Modeling Prep	Fundamentals data
ALPACA_API_KEY	Alpaca Trading	Live/paper trading

On a new machine

1. Install dependencies

# macOS
brew install git-crypt gnupg

# Arch Linux
sudo pacman -S git-crypt gnupg

2. Import GPG key (one-time)

From a machine that has the key:

gpg --export-secret-keys --armor oldham@hey.com > /tmp/gpg-key.asc
# Transfer securely to new machine

On the new machine:

gpg --import ~/path/to/gpg-key.asc
rm ~/path/to/gpg-key.asc  # delete after import

3. Unlock after clone

git-crypt unlock
# config/settings.toml is now readable

The unlock persists for that clone - no need to run again.

Adding new API keys

Edit config/settings.toml directly. It auto-encrypts on commit.

Project Structure

stonks-lab/
├── src/stonks/          # Python package
│   ├── data/            # OpenBB providers, fundamentals, filings, news
│   ├── db/              # DuckDB connection, queries
│   ├── factors/         # Factor library
│   ├── ml/              # LightGBM, SHAP
│   ├── backtest/        # Backtesting engine
│   ├── trading/         # Alpaca integration
│   ├── strategy/        # Strategy execution
│   ├── screener/        # Value stock screener
│   ├── llm/             # Claude integration
│   └── tax/             # Tax-loss harvesting
├── R/                   # R scripts (GARCH, brms, cointegration)
├── data/                # Parquet files (raw + processed)
├── notebooks/           # Quarto research notebooks
├── scripts/             # CLI tools
├── tests/               # pytest + testthat
├── docs/                # Documentation
└── config/              # Settings (encrypted)

Daily Workflow

# Update market data
uv run python scripts/update_data.py

# Run value screen
uv run python scripts/screen_value.py

# Strategy execution (paper trading)
uv run python scripts/run_strategy.py --strategy momentum --dry-run

# Run notebooks
quarto preview notebooks/

Testing

# All Python tests (~168 tests)
uv run pytest tests/ -v --ignore=tests/R/

# R tests (32 tests)
Rscript -e "testthat::test_dir('tests/R')"

# Specific module
uv run pytest tests/test_screener.py -v

Documentation

• CLAUDE.md - AI context and conventions
• TODO.md - Current work items
• CHANGELOG.md - Version history
• docs/architecture.md - System design
• docs/adr/ - Architecture decisions (001-004)
• docs/research/ - Value investing research notes (17 topics)
• docs/sessions/ - Session handoff notes

License

MIT