Portfolio Optimizer

Quantitative portfolio construction and optimization platform built on skfolio and scikit-learn.

Architecture

optimizer/          Pure-Python optimization library (DB-agnostic, sklearn/skfolio-based)
  preprocessing/    Return data cleaning (validation, outlier treatment, sector imputation)
  pre_selection/    Asset filtering pipeline (completeness, variance, correlation, dominance)
  moments/          Expected return and covariance estimation
  views/            Black-Litterman, Entropy Pooling, Opinion Pooling
  optimization/     Mean-risk, risk budgeting, HRP/HERC/NCO, stacking
  synthetic/        Vine copula scenario generation and stress testing
  validation/       Walk-forward, combinatorial purged CV, randomized CV
  scoring/          Performance scoring for model selection
  tuning/           Grid search and randomized search with temporal CV
  rebalancing/      Calendar and threshold-based rebalancing
  pipeline/         End-to-end orchestration (prices → validated weights)

api/                FastAPI backend (PostgreSQL, BAML, Trading 212 integration)
cli/                Typer CLI (data fetching, universe management, macro regime analysis)
tests/              Test suite for the optimizer library
theory/             LaTeX/Markdown theoretical documentation

Quick Start — Optimizer Library

pip install -e ".[dev]"

import pandas as pd
from optimizer.optimization import MeanRiskConfig, build_mean_risk
from optimizer.validation import WalkForwardConfig
from optimizer.pipeline import run_full_pipeline

# Load price data (DatetimeIndex, one column per asset)
prices = pd.read_csv("prices.csv", index_col=0, parse_dates=True)

# Configure and run
optimizer = build_mean_risk(MeanRiskConfig.for_max_sharpe())
cv_config = WalkForwardConfig.for_quarterly_rolling()

result = run_full_pipeline(
    prices=prices,
    optimizer=optimizer,
    cv_config=cv_config,
)

print(result.weights)
print(result.summary)

Quick Start — API + CLI

# Start PostgreSQL
docker compose up -d

# Set up the API
cd api
pip install -r requirements.txt
cp .env.example .env              # Edit with your API keys
alembic upgrade head
uvicorn app.main:app --reload     # http://localhost:8000

# CLI (from project root)
pip install -r requirements.txt
python -m cli --help
python -m cli db health
python -m cli universe stats
python -m cli yfinance fetch

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check .

# Type check
mypy .

Examples

Self-contained scripts using synthetic data (no API keys required):

pip install -e ".[dev]"
python examples/quickstart.py

Environment Variables

Copy .env.example to .env and fill in your API keys. Database defaults match docker-compose.yml and work out of the box.

Disclaimer

This software is provided for educational and research purposes only. It is not intended as, and shall not be understood or construed as, financial, investment, tax, or legal advice.

No investment advice. The authors and contributors are not registered investment advisors, broker-dealers, or financial planners. Nothing in this software or its documentation constitutes a recommendation to buy, sell, or hold any financial instrument.

No liability for losses. The authors and contributors accept no responsibility or liability whatsoever for any loss or damage arising from the use of this software. You may lose some or all of your invested capital. Use this software entirely at your own risk.

Past performance is not indicative of future results. Backtesting and historical analysis produced by this software do not guarantee future performance. Simulated results may not reflect the impact of real market conditions including liquidity, slippage, fees, and taxes.

Seek professional advice. Before making any investment decision, consult with a qualified, licensed financial advisor, accountant, or attorney.

By using this software, you acknowledge that you have read and understood this disclaimer and agree to be bound by its terms.

License

BSD-3-Clause