feat: brokerage abstraction layer with Alpaca implementation

shared/broker/base.py

@@ -0,0 +1,87 @@
+"""Abstract base class for brokerage integrations.
+
+All broker implementations must inherit from ``BaseBroker`` and provide
+concrete implementations for order management, position tracking, and
+account information retrieval.  This abstraction layer allows the trading
+bot to swap brokerages (Alpaca, Interactive Brokers, Tradier, ...) without
+changing strategy or execution logic.
+"""
+
+from abc import ABC, abstractmethod
+
+from shared.schemas.trading import AccountInfo, OrderRequest, OrderResult, PositionInfo
+
+
+class BaseBroker(ABC):
+    """Interface that every brokerage adapter must implement."""
+
+    @abstractmethod
+    async def submit_order(self, order: OrderRequest) -> OrderResult:
+        """Submit a new order to the brokerage.
+
+        Parameters
+        ----------
+        order:
+            The order details including ticker, side, quantity, and order type.
+
+        Returns
+        -------
+        OrderResult
+            Result containing the order ID, status, and fill information.
+        """
+        ...
+
+    @abstractmethod
+    async def cancel_order(self, order_id: str) -> bool:
+        """Cancel an open order.
+
+        Parameters
+        ----------
+        order_id:
+            The brokerage-assigned order identifier.
+
+        Returns
+        -------
+        bool
+            ``True`` if the cancellation was accepted, ``False`` otherwise.
+        """
+        ...
+
+    @abstractmethod
+    async def get_positions(self) -> list[PositionInfo]:
+        """Return all currently open positions.
+
+        Returns
+        -------
+        list[PositionInfo]
+            One entry per open position with quantity, average entry, current
+            price, and unrealized P&L.
+        """
+        ...
+
+    @abstractmethod
+    async def get_account(self) -> AccountInfo:
+        """Return account-level summary information.
+
+        Returns
+        -------
+        AccountInfo
+            Equity, cash, buying power, and total portfolio value.
+        """
+        ...
+
+    @abstractmethod
+    async def get_order_status(self, order_id: str) -> OrderResult:
+        """Fetch the current status of an existing order.
+
+        Parameters
+        ----------
+        order_id:
+            The brokerage-assigned order identifier.
+
+        Returns
+        -------
+        OrderResult
+            Current state of the order including fill price if applicable.
+        """
+        ...