investing-algorithm-framework 8.6.0__tar.gz → 8.6.1__tar.gz

{investing_algorithm_framework-8.6.0 → investing_algorithm_framework-8.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: investing-algorithm-framework
-Version: 8.6.0
+Version: 8.6.1
 Summary: A framework for creating trading bots
 Author: MDUYN
 Requires-Python: >=3.10,<4.0
@@ -79,7 +79,11 @@ Description-Content-Type: text/markdown
 </h4>
 
 <p align="center">
-    <img src="static/showcase.svg" alt="dashboard" style="max-width: 100%;">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="static/features/hero-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="static/features/hero-light.svg">
+    <img src="static/features/hero-dark.svg" alt="Investing Algorithm Framework — features overview" style="max-width: 100%;">
+  </picture>
 </p>
 
 <p align="center">
@@ -89,17 +93,9 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  <sub><b>Sponsored by</b></sub>
+  <sub>Proudly sponsored by</sub>
   <br>
-  <a href="https://www.finterion.com/" target="_blank">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="static/sponsors/finterion-dark.png">
-      <source media="(prefers-color-scheme: light)" srcset="static/sponsors/finterion-light.png">
-      <img src="static/sponsors/finterion-light.png" alt="Finterion" width="200">
-    </picture>
-  </a>
-  <br>
-  <sub>Marketplace for trading bots</sub>
+  <a href="https://www.finterion.com/" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="static/sponsors/finterion-dark.png"><source media="(prefers-color-scheme: light)" srcset="static/sponsors/finterion-light.png"><img src="static/sponsors/finterion-light.png" alt="Finterion" width="180"></picture></a>
 </p>
 
 ## Introduction
@@ -116,6 +112,7 @@ This framework is built around the full loop: **create strategies → vector bac
 </summary> <br>
 
 - 📊 **30+ Metrics** — CAGR, Sharpe, Sortino, Calmar, VaR, CVaR, Max DD, Recovery & more
+- 🧮 **[Cross-Sectional Pipelines](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/pipelines)** — Rank, filter and score entire universes of symbols every iteration with a tidy factor table
 - ⚡ **Vector Backtesting for Signal Analysis** — Quickly test your strategy logic on historical data to see how signals would have behaved before committing to full event-driven backtests
 - 🏃 **Event-Driven Backtesting** — Once promising strategies are identified via vector backtests, run full event-driven backtests to simulate realistic execution and portfolio management
 - 🔀 **Permutation Testing / Monte Carlo Simulations** — Assess the statistical robustness of your strategies by running them across randomized market scenarios to see how often your results could occur by chance
@@ -133,7 +130,109 @@ This framework is built around the full loop: **create strategies → vector bac
 
 </details>
 
-## Usage
+<details open>
+<summary>
+  <strong>Backtesting Engines</strong>
+</summary> <br>
+
+### ⚡ Vector Backtesting — Test thousands of strategies, fast
+
+Polars-powered vectorized signal evaluation. Compare thousands of strategies side by side, sweep parameter grids, run multi-window robustness checks, rank by key metrics and surface your top candidates in seconds — all before committing to a full event-driven simulation.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="static/features/vector-backtest-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="static/features/vector-backtest-light.svg">
+    <img src="static/features/vector-backtest-dark.svg" alt="Vector backtest engine — run thousands of strategies in parallel" style="max-width: 100%;">
+  </picture>
+</p>
+
+### 🏃 Event-Driven Backtesting — Bar-by-bar realism
+
+Once you've narrowed down promising strategies, run them through a full event-driven simulation. Pluggable slippage and fill models, partial fills, and a complete simulation blotter — using the **same code path** you'll deploy live.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="static/features/event-backtest-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="static/features/event-backtest-light.svg">
+    <img src="static/features/event-backtest-dark.svg" alt="Event-driven backtest engine — bar-by-bar realism with order fills" style="max-width: 100%;">
+  </picture>
+</p>
+
+</details>
+
+<details open>
+<summary>
+  <strong>Backtest Analysis & Dashboard</strong>
+</summary> <br>
+
+Every backtest produces a **self-contained HTML dashboard** — open it in any browser, share with teammates, archive it. No server, no Jupyter, no dependencies. Compare strategies side-by-side, drill into trades, and capture your reasoning as you go.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="static/features/dashboard-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="static/features/dashboard-light.svg">
+    <img src="static/features/dashboard-dark.svg" alt="Backtest analysis dashboard with MCP server and notes" style="max-width: 100%;">
+  </picture>
+</p>
+
+- **Self-contained HTML reports** — equity curves, drawdowns, trade lists, monthly returns, side-by-side strategy comparison
+- **Built-in MCP server** — let Copilot, Claude, or any MCP-compatible agent query your backtests, rank strategies, and reason over trades through `investing-algorithm-framework mcp`
+- **Notes keeping** — annotate every backtest with hypotheses, observations and conclusions; notes travel with the report so your research is never lost
+
+→ [Backtest dashboard docs](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtesting) · [MCP server docs](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/mcp-server)
+
+</details>
+
+<details open>
+<summary>
+  <strong>Live Trading</strong>
+</summary> <br>
+
+Once a strategy proves itself in backtests, deploy it with the **same code path** you backtested. Connect to any exchange — use the built-in [CCXT](https://github.com/ccxt/ccxt) integration, or plug in your own [`OrderExecutor`](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/custom-order-executors) for brokers, FIX gateways, or any custom venue. Run locally, in Docker, or deploy serverless to **AWS Lambda** or **Azure Functions**. Built-in portfolio tracking, position management, order persistence, and automatic state recovery.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="static/features/live-trading-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="static/features/live-trading-light.svg">
+    <img src="static/features/live-trading-dark.svg" alt="Live trading & deployment — AWS Lambda and Azure Functions" style="max-width: 100%;">
+  </picture>
+</p>
+
+- **No code rewrites** — your `TradingStrategy` runs identically in backtest, paper trading and live
+- **Cloud deploy** — `investing-algorithm-framework init --type aws_lambda` / `--type azure_function`
+- **Multiple exchanges & venues** — CCXT integration out of the box (Binance, Bitvavo, Coinbase, Kraken …), or plug in your own `OrderExecutor` for any broker / FIX / custom venue
+- **Portfolio persistence** — trades, orders and positions survive restarts
+
+→ [Live trading & deployment docs](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/deployment)
+
+</details>
+
+<details open>
+<summary>
+  <strong>Marketplace Integration</strong>
+</summary> <br>
+
+Publish your winning strategies to the [**Finterion**](https://www.finterion.com/) marketplace and monetize them. Investors subscribe to your bot, you earn a recurring revenue share — the framework handles the technical integration.
+
+<p align="center">
+  <a href="https://www.finterion.com/" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="static/features/marketplace-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="static/features/marketplace-light.svg">
+      <img src="static/features/marketplace-dark.svg" alt="Marketplace integration — featuring Finterion" style="max-width: 100%;">
+    </picture>
+  </a>
+</p>
+
+→ [Finterion plugin](https://github.com/Finterion/finterion-investing-algorithm-framework-plugin)
+
+</details>
+
+<details>
+<summary>
+  <strong>Usage and Installation</strong>
+</summary> <br>
 
 To get started, install the framework and scaffold a new project:
 
@@ -283,6 +382,14 @@ Create as many strategy variants as you want — different parameters, different
 
 Every backtest produces a **single HTML file** you can open in any browser, share with teammates, or archive. No server, no dependencies, no Jupyter required.
 
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="static/features/dashboard-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="static/features/dashboard-light.svg">
+    <img src="static/features/dashboard-dark.svg" alt="Self-contained HTML backtest dashboard" style="max-width: 100%;">
+  </picture>
+</p>
+
 ```python
 from investing_algorithm_framework import BacktestReport
 
@@ -318,6 +425,7 @@ report.save("my_report.html")
 | **[Backtest Report Dashboard](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** | Self-contained HTML report with ranking tables, equity curves, metric charts, heatmaps, and strategy comparison |
 | **[Event-Driven Backtesting](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtesting)** | Realistic, order-by-order simulation |
 | **[Vectorized Backtesting](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/vector-backtesting)** | Fast signal research and prototyping |
+| **[Cross-Sectional Pipelines](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/pipelines)** | Compute factors across many symbols at once — rank, filter and score universes per iteration |
 | **50+ Metrics** | CAGR, Sharpe, Sortino, max drawdown, win rate, profit factor, recovery factor, volatility, and more |
 | **[Live Trading](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/application-setup)** | Connect to exchanges via CCXT for real-time execution |
 | **[Portfolio Management](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/portfolio-configuration)** | Position tracking, trade management, persistence |
@@ -330,14 +438,23 @@ report.save("my_report.html")
 
 </details>
 
-## Plugins
+</details>
+
+<details>
+<summary>
+  <strong>Plugins</strong>
+</summary> <br>
 
 | Plugin | Description |
 |--------|-------------|
 | [PyIndicators](https://github.com/coding-kitties/PyIndicators) | Technical analysis indicators (EMA, RSI, MACD, etc.) |
 | [Finterion Plugin](https://github.com/Finterion/finterion-investing-algorithm-framework-plugin) | Share and monetize strategies on Finterion's marketplace |
 
-## Development
+</details>
+
+## Development & Contributing
+
+We welcome contributions! Open an issue, pick one up, or send a PR.
 
 ```bash
 git clone https://github.com/coding-kitties/investing-algorithm-framework.git
@@ -348,6 +465,10 @@ poetry install
 python -m unittest discover -s tests
 ```
 
+- [Open an issue](https://github.com/coding-kitties/investing-algorithm-framework/issues/new) for bugs or ideas
+- Read the [Contributing Guide](https://coding-kitties.github.io/investing-algorithm-framework/Contributing%20Guide/contributing)
+- PRs go against the `dev` branch
+
 ## Resources
 
 - **[Documentation](https://coding-kitties.github.io/investing-algorithm-framework/)** — Guides and API reference
@@ -355,12 +476,6 @@ python -m unittest discover -s tests
 - **[Discord](https://discord.gg/dQsRmGZP)** — Chat and support
 - **[Reddit](https://www.reddit.com/r/InvestingBots/)** — Strategy discussion
 
-## Contributing
-
-- [Open an issue](https://github.com/coding-kitties/investing-algorithm-framework/issues/new) for bugs or ideas
-- Read the [Contributing Guide](https://coding-kitties.github.io/investing-algorithm-framework/Contributing%20Guide/contributing)
-- PRs go against the `dev` branch
-
 ## Risk Disclaimer
 
 If you use this framework for real trading, **do not risk money you are afraid to lose.** Test thoroughly with backtesting first. Start small. We assume no responsibility for your investment results.

{investing_algorithm_framework-8.6.0 → investing_algorithm_framework-8.6.1}/README.md

@@ -38,7 +38,11 @@
 </h4>
 
 <p align="center">
-    <img src="static/showcase.svg" alt="dashboard" style="max-width: 100%;">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="static/features/hero-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="static/features/hero-light.svg">
+    <img src="static/features/hero-dark.svg" alt="Investing Algorithm Framework — features overview" style="max-width: 100%;">
+  </picture>
 </p>
 
 <p align="center">
@@ -48,17 +52,9 @@
 </p>
 
 <p align="center">
-  <sub><b>Sponsored by</b></sub>
+  <sub>Proudly sponsored by</sub>
   <br>
-  <a href="https://www.finterion.com/" target="_blank">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="static/sponsors/finterion-dark.png">
-      <source media="(prefers-color-scheme: light)" srcset="static/sponsors/finterion-light.png">
-      <img src="static/sponsors/finterion-light.png" alt="Finterion" width="200">
-    </picture>
-  </a>
-  <br>
-  <sub>Marketplace for trading bots</sub>
+  <a href="https://www.finterion.com/" target="_blank"><picture><source media="(prefers-color-scheme: dark)" srcset="static/sponsors/finterion-dark.png"><source media="(prefers-color-scheme: light)" srcset="static/sponsors/finterion-light.png"><img src="static/sponsors/finterion-light.png" alt="Finterion" width="180"></picture></a>
 </p>
 
 ## Introduction
@@ -75,6 +71,7 @@ This framework is built around the full loop: **create strategies → vector bac
 </summary> <br>
 
 - 📊 **30+ Metrics** — CAGR, Sharpe, Sortino, Calmar, VaR, CVaR, Max DD, Recovery & more
+- 🧮 **[Cross-Sectional Pipelines](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/pipelines)** — Rank, filter and score entire universes of symbols every iteration with a tidy factor table
 - ⚡ **Vector Backtesting for Signal Analysis** — Quickly test your strategy logic on historical data to see how signals would have behaved before committing to full event-driven backtests
 - 🏃 **Event-Driven Backtesting** — Once promising strategies are identified via vector backtests, run full event-driven backtests to simulate realistic execution and portfolio management
 - 🔀 **Permutation Testing / Monte Carlo Simulations** — Assess the statistical robustness of your strategies by running them across randomized market scenarios to see how often your results could occur by chance
@@ -92,7 +89,109 @@ This framework is built around the full loop: **create strategies → vector bac
 
 </details>
 
-## Usage
+<details open>
+<summary>
+  <strong>Backtesting Engines</strong>
+</summary> <br>
+
+### ⚡ Vector Backtesting — Test thousands of strategies, fast
+
+Polars-powered vectorized signal evaluation. Compare thousands of strategies side by side, sweep parameter grids, run multi-window robustness checks, rank by key metrics and surface your top candidates in seconds — all before committing to a full event-driven simulation.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="static/features/vector-backtest-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="static/features/vector-backtest-light.svg">
+    <img src="static/features/vector-backtest-dark.svg" alt="Vector backtest engine — run thousands of strategies in parallel" style="max-width: 100%;">
+  </picture>
+</p>
+
+### 🏃 Event-Driven Backtesting — Bar-by-bar realism
+
+Once you've narrowed down promising strategies, run them through a full event-driven simulation. Pluggable slippage and fill models, partial fills, and a complete simulation blotter — using the **same code path** you'll deploy live.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="static/features/event-backtest-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="static/features/event-backtest-light.svg">
+    <img src="static/features/event-backtest-dark.svg" alt="Event-driven backtest engine — bar-by-bar realism with order fills" style="max-width: 100%;">
+  </picture>
+</p>
+
+</details>
+
+<details open>
+<summary>
+  <strong>Backtest Analysis & Dashboard</strong>
+</summary> <br>
+
+Every backtest produces a **self-contained HTML dashboard** — open it in any browser, share with teammates, archive it. No server, no Jupyter, no dependencies. Compare strategies side-by-side, drill into trades, and capture your reasoning as you go.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="static/features/dashboard-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="static/features/dashboard-light.svg">
+    <img src="static/features/dashboard-dark.svg" alt="Backtest analysis dashboard with MCP server and notes" style="max-width: 100%;">
+  </picture>
+</p>
+
+- **Self-contained HTML reports** — equity curves, drawdowns, trade lists, monthly returns, side-by-side strategy comparison
+- **Built-in MCP server** — let Copilot, Claude, or any MCP-compatible agent query your backtests, rank strategies, and reason over trades through `investing-algorithm-framework mcp`
+- **Notes keeping** — annotate every backtest with hypotheses, observations and conclusions; notes travel with the report so your research is never lost
+
+→ [Backtest dashboard docs](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtesting) · [MCP server docs](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/mcp-server)
+
+</details>
+
+<details open>
+<summary>
+  <strong>Live Trading</strong>
+</summary> <br>
+
+Once a strategy proves itself in backtests, deploy it with the **same code path** you backtested. Connect to any exchange — use the built-in [CCXT](https://github.com/ccxt/ccxt) integration, or plug in your own [`OrderExecutor`](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/custom-order-executors) for brokers, FIX gateways, or any custom venue. Run locally, in Docker, or deploy serverless to **AWS Lambda** or **Azure Functions**. Built-in portfolio tracking, position management, order persistence, and automatic state recovery.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="static/features/live-trading-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="static/features/live-trading-light.svg">
+    <img src="static/features/live-trading-dark.svg" alt="Live trading & deployment — AWS Lambda and Azure Functions" style="max-width: 100%;">
+  </picture>
+</p>
+
+- **No code rewrites** — your `TradingStrategy` runs identically in backtest, paper trading and live
+- **Cloud deploy** — `investing-algorithm-framework init --type aws_lambda` / `--type azure_function`
+- **Multiple exchanges & venues** — CCXT integration out of the box (Binance, Bitvavo, Coinbase, Kraken …), or plug in your own `OrderExecutor` for any broker / FIX / custom venue
+- **Portfolio persistence** — trades, orders and positions survive restarts
+
+→ [Live trading & deployment docs](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/deployment)
+
+</details>
+
+<details open>
+<summary>
+  <strong>Marketplace Integration</strong>
+</summary> <br>
+
+Publish your winning strategies to the [**Finterion**](https://www.finterion.com/) marketplace and monetize them. Investors subscribe to your bot, you earn a recurring revenue share — the framework handles the technical integration.
+
+<p align="center">
+  <a href="https://www.finterion.com/" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="static/features/marketplace-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="static/features/marketplace-light.svg">
+      <img src="static/features/marketplace-dark.svg" alt="Marketplace integration — featuring Finterion" style="max-width: 100%;">
+    </picture>
+  </a>
+</p>
+
+→ [Finterion plugin](https://github.com/Finterion/finterion-investing-algorithm-framework-plugin)
+
+</details>
+
+<details>
+<summary>
+  <strong>Usage and Installation</strong>
+</summary> <br>
 
 To get started, install the framework and scaffold a new project:
 
@@ -242,6 +341,14 @@ Create as many strategy variants as you want — different parameters, different
 
 Every backtest produces a **single HTML file** you can open in any browser, share with teammates, or archive. No server, no dependencies, no Jupyter required.
 
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="static/features/dashboard-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="static/features/dashboard-light.svg">
+    <img src="static/features/dashboard-dark.svg" alt="Self-contained HTML backtest dashboard" style="max-width: 100%;">
+  </picture>
+</p>
+
 ```python
 from investing_algorithm_framework import BacktestReport
 
@@ -277,6 +384,7 @@ report.save("my_report.html")
 | **[Backtest Report Dashboard](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** | Self-contained HTML report with ranking tables, equity curves, metric charts, heatmaps, and strategy comparison |
 | **[Event-Driven Backtesting](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtesting)** | Realistic, order-by-order simulation |
 | **[Vectorized Backtesting](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/vector-backtesting)** | Fast signal research and prototyping |
+| **[Cross-Sectional Pipelines](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/pipelines)** | Compute factors across many symbols at once — rank, filter and score universes per iteration |
 | **50+ Metrics** | CAGR, Sharpe, Sortino, max drawdown, win rate, profit factor, recovery factor, volatility, and more |
 | **[Live Trading](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/application-setup)** | Connect to exchanges via CCXT for real-time execution |
 | **[Portfolio Management](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/portfolio-configuration)** | Position tracking, trade management, persistence |
@@ -289,14 +397,23 @@ report.save("my_report.html")
 
 </details>
 
-## Plugins
+</details>
+
+<details>
+<summary>
+  <strong>Plugins</strong>
+</summary> <br>
 
 | Plugin | Description |
 |--------|-------------|
 | [PyIndicators](https://github.com/coding-kitties/PyIndicators) | Technical analysis indicators (EMA, RSI, MACD, etc.) |
 | [Finterion Plugin](https://github.com/Finterion/finterion-investing-algorithm-framework-plugin) | Share and monetize strategies on Finterion's marketplace |
 
-## Development
+</details>
+
+## Development & Contributing
+
+We welcome contributions! Open an issue, pick one up, or send a PR.
 
 ```bash
 git clone https://github.com/coding-kitties/investing-algorithm-framework.git
@@ -307,6 +424,10 @@ poetry install
 python -m unittest discover -s tests
 ```
 
+- [Open an issue](https://github.com/coding-kitties/investing-algorithm-framework/issues/new) for bugs or ideas
+- Read the [Contributing Guide](https://coding-kitties.github.io/investing-algorithm-framework/Contributing%20Guide/contributing)
+- PRs go against the `dev` branch
+
 ## Resources
 
 - **[Documentation](https://coding-kitties.github.io/investing-algorithm-framework/)** — Guides and API reference
@@ -314,12 +435,6 @@ python -m unittest discover -s tests
 - **[Discord](https://discord.gg/dQsRmGZP)** — Chat and support
 - **[Reddit](https://www.reddit.com/r/InvestingBots/)** — Strategy discussion
 
-## Contributing
-
-- [Open an issue](https://github.com/coding-kitties/investing-algorithm-framework/issues/new) for bugs or ideas
-- Read the [Contributing Guide](https://coding-kitties.github.io/investing-algorithm-framework/Contributing%20Guide/contributing)
-- PRs go against the `dev` branch
-
 ## Risk Disclaimer
 
 If you use this framework for real trading, **do not risk money you are afraid to lose.** Test thoroughly with backtesting first. Start small. We assume no responsibility for your investment results.

{investing_algorithm_framework-8.6.0 → investing_algorithm_framework-8.6.1}/investing_algorithm_framework/app/app.py

@@ -4,7 +4,7 @@ import os
 import threading
 from datetime import datetime, timezone, timedelta
 from pathlib import Path
-from typing import List, Optional, Any, Dict, Tuple, Callable, Union
+from typing import List, Literal, Optional, Any, Dict, Tuple, Callable, Union
 
 from flask import Flask
 
@@ -985,6 +985,8 @@ class App:
         ] = None,
         backtest_storage_directory: Optional[Union[str, Path]] = None,
         use_checkpoints: bool = False,
+        force_rerun: Union[bool, Literal["stale"]] = False,
+        on_checkpoint_match: Literal["skip", "rerun", "warn"] = "skip",
         batch_size: int = 50,
         checkpoint_batch_size: int = 25,
         n_workers: Optional[int] = None,
@@ -1087,7 +1089,24 @@ class App:
                 instead of running a new backtest. This is useful for
                 long-running backtests that might take a while to complete.
                 When enabled, uses the optimized version with batching and
-                optional parallel processing.
+                optional parallel processing. Checkpoints are content-aware:
+                each entry stores a manifest hash that fingerprints the
+                strategy code, parameters, data sources, and date range.
+                Strategies whose hash differs from the stored hash are
+                rerun automatically.
+            force_rerun (Union[bool, Literal["stale"]]): Override checkpoint
+                skipping behaviour.
+
+                - False (default): Skip strategies with a matching checkpoint.
+                - "stale": Rerun only strategies whose stored checkpoint hash
+                  differs from the current manifest hash.
+                - True: Ignore checkpoints entirely and rerun all strategies.
+            on_checkpoint_match (Literal["skip", "rerun", "warn"]): Behaviour
+                when a strategy's checkpoint matches.
+
+                - "skip" (default): Silently skip the strategy.
+                - "warn": Skip but emit a single log line per match batch.
+                - "rerun": Rerun the strategy anyway.
             batch_size (int): Number of strategies to process in each batch
                 before memory cleanup. Only used when use_checkpoints=True.
                 Default: 100. Higher values use more memory but may be faster.
@@ -1204,6 +1223,8 @@ class App:
             checkpoint_batch_size=checkpoint_batch_size,
             n_workers=n_workers,
             use_checkpoints=use_checkpoints,
+            force_rerun=force_rerun,
+            on_checkpoint_match=on_checkpoint_match,
             dynamic_position_sizing=dynamic_position_sizing,
             fill_missing_data=fill_missing_data,
             iterative_summary_update=iterative_summary_update,
@@ -1381,6 +1402,8 @@ class App:
         metadata: Optional[Dict[str, str]] = None,
         backtest_storage_directory: Optional[Union[str, Path]] = None,
         use_checkpoints: bool = False,
+        force_rerun: Union[bool, Literal["stale"]] = False,
+        on_checkpoint_match: Literal["skip", "rerun", "warn"] = "skip",
         show_progress: bool = False,
         continue_on_error: bool = False,
         window_filter_function: Optional[Callable] = None,
@@ -1420,7 +1443,16 @@ class App:
             backtest_storage_directory (Union[str, Path]): Directory to save
                 backtests to.
             use_checkpoints (bool): Whether to use checkpointing to resume
-                interrupted backtests.
+                interrupted backtests. Checkpoints are content-aware:
+                strategies whose code or parameters have changed since the
+                last run are detected and rerun automatically.
+            force_rerun (Union[bool, Literal["stale"]]): Override checkpoint
+                skipping behaviour. ``False`` (default) skips matched
+                checkpoints, ``"stale"`` reruns only mismatched ones, and
+                ``True`` reruns everything.
+            on_checkpoint_match (Literal["skip", "rerun", "warn"]): Behaviour
+                on a matching checkpoint. ``"skip"`` (default) silently
+                skips, ``"warn"`` skips and logs, ``"rerun"`` reruns anyway.
             show_progress (bool): Whether to show progress bars.
             continue_on_error (bool): Whether to continue on errors.
             window_filter_function: Filter function applied after each
@@ -1533,6 +1565,8 @@ class App:
             final_filter_function=final_filter_function,
             backtest_storage_directory=backtest_storage_directory,
             use_checkpoints=use_checkpoints,
+            force_rerun=force_rerun,
+            on_checkpoint_match=on_checkpoint_match,
             batch_size=batch_size,
             checkpoint_batch_size=checkpoint_batch_size,
             fill_missing_data=fill_missing_data,

{investing_algorithm_framework-8.6.0 → investing_algorithm_framework-8.6.1}/investing_algorithm_framework/domain/backtesting/backtest.py

@@ -418,6 +418,23 @@ class Backtest:
                 os.makedirs(destination_run_path, exist_ok=True)
                 br.save(destination_run_path)
 
+        # Always rebuild the summary from the current set of backtest runs
+        # before writing it to disk. This guarantees that summary.json is
+        # self-consistent with the per-run metrics.json files (e.g.
+        # number_of_windows == number of runs, total_net_gain == sum of
+        # per-run total_net_gain, etc.) regardless of how the in-memory
+        # Backtest was constructed (single backtest, walk-forward,
+        # merge(), …). See issue #511.
+        if self.backtest_runs:
+            per_run_metrics = [
+                br.backtest_metrics for br in self.backtest_runs
+                if br.backtest_metrics is not None
+            ]
+            if per_run_metrics:
+                self.backtest_summary = generate_backtest_summary_metrics(
+                    per_run_metrics
+                )
+
         # Save combined backtest metrics if available
         if self.backtest_summary:
             summary_file = os.path.join(
@@ -517,15 +534,22 @@ class Backtest:
             Backtest: The merged Backtest instance.
         """
 
-        merged = Backtest()
+        merged = Backtest(algorithm_id=self.algorithm_id)
         merged.backtest_runs = self.backtest_runs + other.backtest_runs
 
-        summary = BacktestSummaryMetrics()
-
-        for bt_run in merged.get_all_backtest_metrics():
-            summary.add(bt_run)
+        # Rebuild the summary from the full set of merged backtest runs.
+        # `BacktestSummaryMetrics` is a plain dataclass and does not expose
+        # an `add()` method, so the previous incremental approach raised
+        # AttributeError and silently produced a stale / single-window
+        # summary. See issue #511.
+        merged_metrics = merged.get_all_backtest_metrics()
+        if merged_metrics:
+            merged.backtest_summary = generate_backtest_summary_metrics(
+                merged_metrics
+            )
+        else:
+            merged.backtest_summary = BacktestSummaryMetrics()
 
-        merged.backtest_summary = summary
         merged.backtest_permutation_tests = \
             self.backtest_permutation_tests + other.backtest_permutation_tests
 

{investing_algorithm_framework-8.6.0 → investing_algorithm_framework-8.6.1}/investing_algorithm_framework/domain/backtesting/backtest_metrics.py

@@ -20,6 +20,21 @@ class BacktestMetrics:
     total return, annualized return, volatility, Sharpe ratio,
     and maximum drawdown.
 
+    .. note:: Field semantics & known duplicates (issue #511)
+
+        - ``total_loss`` is the **gross loss magnitude** (a non-negative
+          number equal to ``sum(abs(net_gain))`` over losing trades).
+          ``total_loss_percentage`` is ``total_loss /
+          initial_unallocated`` (decimal, non-negative). These fields
+          no longer mirror ``total_net_gain`` / ``total_net_gain_pct``;
+          see B1 in issue #511.
+
+        - ``total_growth`` / ``total_growth_percentage`` are
+          numerically equivalent to ``total_net_gain`` /
+          ``total_net_gain_percentage`` for the standard
+          mark-to-market portfolio used in backtests. They are kept as
+          legacy aliases. See B3 in issue #511.
+
     Attributes:
         backtest_date_range_name (str): The name of the date range
             used for the backtest.

{investing_algorithm_framework-8.6.0 → investing_algorithm_framework-8.6.1}/investing_algorithm_framework/domain/backtesting/backtest_summary_metrics.py

@@ -13,6 +13,30 @@ class BacktestSummaryMetrics:
     Represents the summarized results of a backtest,
     focusing on key headline performance and risk metrics.
 
+    .. note:: Field semantics & known duplicates (issue #511)
+
+        - ``total_loss`` / ``total_loss_percentage`` are gross-loss
+          based: ``total_loss`` is ``sum(per-run gross_loss)`` (a
+          non-negative magnitude in account currency) and
+          ``total_loss_percentage`` is ``total_loss /
+          sum(initial_unallocated)`` (decimal). They no longer mix
+          with net-return semantics. See B1/B2 in issue #511.
+
+        - ``total_growth`` / ``total_growth_percentage`` are
+          numerically equivalent to ``total_net_gain`` /
+          ``total_net_gain_percentage`` for closed-position backtests
+          because both are derived from the same start/end portfolio
+          values. They are kept for backwards compatibility but should
+          be considered legacy aliases. See B3 in issue #511.
+
+        - ``average_net_gain``, ``average_loss``, ``average_growth``
+          (and their ``*_percentage`` counterparts) are time-weighted
+          means **across windows**. For a single-window backtest they
+          collapse to the corresponding ``total_*`` value by
+          definition (weighted mean of one element equals that
+          element). See B4 in issue #511. For per-trade averages use
+          ``average_trade_*`` instead.
+
     Attributes:
         total_net_gain (float): Total net gain from the backtest.
         total_net_gain_percentage (float): Total net gain percentage