bbstrader 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

bbstrader/models/risk.py

@@ -1,398 +1,28 @@
-import pickle
-from abc import ABCMeta, abstractmethod
-from datetime import datetime
-from typing import Dict, Optional
 
-import numpy as np
-import pandas as pd
-import seaborn as sns
-from hmmlearn.hmm import GaussianHMM
-from matplotlib import cm
-from matplotlib import pyplot as plt
-from matplotlib.dates import MonthLocator, YearLocator
 
-from bbstrader.metatrader.rates import Rates
-
-sns.set_theme()
-
-__all__ = ["RiskModel", "HMMRiskManager", "build_hmm_models"]
-
-
-class RiskModel(metaclass=ABCMeta):
-    """
-    The RiskModel class serves as an abstract base for implementing
-    risk management strategies in financial markets. It is designed
-    to assist in the decision-making process regarding which trades
-    are permissible under current market conditions and how to allocate
-    assets effectively to optimize the risk-reward ratio.
-
-    Risk management is a critical component in trading and investment
-    strategies, aiming to minimize potential losses without significantly
-    reducing the potential for gains. This class encapsulates the core
-    principles of risk management by providing a structured approach to
-    evaluate market conditions and manage asset allocation.
-
-    Implementing classes are required to define two key methods:
-
-    - `which_trade_allowed`:
-      Determines the types of trades that are permissible based on the
-      analysis of current market conditions and the risk profile of the portfolio.
-      This method should analyze the provided `returns_val` parameter,
-      which could represent historical returns, volatility measures,
-      or other financial metrics, to decide on the suitability of executing
-      certain trades.
-
-    - `which_quantity_allowed`:
-      Defines how assets should be allocated across the portfolio to maintain
-      an optimal balance between risk and return. This involves determining
-      the quantity of each asset that can be held, considering factors such as
-      diversification, liquidity, and the asset's volatility. This method ensures
-      that the portfolio adheres to predefined risk tolerance levels and
-      investment objectives.
-
-    Note:
-        Implementing these methods requires a deep understanding of risk
-        management theories, market analysis, and portfolio management principles.
-        The implementation should be tailored to the specific needs of the
-        investment strategy and the risk tolerance of the investor or the fund
-        being managed.
-    """
-
-    @abstractmethod
-    def which_trade_allowed(self, returns_val):
-        """
-        Determines the types of trades permissible under current market conditions.
-
-        Parameters:
-            returns_val: A parameter representing financial metrics
-            such as historical returns or volatility, used to
-            assess market conditions.
-        """
-        pass
-
-    @abstractmethod
-    def which_quantity_allowed(self):
-        """
-        Defines the strategy for asset allocation within
-        the portfolio to optimize risk-reward ratio.
-        """
-        pass
-
-
-class HMMRiskManager(RiskModel):
-    """
-    This class represents a risk management model using Hidden Markov Models (HMM)
-    to identify and manage market risks. It inherits from a generic RiskModel class
-    and utilizes Gaussian HMM to model the financial market's hidden states. These states
-    are used to make decisions on permissible trading actions based on the identified market
-    trends, thus facilitating a risk-aware trading strategy.
-
-    To learn more about about the Hidden Markov model,
-    See https://en.wikipedia.org/wiki/Hidden_Markov_model
-
-    Exemple:
-        >>> # Assuming `data` is a DataFrame containing your market data
-        >>> risk_manager = HMMRiskManager(data=data, states=3, iterations=200, verbose=True)
-        >>> current_regime = risk_manager.get_current_regime(data['Returns'].values)
-        >>> print(f"Current Market Regime: {current_regime}")
-
-    """
+class HMMRiskManager():
 
     def __init__(
         self,
-        data: Optional[pd.DataFrame] = None,
-        states: int = 2,
-        iterations: int = 100,
-        end_date: Optional[datetime] = None,
-        csv_filepath: Optional[str] = None,
+        data,
+        states,
+        iterations,
+        end_date,
+        csv_filepath,
         **kwargs,
     ):
