Updraft: Quality-Trend 3 automated paper strategy + live page

.github/workflows/updraft-keepalive.yml

@@ -0,0 +1,36 @@
+name: Updraft keep-alive and check
+
+# Daily (incl. weekends) so the free Space never reaches HF's 48-hour sleep, and so the ranking is rebuilt each
+# morning. Fails the run (= an email from GitHub) if the Space reports a problem: missing keys, a ranking older
+# than 3 days, or a data-build error.
+on:
+  schedule:
+    - cron: "30 12 * * *"
+  workflow_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Wake and check
+        env:
+          URL: ${{ secrets.UPDRAFT_URL || 'https://s-ttp-updraft.hf.space' }}
+        run: |
+          for i in $(seq 1 40); do
+            CODE=$(curl -s -o /tmp/h.json -w '%{http_code}' --max-time 30 "$URL/api/health" || echo 000)
+            [ "$CODE" = "200" ] && break; echo "attempt $i: $CODE"; sleep 15
+          done
+          [ "$CODE" = "200" ] || { echo "::error::Space not reachable"; exit 1; }
+          cat /tmp/h.json; echo
+          curl -s --max-time 120 "$URL/api/ranking" -o /tmp/r.json
+          python3 - <<'PY'
+          import json, sys
+          h, r = json.load(open("/tmp/h.json")), json.load(open("/tmp/r.json"))
+          problems = [k for k in ("data_key", "alpaca_keys", "rebalance_enabled") if not h.get(k)]
+          err = (h.get("ranking_state") or {}).get("error")
+          if err: problems.append("ranking build error: " + err)
+          if r.get("age_hours", 0) > 72 and not r.get("building"): problems.append(f"ranking {r.get('age_hours')} h old")
+          print("prices to", r.get("prices_as_of"), "· pool", r.get("pool"), "· top 3", [x["ticker"] for x in (r.get("ranked") or [])[:3]])
+          if problems:
+              print("::error::" + "; ".join(problems)); sys.exit(1)
+          PY

.github/workflows/updraft-rebalance.yml

@@ -0,0 +1,54 @@
+name: Updraft rebalance
+
+# Fires every weekday at 15:00 UTC (mid-morning New York, always market hours). The Space guards it: it trades
+# only while the market is open, on one of the first 5 trading days of a month, once per month, on a ranking
+# built from data at most 5 days old — so in practice it trades on the first trading day of each month and
+# returns "executed: false" every other day. Also runnable by hand from the Actions tab ("force" overrides the
+# once-a-month / window guards, never the market-open or data-freshness guards).
+#
+# Free Spaces sleep after 48 h idle and a cold start can take minutes ("Internal server error" from HF's
+# gateway meanwhile), so the job wakes the Space first and retries the POST. The POST is idempotent.
+on:
+  schedule:
+    - cron: "0 15 * * 1-5"
+  workflow_dispatch:
+    inputs:
+      force:
+        description: "Rebalance now even if already done this month / outside the window"
+        type: boolean
+        default: false
+
+concurrency: updraft-rebalance
+
+jobs:
+  rebalance:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Wake the Space
+        env:
+          URL: ${{ secrets.UPDRAFT_URL || 'https://s-ttp-updraft.hf.space' }}
+        run: |
+          for i in $(seq 1 40); do
+            CODE=$(curl -s -o /dev/null -w '%{http_code}' --max-time 30 "$URL/api/health" || echo 000)
+            echo "attempt $i: /api/health -> $CODE"
+            [ "$CODE" = "200" ] && { echo "Space is awake."; exit 0; }
+            sleep 15
+          done
+          echo "::error::Space did not wake within ~10 minutes"; exit 1
+
+      - name: Trigger rebalance (retries on gateway errors)
+        env:
+          URL: ${{ secrets.UPDRAFT_URL || 'https://s-ttp-updraft.hf.space' }}
+          REBALANCE_TOKEN: ${{ secrets.UPDRAFT_REBALANCE_TOKEN }}
+          FORCE: ${{ inputs.force && '1' || '0' }}
+        run: |
+          for i in $(seq 1 5); do
+            RESP=$(curl -s -w $'\n%{http_code}' --max-time 300 -X POST "$URL/api/rebalance?dry=0&force=$FORCE" \
+              -H "X-Rebalance-Token: $REBALANCE_TOKEN")
+            CODE=$(printf '%s' "$RESP" | tail -1); BODY=$(printf '%s' "$RESP" | sed '$d')
+            echo "attempt $i: HTTP $CODE"; echo "$BODY" | python3 -m json.tool 2>/dev/null || echo "$BODY"
+            [ "$CODE" = "200" ] && exit 0
+            [ "$CODE" = "403" ] && { echo "::error::token rejected — check UPDRAFT_REBALANCE_TOKEN"; exit 1; }
+            echo "transient HTTP $CODE — retrying in 30s"; sleep 30
+          done
+          echo "::error::rebalance did not return 200 after retries"; exit 1

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.env
+.pytest_cache/

Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+ENV PYTHONUNBUFFERED=1 PIP_NO_CACHE_DIR=1 QT3_CACHE=/tmp/qt3
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# HF recommends a non-root user (uid 1000). The ranking cache lives in /tmp (rebuilt after a restart).
+RUN useradd -m -u 1000 app
+COPY --chown=app:app . .
+USER app
+
+EXPOSE 7860
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,61 @@
 ---
 title: Updraft
-emoji: 📈
-colorFrom: gray
-colorTo: indigo
+emoji: 🪁
+colorFrom: red
+colorTo: yellow
 sdk: docker
+app_port: 7860
 pinned: false
+short_description: Rides the strongest quality stocks; 3 names, monthly
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🪁 Updraft
+
+*The Quality-Trend 3 strategy, running on its own.*
+
+Three large US stocks with strong **quality and capital discipline** and the strongest **price trends**, held on an
+Alpaca **paper** account and rebalanced automatically once a month. The page shows the live portfolio, growth vs the
+S&P 500 since the first trade, the trade log and this month's ranking.
+
+**Rule** (backtested in the RS-VCP / Quant Model research, `scripts/finalize_qt3_managed.py`):
+1. Universe — the 1,000 largest US companies by market cap; price ≥ $5; ≥ $5M a day traded; US-dollar statements.
+2. Quality pool — top 30% of a capital-discipline composite: basic-diluted gap, quality score (ROE, ROA, gross margin,
+   FCF conversion), −equity financing, FCF yield, ROE, buyback yield, net share reduction.
+3. Trend — the pool ranked by 0.5 · pct(MA50/MA200) + 0.5 · pct(6-1-month return).
+4. Monthly — keep holdings still ranked in the top 6, sell the rest, buy from the top until 3 are held, re-split
+   equally (1% kept in cash). Sells first, waited for, then buys sized to the cash actually available (no margin).
+
+Backtest 1999-08 → 2026-09, after 10 bps per side, point-in-time lists incl. delisted names: **+30.9%/yr** (S&P +8.5%),
+worst fall −34%, any 12 months median +24% (in profit 87% of the time). Backtests flatter; expect less.
+
+## How it runs without a PC
+- **Data** — each day the Space builds the ranking itself from the Sharadar API (Nasdaq Data Link, ~40 requests,
+  ~70 s). It reproduces the research snapshot exactly (verified 2026-10-13: same top 10, same 250-name pool).
+- **Trading** — `POST /api/rebalance?dry=0` with `X-Rebalance-Token`. It trades only when **all** hold: market open;
+  one of the first 5 trading days of the month (or the very first run); not already rebalanced this month; ranking
+  data ≤ 5 days old. Every other call is a harmless no-op. Orders carry `client_order_id = qt3-YYYYMMDD-SYM-side`,
+  so a retried call cannot duplicate them.
+- **Schedule** — GitHub Actions (free): `.github/workflows/updraft-rebalance.yml` every weekday 15:00 UTC (wakes the
+  Space, then POSTs the rebalance with retries) and `updraft-keepalive.yml` daily (keeps the free Space from sleeping,
+  rebuilds the ranking, fails the run — an email — on missing keys or stale data).
+- **State** — all in Alpaca (positions, orders, portfolio history). A restart only rebuilds the ranking cache.
+
+## Settings (Space → Settings → Variables and secrets)
+| Secret | Purpose |
+|---|---|
+| `NASDAQ_DATA_LINK_API_KEY` | Sharadar data for the ranking |
+| `ALPACA_API_KEY_ID`, `ALPACA_API_SECRET_KEY` | the **paper** account this Space manages (use a dedicated account) |
+| `REBALANCE_TOKEN` | a long random string; the same value goes into the GitHub secret `UPDRAFT_REBALANCE_TOKEN` |
+
+Optional variables: `ALPACA_DATA_FEED` (default `iex`), `CASH_BUFFER` (0.01), `QT3_INCEPTION` (YYYY-MM-DD for the
+public stats). **Live trading** is off unless both `ALPACA_PAPER=false` and `ALPACA_ALLOW_LIVE=yes` are set.
+
+## API
+Public: `GET /` page · `/api/health` · `/api/status` · `/api/portfolio` · `/api/performance` · `/api/orders` ·
+`/api/ranking` · `/api/plan` (dry-run of what a rebalance would do now). Private (token): `POST /api/rebalance?dry=0`
+(`force=1` overrides only the window / once-a-month guards) · `POST /api/refresh` (rebuild the ranking now).
+
+## Notes
+Educational paper-trading demonstration — not investment advice. The page shows derived rankings only, not raw
+Sharadar data. Each stock is a third of the money: one stock halving costs ~17%. Taxes and slippage beyond 10 bps
+are not modelled.

app.py

