Deploy from GitHub Actions to nse-bot-backend (part 3)

ob_breaker_luxalgo_nse_fo_strategy.pine

@@ -0,0 +1,396 @@
+// This work adapts trading logic from:
+//   "Order Blocks & Breaker Blocks [LuxAlgo]" © LuxAlgo
+//   (CC BY-NC-SA 4.0) https://creativecommons.org/licenses/by-nc-sa/4.0/
+//
+// Converted from a cosmetic indicator into a NON-REPAINTING backtesting STRATEGY
+// for NSE F&O stock intraday option trading. Signals are generated on the
+// UNDERLYING equity/futures chart. Option execution is handled separately later.
+// This script only backtests the quality of the underlying directional signal.
+//
+//@version=5
+strategy("OB Breaker Strategy - LuxAlgo Converted - NSE F&O Intraday"
+  , overlay              = true
+  , pyramiding           = 0
+  , initial_capital      = 100000
+  , default_qty_type     = strategy.percent_of_equity
+  , default_qty_value    = 100
+  , commission_type      = strategy.commission.percent
+  , commission_value     = 0.03
+  , slippage             = 1
+  , process_orders_on_close = false
+  , calc_on_every_tick   = false
+  , max_boxes_count      = 1
+  , max_lines_count      = 1
+  , max_labels_count     = 1)
+
+//-----------------------------------------------------------------------------
+// Inputs
+//-----------------------------------------------------------------------------{
+grpCore   = "Core Logic"
+length    = input.int(10,   "Swing Lookback",        minval = 3, group = grpCore)
+useBody   = input.bool(false,"Use Candle Body (else High/Low)",   group = grpCore)
+mode      = input.string("Normal OB Only", "Strategy Mode", options = ["Normal OB Only", "Breaker Only", "Both"], group = grpCore)
+entryMode = input.string("Midpoint Reclaim", "Entry Mode", options = ["Midpoint Reclaim", "Full Zone Reclaim"], group = grpCore)
+invMode   = input.string("Close", "Invalidation Mode", options = ["Body", "Close", "Wick"], group = grpCore)
+
+grpRisk   = "Risk"
+rr        = input.float(1.5, "Risk Reward Ratio",     minval = 0.1, step = 0.1, group = grpRisk)
+stopBuf   = input.float(0.0, "Stop Buffer Points",    step = 0.05, group = grpRisk)
+minObSize = input.float(0.0, "Minimum OB Size Points",group = grpRisk)
+maxObSize = input.float(999999.0, "Maximum OB Size Points", group = grpRisk)
+maxAge    = input.int(100,  "Maximum OB Age Bars",    minval = 1, group = grpRisk)
+
+grpOB     = "OB Management"
+maxBullOB = input.int(3, "Max Active Bullish OBs", minval = 1, group = grpOB)
+maxBearOB = input.int(3, "Max Active Bearish OBs", minval = 1, group = grpOB)
+
+grpTrade  = "Trade Control"
+maxTrades = input.int(4, "Max Trades Per Day", minval = 1, group = grpTrade)
+enableLong  = input.bool(true, "Enable Long Trades",  group = grpTrade)
+enableShort = input.bool(true, "Enable Short Trades", group = grpTrade)
+oneTrade    = input.bool(true, "One Trade At A Time", group = grpTrade)
+
+grpSess   = "Session / EOD"
+useSession   = input.bool(true, "Enable Session Filter", group = grpSess)
+sess         = input.session("0920-1515", "Trading Session", group = grpSess)
+avoidFirstMin= input.int(15, "Avoid First Minutes", minval = 0, group = grpSess)
+lastEntryStr = input.string("1500", "Last Entry Time (HHMM)", group = grpSess)
+eodStr       = input.string("1515", "EOD Exit Time (HHMM)",   group = grpSess)
+
+grpHTF    = "HTF EMA Filter"
+useHTF    = input.bool(false, "Enable HTF EMA Filter", group = grpHTF)
+htfTF     = input.timeframe("15", "HTF Timeframe",     group = grpHTF)
+htfLen    = input.int(50, "HTF EMA Length", minval = 1, group = grpHTF)
+
+grpDbg    = "Debug"
+debugPlots= input.bool(true, "Debug Plots", group = grpDbg)
+
+//-----------------------------------------------------------------------------}
+// Time helpers (exchange timezone via hour/minute built-ins)
+//-----------------------------------------------------------------------------{
+f_hhmm(string s) =>
+    float h = str.tonumber(str.substring(s, 0, 2))
+    float m = str.tonumber(str.substring(s, 2, 4))
+    na(h) or na(m) ? na : int(h * 60 + m)
+
+sessStartMin = f_hhmm(str.substring(sess, 0, 4))
+lastEntryMin = f_hhmm(lastEntryStr)
+eodMin       = f_hhmm(eodStr)
+
+tod        = hour * 60 + minute
+inSessRaw  = not na(time(timeframe.period, sess))
+inSession  = not useSession or inSessRaw
+afterFirst = na(sessStartMin) or tod >= (sessStartMin + avoidFirstMin)
+beforeLast = na(lastEntryMin) or tod <= lastEntryMin
+eodExit    = not na(eodMin) and tod >= eodMin
+
+// Daily trade counter reset
+var int tradesToday = 0
+var int curDay = na
+if dayofmonth != curDay
+    curDay := dayofmonth
+    tradesToday := 0
+
+//-----------------------------------------------------------------------------}
+// HTF EMA filter (optional, lookahead_off = non-repainting on bar close)
+//-----------------------------------------------------------------------------{
+htfEma = request.security(syminfo.tickerid, htfTF, ta.ema(close, htfLen), lookahead = barmerge.lookahead_off)
+longHtfOk  = not useHTF or (not na(htfEma) and close > htfEma)
+shortHtfOk = not useHTF or (not na(htfEma) and close < htfEma)
+
+//-----------------------------------------------------------------------------}
+// Swing detection (original swings(length) logic, non-repainting, len-bar delay)
+//-----------------------------------------------------------------------------{
+var int   os = 0
+var float swTopY = na
+var int   swTopX = na
+var bool  swTopCrossed = false
+var float swBtmY = na
+var int   swBtmX = na
+var bool  swBtmCrossed = false
+
+upper = ta.highest(length)
+lower = ta.lowest(length)
+os := high[length] > upper ? 0 : low[length] < lower ? 1 : os
+
+if os == 0 and os[1] != 0
+    swTopY := high[length]
+    swTopX := bar_index[length]
+    swTopCrossed := false
+if os == 1 and os[1] != 1
+    swBtmY := low[length]
+    swBtmX := bar_index[length]
+    swBtmCrossed := false
+
+srcMax = useBody ? math.max(close, open) : high
+srcMin = useBody ? math.min(close, open) : low
+
+//-----------------------------------------------------------------------------}
+// Order Block model (numeric only - NO boxes/lines/labels used for decisions)
+//-----------------------------------------------------------------------------{
+type OB
+    float top
+    float btm
+    float mid
+    int   srcBar
+    int   createdBar
+    bool  valid
+    bool  isBreaker
+    int   breakBar
+
+var array<OB> bullOBs = array.new<OB>(0)
+var array<OB> bearOBs = array.new<OB>(0)
+
+n = bar_index
+
+// Event flags for alerts
+bullObCreated  = false
+bearObCreated  = false
+bullBecameBrk  = false
+bearBecameBrk  = false
+
+//-----------------------------------------------------------------------------}
+// Bullish OB creation (close breaks confirmed swing high)
+//-----------------------------------------------------------------------------{
+if not na(swTopY) and close > swTopY and not swTopCrossed
+    swTopCrossed := true
+    float minima = srcMin[1]
+    float maxima = srcMax[1]
+    int   loc    = bar_index[1]
+    int   upTo   = (n - swTopX) - 1
+    if upTo >= 1
+        for i = 1 to upTo
+            if srcMin[i] <= minima
+                minima := srcMin[i]
+                maxima := srcMax[i]
+                loc    := bar_index[i]
+    obSize = math.abs(maxima - minima)
+    if obSize >= minObSize and obSize <= maxObSize
+        newOb = OB.new(maxima, minima, (maxima + minima) / 2.0, loc, bar_index, true, false, na)
+        array.unshift(bullOBs, newOb)
+        bullObCreated := true
+        while array.size(bullOBs) > maxBullOB
+            array.pop(bullOBs)
+
+// Bullish OB breaker conversion / invalidation
+if array.size(bullOBs) > 0
+    for i = array.size(bullOBs) - 1 to 0
+        el = array.get(bullOBs, i)
+        if el.valid
+            if not el.isBreaker
+                broke = invMode == "Body" ? math.min(close, open) < el.btm : invMode == "Close" ? close < el.btm : low < el.btm
+                if broke
+                    el.isBreaker := true
+                    el.breakBar := bar_index
+                    bullBecameBrk := true
+            else
+                if close > el.top
+                    array.remove(bullOBs, i)
+
+//-----------------------------------------------------------------------------}
+// Bearish OB creation (close breaks confirmed swing low)
+//-----------------------------------------------------------------------------{
+if not na(swBtmY) and close < swBtmY and not swBtmCrossed
+    swBtmCrossed := true
+    float maxima = srcMax[1]
+    float minima = srcMin[1]
+    int   loc    = bar_index[1]
+    int   upTo   = (n - swBtmX) - 1
+    if upTo >= 1
+        for i = 1 to upTo
+            if srcMax[i] >= maxima
+                maxima := srcMax[i]
+                minima := srcMin[i]
+                loc    := bar_index[i]
+    obSize = math.abs(maxima - minima)
+    if obSize >= minObSize and obSize <= maxObSize
+        newOb = OB.new(maxima, minima, (maxima + minima) / 2.0, loc, bar_index, true, false, na)
+        array.unshift(bearOBs, newOb)
+        bearObCreated := true
+        while array.size(bearOBs) > maxBearOB
+            array.pop(bearOBs)
+
+// Bearish OB breaker conversion / invalidation
+if array.size(bearOBs) > 0
+    for i = array.size(bearOBs) - 1 to 0
+        el = array.get(bearOBs, i)
+        if el.valid
+            if not el.isBreaker
+                broke = invMode == "Body" ? math.max(close, open) > el.top : invMode == "Close" ? close > el.top : high > el.top
+                if broke
+                    el.isBreaker := true
+                    el.breakBar := bar_index
+                    bearBecameBrk := true
+            else
+                if close < el.btm
+                    array.remove(bearOBs, i)
+
+//-----------------------------------------------------------------------------}
+// Entry evaluation
+//-----------------------------------------------------------------------------{
+allowNormal  = mode == "Normal OB Only" or mode == "Both"
+allowBreaker = mode == "Breaker Only"  or mode == "Both"
+
+canEnter = inSession and afterFirst and beforeLast and not eodExit and tradesToday < maxTrades and (not oneTrade or strategy.position_size == 0)
+
+// setup markers (pattern present, independent of gating)
+normalLongSetup  = false
+normalShortSetup = false
+brkLongSetup     = false
+brkShortSetup    = false
+
+// decided orders
+bool  doLong   = false
+bool  doShort  = false
+float sigStop  = na
+float sigTgt   = na
+bool  haveSig  = false
+
+// ---- Normal Long: retest of a valid non-breaker bullish OB ----
+if allowNormal and array.size(bullOBs) > 0
+    for i = 0 to array.size(bullOBs) - 1
+        el = array.get(bullOBs, i)
+        age = bar_index - el.createdBar
+        if el.valid and not el.isBreaker and age >= 1 and age <= maxAge
+            trig = entryMode == "Midpoint Reclaim" ? (low <= el.top and close > el.mid and close > open) : (low <= el.top and close > el.top and close > open)
+            if trig
+                normalLongSetup := true
+                stp = el.btm - stopBuf
+                if not haveSig and enableLong and longHtfOk and canEnter and close > stp and (close - stp) > 0
+                    doLong  := true
+                    sigStop := stp
+                    sigTgt  := close + (close - stp) * rr
+                    haveSig := true
+                break
+
+// ---- Breaker Long: retest (from above) of a bearish OB turned breaker = support ----
+if allowBreaker and array.size(bearOBs) > 0
+    for i = 0 to array.size(bearOBs) - 1
+        el = array.get(bearOBs, i)
+        age = bar_index - el.createdBar
+        if el.valid and el.isBreaker and age >= 1 and age <= maxAge
+            trig = entryMode == "Midpoint Reclaim" ? (low <= el.top and close > el.mid and close > open) : (low <= el.top and close > el.top and close > open)
+            if trig
+                brkLongSetup := true
+                stp = el.btm - stopBuf
+                if not haveSig and enableLong and longHtfOk and canEnter and close > stp and (close - stp) > 0
+                    doLong  := true
+                    sigStop := stp
+                    sigTgt  := close + (close - stp) * rr
+                    haveSig := true
+                break
+
+// ---- Normal Short: retest of a valid non-breaker bearish OB ----
+if allowNormal and array.size(bearOBs) > 0
+    for i = 0 to array.size(bearOBs) - 1
+        el = array.get(bearOBs, i)
+        age = bar_index - el.createdBar
+        if el.valid and not el.isBreaker and age >= 1 and age <= maxAge
+            trig = entryMode == "Midpoint Reclaim" ? (high >= el.btm and close < el.mid and close < open) : (high >= el.btm and close < el.btm and close < open)
+            if trig
+                normalShortSetup := true
+                stp = el.top + stopBuf
+                if not haveSig and enableShort and shortHtfOk and canEnter and stp > close and (stp - close) > 0
+                    doShort := true
+                    sigStop := stp
+                    sigTgt  := close - (stp - close) * rr
+                    haveSig := true
+                break
+
+// ---- Breaker Short: retest (from below) of a bullish OB turned breaker = resistance ----
+if allowBreaker and array.size(bullOBs) > 0
+    for i = 0 to array.size(bullOBs) - 1
+        el = array.get(bullOBs, i)
+        age = bar_index - el.createdBar
+        if el.valid and el.isBreaker and age >= 1 and age <= maxAge
+            trig = entryMode == "Midpoint Reclaim" ? (high >= el.btm and close < el.mid and close < open) : (high >= el.btm and close < el.btm and close < open)
+            if trig
+                brkShortSetup := true
+                stp = el.top + stopBuf
+                if not haveSig and enableShort and shortHtfOk and canEnter and stp > close and (stp - close) > 0
+                    doShort := true
+                    sigStop := stp
+                    sigTgt  := close - (stp - close) * rr
+                    haveSig := true
+                break
+
+//-----------------------------------------------------------------------------}
+// Order placement + exits (next-bar-open entries; stop/target as fixed levels)
+//-----------------------------------------------------------------------------{
+var float pendStop = na
+var float pendTgt  = na
+
+justFlat = strategy.position_size == 0 and strategy.position_size[1] != 0
+if justFlat
+    pendStop := na
+    pendTgt  := na
+
+if doLong
+    strategy.entry("Long", strategy.long)
+    pendStop := sigStop
+    pendTgt  := sigTgt
+    tradesToday += 1
+
+if doShort
+    strategy.entry("Short", strategy.short)
+    pendStop := sigStop
+    pendTgt  := sigTgt
+    tradesToday += 1
+
+// Attach SL/TP once a position is live
+if strategy.position_size > 0 and not na(pendStop) and not na(pendTgt)
+    strategy.exit("XL", from_entry = "Long", stop = pendStop, limit = pendTgt)
+if strategy.position_size < 0 and not na(pendStop) and not na(pendTgt)
+    strategy.exit("XS", from_entry = "Short", stop = pendStop, limit = pendTgt)
+
+// EOD flat + no overnight holding
+eodEvent = eodExit and strategy.position_size != 0
+if eodEvent
+    strategy.close_all(comment = "EOD")
+
+//-----------------------------------------------------------------------------}
+// Debug plots
+//-----------------------------------------------------------------------------{
+bTop = array.size(bullOBs) > 0 ? array.get(bullOBs, 0).top : na
+bBtm = array.size(bullOBs) > 0 ? array.get(bullOBs, 0).btm : na
+bMid = array.size(bullOBs) > 0 ? array.get(bullOBs, 0).mid : na
+sTop = array.size(bearOBs) > 0 ? array.get(bearOBs, 0).top : na
+sBtm = array.size(bearOBs) > 0 ? array.get(bearOBs, 0).btm : na
+sMid = array.size(bearOBs) > 0 ? array.get(bearOBs, 0).mid : na
+
+plot(debugPlots ? bTop : na, "Bull OB Top",  color = color.new(color.blue, 0),  style = plot.style_linebr)
+plot(debugPlots ? bBtm : na, "Bull OB Btm",  color = color.new(color.blue, 40), style = plot.style_linebr)
+plot(debugPlots ? bMid : na, "Bull OB Mid",  color = color.new(color.blue, 60), style = plot.style_linebr)
+plot(debugPlots ? sTop : na, "Bear OB Top",  color = color.new(color.orange, 40), style = plot.style_linebr)
+plot(debugPlots ? sBtm : na, "Bear OB Btm",  color = color.new(color.orange, 0),  style = plot.style_linebr)
+plot(debugPlots ? sMid : na, "Bear OB Mid",  color = color.new(color.orange, 60), style = plot.style_linebr)
+plot(debugPlots ? swTopY : na, "Swing High", color = color.new(color.teal, 0),   style = plot.style_circles)
+plot(debugPlots ? swBtmY : na, "Swing Low",  color = color.new(color.maroon, 0), style = plot.style_circles)
+
+plotshape(debugPlots and normalLongSetup,  "Long Setup",         style = shape.triangleup,   location = location.belowbar, color = color.new(color.green, 0),  size = size.tiny)
+plotshape(debugPlots and normalShortSetup, "Short Setup",        style = shape.triangledown, location = location.abovebar, color = color.new(color.red, 0),    size = size.tiny)
+plotshape(debugPlots and brkLongSetup,     "Breaker Long Setup", style = shape.diamond,      location = location.belowbar, color = color.new(color.lime, 0),   size = size.tiny)
+plotshape(debugPlots and brkShortSetup,    "Breaker Short Setup",style = shape.diamond,      location = location.abovebar, color = color.new(color.fuchsia, 0),size = size.tiny)
+
+//-----------------------------------------------------------------------------}
+// Alerts
+//-----------------------------------------------------------------------------{
+longEntryEvent  = strategy.position_size > 0 and strategy.position_size[1] <= 0
+shortEntryEvent = strategy.position_size < 0 and strategy.position_size[1] >= 0
+longExitEvent   = strategy.position_size[1] > 0 and strategy.position_size <= 0
+shortExitEvent  = strategy.position_size[1] < 0 and strategy.position_size >= 0
+
+alertcondition(bullObCreated,    "Bullish OB Created",     "Bullish OB created")
+alertcondition(bearObCreated,    "Bearish OB Created",     "Bearish OB created")
+alertcondition(bullBecameBrk,    "Bullish OB Breaker",     "Bullish OB became breaker")
+alertcondition(bearBecameBrk,    "Bearish OB Breaker",     "Bearish OB became breaker")
+alertcondition(normalLongSetup,  "Normal Long Setup",      "Normal long setup")
+alertcondition(normalShortSetup, "Normal Short Setup",     "Normal short setup")
+alertcondition(brkLongSetup,     "Breaker Long Setup",     "Breaker long setup")
+alertcondition(brkShortSetup,    "Breaker Short Setup",    "Breaker short setup")
+alertcondition(longEntryEvent,   "Long Entry",             "Long entry")
+alertcondition(shortEntryEvent,  "Short Entry",            "Short entry")
+alertcondition(longExitEvent,    "Long Exit",              "Long exit")
+alertcondition(shortExitEvent,   "Short Exit",             "Short exit")
+alertcondition(eodEvent,         "EOD Exit",               "EOD exit")
+//-----------------------------------------------------------------------------}