-        """
-        Initializes the HMMRiskManager with market data and model parameters.
-
-        Args:
-            `data` : DataFrame containing market data.
-                If not provided, data must be loaded via csv_filepath.
-
-            `states` (int): The number of hidden states in the HMM.
-            `iterations` (int): The number of iterations for the HMM to converge.
-            `end_date` (datetime): The end date for the market data to be considered.
-
-            `csv_filepath` (str): Path to the CSV file containing
-                market data if data is not provided directly.
-
-            kwarg (dict): Additional arguments
-                - `model_filename` (str): Filename to save the trained HMM model.
-                - `verbose` (bool): If True, prints additional model information.
-
-                - `cov_variance` (str): Type of covariance to use in the HMM.
-                    possibles values are "spherical", "tied", "diag", "full".
-                    see https://hmmlearn.readthedocs.io/en/latest/api.html#gaussianhmm for more details.
-
-        """
-        self.data = data
-        self.states = states
-        self.iterations = iterations
-        self.end_date = end_date
-        self.csv_filepath = csv_filepath
-
-        self.model_filename = kwargs.get("model_filename")
-        self.verbose = kwargs.get("verbose", True)
-        self.cov_variance = kwargs.get("cov_variance", "diag")
-
-        self.df = self._get_data()
-        self.hmm_model = self._fit_model()
-        if self.verbose:
-            self.show_hidden_states()
-        trends = self.identify_market_trends()
-        self.bullish_state = trends["bullish"]
-        self.bearish_state = trends["bearish"]
-        self.allowed_regimes = [s for s in trends.values()]
-
-    def _get_data(self):
-        """
-        Retrieves market data for the model either
-            from a provided DataFrame or a CSV file.
-        """
-        if self.data is not None:
-            return self.data
-        elif self.csv_filepath is not None:
-            return self.read_csv_file(self.csv_filepath)
-        else:
-            raise ValueError("No data source provided.")
-
-    def _fit_model(self):
-        """
-        Fits the HMM model to the market data
-            and saves the model if a filename is provided.
-        """
-        df = self.df.copy()
-        data = self.obtain_prices_df(df, end=self.end_date)
-        returns = np.column_stack([data["Returns"]])
-
-        hmm_model = GaussianHMM(
-            n_components=self.states,
-            covariance_type=self.cov_variance,
-            n_iter=self.iterations,
-        ).fit(returns)
+        import warnings
 
