investing-algorithm-framework 7.19.14__py3-none-any.whl

investing_algorithm_framework/app/reporting/tables/trade_metrics_table.py

@@ -0,0 +1,147 @@
+import pandas as pd
+
+from investing_algorithm_framework.domain import DEFAULT_DATETIME_FORMAT
+from .utils import safe_format, safe_format_date, safe_format_percentage
+
+
+def highlight_win_rate(row):
+    """
+    | **Winning Percentage** | **Interpretation**                                                   |
+    |-------------------------|----------------------------------------------------------------------|
+    | **< 40%**               | 🟥 Poor — Strategy may not be viable                                 |
+    | **40% to 50%**          | 🟧 Weak — Needs improvement, often breakeven or slightly negative     |
+    | **50% to 60%**          | 🟨 Average — Acceptable for many strategies, especially with high PF  |
+    | **60% to 70%**          | 🟩 Good — Solid performance, often with good risk/reward              |
+    | **> 70%**               | 🟩 Excellent — High win rate, typically indicates a strong edge       |
+    """
+    metric = row['Metric']
+    try:
+        value = float(row['Value'].strip('%'))
+    except Exception:
+        value = None
+    styles = pd.Series('', index=row.index)
+    if metric == 'Win Rate' and value is not None:
+        if value < 40:
+            styles['Value'] = 'color: #B22222; font-weight: bold;'  # red
+        elif 40 <= value < 50:
+            styles['Value'] = 'color: #FFA500; font-weight: bold;'  # orange
+        elif 50 <= value < 60:
+            styles['Value'] = 'color: #FFD700; font-weight: bold;'  # gold
+        elif 60 <= value < 70:
+            styles['Value'] = 'color: #32CD32; font-weight: bold;'  # lime green
+        elif value >= 70:
+            styles['Value'] = 'color: #228B22; font-weight: bold;'  # dark green
+    return styles
+
+
+def highlight_win_loss_ratio(row):
+    """
+    | **Win/Loss Ratio** | **Interpretation**                                                   |
+    |---------------------|----------------------------------------------------------------------|
+    | **< 0.5**           | 🟥 Poor — Strategy may not be viable                                 |
+    | **0.5 to 1.0**      | 🟧 Weak — Needs improvement, often breakeven or slightly negative     |
+    | **1.0 to 1.5**      | 🟨 Average — Acceptable for many strategies, especially with high PF  |
+    | **1.5 to 2.0**      | 🟩 Good — Solid performance, often with good risk/reward              |
+    | **> 2.0**           | 🟩 Excellent — High win/loss ratio, typically indicates a strong edge |
+    """
+    metric = row['Metric']
+    try:
+        value = float(row['Value'])
+    except Exception:
+        value = None
+    styles = pd.Series('', index=row.index)
+    if metric == 'Win/Loss Ratio' and value is not None:
+        if value < 0.5:
+            styles['Value'] = 'color: #B22222; font-weight: bold;'  # red
+        elif 0.5 <= value < 1.0:
+            styles['Value'] = 'color: #FFA500; font-weight: bold;'  # orange
+        elif 1.0 <= value < 1.5:
+            styles['Value'] = 'color: #FFD700; font-weight: bold;'  # gold
+        elif 1.5 <= value < 2.0:
+            styles['Value'] = 'color: #32CD32; font-weight: bold;'  # lime green
+        elif value >= 2.0:
+            styles['Value'] = 'color: #228B22; font-weight: bold;'  # dark green
+    return styles
+
+
+def create_html_trade_metrics_table(results, report):
+    copy_results = results.to_dict().copy()
+    string_format = "{:.2f}"
+    copy_results['Trades per Year'] = safe_format(copy_results['trades_per_year'], string_format)
+    copy_results['Trades per Day'] =  safe_format(copy_results['trade_per_day'], string_format)
+    copy_results['Exposure Ratio'] = safe_format(copy_results['exposure_ratio'],string_format)
+    copy_results["Cumulative Exposure"] = safe_format(copy_results['cumulative_exposure'],string_format)
+    best_trade = copy_results['best_trade']
+
+    if best_trade is None:
+        copy_results["Best Trade"] = "N/A"
+        copy_results['Best Trade Date'] = "N/A"
+    else:
+        copy_results['Best Trade'] = f"{best_trade['net_gain']:.2f} {report.trading_symbol}"
+        copy_results['Best Trade Date'] = safe_format_date(best_trade["opened_at"], format_str=DEFAULT_DATETIME_FORMAT)
+    worst_trade = copy_results['worst_trade']
+
+    if worst_trade is None:
+        copy_results["Worst Trade"] = "N/A"
+        copy_results['Worst Trade Date'] = "N/A"
+    else:
+        copy_results['Worst Trade'] = f"{worst_trade['net_gain']:.2f} {report.trading_symbol}"
+        copy_results['Worst Trade Date'] = safe_format_date(worst_trade['opened_at'], format_str=DEFAULT_DATETIME_FORMAT)
+
+    copy_results['Trades Average Gain'] = f"{safe_format(copy_results['average_trade_gain'], string_format)} {report.trading_symbol} {copy_results['trades_average_gain_percentage']:.2f}%"
+    copy_results['Trades Average Loss'] = f"{safe_format(copy_results['average_trade_loss'], string_format)} {report.trading_symbol} {copy_results['trades_average_loss_percentage']:.2f}%"
+    copy_results['Average Trade Duration'] = f"{copy_results['average_trade_duration']:.2f} hours"
+    copy_results['Number of Trades'] = f"{copy_results['number_of_trades']}"
+    copy_results['Win Rate'] = f"{copy_results['win_rate']:.2f}%"
+    copy_results['Win/Loss Ratio'] = f"{copy_results['win_loss_ratio']:.2f}"
+
+    stats = {
+        "Metric": [
+            "Trades per Year",
+            "Trade per Day",
+            "Exposure Ratio",
+            "Cumulative Exposure",
+            "Trades Average Gain",
+            "Trades Average Loss",
+            "Best Trade",
+            "Best Trade Date",
+            "Worst Trade",
+            "Worst Trade Date",
+            "Average Trade Duration",
+            "Number of Trades",
+            "Win Rate",
+            "Win/Loss Ratio"
+        ],
+        "Value": [
+            copy_results['Trades per Year'],
+            copy_results['Trades per Day'],
+            copy_results['Exposure Ratio'],
+            copy_results['Cumulative Exposure'],
+            copy_results['Trades Average Gain'],
+            copy_results['Trades Average Loss'],
+            copy_results['Best Trade'],
+            copy_results['Best Trade Date'],
+            copy_results['Worst Trade'],
+            copy_results['Worst Trade Date'],
+            copy_results['Average Trade Duration'],
+            copy_results['Number of Trades'],
+            copy_results['Win Rate'],
+            copy_results['Win/Loss Ratio']
+        ]
+    }
+
+    df_stats = pd.DataFrame(stats)
+
+    table_html = (
+        df_stats.style
+        .apply(highlight_win_rate, axis=1)
+        .apply(highlight_win_loss_ratio, axis=1)
+        .set_table_styles([
+            {'selector': 'th', 'props': [('background-color', '#f2f2f2'), ('font-weight', 'bold')]},
+            {'selector': 'td', 'props': [('font-size', '14px')]},
+            {'selector': 'tr:nth-child(even)', 'props': [('background-color', '#fafafa')]}
+        ])
+        .hide(axis='index')
+        .to_html()
+    )
+    return table_html

