Skip to content

Portfolio Management Toolkit

Offline-first Python command-line toolkit for constructing and backtesting long-horizon retirement portfolios

Documentation Python 3.12 Code style: Ruff

Overview

This toolkit is designed for Polish investors trading via BOŚ Dom Maklerski and mBank's MDM. It emphasizes diversified asset allocation, factor tilts, and disciplined risk overlays, with future plans to incorporate news- and sentiment-driven signals.

Key Features

  • ✅ Offline-first data pipeline - Ingests Stooq exports, validates quality, produces tradeable match reports
  • ✅ Incremental resume - Skips redundant processing when inputs unchanged (minutes → seconds)
  • ✅ Fast I/O - Optional polars/pyarrow backends (2-5x speedup on large datasets)
  • ✅ Production-ready CLIs - Asset selection, classification, return preparation, universe management
  • ✅ Configurable universes - YAML-based universe definitions with validation
  • ✅ Macro signal infrastructure - Provider for macro series + regime gating framework
  • ✅ 200+ automated tests - Unit, CLI, integration, performance smoke tests
  • ✅ Portfolio strategies - Equal-weight, risk-parity, mean-variance with comparison tooling
  • ✅ Factor-based preselection - Momentum and low-volatility filters (no lookahead bias)
  • ✅ Cardinality constraints - Extensible interfaces for limiting portfolio positions
  • ✅ Statistics caching - Automatic caching for covariance matrices and expected returns
  • ✅ Backtesting engine - Opportunistic rebalancing, transaction costs, performance analytics

Architecture

scripts/          # CLI entry points
src/portfolio_management/
├── core/         # Foundation (exceptions, config, utilities)
├── data/         # Data management (I/O, ingestion, analysis)
├── assets/       # Asset universe (selection, classification)
├── analytics/    # Financial analytics (returns, metrics)
├── macro/        # Macroeconomic signals & regime gating
├── portfolio/    # Portfolio construction (strategies, constraints)
├── backtesting/  # Backtesting engine (simulation, transactions)
└── reporting/    # Reporting & visualization

Example Usage

# Construct a portfolio
from portfolio_management.portfolio import EqualWeightStrategy

strategy = EqualWeightStrategy()
weights = strategy.generate_weights(assets=['AAPL', 'MSFT', 'GOOGL'])

# Run a backtest
from scripts.run_backtest import run_backtest

results = run_backtest(
    universe='sp500_liquid',
    strategy='risk_parity',
    start_date='2020-01-01',
    end_date='2023-12-31'
)

Documentation Structure

For New Users

For Regular Users

For Advanced Users

For Developers

Technology Stack

  • Python 3.12 - Modern Python with type hints
  • Ruff - Single tool for formatting, linting, import sorting (10-100x faster)
  • MyPy - Static type checking (0 errors)
  • Pytest - 200+ automated tests
  • Pandas/NumPy - Data processing
  • PyPortfolioOpt - Portfolio optimization
  • Plotly - Interactive visualizations

Development Status

  • ✅ Core functionality - Production ready
  • ✅ Testing - 200+ tests, 85%+ coverage
  • ✅ Documentation - Comprehensive guides
  • ✅ Type safety - 0 MyPy errors
  • 🔄 Advanced features - Ongoing development

Contributing

We welcome contributions! See contributing for guidelines.

License

License details are still being finalized; check the repository for the latest updates or open a quick issue if you need clarification.

Contact

Ask questions or share ideas by opening an issue or discussion on the GitHub repo: https://github.com/jc1122/portfolio_management/issues