onesecondtrader 0.6.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

onesecondtrader/__init__.py

@@ -4,11 +4,9 @@ The Trading Infrastructure Toolkit for Python.
 Research, simulate, and deploy algorithmic trading strategies — all in one place.
 """
 
-# Core infrastructure
-from .monitoring import logger
+from .monitoring.console import logger
 
 
 __all__ = [
-    # Core infrastructure
     "logger",
 ]

onesecondtrader/core/models.py

@@ -0,0 +1,133 @@
+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:
+    """
+    Class for representing a OHLC(V) bar of market data.
+
+    Attributes:
+        open (float): Open price
+        high (float): High price
+        low (float): Low price
+        close (float): Close price
+        volume (float): Volume
+    """
+
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: float | None = None
+
+
+class Side(enum.Enum):
+    """
+    Enum for order sides.
+    """
+
+    BUY = enum.auto()
+    SELL = enum.auto()
+
+
+class TimeInForce(enum.Enum):
+    """
+    Order time-in-force specifications.
+
+    **Attributes:**
+
+    | Enum | Value | Description |
+    |------|-------|-------------|
+    | `DAY` | `enum.auto()` | Valid until end of trading day |
+    | `FOK` | `enum.auto()` | Fill entire order immediately or cancel (Fill-or-Kill) |
+    | `GTC` | `enum.auto()` | Active until explicitly cancelled (Good-Till-Cancelled) |
+    | `GTD` | `enum.auto()` | Active until specified date (Good-Till-Date) |
+    | `IOC` | `enum.auto()` | Execute available quantity immediately, cancel rest
+        (Immediate-or-Cancel) |
+    """
+
+    DAY = enum.auto()
+    FOK = enum.auto()
+    GTC = enum.auto()
+    GTD = enum.auto()
+    IOC = enum.auto()
+
+
+class OrderType(enum.Enum):
+    """
+    Enum for order types.
+
+    **Attributes:**
+
+    | Enum | Value | Description |
+    |------|-------|-------------|
+    | `MARKET` | `enum.auto()` | Market order |
+    | `LIMIT` | `enum.auto()` | Limit order |
+    | `STOP` | `enum.auto()` | Stop order |
+    | `STOP_LIMIT` | `enum.auto()` | Stop-limit order |
+    """
+
+    MARKET = enum.auto()
+    LIMIT = enum.auto()
+    STOP = enum.auto()
+    STOP_LIMIT = enum.auto()
+
+
+class OrderLifecycleState(enum.Enum):
+    """
+    Enum for order lifecycle states.
+
+    **Attributes:**
+
+    | 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 |
+    | `FILLED` | `enum.auto()` | Order has been filled |
+    | `CANCELLED` | `enum.auto()` | Order has been cancelled |
+    """
+
+    PENDING = enum.auto()
+    OPEN = enum.auto()
+    PARTIALLY_FILLED = enum.auto()
+    FILLED = enum.auto()
+    CANCELLED = enum.auto()
+
+
+class OrderRejectionReason(enum.Enum):
+    """
+    Enum for order rejection reasons.
+
+    **Attributes:**
+
+    | Enum | Value | Description |
+    |------|-------|-------------|
+    | `UNKNOWN` | `enum.auto()` | Unknown reason |
+    | `NEGATIVE_QUANTITY` | `enum.auto()` | Negative quantity |
+    """
+
+    UNKNOWN = enum.auto()
+    NEGATIVE_QUANTITY = enum.auto()

onesecondtrader/messaging/events.py

@@ -0,0 +1,742 @@
+"""
+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.
+Base event messages used for structure inheritance are grouped under the
+ `Base` namespace.
+Dataclass field validation logic is grouped under the `_Validate` namespace.
+
+???+ note "Module Overview: `events.py`"
+    ```mermaid
+    ---
+    config:
+      themeVariables:
+        fontSize: "11px"
+    ---
+    graph LR
+
+    R[events.Base.Event]
+    R1[events.Base.Market]
+    R2[events.Base.Request]
+    R21[events.Base.OrderRequest]
+    R22[events.Base.CancelRequest]
+    R3[events.Base.Response]
+    R4[events.Base.System]
+
+    R --> R1
+    R --> R2
+    R --> R3
+    R --> R4
+
+    R2 --> R21
+    R2 --> R22
+
+    A1[events.Market.IncomingBar]
+
+    R1 --> A1
+
+    style A1 fill:#6F42C1,fill-opacity:0.3
+
+    B1[events.Request.MarketOrder]
+    B2[events.Request.LimitOrder]
+    B3[events.Request.StopOrder]
+    B4[events.Request.StopLimitOrder]
+    B5[events.Request.CancelOrder]
+    B6[events.Request.FlushSymbol]
+    B7[events.Request.FlushAll]
+
+    R21 --> B1
+    R21 --> B2
+    R21 --> B3
+    R21 --> B4
+    R22 --> B5
+    R22 --> B6
+    R22 --> B7
+
+    style B1 fill:#6F42C1,fill-opacity:0.3
+    style B2 fill:#6F42C1,fill-opacity:0.3
+    style B3 fill:#6F42C1,fill-opacity:0.3
+    style B4 fill:#6F42C1,fill-opacity:0.3
+    style B5 fill:#6F42C1,fill-opacity:0.3
+    style B6 fill:#6F42C1,fill-opacity:0.3
+    style B7 fill:#6F42C1,fill-opacity:0.3
+
+    C1[events.Response.OrderSubmitted]
+    C2[events.Response.OrderFilled]
+    C3[events.Response.OrderCancelled]
+    C4[events.Response.OrderRejected]
+
+    R3 --> C1
+    R3 --> C2
+    R3 --> C3
+    R3 --> C4
+
+    style C1 fill:#6F42C1,fill-opacity:0.3
+    style C2 fill:#6F42C1,fill-opacity:0.3
+    style C3 fill:#6F42C1,fill-opacity:0.3
+    style C4 fill:#6F42C1,fill-opacity:0.3
+
+    D1[events.System.Shutdown]
+
+    R4 --> D1
+
+    style D1 fill:#6F42C1,fill-opacity:0.3
+
+
+    subgraph Market ["Market Update Event Messages"]
+        R1
+        A1
+
+        subgraph MarketNamespace ["events.Market Namespace"]
+            A1
+        end
+
+    end
+
+
+    subgraph Request ["Broker Request Event Messages"]
+        R2
+        R21
+        R22
+        B1
+        B2
+        B3
+        B4
+        B5
+        B6
+        B7
+
+        subgraph RequestNamespace ["events.Request Namespace"]
+            B1
+            B2
+            B3
+            B4
+            B5
+            B6
+            B7
+        end
+
+    end
+
+    subgraph Response ["Broker Response Event Messages"]
+        R3
+        C1
+        C2
+        C3
+        C4
+
+        subgraph ResponseNamespace ["events.Response Namespace"]
+            C1
+            C2
+            C3
+            C4
+        end
+
+    end
+
+    subgraph System ["System-Internal Event Messages"]
+        R4
+        D1
+
+        subgraph SystemNamespace ["events.System Namespace"]
+            D1
+        end
+
+    end
+    ```
+"""
+
+import dataclasses
+import pandas as pd
+import re
+import uuid
+from onesecondtrader.core import models
+from onesecondtrader.monitoring import console
+
+
+class Base:
+    """
+    Namespace for event base dataclasses.
+    """
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class Event:
+        """
+        Base event message dataclass.
+        This dataclass cannot be instantiated directly.
+
+        Attributes:
+            ts_event (pd.Timestamp): Timestamp of the event in pandas Timestamp format.
+                (Must be timezone-aware.)
+            event_bus_sequence_number (int | None): Auto-generated Sequence number of
+                 the event.
+                This will be assigned as soon as the event enters the event bus via
+                 `messaging.EventBus.publish(<event>)`.
+        """
+
+        ts_event: pd.Timestamp
+        event_bus_sequence_number: int | None = dataclasses.field(
+            default=None, init=False
+        )
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.Event:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+        def __post_init__(self) -> None:
+            _Validate.timezone_aware(self.ts_event, "ts_event", "Event")
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class Market(Event):
+        """
+        Base event message dataclass for market events.
+        Inherits from `Base.Event`.
+        Each market event message is associated with a specific financial instrument via
+         the `symbol` field.
+        This dataclass cannot be instantiated directly.
+
+        Attributes:
+            symbol (str): Symbol of the financial instrument.
+        """
+
+        symbol: str
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.Market:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+        def __post_init__(self) -> None:
+            super().__post_init__()
+            _Validate.symbol(self.symbol, "Market event")
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class Request(Event):
+        """
+        Base event message dataclass for broker requests.
+        This dataclass cannot be instantiated directly.
+        `ts_event` is auto-generated by default.
+
+        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")
+        )
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.Request:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class OrderRequest(Request):
+        """
+        Base event message dataclass for order requests.
+        Inherits from `Base.Request`.
+        This dataclass cannot be instantiated directly.
+
+        Attributes:
+            symbol (str): Symbol of the financial instrument.
+            side (models.Side): Side of the order.
+            quantity (float): Quantity of the order.
+            time_in_force (models.TimeInForce): Time in force of the order.
+            order_expiration (pd.Timestamp | None): Expiration timestamp of the order
+                (optional).
+                Only relevant if `time_in_force` is `models.TimeInForce.GTD`.
+            order_id (uuid.UUID): Unique ID of the order. (auto-generated)
+        """
+
+        symbol: str
+        side: models.Side
+        quantity: float
+        time_in_force: models.TimeInForce
+        order_expiration: pd.Timestamp | None = None
+        order_id: uuid.UUID = dataclasses.field(default_factory=uuid.uuid4)
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.OrderRequest:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+        def __post_init__(self) -> None:
+            super().__post_init__()
+            _Validate.symbol(self.symbol, f"Order {self.order_id}")
+
+            _Validate.timezone_aware(
+                self.order_expiration, "order_expiration", f"Order {self.order_id}"
+            )
+            _Validate.quantity(self.quantity, f"Order {self.order_id}")
+
+            if self.time_in_force.value == 4:
+                if self.order_expiration is None:
+                    console.logger.error(
+                        f"Order {self.order_id}: GTD order missing expiration "
+                        f"timestamp."
+                    )
+                elif self.order_expiration <= self.ts_event:
+                    console.logger.error(
+                        f"Order {self.order_id}: GTD expiration "
+                        f"{self.order_expiration} "
+                        f"is not after event timestamp {self.ts_event}."
+                    )
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class CancelRequest(Request):
+        """
+        Base event message dataclass for order cancellation requests.
+        Inherits from `Base.Request`.
+        This dataclass cannot be instantiated directly.
+        """
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.CancelRequest:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class Response(Event):
+        """
+        Base event message dataclass for broker responses.
+        This dataclass cannot be instantiated directly.
+        """
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.Response:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class System(Event):
+        """
+        Base event message dataclass for system-internal messages.
+        This dataclass cannot be instantiated directly.
+        `ts_event` is auto-generated by default.
+
+        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")
+        )
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Base.System:
+                console.logger.error(
+                    f"Cannot instantiate abstract class '{cls.__name__}' directly"
+                )
+            return super().__new__(cls)
+
+
+class Market:
+    """
+    Namespace for market update event messages.
+    """
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class IncomingBar(Base.Market):
+        """
+        Event message dataclass for incoming market data bars.
+        Inherits from `Base.Market`.
+
+        Attributes:
+            bar (models.Bar): Bar of market data.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> from onesecondtrader.core import models
+            >>> event = events.Market.IncomingBar(
+            ...     ts_event=pd.Timestamp("2023-01-01 00:00:00", tz="UTC"),
+            ...     symbol="AAPL",
+            ...     bar=models.Bar(
+            ...         open=100.0,
+            ...         high=101.0,
+            ...         low=99.0,
+            ...         close=100.5,
+            ...         volume=10000,
+            ...     ),
+            ... )
+            ```
+        """
+
+        bar: models.Bar
+
+
+class Request:
+    """
+    Namespace for broker request event messages.
+    """
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class MarketOrder(Base.OrderRequest):
+        """
+        Event message dataclass for submitting a market order to the broker.
+
+        Attributes:
+            order_type (models.OrderType): Type of the order (automatically set to
+            models.OrderType.MARKET).
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Request.MarketOrder(
+            ...     symbol="AAPL",
+            ...     side=models.Side.BUY,
+            ...     quantity=100.0,
+            ...     time_in_force=models.TimeInForce.DAY,
+            ... )
+        """
+
+        order_type: models.OrderType = dataclasses.field(
+            init=False, default=models.OrderType.MARKET
+        )
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class LimitOrder(Base.OrderRequest):
+        """
+        Event message dataclass for submitting a limit order to the broker.
+
+        Attributes:
+            order_type (models.OrderType): Type of the order (automatically set to
+            models.OrderType.LIMIT).
+            limit_price (float): Limit price of the order.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Request.LimitOrder(
+            ...     symbol="AAPL",
+            ...     side=models.Side.BUY,
+            ...     quantity=100.0,
+            ...     time_in_force=models.TimeInForce.DAY,
+            ...     limit_price=100.0,
+            ... )
+        """
+
+        order_type: models.OrderType = dataclasses.field(
+            init=False, default=models.OrderType.LIMIT
+        )
+        limit_price: float
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class StopOrder(Base.OrderRequest):
+        """
+        Event message dataclass for submitting a stop order to the broker.
+
+        Attributes:
+            order_type (models.OrderType): Type of the order (automatically set to
+            models.OrderType.STOP).
+            stop_price (float): Stop price of the order.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Request.StopOrder(
+            ...     symbol="AAPL",
+            ...     side=models.Side.BUY,
+            ...     quantity=100.0,
+            ...     time_in_force=models.TimeInForce.DAY,
+            ...     stop_price=100.0,
+            ... )
+        """
+
+        order_type: models.OrderType = dataclasses.field(
+            init=False, default=models.OrderType.STOP
+        )
+        stop_price: float
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class StopLimitOrder(Base.OrderRequest):
+        """
+        Event message dataclass for submitting a stop-limit order to the broker.
+
+        Attributes:
+            order_type (models.OrderType): Type of the order (automatically set to
+            models.OrderType.STOP_LIMIT).
+            stop_price (float): Stop price of the order.
+            limit_price (float): Limit price of the order.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Request.StopLimitOrder(
+            ...     symbol="AAPL",
+            ...     side=models.Side.BUY,
+            ...     quantity=100.0,
+            ...     time_in_force=models.TimeInForce.DAY,
+            ...     stop_price=100.0,
+            ...     limit_price=100.0,
+            ... )
+        """
+
+        order_type: models.OrderType = dataclasses.field(
+            init=False, default=models.OrderType.STOP_LIMIT
+        )
+        stop_price: float
+        limit_price: float
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class CancelOrder(Base.CancelRequest):
+        """
+        Event message dataclass for cancelling an order.
+
+        Attributes:
+            order_id (uuid.UUID): Unique ID of the order to cancel.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Request.CancelOrder(
+            ...     order_id=uuid.UUID("12345678-1234-5678-1234-567812345678"),
+            ... )
+        """
+
+        order_id: uuid.UUID
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class FlushSymbol(Base.Request):
+        """
+        Event message dataclass for flushing all orders for a symbol.
+
+        Attributes:
+            symbol (str): Symbol to flush.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Request.FlushSymbol(
+            ...     symbol="AAPL",
+            ... )
+        """
+
+        symbol: str
+
+        def __post_init__(self) -> None:
+            super().__post_init__()
+            _Validate.symbol(self.symbol, "Flush request")
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class FlushAll(Base.Request):
+        """
+        Event message dataclass for flushing all orders for all symbols.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.Request.FlushAll()
+        """
+
+        pass
+
+
+class Response:
+    """
+    Namespace for broker response event messages.
+    """
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class OrderSubmitted(Base.Response):
+        """
+        Event message dataclass for order submission confirmation from the broker.
+
+        Attributes:
+            order_submitted_id (uuid.UUID): Unique ID of the submitted order.
+            associated_request_id (uuid.UUID): Unique ID of the request that triggered
+                the order submission.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> import pandas as pd
+            >>> import uuid
+            >>> event = events.Response.OrderSubmitted(
+            ...     ts_event=pd.Timestamp(
+            ...         "2023-01-01 00:00:00", tz="UTC"),
+            ...     order_submitted_id=uuid.UUID(
+            ...         "12345678-1234-5678-1234-567812345678"),
+            ...     associated_request_id=uuid.UUID(
+            ...         "12345678-1234-5678-1234-567812345678"
+            ...     ),
+            ... )
+        """
+
+        order_submitted_id: uuid.UUID
+        associated_request_id: uuid.UUID
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class OrderFilled(Base.Response):
+        """
+        Event message dataclass for order fill confirmation from the broker.
+
+        Attributes:
+            fill_id (uuid.UUID): Unique ID of the fill. (auto-generated)
+            associated_order_submitted_id (uuid.UUID): Unique ID of the submitted order
+                that triggered the fill.
+            side (models.Side): Side of the fill.
+            quantity_filled (float): Quantity filled.
+            filled_at_price (float): Price at which the fill was executed.
+            commission_and_fees (float): Commission and fees for the fill.
+            net_fill_value (float): Net fill value (auto-generated).
+            exchange (str | None): Exchange on which the fill was executed. (optional;
+                defaults to "SIMULATED")
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> from onesecondtrader.core import models
+            >>> import pandas as pd
+            >>> import uuid
+            >>> event = events.Response.OrderFilled(
+            ...     ts_event=pd.Timestamp("2023-01-01 00:00:00", tz="UTC"),
+            ...     associated_order_submitted_id=uuid.UUID(
+            ...         "12345678-1234-5678-1234-567812345678"
+            ...     ),
+            ...     side=models.Side.BUY,
+            ...     quantity_filled=100.0,
+            ...     filled_at_price=100.0,
+            ...     commission_and_fees=1.0,
+            ... )
+        """
+
+        fill_id: uuid.UUID = dataclasses.field(default_factory=uuid.uuid4)
+        associated_order_submitted_id: uuid.UUID
+        side: models.Side
+        quantity_filled: float
+        filled_at_price: float
+        commission_and_fees: float
+        net_fill_value: float = dataclasses.field(init=False)
+        exchange: str | None = None
+
+        def __post_init__(self):
+            object.__setattr__(self, "fill_id", self.fill_id or uuid.uuid4())
+
+            gross_value = self.filled_at_price * self.quantity_filled
+
+            if self.side.value == 1:
+                net_value = gross_value + self.commission_and_fees
+            else:
+                net_value = gross_value - self.commission_and_fees
+
+            object.__setattr__(self, "net_fill_value", net_value)
+
+            object.__setattr__(self, "exchange", self.exchange or "SIMULATED")
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class OrderCancelled(Base.Response):
+        """
+        Event message dataclass for order cancellation confirmation from the broker.
+
+        Attributes:
+            associated_order_submitted_id (uuid.UUID): Unique ID of the submitted order
+                that was cancelled.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> import pandas as pd
+            >>> import uuid
+            >>> event = events.Response.OrderCancelled(
+            ...     ts_event=pd.Timestamp("2023-01-01 00:00:00", tz="UTC"),
+            ...     associated_order_submitted_id=uuid.UUID(
+            ...         "12345678-1234-5678-1234-567812345678"
+            ...     ),
+            ... )
+        """
+
+        associated_order_submitted_id: uuid.UUID
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class OrderRejected(Base.Response):
+        """
+        Event message dataclass for order rejection confirmation from the broker.
+
+        Attributes:
+            associated_order_submitted_id (uuid.UUID): Unique ID of the submitted order
+                that was rejected.
+            reason (models.OrderRejectionReason): Reason for the rejection.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> from onesecondtrader.core import models
+            >>> import pandas as pd
+            >>> import uuid
+            >>> event = events.Response.OrderRejected(
+            ...     ts_event=pd.Timestamp("2023-01-01 00:00:00", tz="UTC"),
+            ...     associated_order_submitted_id=uuid.UUID(
+            ...         "12345678-1234-5678-1234-567812345678"
+            ...     ),
+            ...     reason=models.OrderRejectionReason.NEGATIVE_QUANTITY,
+            ... )
+        """
+
+        associated_order_submitted_id: uuid.UUID
+        reason: models.OrderRejectionReason
+
+
+class System:
+    """
+    Namespace for system-internal event messages.
+    """
+
+    @dataclasses.dataclass(kw_only=True, frozen=True)
+    class Shutdown(Base.System):
+        """
+        Event message dataclass for system shutdown.
+
+        Examples:
+            >>> from onesecondtrader.messaging import events
+            >>> event = events.System.Shutdown()
+        """
+
+        pass
+
+
+class _Validate:
+    """Internal validation utilities for events."""
+
+    @staticmethod
+    def symbol(symbol: str, context: str = "") -> None:
+        """Validate symbol format and log errors."""
+        if not symbol or not symbol.strip():
+            console.logger.error(f"{context}: Symbol cannot be empty or whitespace")
+            return
+
+        if not re.fullmatch(r"[A-Z0-9._-]+", symbol):
+            console.logger.error(f"{context}: Invalid symbol format: {symbol}")
+
+    @staticmethod
+    def quantity(quantity: float, context: str = "") -> None:
+        """Validate quantity values and log errors."""
+        if (
+            quantity != quantity
+            or quantity == float("inf")
+            or quantity == float("-inf")
+        ):
+            console.logger.error(f"{context}: quantity cannot be NaN or infinite")
+            return
+
+        if quantity <= 0:
+            console.logger.error(
+                f"{context}: quantity must be positive, got {quantity}"
+            )
+
+        if quantity > 1e9:
+            console.logger.error(f"{context}: quantity too large: {quantity}")
+
+    @staticmethod
+    def timezone_aware(
+        timestamp: pd.Timestamp | None, field_name: str, context: str = ""
+    ) -> None:
+        """Validate that timestamp is timezone-aware and log errors."""
+        if timestamp is not None and timestamp.tz is None:
+            console.logger.error(
+                f"{context}: {field_name} must be timezone-aware, got {timestamp}"
+            )

onesecondtrader/{monitoring.py → monitoring/console.py}

@@ -1,7 +1,6 @@
-"""Logging configuration for the OneSecondTrader package.
+"""Console logging utilities for OneSecondTrader.
 
-This module sets up the default logging configuration and provides
-a logger instance for use throughout the package.
+Simple console logging configuration for terminal output.
 """
 
 import logging

onesecondtrader-0.8.0.dist-info/METADATA

@@ -0,0 +1,248 @@
+Metadata-Version: 2.3
+Name: onesecondtrader
+Version: 0.8.0
+Summary: The Trading Infrastructure Toolkit for Python. Research, simulate, and deploy algorithmic trading strategies — all in one place.
+Author: Nils P. Kujath
+Author-email: 63961429+NilsKujath@users.noreply.github.com
+Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: pandas (>=2.3.1,<3.0.0)
+Description-Content-Type: text/markdown
+
+# OneSecondTrader
+
+[![Tests](https://github.com/nilskujath/onesecondtrader/actions/workflows/release.yml/badge.svg)](https://github.com/nilskujath/onesecondtrader/actions/workflows/release.yml)
+[![Docs](https://img.shields.io/badge/docs-onesecondtrader.com-blue)](https://www.onesecondtrader.com)
+[![PyPI](https://img.shields.io/pypi/v/onesecondtrader)](https://pypi.org/project/onesecondtrader/)
+[![License](https://img.shields.io/github/license/nilskujath/onesecondtrader)](https://github.com/nilskujath/onesecondtrader/blob/master/LICENSE)
+
+
+For documentation, please visit [onesecondtrader.com](https://www.onesecondtrader.com).
+
+
+
+
+## For Developers: Continuous Integration & Delivery (CI/CD) Pipeline
+
+This project's continuous integration & continuous delivery (CI/CD) pipeline consists of two distinct workflows:
+ **local pre-commit hooks** that run on `git commit` to ensure code quality,
+ and **GitHub Actions** that run on `git push origin master` to automate releases.
+
+In order for the pipeline to work, the following configuration is required:
+
+* version field in `pyproject.toml` must be set to appropriate version
+```toml
+[tool.poetry]
+name = "onesecondtrader"
+version = "0.1.0"  # Updated automatically by bump_version.py
+```
+* `mkdocs.yml` must have `mkdocstrings-python` plugin configured
+```yaml
+plugins:
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: google
+```
+
+### Local Pre-Commit Workflow
+
+To ensure that only good quality code is commited to the repository, a series of pre-commit hooks are executed before each commit.
+ These hooks include code quality checks, testing, security scans, and automated API reference generation.
+ This workflow is orchestrated by the `pre-commit` package, which is configured in the `.pre-commit-config.yaml` file.
+ If any of these checks fail, the commit is blocked and the developer must fix the issues before retrying.
+
+Prior to usage, the pre-commit hooks must be installed by running:
+```bash
+poetry run pre-commit install
+poetry run pre-commit install --hook-type commit-msg
+poetry run pre-commit run --all-files # Optional: Test installation
+```
+
+This project follows [Conventional Commits](https://www.conventionalcommits.org/) specification for commit messages.
+This standardized format enables automated semantic versioning and changelog generation.
+The commit messages must have the following format:
+
+```
+<type>: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+The commit message must start with a type, followed by a colon and a space, and then a description. The type must be one of the following:
+
+- **feat**: New features that add functionality
+- **fix**: Bug fixes and patches
+- **docs**: Documentation changes only
+- **chore**: Maintenance tasks, dependency updates, build changes
+- **test**: Adding or modifying tests
+- **refactor**: Code changes that neither fix bugs nor add features
+- **perf**: Performance improvements
+- **ci**: Changes to CI/CD configuration
+
+Examples:
+
+```
+feat: added trade-by-trade chart generation 
+```
+
+The following diagram illustrates this pre-commit workflow:
+
+```mermaid
+---
+config:
+  themeVariables:
+    fontSize: "11px"
+---
+graph TD
+    A([<kbd>git commit</kbd>]) -->|Trigger Pre-commit Workflow on <kbd>commit</kbd>| PrecommitHooks
+    
+    subgraph PrecommitHooks ["Local Pre-commit Hooks"]
+        B["<b>Code Quality Checks</b><br/>• Ruff Check & Format<br/>• MyPy Type Checking<br/>• Tests & Doctests"]
+        C["<b>Security Checks</b><br/>• Gitleaks Secret Detection"]
+        D["<b>File Validation</b><br/>• YAML/TOML/JSON Check<br/>• End-of-file Fixer<br/>• Large Files Check<br/>• Merge Conflict Check<br/>• Debug Statements Check"]
+        E["<b>Generate API Documentation</b> via <kbd>scripts/generate_api_docs.py</kbd><br/>• Auto-generate docs<br/>• Stage changes"]
+    end
+    B --> C --> D --> E
+
+    F([Write Commit Message])
+    PrecommitHooks -->|Pass| F
+    PrecommitHooks -.->|Fail| H
+
+    subgraph CommitMessageHook ["Commit Message Hook"]
+        G{Commit Message Valid?}
+    end
+        G -.->|No| H[Commit Blocked]
+        G -->|Yes| I[Commit Successful]
+
+    F --> CommitMessageHook
+
+    H -.->|Rework & Restage<br/>| K
+    
+    K(["<kbd>git commit --amend</kbd>"])
+
+    K -.-> PrecommitHooks
+
+    L(["<kbd>git pull --rebase origin master</kbd>"])
+
+    L -.->|Rebase & Resolve Conflicts| M
+    
+    M([<kbd>git add <...></kbd>])
+    
+    M -.-> A
+
+    I -.~.-> J([<kbd>git push</kbd>])
+```
+
+
+### GitHub Actions Workflow
+
+Once a commit is pushed to the remote `master` branch, the GitHub Actions workflow `.github/workflows/release.yml` is triggered.
+Note that the GitHub Actions workflow might push commits to the remote repository.
+ This means your local branch will be behind the remote branch.
+
+In order for this workflow to run properly, two secrets need to be configured (`Settings > Secrets and variables > Actions`):
+
+- `GH_PAT`: Personal Access Token with enhanced permissions (see PAT Setup below)
+- `PYPI_API_TOKEN`: Generate from PyPI account settings
+
+The default `GITHUB_TOKEN` has limited permissions and cannot trigger subsequent workflow runs or push to protected branches.
+ The PAT provides the necessary permissions for the automated release process. 
+ The PAT is created as follows:
+
+1. Go to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)
+2. Click "Generate new token (classic)"
+3. Set expiration and select these scopes:
+   - `repo` (Full control of private repositories)
+   - `workflow` (Update GitHub Action workflows)
+4. Copy the token and add it as `GH_PAT` secret in repository settings
+
+Note that GitHub Actions bot must have write permissions to the repository.
+
+The following diagram illustrates this GitHub Actions workflow:
+
+```mermaid
+---
+config:
+  themeVariables:
+    fontSize: "11px"
+---
+graph TD
+    
+    A0(<kdb>git commit</kbd>)
+
+    A1(<kdb>git commit --amend</kdb>)
+
+    A(<kbd>git push origin master</kbd>) -->|Trigger GitHub Actions Workflow on <kbd>push</kbd>| GitHubActions
+
+    A2(<kbd>git push origin master --force</kbd>) -->|Trigger GitHub Actions Workflow on <kbd>push</kbd>| GitHubActions
+
+    A0 -.->|Trigger Pre-commit Workflow & Commit| A
+    A1 -.->|Trigger Pre-commit Workflow & Commit| A2
+    
+    subgraph GitHubActions ["GitHub Actions Environment Setup"]
+        B["<b>Checkout Repository</b><br/>Retrieve the full repository history on the latest Ubuntu runner"]
+        C["<b>Setup Python Environment</b><br/>Configure the required Python version and install Poetry"]
+        D["<b>Install Dependencies</b><br/>Install all project dependencies, including development ones"]
+        B --> C --> D
+    end
+
+    GitHubActions -.->|Failure<br/>Rework & Restage| A3
+    A3(<kdb>git commit --amend</kdb>)
+
+    GitHubActions -->|Environment Setup Complete| QualityChecks
+    
+    subgraph QualityChecks ["CI Quality Validation"]
+        F["<b>Ruff Linting</b><br/>Validate code style and enforce formatting rules"]
+        G["<b>MyPy Type Checking</b><br/>Static type analysis"]
+        H["<b>Test Suite</b><br/>Run all automated tests"]
+        F --> G --> H
+    end
+   
+    QualityChecks -.->|Failure<br/>Rework & Restage| A3
+
+    QualityChecks -->|CI Quality Checks Passed| GitConfig
+    
+    subgraph GitConfig ["Git Configuration"]
+        J["<b>Configure Git Identity</b><br/>Set the automated commit author for CI operations"]
+        K["<b>Setup Authentication</b><br/>Enable secure access to the repository with release permissions (requires <kbd>GH_PAT</kbd>)"]
+        J --> K
+    end
+
+    GitConfig -->|Git Configured| VersionAnalysis
+    
+    subgraph VersionAnalysis ["Semantic Version Analysis"]
+        N["<b>Execute bump_version.py</b><br/>Analyze commits since last tag to decide on version bump and bump level"]
+        P{Version Bump Required?}
+        N --> P
+    end
+    
+    VersionAnalysis -->|No Version Change<br/>Skip Release Process| DocDeployment
+    VersionAnalysis -->|Version Bump Required| ReleaseProcess
+    
+    
+    subgraph ReleaseProcess ["Release & Publishing"]
+        R["<b>Update Version & Changelog</b><br/>Write new version and regenerate release notes."]
+        S["<b>Commit & Push</b><br/>Commit updated files and push to the default branch."]
+        T["<b>Publish to PyPI</b><br/>Build and upload distributions in one step."]
+        U["<b>Create GitHub Release</b><br/>Publish tag and attach changelog."]
+        R --> S --> T --> U
+    end
+
+    
+    ReleaseProcess -->|Release Complete| DocDeployment 
+    
+    subgraph DocDeployment ["Documentation Deployment"]
+        X["<b>Generate API Documentation</b><br/>Automatically build API docs and update navigation"]
+        Y["<b>Install Package for Docs</b><br/>Prepare project for import-based documentation"]
+        Z["<b>Deploy to GitHub Pages</b><br/>Publish updated documentation site"]
+        X --> Y --> Z
+    end
+```
+