investing_algorithm_framework/app/reporting/tables/trades_table.py

@@ -0,0 +1,75 @@
+import pandas as pd
+
+
+def highlight_net_gain(row):
+    """
+    Apply conditional formatting to the 'Net Gain' column based on numeric value.
+    """
+    try:
+        # Extract numeric value before the first space (assumes format like "123.45 USDT (10.23%)")
+        value_str = row['Net Gain'].split()[2]
+        value_str = value_str.split('(')[1]
+        value_str = value_str.replace(')', '').strip()
+        if '%' in value_str:
+            value_str = value_str.replace('%', '')
+        value = float(value_str)
+
+    except Exception:
+        value = None
+
+    styles = pd.Series('', index=row.index)
+
+    if value is not None:
+        if value < -5:
+            styles['Net Gain'] = 'color: #B22222; font-weight: bold;'  # red
+        elif -5 <= value < -2:
+            styles['Net Gain'] = 'color: #FFA500; font-weight: bold;'  # orange
+        elif -2 <= value < 0:
+            styles['Net Gain'] = 'color: #FFD700; font-weight: bold;'  # gold
+        elif 0 <= value < 5:
+            styles['Net Gain'] = 'color: #32CD32; font-weight: bold;'  # lime green
+        elif value >= 5:
+            styles['Net Gain'] = 'color: #228B22; font-weight: bold;'  # dark green
+
+    return styles
+
+def get_exit(trade):
+    """
+    Returns the exit price of a trade if it is closed, otherwise returns "open".
+    This is used to display the exit price in the trades table.
+
+    A trade can have multiple exits and close prices.
+    """
+
+    if trade.closed_at:
+        return f"{trade.closed_at.strftime('%Y-%m-%d %H:%M:%S')}"
+    else:
+        return "open"
+
+
+def create_html_trades_table(report):
+    trades = report.get_trades()
+
+    # Create a DataFrame from the trades, with the attributes id, net_gain, net_gain_percentage, entry_time, exit_time, duration, and symbol
+    selection = {
+        'Trade': [f"{trade.id} {trade.target_symbol}/{trade.trading_symbol}" for trade in trades],
+        'Net Gain': [f"{trade.change:.2f} {report.trading_symbol} ({trade.percentage_change:.2f}%)" for trade in trades],
+        'Entry (Price, Date)': [f"{trade.open_price} {trade.opened_at.strftime('%Y-%m-%d %H:%M:%S')}" for trade in trades],
+        'Exit (Price, Date)': [get_exit(trade) for trade in trades],
+        'Duration': [f"{trade.duration:.2f} hours" for trade in trades],
+    }
+    trades_df = pd.DataFrame(selection)
+
+    table_html = (
+        trades_df.style
+        .apply(highlight_net_gain, axis=1)
+        # .apply(highlight_win_loss_ratio, axis=1)
+        .set_table_styles([
+            {'selector': 'th', 'props': [('background-color', '#f2f2f2'), ('font-weight', 'bold')]},
+            {'selector': 'td', 'props': [('font-size', '14px')]},
+            {'selector': 'tr:nth-child(even)', 'props': [('background-color', '#fafafa')]}
+        ])
+        .hide(axis='index')
+        .to_html(classes='display', index=False, table_id='tradesTable')
+    )
+    return table_html