ob_intraday/README.md

@@ -0,0 +1,71 @@
+# ob_intraday — Intraday Order-Block Backtest (NSE, NIFTY futures, 5-min)
+
+Self-contained Python project implementing the numbered spec: bar-by-bar,
+no-lookahead structure/order-block detection, an intraday long/short strategy,
+a sequential backtest engine with costs, visual trade validation, and a small
+`min_score × RR` parameter sweep.
+
+It lives in its own package (`ob_intraday`) and uses **relative imports**, so it
+never collides with the repository's top-level `config.py` / `strategy.py`.
+
+## Layout
+
+| File | Role |
+|------|------|
+| `config.py` | All tunables (`z_threshold`, `min_score`, `rr_target`, pivot lengths, ATR filters, costs). |
+| `data_download.py` | Kite 5-min **continuous** NIFTY-futures download, chunked (<=90-day windows) and cached to `data/NIFTY_5min.csv`. Synthetic generator for offline/no-token runs. |
+| `detector.py` | Pivots (len 5 intraday / len 50 swing), momentum z-score, BOS, order-block construction, scoring, mitigation, merging, swing trend. |
+| `strategy.py` | Pure entry/exit rules (triggers, SL/TP, time windows). |
+| `backtest.py` | Sequential engine, trade log, metrics (win rate, avg R, profit factor, max DD, expectancy), equity curve, monthly P&L. |
+| `validation.py` | Random-trade candlestick snapshots (~100 bars) with the zone drawn. |
+| `sweep.py` | `min_score ∈ {40,50,60,70} × RR ∈ {1.5,2,3}` comparison table. |
+| `run.py` | CLI wiring it all together. |
+| `../tests/test_ob_intraday.py` | Unit + integration tests (run with `pytest`). |
+
+Outputs are written to `ob_intraday/output/` (`trades.csv`, `monthly_pnl.csv`,
+`sweep.csv`, `equity_curve.png`, `validation/*.png`).
+
+## Running
+
+```bash
+# Live: needs a valid Kite token (see below). Downloads 2y, caches, backtests,
+# plots, validates and sweeps.
+python -m ob_intraday.run --years 2
+
+# Offline / expired token: use cached CSV if present, else synthesise data so
+# the whole pipeline still runs. (Synthetic data is cached separately as
+# NIFTY_5min_synthetic.csv and never overwrites the real cache.)
+python -m ob_intraday.run --synthetic
+
+# Override strategy params, or run just the sweep on cached data:
+python -m ob_intraday.run --min-score 60 --rr 3
+python -m ob_intraday.run --sweep-only
+```
+
+### Kite token
+Zerodha access tokens reset **daily (~07:30 IST)**. If the download fails with
+a token error, refresh `tokens.json` (or set `KITE_ACCESS_TOKEN`) using the
+repo's normal auth flow, then re-run. The download reuses the repo's
+`kite_client.get_kite()` and reads the near-month NIFTY FUT token from
+`instruments_nfo.csv`, requesting with `continuous=True`.
+
+## Key modelling choices (documented in code)
+
+- **No lookahead.** Pivots are only acted on at their confirmation bar
+  (`pivot_bar + length`); triggers enter at the **next** bar's open; exits use
+  only the current bar's OHLC.
+- **Session boundaries.** Intraday pivots (5), BOS and the OB leg are confined
+  to one session; the momentum z-score drops the overnight change and builds its
+  50-sample baseline from intraday changes only; ATR ignores the gap at each
+  session open; positions are never held overnight. The **swing** trend uses
+  length-50 pivots and, being a higher frame that cannot fit in one 75-bar
+  session, runs continuously across days.
+- **Score** (per spec): `(0.6·min(dist/(5·height),1) + 0.4·min(vol/volSMA20,1))·100`,
+  with `dist = |break-close − broken pivot|`, `height` = OB candle range,
+  `vol` = OB candle volume.
+- **Costs.** Slippage of `slippage_ticks` on every market-style fill (entry,
+  stop, square-off, EOD); take-profit fills exactly at target; `cost_points` is
+  a flat round-trip deduction.
+
+The two LuxAlgo Pine files were used only to verify overlapping detection
+semantics; no drawing/alert/UI logic was ported.

