Agent-Directed Wave Analysis Blueprint#

You can build this, but the first target should not be “predict the next price.” Build a causal system that identifies and labels multi-degree impulsive, corrective, and uncertain states using only Alligator, momentum, and Williams fractals; prediction and entry/exit policies should sit downstream of that shared structural language.

Separate four tasks#

These are different problems and should produce different artifacts.

Task	Question	Uses future bars?	Output
Historical detection	What structure occurred?	Yes	Research labels
Real-time classification	What is observable now?	No	Current state probabilities
Forecasting	What state or pivot may come next?	No	Probabilistic forecast
Trading policy	Should an entry, exit, or no-action occur?	No	Decision with invalidation

An ex-post wave count can use later fractals to explain history. A real-time system cannot know a Williams fractal at its center bar because the two bars to its right do not exist yet; the fractal becomes available two completed bars later.¹

This distinction is foundational: do not train an agent to predict using labels or features that would not have existed at the decision timestamp.

Indicator contract#

Before agents write code, establish one canonical mathematical specification.

Component	Canonical definition	Structural role	Main trap
Median price	$M_t=(H_t+L_t)/2$	Common Alligator/momentum input	Substituting close silently
Jaw	13-period SMMA of $M_t$, shifted 8 bars	Largest of the three balance scales	Confusing visual shift with future knowledge
Teeth	8-period SMMA, shifted 5 bars	Intermediate balance scale	Platform-specific alignment
Lips	5-period SMMA, shifted 3 bars	Short balance scale	Incorrect SMMA implementation
Up fractal	Middle high exceeds the two highs on each side	Confirmed candidate swing high	Confirmation requires two future bars
Down fractal	Middle low is below the two lows on each side	Confirmed candidate swing low	Same two-bar delay
Momentum	Must be defined explicitly	Impulse strength and weakening	“Momentum” has several incompatible meanings

The standard Alligator uses the 13/8, 8/5, and 5/3 SMMA configurations on median price. Store both computed_at and displayed_at; an agent must never shift a newly computed value backward in a way that exposes future information.²

Momentum decision#

Because your other indicators come from the Bill Williams system, the clean default is the Awesome Oscillator:

$$ AO_t=SMA_5(M)t-SMA{34}(M)_t $$

MetaTrader defines it as the difference between 5- and 34-period simple moving averages of median price. If by “momentum indicator” you instead mean a platform’s conventional Momentum function, freeze its exact specification—for example $C_t-C_{t-n}$ or $100C_t/C_{t-n}$—because those definitions are not interchangeable.³

Do not let an implementation agent make this choice implicitly.

Define wave degree#

A “degree” cannot remain a visual intuition. Give it an explicit data definition.

The safest approach within your indicator restriction is:

Apply the same five-bar fractal rule at several predefined bar intervals.
Treat each interval as a named degree.
Map higher-interval fractals back to their underlying base bars.
Require higher-degree pivots to contain lower-degree pivot sequences.
Record the interval and confirmation time with every pivot.

For example:

Degree	Bars analyzed	Purpose
D0	Base interval	Smallest observable swings
D1	Aggregation of D0 bars	Short wave structure
D2	Aggregation of D1 bars	Larger impulse/correction
D3	Aggregation of D2 bars	Context for lower degrees

The human should decide the aggregation relationships. The agent can test alternatives, but it should not redefine “degree” after seeing profitable results.

A secondary research path is multilevel wavelet decomposition: PyWavelets separates a series into approximation and detail coefficients at multiple scales. That is useful for investigating whether your manually perceived degrees correspond to measurable scales, but it should remain an offline research instrument until boundary effects and real-time causality have been tested.⁴

Operational wave language#

Avoid starting with a claim that an agent has found “the correct Elliott count.” Define observable structures first.

State vocabulary#

Use a small ontology at every degree:

impulse_up
impulse_down
corrective_up
corrective_down
transition
uncertain

