foliotrack 0.1.0

Tool to keep balance a portfolio of securities while investing.

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 position count.
• 🌍 Multi-Currency Native: Seamlessly handles portfolios with assets in different currencies (USD, EUR, GBP, etc.). Real-time exchange rates (ECB) 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.
• 📊 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.

• 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.
  • 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

FolioTrack uses uv for fast, reliable dependency management.

# Clone the repository
git clone [e-mail]:PhDFlo/foliotrack.git
cd foliotrack

# Sync dependencies and create virtual env
uv sync

# Activate environment
source .venv/bin/activate

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 sync --group dev

⚡ Quick Start

1. Command Line Interface (CLI)

You can run the included main.py entry point to see Foliotrack in action immediately:

# Create a portfolio from scratch, optimize it, and backtest it
uv run main.py --action scratch

# Use an existing portfolio JSON file
uv run main.py --action existing

# Use a different data provider (if installed)
uv run main.py --provider ffn

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:

Page	Description
Portfolio & Update Prices	Load/save portfolio JSON files, view holdings, update live prices, buy/sell securities
Equilibrium, Buy & Export	Configure optimization parameters, run MIQP solver, view recommended trades
Display Portfolio	Visualize portfolio with candlestick charts, pie charts (target vs actual allocation)
Compare Securities	Compare investment contracts with different fees and tax regimes
Exchange Rates	Look up ECB exchange rates and convert currencies
Backtest Simulation	Run historical backtests with equity curves, statistics, and return analysis

Note: Run dash from the directory containing your Portfolios/ folder so the dashboard can find your portfolio JSON files.

3. Python API

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.storage.PortfolioRepository import PortfolioRepository

# 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. Save Work
repo.save_to_json(portfolio, "my_portfolio.json")

🏛️ 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.
• 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).

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

🧪 Testing

Run the full test suite (core + dashboard):

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).

🤝 Contributing

Contributions are welcome! Please run the test suite before submitting a PR:

uv run pytest

📄 License

Apache License 2.0. See LICENSE for details.