quantbt-engine 1.0.7__py3-none-any.whl

quantbt/core/basket.py

@@ -0,0 +1,234 @@
+"""
+quantbt.core.basket
+-------------------
+Basket and pair-trading order-plan helpers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+from .orders import OrderIntent
+from .preprocessor import align_series, validate_datetime
+from .schema import BasketSpec, OrderSide, OrderType, TimeInForce
+
+
+@dataclass(frozen=True)
+class FrozenBasketPlan:
+    basket: BasketSpec
+    orders: Tuple[OrderIntent, ...]
+    target_units: pd.DataFrame
+    signals: pd.Series
+    entry_ratios: pd.DataFrame
+    metadata: Dict = field(default_factory=dict)
+
+
+def build_frozen_basket_orders(
+    datetime_index,
+    basket: BasketSpec,
+    signal: pd.Series,
+    closes: Dict[str, pd.Series],
+    hedge_ratios: Optional[Dict[str, pd.Series]] = None,
+    order_type: OrderType = OrderType.MARKET,
+    tif: TimeInForce = TimeInForce.IOC,
+    rebalance_threshold: Optional[float] = None,
+    min_abs_delta: float = 1e-12,
+) -> FrozenBasketPlan:
+    """
+    Convert a scalar basket signal into leg orders with hedge freezing.
+
+    Ratios are interpreted as unit ratios per one basket unit. At every signal
+    transition, units are recomputed from the entry bar prices and then held
+    unchanged until the next signal transition. Price drift alone does not
+    generate micro-rebalancing orders.
+    """
+    if order_type is not OrderType.MARKET:
+        raise NotImplementedError("Phase 4 basket order generation supports market orders")
+    if min_abs_delta < 0.0:
+        raise ValueError("min_abs_delta must be >= 0")
+    if rebalance_threshold is not None and rebalance_threshold < 0.0:
+        raise ValueError("rebalance_threshold must be >= 0")
+
+    idx = validate_datetime(datetime_index)
+    symbols = [leg.symbol for leg in basket.legs]
+    if len(set(symbols)) != len(symbols):
+        raise ValueError("basket legs must have unique symbols")
+    if not set(symbols).issubset(closes.keys()):
+        missing = sorted(set(symbols) - set(closes.keys()))
+        raise ValueError(f"missing closes for basket legs: {missing}")
+
+    close_dict = align_series(closes, symbols, idx)
+    sig = _align_signal(signal, idx)
+    ratio_dict = _build_ratio_series(basket, hedge_ratios, symbols, idx)
+
+    orders = []
+    current_units = {s: 0.0 for s in symbols}
+    current_signal = 0.0
+    target_rows = []
+    ratio_rows = []
+
+    for ts in idx:
+        raw_signal = float(sig.loc[ts])
+        if abs(raw_signal) < min_abs_delta:
+            raw_signal = 0.0
+
+        signal_changed = abs(raw_signal - current_signal) > min_abs_delta
+        ratio_drift = _max_ratio_drift(current_units, ratio_dict, symbols, ts)
+        should_rebalance = (
+            rebalance_threshold is not None
+            and raw_signal != 0.0
+            and not signal_changed
+            and ratio_drift > rebalance_threshold
+        )
+        if signal_changed or should_rebalance:
+            target_units = _compute_entry_units(
+                basket=basket,
+                signal_value=raw_signal,
+                symbols=symbols,
+                timestamp=ts,
+                closes=close_dict,
+                ratios=ratio_dict,
+            )
+
+            for sym in symbols:
+                delta = target_units[sym] - current_units[sym]
+                if abs(delta) <= min_abs_delta:
+                    continue
+                side = OrderSide.BUY if delta > 0.0 else OrderSide.SELL
+                orders.append(
+                    OrderIntent(
+                        timestamp=ts,
+                        symbol=sym,
+                        side=side,
+                        order_type=order_type,
+                        qty=abs(delta),
+                        tif=tif,
+                        tag=basket.basket_id,
+                        metadata={
+                            "basket_id": basket.basket_id,
+                            "basket_signal": raw_signal,
+                            "basket_policy": basket.execution_policy.value,
+                            "hedge_frozen": basket.freeze_hedge,
+                            "rebalance": should_rebalance,
+                            "ratio_drift": ratio_drift,
+                            "target_units": target_units[sym],
+                            "previous_units": current_units[sym],
+                        },
+                    )
+                )
+                current_units[sym] = target_units[sym]
+
+            current_signal = raw_signal
+
+        target_rows.append({s: current_units[s] for s in symbols})
+        ratio_rows.append({s: float(ratio_dict[s].loc[ts]) for s in symbols})
+
+    return FrozenBasketPlan(
+        basket=basket,
+        orders=tuple(orders),
+        target_units=pd.DataFrame(target_rows, index=idx),
+        signals=sig,
+        entry_ratios=pd.DataFrame(ratio_rows, index=idx),
+        metadata={
+            "basket_id": basket.basket_id,
+            "gross_notional": basket.gross_notional,
+            "freeze_hedge": basket.freeze_hedge,
+            "execution_policy": basket.execution_policy.value,
+            "hedged_margin_offset": basket.hedged_margin_offset,
+            "rebalance_threshold": rebalance_threshold,
+        },
+    )
+
+
+def _align_signal(signal: pd.Series, idx: pd.DatetimeIndex) -> pd.Series:
+    if not isinstance(signal, pd.Series):
+        signal = pd.Series(signal, index=idx)
+    else:
+        signal = signal.copy()
+        if isinstance(signal.index, pd.DatetimeIndex):
+            if signal.index.tz is None:
+                signal.index = signal.index.tz_localize("UTC")
+            else:
+                signal.index = signal.index.tz_convert("UTC")
+    return signal.reindex(idx, method="ffill").fillna(0.0).astype(float)
+
+
+def _build_ratio_series(
+    basket: BasketSpec,
+    hedge_ratios: Optional[Dict[str, pd.Series]],
+    symbols: list[str],
+    idx: pd.DatetimeIndex,
+) -> Dict[str, pd.Series]:
+    defaults = {leg.symbol: float(leg.ratio) for leg in basket.legs}
+    if hedge_ratios is None:
+        return {s: pd.Series(defaults[s], index=idx, dtype=float) for s in symbols}
+
+    out = {}
+    for s in symbols:
+        value = hedge_ratios.get(s, defaults[s])
+        if isinstance(value, pd.Series):
+            ser = value.copy()
+            if isinstance(ser.index, pd.DatetimeIndex):
+                if ser.index.tz is None:
+                    ser.index = ser.index.tz_localize("UTC")
+                else:
+                    ser.index = ser.index.tz_convert("UTC")
+            out[s] = ser.reindex(idx, method="ffill").fillna(defaults[s]).astype(float)
+        else:
+            out[s] = pd.Series(float(value), index=idx, dtype=float)
+    return out
+
+
+def _compute_entry_units(
+    basket: BasketSpec,
+    signal_value: float,
+    symbols: list[str],
+    timestamp,
+    closes: Dict[str, pd.Series],
+    ratios: Dict[str, pd.Series],
+) -> Dict[str, float]:
+    if signal_value == 0.0:
+        return {s: 0.0 for s in symbols}
+
+    gross_unit_notional = 0.0
+    for s in symbols:
+        price = float(closes[s].loc[timestamp])
+        ratio = float(ratios[s].loc[timestamp])
+        gross_unit_notional += abs(ratio) * price
+
+    if not np.isfinite(gross_unit_notional) or gross_unit_notional <= 0.0:
+        return {s: 0.0 for s in symbols}
+
+    basket_units = basket.gross_notional * abs(signal_value) / gross_unit_notional
+    signal_side = 1.0 if signal_value > 0.0 else -1.0
+    return {
+        s: basket_units * float(ratios[s].loc[timestamp]) * signal_side
+        for s in symbols
+    }
+
+
+def _max_ratio_drift(
+    current_units: Dict[str, float],
+    ratios: Dict[str, pd.Series],
+    symbols: list[str],
+    timestamp,
+) -> float:
+    if not symbols:
+        return 0.0
+    ref_symbol = symbols[0]
+    frozen_ref = float(current_units[ref_symbol])
+    current_ref = float(ratios[ref_symbol].loc[timestamp])
+    if abs(frozen_ref) <= 1e-12 or abs(current_ref) <= 1e-12:
+        return 0.0
+
+    max_drift = 0.0
+    for symbol in symbols[1:]:
+        frozen_ratio = float(current_units[symbol]) / frozen_ref
+        current_ratio = float(ratios[symbol].loc[timestamp]) / current_ref
+        denom = max(abs(frozen_ratio), 1e-12)
+        max_drift = max(max_drift, abs(current_ratio - frozen_ratio) / denom)
+    return max_drift

quantbt/core/certification.py

@@ -0,0 +1,274 @@
+"""
+Alpha execution-contract certification helpers.
+
+These helpers are intentionally lightweight and conservative. They do not try
+to prove a strategy has no look-ahead bias from source text alone; they identify
+which execution contract a file appears to require and what certification level
+an already-run result can claim from its metadata.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from enum import IntEnum
+from pathlib import Path
+import re
+from typing import Dict, Iterable, List, Optional, Sequence
+
+
+class CertificationLevel(IntEnum):
+    LEGACY = 0
+    ACCOUNTING_REPLAY = 1
+    ENGINE_CAUSAL = 2
+    CROSS_BACKEND = 3
+    EXTERNAL_VALIDATION = 4
+
+
+LEVEL_DESCRIPTIONS = {
+    CertificationLevel.LEGACY: "legacy_or_unspecified_execution_contract",
+    CertificationLevel.ACCOUNTING_REPLAY: "explicit_fills_accounted_but_fill_generation_not_certified",
+    CertificationLevel.ENGINE_CAUSAL: "engine_owned_causal_execution_with_oracle_or_kernel_parity",
+    CertificationLevel.CROSS_BACKEND: "native_engine_matches_native_event_on_known_scenarios",
+    CertificationLevel.EXTERNAL_VALIDATION: "external_or_lower_timeframe_validation_available",
+}
+
+
+INTRABAR_MARKERS = (
+    "exit_price",
+    "exit_type",
+    "stop_loss",
+    "stoploss",
+    "take_profit",
+    "takeprofit",
+    "trailing",
+    "trailing_stop",
+    "use_sl",
+    "use_tp",
+    "slpercent",
+    "tppercent",
+    "high[",
+    "low[",
+)
+FILL_REPLAY_MARKERS = ("fill_replay", "fills_df", "compact_fill", "bar_index", "sequence")
+GRID_MARKERS = ("dca_ladder", "grid", "safety_order", "take_profit_price", "stop_loss_price")
+NEXT_OPEN_MARKERS = ("next_open", "open[t+1]", "shift(1)", "open.shift")
+CLOSE_TARGET_MARKERS = ("native_vectorized", "signal_notional", "pos_weight", "target_weight")
+
+
+@dataclass(frozen=True)
+class AlphaExecutionClassification:
+    alpha_id: str
+    path: str
+    required_engine: str
+    current_backend: str
+    certification_status: str
+    certification_level: int
+    markers: tuple[str, ...] = ()
+    notes: tuple[str, ...] = ()
+    uses_intrabar_high_low: bool = False
+    uses_stop: bool = False
+    uses_take_profit: bool = False
+    uses_trailing: bool = False
+    uses_custom_exit_price: bool = False
+    uses_explicit_fills: bool = False
+    uses_grid_or_dca: bool = False
+    metadata: Dict = field(default_factory=dict)
+
+    def to_dict(self) -> Dict:
+        return asdict(self)
+
+
+def classify_alpha_source(source: str, *, alpha_id: str = "unknown", path: str = "") -> AlphaExecutionClassification:
+    text = source.lower()
+    markers = _matched_markers(text)
+    current_backend = _detect_current_backend(text)
+    uses_explicit_fills = any(marker in text for marker in FILL_REPLAY_MARKERS)
+    uses_grid_or_dca = any(marker in text for marker in GRID_MARKERS)
+    uses_stop = any(marker in text for marker in ("stop_loss", "stoploss", "slpercent", "use_sl"))
+    uses_take_profit = any(marker in text for marker in ("take_profit", "takeprofit", "tppercent", "use_tp"))
+    uses_trailing = "trailing" in text
+    uses_custom_exit_price = "exit_price" in text or "exit_type" in text
+    uses_intrabar_high_low = bool(re.search(r"\bhigh\s*\[|\blow\s*\[|df\s*\[\s*['\"]high|df\s*\[\s*['\"]low", text))
+
+    if uses_grid_or_dca:
+        required_engine = "event_lifecycle_v2"
+        level = CertificationLevel.LEGACY
+        status = "needs_specialized_event_or_nautilus_certification"
+    elif uses_explicit_fills and not (uses_stop or uses_take_profit or uses_trailing):
+        required_engine = "fill_replay_v1"
+        level = CertificationLevel.ACCOUNTING_REPLAY
+        status = "can_start_with_accounting_replay"
+    elif uses_stop or uses_take_profit or uses_trailing or uses_custom_exit_price or uses_intrabar_high_low:
+        required_engine = "intrabar_bracket_v1"
+        level = CertificationLevel.LEGACY
+        status = "requires_intrabar_migration"
+    elif any(marker in text for marker in NEXT_OPEN_MARKERS):
+        required_engine = "next_open_v1"
+        level = CertificationLevel.LEGACY
+        status = "requires_next_open_contract"
+    elif any(marker in text for marker in CLOSE_TARGET_MARKERS):
+        required_engine = "close_target_v2"
+        level = CertificationLevel.ENGINE_CAUSAL if current_backend in {"native_vectorized", "close_target_v2"} else CertificationLevel.LEGACY
+        status = "close_target_candidate"
+    else:
+        required_engine = "unknown"
+        level = CertificationLevel.LEGACY
+        status = "manual_review_required"
+
+    notes = _notes_for_classification(required_engine, current_backend, markers)
+    return AlphaExecutionClassification(
+        alpha_id=alpha_id,
+        path=path,
+        required_engine=required_engine,
+        current_backend=current_backend,
+        certification_status=status,
+        certification_level=int(level),
+        markers=tuple(markers),
+        notes=tuple(notes),
+        uses_intrabar_high_low=uses_intrabar_high_low,
+        uses_stop=uses_stop,
+        uses_take_profit=uses_take_profit,
+        uses_trailing=uses_trailing,
+        uses_custom_exit_price=uses_custom_exit_price,
+        uses_explicit_fills=uses_explicit_fills,
+        uses_grid_or_dca=uses_grid_or_dca,
+    )
+
+
+def scan_alpha_directory(root: str | Path, *, suffixes: Sequence[str] = (".py", ".ipynb", ".md"), max_bytes: int = 2_000_000) -> List[AlphaExecutionClassification]:
+    base = Path(root)
+    if not base.exists():
+        raise FileNotFoundError(str(base))
+    out: list[AlphaExecutionClassification] = []
+    for path in sorted(p for p in base.rglob("*") if p.is_file() and p.suffix.lower() in suffixes):
+        if any(part.startswith(".") for part in path.relative_to(base).parts):
+            continue
+        if path.stat().st_size > max_bytes:
+            out.append(
+                AlphaExecutionClassification(
+                    alpha_id=path.stem,
+                    path=str(path),
+                    required_engine="unknown",
+                    current_backend="unknown",
+                    certification_status="skipped_large_file",
+                    certification_level=int(CertificationLevel.LEGACY),
+                    notes=("file exceeds scanner max_bytes",),
+                )
+            )
+            continue
+        text = path.read_text(encoding="utf-8", errors="ignore")
+        out.append(classify_alpha_source(text, alpha_id=path.stem, path=str(path)))
+    return out
+
+
+def certify_result_metadata(metadata: Dict) -> Dict:
+    engine = str(metadata.get("engine_id") or metadata.get("engine") or "").lower()
+    backend = str(metadata.get("backend") or metadata.get("backend_alias") or "").lower()
+    if engine == "fill_replay_v1":
+        level = CertificationLevel.ACCOUNTING_REPLAY
+        status = "accounting_certified"
+    elif engine == "intrabar_bracket_v1":
+        level = CertificationLevel.ENGINE_CAUSAL
+        status = "engine_causal_certified"
+        if metadata.get("cross_backend_parity_passed"):
+            level = CertificationLevel.CROSS_BACKEND
+            status = "cross_backend_certified"
+    elif backend == "nautilus" or "nautilus" in engine:
+        level = CertificationLevel.EXTERNAL_VALIDATION
+        status = "external_validation_route"
+    elif engine == "close_target_v2":
+        level = CertificationLevel.ENGINE_CAUSAL
+        status = "close_target_certified"
+        if str(metadata.get("certification_status", "")).startswith("uncertified"):
+            level = CertificationLevel.LEGACY
+            status = str(metadata.get("certification_status"))
+    else:
+        level = CertificationLevel.LEGACY
+        status = "uncertified_or_unknown"
+    return {
+        "engine_id": engine or "unknown",
+        "backend": backend or "unknown",
+        "certification_level": int(level),
+        "certification_label": f"LEVEL {int(level)}",
+        "certification_status": status,
+        "description": LEVEL_DESCRIPTIONS[level],
+    }
+
+
+def build_alpha_certification_report(items: Iterable[AlphaExecutionClassification]) -> Dict:
+    rows = [item.to_dict() for item in items]
+    by_engine: Dict[str, int] = {}
+    by_status: Dict[str, int] = {}
+    for row in rows:
+        by_engine[row["required_engine"]] = by_engine.get(row["required_engine"], 0) + 1
+        by_status[row["certification_status"]] = by_status.get(row["certification_status"], 0) + 1
+    return {
+        "total": len(rows),
+        "by_required_engine": by_engine,
+        "by_status": by_status,
+        "items": rows,
+    }
+
+
+def alpha_report_markdown(report: Dict) -> str:
+    lines = [
+        "# Alpha Execution Certification Report",
+        "",
+        f"- Total files scanned: `{report['total']}`",
+        "",
+        "## By Required Engine",
+        "",
+        "| Engine | Count |",
+        "|---|---:|",
+    ]
+    for engine, count in sorted(report["by_required_engine"].items()):
+        lines.append(f"| `{engine}` | {count} |")
+    lines.extend(["", "## By Status", "", "| Status | Count |", "|---|---:|"])
+    for status, count in sorted(report["by_status"].items()):
+        lines.append(f"| `{status}` | {count} |")
+    lines.extend(["", "## Files", "", "| Alpha | Required engine | Current backend | Status | Markers |", "|---|---|---|---|---|"])
+    for item in report["items"]:
+        markers = ", ".join(item["markers"][:8])
+        if len(item["markers"]) > 8:
+            markers += ", ..."
+        lines.append(
+            f"| `{item['alpha_id']}` | `{item['required_engine']}` | `{item['current_backend']}` | "
+            f"`{item['certification_status']}` | {markers or '-'} |"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def _matched_markers(text: str) -> list[str]:
+    all_markers = sorted(set(INTRABAR_MARKERS + FILL_REPLAY_MARKERS + GRID_MARKERS + NEXT_OPEN_MARKERS + CLOSE_TARGET_MARKERS))
+    return [marker for marker in all_markers if marker in text]
+
+
+def _detect_current_backend(text: str) -> str:
+    if "nautilus_validation" in text or "backend=\"nautilus\"" in text or "backend='nautilus'" in text:
+        return "nautilus"
+    if "intrabar_bracket" in text:
+        return "native_intrabar"
+    if "fill_replay" in text:
+        return "fill_replay_v1"
+    if "native_event" in text:
+        return "native_event"
+    if "native_vectorized" in text:
+        return "native_vectorized"
+    if "%_equity" in text or "pct_equity" in text:
+        return "legacy_pct_equity"
+    if "backtestengine(" in text:
+        return "legacy"
+    return "unknown"
+
+
+def _notes_for_classification(required_engine: str, current_backend: str, markers: Sequence[str]) -> list[str]:
+    notes: list[str] = []
+    if required_engine == "intrabar_bracket_v1" and current_backend in {"native_vectorized", "legacy", "legacy_pct_equity"}:
+        notes.append("intrabar markers found on a close-target/legacy route; migrate to intrabar intent or fill replay")
+    if required_engine == "fill_replay_v1":
+        notes.append("accounting can be validated from explicit fills, but fill generation remains alpha-owned")
+    if required_engine == "event_lifecycle_v2":
+        notes.append("multi-order/grid/DCA behavior should stay on event lifecycle or Nautilus validation")
+    if not markers:
+        notes.append("no execution-sensitive markers detected; manual review still required before production certification")
+    return notes

quantbt/core/constraints.py

@@ -0,0 +1,155 @@
+"""Exchange/instrument quantity constraints shared by all backends."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Optional, Sequence, Union
+
+import numpy as np
+
+from .schema import InstrumentSpec
+
+
+NumberOrMap = Union[float, Dict[str, float], None]
+
+
+@dataclass(frozen=True)
+class QuantityConstraints:
+    """Per-symbol exchange quantity rules.
+
+    `contract_size` remains the PnL/notional multiplier.  Fractional crypto
+    acceptance is controlled by `qty_step`/`lot_size`, `min_qty`, and
+    `min_notional`.  QuantBT rounds target quantities down by default, matching
+    the conservative side of common exchange filters.
+    """
+
+    symbols: tuple[str, ...]
+    qty_step: np.ndarray
+    min_qty: np.ndarray
+    min_notional: np.ndarray
+
+    @property
+    def enabled(self) -> bool:
+        return bool(
+            np.any(self.qty_step > 0.0)
+            or np.any(self.min_qty > 0.0)
+            or np.any(self.min_notional > 0.0)
+        )
+
+    def as_dict(self) -> Dict[str, Dict[str, float]]:
+        return {
+            symbol: {
+                "qty_step": float(self.qty_step[i]),
+                "lot_size": float(self.qty_step[i]),
+                "min_qty": float(self.min_qty[i]),
+                "min_notional": float(self.min_notional[i]),
+            }
+            for i, symbol in enumerate(self.symbols)
+        }
+
+
+def build_quantity_constraints(
+    symbols: Sequence[str],
+    *,
+    instruments: Optional[Union[Dict[str, InstrumentSpec], Sequence[InstrumentSpec]]] = None,
+    qty_step: NumberOrMap = None,
+    lot_size: NumberOrMap = None,
+    slot_size: NumberOrMap = None,
+    min_qty: NumberOrMap = None,
+    min_notional: NumberOrMap = None,
+) -> QuantityConstraints:
+    """Resolve quantity constraints from explicit kwargs and InstrumentSpec.
+
+    Explicit kwargs override `InstrumentSpec`. `slot_size` is accepted as a
+    backward-compatible alias for `lot_size`.
+    """
+
+    symbol_list = tuple(symbols)
+    inst_map = _instrument_map(instruments)
+    step_source = qty_step if qty_step is not None else (lot_size if lot_size is not None else slot_size)
+
+    steps = []
+    min_qtys = []
+    min_notionals = []
+    for symbol in symbol_list:
+        inst = inst_map.get(symbol)
+        default_step = 0.0 if inst is None else float(inst.lot_size)
+        default_min_qty = 0.0 if inst is None else float(inst.min_qty)
+        default_min_notional = 0.0 if inst is None else float(inst.min_notional)
+        steps.append(_value_for(step_source, symbol, default_step))
+        min_qtys.append(_value_for(min_qty, symbol, default_min_qty))
+        min_notionals.append(_value_for(min_notional, symbol, default_min_notional))
+
+    out = QuantityConstraints(
+        symbols=symbol_list,
+        qty_step=np.asarray(steps, dtype=np.float64),
+        min_qty=np.asarray(min_qtys, dtype=np.float64),
+        min_notional=np.asarray(min_notionals, dtype=np.float64),
+    )
+    if np.any(out.qty_step < 0.0) or np.any(out.min_qty < 0.0) or np.any(out.min_notional < 0.0):
+        raise ValueError("qty_step/lot_size, min_qty, and min_notional must be >= 0")
+    return out
+
+
+def quantize_target_units_matrix(
+    target_units: np.ndarray,
+    prices: np.ndarray,
+    contract_sizes: np.ndarray,
+    constraints: QuantityConstraints,
+) -> np.ndarray:
+    """Round target-unit matrix down to exchange-acceptable quantities."""
+
+    if not constraints.enabled:
+        return np.ascontiguousarray(target_units, dtype=np.float64)
+    out = np.asarray(target_units, dtype=np.float64).copy(order="C")
+    prices_arr = np.asarray(prices, dtype=np.float64)
+    cs = np.asarray(contract_sizes, dtype=np.float64)
+    for j in range(out.shape[1]):
+        step = float(constraints.qty_step[j])
+        mnq = float(constraints.min_qty[j])
+        mnn = float(constraints.min_notional[j])
+        for i in range(out.shape[0]):
+            out[i, j] = quantize_signed_quantity(out[i, j], prices_arr[i, j], cs[j], step, mnq, mnn)
+    return np.ascontiguousarray(out, dtype=np.float64)
+
+
+def quantize_signed_quantity(
+    qty: float,
+    price: float,
+    contract_size: float = 1.0,
+    qty_step: float = 0.0,
+    min_qty: float = 0.0,
+    min_notional: float = 0.0,
+) -> float:
+    """Round a signed quantity down and zero it if below exchange minima."""
+
+    q = float(qty)
+    if q == 0.0:
+        return 0.0
+    sign = 1.0 if q > 0.0 else -1.0
+    abs_q = abs(q)
+    if qty_step > 0.0:
+        abs_q = np.floor((abs_q / float(qty_step)) + 1e-12) * float(qty_step)
+    if abs_q <= 0.0:
+        return 0.0
+    if min_qty > 0.0 and abs_q + 1e-12 < min_qty:
+        return 0.0
+    if min_notional > 0.0 and abs_q * float(price) * float(contract_size) + 1e-12 < min_notional:
+        return 0.0
+    return sign * abs_q
+
+
+def _instrument_map(instruments) -> Dict[str, InstrumentSpec]:
+    if instruments is None:
+        return {}
+    if isinstance(instruments, dict):
+        return {symbol: spec for symbol, spec in instruments.items() if spec is not None}
+    return {spec.symbol: spec for spec in instruments}
+
+
+def _value_for(value: NumberOrMap, symbol: str, default: float) -> float:
+    if value is None:
+        return float(default)
+    if isinstance(value, dict):
+        return float(value.get(symbol, default))
+    return float(value)