feat: add order metadata with reason tracking

- Add metadata_json column to SQLOrder model with __init__/reconstructor pattern
- Tag orders with reasons (buy_signal, sell_signal, scale_out, stop_loss, take_profit)
- Add metadata support in vector backtest service and trade service
- Add 43 tests across 7 test files for metadata persistence and propagation

Author: MDUYN

investing_algorithm_framework/app/context.py

@@ -161,7 +161,8 @@ def create_limit_order(
         market=None,
         execute=True,
         validate=True,
-        sync=True
+        sync=True,
+        metadata=None
     ) -> Order:
         """
         Function to create a limit order. This function will create a limit
@@ -257,6 +258,9 @@ def create_limit_order(
             "trading_symbol": portfolio.trading_symbol,
         }
 
+        if metadata is not None:
+            order_data["metadata"] = metadata
+
         if BACKTESTING_FLAG in self.configuration_service.config \
                 and self.configuration_service.config[BACKTESTING_FLAG]:
             order_data["created_at"] = \

investing_algorithm_framework/app/strategy.py

@@ -566,7 +566,8 @@ def run_strategy(self, context: Context, data: Dict[str, Any]):
                 price=price,
                 execute=True,
                 validate=True,
-                sync=True
+                sync=True,
+                metadata={"order_reason": "buy_signal"}
             )
 
             # Retrieve and apply stop loss and take profit rules
@@ -637,7 +638,8 @@ def run_strategy(self, context: Context, data: Dict[str, Any]):
                         execute=True,
                         validate=True,
                         sync=True,
-                        price=price
+                        price=price,
+                        metadata={"order_reason": "sell_signal"}
                     )
 
                     # Reset scale-out counter and start cooldown
@@ -683,7 +685,8 @@ def run_strategy(self, context: Context, data: Dict[str, Any]):
                                 execute=True,
                                 validate=True,
                                 sync=True,
-                                price=price
+                                price=price,
+                                metadata={"order_reason": "scale_out"}
                             )
 
                             self._scale_out_counts[symbol] = so_index + 1
@@ -935,7 +938,8 @@ def create_limit_order(
         market=None,
         execute=True,
         validate=True,
-        sync=True
+        sync=True,
+        metadata=None
     ) -> Order:
         """
         Function to create a limit order. This function will create
@@ -981,7 +985,8 @@ def create_limit_order(
             market=market,
             execute=execute,
             validate=validate,
-            sync=sync
+            sync=sync,
+            metadata=metadata
         )
 
     def close_position(

investing_algorithm_framework/infrastructure/models/order/order.py

@@ -1,8 +1,9 @@
+import json
 import logging
 from datetime import datetime, timezone
 
-from sqlalchemy import Column, Integer, String, DateTime, ForeignKey
-from sqlalchemy.orm import relationship
+from sqlalchemy import Column, Integer, String, DateTime, ForeignKey, Text
+from sqlalchemy.orm import relationship, reconstructor
 
 from investing_algorithm_framework.domain import OrderType, \
     OrderSide, Order, OrderStatus
@@ -52,20 +53,41 @@ class SQLOrder(Order, SQLBaseModel, SQLAlchemyModelExtension):
     order_fee_rate = Column(SqliteDecimal(), default=None)
     slippage = Column(SqliteDecimal(), default=None)
     sell_order_metadata_id = Column(Integer, ForeignKey('orders.id'))
+    metadata_json = Column(Text, default=None)
     trade_allocations = relationship(
         'SQLTradeAllocation', back_populates='order'
     )
 
+    def __init__(self, metadata=None, **kwargs):
+        super().__init__(metadata=metadata, **kwargs)
+        # Sync metadata dict to JSON column for DB persistence
+        if self.metadata:
+            self.metadata_json = json.dumps(self.metadata)
+
+    @reconstructor
+    def init_on_load(self):
+        """Deserialize metadata from JSON when loaded from DB."""
+        if self.metadata_json:
+            self.metadata = json.loads(self.metadata_json)
+        else:
+            self.metadata = {}
+
     def update(self, data):
 
+        if "metadata" in data:
+            metadata_val = data.pop("metadata")
+            self.metadata = metadata_val if metadata_val else {}
+            self.metadata_json = json.dumps(self.metadata) \
+                if self.metadata else None
+
         if "status" in data and data["status"] is not None:
             data["status"] = OrderStatus.from_value(data["status"]).value
 
         super().update(data)
 
     @staticmethod
     def from_order(order):
-        return SQLOrder(
+        sql_order = SQLOrder(
             external_id=order.external_id,
             amount=order.get_amount(),
             filled=order.get_filled(),
@@ -78,7 +100,9 @@ def from_order(order):
             trading_symbol=order.get_trading_symbol(),
             created_at=order.get_created_at(),
             updated_at=order.get_updated_at(),
+            metadata=order.metadata,
         )
+        return sql_order
 
     @staticmethod
     def from_ccxt_order(ccxt_order):

investing_algorithm_framework/infrastructure/services/backtesting/vector_backtest_service.py

@@ -270,6 +270,7 @@ def _close_trade(sym, sym_data, price, date):
                 order_fee_rate=tc.fee_percentage / 100
                 if tc.fee_percentage else None,
                 slippage=price - sell_fill,
+                metadata={"order_reason": "sell_signal"},
             )
             orders.append(sell_order)
             trade_orders = lt.orders
@@ -308,6 +309,7 @@ def _close_trade(sym, sym_data, price, date):
                         order_fee_rate=tc.fee_percentage / 100
                         if tc.fee_percentage else None,
                         slippage=price - sell_fill,
+                        metadata={"order_reason": "sell_signal"},
                     )
                     orders.append(sell_o)
                     ot_orders = ot.orders
