investing-algorithm-framework 3.7.0__py3-none-any.whl → 7.19.15__py3-none-any.whl

investing_algorithm_framework/domain/models/order/order_type.py

@@ -3,8 +3,6 @@ from enum import Enum
 
 class OrderType(Enum):
     LIMIT = 'LIMIT'
-    MARKET = 'MARKET'
-    STOP_LOSS_LIMIT = "STOP_LOSS_LIMIT"
 
     @staticmethod
     def from_string(value: str):
@@ -15,7 +13,7 @@ class OrderType(Enum):
                 if value.upper() == order_type.value:
                     return order_type
 
-        raise ValueError("Could not convert value to OrderType")
+        raise ValueError(f"Could not convert value: {value} to OrderType")
 
     @staticmethod
     def from_value(value):

investing_algorithm_framework/domain/models/portfolio/portfolio.py

@@ -2,6 +2,37 @@ from investing_algorithm_framework.domain.models.base_model import BaseModel
 
 
 class Portfolio(BaseModel):
+    """
+    Portfolio base class.
+
+    A portfolio is a collection of positions that are managed by an algorithm.
+
+    Attributes:
+    * identifier: str, unique identifier of the portfolio
+    * trading_symbol: str, trading symbol of the portfolio
+    * unallocated: float, the size of the trading symbol that is not
+      allocated. For example, if the trading symbol is USDT and the unallocated
+      is 1000, it means that the portfolio has 1000 USDT that is not
+        allocated to any position.
+    * net_size: float, net size of the portfolio is the initial balance of the
+        portfolio plus the all the net gains of the trades. The
+    * realized: float, the realized gain of the portfolio is the sum of all the
+        realized gains of the trades.
+    * total_revenue: float, the total revenue of the portfolio is the sum
+        of all the orders (price * size)
+    * total_cost: float, the total cost of the portfolio is the sum of all the
+        costs of the trades (price * size (for buy orders)
+        or -price * size (for sell orders))
+    * total_net_gain: float, the total net gain of the portfolio is the sum of
+        all the net gains of the trades
+    * total_trade_volume: float, the total trade volume of the
+        portfolio is the sum of all the sizes of the trades
+    * market: str, the market of the portfolio (e.g. BITVAVO, BINANCE)
+    * created_at: datetime, the datetime when the portfolio was created
+    * updated_at: datetime, the datetime when the portfolio was last updated
+    * initialized: bool, whether the portfolio is initialized or not
+    * initial_balance: float, the initial balance of the portfolio
+    """
 
     def __init__(
         self,
@@ -9,6 +40,7 @@ class Portfolio(BaseModel):
         trading_symbol,
         net_size,
         unallocated,
+        initial_balance,
         market,
         realized=0,
         total_revenue=0,
@@ -16,21 +48,25 @@ class Portfolio(BaseModel):
         total_net_gain=0,
         total_trade_volume=0,
         created_at=None,
-        updated_at=None
+        updated_at=None,
+        initialized=False,
     ):
         self.identifier = identifier
         self.updated_at = None
         self.trading_symbol = trading_symbol.upper()
         self.net_size = net_size
         self.unallocated = unallocated
+        self.initial_balance = initial_balance
         self.realized = realized
         self.total_revenue = total_revenue
         self.total_cost = total_cost
         self.total_net_gain = total_net_gain
         self.total_trade_volume = total_trade_volume
-        self.market = market
+        self.market = market.upper()
         self.created_at = created_at
         self.updated_at = updated_at
+        self.initialized = initialized
+        self._allocated = None
 
     def __repr__(self):
         return self.repr(
@@ -42,6 +78,7 @@ class Portfolio(BaseModel):
             total_revenue=self.total_revenue,
             total_cost=self.total_cost,
             market=self.market,
+            initial_balance=self.initial_balance
         )
 
     def get_identifier(self):
@@ -80,12 +117,53 @@ class Portfolio(BaseModel):
     def get_market(self):
         return self.market
 
+    def get_initial_balance(self):
+        return self.initial_balance
+
+    @property
+    def allocated(self):
+
+        if self._allocated is None:
+            return 0.0
+
+        return self._allocated
+
+    @allocated.setter
+    def allocated(self, value):
+        self._allocated = value
+
     @staticmethod
     def from_portfolio_configuration(portfolio_configuration):
