SPY Macro-Regime Options Agent

The SPY Macro-Regime Options Agent is an autonomous quantitative trading system built for the Alpaca Hackathon 2026. The agent leverages a machine learning classification ensemble to determine macro market regimes, dynamically shifting portfolio exposure between SPY Call and Put options. Execution is fully automated through the Alpaca Python SDK and CLI toolchain, governed by strict risk management rules and portfolio state alignment logic. The system utilizes a decoupled two-stage pipeline architecture: 1. Signal Generation Engine (live_signal.py): Ingests daily market data, calculates feature transformers, and evaluates the ML model to output regime stance to a centralized bridge file. 2. Execution & State Engine (alpaca_agent.py): Inspects active portfolio holdings via the Alpaca Trading API, resolves cold-start state discrepancies, and executes market orders. Key Strategy & Risk Parameters: - Signals: 1 (Risk-On / Bullish Calls) | 0 (Risk-Off / Bearish Puts) - Contract Selection: Scans active At-The-Money (ATM) SPY options strictly within a 7–14 Days To Expiration (DTE) window to optimize directional delta while minimizing theta decay. - Risk Engine: Dynamic position sizing capped at 3% of total equity ($3,000 maximum allocation on a $100,000 account). - Order Sequencing: Enforces position liquidation prior to opening new stances to eliminate double exposure or leverage spikes. - CLI Integration: Wraps Alpaca CLI commands via Python subprocess during execution to satisfy CLI platform logging standards.