qjtrader 0.1.0__py3-none-any.whl

qjtrader/__init__.py

@@ -0,0 +1,60 @@
+"""qjtrader — the official Python client for the QJ Trader AI Trading APIs.
+
+Stream real-time Canadian market data and send orders over one authenticated
+connection. Get a free sandbox key (no approval) at https://console.qjtrader.ai
+and set ``QJ_CLIENT_ID`` / ``QJ_CLIENT_SECRET``:
+
+    import qjtrader
+    client = qjtrader.Client()
+    with client.orders() as oe:
+        print(oe.order_and_wait(sym="MX:CRAU26", side="buy", qty=1,
+                                price=97.00, account="SIM", tif="ioc"))
+
+Docs: https://docs.qjtrader.ai/docs/ai
+"""
+from __future__ import annotations
+
+from ._version import __version__
+from .autotools import REGISTRY as AUTO_TOOLS, Scalper, make_auto_tool
+from .backtest import BacktestReport, run_backtest, synthetic_bars
+from .client import (
+    Client,
+    MARKET_DATA_SCOPE,
+    ORDERS_SCOPE,
+)
+from .errors import AuthError, ConnectionClosed, QJError, TokenError
+from .market_data import MarketData
+from .orders import Orders
+from .rest import RestClient
+from .run import LiveContext, Supervisor, load_strategy, run_strategy_live
+from .runner import RunRegistry
+from .strategy import Context, PositionBook, Strategy
+
+__all__ = [
+    "Client",
+    "MarketData",
+    "Orders",
+    "RestClient",
+    "QJError",
+    "TokenError",
+    "AuthError",
+    "ConnectionClosed",
+    "MARKET_DATA_SCOPE",
+    "ORDERS_SCOPE",
+    # strategy contract + run venues (§10)
+    "Strategy",
+    "Context",
+    "PositionBook",
+    "run_backtest",
+    "synthetic_bars",
+    "BacktestReport",
+    "Supervisor",
+    "LiveContext",
+    "load_strategy",
+    "run_strategy_live",
+    "RunRegistry",
+    "Scalper",
+    "make_auto_tool",
+    "AUTO_TOOLS",
+    "__version__",
+]

qjtrader/_cli.py

