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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: investing-algorithm-framework
-Version: 8.6.1
+Version: 8.7.0
 Summary: A framework for creating trading bots
 Author: MDUYN
 Requires-Python: >=3.10,<4.0
@@ -27,9 +27,11 @@ Requires-Dist: ccxt (>=4.2.48)
 Requires-Dist: dependency-injector (>=4.40.0)
 Requires-Dist: jupyter (>=1.0.0)
 Requires-Dist: marshmallow (>=3.5.0)
+Requires-Dist: msgpack (>=1.0.0)
 Requires-Dist: plotly (>=6.1.2,<7.0.0)
 Requires-Dist: polars[numpy,pandas] (>=0.20.10)
 Requires-Dist: polygon-api-client (>=1.14.0,<2.0.0) ; extra == "polygon" or extra == "all"
+Requires-Dist: pyarrow (>=14.0.0)
 Requires-Dist: python-dateutil (>=2.8.2)
 Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
 Requires-Dist: schedule (>=1.1.0)
@@ -37,6 +39,7 @@ Requires-Dist: tabulate (>=0.9.0)
 Requires-Dist: tqdm (>=4.66.1)
 Requires-Dist: wrapt (>=1.16.0)
 Requires-Dist: yfinance (>=0.2.61,<0.3.0) ; extra == "yahoo" or extra == "all"
+Requires-Dist: zstandard (>=0.20.0)
 Description-Content-Type: text/markdown
 
 <h1 align="center">
@@ -124,6 +127,7 @@ This framework is built around the full loop: **create strategies → vector bac
 - 🎯 **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

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

@@ -83,6 +83,7 @@ This framework is built around the full loop: **create strategies → vector bac
 - 🎯 **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

{investing_algorithm_framework-8.6.1 → investing_algorithm_framework-8.7.0}/investing_algorithm_framework/__init__.py

@@ -30,7 +30,11 @@ from .domain import ApiException, combine_backtests, PositionSize, \
     VolumeImpactSlippage, \
     CommissionModel, NoCommission, PercentageCommission, FixedCommission, \
     FillModel, FullFill, VolumeBasedFill, \
-    FXRateProvider, StaticFXRateProvider
+    FXRateProvider, StaticFXRateProvider, \
+    Pipeline, Factor, CustomFactor, Filter, \
+    Returns, AverageDollarVolume, AverageTradedValue, SMA, RSI, \
+    Volatility, StaticPerSymbol, CrossSectionalMean, RollingBeta, \
+    Neutralize
 from .infrastructure import AzureBlobStorageStateHandler, \
     CSVOHLCVDataProvider, CSVTickerDataProvider, CSVURLDataProvider, \
     JSONURLDataProvider, ParquetURLDataProvider, \
