pyactuator 0.0.1__py3-none-any.whl

pyactuator/__init__.py

@@ -0,0 +1,25 @@
+"""PyActuator — thin broker-agnostic execution layer for trading."""
+
+from pyactuator.client import ExecutionClient
+from pyactuator.types import (
+    CancelResponse,
+    Fill,
+    OrderRequest,
+    OrderResponse,
+    OrderStatus,
+    OrderType,
+    Side,
+    TimeInForce,
+)
+
+__all__ = [
+    "CancelResponse",
+    "ExecutionClient",
+    "Fill",
+    "OrderRequest",
+    "OrderResponse",
+    "OrderStatus",
+    "OrderType",
+    "Side",
+    "TimeInForce",
+]

pyactuator/adapters/__init__.py

@@ -0,0 +1,9 @@
+"""Broker adapters implementing ExecutionClient."""
+
+from pyactuator.adapters.base import BaseExecutionClient
+from pyactuator.adapters.mock import MockExecutionClient
+
+__all__ = [
+    "BaseExecutionClient",
+    "MockExecutionClient",
+]

pyactuator/adapters/alpaca.py

@@ -0,0 +1,272 @@
+"""Alpaca broker adapter (requires pyactuator[alpaca])."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable
+from datetime import UTC, datetime
+from decimal import Decimal
+from typing import Any
+
+from pyactuator.adapters.base import BaseExecutionClient
+from pyactuator.types import (
+    CancelResponse,
+    Fill,
+    OrderRequest,
+    OrderResponse,
+    OrderStatus,
+    OrderType,
+    Side,
+    TimeInForce,
+)
+
+logger = logging.getLogger(__name__)
+
+try:
+    from alpaca.trading.client import TradingClient
+    from alpaca.trading.enums import (
+        OrderSide as AlpacaOrderSide,
+    )
+    from alpaca.trading.enums import (
+        TimeInForce as AlpacaTimeInForce,
+    )
+    from alpaca.trading.requests import (
+        LimitOrderRequest,
+        MarketOrderRequest,
+        StopLimitOrderRequest,
+        StopOrderRequest,
+    )
+    from alpaca.trading.stream import TradingStream
+
+    _ALPACA_AVAILABLE = True
+except ImportError:
+    _ALPACA_AVAILABLE = False
+
+
+def _alpaca_required() -> None:
+    if not _ALPACA_AVAILABLE:
+        raise ImportError(
+            "alpaca-py is required for AlpacaExecutionClient. "
+            "Install with: pip install pyactuator[alpaca]"
+        )
+
+
+def _map_status(alpaca_status: str | None) -> str:
+    """Map Alpaca order status to normalized status."""
+    if not alpaca_status:
+        return "pending"
+    s = alpaca_status.lower()
+    if s in ("pending_new", "accepted", "new"):
+        return "open" if s == "accepted" or s == "new" else "pending_new"
+    if s in ("partially_filled", "filled", "canceled", "rejected", "expired"):
+        return s
+    return s
+
+
+class AlpacaExecutionClient(BaseExecutionClient):
+    """Alpaca execution adapter using alpaca-py.
+
+    Sync SDK calls are run in asyncio.to_thread so the client is non-blocking.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_secret: str,
+        *,
+        paper: bool = True,
+        base_url: str | None = None,
+    ) -> None:
+        _alpaca_required()
+        self._api_key = api_key
+        self._api_secret = api_secret
+        self._paper = paper
+        self._base_url = base_url
+        self._client = TradingClient(
+            api_key=api_key,
+            secret_key=api_secret,
+            paper=paper,
+            url_override=base_url,
+        )
+        self._stream: TradingStream | None = None
+        self._fill_callback: Callable[[Fill], None] | None = None
+        self._stream_task: asyncio.Task[None] | None = None
+
+    def _build_order_request(self, order: OrderRequest) -> Any:
+        common = {
+            "symbol": order.symbol,
+            "qty": float(order.quantity),
+            "side": AlpacaOrderSide.BUY if order.side == Side.BUY else AlpacaOrderSide.SELL,
+            "time_in_force": self._map_tif(order.time_in_force),
+            "client_order_id": order.client_order_id,
+            "extended_hours": order.extended_hours,
+        }
+        if order.order_type == OrderType.MARKET:
+            return MarketOrderRequest(**common)
+        if order.order_type == OrderType.LIMIT:
+            if order.limit_price is None:
+                raise ValueError("Limit price required for limit orders")
+            return LimitOrderRequest(**common, limit_price=float(order.limit_price))
+        if order.order_type == OrderType.STOP:
+            if order.stop_price is None:
+                raise ValueError("Stop price required for stop orders")
+            return StopOrderRequest(**common, stop_price=float(order.stop_price))
+        if order.order_type == OrderType.STOP_LIMIT:
+            if order.limit_price is None or order.stop_price is None:
+                raise ValueError("Stop and limit price required for stop_limit")
+            return StopLimitOrderRequest(
+                **common,
+                stop_price=float(order.stop_price),
+                limit_price=float(order.limit_price),
+            )
+        raise ValueError(f"Unsupported order type: {order.order_type}")
+
+    def _map_tif(self, tif: TimeInForce) -> Any:
+        m = {
+            TimeInForce.DAY: AlpacaTimeInForce.DAY,
+            TimeInForce.GTC: AlpacaTimeInForce.GTC,
+            TimeInForce.IOC: AlpacaTimeInForce.IOC,
+            TimeInForce.FOK: AlpacaTimeInForce.FOK,
+            TimeInForce.OPG: AlpacaTimeInForce.OPG,
+            TimeInForce.CLS: AlpacaTimeInForce.CLS,
+        }
+        return m.get(tif, AlpacaTimeInForce.DAY)
+
+    async def submit(self, order: OrderRequest) -> OrderResponse:
+        _alpaca_required()
+        try:
+            alpaca_req = self._build_order_request(order)
+            alpaca_order = await asyncio.to_thread(
+                self._client.submit_order,
+                alpaca_req,
+            )
+            return OrderResponse(
+                success=True,
+                external_order_id=str(alpaca_order.id),
+                client_order_id=alpaca_order.client_order_id,
+                status=_map_status(alpaca_order.status.value if alpaca_order.status else None),
+                raw={
+                    "id": str(alpaca_order.id),
+                    "status": getattr(alpaca_order.status, "value", None),
+                },
+            )
+        except Exception as e:
+            logger.exception("Alpaca submit failed")
+            return OrderResponse(
+                success=False,
+                client_order_id=order.client_order_id,
+                message=str(e),
+            )
+
+    async def get_status(self, external_order_id: str) -> OrderStatus:
+        _alpaca_required()
+        alpaca_order = await asyncio.to_thread(
+            self._client.get_order_by_id,
+            external_order_id,
+        )
+        side = Side.BUY if (alpaca_order.side and alpaca_order.side.value == "buy") else Side.SELL
+        return OrderStatus(
+            external_order_id=str(alpaca_order.id),
+            client_order_id=alpaca_order.client_order_id,
+            symbol=alpaca_order.symbol or "",
+            side=side,
+            status=_map_status(alpaca_order.status.value if alpaca_order.status else None),
+            quantity=Decimal(str(alpaca_order.qty)) if alpaca_order.qty else Decimal("0"),
+            filled_quantity=Decimal(str(alpaca_order.filled_qty))
+            if alpaca_order.filled_qty
+            else Decimal("0"),
+            filled_avg_price=Decimal(str(alpaca_order.filled_avg_price))
+            if alpaca_order.filled_avg_price
+            else None,
+            limit_price=Decimal(str(alpaca_order.limit_price))
+            if alpaca_order.limit_price
+            else None,
+            stop_price=Decimal(str(alpaca_order.stop_price)) if alpaca_order.stop_price else None,
+            created_at=alpaca_order.created_at,
+            updated_at=alpaca_order.updated_at,
+        )
+
+    async def cancel(self, external_order_id: str) -> CancelResponse:
+        _alpaca_required()
+        try:
+            await asyncio.to_thread(
+                self._client.cancel_order_by_id,
+                external_order_id,
+            )
+            return CancelResponse(success=True, external_order_id=external_order_id)
+        except Exception as e:
+            logger.exception("Alpaca cancel failed")
+            return CancelResponse(
+                success=False,
+                external_order_id=external_order_id,
+                message=str(e),
+            )
+
+    async def subscribe_fills(self, callback: Callable[[Fill], None]) -> None:
+        _alpaca_required()
+        self._fill_callback = callback
+        self._stream = TradingStream(
+            api_key=self._api_key,
+            secret_key=self._api_secret,
+            paper=self._paper,
+        )
+
+        @self._stream.subscribe_trade_updates  # type: ignore[untyped-decorator]
+        async def on_trade_update(data: Any) -> None:
+            event = getattr(data, "event", None)
+            if event not in ("fill", "partial_fill"):
+                return
+            if not self._fill_callback:
+                return
+            order = getattr(data, "order", None)
+            if not order:
+                return
+            fill_id = f"{getattr(order, 'id', '')}_{getattr(data, 'timestamp', '')}"
+            qty = getattr(data, "qty", None) or getattr(order, "filled_qty", 0)
+            price = getattr(data, "price", None) or getattr(order, "filled_avg_price", 0)
+            ts = getattr(data, "timestamp", None) or datetime.now(UTC)
+            side = (
+                Side.BUY
+                if (getattr(order, "side", None) and getattr(order.side, "value", "") == "buy")
+                else Side.SELL
+            )
+            fill = Fill(
+                fill_id=fill_id,
+                external_order_id=str(getattr(order, "id", "")),
+                client_order_id=getattr(order, "client_order_id", None),
+                symbol=getattr(order, "symbol", ""),
+                side=side,
+                quantity=Decimal(str(qty)),
+                price=Decimal(str(price)),
+                commission=None,
+                executed_at=ts,
+            )
+            self._fill_callback(fill)
+
+        self._stream_task = asyncio.create_task(self._run_stream())
+        logger.info("Subscribed to Alpaca trade updates")
+
+    async def _run_stream(self) -> None:
+        if not self._stream:
+            return
+        try:
+            await self._stream._run_forever()
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            logger.error("Alpaca stream error: %s", e)
+
+    async def close(self) -> None:
+        if self._stream_task:
+            self._stream_task.cancel()
+            try:
+                await self._stream_task
+            except asyncio.CancelledError:
+                pass
+            self._stream_task = None
+        if self._stream:
+            await self._stream.close()
+            self._stream = None
+        self._fill_callback = None
+        logger.debug("AlpacaExecutionClient closed")

