Metadata-Version: 2.4
Name: factor-forge-quant
Version: 0.5.0
Summary: Modern, reproducible factor zoo replication engine with transaction costs, decay analysis, and ML ensembles
Author-email: Satyam Das <satyamdas03@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/satyamdas03/factor-forge
Project-URL: Repository, https://github.com/satyamdas03/factor-forge
Project-URL: Issues, https://github.com/satyamdas03/factor-forge/issues
Project-URL: Documentation, https://satyamdas03.github.io/factor-forge/
Keywords: quantitative-finance,factor-investing,backtesting,machine-learning,cross-sectional
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3.0,>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: requests>=2.31
Requires-Dist: scipy>=1.11
Requires-Dist: statsmodels>=0.14
Requires-Dist: scikit-learn>=1.3
Provides-Extra: data
Requires-Dist: databento>=0.80.0; extra == "data"
Requires-Dist: yfinance>=0.2.0; extra == "data"
Provides-Extra: ml
Requires-Dist: lightgbm>=4.0; extra == "ml"
Requires-Dist: xgboost>=2.0; extra == "ml"
Requires-Dist: mapie>=0.8; extra == "ml"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == "viz"
Requires-Dist: plotly>=5.18; extra == "viz"
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.28; extra == "dashboard"
Requires-Dist: plotly>=5.18; extra == "dashboard"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Provides-Extra: dev
Requires-Dist: factor-forge-quant[data,docs,ml,viz]; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.11.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: all
Requires-Dist: factor-forge-quant[dev]; extra == "all"
Dynamic: license-file

# Factor Forge

[![CI](https://github.com/satyamdas03/factor-forge/actions/workflows/ci.yml/badge.svg)](https://github.com/satyamdas03/factor-forge/actions/workflows/ci.yml)
[![Docs](https://github.com/satyamdas03/factor-forge/actions/workflows/docs.yml/badge.svg)](https://satyamdas03.github.io/factor-forge/)
[![PyPI](https://img.shields.io/pypi/v/factor-forge-quant.svg)](https://pypi.org/project/factor-forge-quant/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**A modern, reproducible factor zoo replication engine for cross-sectional equity research.**

Factor Forge takes the academic "factor zoo" — momentum, value, quality, low-volatility, investment, profitability — and makes it runnable, honest, and ML-ready. It handles transaction costs, survivorship bias, look-ahead bias, factor decay, and walk-forward machine learning.

> **Mission:** Let any researcher or student answer *"Does this factor still work after costs?"* with net-of-cost Sharpe, turnover analysis, and uncertainty-aware ensembles.

---

## Why this matters

- **Quantopian is gone** and `zipline` / `pyfolio` are unmaintained.
- Most public factor code reports **gross returns**, ignores **transaction costs**, and suffers from **look-ahead bias**.
- Factor Forge reports **net-of-cost Sharpe**, **turnover**, **capacity**, and **factor decay** in a clean, extensible Python package.

---

## What you can do

- Compute **15+ classic factors** with a uniform cross-sectional API.
- Build **decile long/short and long-only portfolios** with monthly rebalancing.
- Apply a **transaction-cost and slippage model** to every trade.
- Measure **information coefficient (IC)**, **factor decay**, **turnover**, and **regime performance**.
- Train a **walk-forward LightGBM ensemble** that combines factors without peeking.
- Add **conformal prediction intervals** for return forecasts.
- Generate **publication-ready plots**, **interactive HTML research reports**, and a **Streamlit dashboard**.

---

## Quickstart

```bash
git clone https://github.com/satyamdas03/factor-forge.git
cd factor-forge
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

Or install from PyPI:

```bash
pip install factor-forge-quant
```

Run a backtest on a single factor using cached or Polygon data:

```bash
export POLYGON_API_KEY=your_key_here
factor-forge --factor momentum_12_1 --start 2015-01-01 --end 2024-01-01
```

Generate an HTML research report:

```bash
ff-report --factor momentum_12_1 --start 2015-01-01 --end 2024-01-01 --output reports
```

Launch the interactive dashboard:

```bash
pip install "factor-forge-quant[dashboard]"
ff-dashboard
```

Or from Python:

```python
from factor_forge import BacktestEngine, DataLoader
from factor_forge.factors.registry import FactorRegistry

loader = DataLoader(source="polygon", api_key="your_key")
prices = loader.load_eod(["AAPL", "MSFT", "GOOGL"], start="2015-01-01", end="2024-01-01")

registry = FactorRegistry()
registry.load_builtin()
factor = registry.get("momentum_12_1")

engine = BacktestEngine(factor=factor, prices=prices, transaction_cost_bps=10.0)
result = engine.run()
print(result.metrics)
```

---

## Factor library

| Category | Factors |
|---|---|
| Momentum | `momentum_12_1`, `momentum_52_high`, `residual_momentum` |
| Value | `pe_ratio`, `pb_ratio` |
| Quality | `roe`, `gross_margin`, `accruals` |
| Low volatility | `idiosyncratic_volatility`, `beta`, `max_drawdown` |
| Investment | `asset_growth`, `capex_growth` |
| Profitability | `gross_profits_to_assets` |

Each factor is a pure function `prices / fundamentals → cross-sectional score`. Adding a new factor is one function + one registry entry.

---

## Architecture

```
factor_forge/
├── data/          # Data sources, loader, cache, survivorship handling
├── factors/       # Factor definitions and registry
├── backtest/      # Portfolio, cost model, decile engine
├── analytics/     # Metrics, IC, decay, turnover, regimes, correlations
├── ml/            # Walk-forward features, LightGBM ensemble, conformal prediction
├── viz/           # Publication-ready plots
├── cli/           # Command-line tools
└── docs/          # MkDocs site + blog
```

---

## Roadmap

| Version | Goal | Status |
|---|---|---|
| v0.1.0 | Data pipeline + 5 core factors + decile backtest | ✅ |
| v0.2.0 | 15+ factors + transaction costs + analytics | ✅ |
| v0.3.0 | Factor decay, turnover, regime analysis | ✅ |
| v0.4.0 | ML ensemble + conformal prediction | ✅ |
| v0.5.0 | Dashboard + research report generation | ✅ |

---

## Documentation

Full documentation, API reference, and research blog are at:

**https://satyamdas03.github.io/factor-forge/**

---

## Interview talking points

- *"Most retail factor backtests report gross returns. Factor Forge reports net-of-cost Sharpe and turnover-adjusted returns."*
- *"I handle delisting and point-in-time fundamentals to avoid look-ahead bias."*
- *"I found momentum still works but turnover is high; low-vol is crowded and decayed post-2020."*
- *"I combined factors with a walk-forward LightGBM ensemble and added conformal prediction intervals for risk."*

---

## License

MIT © Satyam Das
