riskkit-quant 0.4.0__py3-none-any.whl

riskkit/session.py

@@ -0,0 +1,173 @@
+"""Session manager.
+
+Enforces the behavioural guardrails that keep a system (and its operator) out of
+trouble: daily trade/loss caps, profit-taking stops, minimum spacing between
+trades, escalating cooldowns after losing streaks, and tilt detection.
+
+Pure standard library. Feed it closed trades via :meth:`record_trade` and ask
+:meth:`can_open` before each new entry.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, time, timedelta, timezone
+from statistics import mean
+
+
+@dataclass
+class TradeRecord:
+    ts_open: datetime
+    ts_close: datetime
+    pnl: float
+    pnl_pct: float
+    score: int                  # signal-quality score for the trade (0-100)
+    position_size_units: float
+    duration_minutes: float
+    side: str
+    symbol: str
+    strategy: str
+
+
+@dataclass
+class SessionDecision:
+    allowed: bool
+    reason: str = ""
+    cooldown_until: datetime | None = None
+    on_tilt: bool = False
+
+
+class SessionManager:
+    def __init__(
+        self,
+        max_trades_per_day: int = 5,
+        max_losses_per_day: int = 3,
+        max_daily_loss_pct: float = 1.5,
+        max_daily_profit_pct: float = 5.0,
+        min_minutes_between_trades: int = 15,
+        consecutive_loss_cooldowns: dict[int, int] | None = None,
+        consecutive_loss_halt: int = 5,
+        min_score: int = 65,
+    ) -> None:
+        self.max_trades = max_trades_per_day
+        self.max_losses = max_losses_per_day
+        self.max_loss_pct = max_daily_loss_pct
+        self.max_profit_pct = max_daily_profit_pct
+        self.min_minutes_between = min_minutes_between_trades
+        # consecutive-loss count -> cooldown minutes
+        self.cooldowns = consecutive_loss_cooldowns or {2: 30, 3: 120, 4: 1440}
+        self.cl_halt = consecutive_loss_halt
+        self.min_score = min_score
+
+        self.day_pnl: float = 0.0
+        self.day_pnl_pct: float = 0.0
+        self.day_trades: int = 0
+        self.day_losses: int = 0
+        self.day_anchor: datetime | None = None
+        self.consecutive_losses: int = 0
+        self.cooldown_until: datetime | None = None
+        self.strategy_halts: dict[str, datetime] = {}
+        self.last_trade_ts: datetime | None = None
+        self.recent_trades: list[TradeRecord] = []
+
+    # ----------------------------------------------------------------- day roll
+
+    def _roll_day(self, now: datetime) -> None:
+        if self.day_anchor is None or now.date() != self.day_anchor.date():
+            self.day_anchor = datetime.combine(now.date(), time(0, 0, tzinfo=timezone.utc))
+            self.day_pnl = 0.0
+            self.day_pnl_pct = 0.0
+            self.day_trades = 0
+            self.day_losses = 0
+
+    # ----------------------------------------------------------------- record
+
+    def record_trade(self, trade: TradeRecord, equity_before: float) -> None:
+        self._roll_day(trade.ts_close)
+        self.day_pnl += trade.pnl
+        self.day_pnl_pct = (self.day_pnl / equity_before * 100.0) if equity_before else 0.0
+        self.day_trades += 1
+        self.last_trade_ts = trade.ts_close
+        if trade.pnl < 0:
+            self.day_losses += 1
+            self.consecutive_losses += 1
+            mins = self.cooldowns.get(self.consecutive_losses)
+            if mins:
+                self.cooldown_until = trade.ts_close + timedelta(minutes=mins)
+            if self.consecutive_losses >= self.cl_halt:
+                self.strategy_halts[trade.strategy] = trade.ts_close + timedelta(hours=24)
+        else:
+            self.consecutive_losses = 0
+            self.cooldown_until = None
+        self.recent_trades.append(trade)
+        if len(self.recent_trades) > 50:
+            self.recent_trades = self.recent_trades[-50:]
+
+    # ----------------------------------------------------------------- can_open
+
+    def can_open(
+        self,
+        strategy: str,
+        now: datetime | None = None,
+        score: int = 100,
+    ) -> SessionDecision:
+        now = now or datetime.now(timezone.utc)
+        self._roll_day(now)
+
+        if self.day_trades >= self.max_trades:
+            return SessionDecision(False, "daily trade cap reached")
+        if self.day_losses >= self.max_losses:
+            return SessionDecision(False, "daily loss-count cap reached")
+        if self.day_pnl_pct <= -self.max_loss_pct:
+            return SessionDecision(False, f"daily loss limit {self.max_loss_pct}% reached")
+        if self.day_pnl_pct >= self.max_profit_pct:
+            return SessionDecision(False, f"daily profit limit {self.max_profit_pct}% reached")
+        if self.cooldown_until and now < self.cooldown_until:
+            return SessionDecision(False, "consecutive-loss cooldown", cooldown_until=self.cooldown_until)
+        if self.last_trade_ts and (now - self.last_trade_ts).total_seconds() < self.min_minutes_between * 60:
+            return SessionDecision(False, "min-time-between-trades not elapsed")
+        halt_until = self.strategy_halts.get(strategy)
+        if halt_until and now < halt_until:
+            return SessionDecision(False, f"strategy '{strategy}' halted until {halt_until.isoformat()}")
+        if self.detect_tilt(score):
+            return SessionDecision(False, "tilt detected", on_tilt=True, cooldown_until=now + timedelta(hours=4))
+        return SessionDecision(True)
+
+    # ----------------------------------------------------------------- tilt
+
+    def detect_tilt(self, latest_score: int = 100) -> bool:
+        """Flag tilt if recent behaviour matches any of these patterns over the
+        last 5 trades:
+
+        - average hold time shrank > 50% vs the prior 20-trade baseline
+        - position size increased right after a loss
+        - any two trades were spaced less than 5 minutes apart
+        - any recent trade was taken on a weak (< ``min_score``) signal
+        """
+        if len(self.recent_trades) < 5:
+            return False
+        last5 = self.recent_trades[-5:]
+        baseline = self.recent_trades[-25:-5] if len(self.recent_trades) >= 25 else self.recent_trades
+        baseline_hold = mean(t.duration_minutes for t in baseline) if baseline else 0
+        last5_hold = mean(t.duration_minutes for t in last5)
+        if baseline_hold > 0 and last5_hold < 0.5 * baseline_hold:
+            return True
+
+        sizes = [t.position_size_units for t in last5]
+        for i in range(1, len(sizes)):
+            if last5[i - 1].pnl < 0 and sizes[i] > sizes[i - 1] * 1.1:
+                return True
+
+        gaps = [
+            (last5[i].ts_open - last5[i - 1].ts_close).total_seconds()
+            for i in range(1, len(last5))
+        ]
+        if gaps and min(gaps) < 5 * 60:
+            return True
+
+        if any(t.score < self.min_score for t in last5):
+            return True
+
+        if latest_score and latest_score < self.min_score:
+            return True
+
+        return False

riskkit/sizing.py

@@ -0,0 +1,263 @@
+"""Position sizing.
+
+Volatility-adjusted fixed-fractional sizing with an optional Kelly ceiling and
+a reduction ladder that cuts size after losing streaks and during drawdowns.
+
+The core idea: you decide how much *risk* (distance to your stop) you are
+willing to put on per trade, expressed as a fraction of equity. From that, the
+number of units follows directly. Everything else — volatility scaling, the
+Kelly cap, the reduction ladder, the high-conviction bonus — only ever moves
+that risk fraction up or down within hard floors and ceilings.
+
+The notional cap is absolute: a position's notional can never exceed
+``max_notional_pct`` of equity, regardless of what the risk math produces.
+
+Alongside the class, this module offers three small, composable sizing helpers
+you can reach for on their own: :func:`kelly_fraction` (the edge-optimal risk
+fraction), :func:`volatility_target_size` (size a position to a target
+volatility), and :func:`inverse_vol_weights` (naive risk-parity weights across a
+basket). Each is a pure function with no dependencies.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping
+
+
+@dataclass
+class SizingInputs:
+    """Everything the sizer needs to size a single trade.
+
+    Prices are in quote currency; ``atr`` is the current Average True Range and
+    ``atr_baseline`` is a longer-run ATR used to scale risk down when the market
+    is more volatile than usual. ``drawdown_pct`` and ``daily_loss_pct`` are
+    positive numbers (e.g. ``4.2`` means down 4.2%).
+
+    The Kelly inputs (``win_rate``, ``avg_win``, ``avg_loss``) are optional. When
+    all three are supplied the sizer applies a half-Kelly ceiling.
+    """
+
+    equity: float
+    entry_price: float
+    stop_price: float
+    atr: float
+    atr_baseline: float
+    confluence_score: int = 100
+    consecutive_losses: int = 0
+    drawdown_pct: float = 0.0
+    daily_loss_pct: float = 0.0
+    win_rate: float | None = None
+    avg_win: float | None = None
+    avg_loss: float | None = None
+
+
+@dataclass
+class SizingResult:
+    """The sized position.
+
+    ``units`` is the position size in base units (0 means *do not trade*).
+    ``multipliers_applied`` records every adjustment that fired, so the decision
+    is fully auditable. When ``units`` is 0, ``reason_for_zero`` explains why.
+    """
+
+    units: float
+    notional: float
+    risk_amount: float
+    risk_pct: float
+    multipliers_applied: dict[str, float] = field(default_factory=dict)
+    reason_for_zero: str | None = None
+
+
+class PositionSizer:
+    """Volatility-adjusted fixed-fractional position sizer.
+
+    All percentage arguments are given as human percentages (``1.0`` == 1%) and
+    stored internally as fractions.
+    """
+
+    def __init__(
+        self,
+        base_risk_pct: float = 1.0,
+        max_risk_pct: float = 1.5,
+        min_risk_pct: float = 0.25,
+        max_notional_pct: float = 4.0,
+        high_conviction_score: int = 85,
+        high_conviction_size_mult: float = 1.5,
+    ) -> None:
+        self.base_risk = base_risk_pct / 100.0
+        self.max_risk = max_risk_pct / 100.0
+        self.min_risk = min_risk_pct / 100.0
+        self.max_notional = max_notional_pct / 100.0
+        self.high_conviction = high_conviction_score
+        self.hc_size_mult = high_conviction_size_mult
+
+    # ------------------------------------------------------------------ helpers
+
+    def _reduction_multiplier(self, inputs: SizingInputs) -> tuple[float, dict[str, float]]:
+        """Combine every size adjustment into a single multiplier (audited)."""
+        applied: dict[str, float] = {}
+        m = 1.0
+
+        if inputs.consecutive_losses >= 3:
+            applied["consecutive_losses>=3"] = 0.5
+            m *= 0.5
+        elif inputs.consecutive_losses == 2:
+            applied["consecutive_losses==2"] = 0.75
+            m *= 0.75
+
+        dd = inputs.drawdown_pct
+        if dd > 7:
+            applied["drawdown>7"] = 0.25
+            m *= 0.25
+        elif dd > 5:
+            applied["drawdown>5"] = 0.5
+            m *= 0.5
+        elif dd > 3:
+            applied["drawdown>3"] = 0.75
+            m *= 0.75
+
+        if inputs.daily_loss_pct > 1.0:
+            applied["daily_loss>1"] = 0.5
+            m *= 0.5
+
+        if 70 <= inputs.confluence_score < 75:
+            applied["confluence_70_74"] = 0.75
+            m *= 0.75
+
+        if inputs.confluence_score >= self.high_conviction:
+            applied["high_conviction"] = self.hc_size_mult
+            m *= self.hc_size_mult
+
+        return m, applied
+
+    # ------------------------------------------------------------------ public
+
+    def size(self, inputs: SizingInputs) -> SizingResult:
+        """Size one trade. Returns a :class:`SizingResult`; ``units == 0`` means skip."""
+        risk_per_unit = abs(inputs.entry_price - inputs.stop_price)
+        if risk_per_unit <= 0 or inputs.equity <= 0:
+            return SizingResult(0, 0, 0, 0, reason_for_zero="zero-distance stop or equity")
+
+        # Volatility scaling: more vol than baseline -> smaller risk fraction.
+        ratio = (inputs.atr / inputs.atr_baseline) if inputs.atr_baseline > 0 else 1.0
+        ratio = max(0.2, min(5.0, ratio))
+        vol_adjusted_risk = self.base_risk / ratio
+
+        # Kelly ceiling (only if we have all three stats). A non-positive Kelly
+        # fraction means no historical edge -> risk clamps toward 0 and the
+        # min-risk floor below skips the trade.
+        if (
+            inputs.win_rate is not None
+            and inputs.avg_win is not None
+            and inputs.avg_loss is not None
+        ):
+            kelly = kelly_fraction(
+                inputs.win_rate, inputs.avg_win, inputs.avg_loss, fraction=0.5
+            )
+            vol_adjusted_risk = min(vol_adjusted_risk, kelly)
+
+        # Reduction ladder + ceiling.
+        red_mult, applied = self._reduction_multiplier(inputs)
+        risk_pct = vol_adjusted_risk * red_mult
+        risk_pct = max(0.0, min(self.max_risk, risk_pct))
+
+        if risk_pct < self.min_risk:
+            return SizingResult(
+                0, 0, 0, risk_pct, applied,
+                reason_for_zero=f"risk {risk_pct * 100:.3f}% below floor",
+            )
+
+        risk_amount = inputs.equity * risk_pct
+        units = risk_amount / risk_per_unit
+
+        # Absolute notional cap.
+        max_units_by_notional = (inputs.equity * self.max_notional) / inputs.entry_price
+        if units > max_units_by_notional:
+            applied["notional_cap"] = max_units_by_notional / units
+            units = max_units_by_notional
+            # The cap bound the size, so realized risk is now below target —
+            # keep risk_pct consistent with risk_amount (risk_amount / equity).
+            risk_pct = (units * risk_per_unit) / inputs.equity
+
+        return SizingResult(
+            units=units,
+            notional=units * inputs.entry_price,
+            risk_amount=units * risk_per_unit,
+            risk_pct=risk_pct,
+            multipliers_applied=applied,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Standalone, composable sizers — pure functions, no dependencies. Use them on
+# their own when the stop-distance model of PositionSizer is not what you want.
+# ---------------------------------------------------------------------------
+
+
+def kelly_fraction(
+    win_rate: float,
+    avg_win: float,
+    avg_loss: float,
+    fraction: float = 1.0,
+) -> float:
+    """The Kelly-optimal fraction of capital to risk, given a historical edge.
+
+    ``win_rate`` is the win probability (0–1); ``avg_win`` and ``avg_loss`` are the
+    mean win and mean loss as positive magnitudes in the same unit (e.g. R, or
+    currency). Returns ``kelly · fraction`` clamped at 0 — a non-positive edge
+    sizes to nothing. Pass ``fraction=0.5`` for the common, less-aggressive
+    half-Kelly. Returns 0 for degenerate inputs (any of the three ≤ 0).
+
+        kelly = win_rate − (1 − win_rate) / (avg_win / avg_loss)
+    """
+    if win_rate <= 0 or avg_win <= 0 or avg_loss <= 0:
+        return 0.0
+    payoff = avg_win / avg_loss
+    kelly = win_rate - ((1.0 - win_rate) / payoff)
+    return max(0.0, kelly * fraction)
+
+
+def volatility_target_size(
+    equity: float,
+    price: float,
+    return_volatility: float,
+    target_volatility_pct: float,
+    max_notional_pct: float = 100.0,
+) -> float:
+    """Units sized so a position's expected volatility ≈ a target % of equity.
+
+    Volatility targeting sizes off an instrument's *return volatility* rather than
+    a stop distance: a calmer instrument earns a larger position and a wilder one
+    a smaller position, so each contributes a similar amount of risk. Supply the
+    per-period return volatility as a fraction (``0.02`` == 2% σ of returns) and
+    the volatility you want the position to carry, as a % of equity.
+
+        units = (target_volatility_pct/100 · equity) / (return_volatility · price)
+
+    The result is capped so notional never exceeds ``max_notional_pct`` of equity.
+    Returns 0 for degenerate inputs (non-positive equity, price, volatility, or
+    target).
+    """
+    if (equity <= 0 or price <= 0 or return_volatility <= 0
+            or target_volatility_pct <= 0):
+        return 0.0
+    target_dollar_vol = (target_volatility_pct / 100.0) * equity
+    per_unit_vol = return_volatility * price
+    units = target_dollar_vol / per_unit_vol
+    max_units = (max_notional_pct / 100.0) * equity / price
+    return min(units, max_units)
+
+
+def inverse_vol_weights(volatilities: Mapping[str, float]) -> dict[str, float]:
+    """Risk-parity weights inversely proportional to each asset's volatility.
+
+    The simplest form of risk parity: ignoring correlations, weighting each asset
+    by 1/σ makes every position contribute the same risk. Returns weights that sum
+    to 1.0. Assets with non-positive volatility are dropped; an empty or all-zero
+    input returns ``{}``.
+    """
+    inv = {k: 1.0 / v for k, v in volatilities.items() if v > 0}
+    total = sum(inv.values())
+    if total <= 0:
+        return {}
+    return {k: w / total for k, w in inv.items()}

riskkit/stops.py

@@ -0,0 +1,228 @@
+"""Stop engine.
+
+Every open position carries a *stack* of stops at once; the tightest one
+relative to current price is active. Stops only ever move closer to price,
+never further away.
+
+Stop types in the stack:
+    initial          set at entry, never widens
+    breakeven        activated at 1R profit (with a fee buffer)
+    trailing_atr     activated at ``trailing_start_at_r``, trails N*ATR behind price
+    trailing_ema     optional, trails a slow EMA (useful for trend trades)
+    chandelier       optional, trails N*ATR from the highest high / lowest low since entry
+    structure        optional, ratchets to a swing level you supply (tighten-only)
+    psar             optional, ratchets to a Parabolic SAR value you supply (tighten-only)
+    time             exit after N bars if the trade hasn't reached 1R
+    volatility       exit if ATR spikes past ``volatility_exit_threshold`` x baseline
+    rsi              for mean-reversion: exit if a momentum signal re-extremes
+
+The chandelier, structure, and psar stops follow riskkit's "you feed it numbers"
+rule: structure and psar simply trail to the level you pass in each bar, and the
+chandelier anchors to the running high/low the engine tracks for you. All three
+are tighten-only, like every other stop here.
+
+The engine is pure arithmetic — it takes prices and indicator values you supply
+and returns an exit reason (or ``None``). It never talks to an exchange.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+Side = Literal["long", "short"]
+
+
+@dataclass
+class StopStack:
+    """Per-position stop state. Create one at entry, then feed it to
+    :meth:`StopEngine.update` once per bar."""
+
+    side: Side
+    entry_price: float
+    initial: float
+    breakeven: float | None = None
+    trailing_atr: float | None = None
+    trailing_ema: float | None = None
+    chandelier: float | None = None
+    structure: float | None = None
+    psar: float | None = None
+    time_stop_bars: int | None = None
+    rsi_stop: bool = False
+    use_chandelier: bool = False
+    volatility_baseline: float | None = None
+    volatility_threshold: float = 2.0
+    bars_held: int = 0
+    realized_r: float = 0.0
+    # Running extremes since entry, maintained for the chandelier stop.
+    highest_since_entry: float | None = None
+    lowest_since_entry: float | None = None
+    history: list[tuple[str, float, str]] = field(default_factory=list)
+
+    @property
+    def initial_risk(self) -> float:
+        return abs(self.entry_price - self.initial)
+
+    def active_stop(self) -> float:
+        """The tightest (closest-to-price) stop currently in the stack."""
+        candidates = [self.initial]
+        for level in (self.breakeven, self.trailing_atr, self.trailing_ema,
+                      self.chandelier, self.structure, self.psar):
+            if level is not None:
+                candidates.append(level)
+        return max(candidates) if self.side == "long" else min(candidates)
+
+
+class StopEngine:
+    """Advances stop stacks each bar and signals exits."""
+
+    def __init__(
+        self,
+        breakeven_at_r: float = 1.0,
+        trailing_start_at_r: float = 1.5,
+        trailing_atr_multiplier: float = 1.5,
+        volatility_exit_threshold: float = 2.0,
+        fees_round_trip_pct: float = 0.001,
+        chandelier_atr_multiplier: float = 3.0,
+    ) -> None:
+        self.breakeven_at_r = breakeven_at_r
+        self.trailing_start_r = trailing_start_at_r
+        self.trailing_atr_mult = trailing_atr_multiplier
+        self.vol_exit_th = volatility_exit_threshold
+        self.fees_rt = fees_round_trip_pct
+        self.chandelier_atr_mult = chandelier_atr_multiplier
+
+    @staticmethod
+    def _r_multiple(stack: StopStack, price: float) -> float:
+        if stack.initial_risk <= 0:
+            return 0.0
+        delta = (
+            (price - stack.entry_price)
+            if stack.side == "long"
+            else (stack.entry_price - price)
+        )
+        return delta / stack.initial_risk
+
+    def update(
+        self,
+        stack: StopStack,
+        current_price: float,
+        current_atr: float,
+        current_ema_slow: float | None = None,
+        rsi_at_extreme_again: bool = False,
+        current_high: float | None = None,
+        current_low: float | None = None,
+        structure_level: float | None = None,
+        psar_value: float | None = None,
+    ) -> tuple[StopStack, str | None]:
+        """Advance the stack one bar. Returns ``(stack, exit_reason)``;
+        ``exit_reason`` is ``None`` unless an exit fired.
+
+        ``current_high`` / ``current_low`` feed the chandelier stop's running
+        extreme (they default to ``current_price`` if you only have closes).
+        ``structure_level`` and ``psar_value`` activate the structure and PSAR
+        stops when supplied — each ratchets toward the level, tighten-only."""
+        stack.bars_held += 1
+        r_now = self._r_multiple(stack, current_price)
+        stack.realized_r = max(stack.realized_r, r_now)
+
+        # Volatility spike -> bail.
+        if stack.volatility_baseline and current_atr > self.vol_exit_th * stack.volatility_baseline:
+            return stack, f"volatility spike ({current_atr / stack.volatility_baseline:.2f}x baseline)"
+
+        # Momentum re-extreme (mean reversion only).
+        if stack.rsi_stop and rsi_at_extreme_again:
+            return stack, "momentum returned to extreme"
+
+        # Time stop: hasn't reached 1R within the bar limit.
+        if (
+            stack.time_stop_bars is not None
+            and stack.bars_held >= stack.time_stop_bars
+            and stack.realized_r < 1.0
+        ):
+            return stack, f"time stop after {stack.bars_held} bars without 1R"
+
+        # Breakeven at 1R (parked just past entry to clear fees).
+        if stack.breakeven is None and r_now >= self.breakeven_at_r:
+            fees_buffer = stack.entry_price * self.fees_rt
+            be = stack.entry_price + (fees_buffer if stack.side == "long" else -fees_buffer)
+            stack.breakeven = be
+            stack.history.append(("breakeven_activated", be, "1R reached"))
+
+        # Trailing ATR stop (tighten-only).
+        if r_now >= self.trailing_start_r:
+            new_trail = (
+                current_price - self.trailing_atr_mult * current_atr
+                if stack.side == "long"
+                else current_price + self.trailing_atr_mult * current_atr
+            )
+            if stack.trailing_atr is None:
+                stack.trailing_atr = new_trail
+                stack.history.append(("trail_atr_activated", new_trail, f"{self.trailing_start_r}R reached"))
+            elif (stack.side == "long" and new_trail > stack.trailing_atr) or (
+                stack.side == "short" and new_trail < stack.trailing_atr
+            ):
+                stack.trailing_atr = new_trail
+                stack.history.append(("trail_atr_tightened", new_trail, "trail"))
+
+        # Trailing EMA stop (tighten-only), for trend trades.
+        if current_ema_slow is not None and r_now >= self.trailing_start_r:
+            if stack.trailing_ema is None:
+                stack.trailing_ema = current_ema_slow
+                stack.history.append(("trail_ema_activated", current_ema_slow, ""))
+            elif (stack.side == "long" and current_ema_slow > stack.trailing_ema) or (
+                stack.side == "short" and current_ema_slow < stack.trailing_ema
+            ):
+                stack.trailing_ema = current_ema_slow
+
+        # Chandelier stop (tighten-only): trail ATR from the highest high (long) /
+        # lowest low (short) *since entry*, not from the current bar.
+        if stack.use_chandelier:
+            high = current_high if current_high is not None else current_price
+            low = current_low if current_low is not None else current_price
+            if stack.side == "long":
+                stack.highest_since_entry = (
+                    high if stack.highest_since_entry is None
+                    else max(stack.highest_since_entry, high)
+                )
+                level = stack.highest_since_entry - self.chandelier_atr_mult * current_atr
+                if stack.chandelier is None or level > stack.chandelier:
+                    stack.chandelier = level
+                    stack.history.append(("chandelier", level, "trail"))
+            else:
+                stack.lowest_since_entry = (
+                    low if stack.lowest_since_entry is None
+                    else min(stack.lowest_since_entry, low)
+                )
+                level = stack.lowest_since_entry + self.chandelier_atr_mult * current_atr
+                if stack.chandelier is None or level < stack.chandelier:
+                    stack.chandelier = level
+                    stack.history.append(("chandelier", level, "trail"))
+
+        # Structure stop (tighten-only): ratchet to a swing level you supply —
+        # a swing low for longs, a swing high for shorts. Never loosens.
+        if structure_level is not None:
+            if stack.structure is None or (
+                (stack.side == "long" and structure_level > stack.structure)
+                or (stack.side == "short" and structure_level < stack.structure)
+            ):
+                stack.structure = structure_level
+                stack.history.append(("structure", structure_level, "swing"))
+
+        # Parabolic SAR stop (tighten-only): ratchet to a PSAR value you supply.
+        # When PSAR flips past price it tightens onto it and triggers the exit.
+        if psar_value is not None:
+            if stack.psar is None or (
+                (stack.side == "long" and psar_value > stack.psar)
+                or (stack.side == "short" and psar_value < stack.psar)
+            ):
+                stack.psar = psar_value
+                stack.history.append(("psar", psar_value, ""))
+
+        # Stopped out?
+        active = stack.active_stop()
+        if stack.side == "long" and current_price <= active:
+            return stack, f"stopped out at {active:.4f}"
+        if stack.side == "short" and current_price >= active:
+            return stack, f"stopped out at {active:.4f}"
+
+        return stack, None