@@ -0,0 +1,177 @@
+"""Updraft (the Quality-Trend 3 strategy) — automated monthly strategy on an Alpaca paper account, with a public live page.
+
+Public (read-only): GET /, /api/health, /api/status, /api/portfolio, /api/performance, /api/orders,
+/api/ranking, /api/plan (dry-run of what a rebalance would do now).
+Private: POST /api/rebalance?dry=0 and POST /api/refresh with header X-Rebalance-Token: <REBALANCE_TOKEN>.
+A daily GitHub Action calls /api/rebalance; the Space trades only on the first trading days of a month (once),
+while the market is open, on a ranking built from data at most 5 days old.
+"""
+from __future__ import annotations
+
+import time
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+
+from fastapi import FastAPI, Header, HTTPException
+from fastapi.responses import FileResponse
+from starlette.concurrency import run_in_threadpool
+
+from qt3 import config, performance, ranking, rebalance
+from qt3.broker import Alpaca, BrokerError
+
+@asynccontextmanager
+async def lifespan(_app):
+    if config.NDL_KEY:
+        ranking.refresh_async()              # build today's ranking in the background at start-up
+    yield
+
+
+app = FastAPI(title="Updraft", lifespan=lifespan)
+STATIC = Path(__file__).parent / "static"
+_cache: dict = {}
+
+
+def cached(key: str, ttl: float, fn):
+    hit = _cache.get(key)
+    if hit and time.time() - hit[0] < ttl:
+        return hit[1]
+    val = fn()
+    _cache[key] = (time.time(), val)
+    return val
+
+
+def broker() -> Alpaca:
+    if not (config.ALPACA_KEY and config.ALPACA_SECRET):
+        raise HTTPException(503, "Alpaca keys are not configured on this Space")
+    return Alpaca()
+
+
+def _authorised(token: str) -> None:
+    if not config.REBALANCE_TOKEN or token != config.REBALANCE_TOKEN:
+        raise HTTPException(403, "rebalance disabled or bad token (set REBALANCE_TOKEN, send X-Rebalance-Token)")
+
+
+@app.get("/")
+def index():
+    return FileResponse(STATIC / "index.html")
+
+
+@app.get("/api/health")
+def health():
+    return {"ok": True, **config.status(), "ranking_state": ranking.state()}
+
+
+@app.get("/api/ranking")
+def get_ranking():
+    if config.NDL_KEY:
+        ranking.refresh_async()
+    r = ranking.cached() or {}
+    return {**r, "rule": {"names": config.N, "keep_within": config.KEEP, "pool": f"top {round((1 - config.POOL) * 100)}%"},
+            "building": ranking.state()["building"], "age_hours": round(ranking.age_hours(r or None), 1)}
+
+
+@app.get("/api/portfolio")
+async def portfolio():
+    def load():
+        a = broker()
+        acct, pos = a.account(), a.positions()
+        rk = {r["ticker"]: r for r in (ranking.cached() or {}).get("ranked", [])}
+        rows = []
+        for s, p in sorted(pos.items(), key=lambda x: -x[1]["market_value"]):
+            r = rk.get(s, {})
+            rows.append({"symbol": s, "name": r.get("name"), "sector": r.get("sector"), "qty": p["qty"],
+                         "price": p["price"], "value": p["market_value"],
+                         "weight": p["market_value"] / acct["equity"] if acct["equity"] else None,
+                         "pl": p["unrealized_pl"], "pl_pct": p["unrealized_plpc"], "today": p["change_today"],
+                         "rank_now": r.get("rank")})
+        return {"paper": a.paper, "equity": acct["equity"], "cash": acct["cash"],
+                "today_change": acct["equity"] - acct["last_equity"] if acct["last_equity"] else None,
+                "today_pct": acct["equity"] / acct["last_equity"] - 1 if acct["last_equity"] else None,
+                "positions": rows, "as_of": datetime.now(timezone.utc).isoformat(timespec="seconds")}
+    try:
+        return await run_in_threadpool(cached, "portfolio", 30, load)
+    except BrokerError as e:
+        raise HTTPException(502, str(e))
+
+
+@app.get("/api/performance")
+async def perf():
+    try:
+        return await run_in_threadpool(cached, "performance", 600, lambda: performance.series(broker()))
+    except BrokerError as e:
+        raise HTTPException(502, str(e))
+
+
+@app.get("/api/orders")
+async def orders():
+    def load():
+        a = broker()
+        out = []
+        for o in a.orders(status="all"):
+            if not str(o.get("client_order_id", "")).startswith(config.TAG + "-"):
+                continue
+            out.append({"date": (o.get("filled_at") or o.get("submitted_at") or "")[:10], "symbol": o.get("symbol"),
+                        "side": o.get("side"), "qty": o.get("filled_qty") or o.get("qty"),
+                        "notional": o.get("notional"), "price": o.get("filled_avg_price"), "status": o.get("status")})
+        return out[:200]
+    try:
+        return await run_in_threadpool(cached, "orders", 120, load)
+    except BrokerError as e:
+        raise HTTPException(502, str(e))
+
+
+@app.get("/api/status")
+async def status():
+    def load():
+        a = broker()
+        chk = rebalance.check(a, ranking.cached())
+        clk = a.clock()
+        nxt = str(datetime.now(rebalance.NY).date()) if (chk["in_window"] or chk["first_run"]) and not chk["done_this_month"] \
+            else chk["next_rebalance"]
+        return {"market_open": bool(clk.get("is_open")), "next_open": clk.get("next_open"),
+                "next_rebalance": nxt, "done_this_month": chk["done_this_month"], "first_run": chk["first_run"],
+                "would_trade_now": chk["ok"], "blocked_by": chk["reasons"], **config.status()}
+    try:
+        return await run_in_threadpool(cached, "status", 60, load)
+    except BrokerError as e:
+        raise HTTPException(502, str(e))
+
+
+@app.get("/api/plan")
+async def dry_plan():
+    r = ranking.cached()
+    if not r:
+        raise HTTPException(503, "ranking not built yet")
+    try:
+        return await run_in_threadpool(cached, "plan", 120, lambda: rebalance.build_plan(broker(), r))
+    except (BrokerError, ValueError) as e:
+        raise HTTPException(502, str(e))
+
+
+@app.post("/api/refresh")
+async def force_refresh(x_rebalance_token: str = Header(default="")):
+    _authorised(x_rebalance_token)
+    r = await run_in_threadpool(ranking.refresh, True)
+    return {"prices_as_of": (r or {}).get("prices_as_of"), "error": ranking.state()["error"]}
+
+
+@app.post("/api/rebalance")
+async def run_rebalance(dry: int = 1, force: int = 0, x_rebalance_token: str = Header(default="")):
+    """Dry-run by default. A real run needs dry=0 and the token; it then refreshes the ranking if needed,
+    checks the guards (market open, rebalance window, once a month, fresh data) and executes."""
+    r = await run_in_threadpool(ranking.refresh)
+    if dry:
+        return {"dry_run": True, **(await dry_plan())}
+    _authorised(x_rebalance_token)
+    a = broker()
+    chk = await run_in_threadpool(rebalance.check, a, r, None, bool(force))
+    if not chk["ok"]:
+        return {"dry_run": False, "executed": False, "reasons": chk["reasons"]}
+    try:
+        p = await run_in_threadpool(rebalance.build_plan, a, r)
+        res = await run_in_threadpool(rebalance.execute, a, p)
+    except (BrokerError, ValueError) as e:
+        raise HTTPException(502, f"rebalance failed: {e}")
+    _cache.clear()
+    return {"dry_run": False, "executed": True, "plan": p, "results": res}

qt3/broker.py

@@ -0,0 +1,132 @@
+"""Alpaca REST v2 (trading + market data) via requests. Keys come from config; never logged."""
+from __future__ import annotations
+
+import time
+from datetime import date, datetime, timezone
+from typing import Optional
+
+import requests
+
+from . import config
+
+PAPER_URL, LIVE_URL, DATA_URL = "https://paper-api.alpaca.markets", "https://api.alpaca.markets", \
+    "https://data.alpaca.markets"
+
+
+class BrokerError(RuntimeError):
+    pass
+
+
+class Alpaca:
+    def __init__(self, key: str = "", secret: str = "", paper: Optional[bool] = None,
+                 session: Optional[requests.Session] = None, feed: Optional[str] = None):
+        self.paper = config.ALPACA_PAPER if paper is None else paper
+        self.base = PAPER_URL if self.paper else LIVE_URL
+        self.feed = feed or config.DATA_FEED
+        self.s = session or requests.Session()
+        self.s.headers.update({"APCA-API-KEY-ID": key or config.ALPACA_KEY,
+                               "APCA-API-SECRET-KEY": secret or config.ALPACA_SECRET})
+
+    def _req(self, method: str, path: str, base: Optional[str] = None, **kw):
+        r = self.s.request(method, (base or self.base) + path, timeout=30, **kw)
+        if r.status_code >= 400:
+            try:
+                msg = r.json().get("message", r.text)
+            except ValueError:
+                msg = r.text
+            raise BrokerError(f"{method} {path} → {r.status_code}: {str(msg)[:200]}")
+        return r.json() if r.content else {}
+
+    # ---------------------------------------------------------------- reads
+    def account(self) -> dict:
+        a = self._req("GET", "/v2/account")
+        f = lambda k: float(a.get(k) or 0)
+        return {"number": a.get("account_number", ""), "status": a.get("status", ""), "equity": f("equity"),
+                "last_equity": f("last_equity"), "cash": f("cash"), "buying_power": f("buying_power"),
+                "non_marginable_buying_power": f("non_marginable_buying_power"),
+                "blocked": bool(a.get("trading_blocked") or a.get("account_blocked"))}
+
+    def positions(self) -> dict[str, dict]:
+        out = {}
+        for p in self._req("GET", "/v2/positions"):
+            out[p["symbol"]] = {"qty": float(p.get("qty") or 0), "price": float(p.get("current_price") or 0),
+                                "market_value": float(p.get("market_value") or 0),
+                                "cost_basis": float(p.get("cost_basis") or 0),
+                                "unrealized_pl": float(p.get("unrealized_pl") or 0),
+                                "unrealized_plpc": float(p.get("unrealized_plpc") or 0),
+                                "change_today": float(p.get("change_today") or 0)}
+        return out
+
+    def clock(self) -> dict:
+        return self._req("GET", "/v2/clock")
+
+    def trading_days(self, start: date, end: date) -> list[str]:
+        return [d["date"] for d in self._req("GET", "/v2/calendar", params={"start": str(start), "end": str(end)})]
+
+    def orders(self, after: Optional[datetime] = None, status: str = "all", limit: int = 500) -> list[dict]:
+        p = {"status": status, "limit": limit, "direction": "desc"}
+        if after:
+            p["after"] = after.astimezone(timezone.utc).isoformat()
+        return self._req("GET", "/v2/orders", params=p)
+
+    def order(self, oid: str) -> dict:
+        return self._req("GET", f"/v2/orders/{oid}")
+
+    def assets(self, symbols: list[str]) -> dict[str, dict]:
+        out = {}
+        for s in sorted(set(symbols)):
+            a = self._req("GET", f"/v2/assets/{s}")
+            out[s] = {"tradable": bool(a.get("tradable")), "fractionable": bool(a.get("fractionable"))}
+        return out
+
+    def latest_prices(self, symbols: list[str]) -> dict[str, float]:
+        if not symbols:
+            return {}
+        j = self._req("GET", "/v2/stocks/trades/latest", base=DATA_URL,
+                      params={"symbols": ",".join(sorted(set(symbols))), "feed": self.feed})
+        return {s: float(t["p"]) for s, t in (j.get("trades") or {}).items() if t.get("p")}
+
+    def daily_bars(self, symbol: str, start: date) -> list[dict]:
+        out, token = [], None
+        while True:
+            p = {"timeframe": "1Day", "start": str(start), "limit": 10000, "adjustment": "all", "feed": self.feed}
+            if token:
+                p["page_token"] = token
+            j = self._req("GET", f"/v2/stocks/{symbol}/bars", base=DATA_URL, params=p)
+            out += [{"t": b["t"][:10], "c": float(b["c"])} for b in (j.get("bars") or [])]
+            token = j.get("next_page_token")
+            if not token:
+                return out
+
+    def portfolio_history(self, period: str = "all", timeframe: str = "1D") -> dict:
+        return self._req("GET", "/v2/account/portfolio/history",
+                         params={"period": period, "timeframe": timeframe, "extended_hours": "false"})
+
+    def cash_flows(self) -> list[dict]:
+        """Deposits / withdrawals (for time-weighted returns)."""
+        try:
+            acts = self._req("GET", "/v2/account/activities", params={"activity_types": "CSD,CSW", "page_size": 100})
+        except BrokerError:
+            return []
+        return [{"date": a.get("date", "")[:10], "amount": float(a.get("net_amount") or 0)} for a in acts]
+
+    # ---------------------------------------------------------------- writes
+    def submit(self, symbol: str, side: str, qty: Optional[float] = None, notional: Optional[float] = None,
+               client_order_id: Optional[str] = None) -> dict:
+        body = {"symbol": symbol, "side": side, "type": "market", "time_in_force": "day"}
+        if notional is not None:
+            body["notional"] = f"{notional:.2f}"
+        else:
+            body["qty"] = f"{qty:.9f}".rstrip("0").rstrip(".")
+        if client_order_id:
+            body["client_order_id"] = client_order_id
+        return self._req("POST", "/v2/orders", json=body)
+
+    def wait(self, ids: list[str], seconds: float = 60.0, poll: float = 2.0) -> dict[str, dict]:
+        end, last = time.time() + seconds, {}
+        while ids and time.time() < end:
+            last = {i: self.order(i) for i in ids}
+            if all(o.get("status") in ("filled", "canceled", "rejected", "expired") for o in last.values()):
+                break
+            time.sleep(poll)
+        return last