+        """
+        Function to create a portfolio from a portfolio configuration
+
+        We assume that a portfolio that is created from a configuration
+        is always un initialized.
+
+        Args:
+            portfolio_configuration: PortfolioConfiguration
+
+        Returns:
+            Portfolio
+        """
         return Portfolio(
             identifier=portfolio_configuration.identifier,
             trading_symbol=portfolio_configuration.trading_symbol,
             unallocated=portfolio_configuration.initial_balance,
             net_size=portfolio_configuration.initial_balance,
-            market=portfolio_configuration.market
+            market=portfolio_configuration.market,
+            initial_balance=portfolio_configuration.initial_balance,
+            initialized=False
         )
+
+    def to_dict(self):
+        return {
+            "trading_symbol": self.trading_symbol,
+            "market": self.market,
+            "unallocated": self.unallocated,
+            "identifier": self.identifier,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "initialized": self.initialized,
+            "initial_balance": self.initial_balance,
+        }

investing_algorithm_framework/domain/models/portfolio/portfolio_configuration.py

@@ -6,6 +6,23 @@ from investing_algorithm_framework.domain.models.base_model import BaseModel
 
 
 class PortfolioConfiguration(BaseModel):
+    """
+    This class represents a portfolio configuration. It is used to
+    configure the portfolio that the user wants to create.
+
+    Attributes:
+    - market: The market where the portfolio will be created
+    - trading_symbol: The trading symbol of the portfolio
+    - track_from: The date from which the portfolio will be tracked
+    - identifier: The identifier of the portfolio
+    - initial_balance: The initial balance of the portfolio
+
+    For backtesting, a portfolio configuration is used to create a
+    portfolio that will be used to simulate the trading of the algorithm. if
+    the user does not provide an initial balance, the portfolio will be created
+    with a balance of according to the initial balanace of
+        the PortfolioConfiguration class.
+    """
 
     def __init__(
         self,
@@ -16,13 +33,19 @@ class PortfolioConfiguration(BaseModel):
         initial_balance=None,
     ):
         self._market = market
+
+        if self._market is not None:
+            self._market = self._market.upper()
+
         self._track_from = None
         self._trading_symbol = trading_symbol.upper()
         self._identifier = identifier
         self._initial_balance = initial_balance
 
         if self.identifier is None:
-            self._identifier = market.lower()
+            self._identifier = market.upper()
+        else:
+            self._identifier = identifier.upper()
 
         if track_from:
             self._track_from = parse(track_from)
@@ -35,8 +58,8 @@ class PortfolioConfiguration(BaseModel):
     @property
     def market(self):
 
-        if hasattr(self._market, "lower"):
-            return self._market.lower()
+        if hasattr(self._market, "upper"):
+            return self._market.upper()
 
         return self._market
 

investing_algorithm_framework/domain/models/portfolio/portfolio_snapshot.py

@@ -1,3 +1,7 @@
+from datetime import timezone
+
+from dateutil import parser
+
 from investing_algorithm_framework.domain.models.base_model import BaseModel
 
 
@@ -5,16 +9,19 @@ class PortfolioSnapshot(BaseModel):
 
     def __init__(
         self,
-        portfolio_id,
-        trading_symbol,
-        pending_value,
-        unallocated,
-        total_net_gain,
-        total_revenue,
-        total_cost,
-        cash_flow,
-        created_at,
-        position_snapshots=None
+        portfolio_id=None,
+        trading_symbol=None,
+        pending_value=None,
+        unallocated=None,
+        net_size=None,
+        total_net_gain=None,
+        total_revenue=None,
+        total_cost=None,
+        total_value=None,
+        cash_flow=None,
+        created_at=None,
+        position_snapshots=None,
+        metadata=None,
     ):
         self.portfolio_id = portfolio_id
         self.trading_symbol = trading_symbol
@@ -22,9 +29,19 @@ class PortfolioSnapshot(BaseModel):
         self.unallocated = unallocated
         self.total_net_gain = total_net_gain
         self.total_revenue = total_revenue
