factor-lab | AI Learning Blog

Quantitative stock screening and backtesting platform for systematic factor investing.

Discover alpha through data-driven multi-factor analysis.

Philosophy

“퀀트는 계산이지 추론이 아닙니다”

factor-lab은 CLI-First Approach를 채택합니다:

✅ 재현 가능한 백테스팅 (동일 명령어 = 동일 결과)
✅ 학술적 검증된 팩터 (Fama-French 5-Factor Model)
✅ 빠른 실행 (Agent 오버헤드 없음)
✅ 표준화된 퀀트 업계 방식 (Python CLI)

Quick Start

Installation

cd plugins/factor-lab
pip3 install -r requirements.txt

Factor Screening

# Screen S&P 500 using multi-factor scoring
python3 quant/factor_screener.py \
  --universe SP500 \
  --factors value:0.3,quality:0.4,momentum:0.3 \
  --top-n 50 \
  --output screener_results.csv

# Output:
# Ticker  Composite  Value  Quality  Momentum  Sector       Price
# MSFT    89.2       72     95       91        Technology   $404.37
# GOOGL   86.5       85     88       82        Technology   $310.96
# ...

Backtesting

# Step 1: Pre-populate cache (one-time, ~12 minutes)
python3 scripts/populate_cache.py --universe SP500 --years 10

# Step 2: Backtest momentum strategy (2020-2024)
python3 quant/backtest_engine.py \
  --strategy momentum \
  --universe SP500 \
  --start-date 2020-01-01 \
  --end-date 2024-01-01 \
  --rebalance monthly \
  --top-n 50

# Output:
# Total Return:    +86.81%
# Annual Return:   +16.91% (vs academic: 8-10%)
# Sharpe Ratio:     3.54 (excellent)
# Max Drawdown:    -25.20%
# Execution Time:   < 1 minute

Real Results (2020-2024):

Momentum: +86.81% total (+16.91% annual, Sharpe 3.54)
Value: +51.47% total (+10.94% annual, Sharpe 2.56)
Quality: +52.15% total (+11.06% annual, Sharpe 2.53)

Features

Core Engine (CLI Tools)

Factor Screener (quant/factor_screener.py)
- Multi-factor scoring (Value, Quality, Momentum, Low Vol)
- Sector-relative comparison
- Universes: S&P 500, KOSPI 200, NASDAQ 100
Backtest Engine (quant/backtest_engine.py)
- Historical strategy simulation
- Performance metrics (Sharpe Ratio, MDD, Win Rate)
- Transaction cost modeling (commission, slippage)
- Equity curve visualization (PNG charts)
Strategy Library (strategies/)
- Momentum Strategy (12M price momentum)
- Value Factor Strategy (Low P/E, P/B)
- Quality Strategy (High ROE, Low Debt)
Cache Pre-population (scripts/populate_cache.py)
- Bulk historical data download (10 years)
- Rate limiting (1.5s delay)
- 100% success rate (503/503 S&P 500 stocks)
- One-time setup (~12 minutes)

Interface Layer (Skills) - Optional

backtest skill: “백테스트해줘” → CLI execution + result interpretation
screen skill: “좋은 종목 찾아줘” → CLI execution + analysis

Architecture

┌─ Core Engine (CLI Tools) ────────────────────┐
│  Python CLI scripts                           │
│  - factor_screener.py                         │
│  - backtest_engine.py                         │
│  - signal_generator.py                        │
│  → 직접 실행 가능, 재현 가능, 빠름            │
└───────────────────────────────────────────────┘
                    ↑
                    │ 호출
                    │
┌─ Interface Layer (Skill) ─────────────────────┐
│  Skill: "quant-screen"                        │
│  - 자연어 → CLI 파라미터 변환                 │
│  - 결과 해석 및 설명                          │
│  → 편의성 제공, 교육적                        │
└───────────────────────────────────────────────┘

Workflow Process

