investing-algorithm-framework 1.5__py3-none-any.whl → 7.25.6__py3-none-any.whl

investing_algorithm_framework/domain/models/portfolio/portfolio_configuration.py

@@ -1,68 +1,68 @@
-from datetime import datetime
-from investing_algorithm_framework.domain.models.base_model import BaseModel
+from dateutil.parser import parse
+
 from investing_algorithm_framework.domain.exceptions import \
     ImproperlyConfigured
+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,
         market,
         trading_symbol,
-        api_key,
-        secret_key,
         track_from=None,
         identifier=None,
-        max_unallocated=-1,
-        backtest=False
+        initial_balance=None,
     ):
         self._market = market
-        self._api_key = api_key
-        self._secret_key = secret_key
+
+        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._max_unallocated = max_unallocated
-        self._backtest = backtest
+        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 = datetime.strptime(track_from, "%d/%m/%Y")
+            self._track_from = parse(track_from)
 
         if self.trading_symbol is None:
             raise ImproperlyConfigured(
                 "Portfolio configuration requires a trading symbol"
             )
 
-        if self.api_key is None and not self._backtest:
-            raise ImproperlyConfigured(
-                "Portfolio configuration requires an api key"
-            )
-
-        if self.secret_key is None and not self._backtest:
-            raise ImproperlyConfigured(
-                "Portfolio configuration requires a secret key"
-            )
-
     @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
 
-    @property
-    def secret_key(self):
-        return self._secret_key
-
-    @property
-    def api_key(self):
-        return self._api_key
-
     @property
     def track_from(self):
         return self._track_from
@@ -76,24 +76,18 @@ class PortfolioConfiguration(BaseModel):
         return self._trading_symbol
 
     @property
-    def max_unallocated(self):
-        return self._max_unallocated
-
-    @property
-    def has_unallocated_limit(self):
-        return self.max_unallocated != -1
+    def initial_balance(self):
+        return self._initial_balance
 
     @property
-    def backtest(self):
-        return self._backtest
+    def has_initial_balance(self):
+        return self._initial_balance is not None
 
     def __repr__(self):
         return self.repr(
             market=self.market,
             trading_symbol=self.trading_symbol,
-            api_key=self.api_key,
-            secret_key=self.secret_key,
             identifier=self.identifier,
             track_from=self.track_from,
-            max_unallocated=self.max_unallocated,
+            initial_balance=self.initial_balance
         )

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,
@@ -39,6 +42,23 @@ class Position(BaseModel):
     def set_portfolio_id(self, portfolio_id):
         self.portfolio_id = portfolio_id
 
+    def to_dict(self):
+        return {
+            "symbol": self.symbol,
+            "amount": self.amount,
+            "cost": self.cost,
+            "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/position/position_snapshot.py

@@ -1,6 +1,4 @@
 from investing_algorithm_framework.domain.models.base_model import BaseModel
-from investing_algorithm_framework.domain.decimal_parsing import \
-    parse_string_to_decimal
 
 
 class PositionSnapshot(BaseModel):

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