pyactuator/adapters/base.py

@@ -0,0 +1,39 @@
+"""Abstract base for execution adapters."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+
+from pyactuator.types import CancelResponse, Fill, OrderRequest, OrderResponse, OrderStatus
+
+
+class BaseExecutionClient(ABC):
+    """Abstract base class for execution adapters.
+
+    Implements the ExecutionClient protocol; subclasses provide broker-specific
+    logic for submit, get_status, cancel, subscribe_fills, and close.
+    """
+
+    @abstractmethod
+    async def submit(self, order: OrderRequest) -> OrderResponse:
+        """Submit an order to the broker."""
+        ...
+
+    @abstractmethod
+    async def get_status(self, external_order_id: str) -> OrderStatus:
+        """Get current status of an order."""
+        ...
+
+    @abstractmethod
+    async def cancel(self, external_order_id: str) -> CancelResponse:
+        """Cancel an existing order."""
+        ...
+
+    async def subscribe_fills(self, callback: Callable[[Fill], None]) -> None:  # noqa: B027
+        """Subscribe to fill updates. Default: no-op (adapter may override)."""
+        pass
+
+    async def close(self) -> None:  # noqa: B027
+        """Release resources. Default: no-op (adapter may override)."""
+        pass

pyactuator/adapters/mock.py

@@ -0,0 +1,170 @@
+"""Mock/paper execution adapter for tests and paper trading."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from decimal import Decimal
+
+from pyactuator.adapters.base import BaseExecutionClient
+from pyactuator.types import (
+    CancelResponse,
+    Fill,
+    OrderRequest,
+    OrderResponse,
+    OrderStatus,
+    Side,
+)
+
+
+@dataclass
+class _MockOrder:
+    """In-memory order record."""
+
+    external_id: str
+    client_order_id: str
+    symbol: str
+    side: Side
+    quantity: Decimal
+    filled_quantity: Decimal
+    filled_avg_price: Decimal | None
+    limit_price: Decimal | None
+    stop_price: Decimal | None
+    status: str  # pending_new, open, filled, partially_filled, canceled, rejected
+    created_at: datetime
+    updated_at: datetime
+
+
+class MockExecutionClient(BaseExecutionClient):
+    """In-memory execution client for tests and paper trading.
+
+    submit() returns success with a generated external_order_id. Optionally
+    configure scripted fills (e.g. immediate full fill at a price) via
+    fill_style or a custom fill callback.
+    """
+
+    def __init__(
+        self,
+        *,
+        default_fill_price: Decimal | None = None,
+        immediate_fill: bool = True,
+        fill_callback: Callable[[OrderRequest, str], Fill | None] | None = None,
+    ) -> None:
+        """Initialize mock client.
+
+        Args:
+            default_fill_price: If set and immediate_fill is True, use this price for fills.
+            immediate_fill: If True, after submit we immediately "fill" the order (status=filled)
+                using default_fill_price or 0 if not set.
+            fill_callback: If set, called (order, external_id) after submit; if it returns a Fill,
+                that fill is recorded and (if subscribe_fills was used) the callback is invoked.
+        """
+        self._orders: dict[str, _MockOrder] = {}
+        self._fills: list[Fill] = []
+        self._fill_callback = fill_callback
+        self._default_fill_price = default_fill_price or Decimal("0")
+        self._immediate_fill = immediate_fill
+        self._subscribed_callback: Callable[[Fill], None] | None = None
+
+    async def submit(self, order: OrderRequest) -> OrderResponse:
+        external_id = str(uuid.uuid4())
+        now = datetime.now(UTC)
+        mock_order = _MockOrder(
+            external_id=external_id,
+            client_order_id=order.client_order_id,
+            symbol=order.symbol,
+            side=order.side,
+            quantity=order.quantity,
+            filled_quantity=Decimal("0"),
+            filled_avg_price=None,
+            limit_price=order.limit_price,
+            stop_price=order.stop_price,
+            status="open",
+            created_at=now,
+            updated_at=now,
+        )
+        self._orders[external_id] = mock_order
+
+        if self._immediate_fill:
+            fill = Fill(
+                fill_id=f"{external_id}-fill",
+                external_order_id=external_id,
+                client_order_id=order.client_order_id,
+                symbol=order.symbol,
+                side=order.side,
+                quantity=order.quantity,
+                price=self._default_fill_price,
+                commission=None,
+                executed_at=now,
+            )
+            mock_order.filled_quantity = order.quantity
+            mock_order.filled_avg_price = self._default_fill_price
+            mock_order.status = "filled"
+            mock_order.updated_at = now
+            self._fills.append(fill)
+            if self._subscribed_callback:
+                self._subscribed_callback(fill)
+        elif self._fill_callback:
+            custom_fill = self._fill_callback(order, external_id)
+            if custom_fill:
+                self._fills.append(custom_fill)
+                mock_order.filled_quantity = custom_fill.quantity
+                mock_order.filled_avg_price = custom_fill.price
+                mock_order.status = (
+                    "filled" if custom_fill.quantity >= order.quantity else "partially_filled"
+                )
+                mock_order.updated_at = custom_fill.executed_at or now
+                if self._subscribed_callback:
+                    self._subscribed_callback(custom_fill)
+
+        return OrderResponse(
+            success=True,
+            external_order_id=external_id,
+            client_order_id=order.client_order_id,
+            status=mock_order.status,
+        )
+
+    async def get_status(self, external_order_id: str) -> OrderStatus:
+        if external_order_id not in self._orders:
+            raise LookupError(f"Order not found: {external_order_id}")
+        o = self._orders[external_order_id]
+        return OrderStatus(
+            external_order_id=o.external_id,
+            client_order_id=o.client_order_id,
+            symbol=o.symbol,
+            side=o.side,
+            status=o.status,
+            quantity=o.quantity,
+            filled_quantity=o.filled_quantity,
+            filled_avg_price=o.filled_avg_price,
+            limit_price=o.limit_price,
+            stop_price=o.stop_price,
+            created_at=o.created_at,
+            updated_at=o.updated_at,
+        )
+
+    async def cancel(self, external_order_id: str) -> CancelResponse:
+        if external_order_id not in self._orders:
+            return CancelResponse(
+                success=False,
+                external_order_id=external_order_id,
+                message="Order not found",
+            )
+        o = self._orders[external_order_id]
+        if o.status in ("filled", "canceled", "rejected"):
+            return CancelResponse(
+                success=False,
+                external_order_id=external_order_id,
+                message=f"Order already {o.status}",
+            )
+        o.status = "canceled"
+        o.updated_at = datetime.now(UTC)
+        return CancelResponse(success=True, external_order_id=external_order_id)
+
+    async def subscribe_fills(self, callback: Callable[[Fill], None]) -> None:
+        self._subscribed_callback = callback
+
+    async def close(self) -> None:
+        self._subscribed_callback = None