investing_algorithm_framework/app/reporting/tables/utils.py

@@ -0,0 +1,29 @@
+import pandas as pd
+
+
+def safe_format(value, format_str, default_value='N/A'):
+    if value is None:
+        return default_value
+
+    if isinstance(value, (int, float)):
+        return format_str.format(value)
+    return value
+
+
+def safe_format_percentage(value, format_str, default_value='N/A'):
+    if value is None:
+        return default_value
+
+    if isinstance(value, (int, float)):
+        return format_str.format(value * 100)
+
+    return value
+
+
+def safe_format_date(value, format_str, default_value='N/A'):
+    if value is None:
+        return default_value
+
+    if isinstance(value, pd.Timestamp):
+        return value.strftime(format_str)
+    return value

investing_algorithm_framework/app/reporting/templates/report_template.html.j2

@@ -0,0 +1,154 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Aluminium Smelting Strategy Report</title>
+    <style>
+        body {{ '{' }}
+            font-family: Arial, sans-serif;
+            margin: 40px;
+        {{ '}' }}
+        h1 {{ '{' }}
+            color: #333;
+            text-align: center;
+        {{ '}' }}
+        .tab {{ '{' }}
+            overflow: hidden;
+            border-bottom: 1px solid #ccc;
+            margin-bottom: 20px;
+        {{ '}' }}
+        .tab button {{ '{' }}
+            background-color: #f1f1f1;
+            float: left;
+            border: none;
+            outline: none;
+            cursor: pointer;
+            padding: 10px 20px;
+            transition: 0.3s;
+            font-size: 17px;
+        {{ '}' }}
+        .tab button:hover {{ '{' }}
+            background-color: #ddd;
+        {{ '}' }}
+        .tab button.active {{ '{' }}
+            background-color: #ccc;
+        {{ '}' }}
+        .tabcontent {{ '{' }}
+            display: none;
+        {{ '}' }}
+        .tabcontent.active {{ '{' }}
+            display: block;
+        {{ '}' }}
+        .stats-table, .metrics-table {{ '{' }}
+            border-collapse: collapse;
+            width: 50%;
+            margin-top: 20px;
+        {{ '}' }}
+        .stats-table th, .stats-table td {{ '{' }}
+            border: 1px solid #ddd;
+            padding: 8px;
+            text-align: left;
+        {{ '}' }}
+        .stats-table th {{ '{' }}
+            background-color: #f2f2f2;
+        {{ '}' }}
+        .grid-container {{ '{' }}
+            display: flex;
+            gap: 10px;
+            align-items: flex-start;
+            margin-top: 20px;
+        {{ '}' }}
+        .heatmap-cell {{ '{' }}
+            padding: 5px;
+            width: 60%;
+        {{ '}' }}
+        .yearly-returns-cell {{ '{' }}
+            padding: 5px;
+            width: 30%;
+        {{ '}' }}
+        .metrics-table {{ '{' }}
+            padding: 5px;
+        {{ '}' }}
+    </style>
+    <script>
+        function openTab(evt, tabName) {{ '{' }}
+            var i, tabcontent, tablinks;
+            tabcontent = document.getElementsByClassName("tabcontent");
+            for (i = 0; i < tabcontent.length; i++) {{ '{' }}
+                tabcontent[i].classList.remove("active");
+            {{ '}' }}
+            tablinks = document.getElementsByClassName("tablink");
+            for (i = 0; i < tablinks.length; i++) {{ '{' }}
+                tablinks[i].classList.remove("active");
+            {{ '}' }}
+            document.getElementById(tabName).classList.add("active");
+            evt.currentTarget.classList.add("active");
+        {{ '}' }}
+    </script>
+
+    <!-- DataTables CSS -->
+    <link rel="stylesheet" href="https://cdn.datatables.net/1.13.6/css/jquery.dataTables.min.css">
+    <link rel="stylesheet" type="text/css" href="https://cdn.datatables.net/1.13.6/css/jquery.dataTables.min.css"/>
+    <script src="https://code.jquery.com/jquery-3.7.0.min.js"></script>
+    <script src="https://cdn.datatables.net/1.13.6/js/jquery.dataTables.min.js"></script>
+</head>
+<body>
+    <h1>Backtest report: {{ report.name }}</h1>
+
+    <div class="tab">
+        <button class="tablink active" onclick="openTab(event, 'Overview')">Overview</button>
+        <button class="tablink" onclick="openTab(event, 'Trades')">Trades</button>
+        <button class="tablink" onclick="openTab(event, 'Positions and orders')">Positions and Orders</button>
+        <button class="tablink" onclick="openTab(event, 'DataAnalysis')">Data Analysis</button>
+
+    </div>
+
+    <div id="Overview" class="tabcontent active">
+        <div>
+            {{ equity_with_drawdown_plot_html | safe }}
+        </div>
+        <div>
+            {{ rolling_sharpe_ratio_plot_html | safe }}
+        </div>
+        <div class="grid-container">
+            <div class="heatmap-cell">
+                {{ monthly_returns_heatmap_html | safe }}
+            </div>
+            <div class="yearly-returns-cell">
+                {{ yearly_returns_histogram_html | safe }}
+            </div>
+        </div>
+        <div class="grid-container">
+            <div class="metrics-table">
+                <h2>Time Metrics</h2>
+                {{ time_metrics_table_html | safe }}
+            </div>
+            <div class="metrics-table">
+                <h2>Performance Metrics</h2>
+                {{ key_metrics_table_html | safe }}
+            </div>
+            <div class="metrics-table">
+                <h2>Trade Metrics</h2>
+                {{ trades_metrics_table_html | safe }}
+            </div>
+        </div>
+    </div>
+    <div id="Trades" class="tabcontent">
+        {{ trades_table_html | safe }}
+        {% raw %}
+        <script>
+        $(document).ready(function() {
+            $('.stats-table').DataTable({
+                paging: true,
+                pageLength: 10,
+                searching: true
+            });
+        });
+        </script>
+        {% endraw %}
+    </div>
+    <div id="DataAnalysis" class="tabcontent">
+    <h2>OHLCV Data Completeness Charts</h2>
+        {{ data_completeness_charts_html | safe }}
+    </div>
+</body>
+</html>

