start experiment 82 (exp/82-scheduled-algo-retrain-on-2026-09-24-tac)

code/MANIFEST.txt

@@ -1,19 +1,34 @@
 # TradeAC custom-qlib-code snapshot (auto-generated)
-# parent repo HEAD : c455000a1ec2ad80a0146a3768a4ccfe9ff32b24
+# parent repo HEAD : 6d2e4976550234d91bc9d0ea65fe100d04befede
 #   tac-qlib/tac_qlib/contrib
 #   tac-qlib/tac_qlib/data
 # per-file hashes (git hash-object):
   1b6298c4a5652f2e863cbdc385a1014a570fcd59  tac-qlib/tac_qlib/contrib/__init__.py
+  d1a8ec0c9e6c38839e966f687b08ec412f87ec20  tac-qlib/tac_qlib/contrib/__pycache__/__init__.cpython-312.pyc
+  2224424d0ff193be4f55d1b791f8fce89439c5d2  tac-qlib/tac_qlib/contrib/backtest/__init__.py
+  0bf40dee440ddbded357d7bbb4efc67c62c4b084  tac-qlib/tac_qlib/contrib/backtest/tradeac_exchange.py
   c76a9f17f680e74eea766eff27f7624359749ed6  tac-qlib/tac_qlib/contrib/data/__init__.py
-  0dd25ef161c6e0f15eafc84886e7e1381deb38c3  tac-qlib/tac_qlib/contrib/data/handler.py
+  c1543fabfc22e07c7e9942015c4462f84acc1e91  tac-qlib/tac_qlib/contrib/data/__pycache__/__init__.cpython-312.pyc
+  89f5cfc15b946b6ea1fb7724f021024967cdb6c5  tac-qlib/tac_qlib/contrib/data/__pycache__/handler.cpython-312.pyc
+  3bba0f1696e4ab4b3deebec3f31f269b2e713899  tac-qlib/tac_qlib/contrib/data/handler.py
   b151d139a0dcde87d74b21e7c4b729176ba5c39b  tac-qlib/tac_qlib/contrib/model/__init__.py
+  f4e9bf0a78d22e256cade0d794a6958aaa7c6721  tac-qlib/tac_qlib/contrib/model/__pycache__/__init__.cpython-312.pyc
+  c35c166a8449c14fa3cd4972c363d3d9d58620ef  tac-qlib/tac_qlib/contrib/model/__pycache__/rank_ensemble.cpython-312.pyc
+  98be60fe19fedb3d9cb21c3f91ef0e176bd93287  tac-qlib/tac_qlib/contrib/model/__pycache__/rank_gbdt.cpython-312.pyc
   d3f051f3a8650c42fedc7b367b966f7c74fb5789  tac-qlib/tac_qlib/contrib/model/rank_ensemble.py
-  ccfe7d554989aa7f3e5a2128ae663e51b2207149  tac-qlib/tac_qlib/contrib/model/rank_gbdt.py
+  d03e6611338918d4aac5eea4adf26f85a3763652  tac-qlib/tac_qlib/contrib/model/rank_gbdt.py
-  4afcf9058231111c412925f4c4b84e81d656db87  tac-qlib/tac_qlib/contrib/strategy/__init__.py
+  184f80da8edf944bad3c8fb4d4d3d189bf4f082b  tac-qlib/tac_qlib/contrib/strategy/__init__.py
+  69684c9c9624cb16c63f3a18a864c49a7db37fa9  tac-qlib/tac_qlib/contrib/strategy/__pycache__/__init__.cpython-312.pyc
+  4d3a5433e57e65e5dc96c6d2999f9d473b696dc4  tac-qlib/tac_qlib/contrib/strategy/__pycache__/long_short.cpython-312.pyc
+  53e72f512b47207a5292a918efef7fee162deef3  tac-qlib/tac_qlib/contrib/strategy/__pycache__/optimal_stop.cpython-312.pyc
+  896ef74ae47bcd1ed388e1e5d9c8d70c28097fe9  tac-qlib/tac_qlib/contrib/strategy/kelly_dropout.py
+  9090fc6dfbd339f2f4df4b0c9b87f400ecb5c9d5  tac-qlib/tac_qlib/contrib/strategy/long_short.py
   79aaad9e39fcc740a773f4f63c512ce1086cfde0  tac-qlib/tac_qlib/contrib/strategy/optimal_stop.py
+  5b9acfb4340111b204249add7760bd53c6ae03f1  tac-qlib/tac_qlib/contrib/strategy/regime_gate.py
+  839abb89ad40cd516eabcfd91fe1be626b9f091f  tac-qlib/tac_qlib/contrib/strategy/weekly_rebalance.py
   92e6e90eb0cd0a25142034560f27adb6b705b1a8  tac-qlib/tac_qlib/data/__init__.py
-  3cbc0686e6f863d306d93c589a607a5bdb7201f2  tac-qlib/tac_qlib/data/__pycache__/__init__.cpython-312.pyc
+  0f1eb6f41d44bd9064b1f16f529dac6bb9d7c3fd  tac-qlib/tac_qlib/data/__pycache__/__init__.cpython-312.pyc
-  46bcdbcc173ff3a6281fed33d10c1bcac96876b0  tac-qlib/tac_qlib/data/__pycache__/config.cpython-312.pyc
+  cf99dd8a481f6e2d1f323f8d8d754730eadb357a  tac-qlib/tac_qlib/data/__pycache__/config.cpython-312.pyc
-  6df4f88af22ab4c026c14ef1835f2e630cdf850c  tac-qlib/tac_qlib/data/__pycache__/providers.cpython-312.pyc
+  ddac5bab6578399c0301390d71bae13511a56cb1  tac-qlib/tac_qlib/data/__pycache__/providers.cpython-312.pyc
-  53c9007a928841fd3c3b08450f9a6520ce1ac091  tac-qlib/tac_qlib/data/config.py
+  1953fb2a6371525db7f7b0e1c9dfbf3492d82110  tac-qlib/tac_qlib/data/config.py
   8d0644f6f0d1efb94798ed444cc73e63b643459b  tac-qlib/tac_qlib/data/providers.py

code/tac-qlib/tac_qlib/contrib/backtest/__init__.py

@@ -0,0 +1 @@
+from .tradeac_exchange import TradeACExchange

code/tac-qlib/tac_qlib/contrib/backtest/tradeac_exchange.py