ob_intraday/__init__.py

@@ -0,0 +1,19 @@
+"""Intraday order-block backtesting project for NSE (NIFTY futures, 5-minute).
+
+Self-contained package. Import paths use the ``ob_intraday`` namespace so the
+project never collides with the repository's top-level ``config``/``strategy``
+modules.
+
+Modules
+-------
+config        - all tunable parameters (:class:`Config`)
+data_download - Kite 5-minute historical download + CSV cache (+ synthetic gen)
+detector      - bar-by-bar, no-lookahead structure/order-block detection
+strategy      - entry/exit rules (signals, SL/TP)
+backtest      - the sequential engine, trade log, metrics and plots
+validation    - random-trade candlestick snapshots for visual QA
+sweep         - min_score x RR grid comparison
+run           - CLI orchestrator that wires everything together
+"""
+
+from .config import Config  # noqa: F401

ob_intraday/backtest.py

@@ -0,0 +1,222 @@
+"""Sequential backtest engine, trade log, metrics and plots.
+
+Bars are walked strictly in order. A trigger at bar ``t`` enters at bar
+``t+1``'s open (next-bar-open fill); the entry bar and every later bar are
+scanned for stop/target/square-off exits. Slippage of ``slippage_ticks`` is
+applied to every *market-style* fill (entry, stop, square-off, end-of-day); a
+take-profit is a limit fill exactly at the target. ``cost_points`` is a flat
+round-trip cost deducted from each trade's P&L.
+
+No lookahead: entry uses the *next* bar's open (unknown at trigger time only as
+a price we commit to, never inspected before committing); exits only use the
+current bar's OHLC.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+import numpy as np
+import pandas as pd
+
+from .config import Config, OUTPUT_DIR
+from . import detector as det
+from . import strategy as strat
+
+
+@dataclass
+class BacktestResult:
+    trades: pd.DataFrame
+    metrics: dict
+    equity: pd.DataFrame
+    detector: det.DetectorResult
+    cfg: Config
+
+
+# ---------------------------------------------------------------------------
+# Engine
+# ---------------------------------------------------------------------------
+def run_backtest(df: pd.DataFrame, cfg: Config,
+                 detector_result: Optional[det.DetectorResult] = None) -> BacktestResult:
+    dres = detector_result or det.detect(df, cfg)
+    d = dres.df
+    n = len(d)
+
+    ts = d["timestamp"].to_numpy()
+    ts_idx = d["timestamp"]
+    o = d["open"].to_numpy(); h = d["high"].to_numpy()
+    l = d["low"].to_numpy(); c = d["close"].to_numpy()
+    sess = d["session_date"].to_numpy()
+    atr_sl = d["atr_sl"].to_numpy()
+    trend = dres.trend
+
+    slip = cfg.slippage_ticks * cfg.tick_size
+    pos: Optional[dict] = None
+    trades: List[dict] = []
+
+    def close_trade(exit_idx, exit_price, reason, market=True):
+        nonlocal pos
+        fill = exit_price
+        if market:
+            fill += -slip if pos["direction"] == "bull" else slip
+        if pos["direction"] == "bull":
+            gross = fill - pos["entry_price"]
+        else:
+            gross = pos["entry_price"] - fill
+        net = gross - cfg.cost_points
+        r_mult = net / pos["risk"] if pos["risk"] > 0 else 0.0
+        trades.append(dict(
+            direction="long" if pos["direction"] == "bull" else "short",
+            entry_idx=pos["entry_idx"], exit_idx=int(exit_idx),
+            entry_time=pos["entry_time"], exit_time=ts_idx.iloc[int(exit_idx)],
+            entry_price=round(pos["entry_price"], 4), exit_price=round(fill, 4),
+            exit_reason=reason,
+            zone_id=pos["zone_id"], zone_score=round(pos["zone_score"], 2),
+            zone_top=round(pos["zone_top"], 4), zone_bottom=round(pos["zone_bottom"], 4),
+            stop=round(pos["stop"], 4), target=round(pos["target"], 4),
+            risk_points=round(pos["risk"], 4),
+            pnl_points_gross=round(gross, 4), cost_points=cfg.cost_points,
+            pnl_points=round(net, 4), r_multiple=round(r_mult, 4),
+            pnl_rupees=round(net * cfg.lot_size, 2),
+            bars_held=int(exit_idx) - pos["entry_idx"],
+        ))
+        pos = None
+
+    for t in range(n):
+        # ---- manage an open position on this bar -------------------------
+        if pos is not None and t >= pos["entry_idx"]:
+            new_session = t == 0 or sess[t] != sess[t - 1]
+            if new_session and t != pos["entry_idx"]:
+                # safety: never hold across the overnight gap
+                close_trade(t, o[t], "eod")
+            elif strat.at_or_after_square_off(ts_idx.iloc[t], cfg):
+                close_trade(t, o[t], "square_off")
+            else:
+                if pos["direction"] == "bull":
+                    if l[t] <= pos["stop"]:
+                        close_trade(t, pos["stop"], "sl")
+                    elif h[t] >= pos["target"]:
+                        close_trade(t, pos["target"], "tp", market=False)
+                else:
+                    if h[t] >= pos["stop"]:
+                        close_trade(t, pos["stop"], "sl")
+                    elif l[t] <= pos["target"]:
+                        close_trade(t, pos["target"], "tp", market=False)
+                # last bar of a session with position still open -> square off
+                if pos is not None and (t + 1 >= n or sess[min(t + 1, n - 1)] != sess[t]):
+                    close_trade(t, c[t], "eod")
+
+        # ---- look for a new entry trigger (flat only) --------------------
+        if pos is None and t + 1 < n and sess[t + 1] == sess[t]:
+            tr = trend[t]
+            direction = "bull" if tr == "bull" else ("bear" if tr == "bear" else None)
+            if direction and strat.within_entry_window(ts_idx.iloc[t], cfg):
+                zone = strat.select_zone(dres.zones, t, direction, cfg)
+                if zone is not None:
+                    fired = (strat.long_trigger(l[t], c[t], zone) if direction == "bull"
+                             else strat.short_trigger(h[t], c[t], zone))
+                    if fired:
+                        entry_price = o[t + 1] + (slip if direction == "bull" else -slip)
+                        levels = strat.compute_levels(direction, entry_price, zone,
+                                                      atr_sl[t], cfg)
+                        if levels is not None:
+                            zone.attempted = True
+                            pos = dict(
+                                direction=direction, entry_idx=t + 1,
+                                entry_time=ts_idx.iloc[t + 1], entry_price=entry_price,
+                                stop=levels.stop, target=levels.target, risk=levels.risk,
+                                zone_id=zone.id, zone_score=zone.score,
+                                zone_top=zone.top, zone_bottom=zone.bottom,
+                            )
+
+    trades_df = pd.DataFrame(trades)
+    metrics = compute_metrics(trades_df, cfg)
+    equity = build_equity(trades_df, cfg)
+    return BacktestResult(trades=trades_df, metrics=metrics, equity=equity,
+                          detector=dres, cfg=cfg)
+
+
+# ---------------------------------------------------------------------------
+# Metrics
+# ---------------------------------------------------------------------------
+def compute_metrics(trades: pd.DataFrame, cfg: Config) -> dict:
+    if trades.empty:
+        return dict(trades=0, win_rate=0.0, avg_R=0.0, profit_factor=0.0,
+                    expectancy_points=0.0, expectancy_R=0.0, max_drawdown_points=0.0,
+                    max_drawdown_rupees=0.0, total_points=0.0, total_rupees=0.0)
+    pnl = trades["pnl_points"]
+    wins = pnl[pnl > 0]
+    losses = pnl[pnl < 0]
+    gross_profit = wins.sum()
+    gross_loss = -losses.sum()
+    equity = pnl.cumsum()
+    running_max = equity.cummax()
+    dd = running_max - equity
+    max_dd = dd.max()
+    return dict(
+        trades=int(len(trades)),
+        wins=int((pnl > 0).sum()),
+        losses=int((pnl < 0).sum()),
+        win_rate=round(float((pnl > 0).mean()) * 100, 2),
+        avg_R=round(float(trades["r_multiple"].mean()), 3),
+        profit_factor=round(float(gross_profit / gross_loss), 3) if gross_loss > 0 else float("inf"),
+        expectancy_points=round(float(pnl.mean()), 3),
+        expectancy_R=round(float(trades["r_multiple"].mean()), 3),
+        max_drawdown_points=round(float(max_dd), 2),
+        max_drawdown_rupees=round(float(max_dd) * cfg.lot_size, 2),
+        total_points=round(float(pnl.sum()), 2),
+        total_rupees=round(float(pnl.sum()) * cfg.lot_size, 2),
+    )
+
+
+def build_equity(trades: pd.DataFrame, cfg: Config) -> pd.DataFrame:
+    if trades.empty:
+        return pd.DataFrame(columns=["exit_time", "pnl_points", "equity_points",
+                                     "equity_rupees"])
+    eq = trades[["exit_time", "pnl_points"]].copy().sort_values("exit_time")
+    eq["equity_points"] = eq["pnl_points"].cumsum()
+    eq["equity_rupees"] = eq["equity_points"] * cfg.lot_size
+    return eq.reset_index(drop=True)
+
+
+def monthly_pnl(trades: pd.DataFrame, cfg: Config) -> pd.DataFrame:
+    if trades.empty:
+        return pd.DataFrame(columns=["month", "trades", "pnl_points", "pnl_rupees",
+                                     "win_rate"])
+    t = trades.copy()
+    t["month"] = pd.to_datetime(t["entry_time"]).dt.strftime("%Y-%m")
+    g = t.groupby("month")
+    out = g.agg(trades=("pnl_points", "size"),
+                pnl_points=("pnl_points", "sum"),
+                win_rate=("pnl_points", lambda s: round((s > 0).mean() * 100, 1)))
+    out["pnl_rupees"] = (out["pnl_points"] * cfg.lot_size).round(2)
+    out["pnl_points"] = out["pnl_points"].round(2)
+    return out.reset_index()
+
+
+# ---------------------------------------------------------------------------
+# Plots
+# ---------------------------------------------------------------------------
+def plot_equity(result: BacktestResult, path=None):
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    path = path or (OUTPUT_DIR / "equity_curve.png")
+    eq = result.equity
+    fig, ax = plt.subplots(figsize=(11, 5))
+    if not eq.empty:
+        ax.plot(pd.to_datetime(eq["exit_time"]), eq["equity_points"],
+                color="#1565c0", lw=1.4)
+        ax.axhline(0, color="#888", lw=0.8, ls="--")
+    ax.set_title(f"Equity curve ({result.cfg.symbol} 5-min OB strategy) — "
+                 f"{result.metrics['trades']} trades, "
+                 f"PF={result.metrics['profit_factor']}, "
+                 f"total={result.metrics['total_points']} pts")
+    ax.set_ylabel("Cumulative P&L (index points)")
+    ax.grid(alpha=0.3)
+    fig.tight_layout()
+    fig.savefig(path, dpi=110)
+    plt.close(fig)
+    return path

ob_intraday/config.py

@@ -0,0 +1,75 @@
+"""Central configuration for the intraday order-block backtest.
+
+Every tunable the spec calls out is exposed here as a field on :class:`Config`:
+``z_threshold``, ``min_score``, ``rr_target``, the pivot lengths and the ATR
+filters. Defaults reproduce the base spec; the sweep (``sweep.py``) overrides
+``min_score`` and ``rr_target`` only.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict, replace
+from pathlib import Path
+
+PROJECT_DIR = Path(__file__).resolve().parent
+DATA_DIR = PROJECT_DIR / "data"
+OUTPUT_DIR = PROJECT_DIR / "output"
+
+
+@dataclass(frozen=True)
+class Config:
+    # ---- Instrument / data -------------------------------------------------
+    symbol: str = "NIFTY"                 # cache file is data/{symbol}_5min.csv
+    exchange: str = "NFO"
+    interval: str = "5minute"
+    lot_size: int = 75                    # for optional rupee conversion only
+    tick_size: float = 0.05               # 1 tick; drives slippage
+    session_start: str = "09:15"          # NSE cash/F&O session (IST)
+    session_end: str = "15:30"
+
+    # ---- Detector: momentum z-score ---------------------------------------
+    z_window: int = 50                    # SMA/stdev window for close-diff
+    z_threshold: float = 0.5              # |z| gate for a valid BOS
+
+    # ---- Detector: pivots --------------------------------------------------
+    pivot_len: int = 5                    # intraday BOS pivots (both sides)
+    swing_pivot_len: int = 50             # swing-scale trend pivots
+
+    # ---- Detector: order-block filters ------------------------------------
+    atr_big_len: int = 200                # skip OB candles with range >= 2*ATR200
+    atr_big_mult: float = 2.0
+    atr_height_len: int = 10              # reject OB if height > 3.5*ATR10
+    atr_height_mult: float = 3.5
+    vol_sma_len: int = 20                 # SMA of volume for the score
+
+    # ---- Detector: score ---------------------------------------------------
+    # score = (0.6*min(dist/(5*height),1) + 0.4*min(vol/volSMA20,1)) * 100
+    score_dist_weight: float = 0.6
+    score_vol_weight: float = 0.4
+    score_dist_height_mult: float = 5.0
+
+    # ---- Strategy ----------------------------------------------------------
+    min_score: float = 50.0               # OB quality gate to trade
+    rr_target: float = 2.0                # take-profit at rr_target * R
+    sl_atr_len: int = 10                  # ATR used to pad the stop
+    sl_atr_mult: float = 0.25             # SL = zone far edge -/+ 0.25*ATR10
+    entry_start: str = "09:30"            # first eligible trigger time
+    entry_cutoff: str = "14:30"           # last eligible trigger time
+    square_off: str = "15:10"             # force flat at/after this time
+
+    # ---- Costs -------------------------------------------------------------
+    slippage_ticks: float = 1.0           # applied on entry and on exit fills
+    cost_points: float = 0.0              # extra round-trip cost, index points
+
+    # -- helpers -------------------------------------------------------------
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def with_overrides(self, **kwargs) -> "Config":
+        return replace(self, **kwargs)
+
+
+DEFAULT = Config()
+
+# Sweep grid required by the spec (no optimisation beyond this).
+SWEEP_MIN_SCORE = (40.0, 50.0, 60.0, 70.0)
+SWEEP_RR = (1.5, 2.0, 3.0)

