investing-algorithm-framework 4.1.0__tar.gz → 5.0.0__tar.gz

{investing_algorithm_framework-4.1.0 → investing_algorithm_framework-5.0.0}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.1
 Name: investing-algorithm-framework
-Version: 4.1.0
+Version: 5.0.0
 Summary: A framework for creating trading bots
 Author: MDUYN
-Requires-Python: >=3.10
+Requires-Python: >=3.9
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -74,7 +75,8 @@ Features:
 The following algorithm connects to binance and buys BTC every 5 seconds. It also exposes an REST API that allows you to interact with the algorithm.
 
 ```python
-import logging
+import logging.config
+
 from investing_algorithm_framework import create_app, PortfolioConfiguration, \
     TimeUnit, CCXTOHLCVMarketDataSource, Algorithm, \
     CCXTTickerMarketDataSource, MarketCredential, DEFAULT_LOGGING_CONFIG
@@ -96,7 +98,6 @@ bitvavo_btc_eur_ticker = CCXTTickerMarketDataSource(
     symbol="BTC/EUR",
 )
 app = create_app()
-algorithm = Algorithm()
 # Bitvavo market credentials are read from .env file
 app.add_market_credential(MarketCredential(market="bitvavo"))
 app.add_portfolio_configuration(
@@ -106,10 +107,9 @@ app.add_portfolio_configuration(
         initial_balance=400
     )
 )
-app.add_algorithm(algorithm)
 
 # Run every two hours and register the data sources
-@algorithm.strategy(
+@app.strategy(
     time_unit=TimeUnit.HOUR,
     interval=2,
     market_data_sources=[bitvavo_btc_eur_ticker, bitvavo_btc_eur_ohlcv_2h]
@@ -117,7 +117,6 @@ app.add_algorithm(algorithm)
 def perform_strategy(algorithm: Algorithm, market_data: dict):
     # Access the data sources with the indentifier
     polars_df = market_data["BTC-ohlcv"]
-
     # Convert the polars dataframe to a pandas dataframe
     pandas_df = polars_df.to_pandas()
     ticker_data = market_data["BTC-ticker"]
@@ -128,18 +127,21 @@ def perform_strategy(algorithm: Algorithm, market_data: dict):
     closed_trades = algorithm.get_closed_trades()
 
     # Create a buy oder
-    algorithm.create_limit_order(
+    order = algorithm.create_limit_order(
         target_symbol="BTC/EUR",
         order_side="buy",
         amount=0.01,
         price=ticker_data["ask"],
     )
+    trade = algorithm.get_trade(order_id=order.id)
+    algorithm.add_trailing_stop_loss(trade=trade, percentage=5)
 
     # Close a trade
-    algorithm.close_trade(trades[0].id)
+    algorithm.close_trade(trade=trade)
 
     # Close a position
-    algorithm.close_position(positions[0].get_symbol())
+    position = algorithm.get_position(symbol="BTC/EUR")
+    algorithm.close_position(position)
 
 if __name__ == "__main__":
     app.run()
@@ -151,7 +153,14 @@ if __name__ == "__main__":
 
 The framework also supports backtesting and performing backtest experiments. After a backtest, you can print a report that shows the performance of your trading bot.
 
-To run a single backtest you can use the example code that can be found [here](./examples/backtest).
+To run a single backtest you can use the example code that can be found [here](./examples/backtest_example). Simply run:
+
+> Its assumed here that you have cloned the repository, installed the framework and
+> are in the root of the project.
+
+```bash
+python examples/backtest_example/run_backtest.py
+```
 
 ### Backtesting report
 

{investing_algorithm_framework-4.1.0 → investing_algorithm_framework-5.0.0}/README.md

@@ -37,7 +37,8 @@ Features:
 The following algorithm connects to binance and buys BTC every 5 seconds. It also exposes an REST API that allows you to interact with the algorithm.
 
 ```python
-import logging
+import logging.config
+
 from investing_algorithm_framework import create_app, PortfolioConfiguration, \
     TimeUnit, CCXTOHLCVMarketDataSource, Algorithm, \
     CCXTTickerMarketDataSource, MarketCredential, DEFAULT_LOGGING_CONFIG
