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

investing_algorithm_framework/analysis/markdown.py

@@ -0,0 +1,91 @@
+from typing import Dict, List, Any, Union
+
+
+def create_markdown_table(data: List[Union[Dict[str, Any], Any]]):
+    """
+    Create a markdown table with evenly spaced columns for nice display
+    in notebook output cells.
+
+    Args:
+        data (List[dict] or List[object]): List of dictionaries or objects
+            containing data.
+
+    Returns:
+        str: Markdown formatted table with evenly spaced columns.
+    """
+    if not data or len(data) == 0:
+        return ("| No Data Available |\n"
+                "|-------------------|\n"
+                "| No records found  |\n")
+
+    # Determine if data contains dicts or objects
+    is_dict = isinstance(data[0], dict)
+
+    # Get columns from data
+    if is_dict:
+        columns = list(data[0].keys())
+    else:
+        # For objects, get all attributes (excluding private ones)
+        columns = [
+            attr for attr in dir(data[0])
+            if not attr.startswith('_')
+            and not callable(getattr(data[0], attr))
+        ]
+
+    # Generate header titles
+    header_titles = [col.replace("_", " ").title() for col in columns]
+
+    # Collect and format all row data
+    all_rows_data = []
+    for item in data:
+        row_values = []
+        for col in columns:
+            # Get value
+            if is_dict:
+                value = item.get(col)
+            else:
+                value = getattr(item, col, None)
+
+            # Format value
+            if value is None:
+                formatted_value = "N/A"
+            elif isinstance(value, float):
+                formatted_value = f"{value:.2f}"
+            else:
+                formatted_value = str(value)
+
+            row_values.append(formatted_value)
+        all_rows_data.append(row_values)
+
+    # Calculate column widths based on both headers and data
+    col_widths = []
+    for i, header in enumerate(header_titles):
+        max_width = len(header)
+        for row in all_rows_data:
+            if i < len(row):
+                max_width = max(max_width, len(row[i]))
+        col_widths.append(max_width)
+
+    # Build markdown table
+    markdown = ""
+
+    # Header with padding
+    header_parts = [
+        title.ljust(width)
+        for title, width in zip(header_titles, col_widths)
+    ]
+    markdown += "| " + " | ".join(header_parts) + " |\n"
+
+    # Separator
+    separator_parts = ["-" * width for width in col_widths]
+    markdown += "| " + " | ".join(separator_parts) + " |\n"
+
+    # Data rows
+    for row_values in all_rows_data:
+        row_parts = [
+            value.ljust(width)
+            for value, width in zip(row_values, col_widths)
+        ]
+        markdown += "| " + " | ".join(row_parts) + " |\n"
+
+    return markdown

investing_algorithm_framework/analysis/ranking.py

