Every directory, every subsystem, every strategy.

Contents

The repository has three trees that matter: bot/ (the engine), site/ (this dossier you're reading), and research/ (a paper trail of source-of-truth notes). Below is a fully traversed map. Skip with the table of contents.

01 — Repository map

The repo separates concerns hard: the engine never reads from site/, and the site never imports Python. The only contract between the two is a small set of JSON files written by build scripts in bot/scripts/ and read by static pages in site/.

Two design choices to call out. First, nothing in site/ imports anything from bot/ — the bridge is a small set of JSON files written into site/data/ by scripts. That makes the site a deployable static artifact without a Python runtime on the edge. Second, research/ is read-only narrative — methodology notes the bot is built from, not configuration the bot consumes. Whenever you see a number in the bot whose source isn't obvious, the chain leads back to a markdown file in research/.

02 — Data layer

Everything starts here. The bot operates point-in-time: at any historical bar, the only data visible is what was knowable on that day. The data layer is the contract that enforces it.

Indicators — lib/indicators.py

A small library of pure functions over a bars frame. None of them store state, all of them are written so the result at index i depends only on rows ≤ i. The set:

Bars & caches — lib/data/

Eleven files. Daily bars come from Massive.com (Polygon-compatible, ~5,300 US common stocks cached since 2010). Intraday 1-minute bars come from Polygon (Stocks Starter tier — 5y of history, no per-minute cap, $29/mo). Both are cached locally so backtests don't pay network round-trips on every reload.

The universe scanner

The corpus rule (Kullamägi, episode 212): trade only stocks that are in the top 1–2% of returns simultaneously across multiple lookback horizons. The old version of this bot hardcoded 25–40 megacap tickers per strategy — which is the dominant reason the original backtests lost money, because megacaps don't have ADR ≥ 4 and they aren't where breakouts live. The current implementation:

~5,300 US common stocks (cached daily bars)
                  │
                  ▼
   universe_scanner.leader_universe(as_of, filters)
   ─ cross-sectional percentile rank of ROC over 1m / 3m / 6m
   ─ keep names in top 15% on at least 2 of 3 timeframes
   ─ require ADR ≥ 4, $5M dollar volume, close above 50-SMA
   ─ exclude biotech (sector blow-up risk)
   ─ sort by composite momentum score; take top N
                  │
                  ▼
   Cached as data_cache/universes/{key}.json (cold ~30s, warm instant)
                  │
                  ▼
   Runners rebuild every Monday — strategies scan only this pool

The UniverseFilters dataclass exposes top_n (200 for breakout, 300 for episodic-pivot and shorts), min_dollar_volume, min_adr_pct, momentum_periods, and momentum_pctile_min. Configs in bot/backtests/configs_swing/ set the "dynamic_leader" universe and override these values per strategy. A 3-year backtest performs roughly 150 weekly rebuilds; the cache means a re-run is effectively free.

03 — Regime gate

A single-file subsystem with one job: decide whether the broad tape is hospitable to long entries. lib/regime/spy_regime.py implements the corpus rule — SPY's 10-day SMA above the 20-day SMA, and both rising over the past five bars. When the gate is closed, swing-long signals don't generate. Shorts are not gated; they want a hostile tape.

The regime gate is intentionally simple. The corpus is unanimous on this point: in every drawdown the bot has tested through, the regime gate would have prevented the worst trades. Cleverer regime detection adds parameters, parameters get over-fit, over-fit regime models miss the next regime change. Two moving averages on SPY is the lowest-degree-of-freedom rule that actually works.

04 — Strategy contract

Every strategy in the repo derives from one tiny abstract base class. The contract is what makes it possible to wire dozens of setups into a single runner without bespoke glue.

lib/setups/base.py

Two pieces:

• Signal — a dataclass capturing one trade idea: symbol, side (long/short), entry, stop, target, risk_pct (fraction of equity risked if stop is hit), setup name, trader attribution, rationale, timestamp. The dataclass exposes a notional_pct() method that converts risk-to-stop into the leverage-capped notional allocation a runner should use.
• SetupModule — abstract base class with three methods every strategy must implement:
  • precompute(bars) — derive any indicators that need to exist before scanning. Pure function over the bars frame, must be point-in-time-safe.
  • scan(bars, context) — return a list of Signals (often zero, occasionally one, rarely many) given the precomputed bars and runner context (date, regime, open positions, universe).
  • exit_rules(position, bars) — given an open position and the latest bars, return either None (hold) or an exit instruction (price, reason).

The contract is deliberately narrow. The runner owns dates, position-sizing, slippage, fees, journaling, regime gates, theme caps, and the discipline overlays. The strategy module owns one thing: what is the setup, and where does the stop go. When a new strategy is added, the diff is one file in setups_swing/ or setups_intraday/, plus one YAML in configs_*/. No runner changes.

05 — Active swing setups

Seven daily-bar strategies are currently wired into bot/scripts/paper.py as ACTIVE_STRATEGIES. Three are the Kullamägi corpus implementations carried since the rebuild; four are novel mechanics added in the last commit cycle.

clv       = ((close - low) - (high - close)) / (high - low)   in [-1, +1]
signed_dv = clv * close * volume
20-day sum of signed_dv = "absorbed dollar flow" with directional bias

annualised_5d  = (1 + roc_5d)^(252/5)  − 1
annualised_21d = (1 + roc_21d)^(252/21) − 1
annualised_63d = (1 + roc_63d)^(252/63) − 1
required:  annualised_5d  >  annualised_21d  >  annualised_63d  >  0

06 — Swing research shelf

Six additional swing modules sit in lib/setups_swing/ with YAML configs in configs_swing/, but are not wired into paper.py. They exist for backtesting, comparison, and possible future promotion. They're listed here so the inventory is complete.

07 — Intraday setups

Fourteen minute-bar strategies live in lib/setups_intraday/. Two are paper candidates with configs in configs_intraday/ wired into ACTIVE_INTRADAY_CANDIDATES in paper.py. The other twelve are research-only — promising on early samples, awaiting either parameter tuning or a longer window before they earn a place in the candidate set.

Paper candidates

rvol      = rolling 30-bar stdev of close-to-close 1-min returns
low       = rvol < 20th pct of last 60 bars
high      = rvol > 80th pct of last 60 bars
trigger   = 5+ consecutive low bars, current bar high,
            AND |close − open| / (high − low) > 0.7  (decisive bar)
direction = sign(close − open)
stop      = prior 5-bar swing low / high
target    = 5R, trail-after-2.5R buffer 1.0R
guards    = skip first 60 minutes; one trade per session per symbol

Research-only intraday modules

08 — Discipline overlays

A signal is necessary but not sufficient. Two cross-cutting overlays sit between strategy modules and the broker, and they have authority to veto entries the strategies would otherwise take. Both are research-active for swing and live for intraday paper.

Breitstein harness — lib/discipline/breitstein.py

Lance Breitstein's teaching survives in this bot as a discipline harness rather than a signal generator. The harness exposes:

1. VWAP regime gate. Blocks fade-side entries if the stock has been on the wrong side of VWAP for 2+ of the last 10 bars.
2. Prior-bar confirmation (opt-in). Long entries require close > prior bar high.
3. Prior-bar trailing stop. Once a trade is in profit, the stop ratchets to the prior bar's low (long) or high (short) on each new bar.
4. Multi-timeframe size-up. 25% larger position when intraday and daily trends align.
5. Quality tiers (A/B/C) — risk multipliers attached to setup quality classification.

What is deliberately not mechanized: Breitstein's "A+ capitulation fade." It's pure tape-reading and attempts to code it produce the canonical "bot shorts the bottom tick" disaster. The decision to leave that behaviour out is a stronger expression of his teaching than coding a poor proxy would be.

Mistake filters — lib/discipline/mistake_filters.py

Stateful guardrails that reset daily and update on each closed trade:

1. Cool-down after losses — after N consecutive losing trades on the same day (default 3), no new entries.
2. Hard daily loss cap — at −1.5% of equity, all new entries halt for the day.
3. Friday afternoon block — no new entries after 14:30 ET on Friday (no-Friday rule from the corpus, with an afternoon cushion).
4. Session-edge guard — skip the first 15 minutes (open auction noise) and the last 15 minutes (close imbalance) of the session.

The MistakeFilters object wraps three calls: reset_day() at the open, on_trade_close(pnl_pct) from the runner, and approve_entry(ts) before any new order. The runner refuses to place an entry if the filter says no.

Theme cap (in the runner)

The corpus pattern: when one biotech blows up, ten do. The swing runner caps concurrent positions per theme bucket at 2–3 (configurable). Sector classification comes from lib/data/sectors.py; the cap is applied at signal acceptance, not at exit.

09 — Risk & sizing

The accounting unit is risk-percent, not notional-percent. This is the single biggest difference between this bot and most retail bot frameworks — and the source of the most common confusion when reading the trades CSV.

The two numbers

Signal.risk_pct is the fraction of equity at risk if the stop is hit. A signal with risk_pct = 0.5 means: if this trade goes from entry to stop, the account drops 0.5%. This is independent of how big the position is in dollars.

The runner converts that to notional via:

notional_pct = min( risk_pct × entry / |entry − stop| ,  1.0 )

No leverage. A tight stop + small risk-percent ⇒ small risk in dollars but possibly large notional (the cap is what prevents over-allocation). A wide stop + same risk-percent ⇒ small notional. Both risk_pct and notional_pct are written to trades.csv for every closed trade so the post-hoc accounting matches.

The asymmetric R-ratchet

R is the per-trade risk unit — (entry − stop) for longs, (stop − entry) for shorts. The four novel swing setups (AVD, TSC, ROCS, VRDC) and several intraday setups (TailHunter, RSAlpha, VolRegimeShift) lean hard on a stepped exit policy:

at +1R     do nothing
at +2R     lock stop at break-even (or +0.5R for tail-friendly setups)
at +3R     trail to prior swing structure
at +4R+    target / partial / trail tighter — strategy-specific

The asymmetry is the point: stops are tight, ratchets are slow. Most exits land between +2R and +5R; the rare +8–12R outliers do the heavy lifting. Calendar partials at days 3–5 were tested and removed across the swing trio after three independent corpus studies (HackerTrader 64% CAGR, Whos_Agent E0, mxteo) showed them hurting returns.

10 — Backtest pipeline

Every strategy is run through walk-forward backtests before any other consideration. The pipeline has four layers: runners, configs, results, sweeps. Each is a directory in bot/backtests/.

Runners

Config schema

Every strategy is paired with a YAML in configs_swing/ or configs_intraday/. The config is the single source of truth for what's being tested:

name: kullamaggie_breakout_swing
strategy: lib.setups_swing.kullamaggie_breakout_swing:KullamaggieBreakoutSwing
universe: dynamic_leader
universe_params:
  top_n: 200
  min_adr_pct: 4.0
start: 2021-01-01
end: 2026-04-27
oos_start: 2024-01-01           # in-sample / out-of-sample split
params: { ... strategy-specific knobs ... }
fees:    { slippage_pct: 0.001, commission_pct: 0.001 }
risk:    { max_concurrent_positions: 3, daily_loss_cap_pct: -0.015 }
vetting_thresholds:
  min_oos_profit_factor: 1.5
  min_sharpe: 1.0
  max_drawdown_pct: 0.20
  min_trades: 30
  max_top5_concentration: 0.60

Results layout

Each run writes a directory under results_swing/ or results_intraday_rotating/:

• metrics.json — combined / in-sample / out-of-sample metrics: Sharpe, profit factor, win rate, CAGR, max drawdown, top-5 concentration.
• equity_curve.csv — daily equity over time, used to render dashboard charts.
• trades.csv — every closed trade with entry, exit, P&L, risk_pct, notional_pct, exit reason.

There are 150+ result subdirectories under results_swing/ across the main strategies plus parameter sweep variants. The newest runs as of this writing — accrual_divergence_swing__20260428_032748 and vol_term_backwardation_swing__20260428_032619 — are the freshly tuned AVD and TSC candidates from commit dce3399.

11 — Promotion gates

A strategy doesn't reach paper trading by decree. bot/scripts/validate_promotions.py reads each strategy's metrics.json + trades.csv, checks them against the vetting_thresholds in the YAML, and writes site/data/promotion_report.json. The dashboard reads that file. Failure on any gate is a public failure.

The gates

1. Combined-metrics pass. Profit factor, Sharpe, max drawdown, CAGR — all must clear thresholds set per-strategy in the YAML.
2. Out-of-sample sample size. Configurable, default ≥ 30 trades. The OOS window is everything after oos_start in the config.
3. Out-of-sample profitability. OOS profit factor > 1.0 and OOS total P&L > 0.
4. Top-winner concentration. The top-5 trades must not exceed 60% of total profit (configurable). This catches strategies whose edge is one or two outliers.
5. Data quality. No missing-bar sequences over the test window.

Three sequential phases

1. Backtest vetting — automated, the gates above.
2. Paper trading — passed strategies run on Alpaca or IBKR paper for ≥ 90 days without intervention. Performance must persist.
3. Live capital — starts at $10k per strategy. Expands only on evidence.

Current state

The latest promotion_report.json shows none of the swing strategies promoted to paper yet — the OOS numbers are interesting (Episodic Pivot OOS PF 2.41, Parabolic Short OOS PF 1.76) but configured vetting still fails on return quality, sample size, or data completeness. The two intraday candidates (RSAlpha + VolatilityRegimeShift) are the closest — wired into paper.py as candidates, with the explicit caveat that a 6-month sample degraded versus the 3-month sample and live paper validation is required before any further promotion.

12 — Paper orchestrator

bot/scripts/paper.py is the command bridge between the bot and a paper-broker connection. Three subcommands.

paper.py brief

Pre-market, read-only. Prints today's watchlist (the universe for the week), open positions, cash balance. No execution. The morning briefing.

paper.py scan [--execute]

End-of-day. Loads today's bars for every strategy's universe, calls strategy.scan(), prints proposed signals with rationale. The --execute flag is the safety: without it, signals are inspected; with it, they're submitted via lib/broker/alpaca.AlpacaBroker.

paper.py manage [--execute]

Daily position management. Loads open positions, computes the Breitstein ratchet trail + MA trail + hard stops, prints the order adjustments needed. --execute modifies orders.

Active set as of dce3399

ACTIVE_STRATEGIES = [
    "kullamaggie_breakout_swing",
    "kullamaggie_episodic_pivot_swing",
    "kullamaggie_parabolic_short_swing",
    "vol_term_backwardation_swing",
    "accrual_divergence_swing",
    "roc_acceleration_swing",
    "coil_release_swing",
]

ACTIVE_INTRADAY_CANDIDATES = [
    "rs_alpha_long_rotating",
    "volatility_regime_shift_rotating",
]

Every action is appended to bot/paper/ledger.jsonl as a JSON line — strategy, symbol, side, price, size, rationale, broker response. The ledger is the long-term audit trail; the site/data/all_trades.json compilation pulls from it (for paper) and from backtest trades.csv (for backtests).

13 — Site & data flow

The site is a static deployment. Each panel reads a JSON file generated by a script in bot/scripts/. The flow:

bot/backtests/results_swing/<run>/metrics.json     ──┐
bot/backtests/results_swing/<run>/equity_curve.csv ──┤    build_dashboard.py
bot/backtests/results_swing/<run>/trades.csv       ──┴───►  site/data/dashboard.json   ──► dashboard.html
                                                            site/data/all_trades.json   ──► trades.html

bot/backtests/configs_swing/*.yaml                ──┐
bot/backtests/results_swing/<run>/metrics.json    ──┤   validate_promotions.py
bot/backtests/results_swing/<run>/trades.csv      ──┴───►  site/data/promotion_report.json ──► dashboard.html

bot/paper/ledger.jsonl                            ──┐    compile_trades.py (mode=paper)
                                                    └───►  site/data/all_trades.json   ──► trades.html

The site panels

14 — Recent trajectory

The shape of the last ten commits, in order from oldest to newest, tells you where the work has been moving.

1. Portfolio harness complete. A 3-year corpus test landed (Sharpe 1.14, 1015 trades) — the first end-to-end multi-strategy backtest the repo could run.
2. Sector confirmation gate. A sector-trend alignment filter was added to swing entries to avoid taking entries into sector-wide weakness.
3. Confirmation candle reverted. An experiment requiring a confirmation candle on breakouts was tested and rolled back — it didn't improve profit factor.
4. Intraday parabolic short. An intraday version of the Kullamägi parabolic short was added with a daily-context filter and timezone fix.
5. Daily-rotating intraday runner. The intraday execution framework was completed; the 2-strategy ensemble (RSAlpha + VolatilityRegimeShift) was live tested.
6. Swing trio tuned. Parameter sweeps on the three Kullamägi setups produced "3-of-3 momentum, looser shorts" — the parabolic-short filter relaxed for better OOS behaviour.
7. Status page replaced the dashboard. The dashboard panel was refactored to a command-bridge Status page tied to paper.py logs.
8. paper.py added. The brief / scan / manage orchestrator landed — the foundation for live trading and paper validation.
9. Four novel strategies + algorithmic R-ratchet. AVD, TSC, ROCS, VRDC were added; the asymmetric R-ratchet exit became load-bearing across the new modules. 5 of 7 strategies showed OOS profitability.
10. Sweep-tune AVD + TSC, wire all 7 into paper.py. The current state — seven swing strategies in the active set, two intraday candidates pending paper validation.

The arc: a single Kullamägi-only swing bot in mid-April; four novel mechanics plus a paper-trading orchestrator in late April; intraday ensemble candidates queued for live paper validation by early May. Tomorrow's commits will probably be parameter sweeps on the four novel modules to find their stable operating points.

15 — Glossary

Acronyms and unit conventions used throughout the codebase and this page.

ADR

Average Daily Range, expressed as a percent. Computed as mean(high/low) − 1 over a window (default 20 bars). Kullamägi's volatility filter — the bot rejects names with ADR < 4 because breakouts on quiet names don't have the gas to justify the strategy.

R

The per-trade risk unit. For a long, R = entry − stop; for a short, R = stop − entry. Targets and trails are expressed in multiples of R (2R, 4R, 6R) so they're scale-invariant across symbols and prices.

MFE

Maximum Favourable Excursion — the best unrealised profit a trade reaches before exit. Used by stepped profit-locks (e.g., "lock +2R after MFE +4R").

OOS

Out-of-sample. The period after oos_start in a backtest config. The bot's promotion gates require strategies to be profitable OOS, not just on the full sample.

PF

Profit factor. gross profit / gross loss. Above 1.0 is profitable; the promotion gate requires > 1.5 OOS for swing.

CAGR

Compound annual growth rate of the equity curve.

mDD / max DD

Maximum drawdown — the largest peak-to-trough decline in equity over the test window.

CIR

Close-in-range. (close − low) / (high − low) in [0, 1]. Used by the VRDC coil setup as a directional vote.

CLV

Close-location-value. ((close − low) − (high − close)) / (high − low) in [−1, +1]. Used by the AVD setup as a sign weight on dollar volume.

RV_n

Realized volatility over n trailing bars — used by the TSC term-structure backwardation setup.

VWAP

Volume-weighted average price. Anchored VWAP (from a chosen anchor index forward) is used by the Breitstein harness as a regime gate.

VCP

Volatility Contraction Pattern — Minervini's tightening-base structure, scored by volatility_contraction() in indicators.py.

EP

Episodic Pivot — the Kullamägi catalyst-gap setup.

ORB

Opening Range Breakout. opening_range_fractal.py uses a hierarchical OR_5 / OR_15 / OR_60 alignment.