feat(agents): add Bollinger Band Trader agent

[nikspz]

A directional volatility-band agent built around a two-stage decision: classify the volatility regime first, read %B second.

The same band touch is a fade in a flat range and a buy signal out of a squeeze. Treating the touch itself as the signal is where this indicator normally loses money, so every routine, veto and exit rule here serves that ordering.

What's added

agents/bollinger_band_trader/
  AGENT.md                                   # identity, the four setups, veto rules, risk defaults
  HOW_IT_WORKS.md                            # data sources, indicator math, classification table, limits
  validation.md                              # what was verified, what wasn't
  routines/band_state.py                     # primary read: classify + derive entry/stop/target
  routines/squeeze_screener.py               # rank a watchlist by squeeze tightness
  routines/band_trade_sizer.py               # risk sizing + pre-trade guardrails
  skills/bollinger_playbook/SKILL.md         # classify → size → deploy → manage
  strategies/bb_squeeze_breakout/strategy.md # optional loop playbook (defaults to dry_run)
tests/test_bollinger_band_trader.py          # 58 tests

The agent is useful at every layer: consulted with no loop running it answers band questions from the routines; given the strategy it can run the same logic unattended.

The four setups

Setup	Entry	Stop	Target
Squeeze breakout	close beyond the band	middle band	2R, then trail the mean
Band walk	pullback to the middle band	1 ATR past the mean	opposite band
Range reversion	at the band	0.5 ATR beyond it	middle band
Failed breakout	on the close back inside	beyond the failure extreme	middle band, then opposite

Three gates can turn any of them into no_trade: the higher-timeframe veto (never fade a 4h band walk), a reward:risk floor (1.5 continuation / 1.2 reversion), and a volume filter on breakouts.

Routines

band_state — BB(20, 2), %B, bandwidth, and the percentile rank of that bandwidth within its own 200-period history across 15m / 1h / 4h. The percentile is what makes this work across assets: raw bandwidth of 1.2% is a tight coil on a major and a dead-flat range on a small-cap. Adds a Keltner-containment check (the classic TTM squeeze) as an independent second squeeze test, plus Wilder ADX and a volume ratio, then emits one setup with concrete prices.

squeeze_screener — ranks a watchlist by bandwidth percentile ascending so the tightest coils surface first, and distinguishes a coil that is resting from one that is firing. A squeeze has no direction, so the output is explicitly a watchlist, not a set of trades.

band_trade_sizer — the only path to a position size. Fixed fractional risk (notional = risk_quote / stop_pct) so a wide-stop setup automatically gets a smaller position and every trade risks the same amount. Seven guardrails follow: portfolio known, stop on the protective side, stop distance 0.05–20%, risk ≤ 1%, leverage ≤ 5, notional above the exchange minimum, margin inside a 20% reserve. Any FAIL blocks the trade and no payload is emitted.

All indicator math is plain Python inside the routines — no pandas, no TA library — so the definitions are auditable in place.

Tests

uv run pytest tests/test_bollinger_band_trader.py — 58 tests, ~1.7s, no network and no Hummingbot server. Full suite: 286 passed, 5 skipped.

Beyond the unit checks, two are worth calling out:

• A reachability sweep asserts every classification verdict fires on realistic data. A branch that never fires is dead code, and this is what catches it.
• A 2,400-case fuzz runs every regime fixture against every trend verdict and asserts no emitted setup ever has an inverted stop or target. An inverted stop is an instant loss, not a bad trade.

Design decisions the tests forced

Three choices below look arbitrary in the diff. Each is there because the obvious
version was tried first and measurably failed. Each is pinned by a named regression test.

Expansion is checked before squeeze (_verdict). Bandwidth rank is computed from
history, so on the exact candle a coil breaks the rank is still low. Checking squeeze
first made the routine report squeeze_pending on the one bar the whole setup exists to
trade. → test_firing_coil_reads_as_expansion_not_squeeze

ADX is Wilder-smoothed, not the raw single-window DX that market_analyzer uses.
Raw DX saturates near 100 on any sustained directional push — and reaching a Bollinger
band is a directional push. Measured: across 600 synthetic ranges a band tag never once
produced a reversion_range verdict, so that setup was unreachable in practice. Note
this means the two agents report different ADX for the same market; this one is the
textbook figure. → test_adx_does_not_pin_at_100_in_a_range

A capped position size is a WARN row, not PASS. When the position cap or the reserve
reduces the size, the trade is still valid but risks less than the configured target. As
a PASS the operator had no signal that had happened. → test_capped_size_is_reported_as_a_warn_row

A fourth, smaller one: the band-walk threshold was %B >= 0.95, which a smooth trend
never reaches — it rides at 0.90–0.93. Relaxed to the top decile and gated on ADX > 25 so
a range cannot be mistaken for a walk.

Second commit: fixes from running it live

The agent was then run against live hyperliquid_perpetual data, which surfaced four more
defects that only appear at runtime:

• manage_routines was missing from the tools allowlist, so the agent could not call
  its own routines and silently did band math in-model instead. The allowlist is only
  enforced on pydantic-ai keys, so this was invisible under an ACP key.
• Routine invocations named the wrong tool in six places across AGENT.md, SKILL.md
  and strategy.md.
• strategy.md told the tick to query executors that are already pre-loaded in
  [CORE DATA], costing a round-trip and a retry-budget failure.
• extra="forbid" on the routine Configs — every field had a default, so a model
  passing symbol instead of trading_pair silently analysed BTC-USDT on Binance while
  reporting confidently about the requested pair.

Plus one repo-level fix in condor/acp/pydantic_ai_client.py: pydantic-ai's default
retries=1 is too tight for small models, which routinely mis-guess a tool schema once
and then abort the whole run.

Verified live: 1 tool call per tick, correct no_trade verdict with the higher-timeframe
veto applied, on a free model at $0.000000 per tick.

What is not validated

• No live exchange run. Every test uses synthetic candles through a fake client. Connector-specific response shapes are handled defensively but unproven — run band_state against a real server before launching a loop.
• No profitability claim. Nothing here is a backtest. The tests prove the agent computes what it says and refuses what it says — not that the setups make money. The thresholds (squeeze_rank, the R:R floors, the ADX split) are starting points to tune per market.
• No executor was created. Only the payload shape is checked, against mcp_servers/hummingbot_api/guides/position_executor.md. The strategy defaults to execution_mode: dry_run.

Full detail in agents/bollinger_band_trader/validation.md.