onesecondtrader-0.8.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+onesecondtrader/__init__.py,sha256=TNqlT20sH46-J7F6giBxwWYG1-wFZZt7toDbZeQK6KQ,210
+onesecondtrader/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onesecondtrader/core/models.py,sha256=Pw3og5b2mzcoPpMfv3ZdKPvUvhLvh_eT68WJSlIpRyo,3325
+onesecondtrader/core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onesecondtrader/messaging/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onesecondtrader/messaging/events.py,sha256=eaWXQQIUnRNOR-9n5-6lyLbZ6bUtzjD4GI567U_vh4g,23625
+onesecondtrader/monitoring/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onesecondtrader/monitoring/console.py,sha256=1mrojXkyL4ro7ebkvDMGNQiCL-93WEylRuwnfmEKzVs,299
+onesecondtrader/monitoring/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onesecondtrader/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+onesecondtrader-0.8.0.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+onesecondtrader-0.8.0.dist-info/METADATA,sha256=ry6U-Hj4bxnaKgAWXdlM7CtL0Zv0w3_kri_NE2T-TzA,9518
+onesecondtrader-0.8.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+onesecondtrader-0.8.0.dist-info/RECORD,,

onesecondtrader-0.6.0.dist-info/METADATA

@@ -1,24 +0,0 @@
-Metadata-Version: 2.3
-Name: onesecondtrader
-Version: 0.6.0
-Summary: The Trading Infrastructure Toolkit for Python. Research, simulate, and deploy algorithmic trading strategies — all in one place.
-Author: Nils P. Kujath
-Author-email: 63961429+NilsKujath@users.noreply.github.com
-Requires-Python: >=3.11
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: pandas (>=2.3.1,<3.0.0)
-Description-Content-Type: text/markdown
-
-# OneSecondTrader
-
-[![Tests](https://github.com/nilskujath/onesecondtrader/actions/workflows/release.yml/badge.svg)](https://github.com/nilskujath/onesecondtrader/actions/workflows/release.yml)
-[![Docs](https://img.shields.io/badge/docs-onesecondtrader.com-blue)](https://www.onesecondtrader.com)
-[![PyPI](https://img.shields.io/pypi/v/onesecondtrader)](https://pypi.org/project/onesecondtrader/)
-[![License](https://img.shields.io/github/license/nilskujath/onesecondtrader)](https://github.com/nilskujath/onesecondtrader/blob/master/LICENSE)
-
-
-For documentation, please visit [onesecondtrader.com](https://www.onesecondtrader.com).
-

onesecondtrader-0.6.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-onesecondtrader/__init__.py,sha256=EKXVvlpWyePQfeBc8V61sDpBfyh5aONvkBmgonzc930,250
-onesecondtrader/monitoring.py,sha256=TGm53SD_TA4Xa57Go91BGHV3SEIA6MflwSO63r9Jt6g,366
-onesecondtrader-0.6.0.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-onesecondtrader-0.6.0.dist-info/METADATA,sha256=RN3j_ySqSFRTgvxqdsiGG-Z3oGERZaMg1DoPFE5Xy40,1220
-onesecondtrader-0.6.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-onesecondtrader-0.6.0.dist-info/RECORD,,