@@ -0,0 +1,201 @@
+"""Command-line interface: ``qjtrader <command>``.
+
+Credentials come from QJ_CLIENT_ID / QJ_CLIENT_SECRET (or --client-id/--secret).
+
+    export QJ_CLIENT_ID=... QJ_CLIENT_SECRET=...
+    qjtrader subscribe CA:RY MX:CRAU26 --watch 30
+    qjtrader order --sym MX:CRAU26 --side buy --qty 1 --price 97.00 --account SIM --tif ioc
+    qjtrader status
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .client import Client
+from .errors import ConnectionClosed, QJError
+
+
+def _client(a: argparse.Namespace) -> Client:
+    return Client(
+        client_id=a.client_id, client_secret=a.client_secret,
+        token_url=a.token_url, data_host=a.data_host, orders_host=a.orders_host,
+        ca_file=a.ca, verify=not a.insecure,
+    )
+
+
+def _common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--client-id")
+    p.add_argument("--client-secret")
+    p.add_argument("--token-url")
+    p.add_argument("--data-host")
+    p.add_argument("--orders-host")
+    p.add_argument("--ca", help="CA/cert file to pin (pilot order endpoint)")
+    p.add_argument("--insecure", action="store_true", help="skip TLS verification (dev only)")
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="qjtrader", description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--version", action="version", version=f"qjtrader {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    ps = sub.add_parser("subscribe", help="stream market data for symbols")
+    ps.add_argument("symbols", nargs="+", help="e.g. CA:RY CA:RY.PT MX:CRAU26")
+    ps.add_argument("--depth", type=int)
+    ps.add_argument("--watch", type=float, default=60.0)
+    _common(ps)
+
+    po = sub.add_parser("order", help="submit a limit order")
+    po.add_argument("--sym", required=True)
+    po.add_argument("--side", required=True, choices=["buy", "sell"])
+    po.add_argument("--qty", type=int, required=True)
+    po.add_argument("--price", type=float, required=True)
+    po.add_argument("--tif", default="day", choices=["day", "ioc", "fok"])
+    po.add_argument("--account", default="")
+    po.add_argument("--iceberg", type=int, default=0)
+    po.add_argument("--cid")
+    po.add_argument("--watch", type=float, default=15.0)
+    _common(po)
+
+    pc = sub.add_parser("cancel", help="cancel an order by its cid")
+    pc.add_argument("--orig", required=True)
+    pc.add_argument("--watch", type=float, default=10.0)
+    _common(pc)
+
+    pst = sub.add_parser("status", help="show open orders + session state")
+    _common(pst)
+    pca = sub.add_parser("cancel-all", help="cancel every open order")
+    _common(pca)
+
+    pb = sub.add_parser("backtest", help="run a strategy file over synthetic/offline bars")
+    pb.add_argument("strategy", help="path to a .py file with a Strategy subclass")
+    pb.add_argument("--symbol", required=True, help="e.g. MX:CRAU26")
+    pb.add_argument("--bars", type=int, default=390, help="number of synthetic bars")
+    pb.add_argument("--interval", type=int, default=60, help="bar seconds")
+    pb.add_argument("--seed", type=int, help="synthetic seed (reproducible day)")
+    pb.add_argument("--param", action="append", default=[],
+                    help="strategy param key=value (repeatable)")
+
+    pr = sub.add_parser("run", help="run a strategy against a live/paper credential")
+    pr.add_argument("strategy", help="path to a .py file with a Strategy subclass")
+    pr.add_argument("--symbols", nargs="+", required=True)
+    pr.add_argument("--tag", default="strat", help="strategy tag on every order")
+    pr.add_argument("--account", default="")
+    pr.add_argument("--param", action="append", default=[])
+    _common(pr)
+
+    a = p.parse_args(argv)
+    if a.cmd == "backtest":
+        return _cmd_backtest(a)
+    if a.cmd == "run":
+        return _cmd_run(a)
+    try:
+        client = _client(a)
+        if a.cmd == "subscribe":
+            with client.market_data() as md:
+                print(f"# authenticated as {md.user}; subscribing {a.symbols}", file=sys.stderr)
+                md.subscribe(a.symbols, depth=a.depth)
+                try:
+                    for msg in md.messages(timeout=a.watch):
+                        print(json.dumps(msg))
+                except ConnectionClosed:
+                    print("# server closed the connection", file=sys.stderr)
+        elif a.cmd == "order":
+            with client.orders() as oe:
+                print(f"# authenticated as {oe.user}", file=sys.stderr)
+                cid = oe.order(sym=a.sym, side=a.side, qty=a.qty, price=a.price,
+                               tif=a.tif, account=a.account, iceberg=a.iceberg, cid=a.cid)
+                print(f"# submitted cid={cid}", file=sys.stderr)
+                _drain(oe, a.watch)
+        elif a.cmd == "cancel":
+            with client.orders() as oe:
+                oe.cancel(a.orig)
+                _drain(oe, a.watch)
+        elif a.cmd == "cancel-all":
+            with client.orders() as oe:
+                oe.cancel_all()
+                _drain(oe, 5.0)
+        elif a.cmd == "status":
+            with client.orders() as oe:
+                print(json.dumps(oe.status(), indent=2))
+    except QJError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _parse_params(items: list[str]) -> dict:
+    out: dict = {}
+    for it in items:
+        k, _, v = it.partition("=")
+        try:
+            out[k] = json.loads(v)      # numbers/bools/JSON pass through
+        except ValueError:
+            out[k] = v                   # plain string
+    return out
+
+
+def _load_strategy_or_autotool(spec: str):
+    """A .py file path, or the name of a built-in auto-tool (e.g. 'scalper')."""
+    from .autotools import REGISTRY, make_auto_tool
+    from .run import load_strategy
+    if spec in REGISTRY:
+        return make_auto_tool(spec)
+    return load_strategy(spec)
+
+
+def _cmd_backtest(a: argparse.Namespace) -> int:
+    from .backtest import run_backtest, synthetic_bars
+    try:
+        strat = _load_strategy_or_autotool(a.strategy)
+    except QJError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    bars = synthetic_bars(a.symbol, a.bars, interval_s=a.interval, seed=a.seed)
+    params = _parse_params(a.param)
+    params.setdefault("symbol", a.symbol)     # so auto-tools scope to the tested symbol
+    report = run_backtest(strat, bars, params=params)
+    report.pop("equity_curve", None)     # keep stdout compact; PnL summary remains
+    print(json.dumps(report, indent=2, default=str))
+    return 0
+
+
+def _cmd_run(a: argparse.Namespace) -> int:
+    import signal
+    import threading
+
+    from .run import run_strategy_live
+    stop = threading.Event()
+    signal.signal(signal.SIGINT, lambda *_: stop.set())
+    try:
+        client = _client(a)
+        print(f"# running {a.strategy} on {a.symbols} (tag={a.tag}); Ctrl-C to stop",
+              file=sys.stderr)
+        run_strategy_live(client, a.strategy, symbols=a.symbols,
+                          params=_parse_params(a.param), account=a.account,
+                          strategy_tag=a.tag, stop=stop)
+    except QJError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _drain(oe: object, watch: float) -> None:
+    try:
+        for msg in oe.updates(timeout=watch):  # type: ignore[attr-defined]
+            print(json.dumps(msg))
+            if msg.get("type") == "order_update" and msg.get("status") in (
+                "filled", "canceled", "rejected", "replaced",
+            ):
+                return
+            if msg.get("type") == "exec" and msg.get("status") == "filled":
+                return
+    except ConnectionClosed:
+        print("# connection closed", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

qjtrader/_stream.py

@@ -0,0 +1,128 @@
+"""Shared NDJSON-over-TLS stream: connect, authenticate, read messages.
+
+Both APIs speak the same wire contract — one JSON object per line, UTF-8,
+newline-terminated, over TLS; the first line the client sends is
+``{"action": "auth", "token": <jwt>}`` and the server replies
+``{"type": "auth_success", ...}``. This class carries that for both.
+"""
+from __future__ import annotations
+
+import json
+import select
+import socket
+import ssl
+import time
+from typing import Any, Iterator
+
+from .auth import TokenSource
+from .errors import AuthError, ConnectionClosed
+
+_CLOSED = object()
+
+
+class _Stream:
+    """A single TLS connection carrying newline-delimited JSON."""
+
+    def __init__(self, token_source: TokenSource, host: str, port: int, *,
+                 ca_file: str | None = None, verify: bool = True,
+                 timeout: float = 15.0) -> None:
+        self._ts = token_source
+        self._host = host
+        self._port = port
+        self._ca_file = ca_file
+        self._verify = verify
+        self._timeout = timeout
+        self._sock: ssl.SSLSocket | None = None
+        self._buf = bytearray()
+        #: The authenticated principal (client_id), set after connect().
+        self.user: str | None = None
+
+    # -- lifecycle ---------------------------------------------------------
+    def connect(self) -> "_Stream":
+        """Open the TLS connection and complete the auth handshake."""
+        if self._verify:
+            ctx = ssl.create_default_context(cafile=self._ca_file)
+        else:  # pilot/dev only — never in production
+            ctx = ssl.create_default_context()
+            ctx.check_hostname = False
+            ctx.verify_mode = ssl.CERT_NONE
+        raw = socket.create_connection((self._host, self._port), timeout=self._timeout)
+        self._sock = ctx.wrap_socket(raw, server_hostname=self._host)
+        try:
+            self._authenticate()
+        except BaseException:
+            self.close()
+            raise
+        return self
+
+    def _authenticate(self) -> dict[str, Any]:
+        self.send({"action": "auth", "token": self._ts.token()})
+        line = self._read_line(time.monotonic() + self._timeout)
+        if line is None or line is _CLOSED:
+            raise AuthError("no auth response (timeout or connection closed)")
+        ack = json.loads(line)
+        if ack.get("type") != "auth_success":
+            raise AuthError(f"auth rejected: {ack.get('message') or ack}")
+        self.user = ack.get("user")
+        return ack
+
+    def close(self) -> None:
+        if self._sock is not None:
+            try:
+                self._sock.close()
+            except OSError:
+                pass
+            self._sock = None
+
+    def __enter__(self) -> "_Stream":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- io ----------------------------------------------------------------
+    def send(self, obj: dict[str, Any]) -> None:
+        """Send one JSON message."""
+        assert self._sock is not None, "not connected"
+        self._sock.sendall(json.dumps(obj).encode() + b"\n")
+
+    def _read_line(self, deadline: float) -> bytes | None | object:
+        """One line, or None on this-slice timeout, or _CLOSED on close."""
+        while True:
+            nl = self._buf.find(b"\n")
+            if nl >= 0:
+                line = bytes(self._buf[:nl])
+                del self._buf[: nl + 1]
+                return line
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return None
+            r, _, _ = select.select([self._sock], [], [], min(remaining, 1.0))
+            if not r:
+                continue
+            try:
+                chunk = self._sock.recv(1 << 16)  # type: ignore[union-attr]
+            except ssl.SSLWantReadError:
+                continue
+            if not chunk:
+                return _CLOSED
+            self._buf.extend(chunk)
+
+    def messages(self, timeout: float | None = None,
+                 include_heartbeats: bool = False) -> Iterator[dict[str, Any]]:
+        """Yield decoded messages until `timeout` seconds elapse (or forever if
+        None). Raises :class:`ConnectionClosed` if the server closes the stream."""
+        deadline = time.monotonic() + timeout if timeout is not None else float("inf")
+        while time.monotonic() < deadline:
+            line = self._read_line(deadline)
+            if line is None:
+                continue
+            if line is _CLOSED:
+                raise ConnectionClosed("server closed the connection")
+            try:
+                msg = json.loads(line)
+            except ValueError:
+                continue
+            if msg.get("type") == "heartbeat" and not include_heartbeats:
+                continue
+            yield msg

qjtrader/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

qjtrader/auth.py

@@ -0,0 +1,63 @@
+"""OAuth2 client-credentials token source.
+
+A credential mints its own short-lived JWT (the console never hands out tokens).
+`TokenSource` fetches one on demand and caches it until shortly before expiry, so
+callers can just ask for `.token()` every time.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from .errors import TokenError
+
+_REFRESH_SKEW = 60.0  # refresh this many seconds before expiry
+
+
+class TokenSource:
+    """Mints and caches an access token for one (credential, scope)."""
+
+    def __init__(self, token_url: str, client_id: str, client_secret: str,
+                 scope: str) -> None:
+        self._url = token_url
+        self._cid = client_id
+        self._secret = client_secret
+        self._scope = scope
+        self._token: str | None = None
+        self._expires_at = 0.0
+
+    def token(self) -> str:
+        """A valid access token, refreshed automatically before it expires."""
+        if self._token and time.time() < self._expires_at - _REFRESH_SKEW:
+            return self._token
+
+        body = urllib.parse.urlencode(
+            {"grant_type": "client_credentials", "scope": self._scope}
+        ).encode()
+        basic = base64.b64encode(f"{self._cid}:{self._secret}".encode()).decode()
+        req = urllib.request.Request(
+            self._url,
+            data=body,
+            headers={
+                "Authorization": f"Basic {basic}",
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=15) as resp:
+                data = json.loads(resp.read())
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", "replace")[:300]
+            raise TokenError(f"token request failed (HTTP {e.code}): {detail}") from None
+        except urllib.error.URLError as e:
+            raise TokenError(f"token request failed: {e.reason}") from None
+        except (ValueError, KeyError):
+            raise TokenError("token endpoint returned an unexpected response") from None
+
+        self._token = data["access_token"]
+        self._expires_at = time.time() + float(data.get("expires_in", 3600))
+        return self._token

qjtrader/autotools.py

@@ -0,0 +1,80 @@
+"""Auto-tools — hardened, parameterized strategies (plan §10.2).
+
+The WinForms AutoTool family (Legger, Scalper, RangerF) is 15 years of evidence
+that most traders **parameterize a hardened automation through a form** and only
+sometimes write code. Auto-tools are that: shipped `Strategy` subclasses configured
+by params, no user code — which also makes them trivially hostable (no arbitrary
+code to sandbox), quietly solving the hosted-runner problem for most users.
+
+The LLM bridges the spectrum (§10.2): its output can be a *parameter set* for one
+of these ("this idea is a scalper with edge=0.05, target=0.10") or new code when
+no template fits. Every auto-tool runs unmodified in backtest / paper / live.
+"""
+from __future__ import annotations
+
+from .strategy import Strategy
+
+# name -> Strategy subclass (used by the CLI/MCP to run an auto-tool by name)
+REGISTRY: dict[str, type] = {}
+
+
+def _register(name: str):
+    def deco(cls):
+        REGISTRY[name] = cls
+        return cls
+    return deco
+
+
+@_register("scalper")
+class Scalper(Strategy):
+    """Rest a bid below the market; on a fill, rest an exit above cost for a small
+    profit; scale in up to ``max_position``. Params (all optional):
+
+        symbol        restrict to one symbol (else trades every symbol it sees)
+        size          lots per entry            (default 1)
+        edge          rest the entry this far below the close   (default 0.05)
+        target        take profit this far above the fill/close (default 0.05)
+        max_position  max net long lots          (default 3)
+    """
+
+    def on_start(self, ctx):
+        self.symbol = ctx.param("symbol")
+        self.size = int(ctx.param("size", 1))
+        self.edge = float(ctx.param("edge", 0.05))
+        self.target = float(ctx.param("target", 0.05))
+        self.max_position = int(ctx.param("max_position", 3))
+        self.entry_cid: str | None = None
+        self.exit_cid: str | None = None
+
+    def _mine(self, sym: str) -> bool:
+        return self.symbol is None or sym == self.symbol
+
+    def on_bar(self, ctx, bar):
+        sym = bar["symbol"]
+        close = bar.get("close")
+        if not self._mine(sym) or close is None:
+            return
+        pos = ctx.position(sym)
+        # entry: rest a bid below the market while we have room to add
+        if pos < self.max_position and not self.entry_cid:
+            self.entry_cid = ctx.buy(sym, self.size, round(close - self.edge, 4))
+        # exit: while long, keep a fresh take-profit sell for the whole position
+        if pos > 0:
+            if self.exit_cid:
+                ctx.cancel(self.exit_cid)
+            self.exit_cid = ctx.sell(sym, pos, round(close + self.target, 4))
+        elif self.exit_cid:
+            ctx.cancel(self.exit_cid)
+            self.exit_cid = None
+
+    def on_fill(self, ctx, fill):
+        cid = fill.get("cid")
+        if cid == self.entry_cid:
+            self.entry_cid = None      # free the entry slot to scale in again
+        if cid == self.exit_cid:
+            self.exit_cid = None
+
+
+def make_auto_tool(name: str) -> Strategy:
+    """Instantiate a registered auto-tool by name (raises KeyError if unknown)."""
+    return REGISTRY[name]()