The final two classes are important. Forcing every sequence into an impulse or correction will manufacture certainty and encourage agents to retrofit counts.

Impulsive evidence#

An upward impulse candidate can accumulate evidence from:

Confirmed alternating down/up fractals making directional progress.
Lips above Teeth above Jaw.
Positive slopes in the Alligator lines.
Expansion between the three lines.
Positive momentum during advancing legs.
A stronger momentum expansion in the central advancing portion.
Continued higher-degree alignment.

The downward definition mirrors this. These should initially be scored conditions, not all-or-nothing doctrine.

Corrective evidence#

A downward correction within a larger upward structure can accumulate evidence from:

A lower-degree sequence moving against the higher-degree direction.
Alligator lines contracting, tangling, or losing their directional ordering.
Momentum falling toward or below zero.
Countertrend momentum that remains weaker than the preceding impulse.
A three-leg fractal sequence rather than a stable five-leg directional sequence.

The resulting classification should be a probability or score accompanied by the contributing evidence.

Multiple hypotheses#

Wave interpretation is inherently ambiguous, especially before a structure is complete. Store several candidates:

{
  "degree": "D1",
  "as_of": "timestamp",
  "hypotheses": [
    {
      "state": "corrective_down",
      "phase": "candidate_C",
      "probability": 0.56,
      "pivots": ["p17", "p18", "p19", "p20"],
      "supporting_rules": ["momentum_negative", "alligator_compressing"],
      "violated_rules": [],
      "invalidation": "close_above_p18"
    },
    {
      "state": "impulse_down",
      "phase": "candidate_3",
      "probability": 0.31,
      "pivots": ["p16", "p17", "p18", "p19", "p20"],
      "supporting_rules": ["lower_fractals"],
      "violated_rules": ["higher_degree_up"]
    }
  ]
}

This gives you something intelligible to review: not merely the agent’s label, but its structural claim, evidence, alternatives, and invalidation.

Labels before models#

Your entry and exit annotations are useful, but they should not be the only labels. Otherwise the system learns your current trading policy instead of learning price structure.

Maintain four independent label families:

Label family	Example	Purpose
Structural	`corrective_down`, degree D1	Describe market structure
Event	Confirmed up fractal	Identify observable turning events
Forecast target	Next confirmed pivot is higher	Train predictive models
Policy	Enter long, exit, hold	Evaluate the trading process

Every research label should include:

Degree.
Start and end pivot identifiers.
Direction.
Complete, incomplete, or invalidated status.
Label creation timestamp.
Last bar the label was allowed to inspect.
Confidence.
Alternative interpretation.
Entry or exit annotation, if applicable.
Annotator and revision history.

Keep event_time separate from available_time. For a five-bar fractal centered at bar $t$, the event time is $t$, but the earliest causal availability is $t+2$.¹

Human responsibilities#

The human does not need to implement every numerical routine. You do need to control the semantics that determine what the routines mean.

You should personally define:

Which momentum formula is authorized.
The bar intervals corresponding to each degree.
Whether incomplete bars are excluded.
The structural state vocabulary.
What constitutes completion and invalidation.
Whether competing wave hypotheses are permitted.
The maximum acceptable signal delay.
The forecasting horizon and target.
What an entry or exit label means.
What level of uncertainty requires agent abstention.
Which historical period remains untouched as final evaluation data.

You should also adjudicate difficult examples. A small set of carefully reasoned “gold” annotations is more useful than thousands of unexplained entry labels.

Agent responsibilities#

Agent	Responsibility	Required artifact
Coordinator	Execute a fixed dependency graph; prevent agents from bypassing validation	Run manifest
Data curator	Ingest and validate immutable OHLC bars	Versioned bar dataset
Indicator engine	Compute only Alligator, authorized momentum, and fractals	Feature frame plus parity tests
Degree mapper	Construct nested fractal events across intervals	Fractal hierarchy
Structure agent	Generate competing impulse/correction hypotheses	Hypothesis graph
Annotation agent	Propose labels and identify uncertain examples	Annotation queue
Human-review agent	Present disagreements without deciding them	Review packet
Model agent	Train causal state and next-event models	Model card
Replay agent	Reconstruct information available at each historical bar	Causal replay log
Evaluation agent	Run walk-forward tests and sensitivity checks	Evaluation report
Red-team agent	Search for leakage, repainting, unstable counts, and overfitting	Failure report
Reporting agent	Explain predictions from stored evidence	Decision packet

