pyactuator 0.0.5__tar.gz

pyactuator-0.0.5/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: pyactuator
+Version: 0.0.5
+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.5/README.md

@@ -0,0 +1,81 @@
+# 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.5/pyproject.toml

@@ -0,0 +1,121 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyactuator"
+version = "0.0.5"
+description = "Thin broker-agnostic execution layer for trading: order submission, status, and fills"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "StatFYI", email = "contact@statfyi.com" },
+]
+keywords = [
+    "trading",
+    "execution",
+    "broker",
+    "alpaca",
+    "order",
+    "finance",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+    "Topic :: Office/Business :: Financial",
+]
+
+[project.urls]
+Homepage = "https://github.com/statfyi/pyactuator"
+Documentation = "https://github.com/statfyi/pyactuator#readme"
+Repository = "https://github.com/statfyi/pyactuator"
+Issues = "https://github.com/statfyi/pyactuator/issues"
+Changelog = "https://github.com/statfyi/pyactuator/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+# pip install pyactuator             → core only (types, protocol, mock adapter)
+# pip install pyactuator[alpaca]     → + Alpaca broker adapter
+# pip install pyactuator[dev]        → testing & release
+alpaca = ["alpaca-py>=0.14.0"]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.4.0",
+    "mypy>=1.5",
+    "pre-commit>=3.0",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["pyactuator*"]
+
+[tool.setuptools.package-data]
+pyactuator = ["py.typed"]
+
+# --- Lint & format (ruff) ---
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+"tests/*" = ["B008"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+# --- Type checking ---
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+exclude = ["tests/"]
+
+[[tool.mypy.overrides]]
+module = ["alpaca.*"]
+ignore_missing_imports = true
+
+# --- Tests ---
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+addopts = ["-v", "--strict-markers", "--tb=short"]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: integration tests",
+    "unit: unit tests",
+]
+filterwarnings = ["error", "ignore::UserWarning"]
+
+# --- Coverage ---
+[tool.coverage.run]
+source = ["src/pyactuator"]
+omit = ["*/tests/*", "*/__pycache__/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+]

pyactuator-0.0.5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyactuator-0.0.5/src/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-0.0.5/src/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-0.0.5/src/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-0.0.5/src/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