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

investing_algorithm_framework/services/metrics/volatility.py

@@ -0,0 +1,118 @@
+"""
+Volatility is a statistical measure of the dispersion of returns for a
+given portfolio. In finance, it is commonly used as a proxy for risk.
+This function calculates the standard deviation of daily log returns and
+annualizes it, giving an estimate of how much the portfolio's value
+fluctuates on a yearly basis.
+
+| **Annual Volatility** | **Risk Level (Standalone)** | **Context Matters: Sharpe Ratio Impact** | **Comments** |
+| --------------------- | --------------------------- | ---------------------------------------- | ----------- |
+| **< 5%** | Very Low Risk | Sharpe > 2.0 = Excellent<br>Sharpe < 0.5 = Poor | Low volatility is great unless returns are negative |
+| **5% – 10%** | Low Risk | Sharpe > 1.0 = Good<br>Sharpe < 0.3 = Mediocre | Typical for conservative portfolios |
+| **10% – 15%** | Moderate Risk | Sharpe > 0.8 = Good<br>Sharpe < 0.2 = Risky | S&P 500 benchmark; quality matters |
+| **15% – 25%** | High Risk | Sharpe > 0.6 = Acceptable<br>Sharpe < 0.0 = Avoid | **Example: 30% CAGR + 23% vol = Sharpe ~1.3 = Excellent** |
+| **> 25%** | Very High Risk | Sharpe > 0.4 = Maybe acceptable<br>Sharpe < 0.0 = Dangerous | Only viable with strong positive returns |
+
+
+Key takeaway: Don't interpret volatility in isolation. Always calculate
+and compare the Sharpe Ratio to assess true strategy quality.
+Your 30% CAGR with 23% volatility is exceptional because the return far outweighs the risk taken.
+
+"""
+
+from typing import List
+
+import pandas as pd
+import numpy as np
+
+from investing_algorithm_framework.domain import PortfolioSnapshot
+
+
+def get_annual_volatility(
+    snapshots: List[PortfolioSnapshot],
+    trading_days_per_year=365
+) -> float:
+    """
+    Calculate the annualized volatility of portfolio net values.
+
+    !Important Note:
+
+    Volatility measures variability, not direction. For example:
+
+    A standard deviation of 0.238 (23.8%) means returns swing
+    wildly around their average, but it doesn't tell you if that average
+    is positive or negative.
+
+    Two scenarios with the same 23.8% volatility:
+        Mean return = +15% per year, Std = 23.8%
+        16% chance of losing >8.8% (15% - 23.8%)
+        16% chance of gaining >38.8% (15% + 23.8%)
+        This is excellent — high growth with swings
+
+        Mean return = -5% per year, Std = 23.8%
+        16% chance of losing >28.8% (-5% - 23.8%)
+        16% chance of gaining >18.8% (-5% + 23.8%)
+        This is terrible — losing money with high risk
+
+    To assess if "always good returns with high std" is perfect, you need
+    to consider risk-adjusted metrics like the Sharpe Ratio:
+    Sharpe Ratio = (Mean Return - Risk-Free Rate) / Volatility
+    Higher is better; tells you return per unit of risk taken
+
+    Args:
+        snapshots (List[PortfolioSnapshot]): List of portfolio snapshots
+            from the backtest report.
+        trading_days_per_year (int): Number of trading days in a year.
+
+    Returns:
+        Float: Annualized volatility as a float
+    """
+
+    if len(snapshots) < 2:
+        return 0.0
+
+    # Build DataFrame from snapshots
+    records = [
+        (snapshot.total_value, snapshot.created_at) for snapshot in snapshots
+    ]
+    df = pd.DataFrame(records, columns=['total_value', 'created_at'])
+    df['created_at'] = pd.to_datetime(df['created_at'])
+    df = df.set_index('created_at').sort_index().drop_duplicates()
+
+    # Resample to daily frequency, taking the last value of each day
+    df_daily = df.resample('D').last()
+    df_daily = df_daily.dropna()
+
+    if len(df_daily) < 2:
+        return 0.0
+
+    # Filter out non-positive values before calculating log returns
+    # Log returns are only valid for positive portfolio values
+    df_daily = df_daily[df_daily['total_value'] > 0]
+
+    if len(df_daily) < 2:
+        return 0.0
+
+    # Calculate log returns on daily data
+    # Add a small epsilon to avoid log(0) and replace inf/nan values
+    price_ratios = df_daily['total_value'] / df_daily['total_value'].shift(1)
+
+    # Filter out invalid price ratios (zero, negative, or NaN)
+    df_daily['log_return'] = np.log(price_ratios)
+
+    # Replace inf and -inf with NaN, then drop them
+    df_daily['log_return'] = df_daily['log_return'].replace([np.inf, -np.inf], np.nan)
+    df_daily = df_daily.dropna()
+
+    if len(df_daily) < 2:
+        return 0.0
+
+    # Calculate daily volatility (standard deviation of daily returns)
+    daily_volatility = df_daily['log_return'].std()
+
+    # Handle edge case where std might be NaN
+    if pd.isna(daily_volatility):
+        return 0.0
+
+    # Annualize using trading days per year
+    return daily_volatility * np.sqrt(trading_days_per_year)