qt3/config.py

@@ -0,0 +1,36 @@
+"""Settings for the Updraft Space (Quality-Trend 3 strategy). Secrets come from the Space's "Variables and secrets" settings
+(never from the repo): NASDAQ_DATA_LINK_API_KEY, ALPACA_API_KEY_ID, ALPACA_API_SECRET_KEY, REBALANCE_TOKEN."""
+from __future__ import annotations
+
+import os
+
+NDL_KEY = os.getenv("NASDAQ_DATA_LINK_API_KEY", "")
+ALPACA_KEY = os.getenv("ALPACA_API_KEY_ID", "")
+ALPACA_SECRET = os.getenv("ALPACA_API_SECRET_KEY", "")
+# Paper unless BOTH ALPACA_PAPER=false and ALPACA_ALLOW_LIVE=yes are set.
+ALPACA_PAPER = os.getenv("ALPACA_PAPER", "true").strip().lower() != "false" or \
+    os.getenv("ALPACA_ALLOW_LIVE", "").strip().lower() != "yes"
+DATA_FEED = os.getenv("ALPACA_DATA_FEED", "iex")
+REBALANCE_TOKEN = os.getenv("REBALANCE_TOKEN", "")
+
+# The backtested rule (Quant Model scripts/finalize_qt3_managed.py)
+N, KEEP = 3, 6                      # hold 3; keep a holding while it ranks in the top 6
+TOPN, MIN_PRICE, MIN_DV = 1000, 5.0, 5e6
+POOL = 0.70                         # quality pool = top 30% of the capital-discipline composite
+QCD = ["basic_diluted_gap", "quality_score", "equity_financing_neg", "fcf_yield", "roe", "buyback_yield",
+       "net_share_reduction_yoy"]
+
+# Execution
+CASH_BUFFER = float(os.getenv("CASH_BUFFER", "0.01"))   # keep 1% cash for fills / drift
+MIN_TRADE = float(os.getenv("MIN_TRADE", "25"))         # skip adjustments smaller than this ($) …
+BAND = float(os.getenv("REBALANCE_BAND", "0.02"))       # … or smaller than 2% of a position's target
+TAG = "qt3"                                             # client_order_id prefix of this strategy's orders
+
+CACHE_DIR = os.getenv("QT3_CACHE", "/tmp/qt3")
+RANKING_MAX_AGE_H = float(os.getenv("RANKING_MAX_AGE_H", "20"))
+INCEPTION = os.getenv("QT3_INCEPTION", "")              # YYYY-MM-DD for public stats; default = first order
+
+
+def status() -> dict:
+    return {"data_key": bool(NDL_KEY), "alpaca_keys": bool(ALPACA_KEY and ALPACA_SECRET),
+            "paper": ALPACA_PAPER, "rebalance_enabled": bool(REBALANCE_TOKEN)}

qt3/fundamental.py

@@ -0,0 +1,73 @@
+"""The quality / capital-discipline inputs, ported unchanged from the research code
+(Quant Model qmodel/features/fundamental.py, only the fields the rule uses).
+
+Input: one ticker's SF1 ARQ rows, sorted by the date each quarter became public (`reported_date`).
+Flows are summed over the trailing four quarters; balance-sheet items are as of the quarter."""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+_FLOWS = ["revenue", "cor", "gp", "opinc", "ebitda", "netinc", "rnd", "sbcomp", "ncfo", "fcf", "ncfcommon",
+          "ncfdiv", "depamor", "capex", "sgna"]
+SF1_COLS = ["ticker", "dimension", "calendardate", "datekey", "reportperiod", "marketcap", "equity", "assets",
+            "netinc", "fcf", "ncfcommon", "ncfdiv", "shareswa", "shareswadil", "gp", "revenue", "cor", "opinc",
+            "ebitda", "rnd", "sbcomp", "ncfo", "depamor", "capex", "sgna", "ev", "epsdil", "debt", "receivables",
+            "inventory", "payables", "cashneq", "roa"]
+
+
+def _safe(numer, denom):
+    d = denom.replace(0, np.nan) if hasattr(denom, "replace") else denom
+    return numer / d
+
+
+def compute_fundamental(sf1: pd.DataFrame) -> pd.DataFrame:
+    if sf1.empty:
+        return pd.DataFrame()
+    df = sf1.sort_values("reported_date").set_index("reported_date").copy()
+    for c in df.columns:
+        if c not in {"ticker", "dimension", "fiscal_date_ending", "calendardate"}:
+            df[c] = pd.to_numeric(df[c], errors="coerce")
+    for c in _FLOWS:
+        if c not in df:
+            df[c] = np.nan
+    ttm = {c: df[c].rolling(4, min_periods=4).sum() for c in _FLOWS}
+    mc = df["marketcap"].replace(0, np.nan)
+    out = pd.DataFrame(index=df.index)
+    out["earnings_yield"] = _safe(ttm["netinc"], mc)
+    out["fcf_yield"] = _safe(ttm["fcf"], mc)
+    out["gross_margin"] = _safe(ttm["gp"], ttm["revenue"])
+    out["roe"] = _safe(ttm["netinc"], df["equity"])
+    out["roa"] = _safe(ttm["netinc"], df["assets"])
+    out["buyback_yield"] = _safe(-ttm["ncfcommon"], mc)
+    # research code ran pandas 2.x pct_change (forward-fill first); made explicit so pandas 3 gives the same
+    out["net_share_reduction_yoy"] = -df["shareswadil"].ffill().pct_change(4, fill_method=None)
+    out["basic_diluted_gap"] = _safe(df["shareswadil"] - df["shareswa"], df["shareswa"])
+    out["rd_intensity"] = _safe(ttm["rnd"], ttm["revenue"])
+    out["fcf_conversion"] = _safe(ttm["fcf"], ttm["netinc"])
+    out["equity_financing"] = _safe(ttm["ncfcommon"], df["assets"])
+    return out
+
+
+def latest_inputs(sf1: pd.DataFrame) -> pd.DataFrame:
+    """Latest quality inputs per ticker from SF1 ARQ rows (as known today: the latest version of each
+    quarter, in calendar order) — the live snapshot's `fundamentals()` logic."""
+    if sf1.empty:
+        return pd.DataFrame(columns=["ticker"])
+    s = sf1.copy()
+    for c in SF1_COLS:
+        if c in s and c not in ("ticker", "dimension", "calendardate", "datekey", "reportperiod"):
+            s[c] = pd.to_numeric(s[c], errors="coerce")
+    s["datekey"], s["calendardate"] = pd.to_datetime(s["datekey"]), pd.to_datetime(s["calendardate"])
+    rows = []
+    for t, g in s[s["dimension"] == "ARQ"].groupby("ticker"):
+        g = g.sort_values("datekey").drop_duplicates("calendardate", keep="last").sort_values("calendardate")
+        g = g.assign(reported_date=g["datekey"].cummax(), fiscal_date_ending=g["reportperiod"])
+        f = compute_fundamental(g.drop(columns=["datekey", "reportperiod"]))
+        if f.empty:
+            continue
+        last = f.iloc[-1]
+        rows.append({"ticker": t, "filed": str(f.index[-1].date()), **{c: last.get(c) for c in (
+            "roe", "roa", "gross_margin", "fcf_conversion", "fcf_yield", "buyback_yield", "net_share_reduction_yoy",
+            "basic_diluted_gap", "equity_financing", "earnings_yield", "rd_intensity")}})
+    return pd.DataFrame(rows) if rows else pd.DataFrame(columns=["ticker"])

qt3/performance.py