pyactuator/client.py

@@ -0,0 +1,68 @@
+"""ExecutionClient protocol — interface implemented by all broker adapters."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Protocol, runtime_checkable
+
+from pyactuator.types import CancelResponse, Fill, OrderRequest, OrderResponse, OrderStatus
+
+
+@runtime_checkable
+class ExecutionClient(Protocol):
+    """Protocol for execution adapters.
+
+    All broker implementations (Alpaca, Mock, future IB/crypto) implement this
+    interface so the stack (pystator, OrderManager) stays broker-agnostic.
+    """
+
+    async def submit(self, order: OrderRequest) -> OrderResponse:
+        """Submit an order to the broker.
+
+        Args:
+            order: Order request with client_order_id, symbol, side, quantity, etc.
+
+        Returns:
+            OrderResponse with success, external_order_id, status, or rejection message.
+        """
+        ...
+
+    async def get_status(self, external_order_id: str) -> OrderStatus:
+        """Get current status of an order.
+
+        Args:
+            external_order_id: Broker's order ID.
+
+        Returns:
+            Normalized OrderStatus (symbol, side, status, filled_quantity, etc.).
+
+        Raises:
+            LookupError or broker-specific error if order not found.
+        """
+        ...
+
+    async def cancel(self, external_order_id: str) -> CancelResponse:
+        """Cancel an existing order.
+
+        Args:
+            external_order_id: Broker's order ID to cancel.
+
+        Returns:
+            CancelResponse with success and optional message.
+        """
+        ...
+
+    async def subscribe_fills(self, callback: Callable[[Fill], None]) -> None:
+        """Subscribe to execution (fill) updates.
+
+        Adapter-dependent: Alpaca uses TradingStream; mock may invoke callback
+        from scripted fills. Callback may be invoked from a background task.
+
+        Args:
+            callback: Function called when a fill is received (same event loop or thread).
+        """
+        ...
+
+    async def close(self) -> None:
+        """Release resources (streams, connections). Call when done with the client."""
+        ...

pyactuator/helpers/__init__.py

@@ -0,0 +1,13 @@
+"""Optional execution helpers: retry, idempotency."""
+
+from pyactuator.helpers.idempotency import (
+    generate_client_order_id,
+    validate_client_order_id,
+)
+from pyactuator.helpers.retry import RetryExecutionClient
+
+__all__ = [
+    "RetryExecutionClient",
+    "generate_client_order_id",
+    "validate_client_order_id",
+]

pyactuator/helpers/idempotency.py

@@ -0,0 +1,67 @@
+"""Idempotency key handling for execution.
+
+Alpaca (and many brokers) support client_order_id as the idempotency key:
+submitting the same client_order_id again is deduplicated. This module
+provides helpers to generate and validate idempotency keys so callers
+(e.g. pystator, OrderManager) pass a consistent key.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+
+# Alpaca allows max 128 characters for client_order_id
+MAX_CLIENT_ORDER_ID_LENGTH = 128
+
+
+def generate_client_order_id(
+    prefix: str = "pa",
+    *,
+    order_id: str | None = None,
+    event_id: str | None = None,
+    max_length: int = MAX_CLIENT_ORDER_ID_LENGTH,
+) -> str:
+    """Generate a client order ID suitable for idempotency.
+
+    Uses prefix + short hash of (order_id or event_id or uuid) so the same
+    logical order always yields the same client_order_id.
+
+    Args:
+        prefix: Short prefix (e.g. "pa" for pyactuator, "tc" for trading controller).
+        order_id: Optional order ID (e.g. from pystator or DB).
+        event_id: Optional event ID if no order_id.
+        max_length: Cap length (Alpaca: 128).
+
+    Returns:
+        String safe for use as client_order_id.
+    """
+    raw = order_id or event_id or str(uuid.uuid4())
+    h = hashlib.sha256(raw.encode()).hexdigest()[:16]
+    candidate = f"{prefix}-{h}"
+    if len(candidate) <= max_length:
+        return candidate
+    return candidate[:max_length]
+
+
+def validate_client_order_id(
+    client_order_id: str,
+    *,
+    max_length: int = MAX_CLIENT_ORDER_ID_LENGTH,
+    allowed_chars: str | None = None,
+) -> bool:
+    """Validate client_order_id length and optionally character set.
+
+    Args:
+        client_order_id: The ID to validate.
+        max_length: Max allowed length (default 128 for Alpaca).
+        allowed_chars: If set, only these characters are allowed (e.g. alphanumeric + hyphen).
+
+    Returns:
+        True if valid.
+    """
+    if len(client_order_id) > max_length or len(client_order_id) == 0:
+        return False
+    if allowed_chars is not None:
+        return all(c in allowed_chars for c in client_order_id)
+    return True

