VWAP Regime AI [AxeAlgo]

16 أغسطس

OVERVIEW

VWAP Regime AI is an anchored VWAP (Volume-Weighted Average Price) with
standard-deviation bands, enhanced by a native, from-scratch k-means
clustering engine that classifies recent market volatility into three
regimes — Low, Medium, and High — and adapts the indicator's behavior
based on which regime is currently active.

At its foundation this is the same tool institutional desks use every
day: a running volume-weighted average price with bands around it, used
to judge where "fair value" sits and how far price has stretched away
from it. What this script adds on top is a genuine unsupervised machine
learning step that reads the market's own volatility and lets that
reading drive three things: how wide the bands are, which signal logic
is active, and how much the indicator should trust its own regime call
before acting on it.

This script is free and open-source. All calculations happen natively in
Pine Script on your own chart data.

============================================================
FULL TRANSPARENCY ABOUT THE "AI" IN THIS SCRIPT
============================================================

Pine Script cannot call an LLM, a remote model, or any external AI
service — TradingView does not allow outbound network requests from
indicators, and this script makes none. There is no hidden API call,
no "black box," and nothing running outside of what you can read in the
source code.

What "AI" means here specifically: this script implements k-means
clustering — a well-established unsupervised machine learning algorithm
— entirely in native Pine Script math and arrays. It groups a rolling
window of recent ATR (volatility) readings into three clusters by
repeatedly assigning each reading to its nearest cluster center and then
recomputing each center as the mean of everything assigned to it. This
publication states plainly what is and is not happening so nobody
mistakes this for predictive AI, sentiment analysis, or anything that
consults external data or forecasts the future. It classifies what has
already happened; it does not predict what will happen next.

============================================================
HOW IT WORKS
============================================================

VWAP & Standard Deviation Bands
--------------------------------
The core VWAP resets at the start of each new anchor period (Session,
Week, Month, Quarter, or Year — configurable) and accumulates a running
volume-weighted average from there. Standard deviation is calculated
using the same volume-weighted variance formula TradingView's own
built-in VWAP-with-bands tool. Up to three bands can be shown,
each set at a configurable standard-deviation distance from VWAP.

AI Volatility Clustering (K-Means)
------------------------------------
A rolling window of recent ATR readings (length and window size are both
configurable) is periodically re-clustered into three groups — Low,
Medium, High — using k-means. Reclustering happens every N bars rather
than every single bar, purely for performance; the live classification
of the current bar still updates continuously between reclusters.
Alongside the classification, the script computes a Confidence score
(0-100%): how much closer the current reading sits to its nearest
cluster than to its second-nearest one. A reading sitting right on a
cluster's center scores near 100%; a reading sitting on the boundary
between two regimes — an effectively ambiguous call — scores near 0%.
A "Minimum Regime Confidence" input lets you require a minimum score
before the regime is allowed to influence anything else in the script,
so an unconfident, boundary-line classification doesn't silently drive
behavior.

Adaptive Band Width
----------------------
When enabled, the standard-deviation band multipliers are scaled by a
per-regime factor: tighter in Low volatility, wider in High volatility,
instead of one fixed multiplier that's too tight in some conditions and
too loose in others. This only engages once the AI is both ready
(its lookback window has filled and it has run at least once) and
confident, per the Minimum Regime Confidence setting above.

Signal Logic — Mean Reversion, Breakout, or Auto
----------------------------------------------------
Two independent signal styles are built in, both measured off Band 2:
Mean Reversion looks for price crossing back inside the band from
outside (betting an extreme move snaps back toward VWAP); Breakout looks
for price crossing outside the band (betting the move has momentum to
keep running). "Auto" mode lets the detected volatility regime decide
which logic applies bar by bar — Low/Medium volatility defaults to Mean
Reversion, High volatility defaults to Breakout — falling back to Mean
Reversion whenever the AI isn't ready or confident enough to trust.

Three independent, stackable filters reduce noise on top of the raw
band cross:
- Bar-Close Confirmation: a cross only counts once the bar has fully
closed, filtering out intrabar wicks that reverse before the close.
- Signal Cooldown: blocks a new signal, in either direction, for a
configurable number of bars after the last one — aimed directly at
whipsaw (price crossing back and forth across a band repeatedly).
- Band Cross Buffer (hysteresis): requires price to clear a band by a
small extra distance, in standard deviations, rather than an exact
touch, so noise sitting right on the line doesn't keep re-triggering
crosses back and forth.

AI Volume Confirmation Filter
---------------------------------
The same k-means engine used for volatility is optionally reused on raw
volume, classifying each bar's volume as Low, Normal, or High. When
enabled, signals are only allowed on Normal-or-above volume, filtering
out low-conviction moves.

Secondary VWAP
-----------------
An optional second VWAP anchored to a different (typically higher)
period can be plotted alongside the primary one — for example a Weekly
VWAP behind a Session VWAP — for confluence, since multiple VWAP anchors
are commonly watched together rather than trusting a single one in
isolation. It is a reference line only; no bands are drawn for it.

Signal Track Record
-----------------------
An on-chart scorecard tracks, in a simple and fully model-free way, how
the signals have actually performed: each signal opens a virtual
position at that bar's close, and the next opposite-direction signal
closes it out, scored as a win or a loss purely on which way price
moved in between. No target or stop-loss assumption is built into this
score — see the Limitations section below for exactly what this number
does and does not tell you.