The LLM should coordinate, explain, and inspect. It should not be the numerical authority calculating indicators or silently assigning pivots; those operations should be deterministic functions with tests.

Shared data contracts#

Your agents will understand one another only if they exchange typed artifacts rather than prose.

Fractal event#

fractal_id
instrument
interval
degree
kind: up | down
pivot_time
available_time
price
left_context_end
right_context_end
status: confirmed | superseded
algorithm_version

Wave hypothesis#

hypothesis_id
instrument
degree
as_of
direction
state
phase
pivot_ids[]
supporting_evidence[]
violations[]
confidence
invalidation_condition
parent_hypothesis_id
algorithm_version

Prediction#

prediction_id
as_of
information_cutoff
degree
target_definition
horizon
class_probabilities
predicted_pivot_interval
abstain
invalidation
model_version
feature_version

The information_cutoff should be mandatory. If any input timestamp is later than that field, the entire result is invalid.

Library map#

These libraries do not need to introduce additional trading indicators. They can supply signal-processing, labeling, classification, and validation machinery around your three authorized indicators.

Library/project	Useful role	Use now?	Caution
NumPy/Pandas	Bar alignment and deterministic feature tables	Yes	Freeze index and timezone semantics
SciPy `find_peaks`	Independent audit of your fractal pivots using distance and prominence controls	Later	Do not replace canonical fractals silently; `find_peaks` has its own peak definition ⁵
PyWavelets	Explore whether apparent degrees correspond to multiresolution components	Research	Border effects and noncausal reconstruction
`ruptures`	Offline segmentation of non-stationary sequences	Research	It performs offline change-point detection, so detected boundaries may use later observations ⁶
Statsmodels Markov models	Estimate probabilities of persistent latent states	Later	A statistical regime is not automatically an impulse or correction ⁷
STUMPY	Find repeated subsequences resembling labeled structures	Later	Similar shape does not imply the same causal state; motifs are based on subsequence distance ⁸
sktime shapelets	Learn interpretable subsequences associated with your human labels	Later	Requires a clean, non-leaking labeled dataset ⁹
Trend scanning	Independent research label for up/down/no-trend	Audit only	It may use forward windows and must never become an input to a live prediction ¹⁰
tsfresh	Automated feature exploration	Not in MVP	It generates very large feature sets and would weaken your indicator restriction; its current documentation describes over 1,200 extracted features ¹¹

GitHub findings#

python-taew is the clearest existing open-source Elliott-wave labeling reference found. It searches iteratively for possible wave points and can return structures of different sizes, but it relies heavily on Fibonacci validation—which you have excluded—and its author explicitly warns that it does not guarantee correct identification; use it as a research comparison, not as your foundation.

WilliamsIndicators contains Python implementations related to Alligator and SMMA. It is a small reference implementation rather than a production dependency: the source should be independently tested against an authoritative platform before adoption.

The older mlfinlab trend-scanning implementation is relevant to your labeling problem rather than your indicator set. It selects the forward window whose linear slope has the strongest t-value, producing up/down or up/flat/down labels.¹²

Academic evidence#

Academic support for automatic turning-point detection is stronger than support for uniquely correct Elliott counts. One probability-based method detects financial peaks and troughs by testing changes between consecutive rolling-regression slopes and evaluates the method with in-sample and out-of-sample data.¹³

Change-point research also distinguishes offline detection, which can use later observations and is usually more accurate, from online detection, which must respond immediately and normally incurs delay. This is directly analogous to the difference between your historical wave labels and live wave-state estimates.¹⁴