pyactuator/helpers/retry.py

@@ -0,0 +1,97 @@
+"""Optional retry policy for submit/cancel.
+
+Wrap an ExecutionClient to retry on transient failures (e.g. network errors).
+Do not retry on validation or rejection (success=False with message).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+from collections.abc import Callable
+
+from pyactuator.client import ExecutionClient
+from pyactuator.types import CancelResponse, Fill, OrderRequest, OrderResponse, OrderStatus
+
+logger = logging.getLogger(__name__)
+
+
+def _is_retryable_submit(response: OrderResponse) -> bool:
+    """True if we should retry (transient failure). False for rejections."""
+    if response.success:
+        return False
+    msg = (response.message or "").lower()
+    if "insufficient" in msg or "invalid" in msg or "reject" in msg or "not allowed" in msg:
+        return False
+    return True
+
+
+def _is_retryable_cancel(response: CancelResponse) -> bool:
+    if response.success:
+        return False
+    msg = (response.message or "").lower()
+    if "not found" in msg or "already" in msg:
+        return False
+    return True
+
+
+class RetryExecutionClient:
+    """Wraps an ExecutionClient with retry for submit and cancel."""
+
+    def __init__(
+        self,
+        client: ExecutionClient,
+        *,
+        max_attempts: int = 3,
+        base_delay: float = 1.0,
+        max_delay: float = 30.0,
+        retry_submit: bool = True,
+        retry_cancel: bool = True,
+    ) -> None:
+        self._client = client
+        self._max_attempts = max_attempts
+        self._base_delay = base_delay
+        self._max_delay = max_delay
+        self._retry_submit = retry_submit
+        self._retry_cancel = retry_cancel
+
+    async def submit(self, order: OrderRequest) -> OrderResponse:
+        attempt = 0
+        while True:
+            response = await self._client.submit(order)
+            if (
+                not self._retry_submit
+                or not _is_retryable_submit(response)
+                or attempt >= self._max_attempts - 1
+            ):
+                return response
+            attempt += 1
+            delay = min(self._base_delay * (2**attempt), self._max_delay) * (0.5 + random.random())
+            logger.warning(
+                "Submit attempt %s returned retryable failure; retrying in %.2fs", attempt, delay
+            )
+            await asyncio.sleep(delay)
+
+    async def get_status(self, external_order_id: str) -> OrderStatus:
+        return await self._client.get_status(external_order_id)
+
+    async def cancel(self, external_order_id: str) -> CancelResponse:
+        attempt = 0
+        while True:
+            response = await self._client.cancel(external_order_id)
+            if (
+                not self._retry_cancel
+                or not _is_retryable_cancel(response)
+                or attempt >= self._max_attempts - 1
+            ):
+                return response
+            attempt += 1
+            delay = min(self._base_delay * (2**attempt), self._max_delay) * (0.5 + random.random())
+            await asyncio.sleep(delay)
+
+    async def subscribe_fills(self, callback: Callable[[Fill], None]) -> None:
+        await self._client.subscribe_fills(callback)
+
+    async def close(self) -> None:
+        await self._client.close()

pyactuator/types.py

@@ -0,0 +1,159 @@
+"""Core execution types: order request/response, status, fill, cancel."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import Decimal
+from enum import StrEnum
+from typing import Any
+
+
+class Side(StrEnum):
+    """Order side."""
+
+    BUY = "buy"
+    SELL = "sell"
+
+
+class OrderType(StrEnum):
+    """Order type."""
+
+    MARKET = "market"
+    LIMIT = "limit"
+    STOP = "stop"
+    STOP_LIMIT = "stop_limit"
+
+
+class TimeInForce(StrEnum):
+    """Order time in force."""
+
+    DAY = "day"
+    GTC = "gtc"
+    IOC = "ioc"
+    FOK = "fok"
+    OPG = "opg"
+    CLS = "cls"
+
+
+@dataclass
+class OrderRequest:
+    """Request to submit an order to the broker.
+
+    Attributes:
+        client_order_id: Our internal order ID (also used as idempotency key; max 128 chars for Alpaca).
+        symbol: Trading symbol (e.g. "AAPL").
+        side: Buy or sell.
+        quantity: Order quantity.
+        order_type: Market, limit, stop, stop_limit.
+        time_in_force: Day, GTC, IOC, FOK, OPG, CLS.
+        limit_price: Limit price (required for limit/stop_limit).
+        stop_price: Stop price (required for stop/stop_limit).
+        extended_hours: If true, order eligible for premarket/afterhours (Alpaca: limit + day only).
+    """
+
+    client_order_id: str
+    symbol: str
+    side: Side
+    quantity: Decimal
+    order_type: OrderType = OrderType.MARKET
+    time_in_force: TimeInForce = TimeInForce.DAY
+    limit_price: Decimal | None = None
+    stop_price: Decimal | None = None
+    extended_hours: bool = False
+
+
+@dataclass
+class OrderResponse:
+    """Response from order submission.
+
+    Attributes:
+        success: Whether the order was accepted by the broker.
+        external_order_id: Broker's order ID.
+        client_order_id: Our client order ID.
+        status: Initial order status from broker (e.g. pending, open, accepted).
+        message: Optional message (e.g. rejection reason).
+        raw: Raw broker response for debugging.
+    """
+
+    success: bool
+    external_order_id: str | None = None
+    client_order_id: str | None = None
+    status: str = "pending"
+    message: str | None = None
+    raw: dict[str, Any] | None = None
+
+
+@dataclass
+class OrderStatus:
+    """Normalized order status (from get_status).
+
+    Attributes:
+        external_order_id: Broker's order ID.
+        client_order_id: Our client order ID.
+        symbol: Trading symbol.
+        side: Buy or sell.
+        status: pending_new, open, filled, partially_filled, canceled, rejected, expired.
+        quantity: Order quantity.
+        filled_quantity: Filled quantity so far.
+        filled_avg_price: Average fill price.
+        limit_price: Limit price if applicable.
+        stop_price: Stop price if applicable.
+        created_at: Order creation time.
+        updated_at: Last update time.
+    """
+
+    external_order_id: str
+    client_order_id: str | None
+    symbol: str
+    side: Side
+    status: str
+    quantity: Decimal
+    filled_quantity: Decimal
+    filled_avg_price: Decimal | None
+    limit_price: Decimal | None
+    stop_price: Decimal | None
+    created_at: datetime | None
+    updated_at: datetime | None
+
+
+@dataclass
+class Fill:
+    """Execution (fill) report from broker.
+
+    Attributes:
+        fill_id: Broker's execution/fill ID.
+        external_order_id: Broker's order ID.
+        client_order_id: Our client order ID.
+        symbol: Trading symbol.
+        side: Buy or sell.
+        quantity: Fill quantity.
+        price: Fill price.
+        commission: Commission charged (optional).
+        executed_at: Execution timestamp.
+    """
+
+    fill_id: str
+    external_order_id: str
+    client_order_id: str | None
+    symbol: str
+    side: Side
+    quantity: Decimal
+    price: Decimal
+    commission: Decimal | None = None
+    executed_at: datetime | None = None
+
+
+@dataclass
+class CancelResponse:
+    """Response from order cancellation.
+
+    Attributes:
+        success: Whether the cancel was accepted.
+        external_order_id: Broker's order ID.
+        message: Optional message.
+    """
+
+    success: bool
+    external_order_id: str | None = None
+    message: str | None = None