@@ -0,0 +1,298 @@
+import math
+from typing import List
+from statistics import mean
+
+from investing_algorithm_framework.domain import BacktestEvaluationFocus, \
+    BacktestDateRange, Backtest, BacktestMetrics, OperationalException
+
+
+def normalize(value, min_val, max_val):
+    """
+    Normalize a value to a range [0, 1].
+    """
+    if value is None or math.isnan(value) or math.isinf(value):
+        return 0
+    if min_val == max_val:
+        return 0
+    return (value - min_val) / (max_val - min_val)
+
+
+def compute_score(metrics, weights, ranges):
+    """
+    Compute a weighted score for the given metrics.
+
+    Args:
+        metrics: The metrics to evaluate.
+        weights: The weights to apply to each metric.
+        ranges: The min/max ranges for each metric.
+
+    Returns:
+        float: The computed score.
+    """
+    score = 0
+    for key, weight in weights.items():
+        if not hasattr(metrics, key):
+            continue
+        value = getattr(metrics, key)
+        # Skip non-numeric values (e.g., Trade objects
+        # for best_trade/worst_trade)
+        if not isinstance(value, (int, float)):
+            continue
+        if value is None or math.isnan(value) or math.isinf(value):
+            continue
+        if key in ranges:
+            value = normalize(value, ranges[key][0], ranges[key][1])
+        score += weight * value
+    return score
+
+
+def create_weights(
+    focus: BacktestEvaluationFocus | str | None = None,
+    custom_weights: dict | None = None,
+) -> dict:
+    """
+    Utility to generate weights dicts for ranking backtests.
+
+    This function does not assign weights to every possible performance
+    metric. Instead, it focuses on a curated subset of commonly relevant
+    ones (profitability, win rate, trade frequency, and risk-adjusted returns).
+    The rationale is to avoid overfitting ranking logic to noisy or redundant
+    statistics (e.g., monthly return breakdowns, best/worst trade), while
+    keeping the weighting system simple and interpretable.
+    Users who need fine-grained control can pass `custom_weights` to fully
+    override defaults.
+
+    Args:
+        focus (BacktestEvaluationFocus | str | None): The focus for ranking.
+        custom_weights (dict): Full override for weights (all metrics).
+                               If provided, it takes precedence over presets.
+
+    Returns:
+        dict: A dictionary of weights for ranking backtests.
+    """
+    if focus is None:
+        focus = BacktestEvaluationFocus.BALANCED
+
+    weights = focus.get_weights()
+
+    # if full custom dict is given → override everything
+    if custom_weights is not None:
+        weights = {**weights, **custom_weights}
+
+    return weights
+
+
+def rank_results(
+    backtests: List[Backtest],
+    focus=None,
+    weights=None,
+    filter_fn=None,
+    backtest_date_range: BacktestDateRange = None
+) -> List[Backtest]:
+    """
+    Rank backtest results based on specified focus, weights, and filters.
+
+    Args:
+        backtests (List[Backtest]): List of backtest results to rank.
+        focus (str, optional): Focus for ranking. If None,
+            uses default weights. Options: "balanced", "profit",
+            "frequency", "risk_adjusted".
+        weights (dict, optional): Custom weights for ranking metrics.
+            If None, uses default weights based on focus.
+        filter_fn (callable | dict, optional): A filter to apply to
+            backtests before ranking.
+            - If callable: receives metrics and should return True/False.
+            - If dict: mapping {metric_name: condition_fn},
+              all conditions must pass.
+        backtest_date_range (BacktestDateRange, optional): If provided,
+            only backtests matching this date range are considered.
+
+    Returns:
+        List[Backtest]: Sorted list of backtests based on computed scores.
+    """
+
+    if weights is None:
+        weights = create_weights(focus=focus)
+
+    # Pair backtests with their metrics
+    paired = []
+    for backtest in backtests:
+        if backtest_date_range is not None:
+            metrics = backtest.get_backtest_metrics(backtest_date_range)
+        else:
+            metrics = backtest.backtest_summary
+
+        if metrics is not None:
+            paired.append((backtest, metrics))
+
+    # Apply filtering on metrics
+    if filter_fn is not None:
+        if callable(filter_fn):
+            paired = [
+                (bt, m) for bt, m in paired if filter_fn(m)
+            ]
+        elif isinstance(filter_fn, dict):
+            paired = [
+                (bt, m) for bt, m in paired
+                if all(
+                    cond(getattr(m, key, None))
+                    for key, cond in filter_fn.items()
+                )
+            ]
+
+    # Compute normalization ranges
+    ranges = {}
+    for key in weights:
+        values = [
+            getattr(m, key, None) for _, m in paired
+        ]
+        values = [
+            v for v in values
+            if isinstance(v, (int, float)) and v is not None
+            and not math.isnan(v) and not math.isinf(v)
+        ]
+        if values:
+            ranges[key] = (min(values), max(values))
+
+    # Sort Backtests by score
+    ranked = sorted(
+        paired,
+        key=lambda bm: compute_score(bm[1], weights, ranges),
+        reverse=True
+    )
+
+    return [bt for bt, _ in ranked]
+
+
+def combine_backtest_metrics(
+    backtest_metrics: List[BacktestMetrics]
+) -> BacktestMetrics:
+    """
+    Combine backtest metrics from multiple backtests into a single list.
+
+    Args:
+        backtest_metrics (List[BacktestMetrics]): List of backtest
+            metrics to combine.
+
+    Returns:
+        BacktestMetrics: Combined list of backtest metrics.
+    """
+    if not backtest_metrics:
+        raise OperationalException("No BacktestMetrics provided")
+
+        # Helper to take mean safely
+
+    def safe_mean(values):
+        vals = [v for v in values if v is not None]
+        return mean(vals) if vals else 0.0
+
+        # Dates
+
+    start_date = min(m.backtest_start_date for m in backtest_metrics)
+    end_date = max(m.backtest_end_date for m in backtest_metrics)
+
+    # Aggregate
+    return BacktestMetrics(
+        backtest_start_date=start_date,
+        backtest_end_date=end_date,
+        equity_curve=[],  # leave empty to avoid misleading curves
+        total_growth=safe_mean([m.total_growth for m in backtest_metrics]),
+        total_growth_percentage=safe_mean(
+            [m.total_growth_percentage for m in backtest_metrics]),
+        total_net_gain=safe_mean([m.total_net_gain for m in backtest_metrics]),
+        total_net_gain_percentage=safe_mean(
+            [m.total_net_gain_percentage for m in backtest_metrics]),
+        final_value=safe_mean([m.final_value for m in backtest_metrics]),
+        cagr=safe_mean([m.cagr for m in backtest_metrics]),
+        sharpe_ratio=safe_mean([m.sharpe_ratio for m in backtest_metrics]),
+        rolling_sharpe_ratio=[],
+        sortino_ratio=safe_mean([m.sortino_ratio for m in backtest_metrics]),
+        calmar_ratio=safe_mean([m.calmar_ratio for m in backtest_metrics]),
+        profit_factor=safe_mean([m.profit_factor for m in backtest_metrics]),
+        gross_profit=sum(m.gross_profit or 0 for m in backtest_metrics),
+        gross_loss=sum(m.gross_loss or 0 for m in backtest_metrics),
+        annual_volatility=safe_mean(
+            [m.annual_volatility for m in backtest_metrics]),
+        monthly_returns=[],
+        yearly_returns=[],
+        drawdown_series=[],
+        max_drawdown=max(m.max_drawdown for m in backtest_metrics),
+        max_drawdown_absolute=max(
+            m.max_drawdown_absolute for m in backtest_metrics),
+        max_daily_drawdown=max(m.max_daily_drawdown for m in backtest_metrics),
+        max_drawdown_duration=max(
+            m.max_drawdown_duration for m in backtest_metrics),
+        trades_per_year=safe_mean(
+            [m.trades_per_year for m in backtest_metrics]
+        ),
+        trade_per_day=safe_mean([m.trade_per_day for m in backtest_metrics]),
+        exposure_ratio=safe_mean(
+            [m.exposure_ratio for m in backtest_metrics]
+        ),
+        average_trade_gain=safe_mean(
+            [m.average_trade_gain for m in backtest_metrics]),
+        average_trade_gain_percentage=(
+            safe_mean(
+                [m.average_trade_gain_percentage for m in backtest_metrics]
+            )
+        ),
+        average_trade_loss=safe_mean(
+            [m.average_trade_loss for m in backtest_metrics]),
+        average_trade_loss_percentage=(
+            safe_mean(
+                [m.average_trade_loss_percentage for m in backtest_metrics]
+            )
+        ),
+        median_trade_return=safe_mean(
+            [m.median_trade_return for m in backtest_metrics]),
+        median_trade_return_percentage=(
+            safe_mean(
+                [m.median_trade_return_percentage for m in backtest_metrics]
+            )
+        ),
+        best_trade=max((
+            m.best_trade for m in backtest_metrics if m.best_trade),
+            key=lambda t: t.net_gain if t else float('-inf'),
+            default=None
+        ),
+        worst_trade=min(
+            (m.worst_trade for m in backtest_metrics if m.worst_trade),
+            key=lambda t: t.net_gain if t else float('inf'),
+            default=None
+        ),
+        average_trade_duration=safe_mean(
+            [m.average_trade_duration for m in backtest_metrics]),
+        number_of_trades=sum(m.number_of_trades for m in backtest_metrics),
+        win_rate=safe_mean([m.win_rate for m in backtest_metrics]),
+        win_loss_ratio=safe_mean([m.win_loss_ratio for m in backtest_metrics]),
+        percentage_winning_months=safe_mean(
+            [m.percentage_winning_months for m in backtest_metrics]),
+        percentage_winning_years=safe_mean(
+            [m.percentage_winning_years for m in backtest_metrics]),
+        average_monthly_return=safe_mean(
+            [m.average_monthly_return for m in backtest_metrics]),
+        average_monthly_return_losing_months=safe_mean(
+            [m.average_monthly_return_losing_months for m in backtest_metrics]
+        ),
+        average_monthly_return_winning_months=safe_mean(
+            [m.average_monthly_return_winning_months for m in backtest_metrics]
+        ),
+        best_month=max(
+            (m.best_month for m in backtest_metrics if m.best_month),
+            key=lambda x: x[0] if x else float('-inf'),
+            default=None
+        ),
+        best_year=max((m.best_year for m in backtest_metrics if m.best_year),
+                      key=lambda x: x[0] if x else float('-inf'),
+                      default=None),
+        worst_month=min(
+            (m.worst_month for m in backtest_metrics if m.worst_month),
+            key=lambda x: x[0] if x else float('inf'),
+            default=None
+        ),
+        worst_year=min(
+            (m.worst_year for m in backtest_metrics if m.worst_year),
+            key=lambda x: x[0] if x else float('inf'),
+            default=None
+        ),
+    )

