onesecondtrader 0.13.1__tar.gz → 0.14.1__tar.gz

{onesecondtrader-0.13.1 → onesecondtrader-0.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: onesecondtrader
-Version: 0.13.1
+Version: 0.14.1
 Summary: The Trading Infrastructure Toolkit for Python. Research, simulate, and deploy algorithmic trading strategies — all in one place.
 License-File: LICENSE
 Author: Nils P. Kujath

{onesecondtrader-0.13.1 → onesecondtrader-0.14.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "onesecondtrader"
-version = "0.13.1"
+version = "0.14.1"
 description = "The Trading Infrastructure Toolkit for Python. Research, simulate, and deploy algorithmic trading strategies — all in one place."
 authors = [
     {name = "Nils P. Kujath",email = "63961429+NilsKujath@users.noreply.github.com"}

onesecondtrader-0.14.1/src/onesecondtrader/brokers/base_broker.py

@@ -0,0 +1,99 @@
+import abc
+from onesecondtrader import messaging
+from onesecondtrader.messaging import events
+
+
+class BaseBroker(abc.ABC):
+    def __init__(self, event_bus: messaging.EventBus | None = None):
+        self.event_bus: messaging.EventBus = (
+            event_bus if event_bus else messaging.system_event_bus
+        )
+        self._is_connected: bool = False
+
+    def connect(self) -> bool:
+        if self._is_connected:
+            return True
+        self._subscribe_to_events()
+        self._is_connected = True
+        return True
+
+    def disconnect(self) -> None:
+        if not self._is_connected:
+            return
+        try:
+            self.event_bus.unsubscribe(events.System.Shutdown, self.on_system_shutdown)
+        finally:
+            self._is_connected = False
+
+    @property
+    def is_connected(self) -> bool:
+        return self._is_connected
+
+    def _subscribe_to_events(self) -> None:
+        """
+        Subscribe to relevant events from the event bus.
+        """
+        self.event_bus.subscribe(events.System.Shutdown, self.on_system_shutdown)
+        self.event_bus.subscribe(events.Strategy.SymbolRelease, self.on_symbol_release)
+
+    def on_system_shutdown(self, event: events.Base.Event) -> None:
+        """
+        Handle system shutdown events (ignore unrelated events).
+        """
+        if not isinstance(event, events.System.Shutdown):
+            return
+        # Default no-op
+        return
+
+    def on_symbol_release(self, event: events.Base.Event) -> None:
+        """
+        Handle portfolio symbol release events (ignore unrelated events).
+        Intended for brokers to perform any symbol-specific cleanup if necessary.
+        Default implementation is a no-op.
+        """
+        if not isinstance(event, events.Strategy.SymbolRelease):
+            return
+        # Default no-op
+        return
+
+    def on_request_market_order(self, event: events.Request.MarketOrder) -> None:
+        """
+        Handle market order requests.
+        """
+        pass
+
+    def on_request_limit_order(self, event: events.Request.LimitOrder) -> None:
+        """
+        Handle limit order requests.
+        """
+        pass
+
+    def on_request_stop_order(self, event: events.Request.StopOrder) -> None:
+        """
+        Handle stop order requests.
+        """
+        pass
+
+    def on_request_stop_limit_order(self, event: events.Request.StopLimitOrder) -> None:
+        """
+        Handle stop limit order requests.
+        """
+        pass
+
+    def on_request_cancel_order(self, event: events.Request.CancelOrder) -> None:
+        """
+        Handle cancel order requests.
+        """
+        pass
+
+    def on_request_flush_symbol(self, event: events.Request.FlushSymbol) -> None:
+        """
+        Handle flush symbol requests.
+        """
+        pass
+
+    def on_request_flush_all(self, event: events.Request.FlushAll) -> None:
+        """
+        Handle flush all requests.
+        """
+        pass

onesecondtrader-0.14.1/src/onesecondtrader/brokers/simulated_broker.py

@@ -0,0 +1,10 @@
+from onesecondtrader.brokers import base_broker
+
+
+class SimulatedBroker(base_broker.BaseBroker):
+    """
+    Simple simulated broker used as a safe default.
+    """
+
+    def __init__(self, event_bus=None):
+        super().__init__(event_bus)

{onesecondtrader-0.13.1 → onesecondtrader-0.14.1}/src/onesecondtrader/core/models.py

@@ -2,26 +2,6 @@ from dataclasses import dataclass
 import enum
 
 
-class BrokerType(enum.Enum):
-    """
-    Enum for broker types.
-
-    **Attributes:**
-
-    | Enum | Value | Description |
-    |------|-------|-------------|
-    | `LOCAL_SIMULATED` | `enum.auto()` | Locally simulated broker |
-    | `IB_SIMULATED` | `enum.auto()` | Interactive Brokers paper trading account |
-    | `IB_LIVE` | `enum.auto()` | Interactive Brokers live trading account |
-    | `MT5` | `enum.auto()` | MetaTrader 5 |
-    """
-
-    LOCAL_SIMULATED = enum.auto()
-    IB_SIMULATED = enum.auto()
-    IB_LIVE = enum.auto()
-    MT5 = enum.auto()
-
-
 @dataclass(frozen=True, slots=True)
 class Bar:
     """
@@ -101,8 +81,8 @@ class OrderLifecycleState(enum.Enum):
 
     | Enum | Value | Description |
     |------|-------|-------------|
-    | `PENDING` | `enum.auto()` | Order has been submitted, but not yet acknowledged by the broker |
-    | `OPEN` | `enum.auto()` | Order has been acknowledged by the broker, but not yet filled or cancelled |
+    | `PENDING` | `enum.auto()` | Order has been submitted, but not yet acknowledged by the brokers |
+    | `OPEN` | `enum.auto()` | Order has been acknowledged by the brokers, but not yet filled or cancelled |
     | `FILLED` | `enum.auto()` | Order has been filled |
     | `CANCELLED` | `enum.auto()` | Order has been cancelled |
     """
@@ -186,3 +166,23 @@ class XMAMode(enum.Enum):
     CLOSE = enum.auto()
     TYPICAL_PRICE = enum.auto()
     WEIGHTED_CLOSE = enum.auto()
+
+
+class Position:
+    pass
+
+
+class StrategyShutdownMode(enum.Enum):
+    """
+    Enum for strategy shutdown modes.
+
+    **Attributes:**
+
+    | Enum | Value | Description |
+    |------|-------|-------------|
+    | `SOFT` | `enum.auto()` | Do not open new positions; wait until current positions close naturally |
+    | `HARD` | `enum.auto()` | Close all positions immediately with market orders |
+    """
+
+    SOFT = enum.auto()
+    HARD = enum.auto()

onesecondtrader-0.14.1/src/onesecondtrader/core/portfolio.py

@@ -0,0 +1,348 @@
+"""
+This module provides the Portfolio class.
+"""
+
+import threading
+from collections.abc import Iterable
+from onesecondtrader import messaging
+from onesecondtrader.messaging import events
+from onesecondtrader.monitoring import console
+from onesecondtrader.brokers import base_broker
+from onesecondtrader.strategies import base_strategy
+from onesecondtrader.core.models import StrategyShutdownMode
+
+
+class Portfolio:
+    """
+    The Portfolio class orchestrates the trading infrastructure's components.
+    It manages the broker connection, market data reception, and strategy execution.
+
+    Multiple instances of the same Strategy class can be registered concurrently.
+    Symbol ownership is exclusive and enforced by the portfolio: each symbol may be
+    owned by at most one strategy instance at a time. Use `add_strategy()` with a list
+    of symbols or `assign_symbols(...)` with a specific strategy and a list of symbols
+    to claim symbols; `owner_of(symbol)` returns the current owner.
+    """
+
+    def __init__(
+        self,
+        event_bus: messaging.EventBus | None = None,
+        broker_class: type[base_broker.BaseBroker] | None = None,
+    ):
+        """
+        Initialize the Portfolio class, subscribe to events, and connect to the broker.
+
+        Args:
+            event_bus (EventBus | None): Event bus to use; defaults to
+                system_event_bus when None.
+            broker_class (type[base_broker.BaseBroker] | None): Broker class to
+                instantiate and connect. Must be a subclass of BaseBroker.
+
+        Attributes:
+            self.event_bus (eventbus.EventBus): Event bus used for communication between
+                the trading infrastructure's components.
+            self._lock (threading.Lock): Lock for thread-safe operations.
+            self._strategies (set[base_strategy.Strategy]): Registered strategy
+                instances.
+            self._symbol_owner (dict[str, base_strategy.Strategy]): Exclusive symbol
+                ownership map; each symbol is owned by at most one strategy instance at
+                a time.
+            self._removal_pending (set[base_strategy.Strategy]): Set of strategies that
+                are still active but marked for removal once all symbols are released.
+            self.broker (base_broker.BaseBroker | None): Instantiated broker; may be
+                disconnected if connect failed.
+        """
+        # INITIALIZE EVENT BUS
+        # ------------------------------------------------------------------------------
+        self.event_bus: messaging.EventBus = (
+            event_bus if event_bus else messaging.system_event_bus
+        )
+
+        # SUBSCRIBE HANDLER METHODS TO EVENTS VIA event_bus.subscribe
+        # ------------------------------------------------------------------------------
+        self.event_bus.subscribe(events.Strategy.SymbolRelease, self.on_symbol_release)
+
+        # INITIALIZE LOCK FOR THREAD-SAFE OPERATIONS WITHIN THE PORTFOLIO
+        # ------------------------------------------------------------------------------
+        self._lock = threading.Lock()
+
+        # KEEP TRACK OF STRATEGIES AND SYMBOL OWNERSHIP
+        # ------------------------------------------------------------------------------
+        self._strategies: set[base_strategy.Strategy] = set()
+        self._symbol_owner: dict[str, base_strategy.Strategy] = {}
+        self._removal_pending: set[base_strategy.Strategy] = set()
+
+        # INITIALIZE BROKER
+        # ------------------------------------------------------------------------------
+        self.broker: base_broker.BaseBroker | None = None
+        if broker_class is None or not issubclass(broker_class, base_broker.BaseBroker):
+            broker_name = (
+                getattr(broker_class, "__name__", str(broker_class))
+                if broker_class
+                else None
+            )
+            console.logger.error(
+                "Portfolio requires a valid broker_class (subclass of BaseBroker), "
+                f"got {broker_name}"
+            )
+            return
+        try:
+            self.broker = broker_class(self.event_bus)
+        except Exception as e:
+            console.logger.error(
+                f"Failed to instantiate broker "
+                f"{getattr(broker_class, '__name__', str(broker_class))}: {e}"
+            )
+            return
+
+        # CONNECT TO BROKER
+        # ------------------------------------------------------------------------------
+        try:
+            connected = self.broker.connect()
+            if not connected:
+                console.logger.error(
+                    f"Failed to connect broker {type(self.broker).__name__}"
+                )
+        except Exception as e:
+            console.logger.error(f"Broker connect failed: {e}")
+
+    def add_strategy(
+        self,
+        strategy_instance: base_strategy.Strategy,
+        symbols: Iterable[str] | None = None,
+    ) -> bool:
+        """
+        Register a Strategy instance and optionally assign a list of symbols to it.
+
+        If symbols are provided, potential conflicts are checked first under a lock.
+        If any conflicts exist, no symbols are assigned; a warning is logged listing
+        both non_conflicting and conflicting symbols and instructions to use
+        assign_symbols(...) are provided.
+        If no conflicts exist, all provided symbols are claimed by the strategy.
+
+        Args:
+            strategy_instance (base_strategy.Strategy): Strategy instance to register.
+            symbols (Iterable[str] | None): Optional list of symbols to assign to the
+                strategy.
+
+        Returns:
+            bool: True if the strategy was registered, False otherwise.
+        """
+        # VALIDATE THAT INSTANCE IS A SUBCLASS OF base_strategy.Strategy
+        # ------------------------------------------------------------------------------
+        if not isinstance(strategy_instance, base_strategy.Strategy):
+            console.logger.error("add_strategy: strategy must inherit from Strategy")
+            return False
+
+        # ADD STRATEGY INSTANCE TO REGISTRY IF NOT ALREADY REGISTERED
+        # ------------------------------------------------------------------------------
+        with self._lock:
+            if strategy_instance in self._strategies:
+                console.logger.warning("add_strategy: strategy already registered")
+                return False
+            self._strategies.add(strategy_instance)
+
+        # ASSIGN SYMBOLS IF PROVIDED AND NO CONFLICTS EXIST, ELSE LOG WARNING
+        # ------------------------------------------------------------------------------
+        if symbols is not None:
+            # Create an ordered list of unique, non-empty, trimmed symbols
+            symbols_list = list(
+                dict.fromkeys(s.strip() for s in symbols if s and s.strip())
+            )
+
+            # Check for conflicts, claim symbols for strategy if no conflicts arise
+            if symbols_list:
+                non_conflicting: list[str] = []
+                conflicting: list[str] = []
+                with self._lock:
+                    for sym in symbols_list:
+                        owner = self._symbol_owner.get(sym)
+                        if owner is None or owner is strategy_instance:
+                            non_conflicting.append(sym)
+                        else:
+                            conflicting.append(sym)
+                if conflicting:
+                    console.logger.warning(
+                        "add_strategy: symbols not assigned due to conflicts; "
+                        "use Portfolio.assign_symbols(...) after resolving. "
+                        f"non_conflicting={non_conflicting}, conflicts={conflicting}"
+                    )
+                else:
+                    self.assign_symbols(strategy_instance, symbols_list)
+        return True
+
+    def remove_strategy(
+        self,
+        strategy: base_strategy.Strategy,
+        shutdown_mode: StrategyShutdownMode = StrategyShutdownMode.SOFT,
+    ) -> bool:
+        """
+        Mark a strategy for removal and request it to close its positions in the manner
+        dictated via the `shutdown_mode` argument (default to soft shutdown, i.e. wait
+        for open positions to close naturally and release symbols once they are flat).
+
+        Args:
+            strategy (base_strategy.Strategy): Strategy instance to remove.
+            shutdown_mode (StrategyShutdownMode): Shutdown mode to use. Defaults to
+                StrategyShutdownMode.SOFT.
+        """
+
+        # IF STRATEGY IS REGISTERED, MARK IT FOR REMOVAL
+        # ------------------------------------------------------------------------------
+        with self._lock:
+            if strategy not in self._strategies:
+                console.logger.warning("remove_strategy: strategy not registered")
+                return False
+            self._removal_pending.add(strategy)
+
+        try:
+            strategy.request_close(shutdown_mode)
+        except Exception:
+            console.logger.warning(
+                "remove_strategy: strategy does not support request_close; proceeding to flatness check"
+            )
+
+        try:
+            if bool(strategy.is_flat()):
+                # If the strategy is already flat and owns no symbols, deregister now
+                with self._lock:
+                    has_owned_left = any(
+                        owner is strategy for owner in self._symbol_owner.values()
+                    )
+                    if not has_owned_left:
+                        if strategy in self._strategies:
+                            self._strategies.remove(strategy)
+                        self._removal_pending.discard(strategy)
+                        console.logger.info(
+                            f"Strategy {getattr(strategy, 'name', type(strategy).__name__)} removed: flat and no symbols owned"
+                        )
+                        return True
+        except Exception:
+            console.logger.warning(
+                "remove_strategy: strategy does not implement is_flat; will wait for symbol releases"
+            )
+        return False
+
+    def assign_symbols(
+        self,
+        strategy: base_strategy.Strategy,
+        symbols: Iterable[str],
+    ) -> tuple[list[str], list[str]]:
+        """
+        Assign symbols to a strategy with exclusivity enforcement.
+
+        Returns:
+            tuple[list[str], list[str]]: (accepted, conflicts)
+        """
+        if not isinstance(strategy, base_strategy.Strategy):
+            console.logger.error("assign_symbols: strategy must inherit from Strategy")
+            return [], list(symbols)
+        symbols_list = list(
+            dict.fromkeys(s.strip() for s in symbols if s and s.strip())
+        )
+        if not symbols_list:
+            return [], []
+        accepted: list[str] = []
+        conflicts: list[str] = []
+        with self._lock:
+            for sym in symbols_list:
+                current = self._symbol_owner.get(sym)
+                if current is None or current is strategy:
+                    self._symbol_owner[sym] = strategy
+                    accepted.append(sym)
+                else:
+                    conflicts.append(sym)
+        if accepted:
+            strategy.add_symbols(accepted)
+        if conflicts:
+            console.logger.warning(
+                f"assign_symbols: conflicts for {len(conflicts)} symbol(s): {conflicts}"
+            )
+        return accepted, conflicts
+
+    def unassign_symbols(
+        self, strategy: base_strategy.Strategy, symbols: Iterable[str]
+    ) -> list[str]:
+        """
+        Release symbol ownership from a strategy.
+
+        Returns:
+            list[str]: Symbols actually unassigned.
+        """
+        if not isinstance(strategy, base_strategy.Strategy):
+            console.logger.error(
+                "unassign_symbols: strategy must inherit from Strategy"
+            )
+            return []
+        symbols_list = list(
+            dict.fromkeys(s.strip() for s in symbols if s and s.strip())
+        )
+        if not symbols_list:
+            return []
+        removed: list[str] = []
+        with self._lock:
+            for sym in symbols_list:
+                if self._symbol_owner.get(sym) is strategy:
+                    del self._symbol_owner[sym]
+                    removed.append(sym)
+        if removed:
+            strategy.remove_symbols(removed)
+        return removed
+
+    def owner_of(self, symbol: str) -> base_strategy.Strategy | None:
+        """
+        Return the owning strategy for a symbol or None if unowned.
+        """
+        with self._lock:
+            return self._symbol_owner.get(symbol)
+
+    def release_symbols_from_strategy(
+        self, strategy: base_strategy.Strategy, symbols: Iterable[str]
+    ) -> list[str]:
+        """
+        Release symbols from the given strategy.
+
+        If the strategy was previously marked for removal and ends up with no owned
+        symbols after this call, and the strategy is flat, it will be automatically
+        deregistered.
+        """
+        removed = self.unassign_symbols(strategy, symbols)
+        if not removed:
+            return removed
+        # Auto-deregister if pending removal and no more owned symbols
+        pending = False
+        with self._lock:
+            pending = strategy in self._removal_pending
+            has_owned_left = any(
+                owner is strategy for owner in self._symbol_owner.values()
+            )
+        if pending and not has_owned_left:
+            try:
+                if bool(strategy.is_flat()):
+                    with self._lock:
+                        if strategy in self._strategies:
+                            self._strategies.remove(strategy)
+                        self._removal_pending.discard(strategy)
+                    console.logger.info(
+                        f"Strategy {getattr(strategy, 'name', type(strategy).__name__)} removed: all symbols released and flat"
+                    )
+            except Exception:
+                pass
+        return removed
+
+    def on_symbol_release(self, event: events.Base.Event) -> None:
+        """
+        Handle symbol release events. Ignores unrelated event types.
+        """
+        if not isinstance(event, events.Strategy.SymbolRelease):
+            return
+        strategy = event.strategy
+        with self._lock:
+            if strategy not in self._strategies:
+                console.logger.warning("on_symbol_release: strategy not registered")
+                return
+        removed = self.release_symbols_from_strategy(strategy, [event.symbol])
+        if not removed:
+            console.logger.warning(
+                f"on_symbol_release: symbol {event.symbol} not owned by {getattr(event.strategy, 'name', type(event.strategy).__name__)}"
+            )

{onesecondtrader-0.13.1 → onesecondtrader-0.14.1}/src/onesecondtrader/datafeeds/base_datafeed.py

@@ -12,14 +12,10 @@ class BaseDatafeed(abc.ABC):
     Base class for all datafeeds.
     """
 
-    def __init__(self, event_bus: messaging.EventBus):
-        """
-        Initialize the datafeed with an event bus.
-
-        Args:
-            event_bus (messaging.EventBus): Event bus to publish market data events to.
-        """
-        self.event_bus: messaging.EventBus = event_bus
+    def __init__(self, event_bus: messaging.EventBus | None = None):
+        self.event_bus: messaging.EventBus = (
+            event_bus if event_bus else messaging.system_event_bus
+        )
 
     @abc.abstractmethod
     def connect(self):

{onesecondtrader-0.13.1 → onesecondtrader-0.14.1}/src/onesecondtrader/messaging/__init__.py

@@ -1,8 +1,9 @@
-from .eventbus import EventBus as EventBus
+from .eventbus import EventBus as EventBus, system_event_bus as system_event_bus
 from .events import (
     Base as Base,
     Market as Market,
     Request as Request,
     Response as Response,
     System as System,
+    Strategy as Strategy,
 )

{onesecondtrader-0.13.1 → onesecondtrader-0.14.1}/src/onesecondtrader/messaging/eventbus.py

@@ -12,6 +12,12 @@ from onesecondtrader.messaging import events
 from onesecondtrader.monitoring import console
 
 
+__all__ = [
+    "EventBus",
+    "system_event_bus",
+]
+
+
 class EventBus:
     # noinspection PyTypeChecker
     """
@@ -488,3 +494,6 @@ class EventBus:
                 f"total handlers: "
                 f"{sum(len(handlers) for handlers in new_cache.values())}"
             )
+
+
+system_event_bus = EventBus()

{onesecondtrader-0.13.1 → onesecondtrader-0.14.1}/src/onesecondtrader/messaging/events.py

@@ -1,8 +1,8 @@
 """
 This module provides the event messages used for decoupled communication between the
  trading infrastructure's components.
-Events are organized into namespaces (`Market`, `Request`, `Response`, and `System`)
- to provide clear semantic groupings.
+Events are organized into namespaces (`Strategy`, `Market`, `Request`, `Response`, and
+`System`) to provide clear semantic groupings.
 Base event messages used for structure inheritance are grouped under the
  `Base` namespace.
 Dataclass field validation logic is grouped under the `_Validate` namespace.
@@ -23,11 +23,13 @@ Dataclass field validation logic is grouped under the `_Validate` namespace.
     R22[events.Base.CancelRequest]
     R3[events.Base.Response]
     R4[events.Base.System]
+    R5[events.Base.Strategy]
 
     R --> R1
     R --> R2
     R --> R3
     R --> R4
+    R --> R5
 
     R2 --> R21
     R2 --> R22
@@ -83,6 +85,14 @@ Dataclass field validation logic is grouped under the `_Validate` namespace.
 
     style D1 fill:#6F42C1,fill-opacity:0.3
 
+    E1[events.Strategy.SymbolRelease]
+    E2[events.Strategy.StopTrading]
+
+    R5 --> E1
+    R5 --> E2
+
+    style E1 fill:#6F42C1,fill-opacity:0.3
+    style E2 fill:#6F42C1,fill-opacity:0.3
 
     subgraph Market ["Market Update Event Messages"]
         R1
@@ -143,6 +153,18 @@ Dataclass field validation logic is grouped under the `_Validate` namespace.
             D1
         end
 
+    end
+
+    subgraph Strategy ["Strategy Coord. Event Messages"]
+        R5
+        E1
+        E2
+
+        subgraph StrategyNamespace ["events.Strategy Namespace"]
+            E1
+            E2
+        end
+
     end
     ```
 """
@@ -153,6 +175,7 @@ import re
 import uuid
 from onesecondtrader.core import models
 from onesecondtrader.monitoring import console
+from onesecondtrader.strategies import base_strategy
 
 
 class Base:
@@ -280,7 +303,7 @@ class Base:
             )
             _Validate.quantity(self.quantity, f"Order {self.order_id}")
 
-            if self.time_in_force.value == 4:
+            if self.time_in_force is models.TimeInForce.GTD:
                 if self.order_expiration is None:
                     console.logger.error(
                         f"Order {self.order_id}: GTD order missing expiration "
@@ -345,6 +368,36 @@ class Base:
                 )
             return super().__new__(cls)
 
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class Strategy(Event):
+        """
+        Base event message dataclass for strategy coordination messages.
+        This dataclass cannot be instantiated directly.
+
+        Attributes:
+            ts_event: Timestamp of the event. (defaults to current UTC time;
+                auto-generated)
+        """
+
+        ts_event: pd.Timestamp = dataclasses.field(
+            default_factory=lambda: pd.Timestamp.now(tz="UTC")
+        )
+        strategy: base_strategy.Strategy
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.Strategy:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+        def __post_init__(self) -> None:
+            super().__post_init__()
+            if not isinstance(self.strategy, base_strategy.Strategy):
+                console.logger.error(
+                    f"{type(self).__name__}: strategy must inherit from Strategy"
+                )
+
 
 class Market:
     """
@@ -374,7 +427,7 @@ class Market:
             ...         volume=10000,
             ...     ),
             ... )
-            ```
+
         """
 
         bar: models.Bar
@@ -621,7 +674,7 @@ class Response:
 
             gross_value = self.filled_at_price * self.quantity_filled
 
-            if self.side.value == 1:
+            if self.side is models.Side.BUY:
                 net_value = gross_value + self.commission_and_fees
             else:
                 net_value = gross_value - self.commission_and_fees
@@ -699,6 +752,51 @@ class System:
         pass
 
 
+class Strategy:
+    """
+    Namespace for strategy coordination event messages.
+    """
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class SymbolRelease(Base.Strategy):
+        """
+        Event to indicate a strategy releases ownership of a symbol.
+
+        Attributes:
+            symbol (str): Symbol released.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Strategy.SymbolRelease(
+            ...     symbol="AAPL",
+            ... )
+        """
+
+        symbol: str
+
+        def __post_init__(self) -> None:
+            super().__post_init__()
+            _Validate.symbol(self.symbol, "Strategy.SymbolRelease")
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class StopTrading(Base.Strategy):
+        """
+        Event to indicate a strategy should stop trading.
+
+        Attributes:
+            shutdown_mode (models.StrategyShutdownMode): Shutdown mode to use.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Strategy.StopTrading(
+            ...     strategy=my_strategy,
+            ...     shutdown_mode=models.StrategyShutdownMode.SOFT,
+            ... )
+        """
+
+        shutdown_mode: models.StrategyShutdownMode
+
+
 class _Validate:
     """Internal validation utilities for events."""
 

onesecondtrader-0.14.1/src/onesecondtrader/strategies/base_strategy.py

@@ -0,0 +1,46 @@
+import abc
+import threading
+from onesecondtrader.messaging.eventbus import EventBus, system_event_bus
+from onesecondtrader.core import models
+
+
+class Strategy(abc.ABC):
+    def __init__(self, name: str, event_bus: EventBus | None = None):
+        self.name = name
+        self.event_bus = event_bus if event_bus else system_event_bus
+        self._lock = threading.Lock()
+        self._active_symbols: set[str] = set()
+        self._close_only_symbols: set[str] = set()
+        self._close_open_positions_only: bool = False
+        self._close_mode: models.StrategyShutdownMode | None = None
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(name='{self.name}')"
+
+    def request_close(
+        self, mode: models.StrategyShutdownMode = models.StrategyShutdownMode.SOFT
+    ) -> None:
+        # Minimalist soft/hard close signalling; subclasses act on this
+        self._close_open_positions_only = True
+        self._close_mode = mode
+
+    @abc.abstractmethod
+    def is_flat(self) -> bool:
+        raise NotImplementedError
+
+    def add_symbols(self, symbols: list[str]) -> None:
+        """
+        Add symbols to the strategy. Thread-safe and idempotent.
+        """
+        clean = [s.strip() for s in symbols if s and s.strip()]
+        with self._lock:
+            self._active_symbols.update(clean)
+
+    def remove_symbols(self, symbols: list[str]) -> None:
+        """
+        Remove symbols from the strategy. Thread-safe and idempotent.
+        """
+        clean = [s.strip() for s in symbols if s and s.strip()]
+        with self._lock:
+            for sym in clean:
+                self._active_symbols.discard(sym)