Evidence for Elliott-wave profitability is mixed:

A Tilburg thesis implemented Elliott-wave and Fibonacci strategies across four exchange rates but did not find enough significant profitability to reject the null hypothesis overall.¹⁵
A neural-network recognition study reported Elliott-pattern extraction, but its described test series contained only 259 EUR/USD values, making it weak evidence for broad market generalization.¹⁶
A 2024 study of NFT and cryptocurrency periodicity found that periodic models could explain some behavior but did not support the existence of Elliott waves in that market.¹⁷

A particularly relevant paper proposed ElliottAgents, a hierarchical multi-agent system with separate data, wave-analysis, backtesting, technical-analysis, advisory, and reporting roles. It reports improved pattern-prediction accuracy after historical backtesting, but the paper does not supply an openly linked reproducibility repository and evaluates several conditions with small pattern counts; its architecture is more useful than treating its reported performance as settled evidence.¹⁸

The defensible position is therefore:

Treat impulse and correction as an explicit, testable labeling hypothesis—not as a proven natural law of prices.

Modeling sequence#

Deterministic baseline#

Begin with no machine learning.

Calculate the three indicators exactly.
Confirm fractals causally.
Construct alternating pivot sequences.
Map pivots across degrees.
Generate scored impulse/correction hypotheses.
Compare those hypotheses with your manual annotations.
Record every disagreement.

This baseline tells you whether the conceptual definitions are workable. A complex model cannot repair an inconsistent label ontology.

Supervised classification#

Once annotations are stable, train a model to estimate:

$$ P(S_t \mid I_t) $$

where $S_t$ is the current structural state and $I_t$ contains only information available by time $t$.

Use features derived only from your authorized indicators:

Alligator ordering.
Alligator slopes.
Separation between lines.
Changes in separation.
Momentum level, sign, slope, and local extrema.
Time since each confirmed fractal.
Distance from price to the latest confirmed fractals.
Number and direction of recent fractal breaks.
Agreement between adjacent degrees.

Event forecasting#

Only after state classification is stable should the system estimate:

Probability that the next confirmed fractal is up or down.
Probability of structural invalidation.
Expected bars until the next confirmed pivot.
Probability of transition from correction to impulse.
Probability that the current candidate remains valid after additional bars.

Prefer ranges and calibrated probabilities over a single predicted price.

Entry and exit policy#

The policy should consume the state forecast; it should not define the state.

For example:

IF
  D2 state supports impulse_up
  AND D1 correction is probably completing
  AND D0 confirms an up fractal outside the Alligator
  AND momentum is improving
THEN
  propose long-entry candidate
ELSE
  no action

This remains within your three-indicator restriction. The policy agent must also output an invalidation condition and should be allowed to return no_action.

Honest validation#

Randomly shuffling financial bars is inappropriate because nearby feature windows and forward labels overlap. Use chronological walk-forward testing, remove training labels whose outcome intervals overlap the test interval, and apply an embargo where needed; purged-validation implementations describe these controls explicitly.¹⁹

Your evaluation should include several layers.

Layer	Metrics
Indicator correctness	Exact parity with a trusted platform
Fractal detection	Precision, recall, confirmation delay
Degree mapping	Parent-child consistency and pivot alignment
State labeling	Per-class precision/recall, macro F1, confusion matrix
Probability quality	Brier score and calibration curves
Structural stability	Percentage of counts revised after new bars
Forecasting	Next-pivot accuracy, timing error, invalidation rate
Human agreement	Inter-annotator agreement and unresolved ambiguity
Trading policy	Net expectancy, drawdown, turnover, costs and slippage
Robustness	Results by instrument, interval, and historical period

Keep one final period locked. No agent should inspect it during label design, parameter selection, prompt development, or model selection.

Required tests#

Your coordinator should reject a build unless all of these pass:

Alligator values match a trusted reference on a fixed fixture.
SMMA initialization and recursive updates are tested.
Chart displacement is separate from information availability.
A fractal centered at $t$ cannot appear before $t+2$.
Features contain no bar later than the prediction cutoff.
Incomplete bars cannot enter calculations.
Higher-degree bars close before their features become available.
Labels record their full look-forward interval.
Training and test label intervals do not overlap.
Every prediction can be reproduced from stored data and versions.
Parameter changes generate a new experiment identifier.
The system reports ambiguous structures rather than coercing a count.

Build order#

Foundation#

Freeze the indicator definitions.
Freeze bar and timestamp semantics.
Define degrees and the structural ontology.
Create 50–100 carefully annotated examples containing both clear and ambiguous cases.

Calculation engine#

Implement deterministic Alligator, momentum, and fractal functions.
Add platform-parity fixtures.
Create causal replay so the chart can be reconstructed exactly as it appeared at each historical bar.

Structural engine#

Build alternating confirmed-fractal sequences.
Create nested degrees.
Generate several candidate wave hypotheses.
Produce evidence and invalidation for every hypothesis.

Annotation workflow#

Let agents pre-label historical windows.
Review disagreement and low-confidence cases.
Version every correction.
Measure your own consistency by relabeling a hidden subset later.

Predictive layer#

Train a current-state classifier.
Add next-fractal and transition forecasts.
Calibrate probabilities.
Compare against deterministic and persistence baselines.

Policy layer#

Formalize your existing entry labels.
Define exit and invalidation separately.
Replay every decision with realistic availability and costs.
Run paper trading before any live execution.

Agent operating rules#

Give these constraints to the coordinating agent:

1. Use no market indicators other than Alligator, the authorized
   momentum definition, and Williams fractals.

2. Distinguish event time, confirmation time, display time,
   and decision time.

3. Never use a future-confirmed fractal in a historical feature row.

4. Never present an ex-post wave count as a real-time prediction.

5. Preserve competing wave hypotheses when evidence is ambiguous.

6. Every label must state its degree, inspected interval,
   confidence, and invalidation condition.

7. Every prediction must state its information cutoff.

8. Numerical calculations must come from deterministic,
   tested functions—not from LLM interpretation.

9. Do not optimize indicator parameters on final test data.

10. Report failed hypotheses, revisions, and abstentions;
    do not report only successful examples.

Recommended starting scope#

Start with one instrument, one base interval, three degrees, the standard Alligator, confirmed five-bar fractals, and one frozen momentum definition. The first deliverable should be a causal chart-replay and annotation system—not an autonomous trading agent—because that artifact establishes the shared language from which reliable model training, agent coordination, and entry/exit evaluation become possible.

