README.md

---
title: Portfolio Engine
emoji: 📈
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
---
# Portfolio Engine

An institutional-grade portfolio allocation and backtesting engine for quantitative finance research.

## Features

- **Walk-Forward Cross-Validation**: Rigorous expanding window out-of-sample backtesting to prevent look-ahead bias and overfitting.
- **Advanced Asset Allocation Models**:
  - CAPM (Capital Asset Pricing Model)
  - Black-Litterman (Market Equilibrium Prior)
  - Bayesian Shrinkage (James-Stein)
  - Fama-French 3-Factor + Momentum
  - Machine Learning Stacking Ensemble (XGBoost + ElasticNet + Ridge Meta-Learner)
  - End-to-End Differentiable Optimization (SPO+)
  - Regime-Adaptive Factor Blend
- **Deep Learning Forecasting**:
  - Noise-Filtered Transformer with Conv1D temporal smoothing
  - Cross-asset training with sliding window sequence datasets
  - Integrated into the meta-learner ensemble pipeline
- **Alternative Data Ingestion**:
  - Real-time options flow: Put/Call volume ratios and Implied Volatility skew
  - Seamless injection into the ML feature generation pipeline
- **Three Allocation Engines**:
  - Mean-Variance Optimization (CVXPY) with 7-stage constraint relaxation cascade
  - Hierarchical Risk Parity (HRP) with tax-aware blending
  - Exact True Risk Parity (ERC) via Spinu logarithmic barrier formulation
- **Cardinality Constraints**: Iterative pruning heuristic for maximum-asset-count limits
- **Econometric Validation & Statistical Rigor**: 
  - Model Confidence Sets (MCS) for screening optimal models
  - Diebold-Mariano Tests for predictive accuracy vs benchmarks
  - Probabilistic Sharpe Ratio (PSR) for non-normality
  - Deflated Sharpe Ratio (DSR) to account for multiple testing bias
  - Christoffersen Conditional Coverage for dynamic risk limit validation
- **Robust Execution**:
  - Differentiable optimization via `cvxpylayers`
  - Realistic transaction cost and Almgren-Chriss market impact modeling
  - Dynamic API rate-limiting for automated data pipeline tasks
  - Structured JSON logging for production monitoring

## Documentation

Comprehensive documentation is available in the `docs/` directory:

| Document | Description |
|----------|-------------|
| [**ARCHITECTURE.md**](docs/ARCHITECTURE.md) | **Master reference** — complete codebase walkthrough with file map |
| [PIPELINE.md](docs/PIPELINE.md) | Pipeline stages, data flow, and execution model |
| [MODELS.md](docs/MODELS.md) | Deep dive into all return forecasting and risk models |
| [ALLOCATION_ENGINES.md](docs/ALLOCATION_ENGINES.md) | Mean-Variance, HRP, and Exact Risk Parity engines |
| [RELAXATION_CASCADE.md](docs/RELAXATION_CASCADE.md) | 7-stage constraint relaxation for infeasible solves |
| [TESTS.md](docs/TESTS.md) | Test suite, mocking strategy, and property-based testing |
| [OUTPUT.md](docs/OUTPUT.md) | Output artefacts and directory structure |
| [DEPLOY.md](docs/DEPLOY.md) | Docker, Helm, CI/CD, and Kubernetes deployment |
| [RESEARCH.md](docs/RESEARCH.md) | Experimental modules: PID controller, Dreamer RL |

## Usage

Configure the engine via `config.py` and execute the core pipeline:
```bash
python main.py
```

### Reporting
Run the integration testing suite using pytest:
```bash
pytest tests/test_simulate.py -v
```

The engine automatically constructs comprehensive HTML reports displaying true equity curves, allocation drift, and marginal risk attributions.

## Deployment

The engine supports robust Kubernetes deployments via Helm.

### Deploying via Helm

1. Configure your API keys in `deploy/helm/portfolio-engine/values.yaml` or pass them via command line.
2. Install the chart:
```bash
helm install portfolio-engine ./deploy/helm/portfolio-engine --set env[0].value="YOUR_API_KEY"
```

3. Ensure the `DATABASE_URL` is configured if you're using a managed PostgreSQL instance for the database layer.

## Results

Validation tests confirm the mathematical stability of the solver across all core models. The walk-forward CV confirms the strategy returns are stable and survive multiple testing deflations (DSR).

## Safety & Rate Limiting

The data fetching module incorporates thread-safe rate limits (max 2 requests per second globally) when fetching assets to ensure safety during automated deployments and prevent API bans.