Status Table
---------------
An optional on-chart table shows the current regime and its confidence,
the active band scale, the current VWAP value, a "Stretch Score" (see
below), and the Signal Track Record numbers, all in one place.

Stretch Score
----------------
A signed z-score of how many standard deviations price currently sits
from VWAP. Because it's measured in the same standard deviations the
bands are drawn in, it stays consistent with whatever the adaptive band
width currently has in effect — a reading of +2.00 always means "sitting
on Band 2," whether that band is currently tight or wide.

============================================================
HOW TO USE THIS INDICATOR
============================================================

1. Start with the default settings and watch the status table for a
while before changing anything. Let the AI Volatility Clustering
lookback window fill (the table will show "Calibrating..." until it
has enough data) so the regime classification is meaningful.
2. Decide whether you want Mean Reversion, Breakout, or Auto signal
logic. Auto is a reasonable starting point since it adapts to
detected conditions automatically.
3. Watch the Confidence score alongside the regime label. If confidence
is frequently low on your instrument/timeframe, consider raising the
Minimum Regime Confidence input so the indicator falls back to
neutral behavior more readily instead of acting on ambiguous calls.
4. Use the Stretch Score to judge how extended price currently is
relative to VWAP in a way that stays consistent even as band width
adapts.
5. Treat the Signal Track Record as a rough, ongoing sanity check on
signal quality — not a backtest and not a promise (see Limitations).
6. This is a visual/analytical tool, not an auto-trading system. It
does not place trades. Any alerts it can generate are notifications
only.

============================================================
INPUT GROUPS (SUMMARY)
============================================================

VWAP Settings
- Anchor Period (Session / Week / Month / Quarter / Year)
- Source price used for the VWAP calculation

Secondary VWAP (Confluence)
- Show/hide toggle, its own anchor period, and its own color

Standard Deviation Bands
- Independent show/hide and distance (in standard deviations) for
three bands, plus a toggle for the gradient fill shading around them

AI Volatility Clustering (K-Means)
- Enable/disable the clustering engine
- ATR length used as the raw volatility reading that gets clustered
- Clustering lookback window (bars) and reclustering frequency
- Number of k-means refinement iterations per reclustering
- Adaptive band width toggle and the three per-regime scale factors
- Minimum Regime Confidence threshold

Signals
- Show/hide signal markers
- Signal Mode (Mean Reversion / Breakout / Auto)
- Volume confirmation filter toggle
- Bar-close confirmation toggle
- Signal cooldown (bars)
- Band cross buffer (hysteresis, in standard deviations)

Visuals
- Regime background highlight toggle
- Status table toggle and Signal Track Record toggle
- Colors for VWAP, each band, each regime, and each signal direction

============================================================
REPAINTING & REAL-TIME BEHAVIOR
============================================================

This script does not use any higher-timeframe security() calls and does
not look ahead — every value at every historical bar is a function of
data available up to and including that bar. Once a historical bar is
confirmed, its VWAP, bands, regime classification, and signals do not
change on subsequent chart loads or reloads.

Like any real-time indicator, values on the currently forming (unclosed)
bar update as new price/volume ticks arrive, and will settle once that
bar closes — this is standard behavior for any live indicator, not
repainting of historical data. If you want signal markers to appear only
after a bar has fully closed rather than updating intrabar, keep the
"Require Bar Close Confirmation" input enabled (it is on by default).

============================================================
LIMITATIONS — PLEASE READ
============================================================

- The Signal Track Record is a simplified, model-free heuristic, not a
backtest. It ignores commissions, spread, slippage, position sizing,
and any stop-loss/take-profit logic, and it scores a "trade" purely by
whether price was above or below the entry price when the next
opposite signal fired. It exists to give a rough, ongoing sense of
signal direction quality — it is not a performance guarantee and
should not be relied on as one.
- K-means clustering, like any clustering method, can produce a
misleadingly high confidence score if recent volatility (or volume)
readings happen to be nearly constant for an extended window — a rare
condition, more likely on thinly-traded instruments, but worth being
aware of.
- Regime classification and adaptive behavior depend on the Clustering
Lookback window filling with data first; expect "Calibrating..." on a
freshly loaded chart or a short history until then.
- This is a discretionary analysis tool intended to support your own
judgment, not a mechanical, guaranteed-signal system. No combination
of settings eliminates false signals entirely, which is why several
independent, adjustable filters (bar-close confirmation, cooldown,
hysteresis buffer, volume confirmation, regime confidence threshold)
are provided rather than relied on individually.

============================================================
RISK DISCLAIMER
============================================================

This script is provided for educational and informational purposes
only. It is not financial advice, and it is not a recommendation to buy
or sell any security or instrument. Trading and investing involve
substantial risk of loss and are not suitable for every investor. Past
performance — whether real, simulated, or shown via the on-chart Signal
Track Record — is not indicative of future results. Always do your own
research and consider consulting a licensed financial advisor before
making trading decisions. Use this indicator, and any alerts it
generates, entirely at your own risk.

18 أغسطس

ملاحظات الأخبار

- Status Table Updated
- Minor Bugs Fixed