flowchart TB
    Start([User: Investment Strategy]) --> Universe[Define Universe<br/>SP500 / KOSPI200 / NASDAQ100]

    Universe --> Path{Choose Path}

    %% Path 1: Screening
    Path -->|Screening| Screen[factor_screener.py<br/>--factors value:0.3,quality:0.4,momentum:0.3]
    Screen --> FetchData1[Data Manager<br/>Fetch OHLCV + Fundamentals]
    FetchData1 --> Cache1{Cache Valid?<br/>30 days}
    Cache1 -->|Yes| CalcFactors[Factor Calculator<br/>5 Factor Scores]
    Cache1 -->|No| YFinance1[yfinance/pykrx API] --> SQLite1[(SQLite Cache)] --> CalcFactors

    CalcFactors --> Value[Value Score<br/>P/E, P/B vs Sector]
    CalcFactors --> Quality[Quality Score<br/>ROE, Debt/Equity, Margins]
    CalcFactors --> Momentum[Momentum Score<br/>12M Return]
    CalcFactors --> LowVol[Low Vol Score<br/>Beta, Volatility]
    CalcFactors --> Size[Size Score<br/>Market Cap]

    Value --> Composite[Composite Score<br/>Weighted Average]
    Quality --> Composite
    Momentum --> Composite
    LowVol --> Composite
    Size --> Composite

    Composite --> Rank[Rank Stocks<br/>Sort by Score]
    Rank --> TopN[Top N Stocks<br/>e.g., Top 50]
    TopN --> Export1[Export Results<br/>CSV/JSON]

    %% Path 2: Backtesting
    Path -->|Backtesting| Backtest[backtest_engine.py<br/>--strategy momentum<br/>--start 2014 --end 2024]
    Backtest --> FetchData2[Historical Data<br/>10 Years OHLCV]
    FetchData2 --> Cache2{Cache Valid?}
    Cache2 -->|Yes| Simulate
    Cache2 -->|No| YFinance2[yfinance API] --> SQLite2[(SQLite Cache)] --> Simulate

    Simulate[Historical Simulation<br/>Monthly Rebalancing] --> Trades[Generate Trades<br/>Buy/Sell Signals]
    Trades --> Costs[Apply Costs<br/>Commission + Slippage]
    Costs --> Metrics[Calculate Metrics<br/>Sharpe, Drawdown, Win Rate]
    Metrics --> EquityCurve[Equity Curve<br/>Visualization]
    EquityCurve --> Export2[Export Results<br/>PNG + CSV]

    %% Integration with other plugins
    Export1 --> Integration{Integration?}
    Export2 --> Integration

    Integration -->|Value Check| MarketPulse[market-pulse<br/>Graham Safety Margin<br/>Buffett Moat Analysis]
    MarketPulse --> Filter[Filter: Both Pass<br/>Quant + Value]

    Integration -->|Direct| Portfolio
    Filter --> Portfolio[investment-analyzer<br/>Portfolio Manager]

    Portfolio --> AddStocks[Add to Portfolio<br/>Equal Weight / Risk Parity]
    AddStocks --> Dashboard[Generate Dashboard<br/>HTML + Chart.js]
    Dashboard --> Monitor[Monitor & Rebalance<br/>Monthly/Quarterly]

    Monitor --> Rebalance{Rebalance Signal?}
    Rebalance -->|Yes| Screen
    Rebalance -->|No| Monitor

    %% Styling
    classDef completed fill:#90EE90,stroke:#228B22,stroke-width:2px
    classDef inProgress fill:#FFD700,stroke:#FF8C00,stroke-width:2px
    classDef planned fill:#87CEEB,stroke:#4682B4,stroke-width:2px
    classDef data fill:#FFE4B5,stroke:#D2691E,stroke-width:2px

    class Screen,FetchData1,CalcFactors,Value,Quality,Momentum,LowVol,Size,Composite,Rank,TopN,Export1 completed
    class Backtest,FetchData2,Simulate,Trades,Costs,Metrics,EquityCurve,Export2 completed
    class MarketPulse,Portfolio,Dashboard,Monitor planned
    class Cache1,Cache2,SQLite1,SQLite2,YFinance1,YFinance2 data

Workflow Legend:

🟢 Green: Completed (Phase 1 - Screening & Backtesting)
🔵 Blue: Planned (Phase 2 - Integration)
🟠 Orange: Data Layer (Caching)

Key Insights:

Two Main Paths: Screening finds stocks NOW, Backtesting validates strategies HISTORICALLY
Data Caching: SQLite cache with 10 years of data enables fast backtests (<1 min)
5 Factor Breakdown: Each factor contributes to the final composite score
Plugin Integration: factor-lab → market-pulse (value check) → investment-analyzer (execution)
Continuous Cycle: Monitor → Rebalance → Screen again (monthly/quarterly)
Validated Results: All strategies exceed academic benchmarks (2020-2024 period)

The 5 Factors (Fama-French Model)

Factor	Logic	Measurement	Expected Premium
Value	Undervalued stocks revert to mean	P/E, P/B, EV/EBITDA	4-5% annually
Quality	High-quality companies sustain profits	ROE, Debt/Equity, Margins	3-4% annually
Momentum	Trends persist (behavioral)	12M returns	8-10% annually
Low Volatility	Low-risk stocks outperform high-risk	Beta, Std Dev	Sharpe 2x
Size	Small caps outperform large caps	Market Cap	2-3% annually

Usage Examples

1. Find Top 20 Stocks by Quality

python3 quant/factor_screener.py \
  --universe SP500 \
  --factors quality:1.0 \
  --top-n 20

2. Backtest Value Strategy

python3 quant/backtest_engine.py \
  --strategy value_factor \
  --universe SP500 \
  --start-date 2014-01-01 \
  --end-date 2024-01-01

3. Custom Multi-Factor Strategy

python3 quant/factor_screener.py \
  --universe KOSPI200 \
  --factors value:0.4,quality:0.3,momentum:0.2,low_vol:0.1 \
  --min-score 70 \
  --top-n 30

File Structure

