README.md

metadata

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

Usage

Configure the engine via config.py and execute the core pipeline:

python main.py

Reporting

Run the integration testing suite using pytest:

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:

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.