@@ -0,0 +1,432 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+TradeACExchange
+
+A short/borrow enabled Exchange implementation built on top of qlib.backtest.exchange.Exchange.
+This exchange adds simple, configurable margin logic (initial/maintenance), borrowing support for
+shorts, a borrow fee, and a lightweight SMA (Special Memorandum Account) concept to emulate
+behaviors similar to brokers such as IBKR and Alpaca for backtesting purposes.
+
+Notes / limitations
+- This implementation is intentionally lightweight and conservative: it implements the
+  key behaviors needed for strategy/backtest experiments (allowing short selling, computing
+  margin requirements, performing margin-call checks, and tracking SMA-like excess equity).
+- It makes some simplifying assumptions compared to real brokers (no per-product house margins,
+  simplified SMA bookkeeping, borrow availability modeled only by a per-symbol boolean/limit).
+- The Position class in qlib.backtest.position was not changed. To support shorts we update the
+  position.position dict directly when necessary. This keeps integration simple but bypasses some
+  internal Position helpers. Use with care.
+
+API additions
+- allow_short: enable short selling (bool)
+- initial_margin_long/short: fraction required to open a position
+- maintenance_margin_long/short: fraction required to keep a position
+- borrow_fee_rate: periodic borrow fee applied on short value (applied at trade time as additional cost)
+- borrowable: dict mapping stock_id -> bool or float (max borrowable shares). Symbols missing from
+  the dict follow `borrow_default` (default True = unlimited; set False for a strict whitelist)
+- get_sma(position): returns SMA-like excess equity available as "buying power credit"
+- check_margin_call(position): returns True if position is below maintenance requirement
+
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Tuple
+
+import numpy as np
+
+from qlib.backtest.decision import Order
+from qlib.backtest.exchange import Exchange
+from qlib.backtest.position import BasePosition
+
+
+class TradeACExchange(Exchange):
+    """An exchange that supports short selling / borrowing and basic margin rules.
+
+    The implementation aims to be compatible with the Exchange API used by Account and
+    Position classes in qlib.backtest. It overrides only the minimum methods required to
+    enable short/borrow behavior and margin calculations.
+    """
+
+    def __init__(
+        self,
+        *args: Any,
+        allow_short: bool = True,
+        initial_margin_long: float = 0.5,
+        initial_margin_short: float = 0.5,
+        maintenance_margin_long: float = 0.25,
+        maintenance_margin_short: float = 0.3,
+        borrow_fee_rate: float = 0.0,
+        borrowable: Optional[Dict[str, float]] = None,
+        borrow_default: bool = True,
+        sma_enabled: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        """Create TradeACExchange.
+
+        Parameters mirror Exchange with additional tradeac-specific options.
+        """
+        super().__init__(*args, **kwargs)
+        self.allow_short = allow_short
+        self.initial_margin_long = initial_margin_long
+        self.initial_margin_short = initial_margin_short
+        self.maintenance_margin_long = maintenance_margin_long
+        self.maintenance_margin_short = maintenance_margin_short
+        self.borrow_fee_rate = borrow_fee_rate
+        # borrowable can be a dict with per-symbol max borrowable amount, or None (unlimited)
+        self.borrowable = borrowable or {}
+        # borrow_default: policy for symbols absent from `borrowable`.
+        #   True  -> unlisted symbols are unlimited-borrowable (legacy behavior)
+        #   False -> unlisted symbols are NOT borrowable; only listed ones can be shorted
+        self.borrow_default = bool(borrow_default)
+        # sma_enabled: whether to expose lightweight SMA calculation
+        self.sma_enabled = sma_enabled
+
+    # --------------------------- Helper calculations ---------------------------
+    def _initial_margin_requirement(self, position: BasePosition) -> float:
+        """Compute the initial margin requirement (money) for the given position.
+
+        We treat longs and shorts separately and sum their required initial margins.
+        """
+        im_req = 0.0
+        for sid in position.get_stock_list():
+            amt = position.get_stock_amount(sid)
+            price = position.get_stock_price(sid)
+            val = amt * price
+            if val > 0:
+                im_req += abs(val) * self.initial_margin_long
+            elif val < 0:
+                im_req += abs(val) * self.initial_margin_short
+        return im_req
+
+    def _maintenance_margin_requirement(self, position: BasePosition) -> float:
+        """Compute the maintenance margin requirement (money) for the given position."""
+        mm_req = 0.0
+        for sid in position.get_stock_list():
+            amt = position.get_stock_amount(sid)
+            price = position.get_stock_price(sid)
+            val = amt * price
+            if val > 0:
+                mm_req += abs(val) * self.maintenance_margin_long
+            elif val < 0:
+                mm_req += abs(val) * self.maintenance_margin_short
+        return mm_req
+
+    def get_equity(self, position: BasePosition) -> float:
+        """Return account equity (position value + cash)."""
+        return position.calculate_value()
+
+    def get_sma(self, position: BasePosition) -> float:
+        """Return a simplified SMA: excess equity above initial margin requirement.
+
+        Note: This is a synthetic/Simplified SMA used for strategy/backtest logic. Real-broker
+        SMA accounting (e.g. credits/debits across days) can be more complex.
+        """
+        if not self.sma_enabled:
+            return 0.0
+        equity = self.get_equity(position)
+        im_req = self._initial_margin_requirement(position)
+        return max(0.0, equity - im_req)
+
+    def check_margin_call(self, position: BasePosition) -> bool:
+        """Return True when the account is under maintenance margin (margin call).
+
+        Margin call condition here is simple: equity < maintenance requirement.
+        """
+        equity = self.get_equity(position)
+        mm_req = self._maintenance_margin_requirement(position)
+        return equity < mm_req
+
+    def get_buying_power(self, position: BasePosition) -> float:
+        """Estimate buying power for new long positions assuming opening margin requirement.
+
+        Simplified: the maximum notional long value = equity / initial_margin_long.
+        """
+        equity = self.get_equity(position)
+        if self.initial_margin_long <= 0:
+            return 0.0
+        return equity / self.initial_margin_long
+
+    # --------------------------- Order / execution overrides ---------------------------
+    def _borrow_headroom(self, stock_id: str, current_short: float) -> float:
+        """Remaining borrowable shares for `stock_id` given an already-open short of `current_short` shares.
+
+        borrowable values: bool (True=unlimited, False=not borrowable) or numeric max shares.
+        Missing symbols follow `borrow_default` (True = unlimited when allow_short is enabled).
+        """
+        if not self.allow_short:
+            return 0.0
+        v = self.borrowable.get(stock_id, self.borrow_default)
+        if isinstance(v, bool):
+            return float("inf") if v else 0.0
+        try:
+            limit = float(v)
+        except (TypeError, ValueError):
+            return float("inf")
+        return max(0.0, limit - max(current_short, 0.0))
+
+    def _calc_trade_info_by_order(
+        self,
+        order: Order,
+        position: Optional[BasePosition],
+        dealt_order_amount: Dict[str, float],
+    ) -> Tuple[float, float, float]:
+        """Override to allow (optionally) short selling and to apply borrow fees.
+
+        The original Exchange implementation forbids selling more than you own. Here we allow
+        sell orders to create/expand short positions when allow_short is True. We still rely on
+        most base logic (price discovery, impact, cost calculation) by calling super(), but we
+        adjust the sell-side clipping behavior before delegating to the base implementation.
+        """
+        # When selling and shorts are allowed, temporarily relax the clipping logic in the base
+        # implementation by monkey-patching current position check. Simpler: replicate minimal
+        # parts of logic from Exchange._calc_trade_info_by_order with the key change.
+
+        # Get basic trade price & volume info using Exchange helpers
+        trade_price = float(self.get_deal_price(order.stock_id, order.start_time, order.end_time, direction=order.direction))
+        total_trade_val = float(self.get_volume(order.stock_id, order.start_time, order.end_time) or 0.0) * trade_price
+
+        order.factor = self.get_factor(order.stock_id, order.start_time, order.end_time)
+        order.deal_amount = order.amount  # attempt full
+
+        # volume clipping (same as base)
+        self._clip_amount_by_volume(order, dealt_order_amount)
+
+        # approximate adjusted cost ratio based on liquidity
+        if not total_trade_val or np.isnan(total_trade_val) or total_trade_val <= 0:
+            adj_cost_ratio = self.impact_cost
+        else:
+            trade_val_tmp = order.deal_amount * trade_price
+            adj_cost_ratio = self.impact_cost * (trade_val_tmp / total_trade_val) ** 2
+
+        # Differentiate buy / sell
+        if order.direction == Order.SELL:
+            cost_ratio = self.close_cost + adj_cost_ratio
+            current_amount = (
+                position.get_stock_amount(order.stock_id) if (position is not None and position.check_stock(order.stock_id)) else 0.0
+            )
+            long_held = max(current_amount, 0.0)
+            short_open = max(-current_amount, 0.0)
+
+            if position is not None:
+                if not self.allow_short:
+                    # clip by current holdings only
+                    if not np.isclose(order.deal_amount, current_amount):
+                        order.deal_amount = self.round_amount_by_trade_unit(
+                            min(long_held, order.deal_amount), order.factor
+                        )
+                else:
+                    # allow selling beyond holdings up to the remaining borrow limit;
+                    # later when updating the position we create/expand a short if necessary.
+                    max_sell = long_held + self._borrow_headroom(order.stock_id, short_open)
+                    if order.deal_amount > max_sell and not np.isclose(order.deal_amount, max_sell):
+                        order.deal_amount = self.round_amount_by_trade_unit(max_sell, order.factor)
+
+        elif order.direction == Order.BUY:
+            cost_ratio = self.open_cost + adj_cost_ratio
+            if position is not None:
+                cash = position.get_cash()
+                trade_val = order.deal_amount * trade_price
+                if cash < max(trade_val * cost_ratio, self.min_cost):
+                    order.deal_amount = 0
+                    self.logger.debug(f"Order clipped due to cost higher than cash: {order}")
+                elif cash < trade_val + max(trade_val * cost_ratio, self.min_cost):
+                    max_buy_amount = self._get_buy_amount_by_cash_limit(trade_price, cash, cost_ratio)
+                    order.deal_amount = self.round_amount_by_trade_unit(min(max_buy_amount, order.deal_amount), order.factor)
+                    self.logger.debug(f"Order clipped due to cash limitation: {order}")
+                else:
+                    order.deal_amount = self.round_amount_by_trade_unit(order.deal_amount, order.factor)
+            else:
+                order.deal_amount = self.round_amount_by_trade_unit(order.deal_amount, order.factor)
+        else:
+            raise NotImplementedError("order direction {} error".format(order.direction))
+
+        # compute final trade_val & trade_cost
+        trade_val = order.deal_amount * trade_price
+        # base trade_cost
+        trade_cost = max(trade_val * cost_ratio, self.min_cost)
+        # apply borrow fee only on the net-new short portion of the sell
+        if order.direction == Order.SELL and self.allow_short:
+            new_short = max(0.0, order.deal_amount - long_held)
+            trade_cost += new_short * trade_price * self.borrow_fee_rate
+
+        if trade_val <= 1e-5:
+            trade_cost = 0
+
+        return trade_price, trade_val, trade_cost
+
+    def deal_order(
+        self,
+        order: Order,
+        trade_account: Optional[Any] = None,
+        position: Optional[BasePosition] = None,
+        dealt_order_amount: Dict[str, float] = None,
+    ) -> Tuple[float, float, float]:
+        """Deal order and handle short position bookkeeping.
+
+        This method mirrors Exchange.deal_order but when a position is provided and shorts are
+        allowed it will update the Position.position dict directly to support negative amounts.
+        """
+        if dealt_order_amount is None:
+            dealt_order_amount = {}
+
+        if not self.check_order(order):
+            order.deal_amount = 0.0
+            self.logger.debug(f"Order failed due to trading limitation: {order}")
+            return 0.0, 0.0, np.nan
+
+        if trade_account is not None and position is not None:
+            raise ValueError("trade_account and position can only choose one")
+
+        pos = position or (trade_account.current_position if trade_account is not None else None)
+        trade_price, trade_val, trade_cost = self._calc_trade_info_by_order(order, pos, dealt_order_amount)
+
+        if trade_val > 1e-5:
+            if trade_account is not None:
+                cp = trade_account.current_position
+                if not cp.skip_update():
+                    held = cp.check_stock(order.stock_id)
+                    # Account-level bookkeeping (turnover/cost/returns). Mirrors
+                    # Account._update_state_from_order except for fresh short sales,
+                    # where no prior price exists to compute order profit from.
+                    if order.direction == Order.SELL and not held:
+                        trade_account.accum_info.add_turnover(trade_val)
+                        trade_account.accum_info.add_cost(trade_cost)
+                        trade_account.accum_info.add_return_value(0.0)
+                    if order.direction == Order.SELL:
+                        # sell: update account state first (stock entry may be deleted)
+                        if held:
+                            trade_account._update_state_from_order(order, trade_val, trade_cost, trade_price)
+                        self._position_sell(cp, order, trade_val, trade_cost, trade_price)
+                    else:
+                        # buy: update position first (entry may be created), then account state
+                        # A buy that covers a short to exactly flat deletes the entry inside
+                        # _position_buy; re-seed a transient zero-amount stub so the
+                        # account's order-profit lookup still finds the trade price,
+                        # then drop it (_update_state_from_order never mutates entries).
+                        sid = order.stock_id
+                        had_entry = isinstance(cp.position.get(sid), dict)
+                        self._position_buy(cp, order, trade_val, trade_cost, trade_price)
+                        covered_to_flat = had_entry and not isinstance(cp.position.get(sid), dict)
+                        if covered_to_flat:
+                            cp.position[sid] = {"amount": 0.0, "price": trade_price, "weight": 0}
+                        trade_account._update_state_from_order(order, trade_val, trade_cost, trade_price)
+                        if covered_to_flat:
+                            cp.position.pop(sid, None)
+            elif position is not None:
+                if order.direction == Order.BUY:
+                    self._position_buy(position, order, trade_val, trade_cost, trade_price)
+                else:
+                    self._position_sell(position, order, trade_val, trade_cost, trade_price)
+        return trade_val, trade_cost, trade_price
+
+    # --------------------------- Position mutation helpers ---------------------------
+    def _position_buy(self, position: BasePosition, order: Order, trade_val: float, cost: float, trade_price: float) -> None:
+        """Handle buy order bookkeeping against a BasePosition while supporting shorts.
+
+        Rules implemented (simplified):
+        - If there is an existing short (amount < 0), the buy will first cover the short.
+        - If covering closes the short completely, the remaining buy becomes a long
+        - Cash updates mimic Position._buy_stock/_sell_stock (cash decreases by trade_val+cost for buys)
+        """
+        trade_amount = trade_val / trade_price
+        sid = order.stock_id
+        current_amount = position.get_stock_amount(sid) if position.check_stock(sid) else 0.0
+
+        # covering existing short
+        if current_amount < -1e-12:
+            # amount is negative -> we are short. Buying reduces the short.
+            new_amount = current_amount + trade_amount
+            if abs(new_amount) <= 1e-8:
+                # short fully covered exactly -> remove entry
+                if sid in position.position:
+                    del position.position[sid]
+            elif new_amount > 0:
+                # short fully covered with leftover buy amount -> leftover becomes a long position
+                position.position[sid] = {"amount": new_amount, "price": trade_price, "weight": 0}
+            else:
+                # partially cover
+                position.position[sid]["amount"] = new_amount
+                position.position[sid]["price"] = trade_price
+        else:
+            # normal or increasing long
+            if sid not in position.position or not isinstance(position.position[sid], dict):
+                # initialize stock
+                position.position[sid] = {"amount": trade_amount, "price": trade_price, "weight": 0}
+            else:
+                position.position[sid]["amount"] = position.position[sid].get("amount", 0.0) + trade_amount
+                position.position[sid]["price"] = trade_price
+
+        # cash effect same as Position._buy_stock
+        position.position["cash"] -= trade_val + cost
+
+    def _position_sell(self, position: BasePosition, order: Order, trade_val: float, cost: float, trade_price: float) -> None:
+        """Handle sell order bookkeeping against a BasePosition while supporting shorts.
+
+        Rules implemented (simplified):
+        - If holding enough long shares, sell will reduce/close the long position normally.
+        - If not holding enough long shares and shorts are allowed, the remaining sold amount will create/expand a short position.
+        - Cash update for sells follows Position._sell_stock logic (cash increases by trade_val - cost)
+        """
+        trade_amount = trade_val / trade_price
+        sid = order.stock_id
+        current_amount = position.get_stock_amount(sid) if position.check_stock(sid) else 0.0
+
+        if current_amount > 1e-12:
+            # we have long shares; sell from them first
+            if trade_amount >= current_amount - 1e-8:
+                # selling all or more than holdings
+                # remove long position
+                if sid in position.position:
+                    del position.position[sid]
+                # remaining sold amount becomes short if allowed
+                remain = trade_amount - current_amount
+                if remain > 1e-8:
+                    if not self.allow_short:
+                        # should not happen due to clipping earlier, but guard anyway
+                        raise ValueError(f"Attempt to short {sid} while shorting disabled")
+                    # create short entry
+                    position.position[sid] = {"amount": -remain, "price": trade_price, "weight": 0}
+            else:
+                # partial sell
+                position.position[sid]["amount"] = current_amount - trade_amount
+                position.position[sid]["price"] = trade_price
+        else:
+            # currently flat or already short
+            if not self.allow_short:
+                raise ValueError(f"Attempt to short {sid} while shorting disabled")
+            # expand short
+            new_amount = current_amount - trade_amount
+            if sid not in position.position or not isinstance(position.position[sid], dict):
+                position.position[sid] = {"amount": new_amount, "price": trade_price, "weight": 0}
+            else:
+                position.position[sid]["amount"] = new_amount
+                position.position[sid]["price"] = trade_price
+
+        # cash effect same as Position._sell_stock
+        new_cash = trade_val - cost
+        if getattr(position, "_settle_type", None) == position.ST_CASH:
+            position.position["cash_delay"] = position.position.get("cash_delay", 0.0) + new_cash
+        else:
+            position.position["cash"] = position.position.get("cash", 0.0) + new_cash
+
+    # --------------------------- Borrow availability helpers ---------------------------
+    def is_borrowable(self, stock_id: str, amount: float) -> bool:
+        """Check whether the requested amount is borrowable for the given stock.
+
+        If a borrowable dict is provided, it may contain either booleans or numeric limits (maximum borrowable shares).
+        Symbols absent from the dict follow `borrow_default`.
+        """
+        if not self.allow_short:
+            return False
+        if stock_id not in self.borrowable:
+            return self.borrow_default
+        v = self.borrowable[stock_id]
+        if isinstance(v, bool):
+            return v
+        try:
+            limit = float(v)
+            return amount <= limit
+        except Exception:
+            return True
+

code/tac-qlib/tac_qlib/contrib/data/handler.py

@@ -15,6 +15,9 @@ import os
 from inspect import getfullargspec
 from typing import List, Optional, Tuple, Union
 
+import numpy as np
+import pandas as pd
+
 from qlib.data.dataset import processor as processor_module
 from qlib.data.dataset.handler import DataHandlerLP
 from qlib.utils import get_callable_kwargs
@@ -22,6 +25,7 @@ from qlib.utils import get_callable_kwargs
 from ...data.config import (
     LakeConfig,
     timeframe_for_freq,
+    FEATURE_FAMILIES,
     NON_FEATURE_COLUMNS,
 )
 
@@ -92,7 +96,7 @@ def get_common_feature_fields(lake_root=None, market="US", timeframe="1d") -> Li
 
     common: set = set()
     # family tier: features/market=*/timeframe=*/family=*/symbol=*.parquet
-    for fam in ("ta", "sp"):
+    for fam in FEATURE_FAMILIES:
         fam_dir = feat_dir / f"family={fam}"
         if fam_dir.is_dir():
             common |= _family_common(fam_dir)
@@ -143,6 +147,174 @@ class DropAllNaN(processor_module.Processor):
         return df
 
 
+class BenchResidual(processor_module.Processor):
+    """Subtract a benchmark instrument's forward return from the label, per datetime.
+
+    Turns the training target from an absolute-return rank into a *residual* rank:
+    ``r_i - r_bench`` is ranked cross-sectionally by the downstream ``CSRankNorm`` /
+    ``CSZScoreNorm`` processors instead of ``r_i`` alone. Must be inserted BEFORE any
+    per-date normalization so the ranking itself is computed on residual returns
+    (ordering flips exactly where the benchmark trends).
+
+    Stateless: ``fit`` is a no-op and the benchmark forward return is recomputed from
+    the lake parquet on first ``__call__``. Rows whose benchmark value is missing are
+    left untouched. Accepts ``fit_start_time``/``fit_end_time`` (ignored) so
+    ``check_transform_proc`` can inject the fit window uniformly.
+
+    NOTE: under any cross-sectional normalization downstream (``CSRankNorm`` /
+    ``CSZScoreNorm``) this processor is a mathematical no-op: subtracting the same
+    per-date constant preserves ranks, and z-scoring absorbs constant shifts. Use
+    ``BenchBetaResidual`` for a target that actually reorders.
+    """
+
+    def __init__(
+        self,
+        benchmark="SPY",
+        fields_group="label",
+        lake_root=None,
+        market="US",
+        timeframe=None,
+        freq="day",
+        fit_start_time=None,
+        fit_end_time=None,
+    ):
+        self.benchmark = benchmark
+        self.fields_group = fields_group
+        self.lake_root = lake_root
+        self.market = market
+        self.timeframe = timeframe or timeframe_for_freq(freq)
+        self.fit_start_time = fit_start_time
+        self.fit_end_time = fit_end_time
+        self._bench_label = None
+
+    def _load_bench_label(self):
+        if self._bench_label is not None:
+            return self._bench_label
+        cfg = LakeConfig(self.lake_root, self.market)
+        p = cfg.bar_path(self.timeframe, self.benchmark)
+        if not p.exists():
+            raise FileNotFoundError(f"BenchResidual: benchmark bar file not found: {p}")
+        df = pd.read_parquet(p)
+        s = pd.Series(df["c"].astype(float).values, index=pd.to_datetime(df["t"])).sort_index()
+        s.index = s.index.normalize()
+        # mirror Ref($close,-6)/Ref($close,-1)-1 on the benchmark's own calendar
+        bench_label = s.shift(-6) / s.shift(-1) - 1
+        self._bench_label = bench_label[~bench_label.index.duplicated(keep="last")]
+        return self._bench_label
+
+    def fit(self, df=None):
+        return self
+
+    def __call__(self, df):
+        bl = self._load_bench_label()
+        cols = processor_module.get_group_columns(df, self.fields_group)
+        dt = df.index.get_level_values("datetime")
+        aligned = bl.reindex(pd.DatetimeIndex(dt.unique())).reindex(dt)
+        mask = aligned.notna().values
+        out = df.copy()
+        for c in cols:
+            vals = df[c].values
+            res = vals.copy()
+            res[mask] = np.asarray(vals[mask], dtype=float) - aligned[mask].values
+            out[c] = res
+        return out
+
+
+class BenchBetaResidual(processor_module.Processor):
+    """Residualize the label against a beta-scaled benchmark move: ``r_i - b_i * r_bench``.
+
+    Unlike a plain constant subtraction (see ``BenchResidual``), the name-specific rolling
+    beta ``b_i`` makes this survive cross-sectional normalization: in up-weeks high-beta
+    names lose rank, in down-weeks they gain — exactly the relative structure an absolute-
+    return ranking hides.
+
+    Beta is estimated from *past* data only (rolling ``window`` trading days of daily close
+    returns of each instrument vs the benchmark, both read up to and including ``t``), so
+    no lookahead enters the target. The benchmark leg uses the same horizon as the label
+    expression (``Ref($close,-6)/Ref($close,-1)-1`` by default via ``horizon``/``base``,
+    matching the yaml's 6-day label). Rows with missing beta or benchmark values keep
+    their raw label.
+
+    Requires ``$close`` to be present in the feature group (it always is for TACHandler).
+    Stateless; accepts ``fit_start_time``/``fit_end_time`` (ignored) for uniform kwargs
+    injection. Must be inserted BEFORE any per-date normalization processor.
+    """
+
+    def __init__(
+        self,
+        benchmark="SPY",
+        fields_group="label",
+        lake_root=None,
+        market="US",
+        timeframe=None,
+        freq="day",
+        window=63,
+        horizon=6,
+        base=1,
+        feature_field="$close",
+        fit_start_time=None,
+        fit_end_time=None,
+    ):
+        self.benchmark = benchmark
+        self.fields_group = fields_group
+        self.lake_root = lake_root
+        self.market = market
+        self.timeframe = timeframe or timeframe_for_freq(freq)
+        self.window = int(window)
+        self.horizon = int(horizon)
+        self.base = int(base)
+        self.feature_field = feature_field
+        self.fit_start_time = fit_start_time
+        self.fit_end_time = fit_end_time
+        self._bench = None
+
+    def _load_bench_close(self):
+        if self._bench is not None:
+            return self._bench
+        cfg = LakeConfig(self.lake_root, self.market)
+        p = cfg.bar_path(self.timeframe, self.benchmark)
+        if not p.exists():
+            raise FileNotFoundError(f"BenchBetaResidual: benchmark bar file not found: {p}")
+        df = pd.read_parquet(p)
+        s = pd.Series(df["c"].astype(float).values, index=pd.to_datetime(df["t"])).sort_index()
+        s.index = s.index.normalize()
+        self._bench = s[~s.index.duplicated(keep="last")]
+        return self._bench
+
+    def fit(self, df=None):
+        return self
+
+    def __call__(self, df):
+        bench = self._load_bench_close()
+
+        # benchmark forward return over the same horizon as the label expression
+        fwd = bench.shift(-(self.base + self.horizon - 1)) / bench.shift(-self.base) - 1
+
+        px_col = ("feature", self.feature_field)
+        if px_col not in df.columns:
+            raise KeyError(f"BenchBetaResidual: {self.feature_field} not found in features")
+        px = df[px_col].unstack("instrument").sort_index()
+        rets = px / px.shift(1) - 1
+        bret = bench.reindex(px.index).pct_change()
+
+        # rolling beta per instrument using data <= t (no lookahead)
+        cov = rets.rolling(self.window, min_periods=max(10, self.window // 2)).cov(bret)
+        var = bret.rolling(self.window, min_periods=max(10, self.window // 2)).var()
+        beta = cov.div(var, axis=0)
+
+        contrib = beta.mul(fwd.reindex(px.index), axis=0)
+        cols = list(processor_module.get_group_columns(df, self.fields_group))
+        out = df.copy()
+        for c in cols:
+            lab = df[c].unstack("instrument").reindex(px.index)
+            resid = lab - contrib.where(contrib.notna() & lab.notna(), 0.0)
+            new_vals = resid.stack()
+            new_vals.index.names = df.index.names
+            # residual where available, raw label otherwise (e.g. beta warm-up rows)
+            out[c] = new_vals.reindex(out.index).fillna(df[c])
+        return out
+
+
 class TACHandler(DataHandlerLP):
     """DataHandlerLP backed by the TradeAC parquet lake.
 
@@ -245,10 +417,12 @@ class TACHandler(DataHandlerLP):
         return get_common_feature_fields(lake_root, market, timeframe_for_freq(freq))
 
 
-__all__ = ["TACHandler", "DropAllNaN", "get_common_feature_fields"]
+__all__ = ["TACHandler", "DropAllNaN", "BenchResidual", "BenchBetaResidual", "get_common_feature_fields"]
 
 
-# Make `DropAllNaN` resolvable by bare name from processor configs (e.g. the default
+# Make `DropAllNaN`/`BenchResidual`/`BenchBetaResidual` resolvable by bare name from processor
-# ``infer_processors`` and workflow yamls that reference it without a ``module_path``),
+# configs (e.g. the default ``infer_processors`` and workflow yamls that reference them without a
-# mirroring how qlib registers its own processors in ``qlib.data.dataset.processor``.
+# ``module_path``), mirroring how qlib registers its own processors in ``qlib.data.dataset.processor``.
 processor_module.DropAllNaN = DropAllNaN
+processor_module.BenchResidual = BenchResidual
+processor_module.BenchBetaResidual = BenchBetaResidual

code/tac-qlib/tac_qlib/contrib/model/rank_gbdt.py

@@ -53,23 +53,61 @@ from qlib.workflow import R
 __all__ = ["RankICLGBModel", "rankic_feval"]
 
 
+def _group_averaged_rank(values: np.ndarray, gid: np.ndarray, offs: np.ndarray) -> np.ndarray:
+    """Averaged (tie-corrected) rank of ``values`` within each group, vectorized.
+
+    ``gid`` maps each row to its group id; ``offs`` holds the cumulative row
+    offsets so that group ``i`` occupies rows ``[offs[i], offs[i+1])``. Returns
+    the same result as ``pandas.Series.rank(method='average')`` applied per
+    group, but in one pass (``np.lexsort`` is the only non-linear step).
+    """
+    n = len(values)
+    order = np.lexsort((values, gid))
+    ord_rank = np.empty(n, dtype=np.float64)
+    ord_rank[order] = np.arange(n, dtype=np.float64) - offs[gid[order]] + 1.0
+    sg = gid[order]
+    sv = values[order]
+    newblock = np.empty(n, dtype=bool)
+    newblock[0] = True
+    newblock[1:] = (sg[1:] != sg[:-1]) | (sv[1:] != sv[:-1])
+    blockid = np.cumsum(newblock) - 1
+    block_mean = np.bincount(blockid, weights=ord_rank[order]) / np.bincount(blockid)
+    out = np.empty(n)
+    out[order] = block_mean[blockid]
+    return out
+
+
 def _per_day_spearman(preds: np.ndarray, labels: np.ndarray, group: np.ndarray) -> float:
     """Mean per-day Spearman rank correlation of preds vs labels.
 
     ``group`` holds the number of rows of each trading day (query group), in
     order. Days with <3 valid rows or a constant pred/label are skipped.
+
+    Vectorized: per-day Spearman == Pearson of the per-day rank transforms,
+    and the Pearson moments (``sum``, ``sum`` of products/squares) aggregate
+    over each day with ``np.bincount``. Runs ~10x faster than the per-day
+    ``pd.Series.rank()`` loop that preceded it — this feval is invoked on the
+    train and valid panels every boosting round, per seed.
     """
     if group is None or len(group) == 0:
         return 0.0
     offs = np.concatenate([[0], np.cumsum(group.astype(int))])
-    vals = []
+    gid = np.repeat(np.arange(len(group)), group.astype(int))
-    for i in range(len(group)):
+    rp = _group_averaged_rank(preds, gid, offs)
-        s = slice(offs[i], offs[i + 1])
+    rl = _group_averaged_rank(labels, gid, offs)
-        p, l = preds[s], labels[s]
+    n_g = group.astype(float)
-        if len(p) < 3 or np.std(p) == 0 or np.std(l) == 0:
+    s_p = np.bincount(gid, weights=rp)
-            continue
+    s_l = np.bincount(gid, weights=rl)
-        vals.append(np.corrcoef(pd.Series(p).rank(), pd.Series(l).rank())[0, 1])
+    s_pl = np.bincount(gid, weights=rp * rl)
-    return float(np.mean(vals)) if vals else 0.0
+    s_pp = np.bincount(gid, weights=rp * rp)
+    s_ll = np.bincount(gid, weights=rl * rl)
+    cov = n_g * s_pl - s_p * s_l
+    var_p = n_g * s_pp - s_p ** 2
+    var_l = n_g * s_ll - s_l ** 2
+    denom = np.sqrt(var_p * var_l)
+    valid = (n_g >= 3) & (denom > 0)
+    corr = np.where(valid, cov / np.where(denom == 0, 1, denom), 0.0)
+    return float(corr[valid].mean()) if valid.any() else 0.0
 
 
 def rankic_feval(preds, dataset):

code/tac-qlib/tac_qlib/contrib/strategy/__init__.py

@@ -1,3 +1,4 @@
 from .optimal_stop import OptimalStopControl  # noqa: F401
+from .long_short import LongShortTopkStrategy  # noqa: F401
 
-__all__ = ["OptimalStopControl"]
+__all__ = ["OptimalStopControl", "LongShortTopkStrategy"]

code/tac-qlib/tac_qlib/contrib/strategy/kelly_dropout.py

@@ -0,0 +1,201 @@
+"""Fractional-Kelly dropout strategy for cross-sectional signals.
+
+Sizing rule variant of ``qlib.contrib.strategy.signal_strategy.TopkDropoutStrategy``:
+the topk/n_drop SELECTION is identical to the reference, but the buy size is
+proportional to the score MAGNITUDE (edge) instead of equal-weight, capped at a
+fraction ``cap_frac`` of the equal-weight notional so a single name cannot
+over-concentrate the book.
+
+``cap_frac`` is the fraction of the equal-weight per-name notional that a top
+signal can deploy at most (e.g. 0.5 = at most half the equal-weight size).
+Names whose score is below the median of the buy set get a proportionally
+smaller slice; the residual stays in cash (that is the point of the rule:
+throw away less edge per name, deploy less capital when conviction is low).
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+import numpy as np
+import pandas as pd
+
+from qlib.backtest import Order
+from qlib.backtest.decision import OrderDir, TradeDecisionWO
+from qlib.contrib.strategy.signal_strategy import TopkDropoutStrategy
+
+__all__ = ["FractionalKellyDropoutStrategy"]
+
+DEFAULT_CAP_FRAC = 0.5
+
+
+class FractionalKellyDropoutStrategy(TopkDropoutStrategy):
+    """TopkDropout selection with score-magnitude (fractional-Kelly) sizing.
+
+    Parameters
+    ----------
+    topk, n_drop, method_sell, method_buy, hold_thresh, only_tradable,
+    forbid_all_trade_at_limit : same as ``TopkDropoutStrategy``.
+    cap_frac : max buy notional as a fraction of the equal-weight notional.
+    """
+
+    def __init__(self, *, topk, n_drop, cap_frac: float = DEFAULT_CAP_FRAC, **kwargs):
+        super().__init__(topk=topk, n_drop=n_drop, **kwargs)
+        self.cap_frac = cap_frac
+
+    def generate_trade_decision(self, execute_result=None):
+        import copy
+
+        trade_step = self.trade_calendar.get_trade_step()
+        trade_start_time, trade_end_time = self.trade_calendar.get_step_time(trade_step)
+        pred_start_time, pred_end_time = self.trade_calendar.get_step_time(trade_step, shift=1)
+        pred_score = self.signal.get_signal(start_time=pred_start_time, end_time=pred_end_time)
+        if isinstance(pred_score, pd.DataFrame):
+            pred_score = pred_score.iloc[:, 0]
+        if pred_score is None:
+            return TradeDecisionWO([], self)
+
+        if self.only_tradable:
+
+            def get_first_n(li, n, reverse=False):
+                cur_n = 0
+                res = []
+                for si in reversed(li) if reverse else li:
+                    if self.trade_exchange.is_stock_tradable(
+                        stock_id=si, start_time=trade_start_time, end_time=trade_end_time
+                    ):
+                        res.append(si)
+                        cur_n += 1
+                        if cur_n >= n:
+                            break
+                return res[::-1] if reverse else res
+
+            def get_last_n(li, n):
+                return get_first_n(li, n, reverse=True)
+
+            def filter_stock(li):
+                return [
+                    si
+                    for si in li
+                    if self.trade_exchange.is_stock_tradable(
+                        stock_id=si, start_time=trade_start_time, end_time=trade_end_time
+                    )
+                ]
+
+        else:
+
+            def get_first_n(li, n):
+                return list(li)[:n]
+
+            def get_last_n(li, n):
+                return list(li)[-n:]
+
+            def filter_stock(li):
+                return li
+
+        current_temp: "object" = copy.deepcopy(self.trade_position)
+        sell_order_list: List[Order] = []
+        buy_order_list: List[Order] = []
+        cash = current_temp.get_cash()
+        current_stock_list = current_temp.get_stock_list()
+        last = pred_score.reindex(current_stock_list).sort_values(ascending=False).index
+
+        if self.method_buy == "top":
+            today = get_first_n(
+                pred_score[~pred_score.index.isin(last)].sort_values(ascending=False).index,
+                self.n_drop + self.topk - len(last),
+            )
+        elif self.method_buy == "random":
+            topk_candi = get_first_n(pred_score.sort_values(ascending=False).index, self.topk)
+            candi = list(filter(lambda x: x not in last, topk_candi))
+            n = self.n_drop + self.topk - len(last)
+            try:
+                today = np.random.choice(candi, n, replace=False)
+            except ValueError:
+                today = candi
+        else:
+            raise NotImplementedError(f"This type of input is not supported")
+
+        comb = pred_score.reindex(last.union(pd.Index(today))).sort_values(ascending=False).index
+
+        if self.method_sell == "bottom":
+            sell = last[last.isin(get_last_n(comb, self.n_drop))]
+        elif self.method_sell == "random":
+            candi = filter_stock(last)
+            try:
+                sell = pd.Index(np.random.choice(candi, self.n_drop, replace=False) if len(last) else [])
+            except ValueError:
+                sell = candi
+        else:
+            raise NotImplementedError(f"This type of input is not supported")
+
+        buy = today[: len(sell) + self.topk - len(last)]
+        for code in current_stock_list:
+            if not self.trade_exchange.is_stock_tradable(
+                stock_id=code,
+                start_time=trade_start_time,
+                end_time=trade_end_time,
+                direction=None if self.forbid_all_trade_at_limit else OrderDir.SELL,
+            ):
+                continue
+            if code in sell:
+                time_per_step = self.trade_calendar.get_freq()
+                if current_temp.get_stock_count(code, bar=time_per_step) < self.hold_thresh:
+                    continue
+                sell_amount = current_temp.get_stock_amount(code=code)
+                sell_order = Order(
+                    stock_id=code,
+                    amount=sell_amount,
+                    start_time=trade_start_time,
+                    end_time=trade_end_time,
+                    direction=Order.SELL,
+                )
+                if self.trade_exchange.check_order(sell_order):
+                    sell_order_list.append(sell_order)
+                    trade_val, trade_cost, trade_price = self.trade_exchange.deal_order(
+                        sell_order, position=current_temp
+                    )
+                    cash += trade_val - trade_cost
+
+        if len(buy) == 0:
+            return TradeDecisionWO(sell_order_list, self)
+
+        # ---- fractional-Kelly sizing --------------------------------------
+        # equal-weight notional (reference baseline)
+        eq_notional = cash * self.risk_degree / len(buy)
+        buy_scores = pred_score.reindex(buy).astype(float)
+        lo, hi = buy_scores.min(), buy_scores.max()
+        if hi == lo:
+            w = pd.Series(1.0, index=buy_scores.index)
+        else:
+            w = (buy_scores - lo) / (hi - lo)  # [0,1] edge magnitude
+            w = w.clip(lower=0.0)
+            w_max = w.max()
+            w = w / w_max if w_max > 0 else w  # max == 1.0
+        for code in buy:
+            if not self.trade_exchange.is_stock_tradable(
+                stock_id=code,
+                start_time=trade_start_time,
+                end_time=trade_end_time,
+                direction=None if self.forbid_all_trade_at_limit else OrderDir.BUY,
+            ):
+                continue
+            buy_price = self.trade_exchange.get_deal_price(
+                stock_id=code, start_time=trade_start_time, end_time=trade_end_time, direction=OrderDir.BUY
+            )
+            notional = eq_notional * min(self.cap_frac, float(w.get(code, 0.0)))
+            buy_amount = notional / buy_price
+            factor = self.trade_exchange.get_factor(
+                stock_id=code, start_time=trade_start_time, end_time=trade_end_time
+            )
+            buy_amount = self.trade_exchange.round_amount_by_trade_unit(buy_amount, factor)
+            buy_order = Order(
+                stock_id=code,
+                amount=buy_amount,
+                start_time=trade_start_time,
+                end_time=trade_end_time,
+                direction=Order.BUY,
+            )
+            buy_order_list.append(buy_order)
+
+        return TradeDecisionWO(sell_order_list + buy_order_list, self)

code/tac-qlib/tac_qlib/contrib/strategy/long_short.py

@@ -0,0 +1,361 @@
+"""Long-short Top-K strategy for cross-sectional signals.
+
+Each day the strategy ranks the cross-section by prediction score and rebalances
+to an equal-weight two-sided book: the ``topk`` highest-ranked names go long and
+the ``k_short`` lowest-ranked names go short. Net-new shorts are opened by
+selling beyond current holdings, which requires a short-aware exchange such as
+``tac_qlib.contrib.backtest.tradeac_exchange.TradeACExchange`` with
+``allow_short=True`` (borrow limits, margin requirements and borrow fees are
+enforced there, not here).
+
+Sizing deploys ``equity * risk_degree`` as gross notional split evenly across
+all long and short legs, so the book is approximately market neutral.
+``allow_short=False`` disables the short side entirely (long-only ``topk``).
+
+Short eligibility can be restricted further, with static or dynamic gates:
+``short_whitelist`` limits shorts to an explicit symbol set; ``short_vol_top_pct``
+requires a candidate's trailing realized volatility to rank in the top fraction
+of that day's cross-section; ``short_max_mom`` (falling-knife filter) only
+allows shorting names whose own trailing momentum is at/below a threshold;
+``short_regime_sma`` disables shorts entirely while the benchmark trades above
+its moving average (risk-on). Borrow availability itself is enforced by the
+exchange (``borrowable`` whitelist / per-symbol caps via ``TradeACExchange``).
+
+Wired into qrun workflows like any ``BaseStrategy`` (see ``PortAnaRecord``
+config). Mirrors the API usage of qlib's ``TopkDropoutStrategy``: ``Order`` /
+``OrderDir`` from ``qlib.backtest.decision``, ``trade_calendar`` /
+``trade_exchange`` / ``trade_position`` injected by the backtest executor.
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Dict, List, Optional
+
+import pandas as pd
+
+from qlib.backtest import Order
+from qlib.backtest.decision import OrderDir, TradeDecisionWO
+from qlib.contrib.strategy.signal_strategy import BaseSignalStrategy
+from qlib.log import get_module_logger
+
+__all__ = ["LongShortTopkStrategy"]
+
+
+class LongShortTopkStrategy(BaseSignalStrategy):
+    """Equal-weight long-short Top-K strategy over a cross-sectional signal.
+
+    Parameters
+    ----------
+    topk : number of long legs (highest-ranked names).
+    k_short : number of short legs (lowest-ranked names).
+    hold_thresh : minimum holding days before a leg may be closed/reduced.
+    only_tradable : only select candidates tradable on the trade date.
+    rebalance_tol : skip rebalances smaller than this fraction of a leg's
+        target notional (turnover control).
+    allow_short : enable/disable the short side. With ``False`` the bottom-ranked
+        legs are dropped and the book is long-only ``topk``; pair with
+        ``allow_short=False`` on the exchange for a fully borrow-free run.
+        Legacy alias ``enable_short`` is accepted.
+    short_whitelist : optional list of symbols eligible for shorting; candidates
+        outside the list are skipped (``None`` = all names eligible).
+    short_vol_window : trailing window (trading days) for realized-vol estimation.
+    short_vol_top_pct : if set, a short candidate's trailing realized volatility
+        must rank at or above this percentile of that day's cross-section
+        (e.g. ``0.5`` = only the more volatile half may be shorted). Candidates
+        without measurable vol are never shorted.
+    short_mom_window : trailing window (trading days) for the candidate momentum
+        used by the falling-knife gate.
+    short_max_mom : if set, a candidate's trailing ``short_mom_window``-day return
+        must be <= this value to be shortable (e.g. ``0.0`` = only short names
+        that are actually falling). Candidates without measurable momentum are
+        never shorted.
+    short_regime_symbol : benchmark symbol for the regime gate (default SPY).
+    short_regime_sma : if set, shorts are only allowed on days where the regime
+        symbol's last close (strictly before the execution bar) is BELOW its
+        ``short_regime_sma``-day moving average — i.e. shorts are disabled in
+        risk-on regimes and enabled in drawdowns.
+    """
+
+    def __init__(
+        self,
+        *,
+        signal=None,
+        topk: int = 4,
+        k_short: int = 2,
+        hold_thresh: int = 1,
+        only_tradable: bool = True,
+        rebalance_tol: float = 0.05,
+        allow_short: Optional[bool] = None,
+        enable_short: Optional[bool] = None,
+        short_whitelist: Optional[List[str]] = None,
+        short_vol_window: int = 20,
+        short_vol_top_pct: Optional[float] = None,
+        short_mom_window: int = 20,
+        short_max_mom: Optional[float] = None,
+        short_regime_symbol: str = "SPY",
+        short_regime_sma: Optional[int] = None,
+        risk_degree: float = 0.95,
+        trade_exchange=None,
+        level_infra=None,
+        common_infra=None,
+        **kwargs,
+    ):
+        super().__init__(
+            signal=signal,
+            risk_degree=risk_degree,
+            trade_exchange=trade_exchange,
+            level_infra=level_infra,
+            common_infra=common_infra,
+            **kwargs,
+        )
+        if allow_short is None:
+            allow_short = True if enable_short is None else bool(enable_short)
+        self.allow_short = bool(allow_short)
+        self.topk = topk
+        self.k_short = k_short
+        self.hold_thresh = hold_thresh
+        self.only_tradable = only_tradable
+        self.rebalance_tol = rebalance_tol
+        self.short_whitelist = set(short_whitelist) if short_whitelist is not None else None
+        if not 0 < float(short_vol_window) <= 1000:
+            raise ValueError(f"short_vol_window must be in (0, 1000], got {short_vol_window}")
+        self.short_vol_window = int(short_vol_window)
+        if short_vol_top_pct is not None and not 0.0 < float(short_vol_top_pct) <= 1.0:
+            raise ValueError(f"short_vol_top_pct must be in (0, 1], got {short_vol_top_pct}")
+        self.short_vol_top_pct = None if short_vol_top_pct is None else float(short_vol_top_pct)
+        if not 0 < float(short_mom_window) <= 1000:
+            raise ValueError(f"short_mom_window must be in (0, 1000], got {short_mom_window}")
+        self.short_mom_window = int(short_mom_window)
+        self.short_max_mom = None if short_max_mom is None else float(short_max_mom)
+        self.short_regime_symbol = str(short_regime_symbol)
+        if short_regime_sma is not None and not 1 < int(short_regime_sma) <= 1000:
+            raise ValueError(f"short_regime_sma must be in (1, 1000], got {short_regime_sma}")
+        self.short_regime_sma = None if short_regime_sma is None else int(short_regime_sma)
+        # per-day caches (keyed by trade date)
+        self._vol_cache_key: Optional[str] = None
+        self._vol_cache_val: Dict[str, Dict[str, float]] = {}
+        self._regime_cache: Dict[str, bool] = {}
+
+    # ------------------------------------------------------------------ utils
+    def _is_tradable(self, code, start, end) -> bool:
+        if not self.only_tradable:
+            return True
+        try:
+            return self.trade_exchange.is_stock_tradable(stock_id=code, start_time=start, end_time=end)
+        except TypeError:
+            return True
+
+    def _mark_price(self, code, start, end) -> Optional[float]:
+        try:
+            px = self.trade_exchange.get_deal_price(
+                stock_id=code, start_time=start, end_time=end, direction=OrderDir.BUY
+            )
+        except (KeyError, ValueError):
+            return None
+        if px is None or px != px or px <= 0:
+            return None
+        return float(px)
+
+    def _day_stats(self, codes: List[str], trade_start) -> Dict[str, Dict[str, float]]:
+        """Per-day cross-sectional stats used by the dynamic short gates.
+
+        For each code, returns ``{"vol_rank": r}`` (percentile of trailing
+        realized vol over ``short_vol_window`` bars across that day's
+        cross-section) when the vol gate is on, and ``{"mom": m}`` (trailing
+        ``short_mom_window``-bar return) when the falling-knife gate is on.
+        All series end on the last bar strictly BEFORE the execution bar (no
+        lookahead). Codes without measurable data are simply absent — such
+        candidates are never shorted (fail-closed).
+        """
+        if self.short_vol_top_pct is None and self.short_max_mom is None:
+            return {}
+        key = str(pd.Timestamp(trade_start))
+        if self._vol_cache_key == key:
+            return self._vol_cache_val
+        out: Dict[str, Dict[str, float]] = {}
+        try:
+            from qlib.data import D
+
+            end = pd.Timestamp(trade_start)
+            buf = max(self.short_vol_window, self.short_mom_window) * 3 + 30
+            df = D.features(
+                sorted(codes),
+                ["$close"],
+                start_time=end - pd.Timedelta(days=buf),
+                end_time=end - pd.Timedelta(days=1),
+            )
+            close = df["$close"].unstack(level="instrument") if isinstance(df.index, pd.MultiIndex) else df["$close"]
+            if self.short_vol_top_pct is not None:
+                vol = close.pct_change().rolling(self.short_vol_window).std().iloc[-1]
+                for code, rank in vol.rank(pct=True).dropna().items():
+                    out.setdefault(str(code), {})["vol_rank"] = float(rank)
+            if self.short_max_mom is not None:
+                w = min(self.short_mom_window, len(close) - 1)
+                mom = close.iloc[-1] / close.iloc[-(w + 1)] - 1
+                for code, m in mom.items():
+                    if m == m:
+                        out.setdefault(str(code), {})["mom"] = float(m)
+        except Exception as e:  # noqa: BLE001 - degrade to fail-closed (no shorts)
+            get_module_logger(self.__class__.__name__).warning(
+                f"short gates unavailable ({type(e).__name__}: {e}); no shorts this step"
+            )
+        self._vol_cache_key, self._vol_cache_val = key, out
+        return out
+
+    def _regime_ok(self, trade_start) -> bool:
+        """True when shorting is allowed by the benchmark-regime gate.
+
+        With ``short_regime_sma`` set, shorts are permitted only while the
+        regime symbol's last close strictly before the execution bar sits below
+        its moving average (risk-off). Data failure fails closed (no shorts).
+        """
+        if self.short_regime_sma is None:
+            return True
+        key = str(pd.Timestamp(trade_start))
+        cached = self._regime_cache.get(key)
+        if cached is not None:
+            return cached
+        ok = False
+        try:
+            from qlib.data import D
+
+            end = pd.Timestamp(trade_start)
+            df = D.features(
+                [self.short_regime_symbol],
+                ["$close"],
+                start_time=end - pd.Timedelta(days=int(self.short_regime_sma * 3 + 30)),
+                end_time=end - pd.Timedelta(days=1),
+            )
+            s = df["$close"]
+            if isinstance(s.index, pd.MultiIndex):
+                s = s.droplevel("instrument")
+            sma = s.rolling(self.short_regime_sma).mean().iloc[-1]
+            px = s.iloc[-1]
+            ok = bool(px < sma)
+        except Exception as e:  # noqa: BLE001 - degrade to fail-closed (no shorts)
+            get_module_logger(self.__class__.__name__).warning(
+                f"regime gate unavailable ({type(e).__name__}: {e}); no shorts this step"
+            )
+        self._regime_cache[key] = ok
+        return ok
+
+    # ------------------------------------------------------------- decision
+    def generate_trade_decision(self, execute_result=None):
+        trade_step = self.trade_calendar.get_trade_step()
+        trade_start, trade_end = self.trade_calendar.get_step_time(trade_step)
+        pred_start, pred_end = self.trade_calendar.get_step_time(trade_step, shift=1)
+        pred_score = self.signal.get_signal(start_time=pred_start, end_time=pred_end)
+        if isinstance(pred_score, pd.DataFrame):
+            pred_score = pred_score.iloc[:, 0]
+        if pred_score is None or len(pred_score) == 0:
+            return TradeDecisionWO([], self)
+        pred_score = pred_score.dropna()
+        if pred_score.empty:
+            return TradeDecisionWO([], self)
+
+        time_per_step = self.trade_calendar.get_freq()
+        current_temp = copy.deepcopy(self.trade_position)
+
+        # ---- signed current holdings ---------------------------------------
+        cur_amount: Dict[str, float] = {}
+        for code in current_temp.get_stock_list():
+            amt = float(current_temp.get_stock_amount(code))
+            if abs(amt) > 1e-6:
+                cur_amount[code] = amt
+
+        # ---- targets: top-k long, bottom-k_short short ----------------------
+        ranked = list(pred_score.sort_values(ascending=False).index)
+        longs: List[str] = []
+        for code in ranked:
+            if len(longs) >= self.topk:
+                break
+            if self._is_tradable(code, trade_start, trade_end):
+                longs.append(code)
+        shorts: List[str] = []
+        if self.allow_short and self._regime_ok(trade_start):
+            stats = self._day_stats(list(ranked), trade_start)
+            for code in reversed(ranked):
+                if len(shorts) >= self.k_short:
+                    break
+                if code in longs:
+                    continue
+                if not self._is_tradable(code, trade_start, trade_end):
+                    continue
+                if self.short_whitelist is not None and code not in self.short_whitelist:
+                    continue
+                st = stats.get(code)
+                if self.short_vol_top_pct is not None:
+                    rank = None if st is None else st.get("vol_rank")
+                    if rank is None or rank < self.short_vol_top_pct:
+                        continue
+                if self.short_max_mom is not None:
+                    mom = None if st is None else st.get("mom")
+                    if mom is None or mom > self.short_max_mom:
+                        continue
+                shorts.append(code)
+
+        # ---- marks & equity --------------------------------------------------
+        marks: Dict[str, float] = {}
+        for code in set(cur_amount) | set(longs) | set(shorts):
+            px = self._mark_price(code, trade_start, trade_end)
+            if px is not None:
+                marks[code] = px
+
+        equity = current_temp.get_cash()
+        for code, amt in cur_amount.items():
+            if code in marks:
+                equity += amt * marks[code]
+        if equity <= 0:
+            return TradeDecisionWO([], self)
+
+        n_legs = len([c for c in longs if c in marks]) + len([c for c in shorts if c in marks])
+        if n_legs == 0:
+            return TradeDecisionWO([], self)
+        per_leg = equity * self.risk_degree / n_legs
+
+        target_signed: Dict[str, float] = {}
+        for code in longs:
+            if code in marks:
+                target_signed[code] = per_leg / marks[code]
+        for code in shorts:
+            if code in marks:
+                target_signed[code] = -(per_leg / marks[code])
+
+        # ---- order generation -------------------------------------------------
+        sell_orders: List[Order] = []
+        buy_orders: List[Order] = []
+
+        def submit(code: str, amount: float, direction: int) -> None:
+            factor = self.trade_exchange.get_factor(stock_id=code, start_time=trade_start, end_time=trade_end)
+            amount = self.trade_exchange.round_amount_by_trade_unit(amount, factor)
+            if amount <= 1e-6:
+                return
+            o = Order(stock_id=code, amount=amount, start_time=trade_start, end_time=trade_end, direction=direction)
+            if self.trade_exchange.check_order(o):
+                (buy_orders if direction == Order.BUY else sell_orders).append(o)
+
+        # close holdings that are no longer targeted (frees cash / unwinds shorts)
+        for code, amt in cur_amount.items():
+            if code in target_signed:
+                continue
+            if marks.get(code) is None:
+                continue
+            if current_temp.get_stock_count(code, bar=time_per_step) < self.hold_thresh:
+                continue
+            submit(code, abs(amt), Order.SELL if amt > 0 else Order.BUY)
+
+        # rebalance targeted legs toward their signed target quantity
+        for code, tgt in target_signed.items():
+            cur = cur_amount.get(code, 0.0)
+            delta = tgt - cur
+            if abs(delta * marks[code]) < max(self.rebalance_tol * per_leg, 1.0):
+                continue
+            if delta > 0:
+                submit(code, delta, Order.BUY)
+            else:
+                if cur > 0 and current_temp.get_stock_count(code, bar=time_per_step) < self.hold_thresh:
+                    continue
+                submit(code, -delta, Order.SELL)
+
+        return TradeDecisionWO(sell_orders + buy_orders, self)

code/tac-qlib/tac_qlib/contrib/strategy/regime_gate.py

@@ -0,0 +1,231 @@
+"""HMM-regime overlay TopkDropout strategy.
+
+Regime-gate overlay on ``qlib.contrib.strategy.signal_strategy.TopkDropoutStrategy``:
+selection and sizing are identical to the reference, but a name is only BOUGHT
+(entry gate) when its per-symbol HMM regime posterior ``sp_hmm_p_regime1`` on
+the signal date is >= ``regime_threshold``; otherwise it is held in cash instead
+of being opened.
+
+The regime posterior is read from the lake feature provider on the fly via
+``qlib.data.D.features`` (field ``$sp_hmm_p_regime1``) for the signal window, so
+no regime column needs to enter the model's ``feature_fields`` — the gate is a
+pure overlay (book ch.01: regime flags regressed as model features, survived
+only as an overlay). The HMM itself was fit with ``fit_end=<train end>`` when
+the lake features were backfilled, so there is no lookahead.
+
+Names already held are NOT force-sold when the regime turns unfavourable
+(entry gate only, matching the queue-10 design).
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+import numpy as np
+import pandas as pd
+
+from qlib.backtest import Order
+from qlib.backtest.decision import OrderDir, TradeDecisionWO
+from qlib.contrib.strategy.signal_strategy import TopkDropoutStrategy
+
+try:
+    from qlib.data import D
+except ImportError:  # pragma: no cover - qlib always present in this stack
+    D = None
+
+__all__ = ["RegimeGateDropoutStrategy"]
+
+DEFAULT_REGIME_THRESHOLD = 0.5
+REGIME_FIELD = "$sp_hmm_p_regime1"
+
+
+class RegimeGateDropoutStrategy(TopkDropoutStrategy):
+    """TopkDropout with an HMM-regime entry gate on buy candidates.
+
+    Parameters
+    ----------
+    topk, n_drop, method_sell, method_buy, hold_thresh, only_tradable,
+    forbid_all_trade_at_limit : same as ``TopkDropoutStrategy``.
+    regime_threshold : minimum ``sp_hmm_p_regime1`` posterior required to open a
+        new position (default 0.5).
+    """
+
+    def __init__(self, *, topk, n_drop, regime_threshold: float = DEFAULT_REGIME_THRESHOLD, **kwargs):
+        super().__init__(topk=topk, n_drop=n_drop, **kwargs)
+        self.regime_threshold = regime_threshold
+
+    def _regime_for(self, codes, pred_start, pred_end) -> pd.Series:
+        """Return {code: sp_hmm_p_regime1} for the signal window (last day)."""
+        if D is None:
+            return pd.Series(dtype=float)
+        try:
+            df = D.features(list(codes), [REGIME_FIELD], start_time=pred_start, end_time=pred_end, freq="day")
+        except Exception:  # noqa: BLE001 - a regime read failure should gate open, not crash
+            return pd.Series(dtype=float)
+        if df is None or len(df) == 0:
+            return pd.Series(dtype=float)
+        # df index is MultiIndex (datetime, instrument); take the last day's values
+        df = df.reset_index()
+        ts_col = "datetime" if "datetime" in df.columns else df.columns[0]
+        sym_col = "instrument" if "instrument" in df.columns else df.columns[1]
+        last_ts = df[ts_col].max()
+        last = df[df[ts_col] == last_ts]
+        out = {}
+        for _, row in last.iterrows():
+            sym = str(row[sym_col]).split("/")[-1].upper()
+            val = row.iloc[-1]
+            out[sym] = float(val) if val == val else np.nan
+        return pd.Series(out)
+
+    def generate_trade_decision(self, execute_result=None):
+        import copy
+
+        trade_step = self.trade_calendar.get_trade_step()
+        trade_start_time, trade_end_time = self.trade_calendar.get_step_time(trade_step)
+        pred_start_time, pred_end_time = self.trade_calendar.get_step_time(trade_step, shift=1)
+        pred_score = self.signal.get_signal(start_time=pred_start_time, end_time=pred_end_time)
+        if isinstance(pred_score, pd.DataFrame):
+            pred_score = pred_score.iloc[:, 0]
+        if pred_score is None:
+            return TradeDecisionWO([], self)
+
+        if self.only_tradable:
+
+            def get_first_n(li, n, reverse=False):
+                cur_n = 0
+                res = []
+                for si in reversed(li) if reverse else li:
+                    if self.trade_exchange.is_stock_tradable(
+                        stock_id=si, start_time=trade_start_time, end_time=trade_end_time
+                    ):
+                        res.append(si)
+                        cur_n += 1
+                        if cur_n >= n:
+                            break
+                return res[::-1] if reverse else res
+
+            def get_last_n(li, n):
+                return get_first_n(li, n, reverse=True)
+
+            def filter_stock(li):
+                return [
+                    si
+                    for si in li
+                    if self.trade_exchange.is_stock_tradable(
+                        stock_id=si, start_time=trade_start_time, end_time=trade_end_time
+                    )
+                ]
+
+        else:
+
+            def get_first_n(li, n):
+                return list(li)[:n]
+
+            def get_last_n(li, n):
+                return list(li)[-n:]
+
+            def filter_stock(li):
+                return li
+
+        current_temp: "object" = copy.deepcopy(self.trade_position)
+        sell_order_list: List[Order] = []
+        buy_order_list: List[Order] = []
+        cash = current_temp.get_cash()
+        current_stock_list = current_temp.get_stock_list()
+        last = pred_score.reindex(current_stock_list).sort_values(ascending=False).index
+
+        if self.method_buy == "top":
+            today = get_first_n(
+                pred_score[~pred_score.index.isin(last)].sort_values(ascending=False).index,
+                self.n_drop + self.topk - len(last),
+            )
+        elif self.method_buy == "random":
+            topk_candi = get_first_n(pred_score.sort_values(ascending=False).index, self.topk)
+            candi = list(filter(lambda x: x not in last, topk_candi))
+            n = self.n_drop + self.topk - len(last)
+            try:
+                today = np.random.choice(candi, n, replace=False)
+            except ValueError:
+                today = candi
+        else:
+            raise NotImplementedError(f"This type of input is not supported")
+
+        comb = pred_score.reindex(last.union(pd.Index(today))).sort_values(ascending=False).index
+
+        if self.method_sell == "bottom":
+            sell = last[last.isin(get_last_n(comb, self.n_drop))]
+        elif self.method_sell == "random":
+            candi = filter_stock(last)
+            try:
+                sell = pd.Index(np.random.choice(candi, self.n_drop, replace=False) if len(last) else [])
+            except ValueError:
+                sell = candi
+        else:
+            raise NotImplementedError(f"This type of input is not supported")
+
+        buy = today[: len(sell) + self.topk - len(last)]
+
+        # ---- regime gate -----------------------------------------------------
+        if buy:
+            regime = self._regime_for(buy, pred_start_time, pred_end_time)
+            gated = [c for c in buy if regime.get(c, np.nan) >= self.regime_threshold]
+        else:
+            gated = []
+
+        for code in current_stock_list:
+            if not self.trade_exchange.is_stock_tradable(
+                stock_id=code,
+                start_time=trade_start_time,
+                end_time=trade_end_time,
+                direction=None if self.forbid_all_trade_at_limit else OrderDir.SELL,
+            ):
+                continue
+            if code in sell:
+                time_per_step = self.trade_calendar.get_freq()
+                if current_temp.get_stock_count(code, bar=time_per_step) < self.hold_thresh:
+                    continue
+                sell_amount = current_temp.get_stock_amount(code=code)
+                sell_order = Order(
+                    stock_id=code,
+                    amount=sell_amount,
+                    start_time=trade_start_time,
+                    end_time=trade_end_time,
+                    direction=Order.SELL,
+                )
+                if self.trade_exchange.check_order(sell_order):
+                    sell_order_list.append(sell_order)
+                    trade_val, trade_cost, trade_price = self.trade_exchange.deal_order(
+                        sell_order, position=current_temp
+                    )
+                    cash += trade_val - trade_cost
+
+        if len(gated) == 0:
+            return TradeDecisionWO(sell_order_list, self)
+
+        value = cash * self.risk_degree / len(gated)
+        for code in gated:
+            if not self.trade_exchange.is_stock_tradable(
+                stock_id=code,
+                start_time=trade_start_time,
+                end_time=trade_end_time,
+                direction=None if self.forbid_all_trade_at_limit else OrderDir.BUY,
+            ):
+                continue
+            buy_price = self.trade_exchange.get_deal_price(
+                stock_id=code, start_time=trade_start_time, end_time=trade_end_time, direction=OrderDir.BUY
+            )
+            buy_amount = value / buy_price
+            factor = self.trade_exchange.get_factor(
+                stock_id=code, start_time=trade_start_time, end_time=trade_end_time
+            )
+            buy_amount = self.trade_exchange.round_amount_by_trade_unit(buy_amount, factor)
+            buy_order = Order(
+                stock_id=code,
+                amount=buy_amount,
+                start_time=trade_start_time,
+                end_time=trade_end_time,
+                direction=Order.BUY,
+            )
+            buy_order_list.append(buy_order)
+
+        return TradeDecisionWO(sell_order_list + buy_order_list, self)

code/tac-qlib/tac_qlib/contrib/strategy/weekly_rebalance.py

@@ -0,0 +1,223 @@
+"""Weekly-rebalance TopkDropout strategy.
+
+Turnover-reduction variant of ``qlib.contrib.strategy.signal_strategy.TopkDropoutStrategy``:
+the topk/n_drop selection and sizing are identical to the reference, but the
+target book is recomputed only on the first trading day of each ISO week; on the
+other days the strategy issues NO orders (holds the book untouched).
+
+The weekly cadence is derived from the qlib trade calendar: a rebalance happens
+when the current trade step's date belongs to a different ISO ``(year, week)``
+than the previous trade step. ``hold_band_pct`` (default 0) optionally skips
+tiny rebalances: when a name's existing position differs from the new target by
+less than this fraction, no order is generated for it.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+import numpy as np
+import pandas as pd
+
+from qlib.backtest import Order
+from qlib.backtest.decision import OrderDir, TradeDecisionWO
+from qlib.contrib.strategy.signal_strategy import TopkDropoutStrategy
+
+__all__ = ["WeeklyRebalanceDropoutStrategy"]
+
+DEFAULT_HOLD_BAND_PCT = 0.0
+
+
+class WeeklyRebalanceDropoutStrategy(TopkDropoutStrategy):
+    """TopkDropout rebalanced once per ISO week; holds otherwise.
+
+    Parameters
+    ----------
+    topk, n_drop, method_sell, method_buy, hold_thresh, only_tradable,
+    forbid_all_trade_at_limit : same as ``TopkDropoutStrategy``.
+    hold_band_pct : skip order for a name whose deviation from target weight is
+        below this fraction of the target (no-trade buffer band).
+    rebalance_every_n_weeks : rebalance every N ISO weeks instead of every week
+        (default 1 = weekly; 2 = biweekly).  Ignored when
+        ``rebalance_every_n_days`` is set.
+    rebalance_every_n_days : rebalance every N trading days (daily when N=1).
+        When set, overrides the weekly gating logic entirely.
+    """
+
+    def __init__(self, *, topk, n_drop, hold_band_pct: float = DEFAULT_HOLD_BAND_PCT,
+                 rebalance_every_n_weeks: int = 1,
+                 rebalance_every_n_days: int = 0, **kwargs):
+        super().__init__(topk=topk, n_drop=n_drop, **kwargs)
+        self.hold_band_pct = hold_band_pct
+        self.rebalance_every_n_weeks = rebalance_every_n_weeks
+        self.rebalance_every_n_days = rebalance_every_n_days
+
+    @staticmethod
+    def _iso_week(ts) -> tuple:
+        return (ts.year, ts.week)
+
+    def generate_trade_decision(self, execute_result=None):
+        import copy
+
+        trade_step = self.trade_calendar.get_trade_step()
+        trade_start_time, trade_end_time = self.trade_calendar.get_step_time(trade_step)
+
+        if self.rebalance_every_n_days > 0:
+            # daily gating: count trading steps since last rebalance
+            step_num = trade_step
+            if hasattr(self, "_last_rebal_step"):
+                if (step_num - self._last_rebal_step) < self.rebalance_every_n_days:
+                    return TradeDecisionWO([], self)
+            self._last_rebal_step = step_num
+        else:
+            cur_week = self._iso_week(trade_start_time)
+            prev_week = getattr(self, "_last_week", None)
+            self._last_week = cur_week
+
+            if prev_week is not None and prev_week == cur_week:
+                return TradeDecisionWO([], self)
+
+            if self.rebalance_every_n_weeks > 1:
+                week_num = cur_week[1]
+                if prev_week is not None and (week_num % self.rebalance_every_n_weeks) != 1:
+                    return TradeDecisionWO([], self)
+
+        pred_start_time, pred_end_time = self.trade_calendar.get_step_time(trade_step, shift=1)
+        pred_score = self.signal.get_signal(start_time=pred_start_time, end_time=pred_end_time)
+        if isinstance(pred_score, pd.DataFrame):
+            pred_score = pred_score.iloc[:, 0]
+        if pred_score is None:
+            return TradeDecisionWO([], self)
+
+        if self.only_tradable:
+
+            def get_first_n(li, n, reverse=False):
+                cur_n = 0
+                res = []
+                for si in reversed(li) if reverse else li:
+                    if self.trade_exchange.is_stock_tradable(
+                        stock_id=si, start_time=trade_start_time, end_time=trade_end_time
+                    ):
+                        res.append(si)
+                        cur_n += 1
+                        if cur_n >= n:
+                            break
+                return res[::-1] if reverse else res
+
+            def get_last_n(li, n):
+                return get_first_n(li, n, reverse=True)
+
+            def filter_stock(li):
+                return [
+                    si
+                    for si in li
+                    if self.trade_exchange.is_stock_tradable(
+                        stock_id=si, start_time=trade_start_time, end_time=trade_end_time
+                    )
+                ]
+
+        else:
+
+            def get_first_n(li, n):
+                return list(li)[:n]
+
+            def get_last_n(li, n):
+                return list(li)[-n:]
+
+            def filter_stock(li):
+                return li
+
+        current_temp: "object" = copy.deepcopy(self.trade_position)
+        sell_order_list: List[Order] = []
+        buy_order_list: List[Order] = []
+        cash = current_temp.get_cash()
+        current_stock_list = current_temp.get_stock_list()
+        last = pred_score.reindex(current_stock_list).sort_values(ascending=False).index
+
+        if self.method_buy == "top":
+            today = get_first_n(
+                pred_score[~pred_score.index.isin(last)].sort_values(ascending=False).index,
+                self.n_drop + self.topk - len(last),
+            )
+        elif self.method_buy == "random":
+            topk_candi = get_first_n(pred_score.sort_values(ascending=False).index, self.topk)
+            candi = list(filter(lambda x: x not in last, topk_candi))
+            n = self.n_drop + self.topk - len(last)
+            try:
+                today = np.random.choice(candi, n, replace=False)
+            except ValueError:
+                today = candi
+        else:
+            raise NotImplementedError(f"This type of input is not supported")
+
+        comb = pred_score.reindex(last.union(pd.Index(today))).sort_values(ascending=False).index
+
+        if self.method_sell == "bottom":
+            sell = last[last.isin(get_last_n(comb, self.n_drop))]
+        elif self.method_sell == "random":
+            candi = filter_stock(last)
+            try:
+                sell = pd.Index(np.random.choice(candi, self.n_drop, replace=False) if len(last) else [])
+            except ValueError:
+                sell = candi
+        else:
+            raise NotImplementedError(f"This type of input is not supported")
+
+        buy = today[: len(sell) + self.topk - len(last)]
+        for code in current_stock_list:
+            if not self.trade_exchange.is_stock_tradable(
+                stock_id=code,
+                start_time=trade_start_time,
+                end_time=trade_end_time,
+                direction=None if self.forbid_all_trade_at_limit else OrderDir.SELL,
+            ):
+                continue
+            if code in sell:
+                time_per_step = self.trade_calendar.get_freq()
+                if current_temp.get_stock_count(code, bar=time_per_step) < self.hold_thresh:
+                    continue
+                sell_amount = current_temp.get_stock_amount(code=code)
+                sell_order = Order(
+                    stock_id=code,
+                    amount=sell_amount,
+                    start_time=trade_start_time,
+                    end_time=trade_end_time,
+                    direction=Order.SELL,
+                )
+                if self.trade_exchange.check_order(sell_order):
+                    sell_order_list.append(sell_order)
+                    trade_val, trade_cost, trade_price = self.trade_exchange.deal_order(
+                        sell_order, position=current_temp
+                    )
+                    cash += trade_val - trade_cost
+
+        if len(buy) == 0:
+            return TradeDecisionWO(sell_order_list, self)
+
+        value = cash * self.risk_degree / len(buy)
+        for code in buy:
+            if not self.trade_exchange.is_stock_tradable(
+                stock_id=code,
+                start_time=trade_start_time,
+                end_time=trade_end_time,
+                direction=None if self.forbid_all_trade_at_limit else OrderDir.BUY,
+            ):
+                continue
+            buy_price = self.trade_exchange.get_deal_price(
+                stock_id=code, start_time=trade_start_time, end_time=trade_end_time, direction=OrderDir.BUY
+            )
+            buy_amount = value / buy_price
+            factor = self.trade_exchange.get_factor(
+                stock_id=code, start_time=trade_start_time, end_time=trade_end_time
+            )
+            buy_amount = self.trade_exchange.round_amount_by_trade_unit(buy_amount, factor)
+            buy_order = Order(
+                stock_id=code,
+                amount=buy_amount,
+                start_time=trade_start_time,
+                end_time=trade_end_time,
+                direction=Order.BUY,
+            )
+            buy_order_list.append(buy_order)
+
+        return TradeDecisionWO(sell_order_list + buy_order_list, self)

code/tac-qlib/tac_qlib/data/config.py

@@ -61,6 +61,11 @@ UNKNOWN_FIELD_NAMES = ("factor", "change", "trade_unit", "suspend_flag")
 #: columns in the parquet files that are not features
 NON_FEATURE_COLUMNS = ("t", "date", "market", "timeframe", "symbol")
 
+#: Feature-family partitions merged by ``LakeConfig.load_features`` and scanned
+#: by the handler's field discovery. ``macro`` holds broadcast market-state
+#: columns (see skills/tac-qlib-custom/examples/persist_macro_broadcast.py).
+FEATURE_FAMILIES = ("ta", "sp", "macro")
+
 
 def timeframe_for_freq(freq: str) -> str:
     """Map a qlib frequency (e.g. ``day``, ``1min``) to a lake timeframe (e.g. ``1d``)."""
@@ -113,12 +118,12 @@ class LakeConfig:
         return self.features_dir(timeframe) / f"symbol={str(symbol).upper()}.parquet"
 
     def load_features(self, timeframe: str, symbol: str) -> pd.DataFrame:
-        """All feature columns for a symbol, merging the `family=ta` and
+        """All feature columns for a symbol, merging the `family=ta|sp|macro`
-        `family=sp` partitions by timestamp. Returns an empty frame when no
+        partitions by timestamp. Returns an empty frame when no
         feature files exist (legacy flat layout falls back transparently)."""
         sym = str(symbol).upper()
         frames = []
-        for family in ("ta", "sp"):
+        for family in FEATURE_FAMILIES:
             p = self.features_dir(timeframe) / f"family={family}" / f"symbol={sym}.parquet"
             if p.exists():
                 frames.append(pd.read_parquet(p))

queue/workflows/q01_m2_sharpe22_repro.yaml

@@ -0,0 +1,140 @@
+# -----------------------------------------------------------------------------
+# QUEUE-01 — M2 reproduction: risk-adjusted 22d Sharpe drift (sp_sharpe_22).
+#
+# Hypothesis (book ch.01/ch.07, EVIDENCE#018 -> exp 30): adding the
+# risk-adjusted 22d Sharpe drift feature (sp_sharpe_22) to the compact
+# stochastic reference IMPROVES net portfolio performance (exp 30: net +6.53%
+# IR 0.62 vs reference +2.13% IR 0.21) while rank metrics dip (RankIC 0.0576 vs
+# 0.0663). exp 30 is a SINGLE clean-lake run, unreproduced -> HYPOTHESIS.
+#
+# Change vs exp-26 reference (EVIDENCE#015, run 21afc6af...): ONE feature added,
+# feature_fields = compact set + sp_sharpe_22. Everything else byte-identical.
+#
+# Acceptance: net_ann_return > +2.13% AND net_IR > 0.21 (else HYPOTHESIS -> REFUTED).
+# Run: rd_run_workflow config_path=<repo>/experiments/queue/workflows/q01_m2_sharpe22_repro.yaml \
+#        experiment_name=tac-rd-q01-m2-sharpe22-repro
+# -----------------------------------------------------------------------------
+{%- set LAKE = TAC_LAKE_DIR %}
+{%- set UNIVERSE = "SPY,QQQ,DIA,IWM,MDY,VTI,VOO,VEA,VWO,VT,EFA,EEM,TLT,IEF,SHY,AGG,BND,LQD,HYG,JNK,EMB,GLD,SLV,USO,UNG,DBA,DBC,XLK,XLF,XLE,XLV,XLI,XLY,XLP,XLU,XLB,XLRE,ARKK,SMH,SOXX,IBB,XBI,ITA,XAR,ICLN,TAN,FDN,IGV,ESPO,REM" %}
+{%- set FEATURES = "$open,$high,$low,$close,$vwap,$volume,sp_ret,sp_jump_ratio,sp_jump_flag,sp_jump_tail,sp_max_move,sp_rv1,sp_rv5,sp_rv22,sp_vol_ratio_5_22,sp_vol_ratio_1_22,sp_trend_slope_5,sp_trend_slope_20,sp_trend_slope_60,sp_logp,sp_hurst_exponent,sp_sig_level1_lead,sp_sig_level1_lag,sp_sig_level2_lead_lag,sp_sig_level2_lag_lead,sp_sharpe_22" %}
+
+qlib_init:
+    provider_uri: "{{ LAKE }}"
+    region: us
+    expression_cache: null
+    dataset_cache: null
+
+    calendar_provider:
+        class: tac_qlib.data.providers.LakeCalendarProvider
+        kwargs:
+            lake_root: "{{ LAKE }}"
+            market: US
+    instrument_provider:
+        class: tac_qlib.data.providers.LakeInstrumentProvider
+        kwargs:
+            lake_root: "{{ LAKE }}"
+            market: US
+            markets: {}
+    feature_provider:
+        class: tac_qlib.data.providers.LakeFeatureProvider
+        kwargs:
+            lake_root: "{{ LAKE }}"
+            market: US
+
+    exp_manager:
+        class: MLflowExpManager
+        module_path: qlib.workflow.expm
+        kwargs:
+            uri: "sqlite:///{{ LAKE }}/mlruns.db"
+            default_exp_name: "tac-rd-q01-m2-sharpe22-repro"
+
+task:
+    model:
+        class: RankICEnsembleLGBModel
+        module_path: tac_qlib.contrib.model.rank_ensemble
+        kwargs:
+            loss: mse
+            learning_rate: 0.02
+            num_leaves: 31
+            n_estimators: 3000
+            num_boost_round: 3000
+            early_stopping_rounds: 200
+            min_data_in_leaf: 20
+            lambda_l2: 0.5
+            colsample_bytree: 0.8
+            subsample: 0.8
+            subsample_freq: 1
+            reg_alpha: 0.1
+            reg_lambda: 1.0
+            seeds: "42,7,2026,99,123"
+            parallel: 5
+
+    dataset:
+        class: DatasetH
+        module_path: qlib.data.dataset
+        kwargs:
+            handler:
+                class: TACHandler
+                module_path: tac_qlib.contrib.data.handler
+                kwargs:
+                    instruments: "{{ UNIVERSE }}"
+                    start_time: 2015-01-03
+                    end_time: 2026-08-10
+                    fit_start_time: 2016-01-04
+                    fit_end_time: 2025-09-01
+                    freq: day
+                    lake_root: "{{ LAKE }}"
+                    market: US
+                    label: "Ref($close,-6)/Ref($close,-1)-1"
+                    feature_fields: "{{ FEATURES }}"
+                    infer_processors:
+                        - class: DropAllNaN
+                          kwargs: {}
+                        - class: ProcessInf
+                          kwargs: {}
+                        - class: CSRankNorm
+                          kwargs: {}
+                        - class: ZScoreNorm
+                          kwargs: {}
+                        - class: Fillna
+                          kwargs: {}
+            segments:
+                train: [2016-01-04, 2025-09-01]
+                valid: [2025-09-03, 2026-01-03]
+                test: [2026-01-04, 2026-08-10]
+
+    record:
+        - class: SignalRecord
+          module_path: qlib.workflow.record_temp
+          kwargs: {}
+        - class: SigAnaRecord
+          module_path: qlib.workflow.record_temp
+          kwargs:
+              ana_long_short: true
+              ann_scaler: 252
+        - class: PortAnaRecord
+          module_path: qlib.workflow.record_temp
+          kwargs:
+              config:
+                  strategy:
+                      class: TopkDropoutStrategy
+                      module_path: qlib.contrib.strategy
+                      kwargs:
+                          signal: "<PRED>"
+                          topk: 10
+                          n_drop: 1
+                          only_tradable: true
+                          risk_degree: 0.95
+                  backtest:
+                      start_time: 2026-01-04
+                      end_time: 2026-08-10
+                      account: 1000000
+                      benchmark: SPY
+                      exchange_kwargs:
+                          codes: "{{ UNIVERSE }}"
+                          deal_price: $close
+                          freq: day
+                          open_cost: 0.0005
+                          close_cost: 0.0015
+                          min_cost: 5.0
+              risk_analysis_freq: 1d

workflows/exp30/workflow.yaml

@@ -0,0 +1,99 @@
+# M2 isolation run: base compact set + risk-adjusted drift sp_sharpe_22.
+# Exact copy of exp26 (reference: expId=25 run=21afc6afdb674a399b59dd76c97628ce)
+# except feature_fields. 5-seed ensemble.
+{%- set LAKE = TAC_LAKE_DIR %}
+{%- set UNIVERSE = "SPY,QQQ,DIA,IWM,MDY,VTI,VOO,VEA,VWO,VT,EFA,EEM,TLT,IEF,SHY,AGG,BND,LQD,HYG,JNK,EMB,GLD,SLV,USO,UNG,DBA,DBC,XLK,XLF,XLE,XLV,XLI,XLY,XLP,XLU,XLB,XLRE,ARKK,SMH,SOXX,IBB,XBI,ITA,XAR,ICLN,TAN,FDN,IGV,ESPO,REM" %}
+{%- set FEATURES = "$open,$high,$low,$close,$vwap,$volume,sp_ret,sp_jump_ratio,sp_jump_flag,sp_jump_tail,sp_max_move,sp_rv1,sp_rv5,sp_rv22,sp_vol_ratio_5_22,sp_vol_ratio_1_22,sp_trend_slope_5,sp_trend_slope_20,sp_trend_slope_60,sp_logp,sp_hurst_exponent,sp_sig_level1_lead,sp_sig_level1_lag,sp_sig_level2_lead_lag,sp_sig_level2_lag_lead,sp_sharpe_22" %}
+
+qlib_init:
+    provider_uri: "{{ LAKE }}"
+    region: us
+    expression_cache: null
+    dataset_cache: null
+    calendar_provider:
+        class: tac_qlib.data.providers.LakeCalendarProvider
+        kwargs: { lake_root: "{{ LAKE }}", market: US }
+    instrument_provider:
+        class: tac_qlib.data.providers.LakeInstrumentProvider
+        kwargs: { lake_root: "{{ LAKE }}", market: US, markets: {} }
+    feature_provider:
+        class: tac_qlib.data.providers.LakeFeatureProvider
+        kwargs: { lake_root: "{{ LAKE }}", market: US }
+    exp_manager:
+        class: MLflowExpManager
+        module_path: qlib.workflow.expm
+        kwargs: { uri: "sqlite:///mlruns.db", default_exp_name: "tac-rd-exp30-m2-sharpe" }
+
+task:
+    model:
+        class: RankICEnsembleLGBModel
+        module_path: tac_qlib.contrib.model.rank_ensemble
+        kwargs:
+            loss: mse
+            learning_rate: 0.02
+            num_leaves: 31
+            n_estimators: 3000
+            num_boost_round: 3000
+            early_stopping_rounds: 200
+            min_data_in_leaf: 20
+            lambda_l2: 0.5
+            colsample_bytree: 0.8
+            subsample: 0.8
+            subsample_freq: 1
+            reg_alpha: 0.1
+            reg_lambda: 1.0
+            seeds: "42,7,2026,99,123"
+
+    dataset:
+        class: DatasetH
+        module_path: qlib.data.dataset
+        kwargs:
+            handler:
+                class: TACHandler
+                module_path: tac_qlib.contrib.data.handler
+                kwargs:
+                    instruments: "{{ UNIVERSE }}"
+                    start_time: 2015-01-03
+                    end_time: 2026-08-10
+                    fit_start_time: 2016-01-04
+                    fit_end_time: 2025-09-01
+                    freq: day
+                    lake_root: "{{ LAKE }}"
+                    market: US
+                    label: "Ref($close,-6)/Ref($close,-1)-1"
+                    feature_fields: "{{ FEATURES }}"
+                    infer_processors:
+                        - { class: DropAllNaN, kwargs: { fit_start_time: "2016-01-04", fit_end_time: "2025-09-01" } }
+                        - { class: ProcessInf, kwargs: {} }
+                        - { class: CSRankNorm, kwargs: {} }
+                        - { class: ZScoreNorm, kwargs: { fit_start_time: "2016-01-04", fit_end_time: "2025-09-01" } }
+                        - { class: Fillna, kwargs: {} }
+            segments:
+                train: [2016-01-04, 2025-09-01]
+                valid: [2025-09-03, 2026-01-03]
+                test: [2026-01-04, 2026-08-10]
+
+    record:
+        - { class: SignalRecord, module_path: qlib.workflow.record_temp, kwargs: {} }
+        - { class: SigAnaRecord, module_path: qlib.workflow.record_temp, kwargs: { ana_long_short: true, ann_scaler: 252 } }
+        - class: PortAnaRecord
+          module_path: qlib.workflow.record_temp
+          kwargs:
+              config:
+                  strategy:
+                      class: TopkDropoutStrategy
+                      module_path: qlib.contrib.strategy
+                      kwargs: { signal: "<PRED>", topk: 10, n_drop: 1, only_tradable: true, risk_degree: 0.95 }
+                  backtest:
+                      start_time: 2026-01-04
+                      end_time: 2026-08-10
+                      account: 1000000
+                      benchmark: SPY
+                      exchange_kwargs:
+                          codes: "{{ UNIVERSE }}"
+                          deal_price: $close
+                          freq: day
+                          open_cost: 0.0005
+                          close_cost: 0.0015
+                          min_cost: 5.0
+              risk_analysis_freq: 1d

workflows/exp31/workflow.yaml

@@ -0,0 +1,99 @@
+# M3 isolation run: base compact set + GARCH(1,1) vol-regime trio.
+# Exact copy of exp26 (reference: expId=25 run=21afc6afdb674a399b59dd76c97628ce)
+# except feature_fields. 5-seed ensemble.
+{%- set LAKE = TAC_LAKE_DIR %}
+{%- set UNIVERSE = "SPY,QQQ,DIA,IWM,MDY,VTI,VOO,VEA,VWO,VT,EFA,EEM,TLT,IEF,SHY,AGG,BND,LQD,HYG,JNK,EMB,GLD,SLV,USO,UNG,DBA,DBC,XLK,XLF,XLE,XLV,XLI,XLY,XLP,XLU,XLB,XLRE,ARKK,SMH,SOXX,IBB,XBI,ITA,XAR,ICLN,TAN,FDN,IGV,ESPO,REM" %}
+{%- set FEATURES = "$open,$high,$low,$close,$vwap,$volume,sp_ret,sp_jump_ratio,sp_jump_flag,sp_jump_tail,sp_max_move,sp_rv1,sp_rv5,sp_rv22,sp_vol_ratio_5_22,sp_vol_ratio_1_22,sp_trend_slope_5,sp_trend_slope_20,sp_trend_slope_60,sp_logp,sp_hurst_exponent,sp_sig_level1_lead,sp_sig_level1_lag,sp_sig_level2_lead_lag,sp_sig_level2_lag_lead,sp_garch_cond_var,sp_garch_persistence,sp_garch_std_resid" %}
+
+qlib_init:
+    provider_uri: "{{ LAKE }}"
+    region: us
+    expression_cache: null
+    dataset_cache: null
+    calendar_provider:
+        class: tac_qlib.data.providers.LakeCalendarProvider
+        kwargs: { lake_root: "{{ LAKE }}", market: US }
+    instrument_provider:
+        class: tac_qlib.data.providers.LakeInstrumentProvider
+        kwargs: { lake_root: "{{ LAKE }}", market: US, markets: {} }
+    feature_provider:
+        class: tac_qlib.data.providers.LakeFeatureProvider
+        kwargs: { lake_root: "{{ LAKE }}", market: US }
+    exp_manager:
+        class: MLflowExpManager
+        module_path: qlib.workflow.expm
+        kwargs: { uri: "sqlite:///mlruns.db", default_exp_name: "tac-rd-exp31-m3-garch" }
+
+task:
+    model:
+        class: RankICEnsembleLGBModel
+        module_path: tac_qlib.contrib.model.rank_ensemble
+        kwargs:
+            loss: mse
+            learning_rate: 0.02
+            num_leaves: 31
+            n_estimators: 3000
+            num_boost_round: 3000
+            early_stopping_rounds: 200
+            min_data_in_leaf: 20
+            lambda_l2: 0.5
+            colsample_bytree: 0.8
+            subsample: 0.8
+            subsample_freq: 1
+            reg_alpha: 0.1
+            reg_lambda: 1.0
+            seeds: "42,7,2026,99,123"
+
+    dataset:
+        class: DatasetH
+        module_path: qlib.data.dataset
+        kwargs:
+            handler:
+                class: TACHandler
+                module_path: tac_qlib.contrib.data.handler
+                kwargs:
+                    instruments: "{{ UNIVERSE }}"
+                    start_time: 2015-01-03
+                    end_time: 2026-08-10
+                    fit_start_time: 2016-01-04
+                    fit_end_time: 2025-09-01
+                    freq: day
+                    lake_root: "{{ LAKE }}"
+                    market: US
+                    label: "Ref($close,-6)/Ref($close,-1)-1"
+                    feature_fields: "{{ FEATURES }}"
+                    infer_processors:
+                        - { class: DropAllNaN, kwargs: { fit_start_time: "2016-01-04", fit_end_time: "2025-09-01" } }
+                        - { class: ProcessInf, kwargs: {} }
+                        - { class: CSRankNorm, kwargs: {} }
+                        - { class: ZScoreNorm, kwargs: { fit_start_time: "2016-01-04", fit_end_time: "2025-09-01" } }
+                        - { class: Fillna, kwargs: {} }
+            segments:
+                train: [2016-01-04, 2025-09-01]
+                valid: [2025-09-03, 2026-01-03]
+                test: [2026-01-04, 2026-08-10]
+
+    record:
+        - { class: SignalRecord, module_path: qlib.workflow.record_temp, kwargs: {} }
+        - { class: SigAnaRecord, module_path: qlib.workflow.record_temp, kwargs: { ana_long_short: true, ann_scaler: 252 } }
+        - class: PortAnaRecord
+          module_path: qlib.workflow.record_temp
+          kwargs:
+              config:
+                  strategy:
+                      class: TopkDropoutStrategy
+                      module_path: qlib.contrib.strategy
+                      kwargs: { signal: "<PRED>", topk: 10, n_drop: 1, only_tradable: true, risk_degree: 0.95 }
+                  backtest:
+                      start_time: 2026-01-04
+                      end_time: 2026-08-10
+                      account: 1000000
+                      benchmark: SPY
+                      exchange_kwargs:
+                          codes: "{{ UNIVERSE }}"
+                          deal_price: $close
+                          freq: day
+                          open_cost: 0.0005
+                          close_cost: 0.0015
+                          min_cost: 5.0
+              risk_analysis_freq: 1d