@@ -0,0 +1,74 @@
+"""Live performance from the Alpaca account: time-weighted return (deposits / withdrawals removed), drawdown,
+and the S&P 500 (SPY) over the same days."""
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta, timezone
+from typing import Optional
+from zoneinfo import ZoneInfo
+
+from . import config
+from .broker import Alpaca
+
+
+def twr(dates: list[str], equity: list[float], flows: dict[str, float]) -> list[float]:
+    """Growth of $1 (time-weighted): each day's return excludes that day's net deposit."""
+    out, g = [], 1.0
+    for i, (d, e) in enumerate(zip(dates, equity)):
+        if i > 0 and equity[i - 1] > 0:
+            g *= (e - flows.get(d, 0.0)) / equity[i - 1]
+        out.append(g)
+    return out
+
+
+def max_drawdown(g: list[float]) -> float:
+    peak, worst = 0.0, 0.0
+    for x in g:
+        peak = max(peak, x)
+        worst = min(worst, x / peak - 1 if peak else 0.0)
+    return worst
+
+
+def series(a: Alpaca, inception: Optional[str] = None) -> dict:
+    h = a.portfolio_history()
+    ny = ZoneInfo("America/New_York")
+    pts = [(datetime.fromtimestamp(t, ny).date().isoformat(), float(e))
+           for t, e in zip(h.get("timestamp") or [], h.get("equity") or []) if e is not None]
+    start = inception or config.INCEPTION
+    if not start:
+        first = [o for o in a.orders(status="all") if str(o.get("client_order_id", "")).startswith(config.TAG + "-")]
+        start = min((o["created_at"][:10] for o in first), default=None)
+    pts = [p for p in pts if p[1] > 0]
+    if start:                                  # base = the last close before the first trade (all cash)
+        before = [p for p in pts if p[0] < start]
+        pts = before[-1:] + [p for p in pts if p[0] >= start]
+    today = datetime.now(ZoneInfo("America/New_York")).date().isoformat()
+    live_eq = a.account()["equity"]
+    if live_eq > 0 and (not pts or pts[-1][0] < today):
+        pts.append((today, live_eq))           # Alpaca's daily history ends at the previous close
+    if len(pts) < 1:
+        return {"start": start, "dates": [], "strategy": [], "spy": [], "stats": {}}
+    dates, eq = [p[0] for p in pts], [p[1] for p in pts]
+    flows = {}
+    for f in a.cash_flows():
+        flows[f["date"]] = flows.get(f["date"], 0.0) + f["amount"]
+    g = twr(dates, eq, flows)
+    bars = {b["t"]: b["c"] for b in a.daily_bars("SPY", date.fromisoformat(dates[0]) - timedelta(days=7))}
+    spy_now = a.latest_prices(["SPY"]).get("SPY")
+    if spy_now and dates[-1] == today:
+        bars[today] = spy_now
+    closes = sorted(bars.items())                 # latest S&P close on or before each date
+    spy, j, last = [], 0, None
+    for d in dates:
+        while j < len(closes) and closes[j][0] <= d:
+            last = closes[j][1]
+            j += 1
+        spy.append(last)
+    base = next((x for x in spy if x), None)
+    spy = [round(x / base, 6) if (x and base) else None for x in spy]
+    days = (date.fromisoformat(dates[-1]) - date.fromisoformat(dates[0])).days
+    tot = g[-1] - 1
+    spy_tot = (spy[-1] - 1) if spy and spy[-1] else None
+    ann = (g[-1] ** (365.25 / days) - 1) if days >= 365 else None
+    return {"start": start or dates[0], "base": dates[0], "dates": dates, "strategy": [round(x, 6) for x in g], "spy": spy,
+            "stats": {"return": tot, "spy_return": spy_tot, "annualised": ann, "max_drawdown": max_drawdown(g),
+                      "days": days, "equity": eq[-1]}}

qt3/ranking.py

@@ -0,0 +1,152 @@
+"""Today's Quality-Trend ranking, built from the Sharadar API (no local data needed).
+
+Same steps as the live RS-VCP snapshot (Quant Model scripts/build_screens_snapshot.py) and the backtest:
+  1. universe   top 1,000 US-listed companies by market cap (Sharadar DAILY, latest date)
+  2. trend      ~300 trading days of SEP prices → MA50/MA200 − 1 and the 6-1-month return; 20-day $ volume
+  3. quality    SF1 quarterly statements (as filed) → basic-diluted gap, quality score (ROE, ROA, gross
+                margin, FCF conversion), −equity financing, FCF yield, ROE, buyback yield, net share reduction
+  4. slice      price ≥ $5, ≥ $5M/day, US-dollar reporters; quality pool = top 30% of the composite
+  5. rank       pool ranked by 0.5·pct(MA50/MA200) + 0.5·pct(6-1-month return)
+About 40 API requests; cached for the day.
+"""
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from datetime import datetime, timedelta, timezone
+from typing import Callable, Optional
+
+import numpy as np
+import pandas as pd
+
+from . import config
+from .fundamental import SF1_COLS, latest_inputs
+from .sharadar import query, query_tickers
+
+_lock = threading.Lock()
+_state = {"building": False, "error": None, "started": None}
+
+
+def trend(p: pd.DataFrame) -> pd.DataFrame:
+    out = []
+    for t, g in p.sort_values(["ticker", "date"]).groupby("ticker", sort=False):
+        c = g["closeadj"].to_numpy(float)
+        if len(c) < 200 or not np.isfinite(c[-1]):
+            continue
+        dv = (g["close"].astype(float) * g["volume"].astype(float)).tail(20).mean()
+        out.append({"ticker": t, "last_bar": str(pd.Timestamp(g["date"].iloc[-1]).date()),
+                    "price": float(g["close"].iloc[-1]), "dv20": float(dv),
+                    "ma50_200": c[-50:].mean() / c[-200:].mean() - 1,
+                    "mom_6_1": c[-21] / c[-126] - 1 if len(c) >= 126 else np.nan,
+                    "ret_1m": c[-1] / c[-22] - 1, "ret_6m": c[-1] / c[-127] - 1 if len(c) >= 127 else np.nan})
+    return pd.DataFrame(out)
+
+
+def rank_table(u: pd.DataFrame) -> pd.DataFrame:
+    """Steps 4-5 on a merged universe table (pure; unit-tested)."""
+    pct = lambda d, c: d[c].rank(pct=True)
+    u = u.copy()
+    for c in ("roe", "roa", "gross_margin", "fcf_conversion", "fcf_yield", "buyback_yield", "net_share_reduction_yoy",
+              "basic_diluted_gap", "equity_financing", "currency"):
+        if c not in u:
+            u[c] = np.nan                       # missing statements → the name simply can't enter the pool
+    u["equity_financing_neg"] = -u["equity_financing"]
+    liq = (u["price"] >= config.MIN_PRICE) & (u["dv20"] >= config.MIN_DV)
+    q = u[liq & (u["currency"].fillna("USD") == "USD")].copy()
+    q["quality_score"] = pd.concat([pct(q, c) for c in ("roe", "roa", "gross_margin", "fcf_conversion")],
+                                   axis=1).mean(axis=1)
+    P = pd.concat([pct(q, c) for c in config.QCD], axis=1)
+    q["qcd"] = P.mean(axis=1).where(P.notna().mean(axis=1) >= 0.5)
+    q["qcd_pct"] = q["qcd"].rank(pct=True)
+    q["trend"] = 0.5 * pct(q, "ma50_200") + 0.5 * pct(q, "mom_6_1")
+    pool = q[(q["qcd_pct"] >= config.POOL) & q["trend"].notna()]
+    pool = pool.sort_values("trend", ascending=False, kind="stable").reset_index(drop=True)
+    pool["rank"] = np.arange(1, len(pool) + 1)
+    pool.attrs.update(universe=int(len(u)), liquid_usd=int(len(q)))
+    return pool
+
+
+def build(key: str, today: Optional[datetime] = None, fetch: Callable = query,
+          fetch_tickers: Callable = query_tickers) -> dict:
+    day = (today or datetime.now(timezone.utc)).date()
+    d = fetch("DAILY", key, date__gte=str(day - timedelta(days=14)), columns=["ticker", "date", "marketcap"])
+    d["date"] = pd.to_datetime(d["date"])
+    d = d[d["date"] == d["date"].max()].dropna(subset=["marketcap"])
+    uni = d.assign(market_cap=pd.to_numeric(d["marketcap"]) * 1e6).nlargest(config.TOPN, "market_cap")
+    tickers = uni["ticker"].tolist()
+    tk = fetch_tickers("TICKERS", key, tickers, columns=["table", "ticker", "name", "sector", "industry", "currency"])
+    meta = tk[tk["table"] == "SEP"].drop_duplicates("ticker").set_index("ticker")[["name", "sector", "industry"]]
+    cur = tk[tk["table"] == "SF1"].drop_duplicates("ticker").set_index("ticker")["currency"]
+    px = fetch_tickers("SEP", key, tickers, date__gte=str(day - timedelta(days=430)),
+                       columns=["ticker", "date", "close", "volume", "closeadj"])
+    px["date"] = pd.to_datetime(px["date"])
+    for c in ("close", "volume", "closeadj"):
+        px[c] = pd.to_numeric(px[c], errors="coerce")
+    tr = trend(px)
+    sf1 = fetch_tickers("SF1", key, tickers, dimension="ARQ", datekey__gte=str(day - timedelta(days=4 * 365)),
+                        columns=SF1_COLS)
+    f = latest_inputs(sf1)
+    u = uni[["ticker", "market_cap"]].merge(tr, on="ticker", how="inner").merge(f, on="ticker", how="left")
+    u = u.join(meta, on="ticker").assign(currency=u["ticker"].map(cur))
+    pool = rank_table(u)
+    keep = ["rank", "ticker", "name", "sector", "industry", "price", "market_cap", "trend", "qcd_pct", "ma50_200",
+            "mom_6_1", "ret_1m", "ret_6m", "roe", "fcf_yield", "buyback_yield", "filed"]
+    rows = pool[[c for c in keep if c in pool]].head(40)
+    return {"built": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            "prices_as_of": str(tr["last_bar"].max()) if not tr.empty else None,
+            "universe": pool.attrs["universe"], "liquid_usd": pool.attrs["liquid_usd"], "pool": int(len(pool)),
+            "ranked": json.loads(rows.to_json(orient="records"))}
+
+
+# ------------------------------------------------------------------ daily cache
+def _path() -> str:
+    os.makedirs(config.CACHE_DIR, exist_ok=True)
+    return os.path.join(config.CACHE_DIR, "ranking.json")
+
+
+def cached() -> Optional[dict]:
+    try:
+        with open(_path()) as fh:
+            return json.load(fh)
+    except (OSError, ValueError):
+        return None
+
+
+def age_hours(r: Optional[dict]) -> float:
+    if not r or not r.get("built"):
+        return float("inf")
+    return (datetime.now(timezone.utc) - datetime.fromisoformat(r["built"])).total_seconds() / 3600
+
+
+def refresh(force: bool = False) -> Optional[dict]:
+    """Rebuild if older than RANKING_MAX_AGE_H (blocking; one build at a time)."""
+    r = cached()
+    if not force and age_hours(r) < config.RANKING_MAX_AGE_H:
+        return r
+    if not _lock.acquire(blocking=False):
+        return r
+    try:
+        _state.update(building=True, error=None, started=time.time())
+        r = build(config.NDL_KEY)
+        tmp = _path() + ".part"
+        with open(tmp, "w") as fh:
+            json.dump(r, fh)
+        os.replace(tmp, _path())
+        return r
+    except Exception as e:  # noqa: BLE001 — keep serving the last good ranking
+        _state["error"] = f"{type(e).__name__}: {e}"[:300]
+        return cached()
+    finally:
+        _state["building"] = False
+        _lock.release()
+
+
+def refresh_async() -> None:
+    if age_hours(cached()) >= config.RANKING_MAX_AGE_H and not _state["building"]:
+        threading.Thread(target=refresh, daemon=True).start()
+
+
+def state() -> dict:
+    return dict(_state)