investing_algorithm_framework/app/__init__.py

@@ -1,13 +1,40 @@
-from investing_algorithm_framework.app.app import App
-from investing_algorithm_framework.app.web import create_flask_app
-from investing_algorithm_framework.app.strategy import TradingStrategy
+from investing_algorithm_framework.app.app import App, AppHook
 from investing_algorithm_framework.app.stateless import StatelessAction
+from investing_algorithm_framework.app.strategy import TradingStrategy
 from investing_algorithm_framework.app.task import Task
+from investing_algorithm_framework.app.web import create_flask_app
+from .algorithm import Algorithm
+from .context import Context
+from .reporting import add_html_report, \
+    BacktestReport, pretty_print_backtest, pretty_print_trades, \
+    pretty_print_positions, pretty_print_orders, \
+    get_equity_curve_with_drawdown_chart, \
+    get_rolling_sharpe_ratio_chart, \
+    get_monthly_returns_heatmap_chart, \
+    get_yearly_returns_bar_chart, get_equity_curve_chart, \
+    get_ohlcv_data_completeness_chart, get_entry_and_exit_signals
+
 
 __all__ = [
+    "Algorithm",
     "App",
     "create_flask_app",
     "TradingStrategy",
     "StatelessAction",
-    "Task"
+    "Task",
+    "AppHook",
+    "Context",
+    "add_html_report",
+    "BacktestReport",
+    "pretty_print_backtest",
+    "pretty_print_trades",
+    "pretty_print_positions",
+    "pretty_print_orders",
+    "get_equity_curve_with_drawdown_chart",
+    "get_rolling_sharpe_ratio_chart",
+    "get_monthly_returns_heatmap_chart",
+    "get_yearly_returns_bar_chart",
+    "get_ohlcv_data_completeness_chart",
+    "get_entry_and_exit_signals",
+    "get_equity_curve_chart",
 ]