²⁰²¹²²²³²⁴²⁵²⁶²⁷²⁸²⁹³⁰³¹³²³³³⁴³⁵³⁶³⁷³⁸³⁹⁴⁰⁴¹⁴²⁴³⁴⁴⁴⁵⁴⁶⁴⁷⁴⁸⁴⁹⁵⁰⁵¹⁵²⁵³⁵⁴⁵⁵⁵⁶⁵⁷⁵⁸⁵⁹⁶⁰⁶¹⁶²⁶³⁶⁴⁶⁵⁶⁶⁶⁷⁶⁸⁶⁹⁷⁰⁷¹⁷²⁷³⁷⁴⁷⁵⁷⁶⁷⁷⁷⁸⁷⁹⁸⁰⁸¹⁸²⁸³⁸⁴⁸⁵⁸⁶⁸⁷⁸⁸⁸⁹⁹⁰⁹¹⁹²⁹³⁹⁴⁹⁵⁹⁶⁹⁷⁹⁸⁹⁹¹⁰⁰¹⁰¹¹⁰²¹⁰³¹⁰⁴¹⁰⁵¹⁰⁶¹⁰⁷¹⁰⁸¹⁰⁹¹¹⁰¹¹¹¹¹²¹¹³¹¹⁴¹¹⁵¹¹⁶¹¹⁷¹¹⁸¹¹⁹¹²⁰¹²¹¹²²¹²³¹²⁴¹²⁵¹²⁶¹²⁷¹²⁸¹²⁹¹³⁰¹³¹¹³²¹³³¹³⁴¹³⁵¹³⁶¹³⁷¹³⁸¹³⁹¹⁴⁰¹⁴¹¹⁴²¹⁴³¹⁴⁴¹⁴⁵¹⁴⁶¹⁴⁷¹⁴⁸¹⁴⁹¹⁵⁰¹⁵¹¹⁵²¹⁵³¹⁵⁴¹⁵⁵¹⁵⁶¹⁵⁷¹⁵⁸¹⁵⁹¹⁶⁰¹⁶¹¹⁶²¹⁶³¹⁶⁴¹⁶⁵¹⁶⁶¹⁶⁷¹⁶⁸¹⁶⁹¹⁷⁰¹⁷¹¹⁷²¹⁷³¹⁷⁴¹⁷⁵¹⁷⁶¹⁷⁷¹⁷⁸¹⁷⁹¹⁸⁰¹⁸¹¹⁸²¹⁸³¹⁸⁴¹⁸⁵¹⁸⁶¹⁸⁷¹⁸⁸¹⁸⁹¹⁹⁰¹⁹¹¹⁹²¹⁹³¹⁹⁴¹⁹⁵¹⁹⁶¹⁹⁷¹⁹⁸¹⁹⁹²⁰⁰²⁰¹²⁰²²⁰³²⁰⁴²⁰⁵²⁰⁶²⁰⁷²⁰⁸²⁰⁹²¹⁰²¹¹²¹²²¹³²¹⁴²¹⁵²¹⁶²¹⁷²¹⁸²¹⁹²²⁰²²¹²²²²²³²²⁴²²⁵²²⁶²²⁷²²⁸²²⁹²³⁰²³¹²³²²³³²³⁴²³⁵²³⁶²³⁷²³⁸²³⁹²⁴⁰²⁴¹²⁴²²⁴³²⁴⁴²⁴⁵²⁴⁶²⁴⁷²⁴⁸²⁴⁹²⁵⁰²⁵¹²⁵²²⁵³²⁵⁴²⁵⁵²⁵⁶²⁵⁷²⁵⁸²⁵⁹²⁶⁰²⁶¹²⁶²²⁶³²⁶⁴²⁶⁵²⁶⁶²⁶⁷²⁶⁸²⁶⁹²⁷⁰²⁷¹²⁷²²⁷³²⁷⁴²⁷⁵²⁷⁶²⁷⁷²⁷⁸²⁷⁹²⁸⁰²⁸¹²⁸²²⁸³²⁸⁴²⁸⁵²⁸⁶²⁸⁷²⁸⁸²⁸⁹²⁹⁰²⁹¹²⁹²²⁹³²⁹⁴²⁹⁵²⁹⁶²⁹⁷²⁹⁸²⁹⁹³⁰⁰³⁰¹³⁰²³⁰³³⁰⁴³⁰⁵³⁰⁶³⁰⁷³⁰⁸³⁰⁹³¹⁰³¹¹³¹²³¹³³¹⁴³¹⁵³¹⁶³¹⁷³¹⁸³¹⁹³²⁰³²¹³²²³²³³²⁴³²⁵³²⁶³²⁷³²⁸³²⁹³³⁰³³¹³³²³³³³³⁴³³⁵³³⁶³³⁷³³⁸³³⁹³⁴⁰³⁴¹³⁴²³⁴³³⁴⁴³⁴⁵³⁴⁶³⁴⁷³⁴⁸³⁴⁹³⁵⁰³⁵¹³⁵²³⁵³³⁵⁴³⁵⁵³⁵⁶³⁵⁷³⁵⁸³⁵⁹³⁶⁰

⁂

Indigenous-AI Platform

Agent-Directed Wave Analysis Blueprint