@@ -256,6 +260,21 @@ __all__ = [
     "VolumeBasedFill",
     "FXRateProvider",
     "StaticFXRateProvider",
+    # Pipeline API (Phase 1, see docs/design/pipeline-api.md)
+    "Pipeline",
+    "Factor",
+    "CustomFactor",
+    "Filter",
+    "Returns",
+    "AverageDollarVolume",
+    "AverageTradedValue",
+    "SMA",
+    "RSI",
+    "Volatility",
+    "StaticPerSymbol",
+    "CrossSectionalMean",
+    "RollingBeta",
+    "Neutralize",
     "load_ipython_extension",
     "get_cv_consistency",
     "get_normalized_stability",

{investing_algorithm_framework-8.6.1 → investing_algorithm_framework-8.7.0}/investing_algorithm_framework/app/eventloop.py

@@ -1,6 +1,6 @@
 from datetime import datetime, timedelta, timezone
 from time import sleep
-from typing import List, Set, Dict
+from typing import List, Set, Dict, FrozenSet, Tuple, Optional, Type
 from logging import getLogger
 
 import polars as pl
@@ -10,6 +10,7 @@ from investing_algorithm_framework.domain import Environment, ENVIRONMENT, \
     TradeStatus, SNAPSHOT_INTERVAL, SnapshotInterval, OperationalException, \
     LAST_SNAPSHOT_DATETIME, INDEX_DATETIME
 from investing_algorithm_framework.services import TradeOrderEvaluator
+from investing_algorithm_framework.services.pipeline import PipelineEngine
 
 from .algorithm import Algorithm
 from .strategy import TradingStrategy
@@ -82,6 +83,19 @@ class EventLoopService:
         self.data_sources = set()
         self.next_run_times = {}
         self.history = {}
+        self._pipeline_engine = PipelineEngine()
+
+        # Per (strategy_id, pipeline_cls) cache of the most recent
+        # universe-refresh: (refresh_at, frozen surviving-symbol set).
+        # Populated when a pipeline declares
+        # ``refresh_universe_every`` so the engine can skip re-running
+        # the universe filter every bar.
+        self._pipeline_universe_cache: Dict[
+            Tuple[str, Type], Tuple[datetime, FrozenSet[str]]
+        ] = {}
+        # One-shot flag: live-mode envelope validation runs once per
+        # process. Reset by ``cleanup`` so a new run re-validates.
+        self._pipelines_live_validated: bool = False
 
     @staticmethod
     def _get_data_sources_for_iteration(
@@ -330,6 +344,11 @@ class EventLoopService:
             None
         """
         self._portfolio_snapshot_service.save_all(self._snapshots)
+        # Reset per-run pipeline state so a subsequent run re-runs
+        # live envelope validation and starts with a fresh universe
+        # cache.
+        self._pipeline_universe_cache.clear()
+        self._pipelines_live_validated = False
 
     def start(
         self,
@@ -443,6 +462,232 @@ class EventLoopService:
 
         self.cleanup()
 
+    # ------------------------------------------------------------------ #
+    # Pipeline live-mode helpers (#503 phase 3b/3c/3d)
+    # ------------------------------------------------------------------ #
+    # Envelope: v1 of live pipelines supports daily timeframes only and
+    # caps universes at 50 symbols per pipeline. Any sub-daily timeframe
+    # on a strategy that declares pipelines, or a strategy whose total
+    # OHLCV symbol set exceeds the cap, raises at first iteration when
+    # running outside backtest mode. See #503.
+    _LIVE_MAX_PIPELINE_SYMBOLS: int = 50
+    _LIVE_MIN_TIMEFRAME_MINUTES: int = 24 * 60  # daily
+
+    def _validate_live_envelope(
+        self, strategies: List[TradingStrategy]
+    ) -> None:
+        """Validate the v1 live-pipeline envelope (max 50 symbols /
+        daily-or-coarser timeframes). Called once per run when env is
+        not BACKTEST. Raises :class:`OperationalException` on
+        violation."""
+        for strategy in strategies or []:
+            pipelines = getattr(strategy, "pipelines", None)
+            if not pipelines:
+                continue
+
+            ohlcv_sources = [
+                ds for ds in (strategy.data_sources or [])
+                if DataType.OHLCV.equals(ds.data_type)
+            ]
+
+            sub_daily = [
+                ds for ds in ohlcv_sources
+                if ds.time_frame is not None
+                and ds.time_frame.amount_of_minutes
+                < self._LIVE_MIN_TIMEFRAME_MINUTES
+            ]
+            if sub_daily:
+                desc = ", ".join(
+                    f"{ds.symbol}@{ds.time_frame.value}"
+                    for ds in sub_daily
+                )
+                raise OperationalException(
+                    f"Strategy '{strategy.strategy_id}' declares "
+                    f"pipelines but uses sub-daily OHLCV timeframes "
+                    f"in live mode: {desc}. v1 of the live pipeline "
+                    f"engine supports daily timeframes only — see "
+                    f"#503. Use a daily timeframe or run the strategy "
+                    f"in backtest mode."
+                )
+
+            unique_symbols = {ds.symbol for ds in ohlcv_sources}
+            unique_symbols.discard(None)
+            if len(unique_symbols) > self._LIVE_MAX_PIPELINE_SYMBOLS:
+                raise OperationalException(
+                    f"Strategy '{strategy.strategy_id}' declares "
+                    f"pipelines over {len(unique_symbols)} symbols, "
+                    f"which exceeds the v1 live cap of "
+                    f"{self._LIVE_MAX_PIPELINE_SYMBOLS}. Reduce the "
+                    f"universe or run the strategy in backtest mode "
+                    f"(see #503)."
+                )
+
+    def _maybe_validate_live_envelope(
+        self, strategies: List[TradingStrategy], environment: str
+    ) -> None:
+        """One-shot envelope validation; no-op for BACKTEST mode."""
+        if self._pipelines_live_validated:
+            return
+        if Environment.BACKTEST.equals(environment):
+            self._pipelines_live_validated = True
+            return
+        self._validate_live_envelope(strategies)
+        self._pipelines_live_validated = True
+
+    def _filter_symbols_for_universe_cache(
+        self,
+        strategy_id: str,
+        pipeline_cls: Type,
+        symbol_to_identifier: Dict[str, str],
+        as_of: datetime,
+    ) -> Optional[Dict[str, str]]:
+        """If ``pipeline_cls`` declares ``refresh_universe_every`` and
+        we have a cached surviving-symbol set still inside the cadence,
+        return a restricted ``symbol_to_identifier`` mapping. Returning
+        ``None`` means "no cache hit — run a full universe evaluation".
+        """
+        cadence: Optional[timedelta] = getattr(
+            pipeline_cls, "refresh_universe_every", None
+        )
+        if cadence is None or cadence <= timedelta(0):
+            return None
+
+        cache_key = (strategy_id, pipeline_cls)
+        cached = self._pipeline_universe_cache.get(cache_key)
+        if cached is None:
+            return None
+
+        last_refresh, symbols = cached
+        # Normalise tz so naive backtest datetimes and aware live
+        # datetimes compare cleanly.
+        if last_refresh.tzinfo is None and as_of.tzinfo is not None:
+            cmp_as_of = as_of.replace(tzinfo=None)
+        elif last_refresh.tzinfo is not None and as_of.tzinfo is None:
+            cmp_as_of = as_of.replace(tzinfo=last_refresh.tzinfo)
+        else:
+            cmp_as_of = as_of
+        if cmp_as_of - last_refresh >= cadence:
+            return None  # cadence elapsed → refresh
+
+        # Cache hit: restrict the symbol set, skipping the universe
+        # filter entirely on this iteration.
+        return {
+            sym: ident
+            for sym, ident in symbol_to_identifier.items()
+            if sym in symbols
+        }
+
+    def _run_pipelines(
+        self,
+        strategy: TradingStrategy,
+        data: Dict,
+        data_object: Dict,
+        as_of: datetime,
+    ) -> None:
+        """Compute cross-sectional pipelines attached to ``strategy``
+        and inject their outputs into ``data`` keyed by pipeline
+        class name.
+
+        Strategies without ``pipelines`` skip this entirely (zero cost).
+
+        Live-mode hardening (#503):
+
+        * The v1 envelope (max 50 symbols, daily-or-coarser timeframes)
+          is validated once per run.
+        * Pipelines that declare ``refresh_universe_every`` reuse the
+          last surviving symbol set within the cadence — saving the
+          cost of evaluating the universe filter every bar.
+        * In non-backtest environments, a single failing pipeline is
+          logged and skipped (the iteration continues with an empty
+          output) instead of killing the whole event loop. Backtests
+          keep raising so failures stay deterministic.
+        """
+        pipelines = getattr(strategy, "pipelines", None)
+        if not pipelines:
+            return
+
+        config = self._configuration_service.get_config()
+        environment = config[ENVIRONMENT]
+        is_backtest = Environment.BACKTEST.equals(environment)
+
+        # Map symbol -> data-source identifier from the strategy's
+        # OHLCV data sources. If a symbol appears on multiple data
+        # sources (e.g. multiple timeframes) the first OHLCV match wins.
+        symbol_to_identifier: Dict[str, str] = {}
+        for ds in strategy.data_sources or []:
+            if not DataType.OHLCV.equals(ds.data_type):
+                continue
+            if ds.symbol is None or ds.symbol in symbol_to_identifier:
+                continue
+            symbol_to_identifier[ds.symbol] = ds.get_identifier()
+
+        if not symbol_to_identifier:
+            logger.warning(
+                "Strategy %s declares pipelines but has no OHLCV data "
+                "sources to feed them; pipelines will be skipped.",
+                strategy.strategy_id,
+            )
+            return
+
+        for pipeline_cls in pipelines:
+            # 3c: universe-refresh cache. If the pipeline declares a
+            # refresh cadence and we're inside it, restrict the panel
+            # input to the cached symbols.
+            cached_mapping = self._filter_symbols_for_universe_cache(
+                strategy_id=strategy.strategy_id,
+                pipeline_cls=pipeline_cls,
+                symbol_to_identifier=symbol_to_identifier,
+                as_of=as_of,
+            )
+            mapping = (
+                cached_mapping
+                if cached_mapping is not None
+                else symbol_to_identifier
+            )
+
+            try:
+                output = self._pipeline_engine.evaluate(
+                    pipeline_cls=pipeline_cls,
+                    data_object=data_object,
+                    symbol_to_identifier=mapping,
+                    as_of=as_of,
+                )
+            except Exception:
+                # 3d: live-mode resilience. In live trading a single
+                # pipeline failure must not kill the iteration —
+                # surface an empty frame and log so the rest of the
+                # strategies can still run. Backtests re-raise so
+                # failures stay deterministic.
+                logger.exception(
+                    "Pipeline %s failed during evaluation at %s",
+                    pipeline_cls.__name__,
+                    as_of,
+                )
+                if is_backtest:
+                    raise
+                output = self._pipeline_engine._empty_output(
+                    pipeline_cls
+                )
+
+            # 3c: refresh the universe cache when we just ran a full
+            # evaluation (cached_mapping was None) and the pipeline
+            # declares a cadence.
+            cadence = getattr(
+                pipeline_cls, "refresh_universe_every", None
+            )
+            if (
+                cadence is not None
+                and cadence > timedelta(0)
+                and cached_mapping is None
+                and "symbol" in output.columns
+            ):
+                surviving = frozenset(output["symbol"].to_list())
+                self._pipeline_universe_cache[
+                    (strategy.strategy_id, pipeline_cls)
+                ] = (as_of, surviving)
+
+            data[pipeline_cls.__name__] = output
+
     def _run_iteration(
         self,
         strategies: List[TradingStrategy] = None,
@@ -470,6 +715,11 @@ class EventLoopService:
         environment = config[ENVIRONMENT]
         current_datetime = config[INDEX_DATETIME]
 
+        # Validate the live-pipeline envelope (max 50 symbols /
+        # daily-or-coarser timeframes) once per run. No-op for
+        # backtests. See #503 phase 3b.
+        self._maybe_validate_live_envelope(strategies, environment)
+
         # Step 1: Collect all data for the strategies and for the
         # pending orders
         open_orders = self._order_service.get_all(
@@ -553,6 +803,17 @@ class EventLoopService:
             else:
                 data = {}
 
+            # Step 5b: Run any cross-sectional pipelines attached to
+            # the strategy (Phase 1 of the Pipeline API, see
+            # docs/design/pipeline-api.md). Strategies without
+            # ``pipelines`` skip this entirely.
+            self._run_pipelines(
+                strategy=strategy,
+                data=data,
+                data_object=data_object,
+                as_of=current_datetime,
+            )
+
             for on_strategy_run_hook in \
                     self._algorithm.on_strategy_run_hooks:
                 on_strategy_run_hook.execute(

{investing_algorithm_framework-8.6.1 → investing_algorithm_framework-8.7.0}/investing_algorithm_framework/app/reporting/backtest_report.py

@@ -12,7 +12,7 @@ from datetime import datetime, timedelta
 from jinja2 import Environment, FileSystemLoader
 
 from investing_algorithm_framework.domain import (
-    Backtest, OperationalException, tqdm
+    Backtest, OperationalException, tqdm, BUNDLE_EXT
 )
 
 logger = logging.getLogger("investing_algorithm_framework")
@@ -217,9 +217,15 @@ class BacktestReport:
 
     @staticmethod
     def _is_backtest(backtest_path):
+        if not os.path.exists(backtest_path):
+            return False
+        # Bundle file (.iafbt)
+        if os.path.isfile(backtest_path) and \
+                backtest_path.endswith(BUNDLE_EXT):
+            return True
+        # Legacy directory layout
         return (
-            os.path.exists(backtest_path)
-            and os.path.isdir(backtest_path)
+            os.path.isdir(backtest_path)
             and os.path.isfile(
                 os.path.join(backtest_path, "algorithm_id.json")
             )
@@ -231,6 +237,7 @@ class BacktestReport:
         backtests: List[Backtest] = None,
         directory_path: Union[str, List[str], None] = None,
         show_progress: bool = False,
+        workers: Union[int, None] = None,
     ) -> "BacktestReport":
         loaded = []
         source_tags = []
@@ -254,7 +261,7 @@ class BacktestReport:
             if BacktestReport._is_backtest(dp):
                 backtest_paths.append((dp, tag))
             else:
-                for root, dirs, _ in os.walk(dp):
+                for root, dirs, files in os.walk(dp):
                     for dir_name in dirs:
                         subdir = os.path.join(
                             root, dir_name
@@ -265,6 +272,11 @@ class BacktestReport:
                             backtest_paths.append(
                                 (subdir, tag)
                             )
+                    for file_name in files:
+                        if file_name.endswith(BUNDLE_EXT):
+                            backtest_paths.append(
+                                (os.path.join(root, file_name), tag)
+                            )
 
         iterator = backtest_paths
         if show_progress:
@@ -273,9 +285,43 @@ class BacktestReport:
                 desc="Loading backtests",
             )
 
-        for path, tag in iterator:
-            loaded.append(Backtest.open(path))
-            source_tags.append(tag)
+        # Parallel load is opt-in (workers > 1). ProcessPoolExecutor
+        # startup costs typically dwarf the per-backtest decode for
+        # batches < ~30, so keep default behaviour serial. Pass
+        # ``workers=N`` (or ``-1`` for cpu_count) to load large
+        # batches in parallel.
+        from investing_algorithm_framework.domain.backtesting.\
+backtest_utils import (
+            _load_one_dispatch, _resolve_workers,
+        )
+
+        n = len(backtest_paths)
+        resolved_workers = (
+            _resolve_workers(workers) if workers is not None else 1
+        )
+        if resolved_workers > 1 and n >= 4:
+            from concurrent.futures import ProcessPoolExecutor
+
+            items = [
+                (path, "bundle" if path.endswith(BUNDLE_EXT) else "dir")
+                for path, _ in backtest_paths
+            ]
+            with ProcessPoolExecutor(max_workers=resolved_workers) as ex:
+                results = list(
+                    tqdm(
+                        ex.map(_load_one_dispatch, items),
+                        total=n,
+                        desc="Loading backtests",
+                        disable=not show_progress,
+                    )
+                )
+            for bt, (_, tag) in zip(results, backtest_paths):
+                loaded.append(bt)
+                source_tags.append(tag)
+        else:
+            for path, tag in iterator:
+                loaded.append(Backtest.open(path))
+                source_tags.append(tag)
 
         for bt in backtests:
             if not isinstance(bt, Backtest):

{investing_algorithm_framework-8.6.1 → investing_algorithm_framework-8.7.0}/investing_algorithm_framework/app/strategy.py

@@ -48,6 +48,7 @@ class TradingStrategy:
     strategy_id: str = None
     decorated = None
     data_sources: List[DataSource] = []
+    pipelines: List[type] = []
     traces = None
     context: Context = None
     metadata: Dict[str, Any] = None
@@ -131,6 +132,13 @@ class TradingStrategy:
             self.data_sources = list(class_data_sources) \
                 if class_data_sources else []
 
+        # Initialize pipelines as a new list per instance. Pipelines
+        # are class-attribute opt-in (Phase 1 of the Pipeline API,
+        # see docs/design/pipeline-api.md). When empty, the engine
+        # is never invoked and there is zero behavioural change.
+        class_pipelines = getattr(self.__class__, 'pipelines', [])
+        self.pipelines = list(class_pipelines) if class_pipelines else []
+
         if decorated is not None:
             self.decorated = decorated
 
@@ -186,6 +194,57 @@ class TradingStrategy:
                     f"interval or use a smaller data timeframe."
                 )
 
+        # Validate that every declared pipeline has enough warmup on
+        # the strategy's OHLCV data sources to compute its longest
+        # factor window. Without this check a live strategy starts
+        # silently emitting NaN columns until enough bars accrue.
+        # Tracked under #503 (Phase 3 — live hardening).
+        if self.pipelines:
+            ohlcv_sources = [
+                ds for ds in self.data_sources
+                if DataType.OHLCV.equals(ds.data_type)
+            ]
+            if not ohlcv_sources:
+                raise OperationalException(
+                    f"Strategy '{self.strategy_id}' declares "
+                    f"{len(self.pipelines)} pipeline(s) but has no "
+                    f"OHLCV data sources. Pipelines build their panel "
+                    f"from the strategy's OHLCV data sources — add at "
+                    f"least one DataSource(data_type=DataType.OHLCV, "
+                    f"...) to data_sources."
+                )
+            for pipeline_cls in self.pipelines:
+                required = pipeline_cls.required_window()
+                # We compare against each OHLCV source's warmup_window
+                # (canonical) / window_size (legacy alias) — the
+                # framework keeps them in sync, but a source may
+                # legitimately leave both unset, which we treat as
+                # "insufficient" because the pipeline cannot guarantee
+                # a full window of data.
+                short_sources = [
+                    ds for ds in ohlcv_sources
+                    if ds.warmup_window is None
+                    or ds.warmup_window < required
+                ]
+                if short_sources:
+                    short_desc = ", ".join(
+                        f"{ds.symbol}@{ds.time_frame.value if ds.time_frame else '?'}"  # noqa: E501
+                        f" (warmup_window="
+                        f"{ds.warmup_window if ds.warmup_window is not None else 'unset'})"  # noqa: E501
+                        for ds in short_sources
+                    )
+                    raise OperationalException(
+                        f"Strategy '{self.strategy_id}' pipeline "
+                        f"'{pipeline_cls.__name__}' requires a "
+                        f"warmup window of {required} bars but the "
+                        f"following OHLCV data source(s) have an "
+                        f"insufficient warmup_window: {short_desc}. "
+                        f"Set warmup_window>={required} on each OHLCV "
+                        f"DataSource the pipeline relies on, otherwise "
+                        f"the pipeline will emit NaN columns until "
+                        f"enough bars accrue."
+                    )
+
         # Initialize stop_losses as a new list per instance
         if stop_losses is not None:
             self.stop_losses = list(stop_losses)

{investing_algorithm_framework-8.6.1 → investing_algorithm_framework-8.7.0}/investing_algorithm_framework/cli/cli.py

@@ -250,3 +250,73 @@ def mcp(directory):
 
 
 cli.add_command(mcp)
+
+
+@click.command(name="migrate-backtests")
+@click.option(
+    "--src", "-s",
+    required=True,
+    type=click.Path(exists=True, file_okay=False, dir_okay=True),
+    help="Source directory containing legacy backtest sub-directories.",
+)
+@click.option(
+    "--dst", "-d",
+    required=True,
+    type=click.Path(file_okay=False, dir_okay=True),
+    help="Destination directory for the new ``.iafbt`` bundle files.",
+)
+@click.option(
+    "--workers", "-w", type=int, default=None,
+    help="Number of parallel workers (default: min(8, CPU count)).",
+)
+@click.option(
+    "--no-index", is_flag=True, default=False,
+    help="Skip writing index.parquet at the destination.",
+)
+@click.option(
+    "--include-ohlcv", is_flag=True, default=False,
+    help="Include OHLCV data in the destination bundles.",
+)
+@click.option(
+    "--no-skip-existing", is_flag=True, default=False,
+    help="Re-migrate even if the destination bundle already exists.",
+)
+@click.option(
+    "--delete-source", is_flag=True, default=False,
+    help=(
+        "Delete each source directory/bundle after its destination "
+        "has been written successfully. Use with care."
+    ),
+)
+def migrate_backtests_cmd(
+    src, dst, workers, no_index, include_ohlcv, no_skip_existing,
+    delete_source,
+):
+    """Convert a directory of legacy backtest folders into the bundled
+    binary format introduced in issue #487.
+
+    The new ``.iafbt`` format is a single zstd-compressed MessagePack
+    file per backtest. Loading bundled directories is dramatically
+    faster than the legacy multi-file layout for large batches.
+
+    Migration is streamed (load+save fused per worker) so memory
+    usage stays roughly constant regardless of source size, and
+    interrupted runs can be resumed (existing destination bundles
+    are skipped by default).
+    """
+    from investing_algorithm_framework.domain import migrate_backtests
+
+    n = migrate_backtests(
+        src,
+        dst,
+        workers=workers,
+        show_progress=True,
+        write_index=not no_index,
+        include_ohlcv=include_ohlcv,
+        skip_existing=not no_skip_existing,
+        delete_source=delete_source,
+    )
+    click.echo(f"Migrated {n} backtest(s) from {src} to {dst}")
+
+
+cli.add_command(migrate_backtests_cmd)