qt3/rebalance.py

@@ -0,0 +1,194 @@
+"""Monthly rebalance: target list (keep while in the top 6, refill to 3), order plan, guards and execution.
+
+The backtest checked once a month and re-split the money equally; here that runs on the first trading days of
+each month (an external daily cron calls it; everything else is a no-op). State lives in Alpaca: the orders this
+strategy placed carry a client_order_id starting with "qt3-".
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import asdict, dataclass
+from datetime import date, datetime, timedelta, timezone
+from typing import Optional
+from zoneinfo import ZoneInfo
+
+from . import config
+from .broker import Alpaca, BrokerError
+
+NY = ZoneInfo("America/New_York")
+WINDOW_DAYS = 5          # a month's rebalance may run on its first 5 trading days (retries after outages)
+
+
+@dataclass
+class Order:
+    symbol: str
+    side: str
+    shares: float
+    price: float
+    value: float
+    reason: str
+    close_all: bool = False
+
+
+def target_list(ranked: list[str], held: list[str], n: int = config.N, keep: int = config.KEEP):
+    """Keep holdings ranked within `keep`, refill from the top to `n`. Returns (final, sell reasons)."""
+    rank = {t: i + 1 for i, t in enumerate(ranked)}
+    kept = sorted([t for t in held if rank.get(t, 10 ** 9) <= keep], key=lambda t: rank[t])[:n]
+    why = {}
+    for t in held:
+        if t in kept:
+            continue
+        r = rank.get(t)
+        why[t] = (f"now ranked #{r} — outside the top {keep}" if r and r > keep else
+                  f"ranked #{r} — below the {n} names kept" if r else "left the quality pool / universe")
+    final = kept + [t for t in ranked if t not in kept][: n - len(kept)]
+    return sorted(final, key=lambda t: rank[t]), why
+
+
+def _floor(x: float, fractional: bool) -> float:
+    return math.floor(x * 1e6) / 1e6 if fractional else float(math.floor(x + 1e-9))
+
+
+def plan(final: list[str], positions: dict[str, float], prices: dict[str, float], cash: float,
+         reasons: Optional[dict] = None, fractional: bool = True, buffer: float = config.CASH_BUFFER,
+         min_trade: float = config.MIN_TRADE, band: float = config.BAND) -> dict:
+    """Orders that turn `positions` (symbol → shares) + `cash` into equal thirds of `final`, keeping `buffer`
+    of the total in cash. Exits and trims first; adjustments under max(min_trade, band × target) skipped."""
+    reasons = reasons or {}
+    held = {s: float(q) for s, q in positions.items() if float(q) > 0}
+    missing = sorted(s for s in set(held) | set(final) if not prices.get(s))
+    if missing:
+        raise ValueError(f"no price for {', '.join(missing)}")
+    total = sum(q * prices[s] for s, q in held.items()) + cash
+    target = total * (1 - buffer) / len(final) if final else 0.0
+    skip = max(min_trade, band * target)
+    sells, buys, after = [], [], {}
+    for s, q in held.items():
+        if s not in final:
+            sells.append(Order(s, "sell", q, prices[s], q * prices[s], reasons.get(s, "not in the plan"), True))
+        else:
+            after[s] = q
+    for s in final:
+        over = after.get(s, 0.0) * prices[s] - target
+        if over >= skip:
+            q = min(_floor(over / prices[s], fractional), after[s])
+            if q > 0:
+                sells.append(Order(s, "sell", q, prices[s], q * prices[s], "trim back to a third"))
+                after[s] -= q
+    spendable = cash + sum(o.value for o in sells) - total * buffer
+    wants = sorted(((s, target - after.get(s, 0.0) * prices[s]) for s in final), key=lambda x: -x[1])
+    for s, need in wants:
+        if need < skip and s in after:
+            continue
+        amt = min(need, max(spendable, 0.0))
+        q = _floor(amt / prices[s], fractional)
+        if q <= 0 or amt < 1:
+            continue
+        buys.append(Order(s, "buy", q, prices[s], q * prices[s], "new — top 3" if s not in held else "top up to a third"))
+        spendable -= q * prices[s]
+        after[s] = after.get(s, 0.0) + q
+    return {"final": final, "orders": [asdict(o) for o in sells + buys], "total": round(total, 2),
+            "target_each": round(target, 2), "cash_after": round(spendable + total * buffer, 2),
+            "skipped_below": round(skip, 2)}
+
+
+# ------------------------------------------------------------------ guards
+def _ts(s: str) -> datetime:
+    """Alpaca timestamps carry nanoseconds; seconds are enough here."""
+    return datetime.fromisoformat(s[:19]).replace(tzinfo=timezone.utc)
+
+
+def strategy_orders(a: Alpaca, since: datetime) -> list[dict]:
+    return [o for o in a.orders(after=since) if str(o.get("client_order_id", "")).startswith(config.TAG + "-")]
+
+
+def window(a: Alpaca, today: date) -> dict:
+    """Trading days of this month so far and whether today is within the rebalance window."""
+    days = a.trading_days(today.replace(day=1), today + timedelta(days=40))
+    month = [d for d in days if d.startswith(today.strftime("%Y-%m"))]
+    nxt = next((d for d in days if d > today.strftime("%Y-%m-31")), None)
+    pos = month.index(str(today)) + 1 if str(today) in month else None
+    return {"trading_day_of_month": pos, "in_window": pos is not None and pos <= WINDOW_DAYS,
+            "next_rebalance": month[0] if month and month[0] > str(today) else nxt}
+
+
+def check(a: Alpaca, ranking: Optional[dict], now: Optional[datetime] = None, force: bool = False) -> dict:
+    now = (now or datetime.now(NY)).astimezone(NY)
+    today = now.date()
+    reasons = []
+    clk = a.clock()
+    if not clk.get("is_open"):
+        reasons.append(f"market closed (next open {clk.get('next_open', '?')})")
+    w = window(a, today)
+    month_start = datetime(today.year, today.month, 1, tzinfo=NY)
+    ever = strategy_orders(a, now - timedelta(days=400))
+    this_month = [o for o in ever if _ts(o["created_at"]) >= month_start]
+    done = any(o.get("side") == "buy" and o.get("status") not in ("canceled", "rejected", "expired") for o in this_month)
+    first_run = not ever
+    if not force:
+        if done:
+            reasons.append("already rebalanced this month")
+        if not first_run and not w["in_window"]:
+            reasons.append(f"outside the rebalance window (first {WINDOW_DAYS} trading days of the month)")
+    if not ranking or not ranking.get("ranked"):
+        reasons.append("no ranking available")
+    else:
+        age = (today - date.fromisoformat(ranking["prices_as_of"])).days
+        if age > 5:
+            reasons.append(f"ranking data is {age} days old")
+    return {"ok": not reasons, "reasons": reasons, "first_run": first_run, "done_this_month": done, **w}
+
+
+# ------------------------------------------------------------------ execution
+def build_plan(a: Alpaca, ranking: dict) -> dict:
+    pos = a.positions()
+    held = sorted(pos)
+    ranked = [r["ticker"] for r in ranking["ranked"]]
+    final, why = target_list(ranked, held)
+    px = a.latest_prices(sorted(set(final) | set(held)))
+    for s, p in pos.items():
+        px.setdefault(s, p["price"])
+    acct = a.account()
+    cash = max(0.0, min(acct["cash"], acct["non_marginable_buying_power"] or acct["cash"]))
+    assets = a.assets(final)
+    frac = all(assets[s]["fractionable"] for s in final)
+    p = plan(final, {s: v["qty"] for s, v in pos.items()}, px, cash, why, fractional=frac)
+    p.update(fractional=frac, untradable=[s for s in final if not assets[s]["tradable"]], equity=acct["equity"])
+    return p
+
+
+def execute(a: Alpaca, p: dict, today: Optional[date] = None, wait_s: float = 90.0) -> list[dict]:
+    if p.get("untradable"):
+        raise BrokerError("not tradable on Alpaca: " + ", ".join(p["untradable"]))
+    day = (today or datetime.now(NY).date()).strftime("%Y%m%d")
+    res, sell_ids = [], []
+    for o in [o for o in p["orders"] if o["side"] == "sell"]:
+        r = a.submit(o["symbol"], "sell", qty=o["shares"], client_order_id=f"{config.TAG}-{day}-{o['symbol']}-sell")
+        sell_ids.append(r.get("id"))
+        res.append({"symbol": o["symbol"], "side": "sell", "id": r.get("id"), "status": r.get("status")})
+    if sell_ids:
+        done = a.wait([i for i in sell_ids if i], wait_s)
+        for x in res:
+            x["status"] = (done.get(x["id"]) or {}).get("status", x["status"])
+        if any(x["status"] != "filled" for x in res):
+            return res + [{"symbol": "-", "side": "buy", "status": "deferred — sells not filled; retried next run"}]
+    buys = [o for o in p["orders"] if o["side"] == "buy"]
+    acct = a.account()
+    cash = max(0.0, min(acct["cash"], acct["non_marginable_buying_power"] or acct["cash"]) - acct["equity"] * config.CASH_BUFFER)
+    want = sum(o["value"] for o in buys)
+    scale = min(1.0, cash / want) if want > 0 else 1.0
+    for o in buys:
+        cid = f"{config.TAG}-{day}-{o['symbol']}-buy"
+        if p.get("fractional"):
+            amt = round(o["value"] * scale, 2)
+            if amt < 1:
+                continue
+            r = a.submit(o["symbol"], "buy", notional=amt, client_order_id=cid)
+        else:
+            q = float(math.floor(o["shares"] * scale + 1e-9))
+            if q < 1:
+                continue
+            r = a.submit(o["symbol"], "buy", qty=q, client_order_id=cid)
+        res.append({"symbol": o["symbol"], "side": "buy", "id": r.get("id"), "status": r.get("status"),
+                    "scaled": round(scale, 4)})
+    return res

qt3/sharadar.py

@@ -0,0 +1,64 @@
+"""Minimal Sharadar (Nasdaq Data Link tables API) client: cursor pagination, ticker chunking, retries.
+The API key is sent as a query parameter and never logged or returned in errors."""
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+import pandas as pd
+import requests
+
+BASE = "https://data.nasdaq.com/api/v3/datatables/SHARADAR/"
+
+
+class SharadarError(RuntimeError):
+    pass
+
+
+def query(table: str, key: str, session: Optional[requests.Session] = None, retries: int = 5,
+          **filters) -> pd.DataFrame:
+    """All rows of SHARADAR/<table> matching `filters` (e.g. ticker="A,B", date__gte="2026-01-01",
+    columns=["ticker", "date"]). Double underscores become dots (date__gte → date.gte)."""
+    if not key:
+        raise SharadarError("NASDAQ_DATA_LINK_API_KEY is not set")
+    s = session or requests.Session()
+    params = {k.replace("__", "."): v for k, v in filters.items() if k != "columns"}
+    if "columns" in filters:
+        params["qopts.columns"] = ",".join(filters["columns"])
+    params["qopts.per_page"] = 10000
+    frames, cursor = [], None
+    while True:
+        p = {**params, "api_key": key, **({"qopts.cursor_id": cursor} if cursor else {})}
+        for attempt in range(retries):
+            r = s.get(BASE + table + ".json", params=p, timeout=90)
+            if r.status_code in (429, 500, 502, 503, 504):
+                time.sleep(min(60, 2 ** attempt * 2))
+                continue
+            break
+        if r.status_code >= 400:
+            try:
+                msg = r.json().get("quandl_error", {}).get("message", "")
+            except ValueError:
+                msg = ""
+            raise SharadarError(f"SHARADAR/{table} → HTTP {r.status_code} {msg}".strip())
+        j = r.json()
+        dt = j.get("datatable", {})
+        cols = [c["name"] for c in dt.get("columns", [])]
+        if dt.get("data"):
+            frames.append(pd.DataFrame(dt["data"], columns=cols))
+        cursor = (j.get("meta") or {}).get("next_cursor_id")
+        if not cursor:
+            break
+    return pd.concat(frames, ignore_index=True) if frames else pd.DataFrame()
+
+
+def query_tickers(table: str, key: str, tickers: list[str], chunk: int = 100,
+                  session: Optional[requests.Session] = None, **filters) -> pd.DataFrame:
+    """`query` over a long ticker list, `chunk` tickers per request."""
+    out = []
+    tickers = sorted(set(tickers))
+    for i in range(0, len(tickers), chunk):
+        part = query(table, key, session=session, ticker=",".join(tickers[i:i + chunk]), **filters)
+        if not part.empty:
+            out.append(part)
+    return pd.concat(out, ignore_index=True) if out else pd.DataFrame()

requirements.txt

@@ -0,0 +1,6 @@
+fastapi>=0.115,<1
+uvicorn[standard]>=0.30,<1
+requests>=2.31,<3
+pandas>=2.2,<4
+numpy>=1.26,<3
+tzdata>=2024.1

static/index.html

@@ -0,0 +1,211 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Updraft — live</title>
+<meta name="description" content="Updraft: a three-stock quality-and-trend strategy, rebalanced automatically each month on an Alpaca paper account.">
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.4/dist/chart.umd.min.js"></script>
+<style>
+:root{--bg:#f7f7f5;--card:#ffffff;--ink:#1d1d1f;--muted:#6b6b72;--line:#e6e4df;--accent:#d9480f;--spy:#6b7280;
+--pos:#1a7f37;--neg:#c92a2a;--chip:#fff4e6;--chipink:#9a3412;font-family:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif}
+@media (prefers-color-scheme: dark){:root:not([data-theme="light"]){--bg:#121214;--card:#1b1b1f;--ink:#ececf1;--muted:#a0a0aa;
+--line:#2c2c33;--accent:#ff7a3d;--spy:#9ca3af;--pos:#4ade80;--neg:#f87171;--chip:#2a1d14;--chipink:#fdba74}}
+:root[data-theme="dark"]{--bg:#121214;--card:#1b1b1f;--ink:#ececf1;--muted:#a0a0aa;--line:#2c2c33;--accent:#ff7a3d;--spy:#9ca3af;
+--pos:#4ade80;--neg:#f87171;--chip:#2a1d14;--chipink:#fdba74}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);line-height:1.45}
+.wrap{max-width:1080px;margin:0 auto;padding:28px 16px 48px}
+header{display:flex;flex-wrap:wrap;gap:10px 16px;align-items:baseline;justify-content:space-between}
+h1{font-size:28px;margin:0;letter-spacing:-.01em}h2{font-size:17px;margin:0 0 12px}
+.lead{color:var(--muted);margin:6px 0 0;max-width:760px}
+.chip{display:inline-block;font-size:12px;font-weight:600;padding:3px 9px;border-radius:999px;background:var(--chip);color:var(--chipink)}
+.live{font-size:12px;color:var(--muted)}.dot{display:inline-block;width:8px;height:8px;border-radius:50%;background:var(--pos);margin-right:6px}
+.tiles{display:grid;grid-template-columns:repeat(5,1fr);gap:12px;margin:22px 0}
+.tile{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:14px}
+.tile .l{font-size:11px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted)}
+.tile .v{font-size:24px;font-weight:700;margin-top:4px;font-variant-numeric:tabular-nums}.tile .s{font-size:12px;color:var(--muted);margin-top:2px}
+.pos{color:var(--pos)}.neg{color:var(--neg)}
+.card{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:18px;margin-top:14px}
+.grid2{display:grid;grid-template-columns:1.4fr 1fr;gap:14px}
+table{width:100%;border-collapse:collapse;font-size:14px;font-variant-numeric:tabular-nums}
+th{text-align:left;font-size:11px;text-transform:uppercase;letter-spacing:.05em;color:var(--muted);font-weight:600;padding:6px 8px;border-bottom:1px solid var(--line)}
+td{padding:8px;border-bottom:1px solid var(--line)}td.r,th.r{text-align:right}
+.sym{font-weight:700}.sub{color:var(--muted);font-size:12px}
+.note{font-size:13px;color:var(--muted)}.empty{color:var(--muted);font-size:14px;padding:8px 0}
+.chartbox{position:relative;height:300px}
+ul.rules{margin:0;padding-left:18px}ul.rules li{margin:4px 0}
+.kv{display:grid;grid-template-columns:repeat(4,1fr);gap:10px;margin-top:10px}
+.kv div{border:1px solid var(--line);border-radius:10px;padding:10px}.kv b{display:block;font-size:18px}
+footer{margin-top:22px;font-size:12px;color:var(--muted)}
+button.theme{background:none;border:1px solid var(--line);color:var(--muted);border-radius:8px;padding:4px 8px;font-size:12px;cursor:pointer}
+@media (max-width:860px){.tiles{grid-template-columns:repeat(2,1fr)}.grid2{grid-template-columns:1fr}.kv{grid-template-columns:repeat(2,1fr)}}
+.scroll{overflow-x:auto}
+</style>
+</head>
+<body>
+<div class="wrap">
+<header>
+  <div>
+    <h1>🪁 Updraft <span class="chip" id="mode">Paper trading</span></h1>
+    <div class="sub" style="margin-top:2px">The Quality-Trend 3 strategy — rides the strongest risers among quality companies</div>
+    <p class="lead">Three large US stocks with strong <b>quality and capital discipline</b> and the strongest
+    <b>price trends</b>. Checked once a month; a stock is kept while it ranks in the top 6, the rest is replaced
+    and the money re-split into thirds. Runs on its own — no human in the loop.</p>
+  </div>
+  <div class="live"><span class="dot" id="dot"></span><span id="updated">loading…</span>
+    <button class="theme" id="themeBtn" title="Toggle light / dark">◐</button></div>
+</header>
+
+<section class="tiles" id="tiles">
+  <div class="tile"><div class="l">Portfolio value</div><div class="v" id="t-eq">—</div><div class="s" id="t-eq-s"></div></div>
+  <div class="tile"><div class="l">Since start</div><div class="v" id="t-ret">—</div><div class="s" id="t-ret-s"></div></div>
+  <div class="tile"><div class="l">S&amp;P 500, same days</div><div class="v" id="t-spy">—</div><div class="s" id="t-spy-s"></div></div>
+  <div class="tile"><div class="l">Worst fall</div><div class="v" id="t-dd">—</div><div class="s">peak to trough, since start</div></div>
+  <div class="tile"><div class="l">Next rebalance</div><div class="v" id="t-next">—</div><div class="s" id="t-next-s"></div></div>
+</section>
+
+<section class="card">
+  <h2>Growth of $1 — strategy vs S&amp;P 500</h2>
+  <div class="chartbox"><canvas id="chart"></canvas></div>
+  <p class="note" id="chartnote">Time-weighted (deposits and withdrawals don't count as gains). Updated every 10 minutes.</p>
+</section>
+
+<div class="grid2">
+  <section class="card">
+    <h2>Holdings now</h2>
+    <div class="scroll"><table id="holdings"><thead><tr><th>Stock</th><th class="r">Weight</th><th class="r">Value</th>
+      <th class="r">Gain</th><th class="r">Today</th><th class="r">Rank now</th></tr></thead><tbody></tbody></table></div>
+    <p class="note" id="cashnote"></p>
+  </section>
+  <section class="card">
+    <h2>This month's ranking</h2>
+    <div class="scroll"><table id="ranking"><thead><tr><th>#</th><th>Stock</th><th>Sector</th><th class="r">6-month</th></tr></thead><tbody></tbody></table></div>
+    <p class="note" id="ranknote"></p>
+  </section>
+</div>
+
+<section class="card">
+  <h2>Trade log</h2>
+  <div class="scroll"><table id="orders"><thead><tr><th>Date</th><th>Action</th><th>Stock</th><th class="r">Shares</th><th class="r">Price</th><th>Status</th></tr></thead><tbody></tbody></table></div>
+</section>
+
+<section class="card">
+  <h2>How it works — and what the backtest says</h2>
+  <ul class="rules">
+    <li><b>Universe:</b> the 1,000 largest US companies, price ≥ $5, ≥ $5M traded a day, US-dollar financial statements.</li>
+    <li><b>Quality pool:</b> the top 30% on capital discipline — low dilution, no new share issuance, buybacks, free-cash-flow yield, ROE, gross margin, cash conversion.</li>
+    <li><b>Trend:</b> the pool ranked by the 50- vs 200-day average and the 6-month return (skipping the last month).</li>
+    <li><b>Monthly:</b> on the first trading day of each month, keep holdings still ranked in the top 6; sell the rest; buy from the top until there are 3; re-split equally (1% kept in cash). Sells go first.</li>
+  </ul>
+  <div class="kv">
+    <div><span class="sub">Return per year, 1999–2026</span><b>+30.9%</b><span class="sub">S&amp;P 500 +8.5%</span></div>
+    <div><span class="sub">Worst fall</span><b>−34%</b><span class="sub">worst month −24%</span></div>
+    <div><span class="sub">Any 12 months: median</span><b>+24%</b><span class="sub">in profit 87% of the time</span></div>
+    <div><span class="sub">Beat the S&amp;P over 12 months</span><b>77%</b><span class="sub">of all start months</span></div>
+  </div>
+  <p class="note">Backtest after 10 bps per trade, point-in-time stock lists, delisted companies included. Backtests flatter — the
+  2024-26 AI rally dominates recent years; expect less, with falls of 30–35% or worse. Each stock is a third of the
+  money: one stock halving costs about 17%.</p>
+</section>
+
+<footer>Educational paper-trading demonstration — not investment advice. Prices and fills from Alpaca (IEX feed); rankings from
+Sharadar fundamentals and prices. <span id="ver"></span></footer>
+</div>
+
+<script>
+const $ = id => document.getElementById(id);
+const pct = (x, d=1) => x == null || isNaN(x) ? "—" : (x >= 0 ? "+" : "−") + Math.abs(x * 100).toFixed(d) + "%";
+const usd = x => x == null ? "—" : "$" + Number(x).toLocaleString(undefined, {maximumFractionDigits: 0});
+const cls = (el, x) => { el.classList.remove("pos", "neg"); if (x != null) el.classList.add(x >= 0 ? "pos" : "neg"); };
+const esc = s => String(s ?? "").replace(/[&<>"]/g, c => ({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;"}[c]));
+async function get(u){ const r = await fetch(u); if(!r.ok) throw new Error((await r.json().catch(()=>({}))).detail || r.status); return r.json(); }
+let chart;
+
+try { const t = localStorage.getItem("updraft-theme"); if (t) document.documentElement.dataset.theme = t; } catch (e) {}
+$("themeBtn").onclick = () => { const cur = document.documentElement.dataset.theme ||
+  (matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
+  const nxt = cur === "dark" ? "light" : "dark"; document.documentElement.dataset.theme = nxt;
+  try { localStorage.setItem("updraft-theme", nxt); } catch (e) {} drawChart(window._perf); };
+
+async function loadPortfolio(){
+  try {
+    const p = await get("/api/portfolio");
+    $("mode").textContent = p.paper ? "Paper trading" : "LIVE trading";
+    $("t-eq").textContent = usd(p.equity);
+    $("t-eq-s").textContent = p.today_pct == null ? "" : `today ${pct(p.today_pct, 2)} (${p.today_change >= 0 ? "+" : "−"}${usd(Math.abs(p.today_change))})`;
+    const tb = $("holdings").querySelector("tbody");
+    tb.innerHTML = p.positions.length ? p.positions.map(r => `<tr><td><span class="sym">${esc(r.symbol)}</span><br><span class="sub">${esc(r.name || "")}</span></td>
+      <td class="r">${pct(r.weight, 0).replace("+","")}</td><td class="r">${usd(r.value)}</td>
+      <td class="r ${r.pl_pct >= 0 ? "pos" : "neg"}">${pct(r.pl_pct)}</td><td class="r ${r.today >= 0 ? "pos" : "neg"}">${pct(r.today)}</td>
+      <td class="r">${r.rank_now ? "#" + r.rank_now : "—"}</td></tr>`).join("")
+      : `<tr><td colspan="6" class="empty">No positions yet — the first rebalance buys the top 3.</td></tr>`;
+    $("cashnote").textContent = `Cash ${usd(p.cash)}. Prices update every 30 seconds while the page is open.`;
+    $("updated").textContent = "Updated " + new Date().toLocaleTimeString();
+    $("dot").style.background = "var(--pos)";
+  } catch (e) { $("updated").textContent = "Live data unavailable: " + e.message; $("dot").style.background = "var(--neg)"; }
+}
+
+async function loadStatus(){
+  try {
+    const s = await get("/api/status");
+    $("t-next").textContent = s.next_rebalance ? new Date(s.next_rebalance + "T12:00:00").toLocaleDateString(undefined, {day:"numeric", month:"short"}) : "—";
+    $("t-next-s").textContent = s.done_this_month ? "this month's rebalance is done" : (s.market_open ? "market open" : "market closed");
+  } catch (e) { $("t-next-s").textContent = ""; }
+}
+
+async function loadRanking(){
+  try {
+    const r = await get("/api/ranking");
+    const tb = $("ranking").querySelector("tbody");
+    tb.innerHTML = (r.ranked || []).slice(0, 6).map(x => `<tr><td>${x.rank}</td><td><span class="sym">${esc(x.ticker)}</span><br><span class="sub">${esc(x.name || "")}</span></td>
+      <td class="sub">${esc(x.sector || "")}</td><td class="r ${x.ret_6m >= 0 ? "pos" : "neg"}">${pct(x.ret_6m, 0)}</td></tr>`).join("")
+      || `<tr><td colspan="4" class="empty">${r.building ? "Building today's ranking…" : "Ranking not available yet."}</td></tr>`;
+    $("ranknote").textContent = r.prices_as_of ? `Prices to ${r.prices_as_of} · ${r.pool} stocks in the quality pool. Holdings are kept while they stay in the top 6.` : "";
+  } catch (e) { $("ranknote").textContent = "Ranking unavailable: " + e.message; }
+}
+
+async function loadOrders(){
+  try {
+    const o = await get("/api/orders");
+    const tb = $("orders").querySelector("tbody");
+    tb.innerHTML = o.length ? o.slice(0, 30).map(x => `<tr><td>${esc(x.date)}</td><td class="${x.side === "buy" ? "pos" : "neg"}">${x.side === "buy" ? "Buy" : "Sell"}</td>
+      <td class="sym">${esc(x.symbol)}</td><td class="r">${x.qty ? Number(x.qty).toFixed(3) : "—"}</td>
+      <td class="r">${x.price ? "$" + Number(x.price).toFixed(2) : "—"}</td><td class="sub">${esc(x.status)}</td></tr>`).join("")
+      : `<tr><td colspan="6" class="empty">No trades yet.</td></tr>`;
+  } catch (e) {}
+}
+
+function drawChart(p){
+  if (!p || !p.dates || !p.dates.length) return;
+  const css = getComputedStyle(document.documentElement);
+  const accent = css.getPropertyValue("--accent").trim(), spyc = css.getPropertyValue("--spy").trim(), grid = css.getPropertyValue("--line").trim(),
+        ink = css.getPropertyValue("--muted").trim();
+  if (chart) chart.destroy();
+  chart = new Chart($("chart"), {type: "line", data: {labels: p.dates, datasets: [
+    {label: "Updraft", data: p.strategy, borderColor: accent, borderWidth: 2.2, pointRadius: 0, tension: .15},
+    {label: "S&P 500", data: p.spy, borderColor: spyc, borderWidth: 1.5, pointRadius: 0, borderDash: [4, 3], tension: .15}]},
+    options: {responsive: true, maintainAspectRatio: false, interaction: {mode: "index", intersect: false},
+      plugins: {legend: {labels: {color: ink, boxWidth: 14}}, tooltip: {callbacks: {label: c => `${c.dataset.label}: ${pct(c.parsed.y - 1)}`}}},
+      scales: {x: {ticks: {color: ink, maxTicksLimit: 8}, grid: {display: false}},
+               y: {ticks: {color: ink, callback: v => pct(v - 1, Math.abs(v - 1) < 0.05 ? 1 : 0)}, grid: {color: grid}}}}});
+}
+
+async function loadPerformance(){
+  try {
+    const p = await get("/api/performance"); window._perf = p; const s = p.stats || {};
+    $("t-ret").textContent = pct(s.return); cls($("t-ret"), s.return);
+    $("t-ret-s").textContent = p.start ? `since the first trade, ${p.start}` + (s.annualised != null ? ` · ${pct(s.annualised)} a year` : "") : "starts with the first trade";
+    $("t-spy").textContent = pct(s.spy_return); cls($("t-spy"), s.spy_return);
+    $("t-spy-s").textContent = s.return != null && s.spy_return != null ? `strategy ${s.return >= s.spy_return ? "ahead by" : "behind by"} ${pct(Math.abs(s.return - s.spy_return)).replace("+","")}` : "";
+    $("t-dd").textContent = s.max_drawdown == null ? "—" : pct(s.max_drawdown); cls($("t-dd"), s.max_drawdown < 0 ? -1 : null);
+    drawChart(p);
+    if (!p.dates.length) $("chartnote").textContent = "The chart starts after the first rebalance.";
+  } catch (e) { $("chartnote").textContent = "Performance unavailable: " + e.message; }
+}
+
+loadPortfolio(); loadStatus(); loadRanking(); loadOrders(); loadPerformance();
+setInterval(loadPortfolio, 30000); setInterval(loadStatus, 60000); setInterval(loadOrders, 120000);
+setInterval(loadRanking, 600000); setInterval(loadPerformance, 600000);
+</script>
+</body>
+</html>

tests/test_qt3_space.py

@@ -0,0 +1,220 @@
+"""Quality-Trend 3 Space: data client, ranking, rebalance rules and guards, execution, performance, API auth.
+No network: Sharadar and Alpaca are faked."""
+from __future__ import annotations
+
+import json
+import sys
+from datetime import date, datetime
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from qt3 import config, performance, ranking, rebalance, sharadar  # noqa: E402
+from qt3.broker import BrokerError  # noqa: E402
+
+
+# --------------------------------------------------------------------------- Sharadar client
+class _R:
+    def __init__(self, code, body):
+        self.status_code, self._b = code, body
+
+    def json(self):
+        return self._b
+
+
+class FakeHTTP:
+    def __init__(self, pages):
+        self.pages, self.calls = pages, []
+
+    def get(self, url, params=None, timeout=None):
+        self.calls.append((url, dict(params)))
+        return _R(200, self.pages[len(self.calls) - 1])
+
+
+def test_sharadar_paginates_and_maps_filters():
+    cols = [{"name": "ticker"}, {"name": "date"}]
+    s = FakeHTTP([{"datatable": {"data": [["A", "2026-10-01"]], "columns": cols}, "meta": {"next_cursor_id": "c2"}},
+                  {"datatable": {"data": [["B", "2026-10-01"]], "columns": cols}, "meta": {"next_cursor_id": None}}])
+    df = sharadar.query("SEP", "KEY", session=s, ticker="A,B", date__gte="2026-01-01", columns=["ticker", "date"])
+    assert list(df["ticker"]) == ["A", "B"]
+    p0, p1 = s.calls[0][1], s.calls[1][1]
+    assert p0["date.gte"] == "2026-01-01" and p0["qopts.columns"] == "ticker,date" and "qopts.cursor_id" not in p0
+    assert p1["qopts.cursor_id"] == "c2"
+    with pytest.raises(sharadar.SharadarError):
+        sharadar.query("SEP", "", session=s)
+
+
+# --------------------------------------------------------------------------- ranking (steps 4-5)
+def _universe(n=40, seed=0):
+    rng = np.random.default_rng(seed)
+    u = pd.DataFrame({"ticker": [f"T{i:02d}" for i in range(n)], "price": 50.0, "dv20": 2e7,
+                      "currency": "USD", "ma50_200": rng.normal(0, .1, n), "mom_6_1": rng.normal(0, .2, n)})
+    for c in ("roe", "roa", "gross_margin", "fcf_conversion", "fcf_yield", "buyback_yield",
+              "net_share_reduction_yoy", "basic_diluted_gap", "equity_financing"):
+        u[c] = rng.normal(0, 1, n)
+    return u
+
+
+def test_rank_table_pool_and_order():
+    u = _universe()
+    u.loc[0, "currency"] = "JPY"          # foreign reporter excluded
+    u.loc[1, "price"] = 3.0               # below $5 excluded
+    pool = ranking.rank_table(u)
+    assert "T00" not in set(pool["ticker"]) and "T01" not in set(pool["ticker"])
+    assert pool.attrs["liquid_usd"] == 38
+    assert len(pool) == pytest.approx(38 * 0.3, abs=1)
+    assert pool["trend"].is_monotonic_decreasing and list(pool["rank"]) == list(range(1, len(pool) + 1))
+
+
+def test_build_uses_api_tables_and_returns_ranked(monkeypatch):
+    u = _universe(60)
+    days = pd.bdate_range(end="2026-10-09", periods=260)
+    def fetch(table, key, **f):
+        assert table == "DAILY"
+        return pd.DataFrame({"ticker": u["ticker"], "date": "2026-10-09", "marketcap": np.arange(60, 0, -1) * 1e3})
+    def fetch_t(table, key, tickers, **f):
+        if table == "TICKERS":
+            return pd.concat([pd.DataFrame({"table": t, "ticker": tickers, "name": "Co", "sector": "Tech",
+                                            "industry": "X", "currency": "USD"}) for t in ("SEP", "SF1")])
+        if table == "SEP":
+            rows = []
+            for i, t in enumerate(tickers):
+                c = 100 * np.exp(np.cumsum(np.full(len(days), (i - 30) / 6000)))
+                rows.append(pd.DataFrame({"ticker": t, "date": days, "close": c, "volume": 1e6, "closeadj": c}))
+            return pd.concat(rows)
+        return pd.DataFrame()                         # SF1 empty → no quality inputs → empty pool is fine
+    r = ranking.build("KEY", today=datetime(2026, 10, 10), fetch=fetch, fetch_tickers=fetch_t)
+    assert r["prices_as_of"] == "2026-10-09" and r["universe"] == 60
+
+
+# --------------------------------------------------------------------------- rebalance rules
+RANKED = ["A", "B", "C", "D", "E", "F", "G", "H"]
+
+
+def test_target_list_keeps_top6_and_refills():
+    final, why = rebalance.target_list(RANKED, ["F", "H", "ZZ"])
+    assert final == ["A", "B", "F"]                       # F (#6) kept; H (#8) and ZZ sold; refill A, B
+    assert "#8" in why["H"] and "left the quality pool" in why["ZZ"]
+    assert rebalance.target_list(RANKED, [])[0] == ["A", "B", "C"]
+
+
+def test_plan_initial_equal_thirds_with_buffer():
+    px = {s: 100.0 for s in "ABC"}
+    p = rebalance.plan(["A", "B", "C"], {}, px, cash=10_000.0, fractional=True)
+    buys = {o["symbol"]: o["value"] for o in p["orders"]}
+    assert set(buys) == {"A", "B", "C"} and all(v == pytest.approx(3300, abs=1) for v in buys.values())
+    assert p["cash_after"] == pytest.approx(100, abs=1)
+
+
+def test_plan_sells_first_exit_and_trim():
+    px = {"A": 200.0, "B": 100.0, "C": 100.0, "OLD": 10.0}
+    p = rebalance.plan(["A", "B", "C"], {"A": 30, "B": 10, "OLD": 100}, px, cash=0.0,
+                       reasons={"OLD": "now ranked #9"}, fractional=True)
+    sides = [(o["symbol"], o["side"]) for o in p["orders"]]
+    assert sides[0] == ("OLD", "sell") and p["orders"][0]["close_all"]
+    assert ("A", "sell") in sides and sides.index(("A", "sell")) < sides.index(("C", "buy"))
+
+
+def test_plan_whole_shares_and_missing_price():
+    p = rebalance.plan(["A", "B", "C"], {}, {s: 333.0 for s in "ABC"}, cash=3000.0, fractional=False)
+    assert all(float(o["shares"]).is_integer() for o in p["orders"])
+    with pytest.raises(ValueError, match="C"):
+        rebalance.plan(["A", "B", "C"], {}, {"A": 1, "B": 1}, cash=10.0)
+
+
+# --------------------------------------------------------------------------- guards + execution (fake Alpaca)
+class FakeAlpaca:
+    def __init__(self, open_=True, orders=(), days=None, fill="filled"):
+        self.open_, self._orders, self.fill = open_, list(orders), fill
+        self._days = days or ["2026-11-02", "2026-11-03", "2026-11-04", "2026-11-05", "2026-11-06", "2026-11-09",
+                              "2026-12-01"]
+        self.submitted = []
+        self.cash = 0.0
+
+    def clock(self):
+        return {"is_open": self.open_, "next_open": "2026-11-03T09:30:00-05:00"}
+
+    def trading_days(self, s, e):
+        return self._days
+
+    def orders(self, after=None, status="all", limit=500):
+        return self._orders
+
+    def submit(self, symbol, side, qty=None, notional=None, client_order_id=None):
+        self.submitted.append({"symbol": symbol, "side": side, "qty": qty, "notional": notional, "cid": client_order_id})
+        if side == "sell":
+            self.cash += 1000.0
+        return {"id": f"o{len(self.submitted)}", "status": "accepted"}
+
+    def wait(self, ids, seconds=0, poll=0):
+        return {i: {"status": self.fill} for i in ids}
+
+    def account(self):
+        return {"cash": self.cash, "non_marginable_buying_power": self.cash, "equity": 10_000.0}
+
+
+NOV2 = datetime(2026, 11, 2, 10, 30, tzinfo=rebalance.NY)
+FRESH = {"ranked": [{"ticker": t} for t in RANKED], "prices_as_of": "2026-10-30"}
+
+
+def test_check_first_run_and_guards():
+    assert rebalance.check(FakeAlpaca(), FRESH, NOV2)["ok"]                          # first run, day 1, open
+    assert "market closed" in rebalance.check(FakeAlpaca(open_=False), FRESH, NOV2)["reasons"][0]
+    stale = {**FRESH, "prices_as_of": "2026-10-20"}
+    assert any("days old" in r for r in rebalance.check(FakeAlpaca(), stale, NOV2)["reasons"])
+    done = [{"client_order_id": "qt3-20261102-A-buy", "side": "buy", "status": "filled",
+             "created_at": "2026-11-02T15:00:01.123456789Z"}]
+    c = rebalance.check(FakeAlpaca(orders=done), FRESH, NOV2)
+    assert not c["ok"] and "already rebalanced this month" in c["reasons"] and c["done_this_month"]
+    old = [{"client_order_id": "qt3-20261001-A-buy", "side": "buy", "status": "filled",
+            "created_at": "2026-10-01T15:00:00Z"}]
+    late = datetime(2026, 11, 9, 10, 30, tzinfo=rebalance.NY)                          # 6th trading day
+    assert any("window" in r for r in rebalance.check(FakeAlpaca(orders=old), FRESH, late)["reasons"])
+    fresh_late = {**FRESH, "prices_as_of": "2026-11-06"}
+    assert rebalance.check(FakeAlpaca(orders=old), fresh_late, late, force=True)["ok"]      # force skips window
+    assert not rebalance.check(FakeAlpaca(orders=old), FRESH, late, force=True)["ok"]      # never stale data
+
+
+def test_execute_sells_then_scaled_buys_with_ids():
+    a = FakeAlpaca()
+    p = {"fractional": True, "orders": [
+        {"symbol": "OLD", "side": "sell", "shares": 5.0, "value": 1000.0},
+        {"symbol": "A", "side": "buy", "shares": 1.0, "value": 600.0},
+        {"symbol": "B", "side": "buy", "shares": 1.0, "value": 600.0}]}
+    res = rebalance.execute(a, p, today=date(2026, 11, 2))
+    assert [r["side"] for r in res] == ["sell", "buy", "buy"]
+    assert a.submitted[0]["cid"] == "qt3-20261102-OLD-sell"
+    # cash after sells 1000 − 1% of equity (100) = 900 → buys scaled 900/1200
+    assert a.submitted[1]["notional"] == pytest.approx(450.0) and a.submitted[1]["cid"] == "qt3-20261102-A-buy"
+
+
+def test_execute_defers_buys_if_sells_not_filled():
+    a = FakeAlpaca(fill="new")
+    res = rebalance.execute(a, {"fractional": True, "orders": [
+        {"symbol": "OLD", "side": "sell", "shares": 1.0, "value": 10.0},
+        {"symbol": "A", "side": "buy", "shares": 1.0, "value": 10.0}]}, today=date(2026, 11, 2), wait_s=0)
+    assert res[-1]["status"].startswith("deferred") and all(s["side"] == "sell" for s in a.submitted)
+
+
+# --------------------------------------------------------------------------- performance
+def test_twr_excludes_deposits_and_drawdown():
+    g = performance.twr(["d1", "d2", "d3"], [1000.0, 2100.0, 1890.0], {"d2": 1000.0})
+    assert g[1] == pytest.approx(1.10) and g[2] == pytest.approx(0.99)
+    assert performance.max_drawdown([1.0, 1.2, 0.9, 1.3]) == pytest.approx(-0.25)
+
+
+# --------------------------------------------------------------------------- API auth
+def test_rebalance_endpoint_requires_token(monkeypatch, tmp_path):
+    from fastapi.testclient import TestClient
+    monkeypatch.setattr(config, "REBALANCE_TOKEN", "secret-token")
+    monkeypatch.setattr(config, "NDL_KEY", "")
+    monkeypatch.setattr(config, "CACHE_DIR", str(tmp_path))
+    (tmp_path / "ranking.json").write_text(json.dumps({**FRESH, "built": datetime.now().astimezone().isoformat()}))
+    import app as space
+    c = TestClient(space.app)
+    assert c.get("/api/health").json()["rebalance_enabled"]
+    r = c.post("/api/rebalance?dry=0", headers={"X-Rebalance-Token": "wrong"})
+    assert r.status_code == 403