ob_intraday/data_download.py

@@ -0,0 +1,335 @@
+"""Download & cache 5-minute NIFTY-futures (continuous) candles from Kite.
+
+Kite caps intraday history per request (~100 days for 5-minute), so we loop over
+date windows and append. The result is cached to ``data/{symbol}_5min.csv`` with
+exactly the columns the rest of the project expects::
+
+    timestamp, open, high, low, close, volume
+
+``timestamp`` is tz-aware Asia/Kolkata. Rows are filtered to the regular NSE
+session (09:15-15:30 IST) and de-duplicated/sorted.
+
+If the Kite token is missing/expired (tokens die daily ~07:30 IST) the live
+download raises with a clear message. ``generate_synthetic`` produces a
+structurally-plausible 2-year 5-minute series so the detector/strategy/backtest
+pipeline can be exercised and unit-tested without a live session.
+"""
+from __future__ import annotations
+
+import sys
+import time
+from datetime import datetime, timedelta, time as dtime
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from .config import Config, DATA_DIR
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+OHLCV_COLS = ["timestamp", "open", "high", "low", "close", "volume"]
+CHUNK_DAYS = 90  # under Kite's ~100-day 5-minute cap
+
+
+# ---------------------------------------------------------------------------
+# Cache path & IO
+# ---------------------------------------------------------------------------
+def cache_path(cfg: Config) -> Path:
+    return DATA_DIR / f"{cfg.symbol}_5min.csv"
+
+
+def synthetic_cache_path(cfg: Config) -> Path:
+    # kept separate so a synthetic run never masquerades as real Kite data
+    return DATA_DIR / f"{cfg.symbol}_5min_synthetic.csv"
+
+
+def load_cached(cfg: Config, path: Path | None = None) -> pd.DataFrame | None:
+    p = path or cache_path(cfg)
+    if not p.exists():
+        return None
+    df = pd.read_csv(p)
+    return normalize(df, cfg)
+
+
+def save_cache(df: pd.DataFrame, cfg: Config, path: Path | None = None) -> Path:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    p = path or cache_path(cfg)
+    out = df.copy()
+    out["timestamp"] = pd.to_datetime(out["timestamp"]).map(
+        lambda ts: ts.isoformat()
+    )
+    out[OHLCV_COLS].to_csv(p, index=False)
+    return p
+
+
+# ---------------------------------------------------------------------------
+# Normalisation / session handling
+# ---------------------------------------------------------------------------
+def normalize(df: pd.DataFrame, cfg: Config) -> pd.DataFrame:
+    df = df.rename(columns={c: c.lower() for c in df.columns})
+    if "date" in df.columns and "timestamp" not in df.columns:
+        df = df.rename(columns={"date": "timestamp"})
+    df["timestamp"] = pd.to_datetime(df["timestamp"], errors="coerce")
+    df = df.dropna(subset=["timestamp"]).copy()
+
+    ts = df["timestamp"]
+    if ts.dt.tz is None:
+        df["timestamp"] = ts.dt.tz_localize("Asia/Kolkata")
+    else:
+        df["timestamp"] = ts.dt.tz_convert("Asia/Kolkata")
+
+    for c in ("open", "high", "low", "close", "volume"):
+        if c not in df.columns:
+            df[c] = 0.0
+        df[c] = pd.to_numeric(df[c], errors="coerce")
+    df = df.dropna(subset=["open", "high", "low", "close"]).copy()
+
+    df = _filter_session(df, cfg)
+    df = (
+        df.drop_duplicates(subset=["timestamp"])
+        .sort_values("timestamp")
+        .reset_index(drop=True)
+    )
+    # session date used everywhere for intraday-scoped logic
+    df["session_date"] = df["timestamp"].dt.date
+    return df[OHLCV_COLS + ["session_date"]]
+
+
+def _filter_session(df: pd.DataFrame, cfg: Config) -> pd.DataFrame:
+    start = _parse_hhmm(cfg.session_start)
+    end = _parse_hhmm(cfg.session_end)
+    t = df["timestamp"].dt.time
+    # keep bars whose stamp is within [start, end]; Kite stamps bars at their
+    # open, so the last 5-min bar opens at 15:25 (<=15:30).
+    mask = (t >= start) & (t <= end)
+    # drop weekends defensively
+    mask &= df["timestamp"].dt.dayofweek < 5
+    return df[mask]
+
+
+def _parse_hhmm(s: str) -> dtime:
+    hh, mm = str(s).split(":")
+    return dtime(int(hh), int(mm))
+
+
+# ---------------------------------------------------------------------------
+# Live download (Kite)
+# ---------------------------------------------------------------------------
+def _resolve_front_future_token(cfg: Config) -> int:
+    """Instrument token of the near-month NIFTY future.
+
+    NOTE: Kite only supports ``continuous=True`` for the *daily* interval, so at
+    5-minute we fetch this single contract; it only returns data over the
+    contract's own listing window (~a few months). Expired-contract tokens are
+    not exposed by the API, so a stitched multi-year 5-min futures series is not
+    obtainable this way.
+    """
+    nfo = pd.read_csv(REPO_ROOT / "instruments_nfo.csv")
+    nfo["tradingsymbol"] = nfo["tradingsymbol"].astype(str).str.upper()
+    fut = nfo[
+        (nfo["name"].astype(str).str.upper() == cfg.symbol.upper())
+        & (nfo["instrument_type"].astype(str).str.upper() == "FUT")
+    ].copy()
+    if fut.empty:
+        raise ValueError(f"No {cfg.symbol} FUT rows in instruments_nfo.csv")
+    fut["expiry"] = pd.to_datetime(fut["expiry"], errors="coerce")
+    fut = fut.sort_values("expiry")
+    return int(fut.iloc[0]["instrument_token"])
+
+
+_INDEX_SYMBOL = {"NIFTY": "NIFTY 50", "BANKNIFTY": "NIFTY BANK",
+                 "FINNIFTY": "NIFTY FIN SERVICE"}
+
+
+def _resolve_index_token(cfg: Config) -> int:
+    """Spot-index token (2-year 5-min history, but volume == 0)."""
+    nse = pd.read_csv(REPO_ROOT / "instruments_nse.csv")
+    nse["tradingsymbol"] = nse["tradingsymbol"].astype(str).str.upper()
+    name = _INDEX_SYMBOL.get(cfg.symbol.upper(), cfg.symbol.upper())
+    row = nse[nse["tradingsymbol"] == name.upper()]
+    if row.empty:
+        raise ValueError(f"Index '{name}' not found in instruments_nse.csv")
+    return int(row.iloc[0]["instrument_token"])
+
+
+def kite_from_token_file(path: str | Path, verify: bool = True):
+    """Build a KiteConnect by PAIRING the api_key + access_token stored in a
+    tokens json (e.g. tokens.paper.json — its api_key differs from .env)."""
+    import json
+    from kiteconnect import KiteConnect
+
+    data = json.loads(Path(path).read_text())
+    api_key = data.get("api_key")
+    access_token = data.get("access_token")
+    if not api_key or not access_token:
+        raise ValueError(f"{path} missing api_key/access_token")
+    kite = KiteConnect(api_key=api_key)
+    kite.set_access_token(access_token)
+    if verify:
+        kite.profile()  # raises TokenException if stale
+    return kite
+
+
+def download(cfg: Config, years: float = 2.0, end: datetime | None = None,
+             pause_s: float = 0.35, verbose: bool = True, kite=None,
+             source: str = "futures") -> pd.DataFrame:
+    """Download ``years`` of 5-minute candles and cache them.
+
+    ``source``:
+      * ``"futures"`` - near-month NIFTY future (real volume, but only spans the
+        contract's listing window since Kite has no 5-min continuous / expired
+        tokens).
+      * ``"index"``   - NIFTY 50 spot (full multi-year history, volume == 0).
+
+    Loops over <=90-day windows (Kite's per-request cap). Pass ``kite`` to use a
+    specific session (e.g. built from tokens.paper.json).
+    """
+    if kite is None:
+        from kite_client import get_kite  # local import: keeps creds optional
+        try:
+            kite = get_kite()
+        except Exception as e:  # expired/missing token -> actionable message
+            raise RuntimeError(
+                "Kite session unavailable (token likely expired — Zerodha tokens "
+                "reset daily ~07:30 IST). Refresh tokens.json / KITE_ACCESS_TOKEN, "
+                "then re-run. Underlying error: " + str(e)
+            ) from e
+
+    if source == "index":
+        token = _resolve_index_token(cfg)
+    elif source == "futures":
+        token = _resolve_front_future_token(cfg)
+    else:
+        raise ValueError(f"unknown source: {source}")
+    end = end or datetime.now()
+    start = end - timedelta(days=int(365 * years))
+
+    frames: list[pd.DataFrame] = []
+    win_start = start
+    while win_start < end:
+        win_end = min(win_start + timedelta(days=CHUNK_DAYS), end)
+        if verbose:
+            print(f"  fetch {win_start:%Y-%m-%d} -> {win_end:%Y-%m-%d}")
+        candles = kite.historical_data(
+            instrument_token=token,
+            from_date=win_start,
+            to_date=win_end,
+            interval="5minute",
+            oi=False,
+        )
+        if candles:
+            frames.append(pd.DataFrame(candles))
+        win_start = win_end + timedelta(days=1)
+        time.sleep(pause_s)  # be gentle with rate limits
+
+    if not frames:
+        raise RuntimeError("Kite returned no candles for the requested range.")
+
+    raw = pd.concat(frames, ignore_index=True)
+    df = normalize(raw, cfg)
+    p = save_cache(df, cfg, cache_path(cfg) if source == "futures"
+                   else DATA_DIR / f"{cfg.symbol}_index_5min.csv")
+    if verbose:
+        print(f"  cached {len(df):,} bars ({source}) -> {p}")
+    return df
+
+
+def get_data(cfg: Config, years: float = 2.0, allow_synthetic: bool = False,
+             refresh: bool = False, verbose: bool = True, kite=None) -> pd.DataFrame:
+    """Return the 5-minute dataset: cached CSV if present (and not ``refresh``),
+    else a live download. Falls back to synthetic only if ``allow_synthetic``.
+    """
+    if not refresh:
+        cached = load_cached(cfg)
+        if cached is not None and not cached.empty:
+            if verbose:
+                print(f"  using cache: {cache_path(cfg)} ({len(cached):,} bars)")
+            return cached
+        if allow_synthetic:
+            syn = load_cached(cfg, synthetic_cache_path(cfg))
+            if syn is not None and not syn.empty:
+                if verbose:
+                    print(f"  using SYNTHETIC cache: {synthetic_cache_path(cfg)} "
+                          f"({len(syn):,} bars)")
+                return syn
+    try:
+        return download(cfg, years=years, verbose=verbose, kite=kite)
+    except Exception as e:
+        if not allow_synthetic:
+            raise
+        if verbose:
+            print(f"  live download failed ({e}); generating synthetic data")
+        df = generate_synthetic(cfg, years=years)
+        save_cache(df, cfg, synthetic_cache_path(cfg))  # separate from real cache
+        return df
+
+
+# ---------------------------------------------------------------------------
+# Synthetic generator (pipeline testing / no-token fallback)
+# ---------------------------------------------------------------------------
+def generate_synthetic(cfg: Config, years: float = 2.0, seed: int = 7,
+                       start_price: float = 20000.0) -> pd.DataFrame:
+    """Structurally-plausible 5-minute NIFTY-like series.
+
+    Trending regimes + intraday mean reversion so that pivots, BOS and order
+    blocks actually form. Not a market model — only for exercising the pipeline.
+    """
+    rng = np.random.default_rng(seed)
+    n_days = int(252 * years)
+    bars_per_day = 75  # 09:15..15:25 inclusive @ 5-min
+    slots = [dtime(9, 15)]
+    t = datetime(2000, 1, 3, 9, 15)
+    for _ in range(bars_per_day - 1):
+        t += timedelta(minutes=5)
+        slots.append(t.time())
+
+    rows = []
+    price = start_price
+    day = datetime.now().date() - timedelta(days=int(365 * years))
+    # drift regime that flips occasionally -> creates swing structure
+    drift = 0.0
+    added = 0
+    while added < n_days:
+        if day.weekday() < 5:
+            if rng.random() < 0.03:
+                drift = rng.normal(0, 3.0)
+            gap = rng.normal(0, 6.0)
+            price += gap
+            day_open = price
+            for slot in slots:
+                vol_base = rng.uniform(0.8, 1.4)
+                step = rng.normal(drift * 0.02, 6.0) * vol_base
+                o = price
+                c = o + step
+                hi = max(o, c) + abs(rng.normal(0, 3.0))
+                lo = min(o, c) - abs(rng.normal(0, 3.0))
+                v = int(abs(rng.normal(1.0, 0.4)) * 100000 + 20000)
+                ts = pd.Timestamp.combine(pd.Timestamp(day), slot).tz_localize(
+                    "Asia/Kolkata"
+                )
+                rows.append((ts, o, hi, lo, c, v))
+                price = c
+            added += 1
+        day = day + timedelta(days=1)
+
+    df = pd.DataFrame(rows, columns=OHLCV_COLS)
+    return normalize(df, cfg)
+
+
+if __name__ == "__main__":  # manual: python -m ob_intraday.data_download
+    import argparse
+
+    ap = argparse.ArgumentParser(description="Download 5-min NIFTY futures")
+    ap.add_argument("--years", type=float, default=2.0)
+    ap.add_argument("--refresh", action="store_true")
+    ap.add_argument("--synthetic", action="store_true",
+                    help="fall back to synthetic if live download fails")
+    args = ap.parse_args()
+    cfg = Config()
+    d = get_data(cfg, years=args.years, allow_synthetic=args.synthetic,
+                 refresh=args.refresh)
+    print(d.head())
+    print(f"rows={len(d):,}  {d['timestamp'].min()} -> {d['timestamp'].max()}")

