executor.py

"""Stage 3: risk-based position sizing.

Size is derived from risk, not from capital: the distance to the stop decides
how many shares a fixed dollar risk buys. A wide stop therefore produces a
small position and a tight stop a large one, so every open trade carries the
same expected loss if it fails.
"""

from typing import Optional

from config import (
    ACCOUNT_EQUITY,
    MAX_STOP_ATR_MULTIPLE,
    RISK_PER_TRADE,
)


def execute_signal(signal: Optional[dict]) -> Optional[dict]:
    """Turn a signal into a sized position, or None if it fails risk checks."""
    if signal is None:
        return None

    entry = signal["entry_price"]
    stop = signal["stop_price"]
    atr = signal["atr"]

    stop_distance = entry - stop
    if stop_distance <= 0:
        return None

    # A stop wider than one ATR means the setup is not tight enough to size
    # sensibly -- the position would be too small to matter, or the risk too
    # large to justify.
    max_stop = MAX_STOP_ATR_MULTIPLE * atr
    if stop_distance > max_stop:
        print(
            f"Trade skipped ({signal['ticker']}): stop distance "
            f"{stop_distance:.2f} exceeds {MAX_STOP_ATR_MULTIPLE:g}x ATR {atr:.2f}"
        )
        return None

    risk_budget = ACCOUNT_EQUITY * RISK_PER_TRADE
    shares = int(risk_budget / stop_distance)  # round down; never over-risk
    if shares <= 0:
        return None

    return {
        "ticker": signal["ticker"],
        "shares": shares,
        "entry_price": round(entry, 2),
        "stop_price": round(stop, 2),
        "total_cost": round(shares * entry, 2),
        "risk_amount": round(shares * stop_distance, 2),
    }