Files
momentum-system/strategy/evaluation/setup_evaluator.py
T
momentum devandClaude Opus 4.8 44ff36a669 Population gate audit: static overnight gap everywhere + full band
The 2026-07-08 audit (owner: "figure out if there is some kind of logic
or audit issue") found BOTH entry paths feeding the population gate the
WRONG gap. The fast path used the trigger book's dynamic gap (latest
price vs prev close), so intraday rallies masqueraded as gappers: TVRD
(6.0% true gap), SKIN (2.2%, filled at $0.98), JLHL (4.3%) all traded
outside the validated population. The slow path used max(gap, intraday)
with "open" taken from the first lookback-window bar, and had no upper
band at all — dead-band names SEER (38.6%) and IOTR (40.7%) entered.

Fixes: candidates carry gap_open_pct (session open vs prev close);
trigger eligibility + submit_breakout_now use it exclusively once the
session is open; _population_reject now implements the full validated
band (10-35% OR volume-verified >=150% squeeze, $1-20 price band) for
both paths; evaluator gap uses the session open; signals carry
relative_volume for squeeze verification. Plus momentum-testpg.service
so the test-isolation Postgres survives reboots.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-08 10:34:46 -04:00

231 lines
9.1 KiB
Python

"""Setup evaluator — the heart of Milestone 1.
Pure function: bars + context in, SetupEvaluationResult (ready/blocked/late) out.
No broker, DB, or UI dependencies.
"""
from __future__ import annotations
from datetime import datetime, time
import pandas as pd
from strategy.models import (
CriteriaWeights,
SetupCriteria,
SetupEvaluationResult,
)
from strategy.evaluation.criteria import build_criteria_result, score_criteria
from strategy.evaluation.levels import compute_key_levels, get_stop_levels
from strategy.evaluation.structure import SetupType, classify_setup
from strategy.evaluation.quality import calculate_setup_quality
from strategy.evaluation.first_candles import calculate_first_candle_features
from strategy.evaluation.volume_metrics import calculate_enhanced_volume_metrics
from strategy.evaluation.data_quality import calculate_data_quality_score
from strategy.risk.entry_cuts import EntryCutoffConfig, check_entry_cutoff
MIN_BARS = 10
def evaluate_setup(
bars: pd.DataFrame,
previous_close: float | None = None,
avg_daily_volume: float | None = None,
criteria: SetupCriteria | None = None,
weights: CriteriaWeights | None = None,
evaluation_time: datetime | None = None,
entry_cutoff: EntryCutoffConfig | None = None,
ready_score_pct: float = 60.0,
min_bars: int = MIN_BARS,
catalyst_score: float | None = None,
) -> SetupEvaluationResult:
"""Evaluate a symbol's session bars for a momentum setup.
Status semantics:
ready — criteria score >= ready_score_pct, valid structure, before cutoff
late — would be ready but the entry cutoff has passed
blocked — anything else (with the dominant blocking reason)
"""
criteria = criteria or SetupCriteria()
weights = weights or CriteriaWeights()
evaluation_time = evaluation_time or datetime.now()
if bars is None or bars.empty or len(bars) < min_bars:
return _blocked(
reason=f"insufficient_data ({0 if bars is None else len(bars)} bars, need {min_bars})",
evaluation_time=evaluation_time,
)
bars = bars.reset_index(drop=True)
price = float(bars["close"].iloc[-1])
# SESSION open, not the first bar of the lookback window: with a 420-min
# premarket-inclusive window the first bar is an early-premarket print, which
# skewed the "overnight gap" fed to the population gate (2026-07-08 audit).
open_price = float(bars["open"].iloc[0])
if "is_regular_hours" in bars.columns:
_rth = bars[bars["is_regular_hours"].astype(bool)]
if len(_rth):
open_price = float(_rth["open"].iloc[0])
ref_close = previous_close if previous_close and previous_close > 0 else open_price
gap_pct = (open_price - ref_close) / ref_close if ref_close > 0 else 0.0
intraday_change = (price - open_price) / open_price if open_price > 0 else 0.0
dq = calculate_data_quality_score(bars)
vol = calculate_enhanced_volume_metrics(bars, avg_daily_volume=avg_daily_volume)
relative_volume = vol.relative_volume if avg_daily_volume else max(
1.0, vol.last_bar_volume / vol.avg_bar_volume if vol.avg_bar_volume else 1.0
)
levels = compute_key_levels(bars, previous_close=previous_close)
structure = classify_setup(
bars,
premarket_high=levels.premarket_high,
session_high=levels.high_of_day,
min_quality_score=0.2,
)
first = calculate_first_candle_features(bars, premarket_high=levels.premarket_high)
above_vwap = levels.vwap is not None and price >= levels.vwap
results = [
build_criteria_result(
"sufficient_data",
dq.score >= criteria.min_quality_score,
f"quality {dq.score:.2f} (min {criteria.min_quality_score})",
),
build_criteria_result(
"gap",
gap_pct >= criteria.gap_pct_min or intraday_change >= criteria.gap_pct_min,
f"gap {gap_pct:.1%} / intraday {intraday_change:.1%} (min {criteria.gap_pct_min:.0%})",
),
build_criteria_result(
"relative_volume",
relative_volume >= criteria.relative_volume_min,
f"rvol {relative_volume:.1f} (min {criteria.relative_volume_min})",
),
build_criteria_result(
"impulse",
structure.is_valid and structure.setup_type != SetupType.NONE,
f"structure {structure.setup_type.value}: {structure.reason or 'ok'}",
),
build_criteria_result(
"pullback",
structure.setup_type
in (SetupType.FIRST_PULLBACK, SetupType.BULL_FLAG, SetupType.GAP_AND_GO,
SetupType.HOD_BREAK, SetupType.CONTINUATION_FALLBACK,
SetupType.OPENING_RANGE_BREAK)
and structure.is_valid,
"pullback/consolidation structure",
),
build_criteria_result(
"pullback_volume",
structure.quality_score >= 0.3,
f"structure quality {structure.quality_score:.2f}",
),
build_criteria_result("vwap", above_vwap, f"price vs VWAP {levels.vwap}"),
build_criteria_result(
"candle_quality",
first.opening_strength != "weak",
f"opening {first.opening_strength}",
),
build_criteria_result(
"breakout",
structure.breakout_level is not None
and price >= structure.breakout_level * 0.995,
f"price {price:.2f} vs breakout {structure.breakout_level}",
),
]
passed_n, total_n, score_pct = score_criteria(results, weights)
passed_names = [r.name for r in results if r.passed]
failed_names = [r.name for r in results if not r.passed]
quality = calculate_setup_quality(
gap_pct=max(gap_pct, intraday_change),
relative_volume=relative_volume,
structure_quality=structure.quality_score,
above_vwap=above_vwap,
opening_strength=first.opening_strength,
data_quality=dq.score,
catalyst_score=catalyst_score,
)
entry_price = structure.breakout_level or price
stop_candidates = get_stop_levels(levels, entry_price)
stop_price = structure.stop_level or (
stop_candidates[0][1] if stop_candidates else round(entry_price * 0.97, 4)
)
setups = []
if structure.is_valid and structure.setup_type != SetupType.NONE:
setups.append(
{
"setup_type": structure.setup_type.value,
"entry_price": round(float(entry_price), 4),
"stop_loss_price": round(float(stop_price), 4),
"quality_score": quality.score,
"quality_grade": quality.grade,
"confidence": round(score_pct / 100.0, 4),
# surfaced for the live VWAP + anti-chase entry gates + observability
"vwap": (round(float(levels.vwap), 4)
if levels.vwap is not None else None),
"above_vwap": bool(above_vwap),
"day_open": round(float(open_price), 4) if open_price > 0 else None,
"cum_volume": float(bars["volume"].sum()),
"relative_volume": round(float(relative_volume), 3),
# true overnight gap (open vs prev close) — input to the live POPULATION
# gate: the year-long gapper replay showed the +EV boundary is the
# population (gap>=10% + real volume), not entry timing
"gap_pct": round(float(gap_pct), 6),
}
)
base = dict(
evaluated_at=evaluation_time.isoformat(),
price=price,
gap_pct=round(gap_pct, 6),
relative_volume=round(relative_volume, 4),
criteria_passed=passed_n,
criteria_total=total_n,
success_score_pct=round(score_pct, 2),
criteria_names_passed=passed_names,
criteria_names_failed=failed_names,
criteria_detail=[
{"name": r.name, "passed": r.passed, "reason": r.reason} for r in results
],
setups=setups,
)
if score_pct < ready_score_pct or not setups:
reason = (
f"score {score_pct:.0f}% < {ready_score_pct:.0f}%"
if score_pct < ready_score_pct
else "no valid setup structure"
)
if failed_names:
reason += f" (failed: {', '.join(failed_names)})"
return SetupEvaluationResult(status="blocked", reason=reason, **base)
cutoff = check_entry_cutoff(
trigger_time=time(evaluation_time.hour, evaluation_time.minute),
cutoff_config=entry_cutoff or EntryCutoffConfig(),
)
if not cutoff.passed:
return SetupEvaluationResult(
status="late", reason=cutoff.reason or "past entry cutoff", **base
)
return SetupEvaluationResult(status="ready", reason=None, **base)
def _blocked(reason: str, evaluation_time: datetime) -> SetupEvaluationResult:
return SetupEvaluationResult(
status="blocked",
reason=reason,
evaluated_at=evaluation_time.isoformat(),
price=0.0,
gap_pct=0.0,
relative_volume=0.0,
criteria_passed=0,
criteria_total=0,
success_score_pct=0.0,
)