o êjj7@sdZddlmZmZmZddlmZddlmZddlm Z ddl Z ddl Z edZ d+d d Z d ed efddZdeded efddZded efddZdedededefddZdedededededededed efdd Z ! d,d"ed#ed$ed%ed&ed'ed(ed efd)d*ZdS)-a/ breakout_scanner.py [FEATURE 2026-09-16] Shadow/comparison scanner implementing the "breakout_bot" candidate-scoring model from docs/breakout_bot_design_conversation.pdf (Part II, sections 2-4) -- run ALONGSIDE sip_bot's own premarket_scanner.py every morning, writing its own separate ranked candidate list to data/breakout_scanner/ so the two scoring philosophies can be compared side by side on the exact same universe and the exact same morning, without either one affecting the other. Deliberately scoped to ONLY the scanner piece: the PDF's full breakout_bot design also calls for a 1-min-bar / 5-min-rolling-window state machine (WATCH -> BUILDING -> PRE_BREAKOUT -> BREAKOUT -> CONFIRMED) driven by live streaming data (stream.py / entry.py / exit.py in the PDF's blueprint) -- none of that exists here, and this module never runs on sip_bot's 30-minute intraday-rescan cadence. monitor.py calls this exactly once, right after its own 9:29 premarket scan, wrapped in a try/except there so a bug in this module can never delay or crash the live trading pipeline. Universe-building (get_universe_symbols / prefilter_by_snapshot / compute_volatility_baseline, all in premarket_scanner.py) is REUSED rather than reimplemented -- per explicit instruction, this keeps both scanners working from the identical symbol pool so any quality difference in the resulting candidate lists reflects the SCORING model, not a universe-filtering discrepancy between two independently written implementations. The PDF's own universe filters (price $5-$15, avg daily volume >=500k, OTC/ETF/leveraged exclusion, max-5-syllable names -- Part II section 2) are already identical to sip_bot's. CANDIDATE SCORE weighting is the PDF's own (Part II section 3): 30% relative volume, 20% premarket volume, 20% gap/price movement, 15% premarket price strength, 15% distance to important resistance. The PDF's own last line says "the next engineering step is to define every calculation mathematically" -- that was never finished before design work stopped, so the exact formulas for premarket_price_strength and distance_to_resistance below are this module's own concrete interpretation (decided 2026-09-16, see that day's conversation), not a literal transcription from the PDF. See each helper's docstring for the specific reasoning. Also deliberately different from sip_bot's own scorer.py: NO hard reject gates beyond universe membership and a minimum-bars data-availability check. sip_bot's premarket_scanner.scan() hard-rejects on meets_min_volume/meets_min_rvol/meets_min_volatility/spread_ok; this scanner's whole premise (per the PDF: candidate_score "answers 'which stocks deserve our attention today' rather than 'which stock will go up'") is a purely continuous, non-gating score -- every prefiltered symbol with enough bars gets ranked, top N taken. This is an intentional point of comparison against sip_bot's hard-gated approach, not an oversight -- see 2026-09-16's RVOL-starvation incident (sip_bot selected ZERO candidates on a thin premarket morning) for exactly the failure mode a purely continuous score never has. )datetime timedeltatimezone) get_config) get_logger)relative_volumeNbreakout_scanner?cCst|t||S)N)maxmin)xlohirbreakout_scanner.py_clampEsrsymbolsreturnc Cstd}|dd}ttj}|t|ddd}||||}i}|D]\}} | dd} | s6q)t d d | D||<q)|S) a {symbol: 20-day high} -- one bulk multi-symbol daily-bars call, same endpoint/chunking pattern as premarket_scanner.compute_volatility_ baseline(). Feeds the distance-to-resistance sub-score's third priority level (premarket high -> previous-day high -> 20-day high, per the PDF's resistance priority order, Part I page 16 / Part II section 10). A symbol absent from the result (too new, delisted, or the request failed) is simply missing -- _distance_to_resistance_pct() treats a missing level the same as it treats one that's below current price: just skip to the next priority level, never reject the symbol. universevolatility_lookback_days )daysiNcs|]}|dVqdShNr.0brrr bz)compute_range_20d_high..) rgetrnowrutcrget_daily_bars_bulkitemsr ) clientrcfg lookback_daysr$start daily_barsoutsymbolbarsrrrcompute_range_20d_highIs    r0price prev_closecCs|sdS|||dS)z(premarket_last_price - prev_close) / prev_close -- the exact formula from the original design conversation's own feature table (Part I page 6).r Y@r)r1r2rrr_gap_pctfsr4r/cCst|}|dkr dStd|d}|d|}|| d}tdd|Dt|}tdd|Dt|}|s late-segment avg), NOT yet normalized to a 0-1 sub-score -- see score_breakout_candidate's price_strength_full_credit_pct for that. r NcsrcNrrrrrr!r"z,_premarket_price_strength..csrr7rrrrrr!r"r3)lenr sum)r/nthirdearlylate early_avglate_avgrrr_premarket_price_strengthos rApm_high prev_day_highrange_20d_highcCs8|||fD]}|r||kr|||d|fSqdS)a Nearest overhead level still ABOVE current price, checked in the PDF's own explicit priority order (premarket high -> previous-day high -> 20-day high). Returns (distance_pct, level_used) -- distance_pct is None if price has already cleared every known level ("clear air"): a breakout already in progress shouldn't be penalized for having no ceiling left to measure against, so that case is full credit at the call site rather than a zero/undefined distance. More room below the nearest ceiling scores BETTER here, not worse -- sitting right at a resistance level is the risky spot, not the strong one. This mirrors sip_bot's own 2026-09-15 correction of the identical mistake in its old distance_from_pm_high scoring (see scorer.py's _note there), reached independently here rather than by importing that fix, per this module's "different scoring implementation, shared universe only" design split. r3)NNr)r1rBrCrDlevelrrr_distance_to_resistance_pcts  rFr.pm_lowavg_vol_baselinecCstd}|d} dd|D} dd|D} | d} t| } t| |}t| |}t|}t| |||\}}| dt||d| d t| |d | d t||d d d| dt||dd dd}|durt| d|d<n| dt||d|d<t|}t| }|rt||dddnd}|t|ddd| D| |t|d| |t|d||||t|d|durt|dnd|d dS)aN bars: 1-min premarket bars, oldest first, each {"t","o","h","l","c","v"} Returns {"symbol", "candidate_score", "breakdown", "metrics"} -- see module docstring for the weighting and "no hard gates" philosophy. candidate_score is 0-100, same scale as sip_bot's total_score, for direct side-by-side comparison. rweightscSg|]}|dqS)r8rrrrr z,score_breakout_candidate..cSrJ)vrrrrrrKrLrrvol_full_credit_multiplepremarket_volumepremarket_volume_full_creditgap_or_price_movementgap_full_credit_pctgr premarket_price_strengthprice_strength_full_credit_pct)rrPrRrTNdistance_to_resistance#resistance_full_credit_distance_pctr3rdr rcSsi|] \}}|t|dqS)r)round)rkrMrrr sz,score_breakout_candidate..) r1previous_closegap_pctrPavg_daily_volumervolpremarket_high premarket_lowprevious_day_highrDprice_strength_pctdistance_to_resistance_pctresistance_level_used)r.candidate_score breakdownmetrics) rr:rr4rArFrvaluesrYr')r.r/rBrGrHr2rCrDr)wclosesvolumesr1rPr_r]rcdist_pctresistance_levelrgtotal max_possiblerfrrrscore_breakout_candidates^      rq prefilteredvolume_baselinesprev_day_highs prev_closesrange_20d_highslookback_hourscandidate_countc CsDtd}|p |dd}ttj} | t|d} g} d} |D]S} t| | | | }t |dkr3q || }|s?| d7} q t dd |D}t d d |D}|| p\td d }t | ||||||| || }| |q | jd ddd| d|}tdt |dt | dt |d| d t||S)a One-shot scan over an ALREADY-prefiltered symbol list (reuses monitor.py's own cached prefiltered universe -- see module docstring). No hard reject gates beyond a minimum-bars data-availability check and requiring a real prev_close (gap_pct's denominator -- unlike sip_bot's optional baselines, this one can't fail open since gap is a required, weighted input here); every other prefiltered symbol gets ranked, top candidate_count taken purely by candidate_score. rtop_candidate_countr)hoursrr5r6csrrrrrrrr!"r"zscan..csr)lNrrrrrr!#r"rmin_avg_daily_volumecSs|dS)Nrfr)rrrr+szscan..T)keyreverseNz[BREAKOUT-SCANNER] Selected z candidates (of z scored, z prefiltered, z skipped for missing prev_close))rr#rr$rr%rpremarket_scanner_bars_to_dictsget_minute_barsr9r r rqappendsortloginfo data_store!write_breakout_scanner_candidates)r(rsrtrurvrwrxryr)r$r+scoredskipped_no_prev_closer.r/r2rBrGrHresulttoprrrscans>        r)r r )rrN)__doc__rrr config_loaderr logger_setupr indicatorsrrrrrlistdictr0floatr4rArFstrrqintrrrrrsN9     $  X