investing_algorithm_framework/services/metrics/win_rate.py

@@ -0,0 +1,177 @@
+"""
+| Metric             | High Value Means...         | Weakness if Used Alone              |
+| ------------------ | --------------------------- | ----------------------------------- |
+| **Win Rate**       | Many trades are profitable  | Doesn't say how big wins/losses are |
+| **Win/Loss Ratio** | Big wins relative to losses | Doesn’t say how *often* you win     |
+
+
+Example of Non-Overlap:
+Strategy A: 90% win rate, but average win is $1, average loss is $10 → not profitable.
+
+Strategy B: 30% win rate, but average win is $300, average loss is $50 → highly profitable.
+
+| Win Rate          | Win/Loss Ratio | Comment                            |
+| ----------------- | -------------- | ---------------------------------- |
+| High (>60%)       | <1             | Can still be profitable            |
+| Moderate (40-60%) | \~1 or >1      | Ideal sweet spot                   |
+| Low (<40%)        | >1             | Possible if big wins offset losses |
+
+
+Practical Example:
+* Win rate 40% with win/loss ratio 2: Good — you win less often but your
+wins are twice as big.
+* Win rate 60% with win/loss ratio 0.7: Also good — you win often
+but your wins are smaller than losses.
+
+What’s “good”?
+* Typical win/loss ratio ranges from 0.5 to 3 depending on strategy style.
+* Many profitable traders target win/loss ratio between 1.5 and 2.5.
+* Very aggressive strategies might have a lower win rate but
+higher win/loss ratio.
+"""
+
+from typing import List
+from investing_algorithm_framework.domain import TradeStatus, Trade
+
+
+def get_win_rate(trades: List[Trade]) -> float:
+    """
+    Calculate the win rate of the portfolio based on the backtest report.
+
+    Win Rate is defined as the percentage of trades that were profitable.
+    The percentage of trades that are profitable.
+
+    Formula:
+        Win Rate = Number of Profitable Trades / Total Number of Trades
+
+    Example: If 60 out of 100 trades are profitable, the win rate is 60%.
+
+    Args:
+        trades (List[Trade]): List of trades from the backtest report.
+
+    Returns:
+        float: The win rate as a percentage (e.g., o.75 for 75% win rate).
+    """
+    trades = [
+        trade for trade in trades if TradeStatus.CLOSED.equals(trade.status)
+    ]
+    positive_trades = sum(1 for trade in trades if trade.net_gain > 0)
+    total_trades = len(trades)
+
+    if total_trades == 0:
+        return 0.0
+
+    return positive_trades / total_trades
+
+def get_current_win_rate(trades: List[Trade]) -> float:
+    """
+    Calculate the current win rate of the portfolio based on a list
+    of recent trades.
+
+    Current Win Rate is defined as the percentage of the most recent trades
+    that were profitable. This metric also includes trades that are still open.
+
+    Formula:
+        Current Win Rate = Number of Profitable Recent Trades
+            / Total Number of Recent Trades
+
+    Args:
+        trades (List[Trade]): List of recent trades.
+
+    Returns:
+        float: The current win rate as a percentage (e.g., 0.75 for
+            75% win rate).
+    """
+    if not trades:
+        return 0.0
+
+    positive_trades = sum(1 for trade in trades if trade.net_gain_absolute > 0)
+    total_trades = len(trades)
+
+    return positive_trades / total_trades
+
+
+def get_win_loss_ratio(trades: List[Trade]) -> float:
+    """
+    Calculate the win/loss ratio of the portfolio based on the backtest report.
+
+    Win/Loss Ratio is defined as the average profit of winning trades divided by
+    the average loss of losing trades.
+
+    Formula:
+        Win/Loss Ratio = Average Profit of Winning Trades
+            / Average Loss of Losing Trades
+
+    Example: If the average profit of winning trades is $200 and the
+            average loss of losing trades is $100, the win/loss ratio is 2.0.
+
+    Args:
+        trades (List[Trade]): List of trades from the backtest report.
+
+    Returns:
+        float: The win/loss ratio.
+    """
+    trades = [
+        trade for trade in trades if TradeStatus.CLOSED.equals(trade.status)
+    ]
+
+    if not trades:
+        return 0.0
+
+    # Separate winning and losing trades
+    winning_trades = [t for t in trades if t.net_gain > 0]
+    losing_trades = [t for t in trades if t.net_gain < 0]
+
+    if not winning_trades or not losing_trades:
+        return 0.0
+
+    # Compute averages
+    avg_win = sum(t.net_gain for t in winning_trades) / len(winning_trades)
+    avg_loss = abs(
+        sum(t.net_gain for t in losing_trades) / len(losing_trades))
+
+    # Avoid division by zero
+    if avg_loss == 0:
+        return float('inf')
+
+    return avg_win / avg_loss
+
+
+def get_current_win_loss_ratio(trades: List[Trade]) -> float:
+    """
+    Calculate the current win/loss ratio of the portfolio based on a list
+    of recent trades.
+
+    Current Win/Loss Ratio is defined as the average profit of winning
+    recent trades divided by the average loss of losing recent trades.
+    This metric also includes trades that are still open.
+
+    Formula:
+        Current Win/Loss Ratio = Average Profit of Winning Recent Trades
+            / Average Loss of Losing Recent Trades
+    Args:
+        trades (List[Trade]): List of recent trades.
+
+    Returns:
+        float: The current win/loss ratio.
+    """
+    if not trades:
+        return 0.0
+
+    # Separate winning and losing trades
+    winning_trades = [t for t in trades if t.net_gain_absolute > 0]
+    losing_trades = [t for t in trades if t.net_gain_absolute < 0]
+
+    if not winning_trades or not losing_trades:
+        return 0.0
+
+    # Compute averages
+    avg_win = sum(t.net_gain_absolute for t in winning_trades) / len(winning_trades)
+    avg_loss = abs(
+        sum(t.net_gain_absolute for t in losing_trades) / len(losing_trades))
+
+    # Avoid division by zero
+    if avg_loss == 0:
+        return float('inf')
+
+    return avg_win / avg_loss