@@ -59,7 +60,6 @@ bitvavo_btc_eur_ticker = CCXTTickerMarketDataSource(
     symbol="BTC/EUR",
 )
 app = create_app()
-algorithm = Algorithm()
 # Bitvavo market credentials are read from .env file
 app.add_market_credential(MarketCredential(market="bitvavo"))
 app.add_portfolio_configuration(
@@ -69,10 +69,9 @@ app.add_portfolio_configuration(
         initial_balance=400
     )
 )
-app.add_algorithm(algorithm)
 
 # Run every two hours and register the data sources
-@algorithm.strategy(
+@app.strategy(
     time_unit=TimeUnit.HOUR,
     interval=2,
     market_data_sources=[bitvavo_btc_eur_ticker, bitvavo_btc_eur_ohlcv_2h]
@@ -80,7 +79,6 @@ app.add_algorithm(algorithm)
 def perform_strategy(algorithm: Algorithm, market_data: dict):
     # Access the data sources with the indentifier
     polars_df = market_data["BTC-ohlcv"]
-
     # Convert the polars dataframe to a pandas dataframe
     pandas_df = polars_df.to_pandas()
     ticker_data = market_data["BTC-ticker"]
@@ -91,18 +89,21 @@ def perform_strategy(algorithm: Algorithm, market_data: dict):
     closed_trades = algorithm.get_closed_trades()
 
     # Create a buy oder
-    algorithm.create_limit_order(
+    order = algorithm.create_limit_order(
         target_symbol="BTC/EUR",
         order_side="buy",
         amount=0.01,
         price=ticker_data["ask"],
     )
+    trade = algorithm.get_trade(order_id=order.id)
+    algorithm.add_trailing_stop_loss(trade=trade, percentage=5)
 
     # Close a trade
-    algorithm.close_trade(trades[0].id)
+    algorithm.close_trade(trade=trade)
 
     # Close a position
-    algorithm.close_position(positions[0].get_symbol())
+    position = algorithm.get_position(symbol="BTC/EUR")
+    algorithm.close_position(position)
 
 if __name__ == "__main__":
     app.run()
@@ -114,7 +115,14 @@ if __name__ == "__main__":
 
 The framework also supports backtesting and performing backtest experiments. After a backtest, you can print a report that shows the performance of your trading bot.
 
-To run a single backtest you can use the example code that can be found [here](./examples/backtest).
+To run a single backtest you can use the example code that can be found [here](./examples/backtest_example). Simply run:
+
+> Its assumed here that you have cloned the repository, installed the framework and
+> are in the root of the project.
+
+```bash
+python examples/backtest_example/run_backtest.py
+```
 
 ### Backtesting report
 

{investing_algorithm_framework-4.1.0 → investing_algorithm_framework-5.0.0}/investing_algorithm_framework/__init__.py

@@ -12,7 +12,7 @@ from investing_algorithm_framework.domain import ApiException, \
     RESERVED_BALANCES, APP_MODE, AppMode, DATETIME_FORMAT, \
     load_backtest_report, BacktestDateRange, convert_polars_to_pandas, \
     DateRange, get_backtest_report, DEFAULT_LOGGING_CONFIG, \
-    BacktestReport
+    BacktestReport, TradeStatus, MarketDataType
 from investing_algorithm_framework.infrastructure import \
     CCXTOrderBookMarketDataSource, CCXTOHLCVMarketDataSource, \
     CCXTTickerMarketDataSource, CSVOHLCVMarketDataSource, \
@@ -90,5 +90,7 @@ __all__ = [
     "get_backtest_report",
     "AzureBlobStorageStateHandler",
     "DEFAULT_LOGGING_CONFIG",
-    "BacktestReport"
+    "BacktestReport",
+    "TradeStatus",
+    "MarketDataType"
 ]

{investing_algorithm_framework-4.1.0 → investing_algorithm_framework-5.0.0}/investing_algorithm_framework/app/algorithm.py

@@ -4,7 +4,7 @@ from typing import List, Dict
 import re
 
 from investing_algorithm_framework.domain import OrderStatus, \
-    Position, Order, Portfolio, OrderType, OrderSide, \
+    Position, Order, Portfolio, OrderType, OrderSide, TradeStatus, \
     BACKTESTING_FLAG, BACKTESTING_INDEX_DATETIME, MarketService, TimeUnit, \
     OperationalException, random_string, RoundingService, Trade
 from investing_algorithm_framework.services import MarketCredentialService, \
@@ -61,7 +61,7 @@ class Algorithm:
         self.market_service: MarketService
         self.configuration_service: ConfigurationService
         self.portfolio_configuration_service: PortfolioConfigurationService
-        self.strategy_orchestrator_service: StrategyOrchestratorService
+        self.strategy_orchestrator_service: StrategyOrchestratorService = None
         self._data_sources = {}
         self._strategies = []
         self._market_credential_service: MarketCredentialService
@@ -94,12 +94,21 @@ class Algorithm:
             )
 
         pattern = re.compile(r"^[a-zA-Z0-9]*$")
+
         if not pattern.match(name):
             raise OperationalException(
                 "The name of the algorithm can only contain" +
                 " letters and numbers"
             )
 
+        illegal_chars = r"[\/:*?\"<>|]"
+
+        if re.search(illegal_chars, name):
+            raise OperationalException(
+                f"Illegal characters detected in algorithm: {name}. "
+                f"Illegal characters: / \\ : * ? \" < > |"
+            )
+
     def initialize_services(
         self,
         configuration_service,
@@ -155,10 +164,28 @@ class Algorithm:
             number_of_iterations=number_of_iterations
         )
 
+    def stop(self) -> None:
+        """
+        Function to stop the algorithm. This function will stop the
+        algorithm by stopping all jobs in the strategy orchestrator
+        service.
+
+        Returns:
+            None
+        """
+
+        if self.strategy_orchestrator_service is not None:
+            self.strategy_orchestrator_service.stop()
+
     @property
     def name(self):
         return self._name
 
+    @name.setter
+    def name(self, name):
+        self._validate_name(name)
+        self._name = name
+
     @property
     def data_sources(self):
         return self._data_sources
@@ -172,6 +199,14 @@ class Algorithm:
         """
         return self.configuration_service.get_config()
 
+    def get_config(self):
+        """
+        Function to get a config instance. This allows users when
+        having access to the algorithm instance also to read the
+        configs of the app.
+        """
+        return self.configuration_service.get_config()
+
     @property
     def description(self):
         """
@@ -315,7 +350,7 @@ class Algorithm:
         order and execute it if the execute parameter is set to True. If the
         validate parameter is set to True, the order will be validated
 
-        Parameters:
+        Args:
             target_symbol: The symbol of the asset to trade
             price: The price of the asset
             order_side: The side of the order
@@ -476,7 +511,7 @@ class Algorithm:
         """
 
         if market is None:
-            return self.portfolio_service.find({})
+            return self.portfolio_service.get_all()[0]
 
         return self.portfolio_service.find({{"market": market}})
 
@@ -497,7 +532,7 @@ class Algorithm:
         If the market parameter is specified, the unallocated balance
         of the specified market will be returned.
 
-        Parameters:
+        Args:
             market: The market of the portfolio
 
         Returns:
@@ -507,7 +542,7 @@ class Algorithm:
         if market:
             portfolio = self.portfolio_service.find({{"market": market}})
         else:
-            portfolio = self.portfolio_service.find({})
+            portfolio = self.portfolio_service.get_all()[0]
 
         trading_symbol = portfolio.trading_symbol
         return self.position_service.find(
@@ -539,6 +574,19 @@ class Algorithm:
         order_side=None,
         order_type=None
     ) -> Order:
+        """
+        Function to retrieve an order.
+
+        Exception is thrown when no param has been provided.
+
+        Args:
+            reference_id [optional] (int): id given by the external
+                market or exchange.
+            market [optional] (str): the market that the order was
+                executed on.
+            target_symbol [optional] (str): the symbol of the asset
+                that the order was executed
+        """
         query_params = {}
 
         if reference_id:
@@ -563,6 +611,11 @@ class Algorithm:
             )
             query_params["position"] = [position.id for position in positions]
 
+        if not query_params:
+            raise OperationalException(
+                "No parameters provided to get order."
+            )
+
         return self.order_service.find(query_params)
 
     def get_orders(
@@ -1169,25 +1222,95 @@ class Algorithm:
         query_params["status"] = OrderStatus.OPEN.value
         return self.order_service.exists(query_params)
 
-    def check_pending_orders(self):
+    def get_trade(
+        self,
+        target_symbol=None,
+        trading_symbol=None,
+        market=None,
+        portfolio=None,
+        status=None,
+        order_id=None
+    ) -> List[Trade]:
         """
-        Function to check pending orders
+        Function to get all trades. This function will return all trades
+        that match the specified query parameters. If the market parameter
+        is specified, the trades with the specified market will be returned.
+
+        Args:
+            market: The market of the asset
+            portfolio: The portfolio of the asset
+            status: The status of the trade
+            order_id: The order id of the trade
+            target_symbol: The symbol of the asset
+            trading_symbol: The trading symbol of the asset
+
+        Returns:
+            List[Trade]: A list of trades that match the query parameters
         """
-        self.order_service.check_pending_orders()
+        query_params = {}
+
+        if market is not None:
+            query_params["market"] = market
+
+        if portfolio is not None:
+            query_params["portfolio"] = portfolio
+
+        if status is not None:
+            query_params["status"] = status
+
+        if order_id is not None:
+            query_params["order_id"] = order_id
+
+        if target_symbol is not None:
+            query_params["target_symbol"] = target_symbol
+
+        if trading_symbol is not None:
+            query_params["trading_symbol"] = trading_symbol
+
+        return self.trade_service.find(query_params)
 
-    def get_trades(self, market=None) -> List[Trade]:
+    def get_trades(
+        self,
+        target_symbol=None,
+        trading_symbol=None,
+        market=None,
+        portfolio=None,
+        status=None,
+    ) -> List[Trade]:
         """
         Function to get all trades. This function will return all trades
         that match the specified query parameters. If the market parameter
         is specified, the trades with the specified market will be returned.
 
-        Parameters:
+        Args:
             market: The market of the asset
+            portfolio: The portfolio of the asset
+            status: The status of the trade
+            target_symbol: The symbol of the asset
+            trading_symbol: The trading symbol of the asset
 
         Returns:
             List[Trade]: A list of trades that match the query parameters
         """
-        return self.trade_service.get_trades(market)
+
+        query_params = {}
+
+        if market is not None:
+            query_params["market"] = market
+
+        if portfolio is not None:
+            query_params["portfolio"] = portfolio
+
+        if status is not None:
+            query_params["status"] = status
+
+        if target_symbol is not None:
+            query_params["target_symbol"] = target_symbol
+
+        if trading_symbol is not None:
+            query_params["trading_symbol"] = trading_symbol
+
+        return self.trade_service.get_all({"market": market})
 
     def get_closed_trades(self) -> List[Trade]:
         """
@@ -1197,7 +1320,44 @@ class Algorithm:
         Returns:
             List[Trade]: A list of closed trades
         """
-        return self.trade_service.get_closed_trades()
+        return self.trade_service.get_all({"status": TradeStatus.CLOSED.value})
+
+    def count_trades(
+        self,
+        target_symbol=None,
+        trading_symbol=None,
+        market=None,
+        portfolio=None
+    ) -> int:
+        """
+        Function to count trades. This function will return the number of
+        trades that match the specified query parameters.
+
+        Args:
+            target_symbol: The symbol of the asset
+            trading_symbol: The trading symbol of the asset
+            market: The market of the asset
+            portfolio: The portfolio of the asset
+
+        Returns:
+            int: The number of trades that match the query parameters
+        """
+
+        query_params = {}
+
+        if market is not None:
+            query_params["market"] = market
+
+        if portfolio is not None:
+            query_params["portfolio"] = portfolio
+
+        if target_symbol is not None:
+            query_params["target_symbol"] = target_symbol
+
+        if trading_symbol is not None:
+            query_params["trading_symbol"] = trading_symbol
+
+        return self.trade_service.count(query_params)
 
     def get_open_trades(self, target_symbol=None, market=None) -> List[Trade]:
         """
@@ -1208,32 +1368,107 @@ class Algorithm:
         is specified, the open trades with the specified market will be
         returned.
 
-        Parameters:
+        Args:
             target_symbol: The symbol of the asset
             market: The market of the asset
 
         Returns:
             List[Trade]: A list of open trades that match the query parameters
         """
-        return self.trade_service.get_open_trades(target_symbol, market)
+        return self.trade_service.get_all(
+            {
+                "status": TradeStatus.OPEN.value,
+                "target_symbol": target_symbol,
+                "market": market
+            }
+        )
 
-    def close_trade(self, trade, market=None, precision=None) -> None:
+    def add_stop_loss(self, trade, percentage: int) -> None:
+        """
+        Function to add a stop loss to a trade. This function will add a
+        stop loss to the specified trade. If the stop loss is triggered,
+        the trade will be closed.
+
+        Args:
+            trade: Trade - The trade to add the stop loss to
+            percentage: int - The stop loss of the trade
+
+        Returns:
+            None
+        """
+        self.trade_service.add_stop_loss(trade, percentage=percentage)
+
+    def add_trailing_stop_loss(self, trade, percentage: int) -> None:
+        """
+        Function to add a trailing stop loss to a trade. This function will
+        add a trailing stop loss to the specified trade. If the trailing
+        stop loss is triggered, the trade will be closed.
+
+        Args:
+            trade: Trade - The trade to add the trailing stop loss to
+            trailing_stop_loss: float - The trailing stop loss of the trade
+
+        Returns:
+            None
+        """
+        self.trade_service.add_trailing_stop_loss(trade, percentage=percentage)
+
+    def close_trade(self, trade, precision=None) -> None:
         """
         Function to close a trade. This function will close a trade by
         creating a market order to sell the position. If the precision
         parameter is specified, the amount of the order will be rounded
         down to the specified precision.
 
-        Parameters:
+        Args:
             trade: Trade - The trade to close
-            market: str - The market of the trade
-            precision: float - The precision of the amount
+            precision: int - The precision of the amount
 
         Returns:
             None
         """
-        self.trade_service.close_trade(
-            trade=trade, market=market, precision=precision
+
+        trade = self.trade_service.get(trade.id)
+
+        if TradeStatus.CLOSED.equals(trade.status):
+            raise OperationalException("Trade already closed.")
+
+        if trade.remaining <= 0:
+            raise OperationalException("Trade has no amount to close.")
+
+        position_id = trade.orders[0].position_id
+        portfolio = self.portfolio_service.find({"position": position_id})
+        position = self.position_service.find(
+            {"portfolio": portfolio.id, "symbol": trade.target_symbol}
+        )
+        amount = trade.remaining
+
+        if precision is not None:
+            amount = RoundingService.round_down(amount, precision)
+
+        if position.get_amount() < amount:
+            logger.warning(
+                f"Order amount {amount} is larger then amount "
+                f"of available {position.symbol} "
+                f"position: {position.get_amount()}, "
+                f"changing order amount to size of position"
+            )
+            amount = position.get_amount()
+
+        ticker = self._market_data_source_service.get_ticker(
+            symbol=trade.symbol, market=portfolio.market
+        )
+
+        self.order_service.create(
+            {
+                "portfolio_id": portfolio.id,
+                "trading_symbol": trade.trading_symbol,
+                "target_symbol": trade.target_symbol,
+                "amount": amount,
+                "order_side": OrderSide.SELL.value,
+                "order_type": OrderType.LIMIT.value,
+                "price": ticker["bid"],
+            }
         )
 
     def get_number_of_positions(self):
@@ -1386,3 +1621,9 @@ class Algorithm:
             [order.get_amount() * order.get_price()
              for order in pending_orders]
         )
+
+    def get_trade_service(self):
+        return self.trade_service
+
+    def get_market_data_source_service(self):
+        return self._market_data_source_service