investing-algorithm-framework

The Investing Algorithm Framework is a comprehensive quantitative workflow tool designed to support the entire lifecycle of an investing strategy. It enables developers to:

• Build strategies: Define quantitative logic for trading.
• Vector Backtesting: Test thousands of strategies simultaneously using high-speed vector operations.
• Event-Driven Backtesting: Perform realistic, bar-by-bar simulations to mimic live market conditions.
• Compare results: Use a single dashboard to evaluate performance across different strategies.
• Deploy: Move winning strategies into production.

The Investing Algorithm Framework is a Python-based library for building, testing, and deploying algorithmic trading systems. It supports the full lifecycle of strategy development, including data management, order execution, and performance analysis.

Core capabilities include:

• Strategy Development: Tools for implementing trading logic.
• Backtesting: Dual approaches using Vector Backtesting (for fast signal analysis) and Event-Driven Backtesting (for realistic execution simulation).
• Data Management: Integration with various data sources and the ability to load external CSV, JSON, or Parquet files from URLs with caching.
• Performance Analysis: Over 30 metrics (CAGR, Sharpe, Sortino, etc.) and interactive reporting.
• Deployment: Production-ready deployment to local environments or cloud providers like AWS Lambda and Azure Functions.

A Trade represents a round-trip position, tracking the full lifecycle from entry to exit. It is distinct from an Order (an instruction to buy/sell) and a Position (current holdings).

Trade Lifecycle

1. Created: A buy order is placed; the trade record is created with status CREATED.
2. Open: The buy order fills; the trade becomes OPEN. It now has an open_price, amount, and cost.
3. Closed: A sell order fills against the trade, closing it. The net_gain is calculated, closed_at is set, and status becomes CLOSED.

Note: A single sell order can close multiple trades, and a single trade can be closed by multiple partial sell orders.

The Risk Parity strategy aims to allocate capital across a basket of assets so that each asset contributes an equal amount of risk to the total portfolio.

In this implementation, the strategy uses inverse-volatility weighting as a first-order approximation of true risk parity. The weighting logic follows the principle: weight ∝ 1/σ (where σ is volatility), followed by renormalization.

Key characteristics within the framework:

• Pattern: Uses a Periodic-rebalance pattern.
• Logic: Portfolio targets are calculated as pure functions of the OHLCV (Open, High, Low, Close, Volume) history.
• Execution: The strategy reads target weights, calculates the delta between target weights and current positions, and emits the required orders.
• Cadence: Rebalancing is configured using time_unit=DAY combined with a monthly gate to ensure monthly rebalancing.

The framework uses a TradeOrderEvaluator system to manage the lifecycle of orders and trades. This system is responsible for determining when orders are executed and how trade data is updated. The implementation of this evaluator changes fundamentally based on your environment:

1. Live Trading: Uses LiveTradeOrderEvaluator to interact with real exchanges via CCXT, checking actual order statuses and updating trade prices based on real-time market data.
2. Backtesting: Uses BacktestTradeOrderEvaluator to simulate execution using historical OHLCV data (Polars DataFrames), applying realistic rules for market and limit orders.

Understanding this distinction is critical for ensuring your strategy behaves predictably when moving from simulation to production.

The framework uses a 'Fit Legend' to indicate how well the current architecture supports specific trading patterns:

A v2 bundle holds exactly one engine's results. The engine_type field determines which top-level keys are populated for runs and metrics. If engine_type is None, it falls back to legacy/unknown-engine keys.

When performing multi-window backtests (such as walk-forward or permutation tests), you can retrieve a single roll-up of performance across all windows using BacktestSummaryMetrics. This is accessed via backtest.get_backtest_summary().

For single-window backtests, these aggregate values collapse to the per-run values. For multi-window backtests, these metrics aggregate performance and provide robustness measures to evaluate how the strategy performs across different time periods.

Fixed (trailing=False)

Reference price is the entry price. The rule fires the first time the price touches entry × (1 + threshold/100). This is best for immediate profit taking.

Example: Buy at 100, threshold=5% $\rightarrow$ exit price = 105. When price hits 105, exit.

Trailing (trailing=True)

The take-profit price is not set at entry. It is armed only when the percentage_threshold is first reached. Once armed, the exit price ratchets with the rolling peak, allowing winners to run while locking in profit on pullbacks.

Example:

1. Buy at 100, threshold=5%.
2. Price hits 105 $\rightarrow$ Rule arms, take_profit_price = 105 (peak=105).
3. Price rises to 120 $\rightarrow$ take_profit_price = 114 (peak=120).
4. Price rises to 150 $\rightarrow$ take_profit_price = 142.50 (peak=150).
5. Price falls to 142.50 $\rightarrow$ Exit at ~142.50.