pyactuator-0.0.1.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: pyactuator
+Version: 0.0.1
+Summary: Thin broker-agnostic execution layer for trading: order submission, status, and fills
+Author-email: StatFYI <contact@statfyi.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/statfyi/pyactuator
+Project-URL: Documentation, https://github.com/statfyi/pyactuator#readme
+Project-URL: Repository, https://github.com/statfyi/pyactuator
+Project-URL: Issues, https://github.com/statfyi/pyactuator/issues
+Project-URL: Changelog, https://github.com/statfyi/pyactuator/blob/main/CHANGELOG.md
+Keywords: trading,execution,broker,alpaca,order,finance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: alpaca
+Requires-Dist: alpaca-py>=0.14.0; extra == "alpaca"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.5; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+
+# pyactuator
+
+Thin broker-agnostic execution layer for trading systems: submit orders, poll status, cancel, and (optionally) subscribe to fills. Designed to sit between your FSM/OMS (e.g. pystator) and broker APIs (Alpaca, future IB/crypto).
+
+## Features
+
+- **Normalized types**: `OrderRequest`, `OrderResponse`, `OrderStatus`, `Fill` — your stack stays broker-agnostic.
+- **ExecutionClient protocol**: One interface (`submit`, `get_status`, `cancel`, optional `subscribe_fills`) implemented per broker.
+- **Adapters**: Alpaca (via alpaca-py), Mock (in-memory for tests and paper).
+- **Optional helpers**: Retry policy, idempotency key handling, timeout wrapper.
+
+## Installation
+
+```bash
+# Core only (types, protocol, mock adapter)
+pip install pyactuator
+
+# With Alpaca broker support
+pip install pyactuator[alpaca]
+
+# Development
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from decimal import Decimal
+from pyactuator import ExecutionClient, OrderRequest, Side, OrderType, TimeInForce
+from pyactuator.adapters.mock import MockExecutionClient
+
+# Use mock for tests or paper
+client: ExecutionClient = MockExecutionClient()
+
+order = OrderRequest(
+    client_order_id="my-order-001",
+    symbol="AAPL",
+    side=Side.BUY,
+    quantity=Decimal("10"),
+    order_type=OrderType.MARKET,
+    time_in_force=TimeInForce.DAY,
+)
+response = await client.submit(order)
+print(response.success, response.external_order_id)
+
+status = await client.get_status(response.external_order_id)
+await client.close()
+```
+
+With Alpaca (requires `pip install pyactuator[alpaca]`):
+
+```python
+from pyactuator.adapters.alpaca import AlpacaExecutionClient
+
+client = AlpacaExecutionClient(
+    api_key="...",
+    api_secret="...",
+    paper=True,
+)
+# Same OrderRequest / submit / get_status / cancel
+```
+
+Optional retry wrapper and idempotency helpers:
+
+```python
+from pyactuator.helpers import RetryExecutionClient, generate_client_order_id
+from pyactuator.adapters.alpaca import AlpacaExecutionClient
+
+client = AlpacaExecutionClient(api_key="...", api_secret="...", paper=True)
+client = RetryExecutionClient(client, max_attempts=3)
+order_id = generate_client_order_id(prefix="pa", order_id="my-internal-id")
+order = OrderRequest(client_order_id=order_id, symbol="AAPL", side=Side.BUY, quantity=Decimal("10"), ...)
+```
+
+## Integration with pystator
+
+Your FSM or OrderManager receives an `ExecutionClient` (injected or constructed). When the FSM triggers "submit" (e.g. after risk approval via pyfortis), call `await client.submit(order_request)`. pystator stays broker-agnostic; execution is behind this single interface.
+
+## License
+
+MIT.