investing_algorithm_framework/app/stateless/__init__.py

@@ -0,0 +1,35 @@
+from investing_algorithm_framework.app.stateless.action_handlers \
+    import ActionHandler
+from investing_algorithm_framework.app.stateless.action_handlers import \
+    StatelessAction
+from investing_algorithm_framework.app.stateless.exception_handler import \
+    handle_exception
+from investing_algorithm_framework.domain.exceptions import \
+    OperationalException
+
+
+class StatelessHandler:
+
+    def handler(self, payload, algorithm):
+        action = StatelessHandler.get_action_type(payload)
+
+        try:
+            # Handle the action
+            action_handler = ActionHandler.of(StatelessAction
+                                              .from_string(action))
+            return action_handler.handle(payload)
+        except Exception as e:
+            return handle_exception(e)
+
+    @staticmethod
+    def get_action_type(payload):
+
+        if "action" in payload:
+            action = payload["action"]
+        else:
+            action = payload["ACTION"]
+
+        if action is None:
+            raise OperationalException("Action type not supported")
+
+        return action

investing_algorithm_framework/app/stateless/action_handlers/__init__.py

@@ -0,0 +1,84 @@
+from enum import Enum
+
+from investing_algorithm_framework.app.stateless.action_handlers \
+    .check_online_handler import CheckOnlineHandler
+from investing_algorithm_framework.app.stateless.action_handlers \
+    .run_strategy_handler import RunStrategyHandler
+from investing_algorithm_framework.domain.exceptions import \
+    OperationalException
+
+
+class StatelessAction(Enum):
+    RUN_STRATEGY = 'RUN_STRATEGY'
+    PING = "PING"
+
+    @staticmethod
+    def from_value(value: str):
+        if isinstance(value, StatelessAction):
+            for action in StatelessAction:
+
+                if value == action:
+                    return action
+
+        if isinstance(value, str):
+            return StatelessAction.from_string(value)
+
+        raise ValueError("Could not convert value to stateless action")
+
+    @staticmethod
+    def from_string(value: str):
+
+        if isinstance(value, str):
+            for action in StatelessAction:
+
+                if value.upper() == action.value:
+                    return action
+
+        raise ValueError("Could not convert value to stateless action")
+
+    def equals(self, other):
+
+        if isinstance(other, Enum):
+            return self.value == other.value
+
+        else:
+            return StatelessAction.from_string(other) == self
+
+
+class ActionHandler:
+    strategy = None
+
+    @staticmethod
+    def of(payload: dict):
+        action_handler = ActionHandler()
+        action_handler.set_strategy(payload)
+        return action_handler
+
+    def handle(self, payload, context, strategy_orchestrator_service):
+        return self.strategy.handle_event(
+            payload, context, strategy_orchestrator_service
+        )
+
+    def set_strategy(self, payload):
+        action = ActionHandler.get_action_type(payload)
+
+        if StatelessAction.RUN_STRATEGY.equals(action):
+            self.strategy = RunStrategyHandler()
+        elif StatelessAction.PING.equals(action):
+            self.strategy = CheckOnlineHandler()
+        else:
+            raise OperationalException("Action not supported")
+
+    @staticmethod
+    def get_action_type(payload):
+
+        if payload is None or \
+                ("ACTION" not in payload and "action" not in payload):
+            raise OperationalException("Action type is not defined")
+
+        if "action" in payload:
+            action = payload["action"]
+        else:
+            action = payload["ACTION"]
+
+        return action

