retrade 0.1.1__py3-none-any.whl

retrade/__init__.py

@@ -0,0 +1,66 @@
+"""reTrade's executor-side SDK."""
+
+from retrade.adapter import ApprovedOrder, BrokerAdapter, GenericAdapter
+from retrade.client import DEFAULT_BASE_URL, Client, LogRecord, Placement, Result
+from retrade.errors import (
+    BrokerRejected,
+    ConfigError,
+    InvalidInput,
+    RequestRefused,
+    ReTradeError,
+    Unreachable,
+    VerificationFailed,
+)
+from retrade.keys import KeyFileError, generate_key, load_key
+from retrade.model import (
+    Adjustment,
+    AdjustmentKind,
+    Fx,
+    Intent,
+    OpenOrder,
+    Order,
+    OrderType,
+    Position,
+    Quote,
+    Side,
+    Snapshot,
+    Tif,
+)
+from retrade.protocol import Mode, Outcome
+from retrade.webhook import verify_webhook
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "Adjustment",
+    "AdjustmentKind",
+    "ApprovedOrder",
+    "BrokerAdapter",
+    "BrokerRejected",
+    "Client",
+    "ConfigError",
+    "Fx",
+    "GenericAdapter",
+    "Intent",
+    "InvalidInput",
+    "KeyFileError",
+    "LogRecord",
+    "Mode",
+    "OpenOrder",
+    "Order",
+    "OrderType",
+    "Outcome",
+    "Placement",
+    "Position",
+    "Quote",
+    "ReTradeError",
+    "RequestRefused",
+    "Result",
+    "Side",
+    "Snapshot",
+    "Tif",
+    "Unreachable",
+    "VerificationFailed",
+    "generate_key",
+    "load_key",
+    "verify_webhook",
+]

retrade/adapter.py