@@ -330,7 +332,8 @@ def _close_trade(sym, sym_data, price, date):
             sym_data['entry_count'] = 0
             sym_data['scale_out_count'] = 0
 
-        def _open_trade(sym, sym_data, price, date, capital):
+        def _open_trade(sym, sym_data, price, date, capital,
+                       order_reason="buy_signal"):
             """Helper to open a new trade for a symbol."""
             nonlocal current_unallocated, total_allocated
 
@@ -366,6 +369,7 @@ def _open_trade(sym, sym_data, price, date, capital):
                 order_fee_rate=tc.fee_percentage / 100
                 if tc.fee_percentage else None,
                 slippage=fill_price - price,
+                metadata={"order_reason": order_reason},
             )
             orders.append(buy_order)
             trade = Trade(
@@ -468,6 +472,7 @@ def _partial_close(sym, sym_data, price, date, sell_pct):
                 order_fee_rate=tc.fee_percentage / 100
                 if tc.fee_percentage else None,
                 slippage=price - sell_fill,
+                metadata={"order_reason": "scale_out"},
             )
             orders.append(sell_order)
             trade_orders = lt.orders
@@ -669,7 +674,8 @@ def _partial_close(sym, sym_data, price, date, sell_pct):
                         else:
                             _open_trade(
                                 symbol, data, current_price,
-                                current_date, capital
+                                current_date, capital,
+                                order_reason="scale_in"
                             )
                             signal_events.append({
                                 "date": current_date,

investing_algorithm_framework/services/trade_service/trade_service.py

@@ -1004,6 +1004,7 @@ def get_triggered_stop_loss_orders(self):
                     "order_type": OrderType.LIMIT.value,
                     "order_side": OrderSide.SELL.value,
                     "portfolio_id": portfolio_id,
+                    "metadata": {"order_reason": "stop_loss"},
                     "stop_losses": stop_loss_metadata,
                     "trades": [{
                         "trade_id": trade.id,
@@ -1110,6 +1111,7 @@ def get_triggered_take_profit_orders(self):
                     "order_type": OrderType.LIMIT.value,
                     "order_side": OrderSide.SELL.value,
                     "portfolio_id": portfolio_id,
+                    "metadata": {"order_reason": "take_profit"},
                     "take_profits": take_profit_metadata,
                     "trades": [{
                         "trade_id": trade.id,

tests/app/algorithm/test_order_metadata_production.py

@@ -0,0 +1,124 @@
+"""
+Tests for order_reason metadata in the production (live) order path.
+
+Verifies that metadata passed through create_limit_order() in
+non-backtest mode survives the full pipeline:
+  context.create_limit_order(metadata=...) → order_service.create()
+  → SQLOrder(**data) → DB → repository.get() → metadata intact
+"""
+from investing_algorithm_framework import PortfolioConfiguration, \
+    MarketCredential, OrderStatus
+from investing_algorithm_framework.domain import OrderSide
+from tests.resources import TestBase
+
+
+class TestProductionOrderMetadata(TestBase):
+    """
+    Tests for metadata persistence in the production (non-backtest) path.
+    Uses TestBase which sets up a full app with DB, order executor, etc.
+    """
+    portfolio_configurations = [
+        PortfolioConfiguration(
+            market="BITVAVO",
+            trading_symbol="EUR"
+        )
+    ]
+    market_credentials = [
+        MarketCredential(
+            market="BITVAVO",
+            api_key="api_key",
+            secret_key="secret_key"
+        )
+    ]
+    external_balances = {
+        "EUR": 1000
+    }
+
+    def test_create_limit_buy_order_with_metadata(self):
+        """
+        Production path: create_limit_order with metadata → DB → read back.
+        """
+        self.app.context.create_limit_order(
+            target_symbol="BTC",
+            amount=1,
+            price=10,
+            order_side="BUY",
+            metadata={"order_reason": "buy_signal"},
+        )
+        order_repository = self.app.container.order_repository()
+        order = order_repository.find({"target_symbol": "BTC"})
+        self.assertIsNotNone(order)
+        self.assertEqual(
+            order.metadata.get("order_reason"), "buy_signal"
+        )
+
+    def test_create_limit_sell_order_with_metadata(self):
+        """
+        Production path: sell order with sell_signal metadata persisted.
+        Uses order_service.create() which is how SL/TP orders are created.
+        """
+        order_service = self.app.container.order_service()
+        # Create a filled buy first to establish position
+        buy_order = order_service.create({
+            "target_symbol": "BTC",
+            "trading_symbol": "EUR",
+            "amount": 10,
+            "filled": 10,
+            "remaining": 0,
+            "price": 10,
+            "order_side": "BUY",
+            "order_type": "LIMIT",
+            "portfolio_id": 1,
+            "status": "CLOSED",
+        })
+        order_service.check_pending_orders()
+        # Now create sell
+        sell_order = order_service.create({
+            "target_symbol": "BTC",
+            "trading_symbol": "EUR",
+            "amount": 1,
+            "price": 10,
+            "order_side": "SELL",
+            "order_type": "LIMIT",
+            "portfolio_id": 1,
+            "status": "OPEN",
+            "metadata": {"order_reason": "sell_signal"},
+        })
+        self.assertEqual(
+            sell_order.metadata.get("order_reason"), "sell_signal"
+        )
+
+    def test_create_order_without_metadata_returns_empty_dict(self):
+        """
+        Production path: order without metadata has empty dict.
+        """
+        self.app.context.create_limit_order(
+            target_symbol="BTC",
+            amount=1,
+            price=10,
+            order_side="BUY",
+        )
+        order_repository = self.app.container.order_repository()
+        order = order_repository.find({"target_symbol": "BTC"})
+        self.assertEqual(order.metadata, {})
+
+    def test_metadata_with_custom_fields_persists(self):
+        """
+        Production path: arbitrary metadata dict persists through DB.
+        """
+        self.app.context.create_limit_order(
+            target_symbol="BTC",
+            amount=1,
+            price=10,
+            order_side="BUY",
+            metadata={
+                "order_reason": "scale_in",
+                "scale_in_index": 2,
+                "strategy_id": "momentum_v3",
+            },
+        )
+        order_repository = self.app.container.order_repository()
+        order = order_repository.find({"target_symbol": "BTC"})
+        self.assertEqual(order.metadata["order_reason"], "scale_in")
+        self.assertEqual(order.metadata["scale_in_index"], 2)
+        self.assertEqual(order.metadata["strategy_id"], "momentum_v3")