FolioTrack

FolioTrack is a robust, modular Python library for modern portfolio management. It helps you manage, optimize, rebalance, and backtest multi-currency investment portfolios with ease.

Designed primarily for DIY passive investors, FolioTrack automates the mathematical heavy lifting of maintaining a "lazy" portfolio. It ensures your asset allocation remains perfectly balanced with minimal effort, helping you stick to your long-term strategy without the spreadsheet headaches.

🚀 Why FolioTrack?

• 🧠 Smart Optimization: Uses Mixed-Integer Quadratic Programming (MIQP) to calculate the best integer number of shares to buy/sell to reach your target allocation, respecting constraints like minimum order size or maximum number of positions to buy.
• 🌍 Multi-Currency Native: Seamlessly handles portfolios with assets in different currencies (USD, EUR, GBP, etc.). Real-time exchange rates, taken from the European Central Bank (ECB) API, ensure your valuations are always accurate.
• 🏗️ Clean Architecture: Built with Domain-Driven Design principles. Your core portfolio logic is decoupled from external data providers, making the system testable and extensible.
• 🔌 Pluggable Data: Comes with support for yfinance and ffn, but you can easily plug in your own market data provider.
• 📈 Built-in Backtesting: Validate your strategies against historical data before investing a cent using bt.
• 📊 Interactive Dashboard: A full-featured Streamlit web dashboard for visual portfolio management, optimization, and analysis.

✨ Features

• Portfolio Management

  • Track stocks, ETFs, and other securities.
  • JSON-based persistence for easy saving/loading.
  • Transaction history logging.

• Performance Statistics

  • Compute Time-Weighted Return (TWR) resolving external cash-flows.
  • Generates 10+ standard metrics (CAGR, Sharpe, Max Drawdown, Alpha, Beta, etc.).
  • Compares Porfolio performance to benchmarks (S&P500, etc.)
  • Easily extensible to custom statistics.

• Advanced Rebalancing

  • Set target weights (e.g., "60% Stocks, 40% Bonds").
  • Mathematical solver finds the optimal trades to minimize tracking error.
  • Cardinality constraints (limit number of positions).

• Data Sources

  • yfinance (Yahoo Finance) support out of the box.
  • ffn support for straightforward financial time series.
  • btsupport for backtest simulations.
  • Extensible MarketService architecture.

• Interactive Dashboard (optional)

  • Load, save, and manage portfolios visually.
  • Update live security prices from the UI.
  • Run portfolio optimization and view recommended trades.
  • Display portfolio composition with pie charts and candlestick evolution.
  • Compare investment contracts (fees, taxes) with interactive simulations.
  • View ECB exchange rates with currency conversion.
  • Run backtests with equity curves, monthly return histograms, and per-security bar charts.

🛠️ Installation

# Using pip
pip install foliotrack

# Using uv
uv pip install foliotrack

Installing the Dashboard

The dashboard has additional dependencies (Streamlit, Plotly) that are optional. Install them with:

# Using pip
pip install foliotrack[dashboard]

# Using uv (development)
uv pip install foliotrack[dashboard]

⚡ Quick Start

1. Python API

Open the examples/portfolio_from_scratch.ipynb in your favorite code editor to get an overview of the library features. FolioTrack's modular API is intuitive. Here is a classic "60/40" portfolio example:

from foliotrack.domain.Portfolio import Portfolio
from foliotrack.services.MarketService import MarketService
from foliotrack.services.OptimizationService import OptimizationService
from foliotrack.services.BacktestService import BacktestService
from foliotrack.services.StatisticsService import StatisticsService
from foliotrack.storage.PortfolioRepository import PortfolioRepository
from foliotrack.statistics import DEFAULT_METRICS

# 1. Setup Services
market_service = MarketService(provider="yfinance")
optimizer = OptimizationService()
repo = PortfolioRepository()

# 2. Create Portfolio
portfolio = Portfolio("Retirement Fund", currency="EUR")

# Buy classic ETFs (Stocks + Bonds)
portfolio.buy_security("IDDA.AS", volume=50.0) # iShares MSCI World (Stocks)
portfolio.buy_security("AGGH.AS", volume=50.0) # iShares Global Agg Bond (Bonds)

# 3. Enrich with Market Data
market_service.update_prices(portfolio)

# 4. Set Targets (60% Stocks, 40% Bonds) & Optimize
portfolio.set_target_share("IDDA.AS", 0.6)
portfolio.set_target_share("AGGH.AS", 0.4)

# Calculate optimal buys to invest an additional 5000 EUR
optimizer.solve_equilibrium(portfolio, investment_amount=5000.0)

# 5. Compute Statistics
stats_service = StatisticsService(market_service)
stats = stats_service.compute_statistics(portfolio, metrics=DEFAULT_METRICS)
print(f"CAGR: {stats['CAGR']:.2%}, Sharpe: {stats['Annualized Sharpe Ratio']:.2f}")

# 6. Save Work
repo.save_to_json(portfolio, "my_portfolio.json")

2. Interactive Dashboard

Launch the full web dashboard with a single command:

dash

This starts a Streamlit application in your browser with the following pages:

🏛️ Architecture

FolioTrack follows a clean, layered architecture:

• domain/: Pure Python data entities (Portfolio, Security). No external dependencies or I/O here.
• services/: Business logic and external adapters.
  • MarketService: Fetches prices.
  • OptimizationService: Runs the solver.
  • BacktestService: Runs simulations.
  • StatisticsService: Computes Time-Weighted Returns and evaluates performance metrics.
• statistics/: Modular definitions for performance metrics (CAGR, Sharpe, Beta, etc.).
• storage/: Handles file persistence (PortfolioRepository).
• dashboard/: Interactive Streamlit web application (optional).
  • app.py: Main Streamlit entry point with sidebar navigation.
  • pages/: Individual dashboard pages (load, optimize, display, compare, exchange, backtest).
  • utils/: Dashboard-specific helpers (plots, formatting, file operations, simulation).
• examples/: Jupyter notebook examples files

This structure ensures that your portfolio data remains safe and stable, regardless of how market APIs or file formats change over time.

🤝 Contributing

Contributions are welcome! FolioTrack uses uv for fast, reliable dependency management.

# Clone the repository
git clone git@github.com:PhDFlo/foliotrack.git
cd foliotrack

# Sync dependencies and create virtual env
uv sync

# Activate environment
source .venv/bin/activate

Please run the test suite (core + dashboard) before submitting a PR:

uv run pytest

Tests are organized as:

• tests/foliotrack/ — Core library unit tests (portfolio, security, optimization, backtest, market, currency).
• tests/dashboard/components/ — Dashboard utility tests (formatting, file helpers, simulation).
• tests/dashboard/ui/ — Streamlit UI tests using AppTest harness (page loading, interactions).

📄 License

Apache License 2.0. See LICENSE for details.