Same Chart, Same Regime: Launching Context-Aware Pattern Matching

The Problem With Shape-Only Pattern Matching

For the past six months, Chart Library has answered one question: 'What did chart patterns that look like this do next?' We find the 10 closest historical matches across 24 million pattern embeddings and show you their forward returns.

This is useful, but it misses something obvious. A bull flag in a low-VIX bull market is not the same event as a bull flag forming during a credit spread blowout. The chart looks identical. The outcome probably isn't.

Academic research agrees. Bollerslev, Tauchen & Zhou (2009) showed the variance risk premium explains ~15% of quarterly equity return variation. Daniel & Moskowitz (2016) documented that momentum crashes in 'panic states' — high volatility regimes where the same price patterns reverse instead of continuing. Lo, Mamaysky & Wang (2000) found statistically significant information in chart patterns, but the economic magnitude was small because they conditioned on nothing.

So we fixed it.

The 12-Dimension Context Vector

Every pattern in our database now has a 12-dimensional context vector attached to it, capturing the market regime at the time the pattern occurred. The features are research-backed, not made up. The data sources are all free: FRED for yields and credit spreads, CBOE for VIX, SEC EDGAR for earnings dates (covering 2,000+ US-listed companies over 10 years), and our own daily_bars table for everything else.

• VIX level (percentile-ranked over 252 days)
• VIX term structure — VIX / VIX3M ratio (contango vs backwardation)
• Variance Risk Premium — VIX squared minus realized variance
• Yield curve — 10y minus 2y Treasury spread (normalized)
• Credit spread — ICE BofA US High Yield OAS percentile
• Market breadth — percentage of stocks above their 50-day moving average
• SPY 20-day trend (z-scored)
• Trailing 20-day realized volatility (percentile)
• Volume ratio — today's volume relative to 20-day average
• SPY correlation (20-day rolling)
• Earnings proximity — days to nearest earnings announcement
• Market cap bucket (log-normalized)

Two-Stage Search

The search now works in two stages. First, we do the same L2 similarity search on the 384-dimensional price shape embeddings — but fetch 50 candidates instead of 10. Second, we re-rank by context similarity using weighted L2 distance on the 12-dim context vector. You get back the 10 patterns that are similar in both shape AND regime.

The re-ranking happens in Python on 50 rows after the vector search returns. Total added latency: under 5ms. The pgvector index stays untouched.

You can control the blend with a new context_weight parameter on our API. context_weight=0 is shape-only (the old behavior, kept as default for backward compatibility). context_weight=0.05 is the recommended value — shape dominates, context adjusts. context_weight=1 flips it entirely to context-driven. On the website, you can toggle 'Regime-matched only' on any search result and the forward return statistics recalculate instantly.

What We Found

Before shipping we ran validation against our 16,438 forward tests with actuals. Results are honest — not every dimension mattered equally.

The strongest signal was match quality itself. Closer shape matches (Q1 of average distance) had 53.0% direction accuracy. Worst matches (Q4) had 47.4%. A 5.6 percentage point spread on the core matching metric.

VIX level conditioning produced a 4.8pp spread on direction accuracy and a 16.5pp spread on bullish signal win rates. When VIX is at its 96th-100th percentile, bullish signals hit 48.4%. At the 91st-93rd percentile, they drop to 28.5%. The signal isn't 'bullish patterns always work' — it's 'bullish patterns work differently in different fear regimes.'

Trailing volatility showed a 17.7pp spread on bearish win rates. Low-vol stocks with bearish pattern setups hit 85.2% within 5 days. High-vol stocks with the same setups hit 67.5%. Big difference. If you're shorting based on pattern signals, you want low-vol targets.

Volume ratio was weak (~1pp spread). Interest score was near-random. Not everything in the context vector carries equal weight — our hand-tuned weights reflect this.

Accuracy By Regime — Now Visible

Every prediction we make is tracked against actual outcomes. Now you can slice that track record by regime on our /track-record page. Pick a dimension (VIX level, trailing vol, breadth, SPY trend, variance risk premium, credit spread), pick a horizon (1/3/5/10 day), and see accuracy per quartile.

This is the trust signal. If your pattern matching claims to be useful, you should be able to say where it's most useful. We're not hiding the buckets where accuracy is weak — we're exposing them.

New Agent-First API Endpoints

We added seven new REST endpoints designed specifically for AI agent workflows. Previous MCP tools called these indirectly; now any HTTP client can hit them. A new format=agent query parameter on our analyze endpoint strips visualization data (fan chart paths, raw forward bars, share URLs) that LLMs can't use — response size drops about 80%, leaving more tokens for the agent's actual reply.

• GET /api/v1/market-context — one-call market awareness (indices, VIX, regime, sectors, crowding)
• POST /api/v1/portfolio/analyze — batch portfolio health for up to 20 symbols
• GET /api/v1/accuracy/by-regime — accuracy bucketed by any context dimension
• GET /api/v1/regime-win-rates — pattern reliability filtered by current regime
• GET /api/v1/exit-signal — position-specific exit recommendations
• GET /api/v1/pattern-degradation — are signals losing accuracy recently?
• GET /api/v1/risk-adjusted-picks — daily picks scored by risk-adjusted return potential

MCP Server v1.2.0

Our MCP server (pip install chartlibrary-mcp) now ships 23 tools, up from 19. The new ones consolidate common agent workflows. analyze_pattern now accepts a context_weight parameter (0 to 1) — set it to 0.05 for regime-aware matching. Server instructions were updated to guide LLM routing toward the consolidated tools first.

• get_market_context — first call an agent should make for any market question
• check_ticker — combines anomaly + volume + earnings in one call
• get_portfolio_health — the entire portfolio-monitoring workflow in one call
• get_regime_accuracy — transparency tool for agents answering 'does this system work in this market?'

What This Costs You

Nothing. Free tier access to /market-context, /accuracy/by-regime, and the regime-filter toggle on results. The website changes are already live for anyone who visits chartlibrary.io. The MCP server update is live on PyPI. Pattern results are enriched with context metadata whether you opt in to re-ranking or not.

If you're building an agent on our API, upgrade to chartlibrary-mcp 1.2.0 and start using get_market_context as the first call before any ticker analysis. That one change makes your agent immediately more market-aware.

What We're Still Working On

This is phase one. We'll publish the next accuracy report once we have 30K+ samples and the V5 embeddings are trained. The track record endpoint is public and updated nightly — you don't have to wait for a report to see how the system is doing. Open problems we're still working on:

• Outcome-aware embeddings (ViT v5) — training pattern embeddings where similar forward returns cluster together, not just similar shapes. In progress, blocked on reaching 30K+ forward test samples for training.
• Learned context weights — current weights are hand-tuned from research. At 50K+ forward tests we can cross-validate learned weights.
• Intraday context vectors — the current implementation covers daily regime only. Intraday conditioning (opening range, morning vs afternoon patterns) is a follow-up.
• Expanded earnings coverage — SEC EDGAR gives us 2,000 top-cap symbols; extending to the full Russell 3000 is next.