investing_algorithm_framework/services/order_service/__init__.py

@@ -0,0 +1,9 @@
+from .order_backtest_service import OrderBacktestService
+from .order_service import OrderService
+from .order_executor_lookup import OrderExecutorLookup
+
+__all__ = [
+    "OrderService",
+    "OrderBacktestService",
+    "OrderExecutorLookup",
+]

investing_algorithm_framework/services/order_service/order_backtest_service.py

@@ -0,0 +1,178 @@
+import logging
+
+import polars as pl
+
+from investing_algorithm_framework.domain import INDEX_DATETIME, \
+    OrderStatus, OrderSide, Order, DataType
+from .order_service import OrderService
+
+logger = logging.getLogger("investing_algorithm_framework")
+
+
+class OrderBacktestService(OrderService):
+
+    def __init__(
+        self,
+        order_repository,
+        trade_service,
+        position_service,
+        portfolio_repository,
+        portfolio_configuration_service,
+        portfolio_snapshot_service,
+        configuration_service,
+    ):
+        super().__init__(
+            configuration_service=configuration_service,
+            order_repository=order_repository,
+            position_service=position_service,
+            portfolio_repository=portfolio_repository,
+            portfolio_configuration_service=portfolio_configuration_service,
+            portfolio_snapshot_service=portfolio_snapshot_service,
+            trade_service=trade_service,
+        )
+        self.configuration_service = configuration_service
+
+    def create(self, data, execute=True, validate=True, sync=True) -> Order:
+        """
+        Override the create method to set the created_at and
+        updated_at attributes to the current backtest time.
+
+        Args:
+            data (dict): Dictionary containing the order data
+            execute (bool): Flag to execute the order
+            validate (bool): Flag to validate the order
+            sync (bool): Flag to sync the order
+
+        Returns:
+            Order: Created order object
+        """
+        config = self.configuration_service.get_config()
+        # Make sure the created_at is set to the current backtest time
+        data["created_at"] = config[INDEX_DATETIME]
+        data["updated_at"] = config[INDEX_DATETIME]
+        # Call super to have standard behavior
+        return super(OrderBacktestService, self)\
+            .create(data, execute, validate, sync)
+
+    def execute_order(self, order, portfolio):
+        order.status = OrderStatus.OPEN.value
+        order.remaining = order.get_amount()
+        order.filled = 0
+        order.updated_at = self.configuration_service.config[
+            INDEX_DATETIME
+        ]
+        return order
+
+    def check_pending_orders(self, market_data):
+        """
+        Function to check if any pending orders have executed. It querys the
+        open orders and checks if the order has executed based on the OHLCV
+        data. If the order has executed, the order status is set to CLOSED
+        and the filled amount is set to the order amount.
+
+        Args:
+            market_data (dict): Dictionary containing the market data
+
+        Returns:
+            None
+        """
+        pending_orders = self.get_all({"status": OrderStatus.OPEN.value})
+        meta_data = market_data["metadata"]
+
+        for order in pending_orders:
+            ohlcv_meta_data = meta_data[DataType.OHLCV]
+
+            if order.get_symbol() not in ohlcv_meta_data:
+                continue
+
+            timeframes = ohlcv_meta_data[order.get_symbol()].keys()
+            sorted_timeframes = sorted(timeframes)
+            most_granular_interval = sorted_timeframes[0]
+            identifier = (
+                ohlcv_meta_data[order.get_symbol()][most_granular_interval]
+            )
+            data = market_data[identifier]
+
+            if self.has_executed(order, data):
+                self.update(
+                    order.id,
+                    {
+                        "status": OrderStatus.CLOSED.value,
+                        "filled": order.get_amount(),
+                        "remaining": 0,
+                        "updated_at": self.configuration_service
+                        .config[INDEX_DATETIME]
+                    }
+                )
+
+    def cancel_order(self, order):
+        self.check_pending_orders()
+        order = self.order_repository.get(order.id)
+
+        if order is not None:
+
+            if OrderStatus.OPEN.equals(order.status):
+                self.update(
+                    order.id,
+                    {
+                        "status": OrderStatus.CANCELED.value,
+                        "remaining": 0,
+                        "updated_at": self.configuration_service
+                        .config[INDEX_DATETIME]
+                    }
+                )
+
+    def has_executed(self, order, ohlcv_data_frame: pl.DataFrame):
+        """
+        Check if the order has executed based on the OHLCV data.
+
+        A buy order is executed if the low price drops below or equals the
+        order price. Example: If the order price is 1000 and the low price
+        drops below or equals 1000, the order is executed. This simulates the
+        situation where a buyer is willing to pay a higher price than the
+        lowest price in the ohlcv data.
+
+        A sell order is executed if the high price goes above or equals the
+        order price. Example: If the order price is 1000 and the high price
+        goes above or equals 1000, the order is executed. This simulates the
+        situation where a seller is willing to accept a higher price for its
+        sell order.
+
+        Args:
+            order: Order object
+            ohlcv_data_frame: OHLCV data frame
+            True if the order has executed, False otherwise
+
+        Returns:
+            bool: True if the order has executed, False otherwise
+        """
+
+        # Extract attributes from the order object
+        created_at = order.get_created_at()
+        order_side = order.get_order_side()
+        order_price = order.get_price()
+        ohlcv_data_after_order = ohlcv_data_frame.filter(
+            pl.col('Datetime') >= created_at
+        )
+
+        # Check if the order execution conditions are met
+        if OrderSide.BUY.equals(order_side):
+            # Check if the low price drops below or equals the order price
+            if (ohlcv_data_after_order['Low'] <= order_price).any():
+                return True
+        elif OrderSide.SELL.equals(order_side):
+            # Check if the high price goes above or equals the order price
+            if (ohlcv_data_after_order['High'] >= order_price).any():
+                return True
+
+        # If conditions are not met, return False
+        return False
+
+    def create_snapshot(self, portfolio_id, created_at=None):
+
+        if created_at is None:
+            created_at = self.configuration_service \
+                .config[INDEX_DATETIME]
+
+        super(OrderBacktestService, self)\
+            .create_snapshot(portfolio_id, created_at=created_at)