@@ -0,0 +1,99 @@
+"""The broker adapter: the SDK's only contact with a broker (DESIGN 5.1). It runs in the client's executor, with the
+client's own broker connection. reTrade never connects to a broker."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import Decimal
+from typing import Protocol
+
+from retrade.errors import InvalidInput
+from retrade.model import OrderType, Quote, Side, Snapshot, Tif
+
+DEFAULT_G_SECONDS = 60
+MAX_G_SECONDS = 3600  # reTrade's account register caps G at one hour (API.md 14.3)
+
+
+@dataclass(frozen=True, slots=True)
+class ApprovedOrder:
+    """The order exactly as reTrade approved it. The SDK builds it from a verified decision; an adapter places these
+    fields and nothing else."""
+
+    instrument: str
+    side: Side
+    quantity: int
+    type: OrderType
+    tif: Tif
+    limit_price: Decimal | None
+
+
+class BrokerAdapter(Protocol):
+    """What the SDK needs from a broker.
+
+    `g_seconds` is how long the broker takes to show a new order in its account data (ARITHMETIC 2.3, G), 1 to 3600.
+    `converts_cash` says whether the broker converts currency automatically when an order needs it. Both must equal
+    the account's settings at reTrade, which the owner confirmed at onboarding.
+    """
+
+    # Read-only, so a frozen dataclass such as GenericAdapter, or a class attribute, satisfies the protocol.
+    @property
+    def g_seconds(self) -> int: ...
+
+    @property
+    def converts_cash(self) -> bool: ...
+
+    def snapshot(self, instrument: str | None, adjustments_since: datetime | None) -> tuple[Snapshot, Quote | None]:
+        """Read the account now from the broker and, when `instrument` is given, a quote for it. Called for every
+        decision; never built from model output.
+
+        The snapshot must carry settled cash. It should carry the USDCAD rate when the broker has one, and the
+        deposits, withdrawals, dividends, fees, transfers and splits since `adjustments_since` (the account's last
+        accepted snapshot; None when there is none). Without them, a large change in the account blocks new buys
+        until an owner confirms it.
+
+        Every resting market buy needs a price, which reTrade takes from a position's mark (ARITHMETIC 3.1, 3.7). For
+        a market buy of an instrument the account doesn't hold, include a position of 0 shares with the current mark;
+        without one, a buy whose rules count that order is BLOCK `STATE-INCOMPLETE`."""
+        ...
+
+    def submit(self, order: ApprovedOrder, tag: str) -> str:
+        """Place `order` with `tag` in the broker's client-order-id field and return the broker order id.
+
+        Raise BrokerRejected only when the broker definitively refused the order. Raise anything else, or let the
+        broker client's own exception through, when the outcome is unknown (a timeout, a dropped connection, a 5xx).
+        The SDK never retries a submit."""
+        ...
+
+    def find(self, tag: str, order: ApprovedOrder, since: datetime) -> str | None:
+        """Look up an order whose submit outcome is unknown, and return its broker order id, or None if it isn't
+        visible. Search by `tag`; where the broker doesn't keep tags, match `order`'s fields among orders placed
+        since `since`. None never means "not placed": the broker may not show the order yet."""
+        ...
+
+    def cancel(self, broker_order_id: str) -> None:
+        """Cancel a working order. Return once the broker has accepted the cancel request; raise if it refused it or
+        the outcome is unknown."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class GenericAdapter:
+    """An adapter made of four plain functions, so any broker works without a ready-made adapter. Each function has
+    the signature of the BrokerAdapter method of the same name. `converts_cash` defaults to False, the cautious
+    setting: reTrade then also checks cash in the order's own currency."""
+
+    snapshot: Callable[[str | None, datetime | None], tuple[Snapshot, Quote | None]]
+    submit: Callable[[ApprovedOrder, str], str]
+    find: Callable[[str, ApprovedOrder, datetime], str | None]
+    cancel: Callable[[str], None]
+    g_seconds: int = DEFAULT_G_SECONDS
+    converts_cash: bool = False
+
+    def __post_init__(self) -> None:
+        if (not isinstance(self.g_seconds, int) or isinstance(self.g_seconds, bool)
+                or not 1 <= self.g_seconds <= MAX_G_SECONDS):
+            raise InvalidInput(f"g_seconds must be an int from 1 to {MAX_G_SECONDS}")
+        if not isinstance(self.converts_cash, bool):
+            raise InvalidInput("converts_cash must be a bool")

retrade/cli.py

@@ -0,0 +1,55 @@
+"""The `retrade` command."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from retrade.keys import KeyFileError, generate_key
+from retrade.kit import ClaimKit
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="retrade")
+    commands = parser.add_subparsers(dest="command", required=True)
+    keygen = commands.add_parser("keygen", help="create an executor key")
+    keygen.add_argument("path", help="where to write the private key; it must not exist yet")
+    claim = commands.add_parser("claim-kit", help="print the evidence for one decision, for a claim")
+    claim.add_argument("decision_id")
+    claim.add_argument("--state-dir", default="retrade-state", help="the Client's state_dir (default: %(default)s)")
+    args = parser.parse_args(argv)
+
+    if args.command == "claim-kit":
+        return claim_kit(Path(args.state_dir), args.decision_id)
+    try:
+        public = generate_key(args.path)
+    except KeyFileError as error:
+        print(f"retrade: {error}", file=sys.stderr)
+        return 1
+    print(f"Private key written to {args.path}. Keep it secret; it never leaves this machine.")
+    print("Register this public key in reTrade's onboarding:")
+    print(public)
+    return 0
+
+
+def claim_kit(state_dir: Path, decision_id: str) -> int:
+    path = state_dir / "claim-kit.sqlite3"
+    if not path.exists():
+        print(f"retrade: no claim kit at {path}", file=sys.stderr)
+        return 1
+    kit = ClaimKit(path)
+    try:
+        exported = kit.export(decision_id)
+    finally:
+        kit.close()
+    if exported is None:
+        print(f"retrade: no decision {decision_id} in {path}", file=sys.stderr)
+        return 1
+    print(json.dumps(exported, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())