ob_intraday/detector.py

@@ -0,0 +1,305 @@
+"""Bar-by-bar structure & order-block detection — strictly no lookahead.
+
+Everything a later bar needs is derived only from that bar and earlier bars. In
+particular a pivot of length ``L`` is only *acted on* at its confirmation bar
+(``pivot_bar + L``), which is exactly how ``ta.pivothigh(L, L)`` behaves on a
+live chart.
+
+Session handling (spec: "never let indicator lookbacks cross overnight gaps for
+intraday logic"):
+
+* Intraday pivots (len 5), BOS crossovers and the order-block leg are all
+  confined to a single session; the last-pivot memory is reset each session
+  open.
+* The momentum z-score excludes the overnight gap: the change at each session's
+  first bar is dropped, and the 50-sample baseline is built from intraday
+  changes only.
+* True range at a session's first bar ignores the prior close, so an overnight
+  gap never inflates ATR.
+* The **swing** trend uses length-50 pivots, which cannot fit inside one 75-bar
+  session and are explicitly a higher ("swing-scale") frame — these run
+  continuously across sessions.
+
+The score follows the spec exactly::
+
+    score = (0.6*min(dist/(5*height), 1) + 0.4*min(vol/volSMA20, 1)) * 100
+
+with ``dist`` = |break-bar close - broken pivot level|, ``height`` = OB candle
+high-low, ``vol`` = OB candle volume, ``volSMA20`` = SMA(20) of volume at the OB
+candle.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+import numpy as np
+import pandas as pd
+
+from .config import Config
+
+
+@dataclass
+class Zone:
+    id: int
+    direction: str            # "bull" | "bear"
+    top: float
+    bottom: float
+    score: float
+    volume: float
+    created_idx: int          # BOS bar; zone is tradeable from created_idx+1
+    ob_idx: int               # bar index of the order-block candle
+    pivot_idx: int            # broken pivot's bar
+    mitigated_idx: Optional[int] = None
+    attempted: bool = False   # set by the strategy (one attempt per zone)
+
+    @property
+    def height(self) -> float:
+        return self.top - self.bottom
+
+    def active_at(self, t: int) -> bool:
+        if t <= self.created_idx:
+            return False
+        return self.mitigated_idx is None or t < self.mitigated_idx
+
+
+@dataclass
+class DetectorResult:
+    df: pd.DataFrame                 # normalized OHLCV + indicator columns
+    zones: List[Zone]
+    trend: np.ndarray                # per-bar "bull"/"bear"/"none"
+    bos_bull: np.ndarray             # bool per bar (intraday BOS up)
+    bos_bear: np.ndarray
+
+    def active_zones_at(self, t: int, direction: Optional[str] = None) -> List[Zone]:
+        out = [z for z in self.zones if z.active_at(t)]
+        if direction:
+            out = [z for z in out if z.direction == direction]
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Vectorised, causal indicators
+# ---------------------------------------------------------------------------
+def _session_start_mask(df: pd.DataFrame) -> np.ndarray:
+    sd = df["session_date"].to_numpy()
+    m = np.ones(len(sd), dtype=bool)
+    m[1:] = sd[1:] != sd[:-1]
+    return m
+
+
+def _wilder_atr(high, low, close, sess_start, n) -> np.ndarray:
+    prev_close = close.shift(1)
+    tr = np.maximum.reduce([
+        (high - low).to_numpy(),
+        (high - prev_close).abs().to_numpy(),
+        (low - prev_close).abs().to_numpy(),
+    ])
+    hl = (high - low).to_numpy()
+    tr[sess_start] = hl[sess_start]          # no overnight gap in TR
+    tr = pd.Series(tr, index=high.index)
+    return tr.ewm(alpha=1.0 / n, adjust=False, min_periods=n).mean().to_numpy()
+
+
+def _momentum_z(close: pd.Series, sess_start: np.ndarray, window: int) -> np.ndarray:
+    ch = close.diff()
+    ch[sess_start] = np.nan                  # drop the overnight change
+    valid = ch.dropna()
+    avg = valid.rolling(window, min_periods=window).mean()
+    std = valid.rolling(window, min_periods=window).std(ddof=0)  # Pine ta.stdev
+    avg = avg.reindex(close.index)
+    std = std.reindex(close.index)
+    z = (ch - avg) / std
+    z[std <= 0] = np.nan
+    return z.to_numpy()
+
+
+def _pivots(values: np.ndarray, sess: np.ndarray, length: int,
+            is_high: bool, intraday: bool) -> np.ndarray:
+    """Return an array aligned to the *confirmation* bar (pivot_bar+length):
+    value = the pivot price, or NaN. Strict extreme on both sides."""
+    n = len(values)
+    out = np.full(n, np.nan)
+    for i in range(length, n - length):
+        conf = i + length
+        if intraday and (sess[i - length] != sess[i] or sess[i + length] != sess[i]):
+            continue
+        c = values[i]
+        left = values[i - length:i]
+        right = values[i + 1:i + length + 1]
+        if is_high:
+            if c > left.max() and c > right.max():
+                out[conf] = c
+        else:
+            if c < left.min() and c < right.min():
+                out[conf] = c
+    return out
+
+
+def add_indicators(df: pd.DataFrame, cfg: Config) -> pd.DataFrame:
+    df = df.copy()
+    sess_start = _session_start_mask(df)
+    high, low, close, vol = df["high"], df["low"], df["close"], df["volume"]
+    df["atr_big"] = _wilder_atr(high, low, close, sess_start, cfg.atr_big_len)
+    df["atr_height"] = _wilder_atr(high, low, close, sess_start, cfg.atr_height_len)
+    df["atr_sl"] = _wilder_atr(high, low, close, sess_start, cfg.sl_atr_len)
+    df["vol_sma"] = vol.rolling(cfg.vol_sma_len, min_periods=cfg.vol_sma_len).mean()
+    df["momentum_z"] = _momentum_z(close, sess_start, cfg.z_window)
+    return df
+
+
+# ---------------------------------------------------------------------------
+# Order-block construction
+# ---------------------------------------------------------------------------
+def _build_ob(df: pd.DataFrame, pivot_idx: int, break_idx: int, direction: str,
+              pivot_level: float, cfg: Config, next_id: int) -> Optional[Zone]:
+    o = df["open"].to_numpy(); h = df["high"].to_numpy()
+    l = df["low"].to_numpy(); c = df["close"].to_numpy()
+    v = df["volume"].to_numpy()
+    atr_big = df["atr_big"].to_numpy()
+    atr_h = df["atr_height"].to_numpy()
+    vol_sma = df["vol_sma"].to_numpy()
+
+    lo_leg, hi_leg = pivot_idx, break_idx
+    best = None
+    for i in range(lo_leg, hi_leg + 1):
+        rng = h[i] - l[i]
+        big = atr_big[i]
+        if not np.isnan(big) and rng >= cfg.atr_big_mult * big:
+            continue                                   # skip oversized candles
+        if direction == "bull":
+            if c[i] < o[i]:                            # opposing (bearish) candle
+                if best is None or l[i] < l[best]:
+                    best = i
+        else:
+            if c[i] > o[i]:                            # opposing (bullish) candle
+                if best is None or h[best] < h[i]:
+                    best = i
+    if best is None:
+        return None
+
+    top, bottom = h[best], l[best]
+    height = top - bottom
+    if height <= 0:
+        return None
+    atrh = atr_h[break_idx]
+    if not np.isnan(atrh) and height > cfg.atr_height_mult * atrh:
+        return None                                    # OB too tall
+
+    dist = abs(c[break_idx] - pivot_level)
+    dist_term = min(dist / (cfg.score_dist_height_mult * height), 1.0)
+    vs = vol_sma[best]
+    if np.isnan(vs) or vs <= 0:
+        vol_term = 0.0
+    else:
+        vol_term = min(v[best] / vs, 1.0)
+    score = (cfg.score_dist_weight * dist_term
+             + cfg.score_vol_weight * vol_term) * 100.0
+
+    return Zone(id=next_id, direction=direction, top=float(top),
+                bottom=float(bottom), score=float(score), volume=float(v[best]),
+                created_idx=break_idx, ob_idx=best, pivot_idx=pivot_idx)
+
+
+def _merge_into_active(zones: List[Zone], new: Zone) -> bool:
+    """Merge ``new`` into an overlapping, same-direction, still-active zone.
+    Returns True if merged (caller then drops ``new``)."""
+    for z in zones:
+        if z.direction != new.direction or z.mitigated_idx is not None:
+            continue
+        if new.bottom <= z.top and new.top >= z.bottom:      # overlap
+            z.top = max(z.top, new.top)
+            z.bottom = min(z.bottom, new.bottom)
+            z.volume += new.volume                            # sum volume
+            z.score = max(z.score, new.score)                 # keep max score
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Main detection pass
+# ---------------------------------------------------------------------------
+def detect(df: pd.DataFrame, cfg: Config) -> DetectorResult:
+    df = add_indicators(df, cfg)
+    n = len(df)
+    sess = df["session_date"].to_numpy()
+    close = df["close"].to_numpy()
+    z = df["momentum_z"].to_numpy()
+
+    ph = _pivots(df["high"].to_numpy(), sess, cfg.pivot_len, True, intraday=True)
+    pl = _pivots(df["low"].to_numpy(), sess, cfg.pivot_len, False, intraday=True)
+    sph = _pivots(df["high"].to_numpy(), sess, cfg.swing_pivot_len, True, intraday=False)
+    spl = _pivots(df["low"].to_numpy(), sess, cfg.swing_pivot_len, False, intraday=False)
+
+    zones: List[Zone] = []
+    active: List[Zone] = []            # unmitigated zones, for fast mitigation
+    trend_arr = np.array(["none"] * n, dtype=object)
+    bos_bull = np.zeros(n, dtype=bool)
+    bos_bear = np.zeros(n, dtype=bool)
+
+    last_ph = np.nan; last_ph_idx = -1
+    last_pl = np.nan; last_pl_idx = -1
+    last_sph = np.nan; last_spl = np.nan
+    trend = "none"
+    next_id = 0
+
+    for t in range(n):
+        new_session = t == 0 or sess[t] != sess[t - 1]
+        if new_session:                       # intraday pivot memory resets
+            last_ph = np.nan; last_ph_idx = -1
+            last_pl = np.nan; last_pl_idx = -1
+
+        # register newly-confirmed pivots at this bar
+        if not np.isnan(ph[t]):
+            last_ph = ph[t]; last_ph_idx = t - cfg.pivot_len
+        if not np.isnan(pl[t]):
+            last_pl = pl[t]; last_pl_idx = t - cfg.pivot_len
+        if not np.isnan(sph[t]):
+            last_sph = sph[t]
+        if not np.isnan(spl[t]):
+            last_spl = spl[t]
+
+        # ---- intraday BOS + order block (needs an in-session prior close) ---
+        if not new_session:
+            zt = z[t]
+            if (not np.isnan(last_ph) and not np.isnan(zt)
+                    and close[t] > last_ph and close[t - 1] <= last_ph
+                    and zt > cfg.z_threshold):
+                bos_bull[t] = True
+                zone = _build_ob(df, last_ph_idx, t, "bull", last_ph, cfg, next_id)
+                if zone is not None and not _merge_into_active(active, zone):
+                    zones.append(zone); active.append(zone); next_id += 1
+                last_ph = np.nan                       # consume broken pivot
+            elif (not np.isnan(last_pl) and not np.isnan(zt)
+                  and close[t] < last_pl and close[t - 1] >= last_pl
+                  and zt < -cfg.z_threshold):
+                bos_bear[t] = True
+                zone = _build_ob(df, last_pl_idx, t, "bear", last_pl, cfg, next_id)
+                if zone is not None and not _merge_into_active(active, zone):
+                    zones.append(zone); active.append(zone); next_id += 1
+                last_pl = np.nan
+
+        # ---- swing trend (continuous, no z filter) --------------------------
+        if t > 0:
+            if (not np.isnan(last_sph) and close[t] > last_sph
+                    and close[t - 1] <= last_sph):
+                trend = "bull"; last_sph = np.nan
+            elif (not np.isnan(last_spl) and close[t] < last_spl
+                  and close[t - 1] >= last_spl):
+                trend = "bear"; last_spl = np.nan
+        trend_arr[t] = trend
+
+        # ---- mitigation: close beyond the zone's far edge -------------------
+        if active:
+            still: List[Zone] = []
+            for zn in active:
+                if zn.created_idx < t and (
+                        (zn.direction == "bull" and close[t] < zn.bottom)
+                        or (zn.direction == "bear" and close[t] > zn.top)):
+                    zn.mitigated_idx = t
+                else:
+                    still.append(zn)
+            active = still
+
+    return DetectorResult(df=df, zones=zones, trend=trend_arr,
+                          bos_bull=bos_bull, bos_bear=bos_bear)

ob_intraday/output/monthly_pnl.csv

@@ -0,0 +1,2 @@
+month,trades,pnl_points,win_rate,pnl_rupees
+2026-05,1,36.63,100.0,2746.92

ob_intraday/output/sweep.csv

@@ -0,0 +1,13 @@
+min_score,rr,trades,win_rate,avg_R,profit_factor,expectancy_R,total_points,max_dd_points
+40.0,1.5,7,42.86,0.071,0.578,0.071,-72.45,108.09
+40.0,2.0,7,42.86,0.285,0.77,0.285,-39.39,100.55
+40.0,3.0,7,28.57,0.142,0.49,0.142,-104.2,168.42
+50.0,1.5,1,100.0,1.5,inf,1.5,27.47,0.0
+50.0,2.0,1,100.0,2.0,inf,2.0,36.63,0.0
+50.0,3.0,1,100.0,3.0,inf,3.0,54.94,0.0
+60.0,1.5,1,100.0,1.5,inf,1.5,27.47,0.0
+60.0,2.0,1,100.0,2.0,inf,2.0,36.63,0.0
+60.0,3.0,1,100.0,3.0,inf,3.0,54.94,0.0
+70.0,1.5,1,100.0,1.5,inf,1.5,27.47,0.0
+70.0,2.0,1,100.0,2.0,inf,2.0,36.63,0.0
+70.0,3.0,1,100.0,3.0,inf,3.0,54.94,0.0

ob_intraday/output/trades.csv

@@ -0,0 +1,2 @@
+direction,entry_idx,exit_idx,entry_time,exit_time,entry_price,exit_price,exit_reason,zone_id,zone_score,zone_top,zone_bottom,stop,target,risk_points,pnl_points_gross,cost_points,pnl_points,r_multiple,pnl_rupees,bars_held
+short,1133,1134,2026-05-21 09:55:00+05:30,2026-05-21 10:00:00+05:30,23979.95,23943.3244,tp,20,90.62,23991.0,23980.0,23998.2628,23943.3244,18.3128,36.6256,0.0,36.6256,2.0,2746.92,1

ob_intraday/run.py

@@ -0,0 +1,97 @@
+"""CLI orchestrator: data -> detect -> backtest -> report -> validate -> sweep.
+
+Examples
+--------
+Live (needs a valid Kite token in tokens.json / KITE_ACCESS_TOKEN)::
+
+    python -m ob_intraday.run --years 2
+
+Use the cached CSV if present, otherwise synthesise so the pipeline still runs::
+
+    python -m ob_intraday.run --synthetic
+
+Just the sweep on already-cached data::
+
+    python -m ob_intraday.run --sweep-only
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from ob_intraday.config import Config, OUTPUT_DIR
+from ob_intraday import data_download as dl
+from ob_intraday import backtest as bt
+from ob_intraday import validation as val
+from ob_intraday import sweep as sw
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Intraday order-block backtest")
+    ap.add_argument("--years", type=float, default=2.0)
+    ap.add_argument("--refresh", action="store_true", help="force re-download")
+    ap.add_argument("--synthetic", action="store_true",
+                    help="fall back to synthetic data if live download fails")
+    ap.add_argument("--min-score", type=float, default=None)
+    ap.add_argument("--rr", type=float, default=None)
+    ap.add_argument("--no-plots", action="store_true")
+    ap.add_argument("--no-validation", action="store_true")
+    ap.add_argument("--no-sweep", action="store_true")
+    ap.add_argument("--sweep-only", action="store_true")
+    args = ap.parse_args(argv)
+
+    cfg = Config()
+    if args.min_score is not None:
+        cfg = cfg.with_overrides(min_score=args.min_score)
+    if args.rr is not None:
+        cfg = cfg.with_overrides(rr_target=args.rr)
+
+    print("== Loading data ==")
+    df = dl.get_data(cfg, years=args.years, allow_synthetic=args.synthetic,
+                     refresh=args.refresh)
+    print(f"   {len(df):,} bars  {df['timestamp'].min()} -> {df['timestamp'].max()}")
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    if args.sweep_only:
+        _do_sweep(df, cfg)
+        return
+
+    print("\n== Backtest ==")
+    res = bt.run_backtest(df, cfg)
+    for k, v in res.metrics.items():
+        print(f"   {k:22}: {v}")
+    print(f"   detected zones        : {len(res.detector.zones)}")
+
+    res.trades.to_csv(OUTPUT_DIR / "trades.csv", index=False)
+    monthly = bt.monthly_pnl(res.trades, cfg)
+    monthly.to_csv(OUTPUT_DIR / "monthly_pnl.csv", index=False)
+    print("\n== Monthly P&L ==")
+    print(monthly.to_string(index=False) if not monthly.empty else "   (no trades)")
+
+    if not args.no_plots:
+        p = bt.plot_equity(res)
+        print(f"\n   equity curve -> {p}")
+    if not args.no_validation:
+        paths = val.plot_random_trades(res, n=20)
+        print(f"   {len(paths)} validation charts -> {OUTPUT_DIR / 'validation'}")
+    if not args.no_sweep:
+        _do_sweep(df, cfg)
+
+
+def _do_sweep(df, cfg):
+    print("\n== Sweep (min_score x RR) ==")
+    table = sw.run_sweep(df, cfg)
+    table.to_csv(OUTPUT_DIR / "sweep.csv", index=False)
+    print(sw.format_table(table))
+    print(f"\n   sweep -> {OUTPUT_DIR / 'sweep.csv'}")
+
+
+if __name__ == "__main__":
+    main()

