Built-in monthly scheduler (no GitHub needed); README keep-awake notes

README.md

@@ -35,9 +35,13 @@ worst fall −34%, any 12 months median +24% (in profit 87% of the time). Backte
   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).
+- **Schedule (built in)** — the Space runs its own timer (`qt3/scheduler.py`): every 15 minutes it rebuilds the
+  ranking if it is older than 20 hours, and on weekdays 10:00–15:30 New York time it attempts the guarded rebalance
+  above — so it trades on the first trading day of each month and does nothing otherwise. No GitHub needed.
+  Set `AUTO_REBALANCE=0` to switch it off. The GitHub workflows in `.github/workflows/` remain an optional backup.
+- **Keep-awake** — a free Space sleeps after 48 h without visitors, and a sleeping Space's timer stops. Either point a
+  free uptime monitor (e.g. UptimeRobot or cron-job.org) at `https://s-ttp-updraft.hf.space/api/health` every 30–60
+  minutes (no secrets involved), or move the Space to paid hardware with sleep turned off.
 - **State** — all in Alpaca (positions, orders, portfolio history). A restart only rebuilds the ranking cache.
 
 ## Settings (Space → Settings → Variables and secrets)

app.py

@@ -3,8 +3,9 @@
 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.
+The Space schedules itself (qt3/scheduler.py: a 15-minute tick that rebuilds the ranking daily and attempts the
+guarded rebalance on weekdays 10:00-15:30 New York); an outside cron calling /api/rebalance is optional. Either
+way it trades only on the first trading days of a month (once), while the market is open, on fresh data.
 """
 from __future__ import annotations
 
@@ -17,13 +18,15 @@ 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 import config, performance, ranking, rebalance, scheduler
 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
+    scheduler.start()                        # the Space's own monthly rebalance timer
     yield
 
 
@@ -59,7 +62,7 @@ def index():
 
 @app.get("/api/health")
 def health():
-    return {"ok": True, **config.status(), "ranking_state": ranking.state()}
+    return {"ok": True, **config.status(), "ranking_state": ranking.state(), "scheduler": scheduler.STATE}
 
 
 @app.get("/api/ranking")
@@ -131,7 +134,8 @@ async def status():
             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()}
+                "would_trade_now": chk["ok"], "blocked_by": chk["reasons"], "scheduler": scheduler.STATE,
+                **config.status()}
     try:
         return await run_in_threadpool(cached, "status", 60, load)
     except BrokerError as e:
@@ -165,13 +169,10 @@ async def run_rebalance(dry: int = 1, force: int = 0, x_rebalance_token: str = H
         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)
+        out = await run_in_threadpool(scheduler.run_once, bool(force), a)
     except (BrokerError, ValueError) as e:
         raise HTTPException(502, f"rebalance failed: {e}")
-    _cache.clear()
-    return {"dry_run": False, "executed": True, "plan": p, "results": res}
+    if out.get("executed"):
+        _cache.clear()
+    return {"dry_run": False, **out}

qt3/config.py

@@ -12,6 +12,7 @@ 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", "")
+AUTO_REBALANCE = os.getenv("AUTO_REBALANCE", "1").strip() == "1"   # the Space's own monthly scheduler
 
 # 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
@@ -33,4 +34,4 @@ INCEPTION = os.getenv("QT3_INCEPTION", "")              # YYYY-MM-DD for public
 
 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)}
+            "paper": ALPACA_PAPER, "rebalance_enabled": bool(REBALANCE_TOKEN), "auto_rebalance": AUTO_REBALANCE}

qt3/scheduler.py

@@ -0,0 +1,78 @@
+"""In-Space scheduler — the Space triggers its own monthly rebalance (no GitHub or outside cron needed).
+
+A background thread wakes every 15 minutes. Each tick it rebuilds the ranking if it is older than 20 hours, and on
+weekdays between 10:00 and 15:30 New York time it calls the same guarded rebalance as POST /api/rebalance: that
+trades only while the market is open, on one of the first 5 trading days of a month (or the very first run), once
+a month, on data at most 5 days old — every other tick is a cheap no-op. A lock makes the scheduler and the API
+never run a rebalance at the same time; Alpaca's order history (orders tagged "qt3-") is the only state, so a
+restart cannot cause a second trade. The thread needs the Space to be awake (see README: keep-awake).
+"""
+from __future__ import annotations
+
+import os
+import threading
+import time
+from datetime import datetime
+from datetime import time as dtime
+
+from . import config, ranking, rebalance
+from .broker import Alpaca
+
+FROM, TO = dtime(10, 0), dtime(15, 30)            # New York time; trades after the opening auction settles
+STATE = {"enabled": config.AUTO_REBALANCE, "running": False, "interval_min": None, "last_tick": None,
+         "last_attempt": None, "last_result": None, "last_error": None}
+_lock = threading.Lock()
+
+
+def due(now: datetime) -> bool:
+    now = now.astimezone(rebalance.NY)
+    return now.weekday() < 5 and FROM <= now.time() <= TO
+
+
+def run_once(force: bool = False, alpaca: Alpaca | None = None) -> dict:
+    """One guarded rebalance attempt (shared by the scheduler and the API)."""
+    if not _lock.acquire(blocking=False):
+        return {"executed": False, "reasons": ["a rebalance is already running"]}
+    try:
+        r = ranking.refresh()
+        a = alpaca or Alpaca()
+        chk = rebalance.check(a, r, None, force)
+        if not chk["ok"]:
+            return {"executed": False, "reasons": chk["reasons"]}
+        p = rebalance.build_plan(a, r)
+        res = rebalance.execute(a, p)
+        return {"executed": True, "plan": p, "results": res}
+    finally:
+        _lock.release()
+
+
+def _tick() -> None:
+    now = datetime.now(rebalance.NY)
+    STATE["last_tick"] = now.isoformat(timespec="seconds")
+    if config.NDL_KEY:
+        ranking.refresh()                         # no-op unless older than RANKING_MAX_AGE_H
+    if config.AUTO_REBALANCE and due(now):
+        out = run_once()
+        STATE["last_attempt"] = now.isoformat(timespec="seconds")
+        STATE["last_result"] = ({"executed": True, "orders": [f"{x['side']} {x['symbol']} {x.get('status')}"
+                                                              for x in out.get("results", [])]}
+                                if out.get("executed") else {"executed": False, "reasons": out.get("reasons")})
+
+
+def _loop(interval_s: float) -> None:
+    while True:
+        try:
+            _tick()
+            STATE["last_error"] = None
+        except Exception as e:  # noqa: BLE001 — keep the thread alive; the next tick retries
+            STATE["last_error"] = f"{type(e).__name__}: {e}"[:300]
+        time.sleep(interval_s)
+
+
+def start(interval_s: float = 900) -> bool:
+    configured = config.NDL_KEY and config.ALPACA_KEY and config.ALPACA_SECRET
+    if STATE["running"] or not configured or os.getenv("QT3_DISABLE_SCHEDULER"):
+        return False
+    threading.Thread(target=_loop, args=(interval_s,), daemon=True, name="updraft-scheduler").start()
+    STATE.update(running=True, interval_min=interval_s / 60)
+    return True

tests/test_qt3_space.py

@@ -218,3 +218,26 @@ def test_rebalance_endpoint_requires_token(monkeypatch, tmp_path):
     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
+
+
+# --------------------------------------------------------------------------- in-Space scheduler
+def test_scheduler_window_and_guarded_run(monkeypatch):
+    from qt3 import scheduler
+    ny = rebalance.NY
+    assert scheduler.due(datetime(2026, 11, 2, 10, 15, tzinfo=ny))          # Monday 10:15 New York
+    assert not scheduler.due(datetime(2026, 11, 2, 9, 45, tzinfo=ny))      # before 10:00
+    assert not scheduler.due(datetime(2026, 11, 2, 15, 45, tzinfo=ny))     # after 15:30
+    assert not scheduler.due(datetime(2026, 11, 7, 11, 0, tzinfo=ny))      # Saturday
+    monkeypatch.setattr(ranking, "refresh", lambda force=False: FRESH)
+    a = FakeAlpaca(open_=False)
+    out = scheduler.run_once(alpaca=a)
+    assert not out["executed"] and "market closed" in out["reasons"][0] and a.submitted == []
+    assert scheduler._lock.acquire(blocking=False)                        # lock released afterwards
+    scheduler._lock.release()
+
+
+def test_scheduler_not_started_without_keys(monkeypatch):
+    from qt3 import scheduler
+    monkeypatch.setattr(config, "ALPACA_KEY", "")
+    monkeypatch.setattr(scheduler, "STATE", {**scheduler.STATE, "running": False})
+    assert scheduler.start() is False