+        self.total_value = total_value if total_value is not None else 0.0
+        self.net_size = net_size
         self.total_cost = total_cost
         self.cash_flow = cash_flow
-        self.created_at = created_at
+        self.metadata = metadata if metadata is not None else {}
+
+        if created_at is not None and isinstance(created_at, str):
+            self.created_at = parser.parse(created_at)
+        else:
+            self.created_at = created_at
+
+        # Make sure that created_at is a timezone aware datetime object
+        self.created_at = self.created_at.replace(tzinfo=timezone.utc)
 
         if position_snapshots is None:
             position_snapshots = []
@@ -67,6 +84,12 @@ class PortfolioSnapshot(BaseModel):
     def set_total_revenue(self, total_revenue):
         self.total_revenue = total_revenue
 
+    def get_total_value(self):
+        return self.total_value
+
+    def set_total_value(self, total_value):
+        self.total_value = total_value
+
     def get_total_cost(self):
         return self.total_cost
 
@@ -102,10 +125,84 @@ class PortfolioSnapshot(BaseModel):
             portfolio_id=self.portfolio_id,
             created_at=self.created_at.strftime("%Y-%m-%d %H:%M:%S"),
             trading_symbol=self.trading_symbol,
+            net_size=self.net_size,
             unallocated=self.unallocated,
             pending_value=self.pending_value,
             total_net_gain=self.total_net_gain,
             total_revenue=self.total_revenue,
             total_cost=self.total_cost,
             cash_flow=self.cash_flow,
+            metadata=self.metadata,
+        )
+
+    def to_dict(self, datetime_format=None):
+        """
+        Convert the portfolio snapshot object to a dictionary
+
+        Args:
+            datetime_format (str): The format to use for the datetime fields.
+                If None, the datetime fields will be returned as is.
+                Defaults to None.
+
+        Returns:
+            dict: A dictionary representation of the portfolio snapshot object.
+        """
+        def ensure_iso(value):
+            if hasattr(value, "isoformat"):
+                if value.tzinfo is None:
+                    value = value.replace(tzinfo=timezone.utc)
+                return value.isoformat()
+            return value
+
+        created_at = ensure_iso(self.created_at) if self.created_at else None
+
+        return {
+            "metadata": self.metadata if self.metadata else {},
+            "portfolio_id": self.portfolio_id if self.portfolio_id else "",
+            "trading_symbol": self.trading_symbol
+            if self.trading_symbol else "",
+            "pending_value": self.pending_value if self.pending_value else 0.0,
+            "unallocated": self.unallocated if self.unallocated else 0.0,
+            "total_net_gain": self.total_net_gain
+            if self.total_net_gain else 0.0,
+            "total_revenue": self.total_revenue if self.total_revenue else 0.0,
+            "total_cost": self.total_cost if self.total_cost else 0.0,
+            "cash_flow": self.cash_flow if self.cash_flow else 0.0,
+            "net_size": self.net_size if self.net_size else 0.0,
+            "created_at": created_at if created_at else "",
+            "total_value": self.total_value if self.total_value else 0.0,
+        }
+
+    @staticmethod
+    def from_dict(data):
+        """
+        Create a PortfolioSnapshot object from a dictionary.
+
+        Args:
+            data (dict): A dictionary containing the portfolio snapshot data.
+
+        Returns:
+            PortfolioSnapshot: An instance of PortfolioSnapshot.
+        """
+        created_at_str = data.get("created_at")
+        created_at = parser.parse(created_at_str)
+
+        # Ensure created_at is timezone aware
+        created_at = created_at.replace(tzinfo=timezone.utc)
+
+        return PortfolioSnapshot(
+            net_size=data.get("net_size", 0.0),
+            created_at=created_at,
+            total_value=data.get("total_value", 0.0),
+            trading_symbol=data.get(
+                "trading_symbol", None
+            ),
+            portfolio_id=data.get("portfolio_id", None),
+            pending_value=data.get("pending_value", 0.0),
+            unallocated=data.get("unallocated", 0.0),
+            total_net_gain=data.get("total_net_gain", 0.0),
+            total_revenue=data.get("total_revenue", 0.0),
+            total_cost=data.get("total_cost", 0.0),
+            cash_flow=data.get("cash_flow", 0.0),
+            metadata=data.get("metadata", {})
         )

