onesecondtrader 0.54.0__py3-none-any.whl → 0.56.0__py3-none-any.whl

onesecondtrader/events/requests/order_submission.py

@@ -14,17 +14,19 @@ class OrderSubmissionRequest(RequestBase):
 
     The `system_order_id` is a unique identifier assigned by the system to the order submission request by default at object creation.
 
-    | Field             | Type                     | Semantics                                                                  |
-    |-------------------|--------------------------|----------------------------------------------------------------------------|
-    | `ts_event_ns`     | `int`                    | Time at which the submission request was issued, as UTC epoch nanoseconds. |
-    | `ts_created_ns`   | `int`                    | Time at which the event object was created, as UTC epoch nanoseconds.      |
-    | `system_order_id` | `uuid.UUID`              | System-assigned unique identifier for the order submission.                |
-    | `symbol`          | `str`                    | Identifier of the traded instrument.                                       |
-    | `order_type`      | `models.OrderType`       | Execution constraint of the order.                                         |
-    | `side`            | `models.TradeSide`       | Direction of the trade.                                                    |
-    | `quantity`        | `float`                  | Requested order quantity.                                                  |
-    | `limit_price`     | `float` or `None`        | Limit price, if applicable to the order type.                              |
-    | `stop_price`      | `float` or `None`        | Stop price, if applicable to the order type.                               |
+    | Field             | Type                       | Semantics                                                                  |
+    |-------------------|----------------------------|----------------------------------------------------------------------------|
+    | `ts_event_ns`     | `int`                      | Time at which the submission request was issued, as UTC epoch nanoseconds. |
+    | `ts_created_ns`   | `int`                      | Time at which the event object was created, as UTC epoch nanoseconds.      |
+    | `system_order_id` | `uuid.UUID`                | System-assigned unique identifier for the order submission.                |
+    | `symbol`          | `str`                      | Identifier of the traded instrument.                                       |
+    | `order_type`      | `models.OrderType`         | Execution constraint of the order.                                         |
+    | `side`            | `models.TradeSide`         | Direction of the trade.                                                    |
+    | `quantity`        | `float`                    | Requested order quantity.                                                  |
+    | `limit_price`     | `float` or `None`          | Limit price, if applicable to the order type.                              |
+    | `stop_price`      | `float` or `None`          | Stop price, if applicable to the order type.                               |
+    | `action`          | `models.ActionType` or `None` | Intent of the order from the strategy's perspective (e.g., entry, exit).   |
+    | `signal`          | `str` or `None`            | Optional signal name or identifier that triggered this order.              |
     """
 
     system_order_id: uuid.UUID = dataclasses.field(default_factory=uuid.uuid4)
@@ -33,3 +35,5 @@ class OrderSubmissionRequest(RequestBase):
     quantity: float
     limit_price: float | None = None
     stop_price: float | None = None
+    action: models.ActionType | None = None
+    signal: str | None = None

onesecondtrader/models/__init__.py

@@ -2,6 +2,7 @@
 Defines the fundamental domain concepts used throughout the trading system.
 """
 
+from .action_types import ActionType
 from .bar_fields import BarField
 from .bar_period import BarPeriod
 from .order_types import OrderType