ob_intraday/strategy.py

@@ -0,0 +1,85 @@
+"""Entry/exit *rules* for the order-block strategy (no market interaction here).
+
+The sequential simulation lives in :mod:`ob_intraday.backtest`; this module is
+the pure decision layer so the rules can be unit-tested in isolation.
+
+Spec:
+* Long  = swing trend bullish, an active bull OB with score >= min_score, the
+  bar's low enters the zone, and the bar closes back at/above the zone top.
+  Enter next bar's open. Shorts are mirrored.
+* SL = zone far edge -/+ 0.25*ATR(10); TP = rr_target * R.
+* Entries only 09:30-14:30; force flat at 15:10; one attempt per zone; one
+  position at a time.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import time as dtime
+from typing import Optional
+
+from .config import Config
+from .detector import Zone
+
+
+def _hhmm(s: str) -> dtime:
+    hh, mm = str(s).split(":")
+    return dtime(int(hh), int(mm))
+
+
+def within_entry_window(ts, cfg: Config) -> bool:
+    t = ts.time()
+    return _hhmm(cfg.entry_start) <= t <= _hhmm(cfg.entry_cutoff)
+
+
+def at_or_after_square_off(ts, cfg: Config) -> bool:
+    return ts.time() >= _hhmm(cfg.square_off)
+
+
+def long_trigger(low: float, close: float, zone: Zone) -> bool:
+    """Bar dipped into the bull zone (low <= top) and closed back above it."""
+    return low <= zone.top and close >= zone.top
+
+
+def short_trigger(high: float, close: float, zone: Zone) -> bool:
+    """Bar poked into the bear zone (high >= bottom) and closed back below it."""
+    return high >= zone.bottom and close <= zone.bottom
+
+
+@dataclass
+class Levels:
+    entry: float
+    stop: float
+    target: float
+    risk: float          # |entry - stop|, i.e. 1R in points
+
+
+def compute_levels(direction: str, entry_price: float, zone: Zone,
+                   atr_sl: float, cfg: Config) -> Optional[Levels]:
+    pad = cfg.sl_atr_mult * (atr_sl if atr_sl and atr_sl == atr_sl else 0.0)
+    if direction == "bull":
+        stop = zone.bottom - pad
+        risk = entry_price - stop
+        if risk <= 0:
+            return None
+        target = entry_price + cfg.rr_target * risk
+    else:
+        stop = zone.top + pad
+        risk = stop - entry_price
+        if risk <= 0:
+            return None
+        target = entry_price - cfg.rr_target * risk
+    return Levels(entry=entry_price, stop=stop, target=target, risk=risk)
+
+
+def select_zone(result_zones, t: int, direction: str, cfg: Config) -> Optional[Zone]:
+    """Best eligible (active, score>=min, not yet attempted) zone at bar ``t``.
+    Highest score wins; ties -> most recently created."""
+    best: Optional[Zone] = None
+    for z in result_zones:
+        if z.direction != direction or z.attempted or not z.active_at(t):
+            continue
+        if z.score < cfg.min_score:
+            continue
+        if best is None or (z.score, z.created_idx) > (best.score, best.created_idx):
+            best = z
+    return best

ob_intraday/sweep.py

@@ -0,0 +1,41 @@
+"""Small parameter sweep over min_score x RR (no optimisation beyond this grid).
+
+Reuses one detection pass per RR-independent config where possible: the detector
+only depends on ``min_score``/``rr_target`` at the *strategy* layer, not the
+detection layer, so we detect once and re-run the cheap engine for every cell.
+"""
+from __future__ import annotations
+
+import pandas as pd
+
+from .config import Config, SWEEP_MIN_SCORE, SWEEP_RR
+from . import detector as det
+from . import backtest as bt
+
+
+def run_sweep(df: pd.DataFrame, cfg: Config,
+              min_scores=SWEEP_MIN_SCORE, rrs=SWEEP_RR) -> pd.DataFrame:
+    # Detection is independent of min_score/rr -> compute once and reuse.
+    dres = det.detect(df, cfg)
+    rows = []
+    for ms in min_scores:
+        for rr in rrs:
+            c = cfg.with_overrides(min_score=float(ms), rr_target=float(rr))
+            # zones carry an 'attempted' flag mutated by the engine; reset it.
+            for z in dres.zones:
+                z.attempted = False
+            res = bt.run_backtest(df, c, detector_result=dres)
+            m = res.metrics
+            rows.append(dict(
+                min_score=ms, rr=rr, trades=m["trades"], win_rate=m["win_rate"],
+                avg_R=m["avg_R"], profit_factor=m["profit_factor"],
+                expectancy_R=m["expectancy_R"], total_points=m["total_points"],
+                max_dd_points=m["max_drawdown_points"],
+            ))
+    return pd.DataFrame(rows)
+
+
+def format_table(sweep_df: pd.DataFrame) -> str:
+    cols = ["min_score", "rr", "trades", "win_rate", "avg_R", "profit_factor",
+            "expectancy_R", "total_points", "max_dd_points"]
+    return sweep_df[cols].to_string(index=False)

ob_intraday/validation.py

@@ -0,0 +1,99 @@
+"""Visual QA: save candlestick snapshots of random trades with the OB zone drawn.
+
+For each sampled trade we render ~100 surrounding 5-minute candles (matplotlib,
+no extra deps), shade the order-block zone, and mark entry, exit, stop and
+target — so signals can be eyeballed against TradingView.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from .config import Config, OUTPUT_DIR
+from .backtest import BacktestResult
+
+
+def _draw_candles(ax, sub: pd.DataFrame, x):
+    up = sub["close"] >= sub["open"]
+    for xi, (_, r), is_up in zip(x, sub.iterrows(), up):
+        color = "#26a69a" if is_up else "#ef5350"
+        ax.vlines(xi, r["low"], r["high"], color=color, lw=0.7)
+        lo, hi = sorted((r["open"], r["close"]))
+        ax.add_patch(_bar_rect(xi, lo, hi, color))
+
+
+def _bar_rect(xi, lo, hi, color):
+    import matplotlib.patches as mpatches
+    height = max(hi - lo, 1e-6)
+    return mpatches.Rectangle((xi - 0.3, lo), 0.6, height, color=color,
+                              alpha=0.9, linewidth=0)
+
+
+def plot_random_trades(result: BacktestResult, n: int = 20, window: int = 100,
+                       seed: int = 11, out_dir: Path | None = None) -> list[Path]:
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    import matplotlib.patches as mpatches
+
+    trades = result.trades
+    if trades.empty:
+        return []
+    out_dir = Path(out_dir or (OUTPUT_DIR / "validation"))
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    d = result.detector.df.reset_index(drop=True)
+    rng = np.random.default_rng(seed)
+    k = min(n, len(trades))
+    picks = rng.choice(len(trades), size=k, replace=False)
+
+    half = window // 2
+    paths = []
+    for rank, ti in enumerate(sorted(picks)):
+        tr = trades.iloc[ti]
+        eidx = int(tr["entry_idx"])
+        lo = max(0, eidx - half)
+        hi = min(len(d), eidx + half)
+        sub = d.iloc[lo:hi].reset_index(drop=True)
+        x = np.arange(len(sub))
+        entry_x = eidx - lo
+        exit_x = int(tr["exit_idx"]) - lo
+
+        fig, ax = plt.subplots(figsize=(13, 6))
+        _draw_candles(ax, sub, x)
+
+        # order-block zone shaded across the visible window
+        ax.add_patch(mpatches.Rectangle(
+            (0, tr["zone_bottom"]), len(sub) - 1, tr["zone_top"] - tr["zone_bottom"],
+            color="#42a5f5" if tr["direction"] == "long" else "#ffa726",
+            alpha=0.18, linewidth=0))
+        ax.axhline(tr["zone_top"], color="#1e88e5", lw=0.8, ls=":")
+        ax.axhline(tr["zone_bottom"], color="#1e88e5", lw=0.8, ls=":")
+
+        # stop / target
+        ax.axhline(tr["stop"], color="#c62828", lw=0.9, ls="--", label="stop")
+        ax.axhline(tr["target"], color="#2e7d32", lw=0.9, ls="--", label="target")
+
+        # entry / exit markers
+        ax.scatter([entry_x], [tr["entry_price"]], marker="^" if tr["direction"] == "long" else "v",
+                   color="black", s=90, zorder=5, label="entry")
+        if 0 <= exit_x < len(sub):
+            ax.scatter([exit_x], [tr["exit_price"]], marker="x", color="purple",
+                       s=90, zorder=5, label="exit")
+
+        ax.set_title(
+            f"{tr['direction'].upper()} {tr['entry_time']}  "
+            f"score={tr['zone_score']}  reason={tr['exit_reason']}  "
+            f"R={tr['r_multiple']}  pnl={tr['pnl_points']}pts")
+        ax.set_xlabel("bar (relative)")
+        ax.set_ylabel("price")
+        ax.legend(loc="best", fontsize=8)
+        ax.grid(alpha=0.25)
+        fig.tight_layout()
+        p = out_dir / f"trade_{rank:02d}_{tr['direction']}_{pd.to_datetime(tr['entry_time']):%Y%m%d_%H%M}.png"
+        fig.savefig(p, dpi=100)
+        plt.close(fig)
+        paths.append(p)
+    return paths

ob_portfolio/__init__.py

@@ -0,0 +1,10 @@
+"""Intraday order-block *options portfolio* backtest over NSE F&O stocks.
+
+Sibling of :mod:`ob_intraday`: it reuses that package's proven, unit-tested
+detection (`ob_intraday.detector`) and pure signal rules (`ob_intraday.strategy`)
+unchanged, and adds the multi-symbol data layer, the options execution model and
+the cross-symbol portfolio engine that are the point of this project.
+
+Relative imports throughout keep it from colliding with the repo's top-level
+``config.py`` / ``strategy.py``.
+"""