investing_algorithm_framework/app/stateless/action_handlers/action_handler_strategy.py

@@ -0,0 +1,8 @@
+from abc import ABC, abstractmethod
+
+
+class ActionHandlerStrategy(ABC):
+
+    @abstractmethod
+    def handle_event(self, payload, context, strategy_orchestrator_service):
+        pass

investing_algorithm_framework/app/stateless/action_handlers/check_online_handler.py

@@ -0,0 +1,15 @@
+import json
+
+from investing_algorithm_framework.app.stateless.action_handlers \
+    .action_handler_strategy import ActionHandlerStrategy
+
+
+class CheckOnlineHandler(ActionHandlerStrategy):
+    MESSAGE = {"message": "online"}
+
+    def handle_event(self, payload, context, strategy_orchestrator_service):
+        return {
+            "statusCode": 200,
+            "headers": {"Content-Type": "application/json"},
+            "body": json.dumps(CheckOnlineHandler.MESSAGE)
+        }

investing_algorithm_framework/app/stateless/action_handlers/run_strategy_handler.py

@@ -0,0 +1,40 @@
+import json
+
+from investing_algorithm_framework.app.stateless.action_handlers \
+    .action_handler_strategy import ActionHandlerStrategy
+
+
+class RunStrategyHandler(ActionHandlerStrategy):
+    """
+    RunStrategyHandler is an action handler that runs a strategy and its tasks
+    synchronously.
+
+    If the run was successful, it returns a 200 OK response with a message
+    "OK".
+    """
+    MESSAGE = {"message": "Ok"}
+
+    def handle_event(self, payload, context, strategy_orchestrator_service):
+        strategies = strategy_orchestrator_service\
+            .get_strategies(payload.get("strategies", None))
+        tasks = strategy_orchestrator_service.get_tasks()
+
+        for strategy in strategies:
+            strategy_orchestrator_service.run_strategy(
+                strategy=strategy,
+                context=context,
+                sync=True
+            )
+
+        for task in tasks:
+            strategy_orchestrator_service.run_task(
+                task=task,
+                context=context,
+                sync=True
+            )
+
+        return {
+            "statusCode": 200,
+            "headers": {"Content-Type": "application/json"},
+            "body": json.dumps({"message": RunStrategyHandler.MESSAGE})
+        }

investing_algorithm_framework/app/stateless/exception_handler.py

@@ -0,0 +1,40 @@
+import json
+import logging
+from typing import Dict, List
+
+from investing_algorithm_framework.domain import OperationalException
+
+logger = logging.getLogger("investing_algorithm_framework")
+
+
+def create_error_response(error_message, status_code: int = 400):
+    response = json.dumps({"error_message": error_message})
+    return response, status_code
+
+
+def format_marshmallow_validation_error(errors):
+    errors_message = {}
+
+    for key in errors:
+
+        if isinstance(errors[key], Dict):
+            errors_message[key] = \
+                format_marshmallow_validation_error(errors[key])
+
+        if isinstance(errors[key], List):
+            errors_message[key] = errors[key][0].lower()
+    return errors_message
+
+
+def handle_exception(error):
+    logger.error("exception of type {} occurred".format(type(error)))
+    logger.exception(error)
+
+    if isinstance(error, OperationalException):
+        return error.to_response()
+    else:
+        # Internal error happened that was unknown
+        return {
+            "status": "error",
+            "message": str(error)
+        }