pyactuator-0.0.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+pyactuator/__init__.py,sha256=zmoc51-mhcTxq5z_g9ZpclVfTpBa4YN4-AUY1o-t7bM,457
+pyactuator/client.py,sha256=eFNT1XyLNXNHC-TK3IL6qhjuEHeygx-D9QWjddU2GdM,2121
+pyactuator/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyactuator/types.py,sha256=OcvDyI9ujlt4nB1IAZHDnHbIndnndh1t0E3z6JUDqIE,4170
+pyactuator/adapters/__init__.py,sha256=PmysjZH8TejJzDPgagV1Fi3tm4EF6DD80ylhvOXMOAY,236
+pyactuator/adapters/alpaca.py,sha256=6gm9OTd3W1HbjnI0QYOGMtoEcrsrifWOItXzzmhtzug,9956
+pyactuator/adapters/base.py,sha256=bvld5i6YS6AvkH5FhhABFzxQp-YOYAeK51Ya5a5H4y4,1250
+pyactuator/adapters/mock.py,sha256=3dPh-S-Nl0CM8NVrfG4H5R5FqdAzGL3ygZcY8dQhvP0,6162
+pyactuator/helpers/__init__.py,sha256=muY47fUNtFsycmtZD8lEO-iGdduv3ZihWND5OuvsCz8,327
+pyactuator/helpers/idempotency.py,sha256=fQON1CgsRkPFKK5XN8ikloJswbsKr3aZ6DipPyrbw9M,2115
+pyactuator/helpers/retry.py,sha256=NruWZG9K8ROf-iuZQ6fuMut3qBmP2VIAZBuU219fhvY,3242
+pyactuator-0.0.1.dist-info/METADATA,sha256=XwtdJSK6903y4DOpv-Jj1oUoD7D191vnnjbJO7pqHJc,4176
+pyactuator-0.0.1.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+pyactuator-0.0.1.dist-info/top_level.txt,sha256=op74AikGGPFvoHjaSIz8-1iXgH4g9vSOLIyjlMdiUV4,11
+pyactuator-0.0.1.dist-info/RECORD,,

pyactuator-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyactuator-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyactuator