Skip to content

Automated Screening (Go Hunting)

The go_hunting.py script scans for trading opportunities and saves passing recommendations to Supabase. It runs automatically via GitHub Actions and can also be run manually.

Schedule

The automated job runs daily at 16:00 Zurich time (15:00 UTC during CET; 17:00 Zurich during CEST). The workflow is defined in .github/workflows/go_hunting.yml and can also be triggered manually via workflow_dispatch.

Strategies

The job runs two screener strategies on symbols from the earnings calendar (tickers with earnings between tomorrow and 8 days out):

1. Forward Factor

Purpose: Screens for favorable forward volatility conditions without requiring earnings dates.

The Forward Factor (FF) measures how much near-term implied volatility exceeds the forward-implied volatility between two expirations. It uses the forward variance identity:

\[\sigma_{fwd} = \sqrt{\frac{\sigma_2^2 T_2 - \sigma_1^2 T_1}{T_2 - T_1}}\]
\[FF = \frac{\sigma_1 - \sigma_{fwd}}{\sigma_{fwd}}\]

Where \(\sigma_1\) is front-month IV, \(\sigma_2\) is back-month IV, and \(T\) is time to expiration in years. A positive FF indicates near-term options are relatively expensive compared to forward volatility—a potential opportunity for volatility-selling strategies.

Key characteristics:

  • Does not cross earnings dates (no earnings-specific timing)
  • Uses ATM implied volatility from front and back expirations
  • Quality thresholds (minimum FF score) are configurable via the Supabase quality_metrics table
  • Saves to recommendations with forward_factor, stock_price, current_underlying_price

2. Sell Earnings Volatility (SEV)

Purpose: Screens for calendar spread opportunities around earnings events.

This strategy identifies stocks where options are overpriced relative to historical volatility (high IV/RV ratio) and the term structure slopes downward (near-term IV > far-term IV). It validates that the front-month expiration is after the earnings date and saves full calendar spread details including entry/exit times.

Key characteristics:

  • Requires earnings dates (crosses earnings)
  • Uses IV/RV ratio, term structure slope, volume, and price thresholds
  • Saves to recommendations and recommended_positions with calendar spread legs, earnings date, open/exit times

CLI Usage

# Run both strategies (default when --with-earnings is passed)
uv run scripts/go_hunting.py --with-earnings

# Run only strategies that do not cross earnings dates (Forward Factor only)
uv run scripts/go_hunting.py

# Run a specific strategy
uv run scripts/go_hunting.py --strategy forward_factor
uv run scripts/go_hunting.py --strategy sell_earnings_volatility --with-earnings

Quality Metrics

Both strategies use the Supabase quality_metrics table to enforce minimum acceptable scores. Configure rows with:

  • strategy: Strategy name ("Forward Factor" or "Sell Earnings Volatility")
  • recommendation_value_column: Column to check (e.g. forward_factor, iv30_rv30_ratio)
  • values: Threshold values
  • direction: >= 0 for "higher is better", < 0 for "lower is better"

If no quality metrics exist for a strategy, all symbols with valid analysis pass (vacuous pass).

Data Flow

  1. Symbol source: Queries earnings_calendar for tickers with earnings between tomorrow and 8 days out
  2. Analysis: Each strategy runs analyze(symbol) and passes(result, quality_metrics)
  3. Save: Passing symbols are upserted to tickers, inserted into recommendations, and (for SEV) recommended_positions

Requirements

  • Supabase credentials in .env: SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_USERNAME, SUPABASE_PASSWORD
  • earnings_calendar table populated with upcoming earnings
  • quality_metrics table configured for desired thresholds (optional but recommended)