investing_algorithm_framework/app/algorithm/__init__.py

@@ -0,0 +1,7 @@
+from .algorithm_factory import AlgorithmFactory
+from .algorithm import Algorithm
+
+__all__ = [
+    "AlgorithmFactory",
+    "Algorithm"
+]

investing_algorithm_framework/app/algorithm/algorithm.py

@@ -0,0 +1,193 @@
+import inspect
+import logging
+from typing import List
+
+from investing_algorithm_framework.app.app_hook import AppHook
+from investing_algorithm_framework.app.strategy import TradingStrategy
+from investing_algorithm_framework.domain import OperationalException, \
+    DataSource
+
+logger = logging.getLogger("investing_algorithm_framework")
+
+
+class Algorithm:
+    """
+    Class to represent an algorithm. An algorithm is a collection of
+    strategies that are executed in a specific order.
+
+    Attributes:
+        algorithm_id: The unique identifier of the algorithm. This id
+            should be a string and also will be used for all the
+            registered strategies within the algorithm.
+        _description: The description of the algorithm. It should be a string.
+        _strategies: A list of strategies that are part of the algorithm.
+        _tasks: A list of tasks that are part of the algorithm.
+        _data_sources: A list of data sources that are part of the algorithm.
+        _on_strategy_run_hooks: A list of hooks that will be called when a
+    """
+    def __init__(
+        self,
+        algorithm_id: str = None,
+        description: str = None,
+        strategy=None,
+        strategies=None,
+        tasks: List = None,
+        data_sources: List[DataSource] = None,
+        on_strategy_run_hooks=None,
+        metadata=None
+    ):
+        self.algorithm_id = algorithm_id
+        self._context = {}
+        self._description = None
+
+        if description is not None:
+            self._description = description
+
+        self._strategies = []
+        self._tasks = []
+        self._data_sources = []
+        self._on_strategy_run_hooks = []
+        self.metadata = metadata
+
+        if data_sources is not None:
+            self._data_sources = data_sources
+
+        if strategies is not None:
+            self.strategies = strategies
+
+        if tasks is not None:
+            self.tasks = tasks
+
+        if strategy is not None:
+            self.add_strategy(strategy, throw_exception=True)
+
+        if on_strategy_run_hooks is not None:
+            for hook in on_strategy_run_hooks:
+                self.add_on_strategy_run_hook(hook)
+
+    @property
+    def data_sources(self):
+        return self._data_sources
+
+    @data_sources.setter
+    def data_sources(self, data_sources):
+        self._data_sources = data_sources
+
+    @property
+    def description(self):
+        """
+        Function to get the description of the algorithm
+        """
+        return self._description
+
+    @property
+    def strategies(self):
+        return self._strategies
+
+    @property
+    def on_strategy_run_hooks(self):
+        return self._on_strategy_run_hooks
+
+    @strategies.setter
+    def strategies(self, strategies):
+
+        for strategy in strategies:
+            self.add_strategy(strategy)
+
+    @property
+    def tasks(self):
+        return self._tasks
+
+    @tasks.setter
+    def tasks(self, tasks):
+
+        for task in tasks:
+            self.add_task(task)
+
+    def get_strategy(self, strategy_id):
+        for strategy in self._strategies:
+            if strategy.worker_id == strategy_id:
+                return strategy
+
+        return None
+
+    def get_strategies(self):
+
+        if self._strategies is None:
+            raise OperationalException(
+                "No strategies have been added to the algorithm"
+            )
+        return self._strategies
+
+    def add_strategy(self, strategy, throw_exception=True) -> None:
+        """
+        Function to add a strategy to the algorithm. The strategy should be an
+        instance of TradingStrategy or a subclass based on the TradingStrategy
+        class.
+
+        Args:
+            strategy: Instance of TradingStrategy
+            throw_exception: Flag to allow for throwing an exception when
+                the provided strategy is not inline with what the application
+                expects.
+
+        Returns:
+            None
+        """
+
+        if inspect.isclass(strategy):
+
+            if not issubclass(strategy, TradingStrategy):
+                raise OperationalException(
+                    "The strategy must be a subclass of TradingStrategy"
+                )
+
+            strategy = strategy()
+
+        if not isinstance(strategy, TradingStrategy):
+
+            if throw_exception:
+                raise OperationalException(
+                    "Strategy should be an instance of TradingStrategy"
+                )
+            else:
+                return
+
+        strategy_ids = []
+
+        for s in self._strategies:
+            strategy_ids.append(s.strategy_id)
+
+        # Check for duplicate strategy IDs
+        if strategy.strategy_id in strategy_ids:
+            raise OperationalException(
+                "Can't add strategy, there already exists a strategy "
+                "with the same id in the algorithm"
+            )
+
+        strategy.algorithm_id = self.algorithm_id
+        self._strategies.append(strategy)
+
+    def add_task(self, task):
+        if inspect.isclass(task):
+            task = task()
+
+        self._tasks.append(task)
+
+    def add_on_strategy_run_hook(self, app_hook):
+        """
+        Function to add a hook that will be called when a strategy is run.
+
+        Args:
+            app_hook: The hook function to be added.
+        """
+        # Check if the app_hook inherits from AppHook
+        if inspect.isclass(app_hook) and not issubclass(app_hook, AppHook):
+            raise OperationalException(
+                "App hook should be an instance of AppHook"
+            )
+
+        if inspect.isclass(app_hook):
+            app_hook = app_hook()
+
+        self._on_strategy_run_hooks.append(app_hook)