Qubx 0.5.0__tar.gz → 0.5.3__tar.gz

{qubx-0.5.0 → qubx-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: Qubx
-Version: 0.5.0
+Version: 0.5.3
 Summary: Qubx - quantitative trading framework
 Home-page: https://github.com/dmarienko/Qubx
 Author: Dmitry Marienko
@@ -16,6 +16,7 @@ Requires-Dist: cython (==3.0.8)
 Requires-Dist: dash (>=2.18.2,<3.0.0)
 Requires-Dist: dash-bootstrap-components (>=1.6.0,<2.0.0)
 Requires-Dist: importlib-metadata
+Requires-Dist: jupyter-console (>=6.6.3,<7.0.0)
 Requires-Dist: loguru (>=0.7.2,<0.8.0)
 Requires-Dist: matplotlib (>=3.8.4,<4.0.0)
 Requires-Dist: msgspec (>=0.18.6,<0.19.0)
@@ -38,6 +39,8 @@ Requires-Dist: scipy (>=1.12.0,<2.0.0)
 Requires-Dist: sortedcontainers (>=2.4.0,<3.0.0)
 Requires-Dist: stackprinter (>=0.2.10,<0.3.0)
 Requires-Dist: statsmodels (>=0.14.2,<0.15.0)
+Requires-Dist: tabulate (>=0.9.0,<0.10.0)
+Requires-Dist: toml (>=0.10.2,<0.11.0)
 Requires-Dist: tqdm
 Project-URL: Repository, https://github.com/dmarienko/Qubx
 Description-Content-Type: text/markdown

{qubx-0.5.0 → qubx-0.5.3}/pyproject.toml

@@ -1,12 +1,13 @@
 [tool.poetry]
 name = "Qubx"
-version = "0.5.0"
+version = "0.5.3"
 description = "Qubx - quantitative trading framework"
-authors = ["Dmitry Marienko <dmitry@gmail.com>", "Yuriy Arabskyy <yuriy.arabskyy@gmail.com>"]
-readme = "README.md"
-packages = [
-    { include = "qubx", from = "src" },
+authors = [
+    "Dmitry Marienko <dmitry@gmail.com>",
+    "Yuriy Arabskyy <yuriy.arabskyy@gmail.com>",
 ]
+readme = "README.md"
+packages = [{ include = "qubx", from = "src" }]
 repository = "https://github.com/dmarienko/Qubx"
 include = [
     # Compiled extensions must be included in the wheel distributions
@@ -45,6 +46,9 @@ msgspec = "^0.18.6"
 pyyaml = "^6.0.2"
 dash = "^2.18.2"
 dash-bootstrap-components = "^1.6.0"
+tabulate = "^0.9.0"
+jupyter-console = "^6.6.3"
+toml = "^0.10.2"
 
 [tool.poetry.group.dev.dependencies]
 pre-commit = "^2.20.0"
@@ -59,7 +63,13 @@ click = "^8.1.7"
 ipywidgets = "^8.1.5"
 
 [build-system]
-requires = ["poetry-core", "setuptools", "numpy>=1.26.3", "cython==3.0.8", "toml>=0.10.2"]
+requires = [
+    "poetry-core",
+    "setuptools",
+    "numpy>=1.26.3",
+    "cython==3.0.8",
+    "toml>=0.10.2",
+]
 build-backend = "poetry.core.masonry.api"
 
 [tool.poetry.build]
@@ -67,7 +77,7 @@ script = "build.py"
 generate-setup-file = false
 
 [tool.poetry.group.test.dependencies]
-pytest = {extras = ["lazyfixture"], version = "^8.2.0"}
+pytest = { extras = ["lazyfixture"], version = "^8.2.0" }
 pytest-asyncio = "^0.24.0"
 pytest-mock = "*"
 
@@ -75,16 +85,15 @@ pytest-mock = "*"
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 pythonpath = ["src"]
-markers = [
-    "integration: mark a test as an integration test",
-]
+markers = ["integration: mark a test as an integration test"]
 addopts = "--disable-warnings -s"
-filterwarnings = [
-    "ignore:.*Jupyter is migrating.*:DeprecationWarning",
-]
+filterwarnings = ["ignore:.*Jupyter is migrating.*:DeprecationWarning"]
 
 [tool.ruff]
 line-length = 120
 
 [tool.ruff.lint.extend-per-file-ignores]
-"*.ipynb" = ["F405", "F401", "E701", "E402", "F403", "E401", "E702"]
+"*.ipynb" = ["F405", "F401", "E701", "E402", "F403", "E401", "E702"]
+
+[tool.poetry.scripts]
+qubx = "qubx.cli.commands:main"

{qubx-0.5.0 → qubx-0.5.3}/src/qubx/__init__.py

@@ -1,10 +1,13 @@
+import os
+import sys
 from typing import Callable
-from qubx.utils import set_mpl_theme, runtime_env
-from qubx.utils.misc import install_pyx_recompiler_for_dev
 
+import stackprinter
 from loguru import logger
-import os, sys, stackprinter
+
 from qubx.core.lookups import FeesLookup, GlobalLookup, InstrumentsLookup
+from qubx.utils import runtime_env, set_mpl_theme
+from qubx.utils.misc import install_pyx_recompiler_for_dev
 
 # - TODO: import some main methods from packages
 
@@ -34,7 +37,7 @@ def formatter(record):
 class QubxLogConfig:
     @staticmethod
     def get_log_level():
-        return os.getenv("QUBX_LOG_LEVEL", "DEBUG")
+        return os.getenv("QUBX_LOG_LEVEL", "WARNING")
 
     @staticmethod
     def set_log_level(level: str):
@@ -66,8 +69,8 @@ lookup = GlobalLookup(InstrumentsLookup(), FeesLookup())
 
 # registering magic for jupyter notebook
 if runtime_env() in ["notebook", "shell"]:
-    from IPython.core.magic import Magics, magics_class, line_magic, line_cell_magic
     from IPython.core.getipython import get_ipython
+    from IPython.core.magic import Magics, line_cell_magic, line_magic, magics_class
 
     @magics_class
     class QubxMagics(Magics):
@@ -112,7 +115,7 @@ if runtime_env() in ["notebook", "shell"]:
                     # - temporary workaround for vscode - dark theme not applying to ipywidgets in notebook
                     # - see https://github.com/microsoft/vscode-jupyter/issues/7161
                     if runtime_env() == "notebook":
-                        _vscode_clr_trick = """from IPython.display import display, HTML; display(HTML("<style> .cell-output-ipywidget-background { background-color: transparent !important; } :root { --jp-widgets-color: var(--vscode-editor-foreground); --jp-widgets-font-size: var(--vscode-editor-font-size); } </style>"))"""
+                        _vscode_clr_trick = """from IPython.display import display, HTML; display(HTML("<style> .cell-output-ipywidget-background { background-color: transparent !important; } :root { --jp-widgets-color: var(--vscode-editor-foreground); --jp-widgets-font-size: var(--vscode-editor-font-size); } .widget-hprogress, .jupyter-widget-hprogress { height: 16px; align-self: center; kj} table.dataframe, .dataframe td, .dataframe tr { border: 1px solid #55554a85; border-collapse: collapse; color: #859548d9 !important; } .dataframe th { border: 1px solid #55554a85; border-collapse: collapse; background-color: #010101 !important; color: #177 !important; } </style>"))"""
                         exec(_vscode_clr_trick, self.shell.user_ns)
 
                 elif "light" in line.lower():
@@ -136,7 +139,8 @@ if runtime_env() in ["notebook", "shell"]:
 
             """
             import multiprocessing as m
-            import time, re
+            import re
+            import time
 
             # create ext args
             name = None
@@ -151,7 +155,7 @@ if runtime_env() in ["notebook", "shell"]:
                         return
 
                 ipy = get_ipython()
-                for a in [x for x in re.split("[\ ,;]", line.strip()) if x]:
+                for a in [x for x in re.split(r"[\ ,;]", line.strip()) if x]:
                     ipy.push({a: self._get_manager().Value(None, None)})
 
             # code to run

{qubx-0.5.0 → qubx-0.5.3}/src/qubx/_nb_magic.py

@@ -32,60 +32,61 @@ if runtime_env() in ["notebook", "shell"]:
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
     # - - - - Common stuff - - - -
+    from datetime import time, timedelta
+
     import numpy as np
     import pandas as pd
-    from datetime import time, timedelta
+
+    # - - - - Charting stuff - - - -
+    from matplotlib import pyplot as plt
     from tqdm.auto import tqdm
 
     # - - - - TA stuff and indicators - - - -
     import qubx.pandaz.ta as pta
     import qubx.ta.indicators as ta
+    from qubx.backtester.optimization import variate
+
+    # - - - - Simulator stuff - - - -
+    from qubx.backtester.simulator import simulate
 
     # - - - - Portfolio analysis - - - -
     from qubx.core.metrics import (
-        tearsheet,
         chart_signals,
-        get_symbol_pnls,
-        get_equity,
-        portfolio_metrics,
-        pnl,
         drop_symbols,
+        get_symbol_pnls,
         pick_symbols,
+        pnl,
+        portfolio_metrics,
+        tearsheet,
     )
+    from qubx.data.helpers import loader
 
     # - - - - Data reading - - - -
     from qubx.data.readers import (
-        CsvStorageDataReader,
-        MultiQdbConnector,
-        QuestDBConnector,
         AsOhlcvSeries,
         AsPandasFrame,
         AsQuotes,
         AsTimestampedRecords,
+        CsvStorageDataReader,
+        MultiQdbConnector,
+        QuestDBConnector,
         RestoreTicksFromOHLC,
     )
-    from qubx.data.helpers import loader
-
-    # - - - - Simulator stuff - - - -
-    from qubx.backtester.simulator import simulate
-    from qubx.backtester.optimization import variate
-
-    # - - - - Charting stuff - - - -
-    from matplotlib import pyplot as plt
-    from qubx.utils.charting.mpl_helpers import fig, subplot, sbp, plot_trends, ohlc_plot
-    from qubx.utils.charting.lookinglass import LookingGlass
 
     # - - - - Utils - - - -
     from qubx.pandaz.utils import (
-        scols,
-        srows,
-        ohlc_resample,
         continuous_periods,
-        generate_equal_date_ranges,
         drop_duplicated_indexes,
+        generate_equal_date_ranges,
+        ohlc_resample,
         retain_columns_and_join,
         rolling_forward_test_split,
+        scols,
+        srows,
     )
+    from qubx.utils.charting.lookinglass import LookingGlass
+    from qubx.utils.charting.mpl_helpers import fig, ohlc_plot, plot_trends, sbp, subplot
+    from qubx.utils.misc import this_project_root
 
     # - setup short numpy output format
     np_fmt_short()

{qubx-0.5.0 → qubx-0.5.3}/src/qubx/backtester/__init__.py

@@ -1,2 +1,3 @@
-from .simulator import simulate
+from .management import BacktestsResultsManager
 from .optimization import variate
+from .simulator import simulate

{qubx-0.5.0 → qubx-0.5.3}/src/qubx/backtester/account.py

@@ -7,11 +7,12 @@ from qubx.core.basics import (
     Instrument,
     Order,
     Position,
+    Timestamped,
     TransactionCostsCalculator,
     dt_64,
 )
 from qubx.core.interfaces import ITimeProvider
-from qubx.core.series import Bar, Quote, Trade
+from qubx.core.series import Bar, OrderBook, Quote, Trade
 
 
 class SimulatedAccountProcessor(BasicAccountProcessor):
@@ -45,7 +46,7 @@ class SimulatedAccountProcessor(BasicAccountProcessor):
         self._half_tick_size = {}
         self._fill_stop_order_at_price = accurate_stop_orders_execution
         if self._fill_stop_order_at_price:
-            logger.info(f"{self.__class__.__name__} emulates stop orders executions at exact price")
+            logger.info(f"[<y>{self.__class__.__name__}</y>] :: emulates stop orders executions at exact price")
 
     def get_orders(self, instrument: Instrument | None = None) -> list[Order]:
         if instrument is not None:
@@ -101,23 +102,32 @@ class SimulatedAccountProcessor(BasicAccountProcessor):
         return super().process_order(order, update_locked_value)
 
     def emulate_quote_from_data(
-        self, instrument: Instrument, timestamp: dt_64, data: float | Trade | Bar
+        self, instrument: Instrument, timestamp: dt_64, data: float | Timestamped
     ) -> Quote | None:
         if instrument not in self._half_tick_size:
             _ = self.get_position(instrument)
 
-        _ts2 = self._half_tick_size[instrument]
         if isinstance(data, Quote):
             return data
+
         elif isinstance(data, Trade):
+            _ts2 = self._half_tick_size[instrument]
             if data.taker:  # type: ignore
                 return Quote(timestamp, data.price - _ts2 * 2, data.price, 0, 0)  # type: ignore
             else:
                 return Quote(timestamp, data.price, data.price + _ts2 * 2, 0, 0)  # type: ignore
+
         elif isinstance(data, Bar):
+            _ts2 = self._half_tick_size[instrument]
             return Quote(timestamp, data.close - _ts2, data.close + _ts2, 0, 0)  # type: ignore
+
+        elif isinstance(data, OrderBook):
+            return data.to_quote()
+
         elif isinstance(data, float):
+            _ts2 = self._half_tick_size[instrument]
             return Quote(timestamp, data - _ts2, data + _ts2, 0, 0)
+
         else:
             return None
 

{qubx-0.5.0 → qubx-0.5.3}/src/qubx/backtester/broker.py

@@ -18,9 +18,11 @@ class SimulatedBroker(IBroker):
         self,
         channel: CtrlChannel,
         account: SimulatedAccountProcessor,
+        exchange_id: str = "simulated",
     ) -> None:
         self.channel = channel
         self._account = account
+        self._exchange_id = exchange_id
 
     @property
     def is_simulated_trading(self) -> bool:
@@ -80,3 +82,6 @@ class SimulatedBroker(IBroker):
         self.channel.send((instrument, "order", report.order, False))
         if report.exec is not None:
             self.channel.send((instrument, "deals", [report.exec], False))
+
+    def exchange(self) -> str:
+        return self._exchange_id.upper()

{qubx-0.5.0 → qubx-0.5.3}/src/qubx/backtester/data.py

@@ -6,13 +6,14 @@ import pandas as pd
 from tqdm.auto import tqdm
 
 from qubx import logger
-from qubx.backtester.simulated_data import EventBatcher, IterableSimulationData
+from qubx.backtester.simulated_data import IterableSimulationData
 from qubx.core.basics import (
     CtrlChannel,
     DataType,
     Instrument,
     TimestampedDict,
 )
+from qubx.core.exceptions import SimulationError
 from qubx.core.helpers import BasicScheduler
 from qubx.core.interfaces import IDataProvider
 from qubx.core.series import Bar, Quote, time_as_nsec
@@ -74,23 +75,22 @@ class SimulatedDataProvider(IDataProvider):
         start: str | pd.Timestamp,
         end: str | pd.Timestamp,
         silent: bool = False,
-        enable_event_batching: bool = True,
     ) -> None:
         logger.info(f"{self.__class__.__name__} ::: Simulation started at {start} :::")
 
         if self._pregenerated_signals:
             self._prepare_generated_signals(start, end)
-            _run = self._run_generated_signals
-            enable_event_batching = False  # no batching for pre-generated signals
+            _run = self._process_generated_signals
         else:
-            _run = self._run_as_strategy
+            _run = self._process_strategy
 
-        qiter = EventBatcher(self._data_source.create_iterable(start, end), passthrough=not enable_event_batching)
         start, end = pd.Timestamp(start), pd.Timestamp(end)
         total_duration = end - start
         update_delta = total_duration / 100
         prev_dt = pd.Timestamp(start)
 
+        # - date iteration
+        qiter = self._data_source.create_iterable(start, end)
         if silent:
             for instrument, data_type, event, is_hist in qiter:
                 if not _run(instrument, data_type, event, is_hist):
@@ -114,7 +114,9 @@ class SimulatedDataProvider(IDataProvider):
         logger.info(f"{self.__class__.__name__} ::: Simulation finished at {end} :::")
 
     def set_generated_signals(self, signals: pd.Series | pd.DataFrame):
-        logger.debug(f"Using pre-generated signals:\n {str(signals.count()).strip('ndtype: int64')}")
+        logger.debug(
+            f"[<y>{self.__class__.__name__}</y>] :: Using pre-generated signals:\n {str(signals.count()).strip('ndtype: int64')}"
+        )
         # - sanity check
         signals.index = pd.DatetimeIndex(signals.index)
 
@@ -132,11 +134,29 @@ class SimulatedDataProvider(IDataProvider):
         return True
 
     def subscribe(self, subscription_type: str, instruments: set[Instrument], reset: bool) -> None:
-        logger.debug(f" | subscribe: {subscription_type} -> {instruments}")
+        _new_instr = [i for i in instruments if not self.has_subscription(i, subscription_type)]
         self._data_source.add_instruments_for_subscription(subscription_type, list(instruments))
 
+        # - provide historical data and last quote for subscribed instruments
+        for i in _new_instr:
+            h_data = self._data_source.peek_historical_data(i, subscription_type)
+            if h_data:
+                # _s_type = DataType.from_str(subscription_type)[0]
+                last_update = h_data[-1]
+                if last_quote := self._account.emulate_quote_from_data(i, last_update.time, last_update):  # type: ignore
+                    # - send historical data to the channel
+                    self.channel.send((i, subscription_type, h_data, True))
+
+                    # - set last quote
+                    self._last_quotes[i] = last_quote
+
+                    # - also need to pass this quote to OME !
+                    self._account._process_new_quote(i, last_quote)
+
+                    logger.debug(f" | subscribed {subscription_type} {i} -> {last_quote}")
+
     def unsubscribe(self, subscription_type: str, instruments: set[Instrument] | Instrument | None = None) -> None:
-        logger.debug(f" | unsubscribe: {subscription_type} -> {instruments}")
+        # logger.debug(f" | unsubscribe: {subscription_type} -> {instruments}")
         if instruments is not None:
             self._data_source.remove_instruments_from_subscription(
                 subscription_type, [instruments] if isinstance(instruments, Instrument) else list(instruments)
@@ -147,12 +167,12 @@ class SimulatedDataProvider(IDataProvider):
 
     def get_subscriptions(self, instrument: Instrument) -> list[str]:
         _s_lst = self._data_source.get_subscriptions_for_instrument(instrument)
-        logger.debug(f" | get_subscriptions {instrument} -> {_s_lst}")
+        # logger.debug(f" | get_subscriptions {instrument} -> {_s_lst}")
         return _s_lst
 
     def get_subscribed_instruments(self, subscription_type: str | None = None) -> list[Instrument]:
         _in_lst = self._data_source.get_instruments_for_subscription(subscription_type or DataType.ALL)
-        logger.debug(f" | get_subscribed_instruments {subscription_type} -> {_in_lst}")
+        # logger.debug(f" | get_subscribed_instruments {subscription_type} -> {_in_lst}")
         return _in_lst
 
     def warmup(self, configs: dict[tuple[str, Instrument], str]) -> None:
@@ -190,15 +210,16 @@ class SimulatedDataProvider(IDataProvider):
                 if s == i.symbol or s == str(i) or s == f"{i.exchange}:{i.symbol}" or str(s) == str(i):
                     _start, _end = pd.Timestamp(start), pd.Timestamp(end)
                     _start_idx, _end_idx = v.index.get_indexer([_start, _end], method="ffill")
-                    sel = v.iloc[max(_start_idx, 0) : _end_idx + 1]  # sel = v[pd.Timestamp(start) : pd.Timestamp(end)]
+                    sel = v.iloc[max(_start_idx, 0) : _end_idx + 1]
 
+                    # TODO: check if data has exec_price - it means we have deals
                     self._to_process[i] = list(zip(sel.index, sel.values))
                     _s_inst = i
                     break
 
             if _s_inst is None:
                 logger.error(f"Can't find instrument for pregenerated signals with id '{s}'")
-                raise ValueError(f"Can't find instrument for pregenerated signals with id '{s}'")
+                raise SimulationError(f"Can't find instrument for pregenerated signals with id '{s}'")
 
     def _convert_records_to_bars(
         self, records: list[TimestampedDict], cut_time_ns: int, timeframe_ns: int
@@ -228,42 +249,44 @@ class SimulatedDataProvider(IDataProvider):
 
         return bars
 
-    def _run_generated_signals(self, instrument: Instrument, data_type: str, data: Any, is_hist) -> bool:
-        if is_hist:
-            raise ValueError("Historical data is not supported for pre-generated signals !")
+    def _process_generated_signals(self, instrument: Instrument, data_type: str, data: Any, is_hist: bool) -> bool:
+        cc = self.channel
+        t = np.datetime64(data.time, "ns")
 
-        t = data.time  # type: ignore
-        self.time_provider.set_time(np.datetime64(t, "ns"))
+        if not is_hist:
+            # - signals for this instrument
+            sigs = self._to_process[instrument]
 
-        q = self._account.emulate_quote_from_data(instrument, np.datetime64(t, "ns"), data)
-        self._last_quotes[instrument] = q
-        cc = self.channel
+            while sigs and t >= (_signal_time := sigs[0][0].as_unit("ns").asm8):
+                self.time_provider.set_time(_signal_time)
+                cc.send((instrument, "event", {"order": sigs[0][1]}, False))
+                sigs.pop(0)
+
+            if q := self._account.emulate_quote_from_data(instrument, t, data):
+                self._last_quotes[instrument] = q
 
-        # - we need to send quotes for invoking portfolio logging etc
+        self.time_provider.set_time(t)
         cc.send((instrument, data_type, data, is_hist))
-        sigs = self._to_process[instrument]
-        _current_time = self.time_provider.time()
-        while sigs and sigs[0][0].as_unit("ns").asm8 <= _current_time:
-            cc.send((instrument, "event", {"order": sigs[0][1]}, is_hist))
-            sigs.pop(0)
 
         return cc.control.is_set()
 
-    def _run_as_strategy(self, instrument: Instrument, data_type: str, data: Any, is_hist: bool) -> bool:
-        t = data.time  # type: ignore
-        self.time_provider.set_time(np.datetime64(t, "ns"))
-
-        q = self._account.emulate_quote_from_data(instrument, np.datetime64(t, "ns"), data)
+    def _process_strategy(self, instrument: Instrument, data_type: str, data: Any, is_hist: bool) -> bool:
         cc = self.channel
+        t = np.datetime64(data.time, "ns")
 
-        if not is_hist and q is not None:
-            self._last_quotes[instrument] = q
+        if not is_hist:
+            if t >= (_next_exp_time := self._scheduler.next_expected_event_time()):
+                # - we use exact event's time
+                self.time_provider.set_time(_next_exp_time)
+                self._scheduler.check_and_run_tasks()
 
-            # we have to schedule possible crons before sending the data event itself
-            if self._scheduler.check_and_run_tasks():
-                # - push nothing - it will force to process last event
-                cc.send((None, "service_time", None, False))
+            if q := self._account.emulate_quote_from_data(instrument, t, data):
+                self._last_quotes[instrument] = q
 
+        self.time_provider.set_time(t)
         cc.send((instrument, data_type, data, is_hist))
 
         return cc.control.is_set()
+
+    def exchange(self) -> str:
+        return self._exchange_id.upper()

qubx-0.5.3/src/qubx/backtester/management.py

@@ -0,0 +1,119 @@
+import re
+import zipfile
+from collections import defaultdict
+from pathlib import Path
+
+import pandas as pd
+import yaml
+
+from qubx.core.metrics import TradingSessionResult, _pfl_metrics_prepare
+from qubx.utils.misc import blue, cyan, green, magenta, red, yellow
+
+
+class BacktestsResultsManager:
+    """
+    Manager class for handling backtesting results.
+
+    This class provides functionality to load, list and manage backtesting results stored in zip files.
+    Each result contains trading session information and metrics that can be loaded and analyzed.
+
+    Parameters
+    ----------
+    path : str
+        Path to directory containing backtesting result zip files
+
+    Methods
+    -------
+    reload()
+        Reloads all backtesting results from the specified path
+    list(regex="", with_metrics=False)
+        Lists all backtesting results, optionally filtered by regex and including metrics
+    load(name)
+        Loads a specific backtesting result by name
+    """
+
+    def __init__(self, path: str):
+        self.path = path
+        self.reload()
+
+    def reload(self) -> "BacktestsResultsManager":
+        self.results = {}
+        names = defaultdict(lambda: 0)
+        for p in Path(self.path).glob("**/*.zip"):
+            with zipfile.ZipFile(p, "r") as zip_ref:
+                try:
+                    info = yaml.safe_load(zip_ref.read("info.yml"))
+                    info["path"] = str(p)
+                    n = info.get("name", "")
+                    _new_name = n if names[n] == 0 else f"{n}.{names[n]}"
+                    names[n] += 1
+                    info["name"] = _new_name
+                    self.results[_new_name] = info
+                except Exception:
+                    pass
+
+        # - reindex
+        _idx = 1
+        for n in sorted(self.results.keys()):
+            self.results[n]["idx"] = _idx
+            _idx += 1
+
+        return self
+
+    def load(self, name: str | int | list[int] | list[str]) -> TradingSessionResult | list[TradingSessionResult]:
+        for info in self.results.values():
+            match name:
+                case int():
+                    if info.get("idx", -1) == name:
+                        return TradingSessionResult.from_file(info["path"])
+                case str():
+                    if info.get("name", "") == name:
+                        return TradingSessionResult.from_file(info["path"])
+                case list():
+                    return [self.load(i) for i in name]
+
+        raise ValueError(f"No result found for {name}")
+
+    def list(self, regex: str = "", with_metrics=False, params=False):
+        for n in sorted(self.results.keys()):
+            info = self.results[n]
+            s_cls = info.get("strategy_class", "").split(".")[-1]
+
+            if regex:
+                if not re.match(regex, n, re.IGNORECASE):
+                    if not re.match(regex, s_cls, re.IGNORECASE):
+                        continue
+
+            name = info.get("name", "")
+            smbs = ", ".join(info.get("symbols", list()))
+            start = pd.Timestamp(info.get("start", "")).round("1s")
+            stop = pd.Timestamp(info.get("stop", "")).round("1s")
+            dscr = info.get("description", "")
+            _s = f"{yellow(str(info.get('idx')))} - {red(name)} ::: {magenta(pd.Timestamp(info.get('creation_time', '')).round('1s'))} by {cyan(info.get('author', ''))}"
+            if dscr:
+                _s += f"\n\t{magenta(dscr)}"
+            _s += f"\n\tstrategy: {green(s_cls)}"
+            _s += f"\n\tinterval: {blue(start)} - {blue(stop)}"
+            _s += f"\n\tcapital: {blue(info.get('capital', ''))} {info.get('base_currency', '')} ({info.get('commissions', '')})"
+            _s += f"\n\tinstruments: {blue(smbs)}"
+            if params:
+                formats = ["{" + f":<{i}" + "}" for i in [50]]
+                _p = pd.DataFrame.from_dict(info.get("parameters", {}), orient="index")
+                for i in _p.to_string(
+                    max_colwidth=30,
+                    header=False,
+                    formatters=[(lambda x: cyan(fmt.format(str(x)))) for fmt in formats],
+                    justify="left",
+                ).split("\n"):
+                    _s += f"\n\t  |  {yellow(i)}"
+            print(_s)
+
+            if with_metrics:
+                r = TradingSessionResult.from_file(info["path"])
+                metric = _pfl_metrics_prepare(r, True, 365)
+                _m_repr = str(metric[0][["Gain", "Cagr", "Sharpe", "Max dd pct", "Qr", "Fees"]].round(3)).split("\n")[
+                    :-1
+                ]
+                for i in _m_repr:
+                    print("\t " + cyan(i))
+            print()