investing_algorithm_framework/services/order_service/order_executor_lookup.py

@@ -0,0 +1,110 @@
+from collections import defaultdict
+from typing import List
+
+from investing_algorithm_framework.domain import OrderExecutor, \
+    ImproperlyConfigured
+
+
+class OrderExecutorLookup:
+    """
+    Efficient lookup for order executors based on market in O(1) time.
+
+    Attributes:
+        order_executors (List[OrderExecutor]): List of order executors
+        order_executor_lookup (dict): Dictionary to store the lookup
+            for order executors based on market.
+    """
+    def __init__(self, order_executors=[]):
+        self.order_executors = order_executors
+
+        # These will be our lookup tables
+        self.order_executor_lookup = defaultdict()
+
+    def add_order_executor(self, order_executor: OrderExecutor):
+        """
+        Add an order executor to the lookup.
+
+        Args:
+            order_executor (OrderExecutor): The order executor to be added.
+
+        Returns:
+            None
+        """
+        self.order_executors.append(order_executor)
+
+    def register_order_executor_for_market(self, market) -> None:
+        """
+        Register an order executor for a specific market.
+        This method will create a lookup table for efficient access to
+        order executors based on market. It will use the
+        order executors that are currently registered in the
+        order_executors list. The lookup table will be a dictionary
+        where the key is the market and the value is the portfolio provider.
+
+        This method will also check if the portfolio provider supports
+        the market. If no portfolio provider is found for the market,
+        it will raise an ImproperlyConfigured exception.
+
+        If multiple order executors are found for the market,
+        it will sort them by priority and pick the best one.
+
+        Args:
+            market:
+
+        Returns:
+            None
+        """
+        matches = []
+
+        for order_executor in self.order_executors:
+
+            if order_executor.supports_market(market):
+                matches.append(order_executor)
+
+        if len(matches) == 0:
+            raise ImproperlyConfigured(
+                f"No portfolio provider found for market "
+                f"{market}. Cannot configure portfolio."
+                f" Please make sure that you have registered a portfolio "
+                f"provider for the market you are trying to use"
+            )
+
+        # Sort by priority and pick the best one
+        best_provider = sorted(matches, key=lambda x: x.priority)[0]
+        self.order_executor_lookup[market] = best_provider
+
+    def get_order_executor(self, market: str):
+        """
+        Get the order executor for a specific market.
+        This method will return the order executor for the market
+        that was registered in the lookup table. If no order executor
+        was found for the market, it will return None.
+
+        Args:
+            market:
+
+        Returns:
+            OrderExecutor: The order executor for the market.
+        """
+        return self.order_executor_lookup.get(market, None)
+
+    def get_all(self) -> List[OrderExecutor]:
+        """
+        Get all order executors.
+        This method will return all order executors that are currently
+        registered in the order_executors list.
+
+        Returns:
+            List[OrderExecutor]: A list of all order executors.
+        """
+        return self.order_executors
+
+    def reset(self):
+        """
+        Function to reset the order executor lookup table
+
+        Returns:
+            None
+        """
+        self.order_executor_lookup = defaultdict()
+        self.order_executors = []