investing_algorithm_framework/domain/models/position/__init__.py

@@ -1,4 +1,5 @@
 from .position import Position
 from .position_snapshot import PositionSnapshot
+from .position_size import PositionSize
 
-__all__ = ["Position", "PositionSnapshot"]
+__all__ = ["Position", "PositionSnapshot", "PositionSize"]

investing_algorithm_framework/domain/models/position/position.py

@@ -2,6 +2,9 @@ from investing_algorithm_framework.domain.models.base_model import BaseModel
 
 
 class Position(BaseModel):
+    """
+    This class represents a position in a portfolio.
+    """
 
     def __init__(
         self,
@@ -47,6 +50,15 @@ class Position(BaseModel):
             "portfolio_id": self.portfolio_id,
         }
 
+    @staticmethod
+    def from_dict(data: dict):
+        return Position(
+            symbol=data.get("symbol"),
+            amount=data.get("amount", 0),
+            cost=data.get("cost", 0),
+            portfolio_id=data.get("portfolio_id"),
+        )
+
     def __repr__(self):
         return self.repr(
             symbol=self.symbol,

investing_algorithm_framework/domain/models/position/position_size.py

@@ -0,0 +1,41 @@
+from typing import Optional
+from investing_algorithm_framework.domain.exceptions import \
+    OperationalException
+
+
+class PositionSize:
+    """
+    Defines how much capital to allocate to a specific symbol.
+    """
+
+    def __init__(
+        self,
+        symbol: str,
+        percentage_of_portfolio: Optional[float] = None,
+        fixed_amount: Optional[float] = None
+    ):
+        self.symbol = symbol
+        self.percentage_of_portfolio = percentage_of_portfolio
+        self.fixed_amount = fixed_amount
+
+    def get_size(self, portfolio, asset_price) -> float:
+        """
+        Calculate size in currency/units.
+        """
+        if self.fixed_amount is not None:
+            return self.fixed_amount
+        elif self.percentage_of_portfolio is not None:
+            total_value = portfolio.get_unallocated() + portfolio.allocated
+            return total_value * (self.percentage_of_portfolio / 100)
+        else:
+            raise OperationalException(
+                "A position size object must have either a fixed amount or a "
+                "percentage of the portfolio defined."
+            )
+
+    def __repr__(self) -> str:
+        return (
+            f"PositionSize(symbol={self.symbol}, "
+            f"percentage_of_portfolio={self.percentage_of_portfolio}, "
+            f"fixed_amount={self.fixed_amount})"
+        )

investing_algorithm_framework/domain/models/risk_rules/__init__.py

@@ -0,0 +1,7 @@
+from .stop_loss_rule import StopLossRule
+from .take_profit_rule import TakeProfitRule
+
+__all__ = [
+    "StopLossRule",
+    "TakeProfitRule",
+]

investing_algorithm_framework/domain/models/risk_rules/stop_loss_rule.py

@@ -0,0 +1,51 @@
+class StopLossRule:
+    """
+    A rule that defines when to trigger a stop loss based
+    on a specified threshold such as a percentage drop in price or
+    a fixed amount.
+
+    if trade_risk_type is fixed, the stop loss price is calculated as follows:
+        You buy an asset at $100.
+        You set a 5% stop loss, meaning you will sell if
+            the price drops to $95.
+        If the price rises to $120, the stop loss is not triggered.
+        But if the price keeps falling to $95, the stop loss triggers,
+            and you exit with a $5 loss.
+
+    if trade_risk_type is trailing, the stop loss price is
+    calculated as follows:
+        You buy an asset at $100.
+        You set a 5% trailing stop loss, meaning you will sell if
+            the price drops 5% from its peak at $96
+        If the price rises to $120, the stop loss adjusts
+            to $114 (5% below $120).
+        If the price falls to $114, the position is
+            closed, securing a $14 profit.
+        But if the price keeps rising to $150, the stop
+            loss moves up to $142.50.
+        If the price drops from $150 to $142.50, the stop
+            loss triggers, and you exit with a $42.50 profit.
+
+    Attributes:
+        - percentage_threshold (float): The percentage drop in price
+            that triggers the stop loss.
+        - trailing (bool): Indicates whether the stop loss is trailing
+            or fixed.
+        - sell_percentage (float): The percentage of the position to sell
+            when the stop loss is triggered.
+        - symbol (str): The symbol of the asset the stop loss rule
+            applies to. Symbol is defined as the target symbol
+            (the asset being traded) combined with the trading symbol
+            (the asset used to trade the target symbol), e.g., 'BTC-EUR'.
+    """
+    def __init__(
+        self,
+        percentage_threshold: float,
+        sell_percentage: float,
+        symbol: str,
+        trailing: bool = False,
+    ):
+        self.percentage_threshold = percentage_threshold
+        self.trailing = trailing
+        self.sell_percentage = sell_percentage
+        self.symbol = symbol

investing_algorithm_framework/domain/models/risk_rules/take_profit_rule.py

@@ -0,0 +1,55 @@
+class TakeProfitRule:
+    """
+    A rule that defines when to trigger a take profit based
+    on a specified threshold such as a percentage gain in price or
+    a fixed amount.
+
+    if trailing is set to true, the take profit price is
+    calculated as follows:
+        You buy an asset at $100.
+        You set a 5% take profit, meaning you will sell if the price
+            rises to $105.
+        If the price rises to $120, the take profit triggers,
+            and you exit with a $20 profit.
+        But if the price keeps falling below $105, the take profit is not
+            triggered.
+
+    if trailing is set to true, the take profit price is
+    calculated as follows:
+        You buy an asset at $100.
+        You set a 5% trailing take profit, the moment the price rises
+            5% the initial take profit mark will be set. This means you
+            will set the take_profit_price initially at none and
+            only if the price hits $105, you will set the
+            take_profit_price to $105.
+        if the price drops below $105, the take profit is triggered.
+        If the price rises to $120, the take profit adjusts to
+        $114 (5% below $120).
+        If the price falls to $114, the position is closed,
+        securing a $14 profit.
+        But if the price keeps rising to $150, the take profit
+        moves up to $142.50.
+
+
+    Attributes:
+        - percentage_threshold (float): The percentage gain in price
+            that triggers the stop loss.
+        - trailing (bool): Indicates whether the take profit is trailing
+            or fixed.
+        - sell_percentage (float): The percentage of the position to sell
+            when the take profit is triggered.
+        - symbol (str): The symbol of the asset the take profit rule
+            applies to. Symbol is defined as only the target symbol.
+            So for example, 'BTC' in 'BTC-EUR' or 'META' in 'META-USD'.
+    """
+    def __init__(
+        self,
+        percentage_threshold: float,
+        sell_percentage: float,
+        symbol: str,
+        trailing: bool = False,
+    ):
+        self.percentage_threshold = percentage_threshold
+        self.trailing = trailing
+        self.sell_percentage = sell_percentage
+        self.symbol = symbol

investing_algorithm_framework/domain/models/snapshot_interval.py

@@ -0,0 +1,45 @@
+from enum import Enum
+
+
+class SnapshotInterval(Enum):
+    STRATEGY_ITERATION = "STRATEGY_ITERATION"
+    DAILY = "DAILY"
+
+    @staticmethod
+    def from_string(value: str):
+
+        if isinstance(value, str):
+
+            for entry in SnapshotInterval:
+
+                if value.upper() == entry.value:
+                    return entry
+
+            raise ValueError(
+                f"Could not convert {value} to SnapshotInterval"
+            )
+        return None
+
+    @staticmethod
+    def from_value(value):
+
+        if isinstance(value, str):
+            return SnapshotInterval.from_string(value)
+
+        if isinstance(value, SnapshotInterval):
+
+            for entry in SnapshotInterval:
+
+                if value == entry:
+                    return entry
+
+        raise ValueError(
+            f"Could not convert {value} to SnapshotInterval"
+        )
+
+    def equals(self, other):
+
+        if isinstance(other, Enum):
+            return self.value == other.value
+        else:
+            return SnapshotInterval.from_string(other) == self