investing-algorithm-framework 8.7.2__tar.gz → 8.8.0__tar.gz

{investing_algorithm_framework-8.7.2 → investing_algorithm_framework-8.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: investing-algorithm-framework
-Version: 8.7.2
+Version: 8.8.0
 Summary: A framework for creating trading bots
 Author: MDUYN
 Requires-Python: >=3.10,<4.0
@@ -114,23 +114,24 @@ This framework is built around the full loop: **create strategies → vector bac
  Features
 </summary> <br>
 
-- 📊 **30+ Metrics** — CAGR, Sharpe, Sortino, Calmar, VaR, CVaR, Max DD, Recovery & more
+- 📊 **[30+ Metrics](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/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
-- 🚀 **Deployment** — Once the best strategy is identified through backtesting and comparison, deploy it to production locally or in the cloud (AWS Lambda / Azure Functions) to start live trading
-- ⚔️ **Multi-Strategy Comparison** — Rank, filter & compare strategies in a single interactive report
-- 🪟 **Multi-Window Robustness** — Test across different time periods with window coverage analysis
-- 📈 **Equity & Drawdown Charts** — Overlay equity curves, rolling Sharpe, drawdown & return distributions
-- 🗓️ **Monthly Heatmaps & Yearly Returns** — Calendar heatmap per strategy with return/growth toggles
-- 🎯 **Return Scenario Projections** — Good, average, bad & very bad year projections from backtest data
-- 📉 **Benchmark Comparison** — Beat-rate analysis vs Buy & Hold, DCA, risk-free & custom benchmarks
-- 📄 **One-Click HTML Report** — Self-contained file, no server, dark & light theme, shareable
-- 📦 **Custom `.iafbt` Backtest Bundle Format** — An explicit, versioned, compressed, language-portable container (zstd + msgpack with magic-byte header) plus a separate parquet index for fast filtering without loading. ~21× smaller and ~27× fewer files than standard filebased directory layouts, with parallel I/O for fast load/save of large amounts of backtests.
-- 🌐 **Load External Data** — Fetch CSV, JSON, or Parquet from any URL with caching and auto-refresh
-- � **[Record Custom Variables](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/recording-variables)** — Track any indicator or metric during backtests with `context.record()`
-- �🚀 **Build → Backtest → Deploy** — Local dev, cloud deploy (AWS / Azure), or monetize on Finterion
+- ⚡ **[Vector Backtesting for Signal Analysis](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/vector-backtesting)** — 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](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/event-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](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Assess the statistical robustness of your strategies by running them across randomized market scenarios to see how often your results could occur by chance
+- 🚀 **[Deployment](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/deployment)** — Once the best strategy is identified through backtesting and comparison, deploy it to production locally or in the cloud (AWS Lambda / Azure Functions) to start live trading
+- ⚔️ **[Multi-Strategy Comparison](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Rank, filter & compare strategies in a single interactive report
+- 🪟 **[Multi-Window Robustness](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Test across different time periods with window coverage analysis
+- 📈 **[Equity & Drawdown Charts](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Overlay equity curves, rolling Sharpe, drawdown & return distributions
+- 🗓️ **[Monthly Heatmaps & Yearly Returns](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Calendar heatmap per strategy with return/growth toggles
+- 🎯 **[Return Scenario Projections](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Good, average, bad & very bad year projections from backtest data
+- 📉 **[Benchmark Comparison](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Beat-rate analysis vs Buy & Hold, DCA, risk-free & custom benchmarks
+- 📄 **[One-Click HTML Report](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Self-contained file, no server, dark & light theme, shareable
+- 📦 **[Custom `.iafbt` Backtest Bundle Format](https://coding-kitties.github.io/investing-algorithm-framework/Data/backtest_data)** — An explicit, versioned, compressed, language-portable container (zstd + msgpack with magic-byte header) plus a separate parquet index for fast filtering without loading. ~21× smaller and ~27× fewer files than standard filebased directory layouts, with parallel I/O for fast load/save of large amounts of backtests.
+- 🌐 **[Load External Data](https://coding-kitties.github.io/investing-algorithm-framework/Data/external-data)** — Fetch CSV, JSON, or Parquet from any URL with caching and auto-refresh
+- � **[Per-Market Deposit Schedules & Portfolio Sync](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/portfolio-sync)** — Declare recurring or one-shot external cash flows on a market with `deposit_schedule=` / `auto_sync=True`. Backtests simulate the deposits; live mode reconciles with the broker — same `context.sync_portfolio()` API in both modes.
+- �📝 **[Record Custom Variables](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/recording-variables)** — Track any indicator or metric during backtests with `context.record()`
+- 🚀 **[Build → Backtest → Deploy](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/application-setup)** — Local dev, cloud deploy (AWS / Azure), or monetize on Finterion
 
 </details>
 

{investing_algorithm_framework-8.7.2 → investing_algorithm_framework-8.8.0}/README.md

@@ -70,23 +70,24 @@ This framework is built around the full loop: **create strategies → vector bac
  Features
 </summary> <br>
 
-- 📊 **30+ Metrics** — CAGR, Sharpe, Sortino, Calmar, VaR, CVaR, Max DD, Recovery & more
+- 📊 **[30+ Metrics](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/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
-- 🚀 **Deployment** — Once the best strategy is identified through backtesting and comparison, deploy it to production locally or in the cloud (AWS Lambda / Azure Functions) to start live trading
-- ⚔️ **Multi-Strategy Comparison** — Rank, filter & compare strategies in a single interactive report
-- 🪟 **Multi-Window Robustness** — Test across different time periods with window coverage analysis
-- 📈 **Equity & Drawdown Charts** — Overlay equity curves, rolling Sharpe, drawdown & return distributions
-- 🗓️ **Monthly Heatmaps & Yearly Returns** — Calendar heatmap per strategy with return/growth toggles
-- 🎯 **Return Scenario Projections** — Good, average, bad & very bad year projections from backtest data
-- 📉 **Benchmark Comparison** — Beat-rate analysis vs Buy & Hold, DCA, risk-free & custom benchmarks
-- 📄 **One-Click HTML Report** — Self-contained file, no server, dark & light theme, shareable
-- 📦 **Custom `.iafbt` Backtest Bundle Format** — An explicit, versioned, compressed, language-portable container (zstd + msgpack with magic-byte header) plus a separate parquet index for fast filtering without loading. ~21× smaller and ~27× fewer files than standard filebased directory layouts, with parallel I/O for fast load/save of large amounts of backtests.
-- 🌐 **Load External Data** — Fetch CSV, JSON, or Parquet from any URL with caching and auto-refresh
-- � **[Record Custom Variables](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/recording-variables)** — Track any indicator or metric during backtests with `context.record()`
-- �🚀 **Build → Backtest → Deploy** — Local dev, cloud deploy (AWS / Azure), or monetize on Finterion
+- ⚡ **[Vector Backtesting for Signal Analysis](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/vector-backtesting)** — 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](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/event-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](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Assess the statistical robustness of your strategies by running them across randomized market scenarios to see how often your results could occur by chance
+- 🚀 **[Deployment](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/deployment)** — Once the best strategy is identified through backtesting and comparison, deploy it to production locally or in the cloud (AWS Lambda / Azure Functions) to start live trading
+- ⚔️ **[Multi-Strategy Comparison](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Rank, filter & compare strategies in a single interactive report
+- 🪟 **[Multi-Window Robustness](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Test across different time periods with window coverage analysis
+- 📈 **[Equity & Drawdown Charts](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Overlay equity curves, rolling Sharpe, drawdown & return distributions
+- 🗓️ **[Monthly Heatmaps & Yearly Returns](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Calendar heatmap per strategy with return/growth toggles
+- 🎯 **[Return Scenario Projections](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Good, average, bad & very bad year projections from backtest data
+- 📉 **[Benchmark Comparison](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Beat-rate analysis vs Buy & Hold, DCA, risk-free & custom benchmarks
+- 📄 **[One-Click HTML Report](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Self-contained file, no server, dark & light theme, shareable
+- 📦 **[Custom `.iafbt` Backtest Bundle Format](https://coding-kitties.github.io/investing-algorithm-framework/Data/backtest_data)** — An explicit, versioned, compressed, language-portable container (zstd + msgpack with magic-byte header) plus a separate parquet index for fast filtering without loading. ~21× smaller and ~27× fewer files than standard filebased directory layouts, with parallel I/O for fast load/save of large amounts of backtests.
+- 🌐 **[Load External Data](https://coding-kitties.github.io/investing-algorithm-framework/Data/external-data)** — Fetch CSV, JSON, or Parquet from any URL with caching and auto-refresh
+- � **[Per-Market Deposit Schedules & Portfolio Sync](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/portfolio-sync)** — Declare recurring or one-shot external cash flows on a market with `deposit_schedule=` / `auto_sync=True`. Backtests simulate the deposits; live mode reconciles with the broker — same `context.sync_portfolio()` API in both modes.
+- �📝 **[Record Custom Variables](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/recording-variables)** — Track any indicator or metric during backtests with `context.record()`
+- 🚀 **[Build → Backtest → Deploy](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/application-setup)** — Local dev, cloud deploy (AWS / Azure), or monetize on Finterion
 
 </details>
 

{investing_algorithm_framework-8.7.2 → investing_algorithm_framework-8.8.0}/investing_algorithm_framework/__init__.py

@@ -35,7 +35,8 @@ from .domain import ApiException, combine_backtests, PositionSize, \
     Pipeline, Factor, CustomFactor, Filter, \
     Returns, AverageDollarVolume, AverageTradedValue, SMA, RSI, \
     Volatility, StaticPerSymbol, CrossSectionalMean, RollingBeta, \
-    Neutralize
+    Neutralize, \
+    SyncResult, ScheduledDeposit, PortfolioOutOfSyncError
 from .infrastructure import AzureBlobStorageStateHandler, \
     CSVOHLCVDataProvider, CSVTickerDataProvider, CSVURLDataProvider, \
     JSONURLDataProvider, ParquetURLDataProvider, \
@@ -285,6 +286,9 @@ __all__ = [
     "get_normalized_stability",
     "get_consistency_score",
     "get_stability_score",
+    "SyncResult",
+    "ScheduledDeposit",
+    "PortfolioOutOfSyncError",
 ]
 
 

{investing_algorithm_framework-8.7.2 → investing_algorithm_framework-8.8.0}/investing_algorithm_framework/app/app.py

@@ -2242,6 +2242,9 @@ class App:
         initial_balance=None,
         fee_percentage=0.0,
         slippage_percentage=0.0,
+        deposit_schedule=None,
+        auto_sync=False,
+        auto_sync_error_mode="raise",
     ):
         """
         Function to add a market to the app. This function is a utility
@@ -2260,10 +2263,28 @@ class App:
             slippage_percentage: Default slippage percentage for all
                 trades on this market (e.g. 0.05 for 0.05%). Can be
                 overridden per-symbol via TradingCost on the strategy.
+            deposit_schedule: Optional list of
+                :class:`ScheduledDeposit` describing simulated external
+                cash flows landing on this market during a backtest
+                (e.g. monthly paychecks). Ignored in live mode — for
+                live deployments the broker is the source of truth and
+                ``Context.sync_portfolio()`` queries it directly.
+            auto_sync: When ``True``, the framework automatically calls
+                ``Context.sync_portfolio(market=market)`` before every
+                strategy iteration so deposits/withdrawals are absorbed
+                without strategy code having to opt in. Defaults to
+                ``False`` (explicit opt-in via ``context.sync_portfolio()``).
+            auto_sync_error_mode: How auto-sync handles failures. One of
+                ``"raise"`` (loud, default — best for development),
+                ``"warn"`` (log and continue with stale state — best for
+                live trading where transient broker glitches should not
+                crash the bot), or ``"halt"`` (log, disable auto-sync
+                for this market, and continue).
 
         Returns:
             None
         """
+        deposit_schedule = self._normalize_deposit_schedule(deposit_schedule)
 
         portfolio_configuration = PortfolioConfiguration(
             market=market,
@@ -2271,6 +2292,7 @@ class App:
             initial_balance=initial_balance,
             fee_percentage=fee_percentage,
             slippage_percentage=slippage_percentage,
+            deposit_schedule=deposit_schedule,
         )
 
         self.add_portfolio_configuration(portfolio_configuration)
@@ -2281,6 +2303,78 @@ class App:
         )
         self.add_market_credential(market_credential)
 
+        tracker = self.container.broker_balance_tracker()
+        if deposit_schedule:
+            tracker.set_schedule(market, deposit_schedule)
+        if auto_sync:
+            tracker.set_auto_sync(market, True)
+        tracker.set_auto_sync_error_mode(market, auto_sync_error_mode)
+
+    @staticmethod
+    def _normalize_deposit_schedule(deposit_schedule):
+        """Coerce a deposit_schedule argument to a validated list.
+
+        Accepts ``None`` (treated as no schedule), a list/tuple of
+        :class:`ScheduledDeposit`, or rejects anything else with a clear
+        error. Notably rejects passing a single ``ScheduledDeposit``
+        directly (which would be iterable over its dataclass fields and
+        produce nonsense).
+        """
+        from investing_algorithm_framework.domain import ScheduledDeposit
+        if deposit_schedule is None:
+            return []
+        if isinstance(deposit_schedule, ScheduledDeposit):
+            raise OperationalException(
+                "deposit_schedule must be a list of ScheduledDeposit, not a "
+                "single ScheduledDeposit. Wrap it: [ScheduledDeposit(...)]."
+            )
+        if not isinstance(deposit_schedule, (list, tuple)):
+            raise OperationalException(
+                "deposit_schedule must be a list of ScheduledDeposit, got "
+                f"{type(deposit_schedule).__name__}."
+            )
+        for entry in deposit_schedule:
+            if not isinstance(entry, ScheduledDeposit):
+                raise OperationalException(
+                    "deposit_schedule entries must be ScheduledDeposit, "
+                    f"got {type(entry).__name__}."
+                )
+        return list(deposit_schedule)
+
+    def add_deposit_schedule(self, market, schedule):
+        """Register simulated external deposits for a backtested market.
+
+        Equivalent to passing ``deposit_schedule=`` to :meth:`add_market`,
+        but usable after the market has already been registered. Replaces
+        any previously registered schedule for this market.
+
+        Args:
+            market: Market identifier.
+            schedule: Iterable of :class:`ScheduledDeposit`.
+
+        Returns:
+            None
+        """
+        self.container.broker_balance_tracker().set_schedule(
+            market, self._normalize_deposit_schedule(schedule)
+        )
+
+    def set_market_auto_sync(self, market, enabled=True):
+        """Toggle automatic ``sync_portfolio`` before each strategy iteration.
+
+        Args:
+            market: Market identifier.
+            enabled: When ``True`` (the default), the framework calls
+                ``Context.sync_portfolio(market=market)`` immediately before
+                each strategy ``run_strategy`` invocation.
+
+        Returns:
+            None
+        """
+        self.container.broker_balance_tracker().set_auto_sync(
+            market, enabled
+        )
+
     def set_blotter(self, blotter):
         """
         Set a blotter for order book management. The blotter sits