-        if self.verbose:
-            print(f"Hidden Markov model (HMM) Score: {hmm_model.score(returns)}")
-        if self.model_filename is not None:
-            self.save_hmm_model(hmm_model, self.model_filename)
-
-        return hmm_model
-
-    def get_states(self):
-        """
-        Predicts the hidden states for the market data
-        and calculates the mean returns and volatility for each state.
-
-        Returns:
-            DataFrame containing mean returns
-            and volatility for each hidden state.
-        """
-        df = self.df.copy()
-        data = self.obtain_prices_df(df, end=self.end_date)
-        returns = np.column_stack([data["Returns"]])
-        states = self.hmm_model.predict(returns)
-        data["State"] = states
-        # Calculating mean and volatility for each state
-        state_stats = (
-            data.groupby("State")["Returns"]
-            .agg(["mean", "std"])
-            .rename(columns={"mean": "Mean Returns", "std": "Volatility"})
-        )
-        return state_stats
-
-    def identify_market_trends(self):
-        """
-        Identifies bullish and bearish market trends
-          based on the mean returns and volatility of each state.
-
-        Returns:
-            A dictionary with keys 'bullish' and 'bearish'
-            indicating the identified states.
-        """
-        df = self.get_states()
-        # Sort the df based on Mean Returns and then by lower Volatility
-        sorted_df = df.sort_values(
-            by=["Mean Returns", "Volatility"], ascending=[False, True]
-        )
-
-        # The first row after sorting will be the bullish state
-        # (highest mean return, lower volatility preferred)
-        bullish_state = sorted_df.index[0]
-
-        # The last row will be the bearish state
-        # (as it has the lowest mean return)
-        bearish_state = sorted_df.index[-1]
-
-        return {"bullish": bullish_state, "bearish": bearish_state}
-
-    def get_current_regime(self, returns_val):
-        """
-        Determines the current market regime based on the latest returns.
-
-        Args:
-            returns_val : Array of recent return values
-            to predict the current state.
-
-        Returns:
-            The predicted current market state.
-        """
-        returns = returns_val[~(np.isnan(returns_val) | np.isinf(returns_val))]
-        features = np.array(returns).reshape(-1, 1)
-        current_regime = self.hmm_model.predict(features)[-1]
-        return current_regime
-
-    def which_trade_allowed(self, returns_val):
-        """
-        Decides whether a long or short trade
-        is allowed based on the current market regime.
-        This method override the which_trade_allowed() from
-        RiskModel class .
-
-        Args:
-            returns_val : Array of recent return values
-            to assess the permissible trade.
-
-        Returns:
-            A string indicating "LONG" or "SHORT"
-                if a trade is allowed, or None if no trade is permitted.
-        """
-        state = self.get_current_regime(returns_val)
-        if state in self.allowed_regimes:
-            trade = "LONG" if state == self.bullish_state else "SHORT"
-            return trade
-        else:
-            return None
-
-    def which_quantity_allowed(self): ...
-
-    def save_hmm_model(self, hmm_model, filename):
-        """
-        Saves the trained HMM model to a pickle file.
-
-        Args:
-            hmm_model : The trained GaussianHMM model to be saved.
-            filename : The filename under which to save the model.
-        """
-        print("Pickling HMM model...")
-        pickle.dump(hmm_model, open(f"{filename}.pkl", "wb"))
-        print("...HMM model pickled.")
-
-    def read_csv_file(self, csv_filepath):
-        """
-        Reads market data from a CSV file.
-
-        Args:
-            csv_filepath : Path to the CSV file containing the market data.
-
-        Returns:
-            DataFrame containing the parsed market data.
-        """
-        df = pd.read_csv(
-            csv_filepath,
-            header=0,
-            names=["Date", "Open", "High", "Low", "Close", "Adj Close", "Volume"],
-            index_col="Date",
-            parse_dates=True,
+        warnings.warn(
+            "The class 'HMMRiskManager' is deprecated. ",
+            DeprecationWarning,
         )
-        return df
-
-    def obtain_prices_df(self, data_frame, end=None):
-        """
-        Processes the market data to calculate returns
-        and optionally filters data up to a specified end date.
-
-        Args:
-            data_frame : DataFrame containing the market data.
-            end : Optional datetime object specifying the end date for the data.
-
-        Returns:
-            DataFrame with returns calculated
-                and data filtered up to the end date if specified.
-        """
-        df = data_frame.copy()
-        if "Returns" or "returns" not in df.columns:
-            if "Close" in df.columns:
-                df["Returns"] = df["Close"].pct_change()
-            elif "Adj Close" in df.columns:
-                df["Returns"] = df["Adj Close"].pct_change()
-            else:
-                raise ValueError("No 'Close' or 'Adj Close' columns found.")
-        elif "returns" in df.columns:
-            df.rename(columns={"returns": "Returns"}, inplace=True)
-        if end is not None:
-            df = df[: end.strftime("%Y-%m-%d")]
-        df.dropna(inplace=True)
-        return df
-
-    def show_hidden_states(self):
-        """
-        Visualizes the market data
-            and the predicted hidden states from the HMM model.
-        """
-        data = self.df.copy()
-        df = self.obtain_prices_df(data, end=self.end_date)
-        self.plot_hidden_states(self.hmm_model, df)
-
-    def plot_hidden_states(self, hmm_model, df):
-        """
-        Plots the adjusted closing prices masked
-        by the in-sample hidden states as a mechanism
-        to understand the market regimes.
-
-        Args:
-            hmm_model : The trained GaussianHMM model used for predicting states.
-            df : DataFrame containing the market data with calculated returns.
-        """
-        hidden_states = hmm_model.predict(df[["Returns"]])
-        fig, axs = plt.subplots(hmm_model.n_components, sharex=True, sharey=True)
-        colours = cm.rainbow(np.linspace(0, 1, hmm_model.n_components))
 
-        for i, (ax, colour) in enumerate(zip(axs, colours)):
-            mask = hidden_states == i
-            ax.plot_date(
-                df.index[mask], df["Adj Close"][mask], ".", linestyle="none", c=colour
-            )
-            ax.set_title(f"Hidden State #{i}")
-            ax.xaxis.set_major_locator(YearLocator())
-            ax.xaxis.set_minor_locator(MonthLocator())
-            ax.grid(True)
-        plt.show()
 
+def build_hmm_models(symbol_list=None, **kwargs):
+    import warnings
 
-def build_hmm_models(symbol_list=None, **kwargs) -> Dict[str, HMMRiskManager]:
-    mt5_data = kwargs.get("use_mt5_data", False)
-    data = kwargs.get("hmm_data")
-    tf = kwargs.get("time_frame", "D1")
-    hmm_end = kwargs.get("hmm_end", 0)
-    sd = kwargs.get("session_duration", 23.0)
-    hmm_tickers = kwargs.get("hmm_tickers")
-    if hmm_tickers is not None:
-        symbols = hmm_tickers
-    else:
-        symbols = symbol_list
-    hmm_models = {symbol: None for symbol in symbols}
-    if data is not None:
-        if isinstance(data, pd.DataFrame):
-            hmm_data = data
-            hmm = HMMRiskManager(data=hmm_data, verbose=True, iterations=1000, **kwargs)
-            for symbol in symbols:
-                hmm_models[symbol] = hmm
-        elif isinstance(data, dict):
-            for symbol, data in data.items():
-                hmm = HMMRiskManager(data=data, verbose=True, iterations=1000, **kwargs)
-                hmm_models[symbol] = hmm
-    if mt5_data:
-        for symbol in symbols:
-            rates = Rates(
-                symbol, timeframe=tf, start_pos=hmm_end, session_duration=sd, **kwargs
-            )
-            data = rates.get_rates_from_pos()
-            assert data is not None, f"No data for {symbol}"
-            hmm = HMMRiskManager(data=data, verbose=True, iterations=1000, **kwargs)
-            hmm_models[symbol] = hmm
-    return hmm_models
+    warnings.warn(
+        "The function 'build_hmm_models' is deprecated.",
+        DeprecationWarning,
+    )

bbstrader/trading/execution.py

@@ -1,14 +1,15 @@
 import multiprocessing as mp
+import sys
 import time
 from datetime import date, datetime
-from typing import Dict, List, Literal, Optional
+from typing import Callable, Dict, List, Literal, Optional
 
 import pandas as pd
 from loguru import logger as log
 
 from bbstrader.btengine.strategy import MT5Strategy, Strategy
 from bbstrader.config import BBSTRADER_DIR
-from bbstrader.metatrader.account import Account, check_mt5_connection
+from bbstrader.metatrader.account import check_mt5_connection
 from bbstrader.metatrader.trade import Trade, TradeAction, TradingMode
 from bbstrader.trading.utils import send_message
 
@@ -36,6 +37,8 @@ _TF_MAPPING = {
     "D1": 1440,
 }
 
+MT5_ENGINE_TIMEFRAMES = list(_TF_MAPPING.keys())
+
 TradingDays = ["monday", "tuesday", "wednesday", "thursday", "friday"]
 WEEK_DAYS = TradingDays + ["saturday", "sunday"]
 FRIDAY = "friday"
@@ -88,7 +91,7 @@ NON_EXEC_RETCODES = {
 log.add(
     f"{BBSTRADER_DIR}/logs/execution.log",
     enqueue=True,
-    level="INFO",
+    level="DEBUG",
     format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {name} | {message}",
 )
 
@@ -171,10 +174,11 @@ class Mt5ExecutionEngine:
         self,
         symbol_list: List[str],
         trades_instances: Dict[str, Trade],
-        strategy_cls: Strategy,
+        strategy_cls: Strategy | MT5Strategy,
         /,
         mm: bool = True,
         auto_trade: bool = True,
+        prompt_callback: Callable = None,
         optimizer: str = "equal",
         trail: bool = True,
         stop_trail: Optional[int] = None,
@@ -201,6 +205,8 @@ class Mt5ExecutionEngine:
             auto_trade :  If set to true, when signal are generated by the strategy class,
                 the Execution engine will automaticaly open position in other whise it will prompt
                 the user for confimation.
+            prompt_callback : Callback function to prompt the user for confirmation.
+                This is useful when integrating with GUI applications.
             show_positions_orders : Print open positions and orders. Defaults to False.
             iter_time : Interval to check for signals and `mm`. Defaults to 5.
             use_trade_time : Open trades after the time is completed. Defaults to True.
@@ -244,6 +250,7 @@ class Mt5ExecutionEngine:
         self.strategy_cls = strategy_cls
         self.mm = mm
         self.auto_trade = auto_trade
+        self.prompt_callback = prompt_callback
         self.optimizer = optimizer
         self.trail = trail
         self.stop_trail = stop_trail
@@ -267,6 +274,7 @@ class Mt5ExecutionEngine:
 
         self._initialize_engine(**kwargs)
         self.strategy = self._init_strategy(**kwargs)
+        self._running = True
 
     def __repr__(self):
         trades = self.trades_instances.keys()
@@ -308,16 +316,16 @@ class Mt5ExecutionEngine:
     def _print_exc(self, msg: str, e: Exception):
         if isinstance(e, KeyboardInterrupt):
             logger.info("Stopping the Execution Engine ...")
-            quit()
+            sys.exit(0)
         if self.debug_mode:
             raise ValueError(msg).with_traceback(e.__traceback__)
         else:
-            logger.error(f"{msg, repr(e)}")
+            logger.error(f"{msg}: {type(e).__name__}: {str(e)}")
 
     def _max_trades(self, mtrades):
         max_trades = {
             symbol: mtrades[symbol]
-            if mtrades is not None and symbol in mtrades
+            if mtrades is not None and isinstance(mtrades, dict) and symbol in mtrades
             else self.trades_instances[symbol].max_trade()
             for symbol in self.symbols
         }
@@ -332,10 +340,10 @@ class Mt5ExecutionEngine:
             expert_ids = [expert_ids]
         return expert_ids
 
-    def _init_strategy(self, **kwargs):
+    def _init_strategy(self, **kwargs) -> MT5Strategy:
         try:
             check_mt5_connection(**kwargs)
-            strategy: MT5Strategy = self.strategy_cls(
+            strategy = self.strategy_cls(
                 symbol_list=self.symbols, mode=TradingMode.LIVE, **kwargs
             )
         except Exception as e:
@@ -350,7 +358,7 @@ class Mt5ExecutionEngine:
         return strategy
 
     def _get_signal_info(self, signal, symbol, price, stoplimit):
-        account = Account(**self.kwargs)
+        account = self.strategy.account
         symbol_info = account.get_symbol_info(symbol)
 
         common_data = {
@@ -367,21 +375,21 @@ class Mt5ExecutionEngine:
         ).format(**common_data)
 
         sigmsg = (
-            "SIGNAL={signal},\n"
-            "SYMBOL={symbol},\n"
-            "TYPE={symbol_type},\n"
-            "DESCRIPTION={description},\n"
-            "PRICE={price},\n"
-            "STOPLIMIT={stoplimit},\n"
-            "STRATEGY={strategy},\n"
-            "TIMEFRAME={timeframe},\n"
-            "BROKER={broker},\n"
+            "SIGNAL={signal}\n"
+            "SYMBOL={symbol}\n"
+            "TYPE={symbol_type}\n"
+            "DESCRIPTION={description}\n"
+            "PRICE={price}\n"
+            "STOPLIMIT={stoplimit}\n"
+            "STRATEGY={strategy}\n"
+            "TIMEFRAME={timeframe}\n"
+            "BROKER={broker}\n"
             "TIMESTAMP={timestamp}"
         ).format(
             **common_data,
             symbol_type=account.get_symbol_type(symbol).value,
-            description=symbol_info.description,
-            price=price,
+            description=symbol_info.description if symbol_info else "N/A",
+            price=price if price else "MARKET",
             stoplimit=stoplimit,
             broker=account.broker.name,
             timestamp=datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
@@ -506,6 +514,9 @@ class Mt5ExecutionEngine:
                 or (period_type == "day" and closing)
                 or (period_type == "24/7" and closing)
             ):
+                logger.info(
+                    f"{self.ACCOUNT} Closing all positions and orders for {symbol} ..."
+                )
                 for id in self.expert_ids:
                     trade.close_positions(
                         position_type="all", id=id, comment=self.comment
@@ -520,7 +531,7 @@ class Mt5ExecutionEngine:
     def _daily_end_checks(self, today, closing, sessionmsg):
         self.strategy.perform_period_end_checks()
         if self.period_end_action == "break" and closing:
-            exit(0)
+            sys.exit(0)
         elif self.period_end_action == "sleep" and today != FRIDAY or not closing:
             self._sleep_over_night(sessionmsg)
         elif self.period_end_action == "sleep" and today == FRIDAY:
@@ -532,7 +543,7 @@ class Mt5ExecutionEngine:
         elif today == FRIDAY:
             self.strategy.perform_period_end_checks()
             if self.period_end_action == "break" and closing:
-                exit(0)
+                sys.exit(0)
             elif self.period_end_action == "sleep" or not closing:
                 self._sleep_over_weekend(sessionmsg)
 
@@ -541,7 +552,7 @@ class Mt5ExecutionEngine:
             self._sleep_over_night(sessionmsg)
         elif today == FRIDAY and self._is_month_ends() and closing:
             self.strategy.perform_period_end_checks()
-            exit(0)
+            sys.exit(0)
         else:
             self._sleep_over_weekend(sessionmsg)
 
@@ -621,17 +632,32 @@ class Mt5ExecutionEngine:
             )
             pass
 
-    def _open_buy(
-        self, signal, symbol, id, trade: Trade, price, stoplimit, sigmsg, msg, comment
-    ):
+    def _auto_trade(self, sigmsg, symbol) -> bool:
         if self.notify:
             self._send_notification(sigmsg, symbol)
+        if self.auto_trade:
+            return True
         if not self.auto_trade:
-            auto_trade = input(
-                f"{sigmsg} \n\n Please enter Y/Yes to accept this order or N/No to reject it :"
+            prompt = (
+                f"{sigmsg} \n Enter Y/Yes to accept or N/No to reject this order : "
             )
+            if self.prompt_callback is not None:
+                auto_trade = self.prompt_callback(prompt)
+            else:
+                auto_trade = input(prompt)
             if not auto_trade.upper().startswith("Y"):
-                return
+                info = f"Order Rejected !!! SYMBOL={symbol}, STRATEGY={self.STRATEGY} , ACCOUNT={self.ACCOUNT}"
+                logger.info(info)
+                if self.notify:
+                    self._send_notification(info, symbol)
+                return False
+        return True
+
+    def _open_buy(
+        self, signal, symbol, id, trade: Trade, price, stoplimit, sigmsg, msg, comment
+    ):
+        if not self._auto_trade(sigmsg, symbol):
+            return
         if not self._check_retcode(trade, "BMKT"):
             logger.info(msg)
             trade.open_buy_position(
@@ -647,14 +673,8 @@ class Mt5ExecutionEngine:
     def _open_sell(
         self, signal, symbol, id, trade: Trade, price, stoplimit, sigmsg, msg, comment
     ):
-        if self.notify:
-            self._send_notification(sigmsg, symbol)
-        if not self.auto_trade:
-            auto_trade = input(
-                f"{sigmsg} \n\n Please enter Y/Yes to accept this order or N/No to reject it :"
-            )
-            if not auto_trade.upper().startswith("Y"):
-                return
+        if not self._auto_trade(sigmsg, symbol):
+            return
         if not self._check_retcode(trade, "SMKT"):
             logger.info(msg)
             trade.open_sell_position(
@@ -905,7 +925,7 @@ class Mt5ExecutionEngine:
             pass
 
     def run(self):
-        while True:
+        while self._running:
             try:
                 check_mt5_connection(**self.kwargs)
                 positions_orders = self._check_positions_orders()
@@ -927,12 +947,21 @@ class Mt5ExecutionEngine:
                 self._sleep()
                 self._handle_period_end_actions(today)
             except KeyboardInterrupt:
-                logger.info("Stopping the Execution Engine ...")
+                logger.info(
+                    f"Stopping Execution Engine for {self.STRATEGY} STRATEGY on {self.ACCOUNT} Account"
+                )
                 break
             except Exception as e:
                 msg = f"Running Execution Engine, STRATEGY={self.STRATEGY} , ACCOUNT={self.ACCOUNT}"
                 self._print_exc(msg, e)
-                continue
+
+    def stop(self):
+        """Stops the execution engine."""
+        self._running = False
+        logger.info(
+            f"Stopping Execution Engine for {self.STRATEGY} STRATEGY on {self.ACCOUNT} Account"
+        )
+        logger.info("Execution Engine stopped successfully.")
 
 
 def RunMt5Engine(account_id: str, **kwargs):