plugins/factor-lab/
├── .claude-plugin/
│   └── plugin.json              # Plugin metadata v1.0.0
├── quant/                        # Core Engine (CLI Tools)
│   ├── data_manager.py          # Data fetching & caching (522 lines)
│   ├── factor_calculator.py     # 5-factor scoring engine (499 lines)
│   ├── factor_screener.py       # CLI screening tool (333 lines)
│   └── backtest_engine.py       # CLI backtesting engine (530+ lines)
├── strategies/                   # Strategy Library
│   ├── base.py                  # Strategy abstract class (120 lines)
│   ├── momentum.py              # Momentum strategy (200 lines)
│   ├── value_factor.py          # Value factor strategy (140 lines)
│   └── quality.py               # Quality factor strategy (135 lines)
├── scripts/                      # Utilities
│   └── populate_cache.py        # Cache pre-population (200 lines)
├── config/
│   └── factor_definitions.yaml  # Factor definitions & weights (190 lines)
├── docs/
│   └── QUANT_INVESTING_GUIDE.md # Complete quant investing guide
├── data/                         # SQLite cache & results
│   └── market_data_cache.db     # 10 years × 503 stocks (~200MB)
└── README.md                    # This file (410 lines)

Data Sources (All Free)

Library	Purpose	Coverage
yfinance	US stocks, ETFs, crypto	15-20min delay, free
pykrx	Korean stocks	Real-time, free
SQLite	Data caching	30-day validity

Key Metrics Explained

Sharpe Ratio

Sharpe = (Return - Risk-Free Rate) / Volatility

Interpretation:
> 1.0: Excellent
0.5-1.0: Good
< 0.5: Poor

Max Drawdown (MDD)

MDD = max(Peak - Trough) / Peak × 100

Interpretation:
< 20%: Excellent
20-30%: Acceptable
> 30%: High (may be hard to tolerate)

Backtesting Best Practices

✅ Point-in-Time Data: Only use information available at that time
✅ Survivorship Bias: Include delisted stocks
✅ Transaction Costs: Reflect commission (0.1%) + slippage (0.05%)
✅ Out-of-Sample Testing: Train on 2014-2019, validate on 2020-2024
✅ Simple Strategies: Avoid overfitting (< 5 parameters)

Integration with Other Plugins

3-Plugin Workflow

factor-lab        → 50 stocks (quant screening)
    ↓
market-pulse      → 15 stocks (Graham, Buffett validation)
    ↓
investment-analyzer → Portfolio execution

JSON Export:

python3 quant/factor_screener.py --output results.json
# → Use in market-pulse or investment-analyzer

Learning Resources

Essential Reading

“Quantitative Momentum” by Wesley Gray - Best intro to quant investing
Fama-French 5-Factor Model (2015) - Academic foundation
“Value and Momentum Everywhere” (Asness et al.) - Global factor evidence

Online Courses

QuantConnect Tutorial (Free)
Coursera: Machine Learning for Trading (Georgia Tech)

Documentation

Complete Quant Investing Guide - 60-page comprehensive guide

Real-World Quant Funds

Fund	AUM	Strategy	Performance
Renaissance Technologies	$130B	Statistical arbitrage	66% annually (30 years)
AQR Capital	$143B	Multi-factor (Value, Momentum, Quality)	Sharpe 1.2+
Two Sigma	$60B	Machine learning	Proprietary

Disclaimer

Educational Purpose: factor-lab is designed for learning quantitative investing principles. This is NOT financial advice.

Data Limitations:

yfinance: 15-20 minute delayed data (free tier)
Backtests: Past performance does NOT guarantee future results
Paper trading recommended before real capital

Risk Warning: Quantitative strategies can experience significant drawdowns. Only invest what you can afford to lose.

Development Roadmap

Phase 1: Core Engine ✅ COMPLETE

Factor Calculator (5 factors) - Week 1
Factor Screener CLI - Week 1
Backtest Engine CLI - Week 2
Strategy Library (momentum, value, quality) - Week 2
Cache Pre-population Script - Week 2
Validation with Real Data (2020-2024) - Week 2
- Momentum: +86.81% (Sharpe 3.54)
- Value: +51.47% (Sharpe 2.56)
- Quality: +52.15% (Sharpe 2.53)

Phase 2: Documentation & Polish (Optional)

Complete QUANT_INVESTING_GUIDE.md (60+ pages)
Unit tests (factor_calculator, backtest_engine)
Integration tests (end-to-end workflows)

Phase 3: Interface Layer (Optional)

Backtest Skill (“백테스트해줘”)
Screener Skill (“좋은 종목 찾아줘”)

Phase 4: MCP Integration (Advanced)

MCP Server (cross-plugin integration)
market-pulse collaboration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone repository
git clone https://github.com/JayKim88/claude-ai-engineering.git
cd claude-ai-engineering/plugins/factor-lab

# Install dependencies
pip3 install -r requirements.txt

# Run tests
python3 -m pytest tests/

License

This project is licensed under the MIT License.

Acknowledgments

Academic Foundation: Fama-French 5-Factor Model
Inspiration: AQR Capital, Renaissance Technologies, Two Sigma
Data Sources: yfinance, pykrx
Philosophy: “Quant is calculation, not reasoning”

Contact

Jay Kim - @JayKim88

Project Link: https://github.com/JayKim88/claude-ai-engineering

Made with 📊 for quantitative investors