onesecondtrader 0.14.0__tar.gz → 0.14.2__tar.gz

{onesecondtrader-0.14.0 → onesecondtrader-0.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: onesecondtrader
-Version: 0.14.0
+Version: 0.14.2
 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.14.0 → onesecondtrader-0.14.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "onesecondtrader"
-version = "0.14.0"
+version = "0.14.2"
 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.2/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.2/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.14.2/src/onesecondtrader/core/portfolio.py

@@ -0,0 +1,359 @@
+"""
+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.strategy_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.strategy_removal_pending: set[base_strategy.Strategy] = set()
+        self._symbol_owner: dict[str, base_strategy.Strategy] = {}
+
+        # INITIALIZE BROKER
+        # ------------------------------------------------------------------------------
+        # TODO Decouple by also doing this via an event
+        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}"
+                    )
+                    return False
+                else:
+                    for sym in symbols_list:
+                        self._symbol_owner[sym] = strategy_instance
+                    self.event_bus.publish(
+                        events.Strategy.SymbolAssignment(
+                            strategy=strategy_instance,
+                            symbol_list=symbols_list,
+                        )
+                    )
+                    return True
+
+        return True
+
+    def remove_strategy(
+        self,
+        strategy_instance: 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_instance (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 AND PUBLISH STOP TRADING EVENT
+        # ------------------------------------------------------------------------------
+        with self._lock:
+            if strategy_instance not in self._strategies:
+                console.logger.warning("remove_strategy: strategy not registered")
+                return False
+            self.strategy_removal_pending.add(strategy_instance)
+
+        # PUBLISH STOP TRADING REQUEST TO EVENT BUS
+        # ------------------------------------------------------------------------------
+        self.event_bus.publish(
+            events.Strategy.StopTrading(
+                strategy=strategy_instance,
+                shutdown_mode=shutdown_mode,
+            )
+        )
+        return True
+
+    def assign_symbols(
+        self, strategy_instance: base_strategy.Strategy, symbols: Iterable[str]
+    ):
+        """
+        Assign a list of symbols to a strategy.
+
+        Args:
+            strategy_instance (base_strategy.Strategy): Strategy instance to assign
+                symbols to.
+            symbols (Iterable[str]): List of symbols to assign.
+        """
+        # IF STRATEGY IS REGISTERED, MARK IT FOR REMOVAL AND PUBLISH STOP TRADING EVENT
+        # ------------------------------------------------------------------------------
+        with self._lock:
+            if strategy_instance not in self._strategies:
+                console.logger.warning("remove_strategy: strategy not registered")
+                return False
+            self.strategy_removal_pending.add(strategy_instance)
+
+        # ASSIGN SYMBOLS IF PROVIDED AND NO CONFLICTS EXIST, ELSE LOG WARNING
+        # ------------------------------------------------------------------------------
+        # TODO This is an repetition of the same logic as in add_strategy; refactor
+
+        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(
+                        "assign_symbols: symbols not assigned due to conflicts; "
+                        "use Portfolio.assign_symbols(...) after resolving. "
+                        f"non_conflicting={non_conflicting}, conflicts={conflicting}"
+                    )
+                    return False
+                else:
+                    for sym in symbols_list:
+                        self._symbol_owner[sym] = strategy_instance
+                    self.event_bus.publish(
+                        events.Strategy.SymbolAssignment(
+                            strategy=strategy_instance,
+                            symbol_list=symbols_list,
+                        )
+                    )
+                    return True
+
+    def unassign_symbols(
+        self, strategy: base_strategy.Strategy, symbols: Iterable[str]
+    ) -> list[str]:
+        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 on_symbol_release(self, event: events.Base.Event) -> None:
+        """
+        Handle symbol release events. Ignores unrelated event types.
+
+        If a symbol is released, it is unassigned from the strategy that owns it
+        (inside the symbol_owner registry). If the strategy is marked for removal and
+        has no more symbols assigned to it, it is automatically deregistered.
+        """
+
+        # IGNORE UNRELATED EVENT TYPES
+        # ------------------------------------------------------------------------------
+        if not isinstance(event, events.Strategy.SymbolRelease):
+            return
+
+        # IF STRATEGY IS REGISTERED, RELEASE SYMBOL FROM STRATEGY
+        # ------------------------------------------------------------------------------
+        # TODO This needs reworking; this will be the same logic as unassig_symbols
+        strategy = event.strategy
+        with self._lock:
+            if strategy not in self._strategies:
+                console.logger.warning("on_symbol_release: strategy not registered")
+                return
+        removed = self.unassign_symbols(strategy, [event.symbol])
+        if not removed:
+            console.logger.warning(
+                f"on_symbol_release: symbol {event.symbol} not owned by "
+                f"{getattr(event.strategy, 'name', type(event.strategy).__name__)}"
+            )
+            return
+        pending = False
+        with self._lock:
+            pending = strategy in self.strategy_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.strategy_removal_pending.discard(strategy)
+                    console.logger.info(
+                        f"Strategy {getattr(strategy, 'name', type(strategy).__name__)} "
+                        f"removed: all symbols released and flat"
+                    )
+            except Exception:
+                pass
+        console.logger.info(
+            f"on_symbol_release: symbol {event.symbol} released from "
+            f"{getattr(event.strategy, 'name', type(event.strategy).__name__)}"
+        )

{onesecondtrader-0.14.0 → onesecondtrader-0.14.2}/src/onesecondtrader/messaging/__init__.py

@@ -5,5 +5,5 @@ from .events import (
     Request as Request,
     Response as Response,
     System as System,
-    Portfolio as Portfolio,
+    Strategy as Strategy,
 )

{onesecondtrader-0.14.0 → onesecondtrader-0.14.2}/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,7 +23,7 @@ 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.Portfolio]
+    R5[events.Base.Strategy]
 
     R --> R1
     R --> R2
@@ -85,11 +85,17 @@ Dataclass field validation logic is grouped under the `_Validate` namespace.
 
     style D1 fill:#6F42C1,fill-opacity:0.3
 
-    E1[events.Portfolio.SymbolRelease]
+    E1[events.Strategy.SymbolRelease]
+    E2[events.Strategy.SymbolAssignment]
+    E3[events.Strategy.StopTrading]
 
     R5 --> E1
+    R5 --> E2
+    R5 --> E3
 
     style E1 fill:#6F42C1,fill-opacity:0.3
+    style E2 fill:#6F42C1,fill-opacity:0.3
+    style E3 fill:#6F42C1,fill-opacity:0.3
 
     subgraph Market ["Market Update Event Messages"]
         R1
@@ -152,12 +158,16 @@ Dataclass field validation logic is grouped under the `_Validate` namespace.
 
     end
 
-    subgraph Portfolio ["Portfolio Coord. Event Messages"]
+    subgraph Strategy ["Strategy Coord. Event Messages"]
         R5
         E1
+        E2
+        E3
 
-        subgraph PortfolioNamespace ["events.Portfolio Namespace"]
+        subgraph StrategyNamespace ["events.Strategy Namespace"]
             E1
+            E2
+            E3
         end
 
     end
@@ -170,6 +180,7 @@ import re
 import uuid
 from onesecondtrader.core import models
 from onesecondtrader.monitoring import console
+from onesecondtrader.strategies import base_strategy
 
 
 class Base:
@@ -297,7 +308,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 "
@@ -363,9 +374,9 @@ class Base:
             return super().__new__(cls)
 
     @dataclasses.dataclass(kw_only=True, frozen=True)
-    class Portfolio(Event):
+    class Strategy(Event):
         """
-        Base event message dataclass for portfolio coordination messages.
+        Base event message dataclass for strategy coordination messages.
         This dataclass cannot be instantiated directly.
 
         Attributes:
@@ -376,14 +387,22 @@ class Base:
         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.Portfolio:
+            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:
     """
@@ -413,7 +432,7 @@ class Market:
             ...         volume=10000,
             ...     ),
             ... )
-            ```
+
         """
 
         bar: models.Bar
@@ -660,7 +679,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
@@ -738,23 +757,72 @@ class System:
         pass
 
 
-class Portfolio:
+class Strategy:
     """
-    Namespace for portfolio coordination event messages.
+    Namespace for strategy coordination event messages.
     """
 
     @dataclasses.dataclass(kw_only=True, frozen=True)
-    class SymbolRelease(Base.Portfolio):
+    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
-        strategy_name: str
 
         def __post_init__(self) -> None:
             super().__post_init__()
-            _Validate.symbol(self.symbol, "Portfolio.SymbolRelease")
+            _Validate.symbol(self.symbol, "Strategy.SymbolRelease")
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class SymbolAssignment(Base.Strategy):
+        """
+        Event message to indicate that a symbol should be assigned to a strategy.
+
+        Attributes:
+            symbol_list (list[str]): List of symbols to be assigned.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Strategy.SymbolAssignment(
+            ...     strategy=my_strategy,
+            ...     symbol=["AAPL"],
+            ... )
+        """
+
+        symbol_list: list[str]
+
+        def __post_init__(self) -> None:
+            super().__post_init__()
+            for symbol in self.symbol_list:
+                _Validate.symbol(symbol, "Strategy.SymbolAssignment")
+
+    @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:

onesecondtrader-0.14.2/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)