@@ -13,6 +14,7 @@ from .rejection_reasons import (
 from .trade_sides import TradeSide
 
 __all__ = [
+    "ActionType",
     "BarField",
     "BarPeriod",
     "OrderType",

onesecondtrader/models/action_types.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import enum
+
+
+class ActionType(enum.Enum):
+    """
+    Enumeration of trading action types.
+
+    `ActionType` specifies the intent or purpose of an order from the strategy's perspective,
+    describing what the order is meant to accomplish in terms of position management.
+
+    | Value         | Semantics                                                                  |
+    |---------------|----------------------------------------------------------------------------|
+    | `ENTRY`       | Opens a new position (direction-agnostic).                                 |
+    | `ENTRY_LONG`  | Opens a new long position.                                                 |
+    | `ENTRY_SHORT` | Opens a new short position.                                                |
+    | `EXIT`        | Closes an existing position (direction-agnostic).                          |
+    | `EXIT_LONG`   | Closes an existing long position.                                          |
+    | `EXIT_SHORT`  | Closes an existing short position.                                         |
+    | `ADD`         | Increases the size of an existing position.                                |
+    | `REDUCE`      | Decreases the size of an existing position without fully closing it.       |
+    | `REVERSE`     | Closes the current position and opens a new one in the opposite direction. |
+    """
+
+    ENTRY = enum.auto()
+    ENTRY_LONG = enum.auto()
+    ENTRY_SHORT = enum.auto()
+    EXIT = enum.auto()
+    EXIT_LONG = enum.auto()
+    EXIT_SHORT = enum.auto()
+    ADD = enum.auto()
+    REDUCE = enum.auto()
+    REVERSE = enum.auto()

onesecondtrader/orchestrator/__init__.py

@@ -0,0 +1,8 @@
+"""
+Orchestrates the execution of a trading run and records all events to a SQLite database.
+"""
+
+from .orchestrator import Orchestrator
+from .run_recorder import RunRecorder
+
+__all__ = ["Orchestrator", "RunRecorder"]

onesecondtrader/orchestrator/orchestrator.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import pathlib
+
+import dotenv
+import pandas as pd
+
+from onesecondtrader import messaging, models
+from onesecondtrader.brokers.base import BrokerBase
+from onesecondtrader.datafeeds.base import DatafeedBase
+from onesecondtrader.strategies.base import StrategyBase
+from .run_recorder import RunRecorder
+
+
+class Orchestrator:
+    """
+    Orchestrates the execution of a trading run.
+
+    The orchestrator instantiates strategies, broker, datafeed, and recorder components,
+    connects them via an event bus, and coordinates the run lifecycle from start to shutdown.
+    """
+
+    db_path: str = "runs.db"
+    mode: str = "backtest"
+
+    def __init__(
+        self,
+        strategies: list[type[StrategyBase]],
+        broker: type[BrokerBase],
+        datafeed: type[DatafeedBase],
+    ) -> None:
+        """
+        Initialize the orchestrator with component classes.
+
+        Parameters:
+            strategies:
+                List of strategy classes to instantiate for the run.
+            broker:
+                Broker class to instantiate for order execution.
+            datafeed:
+                Datafeed class to instantiate for market data delivery.
+        """
+        dotenv.load_dotenv()
+        self._strategy_classes = strategies
+        self._broker_class = broker
+        self._datafeed_class = datafeed
+        self._event_bus: messaging.EventBus | None = None
+        self._strategies: list[StrategyBase] = []
+        self._broker: BrokerBase | None = None
+        self._datafeed: DatafeedBase | None = None
+        self._recorder: RunRecorder | None = None
+
+    def run(self) -> None:
+        """
+        Execute the trading run.
+
+        Creates all components, connects them, subscribes to symbols, waits for
+        the datafeed to complete, and then shuts down all components.
+        """
+        run_id = self._generate_run_id()
+
+        self._event_bus = messaging.EventBus()
+
+        self._recorder = self._create_recorder(run_id)
+        self._broker = self._broker_class(self._event_bus)
+        self._strategies = [s(self._event_bus) for s in self._strategy_classes]
+        self._datafeed = self._datafeed_class(self._event_bus)
+
+        try:
+            self._broker.connect()
+            self._datafeed.connect()
+            self._subscribe_symbols()
+            self._datafeed.wait_until_complete()
+            self._event_bus.wait_until_system_idle()
+            self._recorder.update_run_status(
+                "completed", pd.Timestamp.now(tz="UTC").value
+            )
+        except Exception:
+            if self._recorder:
+                self._recorder.update_run_status(
+                    "failed", pd.Timestamp.now(tz="UTC").value
+                )
+            raise
+        finally:
+            self._shutdown()
+
+    def _generate_run_id(self) -> str:
+        """
+        Generate a unique run identifier.
+
+        Returns:
+            A string combining the current UTC timestamp and strategy names.
+        """
+        timestamp = pd.Timestamp.now(tz="UTC").strftime("%Y-%m-%d_%H-%M-%S")
+        strategy_names = "_".join(s.name for s in self._strategy_classes)
+        return f"{timestamp}_{strategy_names}"
+
+    def _collect_symbols(self) -> list[str]:
+        """
+        Collect all unique symbols from the strategy classes.
+
+        Returns:
+            A deduplicated list of symbols from all strategies.
+        """
+        symbols = []
+        for strategy_class in self._strategy_classes:
+            symbols.extend(strategy_class.symbols)
+        return list(set(symbols))
+
+    def _create_recorder(self, run_id: str) -> RunRecorder:
+        """
+        Create and return a RunRecorder instance for this run.
+
+        Parameters:
+            run_id:
+                Unique identifier for this run.
+
+        Returns:
+            A configured RunRecorder instance.
+        """
+        assert self._event_bus is not None
+        config = {
+            "mode": self.mode,
+            "symbols": self._collect_symbols(),
+            "strategies": [s.name for s in self._strategy_classes],
+        }
+        return RunRecorder(
+            event_bus=self._event_bus,
+            db_path=pathlib.Path(self.db_path),
+            run_id=run_id,
+            name="_".join(s.name for s in self._strategy_classes),
+            config=config,
+        )
+
+    def _subscribe_symbols(self) -> None:
+        """
+        Subscribe the datafeed to symbols for each strategy's bar period.
+        """
+        assert self._datafeed is not None
+        subscriptions: dict[models.BarPeriod, list[str]] = {}
+        for strategy_class in self._strategy_classes:
+            bar_period_value = strategy_class.parameters["bar_period"].default
+            assert isinstance(bar_period_value, models.BarPeriod)
+            if bar_period_value not in subscriptions:
+                subscriptions[bar_period_value] = []
+            subscriptions[bar_period_value].extend(strategy_class.symbols)
+        for bar_period, symbols in subscriptions.items():
+            self._datafeed.subscribe(list(set(symbols)), bar_period)
+
+    def _shutdown(self) -> None:
+        """
+        Shut down all components in the correct order.
+        """
+        if self._datafeed:
+            self._datafeed.disconnect()
+        if self._broker:
+            self._broker.disconnect()
+        for strategy in self._strategies:
+            strategy.shutdown()
+        if self._recorder:
+            self._recorder.shutdown()