The AI build-out, floor by floor — and how to read its health.

What it measures

The ICE BofA US High-Yield option-adjusted spread (OAS) — the extra yield, in percentage points, that investors demand to hold the entire universe of US junk-rated corporate bonds over duration-matched Treasuries. It is the price of credit risk for exactly the kind of speculative, debt-financed issuers (neoclouds, AI-infrastructure SPVs, leveraged data-center buildouts) that fund an AI capex boom; because in a debt-financed mania the bond market reprices risk *before* equities crack, a widening HY OAS while stocks keep rallying is the single highest-value early-warning divergence — the literal "bonds flinch first" mechanism of the 1997 Asian crisis and the 2000 telecom bust.

Source & fetch

Live, from FRED. This is a fred-kind indicator. The upstream source is the St. Louis Fed FRED series BAMLH0A0HYM2 ("ICE BofA US High Yield Index Option-Adjusted Spread"), a daily series. In fetch_indicators.py the metadata entry (INDICATORS_META, id: "hy-oas") carries "fred": "BAMLH0A0HYM2", "unit": "%". The FRED branch of build_indicator() detects the "fred" key and calls:

``python history = fetch_fred(meta["fred"], start_date) ``

where start_date is the module-level constant HISTORY_START = "1900-01-01" — a sentinel that pulls the *full* available series and harmlessly clamps to the series' real inception (BAMLH0A0HYM2 begins in late 1996). fetch_fred() hits the REST endpoint https://api.stlouisfed.org/fred/series/observations with params series_id, api_key (read from a local .env, never committed), file_type=json, observation_start=start_date, and sort_order=asc. It is hardened against FRED's free-tier burst limit: up to FRED_MAX_RETRIES = 3 attempts, exponential backoff (FRED_BACKOFF_BASE = 1.0s → 1s/2s/4s) on HTTP 429 or 5xx, honoring any Retry-After header, and a fixed FRED_CALL_DELAY = 0.6s pause after each success so the several sequential FRED series don't go out as one burst. Missing observations (FRED returns ".") are filtered out, and each kept row becomes {"date": ..., "value": float(...)}. A total fetch failure raises RuntimeError rather than returning empty — and the orchestrator then marks the indicator "unknown" (excluded from scoring) instead of silently scoring a dead feed as healthy.

Cadence/history depth: the script is designed to run weekly via a scheduled task; each run re-pulls the full daily history from inception to present. No manual entry and no SentimenTrader CSV feed are involved for this indicator.

Calculation

There is no transformation — HY OAS is consumed as the raw FRED level in percentage points. The fetched history is sorted ascending; out["current"] is simply the most recent observation:

``python out["current"] = history[-1]["value"] # latest daily OAS, in % ``

The only "computation" is the state assignment, which runs through compute_state() using the explicit warn/critical bands rather than a derived statistic. Because the meta supplies both warn and crit, compute_state() takes its explicit-band path and the legacy ±10% rule is *bypassed* (the explicit bands override it). With trigger_type = "above" the logic is:

``python if current >= crit: state = "critical" # current >= 5.5 elif current >= warn: state = "warn" # 4.5 <= current < 5.5 else: state = "normal" # current < 4.5 ``

State maps to points for the composite via state_to_points(): normal → 100, warn → 50, critical → 0. The indicator sits in bucket A_credit, which is weighted 25% of the Current-Health score and 35% of the Future-Projection score (credit is given the heaviest forward weight because bonds lead).

Thresholds & statistical significance

Current bands: warn ≥ 4.5%, critical ≥ 5.5% (trigger: 4.5, warn: 4.5, crit: 5.5, trigger_type: "above"). These were recalibrated on 2026-06-07 — the calibration_data.json suggested_adjustment is tagged [APPLIED 2026-06-07], raising critical from a prior 4.5% to 5.5% (the old 4.5% critical was flagged as the main calibration error because it sat essentially *at* the long-run median).

The justification is the dated comparable set, because credit blow-ups are scarce and the historical record *is* the statistical sample:

• All-time tight 2.41% (June 2007) and the current reading ~2.72% sit right on the complacency floor — a textbook late-cycle "calm baseline."
• Long-run median ≈ 4.52% (1996–2026). This is why warn is placed at 4.5%: it marks a clear move *off* the sub-3% complacency floor and up *through* the historical median, i.e. "risk appetite is deteriorating," without being so low it fires in ordinary conditions.
• The 5.0% (500 bps) "red line." Every genuine modern crisis or pre-top stress event first crossed 5.0% before the worst hit: dot-com (early 2000), GFC (Nov 2007, ~13 months before the Dec-2008 peak), 2015–16 (Jul 2015), 2018 (Q4, peaked ~5.3–5.4%), COVID (late Feb 2020). Critical at 5.5% places the red flag *decisively through* that validated 5.0% line, giving clean separation from the noisy median.
• True crisis peaks sit far higher and bound the scale: GFC peak 21.82% (2008-12-15, all-time record), COVID 10.87% (2020-03, fastest-ever shock — ~3.3% to 1,087 bps in ~22 trading days), dot-com/telecom + Enron/WorldCom ~10% (late 2002), and the 2016 energy selloff 8.87% (a "false-positive-flavored" episode — no recession, but a real ~15% S&P drawdown).

So the ladder is: warn 4.5% = "off the complacency floor / above the median, credit is waking up"; critical 5.5% = "decisively through the historically validated 5.0% red line that preceded GFC, dot-com, 2018, 2020 and 2015-16." Confidence is rated Medium-high (verification: solid): the series is high-quality, daily, FRED-authoritative, and directly covers every modern bubble/crisis, but confidence is capped below "high" by structural caveats (notably that in a calm AI mania credit may stay tight until very late).

How to read it

• Normal (< 4.5%, e.g. today's ~2.72%): credit is complacent — investors are paid almost nothing extra to fund speculative AI debt. This is the late-cycle "calm baseline," healthy on its face but *also* the condition from which every blow-up has started. The risk here is silence: the spread can sit near record tights right up until it doesn't.
• Warn (4.5%–5.5%): the spread has lifted off the floor and pushed above its 30-year median — the bond market is starting to discriminate again. The highest-conviction read is when this widening happens *while equities are still making new highs*: that is the textbook 1997/2000 divergence, a signal that the debt-financing engine behind the AI buildout is repricing risk weeks-to-months ahead of the tape. Treat it as an early de-risking trip, not a panic.
• Critical (≥ 5.5%): the spread is decisively through the 5.0% red line that front-ran GFC, dot-com, 2018, 2020 and 2015-16. Funding for the speculative periphery (neoclouds, AI SPVs, leveraged data centers) is tightening hard; historically this regime precedes — and during COVID/2008 coincided with — the worst of the equity drawdown. As the most forward-weighted credit input (35% of the Future projection), a critical HY OAS pulls the cycle read sharply toward "the unwind has begun."

What it measures

The ICE BofA US Corporate (investment-grade) option-adjusted spread — the extra yield, in percentage points, that the market demands to hold high-quality corporate bonds over duration-matched Treasuries. It matters to an AI bubble because IG spreads widening means stress has climbed *up* the credit-quality stack — out of the speculative neocloud/SPV periphery (where HY OAS lives) and into the investment-grade core that funds the hyperscalers themselves. That is the moment liquidity tightens for *everyone*, not just the marginal AI borrower, and in a debt-financed buildout the IG bond market typically reprices before equities break.

Source & fetch

LIVE from FRED (Federal Reserve Bank of St. Louis), series id BAMLC0A0CM ("ICE BofA US Corporate Index Option-Adjusted Spread"), daily frequency. It is pulled by fetch_fred(series_id, start_date) in fetch_indicators.py, which hits the observations endpoint https://api.stlouisfed.org/fred/series/observations with params series_id=BAMLC0A0CM, the .env-loaded FRED_API_KEY, file_type=json, observation_start=start_date, and sort_order=asc. The helper is hardened against FRED's free-tier burst limit: it retries up to FRED_MAX_RETRIES (3) on HTTP 429 or any 5xx, honoring a Retry-After header when present and otherwise backing off exponentially (FRED_BACKOFF_BASE * 2**attempt = 1s, 2s, 4s), and pauses FRED_CALL_DELAY (0.6s) after every success so the sequential FRED series don't go out as one burst. FRED's "." missing-value markers (and blanks/None) are filtered out; each kept observation becomes {"date", "value": float}, sorted ascending. If all retries fail it raises RuntimeError rather than returning empty — a failed fetch must not be scored as healthy.

History depth: in build_indicator() the FRED branch runs history = fetch_fred(meta["fred"], start_date) where start_date = HISTORY_START = "1900-01-01". FRED clamps that to the series inception, so this pulls the *full* available record — BAMLC0A0CM begins in 1996. Cadence is weekly: the whole script is designed to run on a weekly scheduled task that regenerates indicators_data.json (consumed by ai_cycle_dashboard.html). This is a fully automated series — there is no manual entry and no SentimenTrader CSV feed for this indicator.

Calculation

There is no transformation. The FRED series is already the published option-adjusted spread in percent, so the raw observation *is* the indicator value — no normalization, no ratio, no TTM/YTD differencing, no 200-DMA gate, no percentile rank. The fetched list becomes out["history"], and the latest reading drives the state:

`` out["current"] = history[-1]["value"] # most recent daily spread, in % out["state"] = compute_state(current, trigger=1.2, "above", warn=1.10, crit=1.60) ``

The state itself comes from compute_state(). Because explicit warn (1.10) and crit (1.60) bands are supplied in the meta, the function takes the explicit-band path, which overrides the legacy ±10%-of-trigger rule entirely. With trigger_type="above":

`` if current >= crit (1.60): state = "critical" elif current >= warn (1.10): state = "warn" else: state = "normal" ``

State maps to score points via state_to_points: normal = 100, warn = 50, critical = 0. The points feed the equal-weighted mean of bucket A_credit, which carries 25% of the Current-health score and 35% of the Future-projection score (BUCKET_WEIGHTS). The bare trigger field of 1.2 is now vestigial for scoring — it only matters under the legacy fallback, which the explicit bands bypass; the actual cut points are 1.10 and 1.60. (Note: ig-oas is *not* one of the FROTH_INPUTS, so it does not contribute to the separate 0-100 Froth overlay.)

Thresholds & statistical significance

Current bands: warn ≥ 1.10%, critical ≥ 1.60% (trigger_type "above"). These reflect the recalibration tagged [APPLIED 2026-06-07] in calibration_data.json, which widened the old, overlapping 1.08% / 1.20% pair.

The justification is the dated historical comparable set (bubbles are scarce, so the comparables *are* the statistics), all from the authoritative daily BAMLC0A0CM record since 1996:

• Complacency floor: record low 0.53% (Oct 1997); the current AI-cycle reading sits at 0.74% (June 2026), matching the 0.74–0.78% of late 2025 that was described as the tightest in ~15 years and in the lowest quintile of history. This is the "calm baseline."
• Ordinary mid-cycle band: roughly 1.0–1.5%.
• Non-terminal risk-off episodes: EU debt crisis 2011 ≈ 2.0–2.5%, Feb-2016 energy/China selloff ≈ 2.1–2.2%, Dec-2018 ≈ 1.5–1.7% — all materially above 1.20%, proving 1.20% alone does not denote crisis.
• Genuine bubble-unwind / systemic peaks: dot-com/telecom bust ~2.72% (Oct 2002) — the nearest "post-bubble" analogue to an AI cycle; COVID ~4.0% (Mar 2020) before the Fed SMCCF backstop; GFC 6.56% (Dec 2008), the all-time high and absolute series ceiling.

So warn 1.10% is placed deliberately as an *early-inflection* tripwire: roughly +35 bps off the 0.74% complacency floor — about a one-standard-deviation-ish move that says "complacent credit is starting to reprice," which historically leads equity stress in a froth regime. Critical 1.60% was lifted to the Dec-2018 / lower-bound-of-real-risk-off level, the first point where the series clearly exits the 1.0–1.5% mid-cycle band, so "critical" actually corresponds to stress history associates with real (not routine) credit deterioration. The recalibration also fixed a structural flaw in the old 1.08/1.20 pair: they were only 12 bps apart, so warn and critical fired almost simultaneously with no escalation runway; the new 1.10/1.60 spread restores ~50 bps of graded escalation. The calibration note even flags an optional third "systemic" tier at ≥2.5% to capture true 2002/2008/2020-class unwinds, which is not (yet) wired in. Confidence is rated Medium-high on the numbers (FRED daily series since 1996, well-corroborated figures) and Medium on the exact threshold (a judgment call about how aggressively this dashboard trades false positives for early warning).

How to read it

• Normal (< 1.10%): the high-quality credit core is calm. At today's ~0.74% the read is actually *below* the complacency floor — late-cycle quiet, not safety. IG calm here should be interpreted as "the bond market has not yet flinched," consistent with an early/mid bubble stage where credit can stay tight until very late. It earns the full 100 health points but is, in context, a froth tell rather than reassurance.
• Warn (1.10%–1.60%): "credit is waking up." Spreads have lifted ~35+ bps off the floor and stress is beginning to migrate toward the IG core. In an AI-froth setting this is the meaningful inflection — the high-quality bond market starting to reprice the buildout's leverage, often before equities crack. Watch whether it is rising *while* equities still rally (the textbook divergence) and confirm against HY OAS (which should already be moving) and NFCI.
• Critical (≥ 1.60%): stress has decisively exited the ordinary mid-cycle band into genuine risk-off — the Dec-2018-and-beyond regime. Liquidity is tightening for investment-grade borrowers, i.e. for the hyperscalers themselves, not just the speculative AI periphery. Readings climbing toward the 2.7% (2002 post-bubble) / 4.0% (2020) / 6.56% (2008) comparables mark progressively more systemic unwind. This contributes zero health points and, given the heavy 35% Future-projection weight on the credit bucket, pulls the forward score down hard — a positioning signal to be defensive, since IG core repricing is the point where the credit squeeze becomes broad.

What it measures

The Chicago Fed's National Financial Conditions Index (NFCI) is a single weekly z-score distilled from 105 underlying measures of risk, credit, and leverage across U.S. money markets, debt and equity markets, and the traditional/shadow banking systems. Zero is the historical average: negative = financial conditions looser than average (easy money, abundant funding), positive = tighter than average (funding stress). It is the cleanest aggregate "plumbing pressure" gauge for an AI bubble because a debt-financed buildout (vendor financing, neocloud SPVs, GPU-backed debt) lives or dies on cheap, abundant funding — when the aggregate index crosses from loose to tight, the financial system is withdrawing the liquidity the whole AI capex loop depends on.

Source & fetch

Live, fully automated. Upstream source is the Federal Reserve Bank of Chicago's NFCI, distributed through the St. Louis Fed FRED API, series id NFCI (weekly frequency, published every Wednesday for the prior week; the underlying series is back-extended to 1971). It is pulled by fetch_fred("NFCI", start_date) in fetch_indicators.py, hitting https://api.stlouisfed.org/fred/series/observations with file_type=json, sort_order=asc, and observation_start set from the module constant HISTORY_START = "1900-01-01" — which simply clamps to the series' true inception (so the dashboard charts the FULL available history, not a fixed lookback). The fetch is rate-limit-hardened: up to FRED_MAX_RETRIES = 3 attempts with exponential backoff (FRED_BACKOFF_BASE = 1.0 → 1s/2s/4s), it honors any Retry-After header on HTTP 429/5xx, and pauses FRED_CALL_DELAY = 0.6s after each success so the back-to-back FRED series don't fire as one burst. Missing values (FRED returns ".") are filtered out; each kept observation becomes {"date": "YYYY-MM-DD", "value": float}. If all retries fail, fetch_fred raises RuntimeError rather than returning empty — and in build_indicator a live FRED indicator that ends up with no history is scored "unknown" (excluded from bucket scoring), so a dead feed can never masquerade as healthy. Cadence: refreshed on the weekly scheduled run alongside the other 17 indicators. No API key is in source — it is read from a local .env (FRED_API_KEY).

Calculation

There is no local transformation — NFCI is consumed as-published. The FRED branch in build_indicator (if "fred" in meta: history = fetch_fred(meta["fred"], start_date)) stores the raw weekly index values directly as the chart history, and out["current"] is simply the last (most recent) observation:

`` current = history[-1]["value"] # latest weekly NFCI z-score, e.g. -0.494 ``

The value is already a standardized z-score by construction (the Chicago Fed performs the 105-input principal-components standardization upstream), so the tracker does no normalization, ratio, differencing, moving-average gate, or rate-of-change on it. State is then computed by compute_state(current, trigger=0.0, trigger_type="above", warn=None, crit=None). Because the nfci meta carries no explicit warn/crit keys (unlike hy-oas or ig-oas), it does NOT take the explicit-band path; it falls through to the legacy ±10% rule for trigger_type="above":

`` critical if current >= trigger # >= 0.0 warn if current >= trigger * 0.9 # >= 0.0 (0.9 * 0 = 0, identical to critical) normal otherwise # < 0.0 ``

The mathematical consequence is the key quirk: since the trigger is exactly 0, the warn band trigger * 0.9 also equals 0, so the warn condition collapses into the critical condition. In practice the indicator has only two reachable states — normal below 0, critical at/above 0 — there is effectively no warn tier. (The FORMULAS["nfci"] text and INDICATOR_GUIDE["nfci"] both state this explicitly: "critical >= 0 (loose->tight)" and "the 10% warn band collapses to nothing — there is effectively no warn state.")

Thresholds & statistical significance

Current operative cutoff: critical at NFCI >= 0 (warn collapses into it; normal below 0). The >= 0 line is grounded directly in the dated comparables in calibration_data.json, and the entry's suggested_adjustment does NOT begin with [APPLIED ...], so the threshold was kept as-is (>=0), not recalibrated. The justification is that zero is the index's own design fulcrum between "looser than average" and "tighter than average," and a positive NFCI has essentially never occurred outside genuine financial stress in 55 years — making >=0 a high-precision, very-low-false-positive critical line. The historical ruler:

• GFC peak (Lehman aftermath), 2008-11-28: +3.068 — the modern all-time high. NFCI first crossed 0 on 2007-08-17 (+0.060) at subprime onset, hit +0.967 at Bear Stearns (2008-03-21), then exploded post-Lehman (+1.010 → +2.075 → +3.068). The 2007 zero-crossing was a genuine ~13-month early warning before the March-2009 equity bottom.
• COVID, peak +0.304 (2020-04-03) — ripped from -0.622 (Jan 2020) across 0 on 2020-03-13 (+0.030), essentially coincident with the 2020-03-23 equity bottom (a fast V-shaped liquidity event, not a slow unwind), then back below 0 by May after Fed backstops.
• Calm/easy baseline: roughly -0.4 to -0.7 — where the index has spent the bulk of 2010-2026; the current ~-0.494 reading sits squarely in this loose band, ~0.5 SD below the zero tripwire.

So the >=0 line sits a long way above the calm baseline but far below full-blown crisis (+0.97 Bear Stearns, +2 to +3 GFC): it functions as a leading tripwire, not a crisis confirmation. The decisive caveat the calibration flags — and the reason confidence is "Medium-high on the threshold itself, lower on its fitness for an AI bubble" (verification: solid) — is selectivity. NFCI is a credit/funding/banking-stress gauge, not an equity-valuation gauge, and the two closest AI-bust analogues never tripped it: the dot-com bubble peaked at only +0.033 (2000-06-09) and stayed NEGATIVE (worst ~-0.34 to -0.35) through the entire ~50% Nasdaq crash, 2001 recession, and Oct-2002 bottom; the 2022 "everything" bear peaked at just -0.100 (2022-10-07) despite the worst combined stock+bond drawdown in decades. The dot-com miss is "the defining false negative for this indicator" — a >=0 rule would have given zero warning. The calibration's recommended (not-yet-applied) refinement is a two-tier scheme adding a WARN at >= -0.20 ("drifting off the easy baseline") and an optional SEVERE tier at >= +0.75 (Bear-Stearns level), but the as-coded tracker still runs the single >=0 critical with no warn.

How to read it

A normal reading (anything below 0, e.g. the current ~-0.49) means aggregate financial conditions are looser than average — funding is abundant and the AI buildout's credit machinery is well-lubricated; in cycle terms this is the easy-money expansion phase where leverage, vendor financing, and neocloud debt can keep compounding. The reading drifting from -0.6 toward -0.2/-0.1 (as it did early in 2007 and approached in 2011/2015/2018 stress) is the texture worth watching even though the as-coded tracker won't flag it. A critical reading (>= 0, no warn step before it) is a regime statement: financial conditions have flipped from looser-than-average to tighter-than-average, and historically (2007, 2020) that crossing has either led the equity top by months or coincided with the crash — at that point the funding tide the AI loop depends on is going out, and credit-sensitive positioning (vendor-financed names, GPU-backed-debt issuers, neoclouds) is where the damage concentrates first. The critical signal is rare and high-conviction: outside genuine stress it has not fired in 55 years, so when it does, treat it as real. But the inverse is the load-bearing limitation: NFCI's silence is NOT an all-clear. Because its single most relevant analogue (dot-com) was an equity/valuation/capex bust that this index completely missed, a benign NFCI must always be read alongside the equity-valuation and credit-spread indicators in the tracker — an AI bust could be fully underway in stocks and capex while NFCI stays calmly negative.

What it measures

The 10-year-minus-2-year Treasury yield spread (FRED's T10Y2Y, in percentage points) — the steepness of the front-to-belly of the Treasury curve. In a credit-financed boom the curve normally sits inverted (long rates below short rates) for years; the dangerous event is not the inversion itself but the bull-steepener re-steepening out of inversion, when short rates collapse (or long rates jump) as the cycle turns. Historically the spread crossing back up through ~1.0% has coincided almost exactly with recession onset — the moment the AI-capex cycle's funding backdrop would flip from cheap-money tailwind to cyclical contraction.

Source & fetch

Live, from FRED. Series id T10Y2Y ("10-Year Treasury Constant Maturity Minus 2-Year Treasury Constant Maturity"), pulled by fetch_fred(series_id, start_date) (Section 2 of fetch_indicators.py). The indicator's META carries "fred": "T10Y2Y", so in build_indicator() it takes the FRED branch: history = fetch_fred(meta["fred"], start_date).

fetch_fred hits https://api.stlouisfed.org/fred/series/observations with params series_id, api_key (read from a local .env via load_env_file, never committed), file_type=json, observation_start=start_date, and sort_order=asc. It is hardened against FRED's free-tier burst limit: up to FRED_MAX_RETRIES (3) attempts with exponential backoff (FRED_BACKOFF_BASE 1s → 2s → 4s), honoring a Retry-After header on HTTP 429/5xx, and a fixed FRED_CALL_DELAY (0.6s) pause after every success so the sequential FRED series don't fire as one burst. Missing observations (FRED returns ".") are filtered out; the function returns a clean [{date, value}, ...] list sorted ascending — the exact shape the dashboard chart consumes, so no later transformation is needed. A failed fetch raises rather than returning empty, and a live indicator with no history is scored "unknown" (excluded from scoring) — a dead feed is never silently scored as healthy.

Cadence & history depth. T10Y2Y is a daily series. The orchestrator (main()) sets start_date = HISTORY_START = "1900-01-01", which clamps to the series' actual inception, so this pulls the full available daily history (FRED's T10Y2Y begins 1976). It is designed to run weekly via a scheduled task, writing into indicators_data.json.

Calculation

There is no derived transformation — the FRED series is the spread (10y CMT yield minus 2y CMT yield, already differenced and published by FRED in percentage points). The fetched daily series is charted as-is, and the current value is history[-1]["value"] (the latest daily reading).

State is assigned the standard way (no custom branch for this id): build_indicator calls `` compute_state(current, trigger=1.0, trigger_type="above", warn=meta.get("warn"), crit=meta.get("crit")) ` Crucially, the yield-curve META supplies only trigger: 1.0, trigger_type: "above" — it has no explicit warn/crit keys (unlike hy-oas or vix-term, where explicit bands override). So compute_state falls through to its legacy ±10% rule for an "above" trigger: ` current >= trigger (1.0) -> "critical" current >= trigger * 0.9 (0.9) -> "warn" otherwise -> "normal" ` This yields the bands documented in the guide: < 0.9% NORMAL / 0.9–1.0% WARN / ≥ 1.0% CRITICAL. (Note: the indicator scores on the level, not on the rate of re-steepening — see the caveat under Thresholds.) state_to_points` then maps normal→100, warn→50, critical→0, and the indicator feeds Bucket A_credit (25% of the Current score, 35% of the Future projection).

Thresholds & statistical significance

Effective bands: warn ≥ 0.9%, critical ≥ 1.0% (produced by the trigger=1.0 ±10% rule). These are unusually well-grounded for an AI-tracker indicator because, unlike the bubble-specific dials, T10Y2Y has real multi-cycle daily FRED data back to 1976. The calibration_data.json rationale rates confidence Medium-high and explicitly says the cutoffs are "well-placed and historically defensible" and "do NOT need to move." The justification rests on the dated comparables (bubbles are scarce, so the comparable set *is* the significance test):

• 2007–08 GFC (the cleanest re-steepening analogue, authoritative daily FRED values): the spread disinverted to ~0% in mid-2007, crossed 0.9% on 2007-11-19/20 (0.89%/0.92%), crossed 1.0% on 2007-12-05 (1.02%) and held ~1.0% through December, then surged to 1.50% (Jan 31 2008), 1.92% (Feb 14), peaking ~2.0–2.1% in early March 2008. NBER dates the recession start to December 2007 — precisely when the spread was sitting at ~0.9–1.0%. The warn(0.9)/critical(1.0) band brackets the recession-onset window almost exactly.
• 2000–01 dot-com/telecom bust: the curve un-inverted in 2000 (inversion trough ~−52 bps), and the NBER recession began ~6 months later (March 2001) with the 2s10s at ~100 bps (1.0%) — independently landing on the same ~1.0% onset level and directly validating the critical cutoff.
• 2022–24 / current cycle (calm baseline): the deepest inversion in 40+ years (trough ~−1.08%, Jul 2023), disinverted Sep 2024. Current value 0.38% (2026-06-07), down from 0.62% (Feb 2026) — a normal-positive "calm baseline." This frames where the cutoffs sit: ~0.4% calm now vs ~0.9–1.0% historical danger.
• 2019–20 (counter-example): brief inversion (trough ~−0.04%), re-steepened only modestly (peak ~0.34%, then 0.45% as COVID hit). The 2s10s never reached the 0.9/1.0% band before the Feb 2020 recession — illustrating the main failure mode: it catches credit/cycle-driven recessions, not exogenous shocks.

So warn=0.9% is a true "getting close to the onset zone" flag and critical=1.0% is "onset zone reached," with both the GFC and dot-com cases independently converging on ~1.0% at recession start. Confidence is held below "high" because n is small (~2–3 clean re-steepening episodes), the real predictive content is in the velocity of re-steepening (which a level cutoff only partially captures), and the indicator demonstrably misfires for exogenous shocks (2020) and produced a long false/late signal in 2022–24. The calibration's suggested_adjustment is therefore to keep 0.9%/1.0% as-is, with two optional (not-yet-applied) refinements: add a velocity companion (warn if the spread rises ≥0.5% over a trailing ~3-month window) and gate on "was inverted within the prior ~18 months" so a benign early-cycle steepening doesn't trip it.

How to read it

• NORMAL (< 0.9%): the cycle's quiet zone. A deeply inverted curve (e.g. the −1.08% of 2023) or a modestly positive "calm baseline" (the current 0.38%) both read normal — the curve is not yet signaling a turn. For the AI cycle this means the funding/recession backdrop is not the active risk; you watch HY/IG spreads and NFCI for the earlier credit tell. Be aware this band can persist far longer than history suggests (the curve stayed inverted through 2022–24 with no recession).
• WARN (0.9–1.0%): the spread has re-steepened into the historical recession-onset zone. In both 2007 (crossed 0.9% in Nov 2007) and 2001, this is where the recession was essentially beginning. Treat it as a late-stage confirmation that the cycle is turning — corroborate with the velocity of the move (a fast bull-steepener from inversion is the real tell) and with whether the curve was recently inverted.
• CRITICAL (≥ 1.0%): the "onset zone reached" line. ~1.0% is exactly where the GFC (Dec 2007, recession start) and dot-com (early 2001) recessions began; in 2007 the spread then exploded from 1.0% to 2.0% in about three months as the crisis itself unfolded. For an AI-capex bubble this is the credit-cycle's loudest cyclical warning — the buildout's cheap-funding regime is ending. Caveat: because it scores the level and lags the velocity, and because it won't fire for sudden exogenous shocks, it should be read alongside the rest of Bucket A (HY OAS, IG OAS, NFCI), not in isolation.

What it measures

A 0-100 judgment dial that tracks the *intensity* of circular AI vendor-financing — the web of deals where a chip/compute seller also funds its own customers (NVIDIA↔OpenAI↔Oracle↔CoreWeave↔AMD investments, GPU-collateralized SPV/neocloud debt). It matters because vendor-financed "demand" is the exact mechanism that flattered telecom-equipment revenue into the 2000 top: when the supplier is bankrolling the buyer, reported sales can be a loop rather than independent end-demand, and the loop unwinds violently if the funded customers can't generate cash to repay.

Source & fetch

This indicator is manual / hand-graded — it is NOT auto-fetched. The real upstream source is the *terms of the actual AI vendor-financing deals* plus reputable reporting on them: NVIDIA's equity stakes/commitments into OpenAI, OpenAI's compute purchase commitments to Oracle and CoreWeave, NVIDIA→CoreWeave, the OpenAI↔AMD warrant deal, and the GPU-collateralized SPV / neocloud debt structures (Abilene/Blue Owl/JPM off-balance-sheet leverage, Oracle CDS, CoreWeave debt load). These are read from primary deal terms and filings first, then triangulated against reporting (e.g. Bloomberg 2026-05-21 on the ~$800B interlinked web; The Register's "circular economy of AI" tally), and run through the project's deep news-grading method (news-grading.md: per-item claim→driver→durability→circumvention→voiding pass, supply-vs-demand caution, ≥2 independent sources or it's tagged rumor) to collapse the qualitative picture into a single 0-100 score.

That graded score is hand-entered into manual_readings.json under the key "circular-fin" as { "value": <0-100 int>, "as_of": "YYYY-MM-DD", "note": "" } (current entry: value: 62, as_of: 2026-06-07). In fetch_indicators.py, build_indicator() takes the meta.get("manual") branch: it reads manual_readings["circular-fin"], uses reading["value"] as base (falling back to the hardcoded meta["current"] = 50 if absent), and — because there is no series and trigger_type is "above" (not monthly_roc) — it does NOT use the rate-of-change path that hbm-prices uses. Instead it synthesizes a flat history: 52 weekly points plus today, every point equal to base, so the dashboard chart is a non-empty flat line that only moves when you edit the file. Staleness is computed from as_of: stale_days = today - as_of, and out["stale"] = stale_days is None or stale_days > 90 (STALE_AFTER_DAYS), so a reading older than ~90 days (or with a missing/invalid date) is flagged rather than silently treated as fresh. Feed: there is none — no FRED series id, no yfinance ticker, no SentimenTrader CSV, and no path in sentiment_feed.py. No auto-fetch path is currently planned; the metric is definitionally a graded judgment dial.

Calculation

There is no numeric transform of an upstream series — the calculation is the *grading*, then a direct pass-through. The 0-100 value is set by hand and consumed two ways:

1. Level/state (no normalization, no ratio, no differencing, no DMA gate). compute_state(current, trigger, trigger_type, warn, crit) is called with the entered value as current, trigger_type="above", and explicit bands warn=70, crit=85. Because explicit warn/crit are supplied, the function uses the explicit-band path and the legacy ±10% rule is bypassed: `` if current >= 85: state = "critical" elif current >= 70: state = "warn" else: state = "normal" ` State maps to health points via state_to_points: normal=100, warn=50, critical=0. With the current value 62 → normal → 100 pts, feeding bucket A_credit` (credit plumbing: 25% of the Current score, 35% of the Future score).

2. Froth overlay (raw pass-through). In FROTH_INPUTS, circular-fin is mapped "raw", meaning its 0-100 value IS its froth contribution unchanged (62 → +62 into the inverted Froth Index), with no scaling (unlike mag7-capex-rev's vs_ceiling rescale). This is why the dial sits in bucket A_credit *and* the standalone Froth gauge.

The conceptual yardstick behind the hand-grading (per the calibration entry) is the vendor-financing-as-%-of-revenue intensity proxy mapped onto 0-100: ~0-20 = a rounding error vs revenue (normal hardware credit terms); ~50-60 = the telecom *sector* level (~7% of revenue, broad but not single-name-extreme); ~70 = the Lucent FY2000 single-vendor peak (~24% of revenue); ~85 = intensity materially beyond any historical analogue.

Thresholds & statistical significance

Bubbles are scarce, so the comparable set is the justification. Current bands: warn ≥ 70, critical ≥ 85 — these were recalibrated on 2026-06-07 (the calibration entry's suggested_adjustment begins [APPLIED 2026-06-07]), replacing the original warn 90 / critical 100, which left almost no headroom and would never have fired until the situation was far past any analogue (the dial's ceiling sat *above*, not between, calm and historical-danger).

The anchors:

• Telecom equipment vendor financing, 1999→Q4 2000 (Lucent/Nortel/Cisco→CLECs): industry vendor financing exploded ~9x from $3.5B (1999) to $32.8B (Q4 2000); Nortel's was ~7% of total revenue. This *sector-wide* ~7%-of-revenue level is the ~50-60 anchor on the dial — broad but not yet single-name-extreme. It was the peak: it unwound to $25.5B (Q1 2001) and $18.2B (Q2 2001), and 47 CLECs went bankrupt 2000-2003.
• Lucent single-vendor intensity, FY2000: $8.1B vendor-financing commitments / $33.6B revenue = 24% of revenue (operating cash flow only $304M). This is the single best documented *pre-collapse danger anchor* and sets warn ≈ 70. Lucent then collapsed — revenue fell 69% to $11.8B (2002), $3.5B of bad-debt provisions, 33-80% of the vendor-loan portfolio uncollected.
• Current AI loop, Sep-Oct 2025→2026 (NVIDIA↔OpenAI↔Oracle↔CoreWeave↔AMD): NVIDIA ~$110B direct investments/commitments / $165B LTM revenue = ~67% of revenue — 2.8x Lucent's 24% — plus $15B+ GPU-backed debt; top-2 customers 39% of revenue; total announced web $440B-$800B+. This "materially beyond any historical analogue" state is where critical ≈ 85 sits — i.e. the present configuration already reads at/near critical on the intensity proxy.

So the bands separate three regimes the only real analogue gives us: below 70 = below the documented single-vendor danger anchor; 70-85 = at/past Lucent-FY2000 single-vendor peak intensity; ≥85 = beyond any documented analogue, where the current loop's raw intensity already sits. The 15-point warn→critical gap preserves an actionable escalation zone. Confidence: Medium — the telecom anchors and the NVIDIA ~67%-of-revenue figure are real, dated, and sourced (so the *direction* — lower the cutoffs — is well-supported), but the mapping from a $/%-of-revenue proxy onto a subjective 0-100 dial is interpretive, not mechanical.

How to read it

Read it as "how much of the AI demand picture is the supplier financing its own buyers," not as a live price. A normal reading (<70) says financing is present but below the single-vendor intensity that historically preceded collapse — the loop is not yet flattering demand to a documented-danger degree. A warn (70-85) says intensity has reached or passed the Lucent-FY2000 single-vendor peak (~24% of revenue) — the level that actually preceded a 69% revenue collapse; treat new "sales" funded by the seller with suspicion and watch whether funded customers can self-fund. A critical (≥85) means intensity is beyond any documented analogue, or a marquee circular deal has been pulled, failed to syndicate, or an SPV/neocloud has defaulted — the primary hard trigger.

The judgment overlay matters here: the *raw* intensity proxy already implies ~85+, but the current hand-grade is deliberately 62, below warn. The grading rationale: the most demand-flattering leg was *de-circularized* (NVIDIA's $100B deployment-tied OpenAI LOI was cut to a fixed $30B equity check decoupled from chip purchases, closed 2026-03-31; Huang called $100B "not in the cards"), end-demand is genuine and supply-constrained (rising GPU rental prices, multi-hundred-billion backlogs) rather than manufactured by the loop, and no marquee circular deal has broken yet — all of which the news-grading method weights down from the surface dollar figure. The standing escalation rule: a first major AI debt deal pulled / failing to syndicate, or an SPV/neocloud default, pushes it toward ≥85; until then the offsetting risk is concentrated in *debt* (Oracle CDS, CoreWeave's tripling interest expense, GPU-collateralized SPV leverage), not vendor equity. As a Froth input (raw), its value is also a direct +62 into the inverted Froth Index, so it can flag late-cycle danger even while the health composite still reads Bullish.

What it measures

A 0-100 conviction dial distilling the hyperscalers' (MSFT/GOOGL/AMZN/META) own forward capital-expenditure guidance and the *tone* of management commentary on each quarterly earnings call. It is the demand engine of the whole AI cycle: roughly $600B+ of 2026 capex (~75% AI-tied) is the single largest signal that the buildout is still being funded — and every prior tech build (telecom 2000-02, hyperscaler 2022-23) topped not on a *high* capex print but on the moment conviction *broke* ("optimization / digestion" language, or an outright guide cut). High = conviction intact; low = the demand-side crack.

Source & fetch

This indicator is news-graded / hand-recorded — it is scored via the deep news-grading method from hyperscaler earnings-call capex guidance and is *not* auto-fetched by any API. The primary upstream sources are the hyperscalers' quarterly earnings calls and capex guidance: MSFT/GOOGL/AMZN/META management commentary, prepared remarks, analyst-call Q&A, and the capital-expenditure line and forward-spend language in their 10-Q / 10-K. Each quarter the analyst reads those sources, applies the scoring rubric, and hand-records the conviction score plus a reasoning note.

In fetch_indicators.py, build_indicator() takes the meta.get("manual") branch. It loads the entry from manual_readings.json:

``json "capex-guidance": { "value": 86, "as_of": "2026-06-07", "note": "..." } ``

It reads base = reading.get("value") (currently 86, as_of 2026-06-07). The note field carries the full grading reasoning; build_indicator() copies it onto the output dict and sets graded=True, so the dashboard shows a GRADED chip (violet) instead of DUMMY. There is no series list and the trigger_type is not monthly_roc, so it does not take the rate-of-change path. Cadence is per-earnings-quarter (refresh after each hyperscaler reporting cycle). A staleness check flags the reading stale if older than 90 days. No SentimenTrader feed or local CSV is involved — it is a human judgment dial backed by primary call-based sourcing.

Calculation

There is no quantitative transformation — the stored value *is* the score. Because there is no live series to chart, the manual branch synthesizes a flat history so the dashboard chart is non-empty: it writes ~53 weekly points, all equal to base, spanning the trailing year:

``python today = dt.date.today() history = [ {"date": (today - dt.timedelta(weeks=w)).strftime("%Y-%m-%d"), "value": base} for w in range(52, 0, -1) ] history.append({"date": today.strftime("%Y-%m-%d"), "value": base}) ``

So the line is dead-flat at 85 for 52 weeks plus today, moving only when you edit the value. out["current"] is set to the last history point (base). State is assigned by compute_state(current, trigger, trigger_type, warn, crit) using the explicit-band path, with this indicator's metadata trigger=40, trigger_type="below", warn=55, crit=40:

``python if trigger_type == "below": if current <= crit: return "critical" # <= 40 if current <= warn: return "warn" # <= 55 return "normal" ``

The presence of explicit warn and crit means the legacy ±10% band rule (the trigger * 1.1 fallback) is bypassed entirely — warn/critical are the hard thresholds, not derived from the trigger. State then maps to points (normal=100, warn=50, critical=0) and feeds bucket B_demand, weighted 30% of the Current-health score and 15% of the Future-projection score. (Note: capex-guidance is *not* a Froth-overlay input — only circular-fin, ipo-pipeline, and mag7-capex-rev feed froth.)

Thresholds & statistical significance

Current bands: warn ≤ 55, critical ≤ 40 (trigger_type="below", so lower = worse). These were recently recalibrated — the calibration entry's suggested_adjustment is marked [APPLIED 2026-06-07], which moved warn UP from 44 to 55 while keeping critical at 40. The prior 44/40 band placed warn and critical only 4 points apart, so the early-warning tier fired almost simultaneously with the red line; widening warn to 55 restores a real two-step ladder.

Because no continuous historical series of this exact "conviction" metric exists, the comparable *episodes* are the justification (confidence: "Medium-low" — directional logic and episodes are solid; the precise 0-100 mapping is reasoned, not back-tested):

• Telecom / dot-com capex collapse, 2000-2002 (the canonical "conviction break = top"): wired-carrier capex fell from $72.0B (2001) to $34.8B (2002), ~-52% YoY; CLEC capex ~-80% from the 2000 peak; Q4-2001 telecom capex was only 69% of Q4-2000. Conviction flipped from "traffic doubles every 3 months" to overcapacity/"dark fiber" almost overnight; ~$700B-$2T of telecom equity value lost.
• Telecom capex/revenue intensity unwind (the conviction-dial proxy), 2000 vs 2004: Western-European telecom capex/revenue peaked ~28% then collapsed to ~12% by 2004 — the full round-trip of a conviction break. For scale, 2026 hyperscaler capital intensity already runs ~45-57% of revenue (Meta ~54%, Oracle ~86%) and the capex-vs-sales growth gap (~46%) *exceeds* the ~32% divergence of the 2001 telecom excess.
• Hyperscaler "Year of Efficiency," 2022-2023 (the false-top caution): Meta CUT its 2023 capex guide from $34-37B to $30-33B and declared the "Year of Efficiency"; Amazon cut 2023 capex ~-17% YoY to $52.7B; Dell'Oro flagged broad "cloud deceleration." The dial would have correctly fired warn on the cuts — yet capex then ~doubled from ~$160B (2023) to $300B+ (2025). This is exactly why critical stays at a deep 40 and warn at 55: a single soft quarter must not trip critical.
• Evercore AI-capex flag system, 2026-02-17 (live calibration anchor): 12-month-forward hyperscaler FCF has dropped below the 2022 "yellow-flag" lows; the "RED FLAG" is aggregate hyperscaler FCF turning negative; BofA expects ~90% of operating cash flow consumed by capex in 2026 (up from ~65% in 2025). Evercore's two-tier yellow/red flag maps almost exactly onto warn/critical — which is why warn=55 is set to register funding strain (forward FCF below 2022 lows / >85-90% of OCF consumed), not just spoken guidance.

So the placement reads: a >40-point gulf between the calm baseline (~80-90, all four hyperscalers raising 2026 guides 36-77%) and warn=55 deliberately demands a *large, unambiguous* deterioration before flagging — appropriate given how violently and bimodally this metric historically flips. The calibration also defines a language-cut override: an explicit *sector-wide* guide reduction should hard-set the dial to ≤40 regardless of the headline dollar level.

How to read it

This is an inverted / downside dial — historical danger is a *low* reading and the calm baseline is a *high* one.

• Normal (>55, today's 85): Conviction intact. All four hyperscalers are raising 2026 capex guides and the call language is still expansionary ("demand outpacing supply," backlog growth). The demand engine is running; B_demand scores healthy.
• Warn (40-55): First cracks. A *single* hyperscaler softens — "optimization," "digestion," "ROI discipline" — or one name trims a guide, OR funding strain crosses Evercore's yellow line (forward FCF below 2022 lows, >85-90% of OCF consumed) even while headline dollar guidance is still high. The 2022-23 episode is the warning that this tier can be a V-shaped head-fake, so warn = "watch and verify," not "exit."
• Critical (≤40): A broad, sector-wide guide cut or a regime shift to "digestion" language across multiple hyperscalers — the true 2000-02 / 2022 analogue, and the level the language-cut override hard-sets to. This is the primary demand-side break: it scores B_demand to zero and, given B_demand's 30%-current weight, drags the composite hard toward late-cycle. A reading here says the capex story that underwrites the entire AI complex's multiple has changed — position for the down-leg, not the dip.

What it measures

The trend in HBM / DRAM memory contract pricing — the "is AI demand actually real?" meter. HBM (high-bandwidth memory) is the load-bearing, capacity-constrained input that sits next to every AI accelerator, so its pricing is a live read on whether the buildout is still pulling hardware through at a premium. In an AI bubble the danger is not a high price (a deepening shortage is *healthy*) but a roll-over: when sticky, negotiated contract prices start printing consecutive monthly declines, it means suppliers are capitulating on demand — historically the leading edge of a multi-quarter memory bust.

Source & fetch

This indicator is NOT auto-fetched. It is a "manual": True indicator (see INDICATORS_META in fetch_indicators.py, id hbm-prices, bucket B_demand, unit idx), so no API is called.

• Original real-world source: monthly HBM / DRAM contract ASPs from TrendForce / DRAMeXchange. Real HBM monthly ASPs are proprietary/paid (TrendForce ~$4k/yr+, Bloomberg ~$25k/yr) and their sites are off-limits to scraping (ToS). Per docs/data-automation/acquisition-plans.md §3, the recommended free proxy is the Micron (MU) share price via yfinance (or a memory basket) — "direction is all the rate-of-change scorer needs" — with the option to upgrade to a paid monthly DRAM series later. (Estimate-grade APIs exist but are labeled ±15–20% and only quarterly.) Until that proxy is wired up, the value is hand-entered.
• Hand-entry shape: unlike the other manual dials (which store a single value), hbm-prices stores a monthly series in manual_readings.json — a list of { "as_of": "YYYY-MM-DD", "value": <number> } objects, oldest→newest. The current seed (flagged as ESTIMATED from the 2026 shortage trend in _README_hbm, to be replaced with real TrendForce/DRAMeXchange prints) is:

[ {2026-04-03: 235}, {2026-05-03: 258}, {2026-06-03: 278} ]. A top-level value/as_of (278 / 2026-06-03) is kept for back-compat, but the series drives scoring.

• In build_indicator() the manual branch (elif meta.get("manual")) reads reading.get("series"). Because a series is present *and* trigger_type == "monthly_roc", it takes the rate-of-change sub-branch: it charts the REAL series (history = [{date: s["as_of"], value: s["value"]} for s in series]) rather than drawing the flat synthetic 53-week line the other manual dials get. base is reset to the last value, as_of to the last reading's date, and an roc_note records the last three readings.
• Freshness: stale_days is computed from the latest reading's as_of; out["stale"] is set True if that is missing or older than STALE_AFTER_DAYS (90).

Calculation

There is no level normalization, ratio, or moving-average here. The chart is the raw stored monthly index; the *state* is a pure consecutive-monthly-decline counter on the series values vals = [s["value"] for s in series] (in build_indicator's monthly_roc branch):

`` if len(vals) >= 3 and vals[-1] < vals[-2] < vals[-3]: state = "critical" # two consecutive monthly declines elif len(vals) >= 2 and vals[-1] < vals[-2]: state = "warn" # one decline else: state = "normal" # flat or rising = healthy ``

So the transformation is a strict-inequality test on the last two/three points: two back-to-back drops → critical, one drop → warn, anything flat-or-rising → normal. On the seed series 235 → 258 → 278 (monotonically rising), vals[-1] (278) < vals[-2] (258) is False, so the indicator scores normal today. This forced_state is assigned directly in build_indicator and bypasses compute_state() and the ±10% / explicit-band machinery entirely (which is why trigger is None and there are no warn/crit numeric bands in the meta). The state then maps to points via state_to_points (normal=100, warn=50, critical=0) and feeds bucket B_demand (30% of Current health, 15% of Future).

Thresholds & statistical significance

The "threshold" is structural — 1 decline = warn, 2 consecutive declines = critical — not a price level, and the calibration entry (calibration_data.json → hbm-prices) validates keeping it as-is. Note this entry was not recalibrated: its suggested_adjustment begins "KEEP the two-tier consecutive-decline structure" (no [APPLIED ...] prefix), with confidence: "Medium" and verification: "mixed".

The justification is that across every dated memory top the defining fact is that declines cluster and persist once they begin — so a count-of-declines rule beats a magnitude threshold:

• 2018–2019 hyperscaler over-order top (the closest modern analogue): the *first* monthly contract decline (Nov 2018, a modest −1.6% to −3.2% MoM) was the leading edge of a ~60% four-quarter DRAM collapse; Micron fell −56% (~$64→~$28) and FY19 gross margin went 58.9% → 45.7% → 30.6%. "The first decline WAS the signal" — there was no benign one-bad-month that reverted.
• 2022–2023 post-pandemic glut: Q4-2022 contract prices −13% to −18% QoQ, inventories ~31 weeks; Micron revenue halved ($30.8B → $15.5B) and the stock fell ~50%. Again declines ran across consecutive quarters.
• 2008 GFC glut: DRAM spot −85% in 2007 then a further −58% in 2008, falling continuously for ~24 months (Qimonda insolvency).
• 2001 dot-com/telecom top: DRAM ASP −83%, price-per-megabit −76%, revenue −61%; the first quarter of decline led a multi-quarter collapse.

Against that, the calm baseline is zero declines — in a real boom contract prices rise monotonically (the current regime: +90–95% QoQ Q1'26, +58–63% Q2'26, sold out through 2026). Because contract pricing is sticky and negotiated (not jittery spot), a single printed monthly decline is a deliberate supplier capitulation, which is why "1 decline = warn" is signal, not noise; and "2 consecutive = critical" maps directly onto the 2018/2022 confirmation pattern, where the second down-print was never a false alarm. The acknowledged weaknesses (held to mixed/Medium): HBM as a distinct priced product is post-2014 and only AI-load-bearing since ~2023, so all pre-2023 comparables are commodity-DRAM proxies; and public monthly series mix MoM/QoQ cadences. The entry's suggested refinements (a ~−1% MoM magnitude floor so trivial declines don't trip warn; optionally weighting an HBM-specific decline as 1-decline-critical) are not yet implemented in the code — the live rule is still a bare strict-inequality count.

How to read it

• Normal (rising or flat, today): memory is still in deepening shortage — the AI buildout is pulling hardware through at premium prices and demand is being validated in real time. This is the healthy, mid-cycle read; a *higher* index here is *more* bullish, not a warning. Stay constructive on the demand thesis.
• Warn (one monthly decline): the first crack. Sticky contract pricing has broken a multi-quarter uptrend, which — given the 2018 template where a −1.6% MoM print preceded a 60% rout — is a genuine "watch closely" tripwire, not noise. Treat it as an early demand-side rollover signal and tighten risk on the AI-hardware complex; wait for the next print before acting decisively.
• Critical (two consecutive monthly declines): confirmation. In every historical memory top the second back-to-back down-print marked the rollover and was never a false alarm, typically front-running a ~50%+ memory-stock drawdown and a year-long price decline. This is a primary demand-break signal: the "is AI demand real?" meter has answered no, and the cycle is turning. Position defensively.

Caveat for the reader: today the score rests on an estimated seed series and freshness depends on the latest as_of (stale-flagged after 90 days) — once real TrendForce/DRAMeXchange (or the MU proxy) prints are entered monthly, the signal becomes live.

What it measures

NVDA's forward price-to-earnings multiple (price divided by the next-twelve-months consensus EPS) - the premium the market pays for Nvidia's AI-accelerator monopoly. Because that monopoly pricing power is the load-bearing assumption of the whole AI trade, a *decisive* break of the forward multiple below its historical distress floor is the market voting that the monopoly is impaired - a self-reinforcing de-rating. The twist is that a *low* forward P/E is ambiguous, so this indicator is built to fire only on the bearish version of "cheap."

Source & fetch

Live, from Yahoo Finance via the yfinance library. The forward multiple itself is a single daily snapshot read straight off the .info dictionary: yf.Ticker("NVDA").info["forwardPE"]. This is *not* a historical series - Yahoo exposes only the current forward P/E - so the charted "history" is a one-point series stamped with today's date: history = [{"date": today, "value": round(forwardPE, 2)}]. If forwardPE is missing, the function returns ([], None) with fetch_error = "forwardPE unavailable from yfinance" and the indicator scores unknown (a dead feed is deliberately never scored healthy).

Separately, the function fetches NVDA's recent daily price history to build the 200-day-MA *gate*: fetch_yahoo_close("NVDA", start=today - 400 days) (GATE_LOOKBACK_DAYS = 400), which calls yf.download(..., auto_adjust=True) and returns daily adjusted closes. It also pulls trailingPE and currentPrice from the same .info object for context. The dispatch branch is meta.get("compute") == "forward_pe" -> build_forward_pe(meta, start_date, out) in fetch_indicators.py; the upstream ticker is "NVDA". Cadence is per dashboard refresh (the snapshot is whatever Yahoo currently reports); price-gate depth is ~400 calendar days (enough for a 200-trading-day MA).

Calculation

Two quantities and a gate.

1. The multiple (charted value): fpe = round(float(info["forwardPE"]), 2). Yahoo computes this as price / forward-EPS consensus; the code consumes it as-is.

2. The 200-DMA price gate: from the recent daily closes, take the last 200 points and average them: closes = [p.value for p in px[-200:]] sma200 = round(sum(closes) / len(closes), 2) price = px[-1].value (last close; falls back to info.currentPrice) downtrend = (price < sma200)

3. Base state (level only): base_state = compute_state(fpe, trigger=22, trigger_type="below"). This metadata carries no explicit warn/crit keys, so compute_state uses the legacy +/-10% rule for a "below" trigger: critical if fpe <= 22, warn if fpe <= 22 * 1.1 = 24.2, else normal.

4. Gate override (the load-bearing step): the base state is then overridden by the price trend - - if base_state is warn/critical but not downtrend (price >= 200-DMA): forced to normal, with a state_note explaining the low multiple is estimate-driven (euphoric forward EPS), and the bearish trigger is suppressed; - if base_state is warn/critical and downtrend (price < 200-DMA): the warn/critical state is kept with a "genuine de-rating, trigger active" note.

So the gate can only ever *suppress* a fired trigger, never invent one. The function returns (history, forced_state), and the caller sets out["state"] = forced_state directly (bypassing the generic compute_state path that other indicators use). It also surfaces price, sma200, trailing_pe, and price_downtrend for the detail modal. Live example from the current run: fpe = 16.17, price = 205.1, sma200 = 188.34 -> downtrend = False -> state forced to normal (estimates euphoric, price still in uptrend), exactly the false positive the gate is designed to kill.

Thresholds & statistical significance

Trigger: forward P/E <= 22x, price-gated (only counts when price is also below its 200-DMA). The calibration entry was reviewed but not recalibrated (no [APPLIED ...] prefix), so 22x stands. The justification is the comparable set, because real NVDA de-ratings are scarce (n=2):

• NVDA late-2018 GPU/crypto bust trough (2019-01-14) - the one clean direct analogue - bottomed at ~20.8x forward, a price-confirmed de-rating (price well below its 200-DMA) on a real demand air-pocket (crypto-mining GPU glut, gaming inventory). The only real NVDA de-rating on record undercut 22x by ~1 point.
• NVDA 2022 bear-market trough (2022-10-01) - trailing P/E floor ~17x over the 10-yr window; forward compressed into the low-to-mid 20s on a genuine operational bust (gaming revenue -44% q/q, a $1.22B inventory charge), price below the 200-DMA. Confirms ~17-22x as the empirical "broken/distressed" zone for this name.
• NVDA's own modern baseline (2019-2026) - forward P/E has overwhelmingly sat at ~25-60x (10-yr mean trailing ~53-64x; 5-yr mean ~70x). 22x is roughly the 5th-10th percentile of NVDA's own range: firmly "something is wrong" territory, not a coin flip.
• Cisco dot-com analogue (peak 2000-03-27, >100x forward -> -88%) - a dominant compute-infrastructure vendor whose multiple unwound from triple digits to the low teens and stayed structurally lower for 20+ years. The lesson encoded in the gate: the danger is the *unwind from a high multiple* (which always broke the long-term price trend), so a sub-22x reading is the *end state* of a de-rating, and a low multiple without a price break is not a bust.

Net: 22x = NVDA's empirical distress floor (~17-21x) plus a small buffer, and the 200-DMA gate is the most important, correctly-specified element - it suppresses the most likely false positive (low multiple from surging forward EPS while price is still trending up). Confidence is Medium: the 22x line is well-supported for the single direct 2018 analogue and consistent with NVDA's distribution, but clean dated *forward*-P/E series are paywalled (2021 peak / 2022 trough figures are partly inferred from trailing data), and n=2 real de-ratings is a tiny sample. The calibration suggests an optional (not-applied) two-tier refinement (warn ~22x with price below 200-DMA; critical with price >5% below 200-DMA and forward P/E <~18x) and explicitly warns against *raising* the trigger above 22x, which would start flagging ordinary mid-20s mid-cycle multiples.

How to read it

• Normal is the default and includes two very different worlds. Forward P/E comfortably above ~24x (e.g. the AI-boom 25-60x range) is a richly-valued monopoly being paid full price - watch other buckets for froth, but the de-rating signal is dormant. Critically, a forward P/E *below* 22x while price is still above its 200-DMA is also normal here: that is the euphoric-estimates case (forward EPS rising faster than price), and the gate deliberately refuses to flag it as a bust - it is arguably a sign of strength, not danger. Today's ~16x with price above the 200-DMA is exactly this.
• Warn means the multiple has fallen to ~22-24x and price has broken below its 200-DMA - a real downtrend confirming the cheapness. This is the 2018 (~20.8x) regime: the market is starting to price an impaired monopoly rather than just resetting estimates. Treat it as the cycle entering a Nvidia-specific de-rating; reduce concentration in the name and the AI-hardware complex.
• Critical means forward P/E <= 22x *with* a confirmed price downtrend - the validated distressed floor, price and multiple agreeing. Historically this is where genuine busts (2018, 2022) actually printed; the original danger note asks for a close below 22x for ~5 sessions to filter noise. At this stage the indicator is telling you the monopoly premium is unwinding, which in the Cisco analogue marked the *end* of a long, self-reinforcing slide, not its beginning - position defensively.

What it measures

power-rs is an equal-weight price-trend index of the three purest "AI electricity" equities — Constellation Energy (CEG), Vistra (VST) and Vertiv (VRT) — read relative to its own 200-day moving average. Power (grid connectivity, generation, thermal/power-distribution gear), not chips, is now the binding *physical* constraint on the AI buildout, so this complex is the market's cleanest real-time vote on whether the buildout is still being funded and built; because these are trendless, high-beta narrative stocks, their break below trend tends to lead the broader AI-capex unwind by roughly 6–12 weeks. It covers bubble-rubric marker 8 (the power/physical bottleneck).

Source & fetch

LIVE from Yahoo Finance via yfinance, no manual entry and no SentimenTrader CSV feed. The indicator is defined in INDICATORS_META with "basket": ["CEG", "VST", "VRT"] and "trigger_type": "below_200dma", so build_indicator() routes it through the elif "basket" in meta: branch to build_power_basket(meta, out). That function loops over the three tickers and calls fetch_yahoo_close(t) for each with no start argument, which means yf.download(ticker, period="max", auto_adjust=True) — i.e. each ticker's full available daily history of split/dividend-adjusted closes (VST and VRT only date to their 2016/2020 listings, so the common-overlap window is the constraint, not the API). Cadence is daily; the script is run on demand / weekly to refresh indicators_data.json. If yfinance returns nothing for all three legs, the branch sets out["fetch_error"] = "no basket data (CEG/VST/VRT)" and returns forced_state = None, which the caller converts to state "unknown" so a dead feed can never score as healthy.

Calculation

Per-leg fetch -> inner-join on date -> equal-weight indexing -> average -> 200-DMA gate:

1. Each ticker's [{date, value}] series becomes a DataFrame column; the three are combined with reduce(lambda a, b: a.merge(b, on="date", how="inner"), series) — an inner join, so the basket only spans dates where all three trade (the youngest member sets the start). 2. Each leg is indexed to 100 at the common start: merged[c] = merged[c] / merged[c].iloc[0] * 100. 3. The basket value is the equal-weight (simple) mean of the three indexed legs each day: merged["value"] = merged[cols].mean(axis=1).round(2). This indexed series is the charted history. 4. The 200-DMA is a simple average of the last 200 basket points: sma200 = round(sum(history[-200:]) / len(...), 2) (so if fewer than 200 points exist it averages whatever is available). last = history[-1]["value"]. 5. State is assigned by where last sits versus sma200: - last < sma200 * 0.95 -> critical (basket >5% below its 200-DMA: "decisive breakdown") - last < sma200 -> warn (below the 200-DMA: "early rollover") - else -> normal ("buildout trade intact")

Diagnostics basket_last, basket_sma200, basket_members and a human-readable state_note are written to the output.

This branch returns (history, forced_state). Because forced_state is not None, build_indicator() takes the if forced_state is not None: out["state"] = forced_state path — so this explicit 200-DMA logic overrides the generic compute_state() +/-10% trigger-band rule entirely (the meta even sets "trigger": None). There is no TTM/YTD differencing, percentile-rank or acceleration leg here — it is a pure trend gate on a normalized equal-weight basket.

Thresholds & statistical significance

The thresholds are structural, not numeric levels: warn = any close below the 200-DMA; critical = >5% below the 200-DMA. The calibration_data.json entry (confidence: Medium, verification: solid) justifies the design with four dated comparables, because true power-complex tops are scarce so the comparable set *is* the justification:

• Calm baseline (2024–2025): the utility sector rallied +19% (2024) then +21% (2025), ~+$500B — "one of the biggest rallies in power company stocks in two decades." Throughout this validated up-leg the complex held comfortably above a rising 200-DMA and the indicator stayed green. This is the "calm" end the cutoffs must span away from.
• DeepSeek shock (2025-01-27): an efficiency-thesis challenge sliced VST (-28%), CEG (-21%) and VRT (~-25/-30%) through their rising 200-DMAs in a single session — the leading edge of the eventual top. This is why warn fires the instant price breaks the 200-DMA: the warn line caught the real top early.
• Major drawdown (2025-09 to 2026-02): the complex spent months below its 200-DMA — VST max drawdown -34.5%, CEG -38.8% (CEG -25% YTD through 2026-06-01) — coinciding with Constellation's CEO admitting demand forecasts were inflated ("pump the brakes"). This sustained sub-trend regime is exactly what the >5% critical band is built to flag.
• Independent Power Producer bubble (2000–2003, the closest true historical analogue): the same "tech demand for electricity" thesis ended in -99% wipeouts — Calpine bankrupt Dec 2005, NRG Ch.11 May 2003, Mirant Ch.11 July 2003 — and in every case the 200-DMA broke decisively at the start of the collapse and was never reclaimed.

The 5% buffer is the load-bearing calibration choice: high-beta names whip a few percent around the 200-DMA routinely (the Jan-2025 break largely retraced before the real Sep-2025 decline), so requiring a >5% breach separates a transient wick from the sustained sub-trend regime that actually preceded the -35%+ losses. The calibration notes the cutoffs are validated by both the modern cycle and the IPP proxy, and suggests (not yet applied) optional refinements: a ~5–10 day persistence filter on the warn level, and widening critical toward -7/-8% or pairing it with a 200-DMA-slope-down condition. Confidence is held at Medium only because the precise composite is novel and rests on one full modern cycle plus a 25-year-old proxy — the *direction and structure* are high-confidence.

How to read it

The 200-DMA *is* the thesis for these stocks: as long as the basket holds above a rising 200-DMA, the marginal buyer is still validating the AI-electricity demand story.

• Normal (above the 200-DMA): the AI-capex/power trade is intact and being funded — consistent with mid-cycle or melt-up. No action from this gauge.
• Warn (below the 200-DMA): an early rollover. The leading edge of the complex has cracked; historically this has appeared *before* the broad tape rolls over (the DeepSeek and pre-top signals). Treat as a yellow flag on Layer-0 / AI-capex exposure and watch for confirmation rather than a one-session wick.
• Critical (>5% below the 200-DMA): the decisive-breakdown regime — the same configuration that preceded the 2025–26 -35% to -39% drawdowns and, in the IPP analogue, moves toward -99%. The physical-bottleneck bet is unwinding; positioning should already be defensive on the AI-capex complex. Because the gate overrides the generic trigger logic and a dead feed scores "unknown," any green ("normal") reading here genuinely means price is above trend, not merely a missing-data default.

What it measures

NVIDIA's company-wide GAAP gross margin for the most recently reported quarter — gross profit as a percentage of revenue. Because Compute/Data-Center is now ~90% of NVDA revenue, this company-wide figure is a close proxy for the "Data Center" margin the indicator is named for. It matters to an AI bubble because NVDA's monopoly pricing power is what justifies its multiple; the quarter that margin visibly breaks is the quarter the whole AI-hardware trade re-rates (last cycle the FY2019 channel-glut break ran 60.4% to 54.7% GAAP and the stock fell ~55%).

Source & fetch

LIVE from the SEC EDGAR companyconcept API — https://data.sec.gov/api/xbrl/companyconcept/CIK{cik}/us-gaap/{concept}.json (free, no API key; only a descriptive User-Agent header set via the SEC_EDGAR_USER_AGENT env var, which _get_user_agent() enforces before any HTTP call).

• Company: NVDA, CIK 0001045810 (10-digit zero-padded, from COMPANY_CIKS in edgar_fetch.py).
• XBRL concept tags: GrossProfit (numerator) and Revenues (denominator). NVDA's RevenueFromContractWithCustomerExcludingAssessedTax tag only carries stale pre-2019 segment breakdowns, so compute_nvda_gross_margin() deliberately fetches Revenues (the revenue_fb tag) as the primary for NVDA rather than as a fallback, to avoid pulling the wrong time period.
• Fetcher: fetch_concept() does the GET with retry/backoff (≤10 req/s SEC limit respected via EDGAR_CALL_DELAY = 0.15s, EDGAR_MAX_RETRIES = 3, exponential backoff base 2.0s; 403 raises immediately with a User-Agent hint, 404 returns [], 429/5xx retry honoring Retry-After). The metric itself is computed by compute_nvda_gross_margin() in edgar_fetch.py and returned under the key nvda-gaap-margin; build_edgar_tracker_indicators() in fetch_indicators.py then reads edgar["nvda-gaap-margin"] and re-publishes it under the indicator id nvda-dc-margin.
• Cadence & history depth: quarterly underlying data; the pipeline caches the whole EDGAR payload in edgar_cache.json with a 24-hour TTL (load_edgar_cached() / EDGAR_CACHE_TTL_HOURS = 24), so it re-fetches at most once per day. This indicator stores only a single-point history ([{date: as_of, value: current}]) — the most-recent quarter, not a long series.
• This is a true LIVE/edgar: True indicator (no manual key → dataKind resolves to LIVE). There is a placeholder row in manual_readings.json ("nvda-dc-margin": { "value": 75.2, "as_of": "2026-05-27" }), but it is ignored: nvda-dc-margin is in EDGAR_IDS, so the main meta loop skips building a manual version and the EDGAR-derived dict replaces it. The manual value only surfaces as the "unknown" fallback if the entire EDGAR fetch throws.

Calculation

From compute_nvda_gross_margin():

1. Fetch raw USD entries for GrossProfit and Revenues. 2. _filter_and_dedup() keeps only 10-Q/10-K forms and, per end date, keeps the most-recently-filed entry (so restatements/amendments win). 3. _to_quarter_series() converts EDGAR's year-to-date cumulative income-statement values into single-quarter dollars. Within a fiscal year (grouped by the start date's year to avoid EDGAR's reused-fy-label cross-contamination): Q1 is taken as-is; Q2 = Q2_YTD − Q1_YTD; Q3 = Q3_YTD − Q2_YTD; Q4 = FY − Q3_YTD. Entries already filed as direct ~90-day quarters (span ≤ 100 days and fp ≠ "FY") are detected and used as-is to avoid double-subtraction. 4. Take the most-recent single-quarter GrossProfit (last_gp), then find the matching-end Revenues quarter; if exact end dates diverge it uses the closest revenue quarter with end >= last_gp["end"]. 5. Both values must be positive (a non-positive value would signal a YTD-differencing error and raises).

Formula:

gross_margin = GrossProfit_quarter / Revenues_quarter * 100 (rounded to 2 dp)

with a final sanity gate requiring 0 < gross_margin < 100. Note this is a single-quarter level — NOT TTM-aggregated and NOT acceleration-scored (unlike mag7-capex-rev, which uses TTM _ttm() plus a level+YoY-acceleration "worse-of-two" composite). as_of is max(last_gp end, last_rev end).

Thresholds & statistical significance

State assignment lives directly in build_edgar_tracker_indicators() as an explicit override (the generic ±10%-of-trigger banding does NOT apply here): NVDA_WARN = 73.0, NVDA_CRIT = 71.0, direction = below.

current <= 71.0 -> critical current <= 73.0 -> warn else -> normal

These reflect the recalibration applied 2026-06-07. The calibration_data.json rationale showed the prior warn (≤78.1%) sat a mere 0.3pt under NVDA's all-time peak of 78.4% and had therefore been "tripped" continuously for ~2 years — a threshold true ~100% of the time carries no information. Grounding in the dated comparables:

• NVDA peak margin Q1 FY2025 = 78.4% GAAP (2024-05), which immediately ground down (75.1% Q2, 74.6% Q3, 73.0% Q4 FY25) even as revenue rose — the late-cycle "peak pricing power rolls over before demand" signature.
• FY2025 full-year run-rate = 75.0%.
• NVDA's own only crisis low: Q4 FY2019 = 54.7% GAAP (2019-02), a ~570bp QoQ collapse on a channel-inventory glut and ~$120M excess-component charge — the demand-break/write-down template.
• Cross-reads: Intel's 2010→2011 cyclical fade (67.5% → ~60.6%, a ~7pt normalization with no crisis) and Cisco into the 2000 top (mid-60s, gave NO margin warning — the bubble broke on orders/backlog, not the margin line).

So warn at 73% = roughly a 5pt erosion off the 78.4% AI-era peak and below the 75.0% FY2025 run-rate — the Intel-style "multi-point fade off peak," the only margin pattern that has historically preceded trouble, and a level that actually toggles instead of being permanently on. Critical at 71% sits just below the FY2025 average and near the ex-charge level of the China-hit quarter; on a clean GAAP basis it is essentially only reached when a real one-off charge or inventory event lands (a "demand-break/inventory-charge" detector, echoing FY2019). Note the calibration's suggested_adjustment floated dropping critical all the way to ≤65% and/or switching to a rate-of-change rule; the code applied the warn move to 73 but kept critical at 71, not 65. Confidence is rated "Medium-low / verification solid" — explicitly because gross margin is a coincident-to-lagging pricing-power signal, not a leading crash signal (Cisco's clean miss is the cautionary tale).

How to read it

• Normal (> 73%): NVDA's monopoly economics intact. A reading like 74.9% means pricing power is still fully capitalized into the multiple — no margin-side stress, consistent with the boom regime (high-70s peak fading toward run-rate). This is the expected state through most of the cycle; treat it as "engine still humming," not a buy signal.
• Warn (71–73%): a meaningful, ~5pt fade off the 78.4% high-water mark and a drop below the 75% run-rate. This is the first credible margin-side tell — the Intel-2011 / NVDA-into-FY25 "peak pricing power rolling over" pattern. By itself it does not time the top (margins lag), but combined with cracks in the demand-side dials (capex guidance, HBM rollover, forward P/E de-rating) it raises the odds the cycle is maturing. Trim conviction, watch the next print for a second down-quarter.
• Critical (≤ 71%): on a clean GAAP basis this level is essentially only hit when a genuine glut or inventory/export-control write-down lands — the FY2019 (54.7%, −570bp) template. That is the visible margin break the indicator exists to catch; it is the point where the monopoly premium is empirically in question and the multiple is most exposed to a re-rate. Caveat baked into the calibration: a single one-off charge (e.g., an H20-style export write-down) can drag GAAP margin down for one quarter without a structural break, so confirm with the trajectory (consecutive declines) and the demand-side bucket before reading it as the cycle turning.

What it measures

The aggregate trailing-twelve-month capital expenditure of the four hyperscaler "Mag-4" balance sheets (MSFT, GOOGL, AMZN, META) divided by their aggregate TTM revenue, expressed as a percentage — i.e., how many cents of every revenue dollar the cloud giants are plowing back into property, plant and equipment (data centers, GPUs, power). It is the cleanest single read on AI-buildout *investment intensity*: every documented infrastructure bubble (telecom fiber, the railroads) broke when debt-funded capex outran the revenue it was supposed to serve, so a structurally rising capex/revenue ratio is the canonical "are they overbuilding ahead of demand?" gauge.

Source & fetch

LIVE from SEC EDGAR's free companyconcept XBRL API (https://data.sec.gov/api/xbrl/companyconcept/CIK{cik}/us-gaap/{concept}.json) — no API key, only a descriptive User-Agent header (read from SEC_EDGAR_USER_AGENT in .env; _get_user_agent() fails fast if blank, and a 403 is surfaced as a bad-header error). The fetcher is fetch_concept(cik10, concept) in edgar_fetch.py, which retries up to EDGAR_MAX_RETRIES=3 times with exponential backoff (EDGAR_BACKOFF_BASE=2.0 → 2s/4s/8s, honoring Retry-After on 429/5xx), sleeps EDGAR_CALL_DELAY=0.15s between successful calls to stay under the SEC's ≤10 req/s limit, and treats a 404 as a legitimate empty list so a fallback tag can be tried.

CIKs are hard-coded, 10-digit zero-padded, in COMPANY_CIKS (MSFT 0000789019, GOOGL 0001652044, AMZN 0001018724, META 0001326801; NVDA 0001045810 exists but is not used here). The us-gaap XBRL concept tags pulled are:

• Capex (numerator): PaymentsToAcquirePropertyPlantAndEquipment for MSFT/GOOGL/META. AMZN is overridden (CAPEX_CONCEPT_OVERRIDE) to PaymentsToAcquireProductiveAssets, which Amazon has filed exclusively since ~2017 (it stopped filing the standard PP&E tag after 2016).
• Revenue (denominator): RevenueFromContractWithCustomerExcludingAssessedTax as primary, with Revenues as the fallback tag (used for names where the primary tag has gone stale, e.g. GOOGL/NVDA).

Cadence/history: the underlying data is quarterly (10-Q/10-K filings). The dashboard caches the whole build_edgar_indicators() payload in edgar_cache.json with a 24-hour TTL (EDGAR_CACHE_TTL_HOURS = 24; quarterly data needs at most one re-fetch a day). The level history is the most-recent 8 rolling-TTM quarterly points (n_points=8), built from filings back to a recency_cutoff of 2022-01-01.

Note: in INDICATORS_META this id is still tagged manual: True (a legacy placeholder, current: 51), but at runtime build_edgar_tracker_indicators() produces a dict with edgar: True and no manual key, so the indicator resolves as LIVE and the EDGAR value replaces the placeholder. If EDGAR fails entirely it degrades honestly to state: "unknown" rather than reverting to the stale 51.

Calculation

Per company, per concept, the raw XBRL units.USD list is run through _filter_and_dedup() (keep only 10-Q/10-K forms; for each end date keep the most-recently-filed entry, so restatements/amendments win). The hard part is YTD → single-quarter differencing, done in _to_quarter_series(): EDGAR cash-flow and income concepts are cumulative within a fiscal year (Q1 = Q1; Q2-filing = Q1+Q2; Q3-filing = Q1+Q2+Q3; 10-K = full FY). The code classifies each entry as *direct-quarter* (start→end span ≤100 days and fp ≠ FY — used as-is) or *YTD*, groups YTD entries by the fiscal-year start year (derived from the start date, not the fy label, to avoid cross-year contamination when EDGAR reuses an fy label for comparative periods), and differences within the group:

`` Q1 = Q1_ytd Q2 = Q2_ytd − Q1_ytd Q3 = Q3_ytd − Q2_ytd Q4 = FY_ytd − Q3_ytd ``

TTM is then the sum of the 4 most-recent single-quarter values (_ttm() / _quarterly_ttm_series() for the historical series). A special case: AMZN files capex as rolling-annual (every 10-Q already carries a trailing-12-month figure). _is_rolling_annual() detects this when ≥70% of entries span 340–380 days; if so the most-recent entry *is* the TTM (_latest_rolling_annual()) and the quarter-summation is skipped — preventing a 4× double-count. A staleness guard (fetch_ttm) requires ≥4 quarters ending within the last ~9 months (cutoff_current = today − 274 days) before accepting a concept; otherwise it falls through to the fallback tag, and if both are stale it raises rather than silently dropping a company and understating the aggregate.

The aggregate level (compute_mag7_capex_rev) is dollar-weighted, not an average of ratios:

`` value = (Σ capex_ttm over Mag-4) / (Σ revenue_ttm over Mag-4) × 100 as_of = max(component as_of dates) ``

The 8-point history (_compute_aggregate_history) recomputes Σcapex/Σrevenue at each quarter-end where all four names have valid TTM capex and revenue. The acceleration leg, ratio_yoy_pp, is the level minus the level at the history point closest to ~365 days earlier (within ±45 days): ratio_yoy_pp = latest.value − year_ago.value, in percentage points per year.

State assignment uses two independent bands (the explicit warn/critical cutoffs override the dashboard's generic ±10%-of-trigger rule):

• LEVEL (_edgar_level_state): >32 critical, ≥25 warn, else normal.
• ACCELERATION (_edgar_accel_state, on ratio_yoy_pp): >10 critical, ≥5 warn, else normal (None → normal).
• Composite state = worse of the two legs (_worse_state).

It is also a Froth Index input: FROTH_INPUTS["mag7-capex-rev"] = "vs_ceiling", scaled min(100, value / 32 × 100) (so 25% → 78/100, 32% → 100). This was recalibrated 2026-06-07 from the old vs_trigger/60 mapping, which understated froth (25% had mapped to only ~42/100).

Thresholds & statistical significance

There is no hyperscaler-specific historical series — the metric as defined didn't exist before ~2010 — so the comparable set in calibration_data.json is the justification (confidence is rated *Medium-low*, verification *mixed*).

The single best quantified analogue is the U.S. telecom industry's capex/revenue at the dot-com/fiber peak: a calm baseline of ~12–21% (12% post-crash in 2004, ~20–21% in normal 4G/5G years, 21% in 1992) that reached ~27–28% at the 2000–01 peak, immediately before a 3-year crash (~$500B spent 1996–2000, peak annual capex ~$120B, 85–95% of laid fiber left "dark," then a collapse to ~12% by 2004 and a wave of bankruptcies). The LEVEL warn floor of 22% (tightened from 25% — [APPLIED 2026-06-08]) sits almost exactly at the top edge of telecom's calm range — "leaving normal, approaching the only documented danger zone" — and the critical line of 32% sits *above* telecom's ~28% peak, which is defensible because cloud is structurally more capital-intensive than legacy telecom and because the deepest-overbuild cohorts only revealed danger when capex blew past cash flow entirely: CLEC/pure-play fiber names (Level 3, Global Crossing, WorldCom, 360networks) ran effective capex/revenue >100% (debt-funded, >75% bond-financed) into mass bankruptcy in 2001–02, and the railroad boom (~2.5% of GDP across the 1870s–80s, ~5% at peak, >75% bond-financed) ended in the Panic of 1873. So 32% is "above any healthy precedent, yet below the run-rate at which the canonical busts actually broke."

The ACCELERATION band (>3 pp/yr warn, >7 critical — [APPLIED 2026-06-08], tightened from >5/>10) is anchored to the same telecom episode, where capex/revenue rose only ~6pp over a *full decade* (21%→27%, ~0.6 pp/yr) and still ended in catastrophe. The current cycle is adding ~+7.9 pp/yr (a ~72%/yr capex CAGR; the ratio climbed from ~13% in 2022 to ~25.5% in 2026 Q1) — traversing telecom's entire decade-long danger build in roughly nine months. That recalibration was applied on 2026-06-08: the live bands are now level warn ≥22% / critical >32% and acceleration warn >3 pp/yr / critical >7 pp/yr, plus a compound flag — level ≥25% AND acceleration >5 pp/yr forces critical, the telecom/CLEC/railroad signature of an elevated level combined with debt-funded acceleration. Under the applied bands the live reading (~25.5% level, +7.9 pp/yr) registers critical (it previously read only warn — the exact under-reporting the calibration flagged). The froth mapping (value vs the ~32% real-cycle ceiling) was separately recalibrated 2026-06-07.

One critical caveat from the calibration: the level bands only hold on the broad Mag-4 aggregate-revenue denominator (~25.5% basis). On a pure-cloud denominator, published figures run far higher (MSFT ~45%, Oracle ~57% capital intensity) and the bands would need to roughly double — so the indicator must keep using the same broad denominator for the cutoffs to mean what they say.

How to read it

A reading below 22% with sub-3 pp/yr acceleration is normal: capex is inside the historical tech-investment band and not climbing alarmingly. A warn (25–32% level, or +5 to +10 pp/yr acceleration) means the basket has left the calm zone and entered telecom's pre-crash neighborhood — the buildout is now running hot relative to revenue, the territory where overbuild risk historically begins to accumulate even though the technology may ultimately prove valuable. Critical (>32% level, or >+10 pp/yr) would put intensity above any documented healthy precedent and into the regime where the canonical busts (CLECs, railroads, late-stage telecom) had committed capex the cash flows could not yet justify.

Because state = the worse of the two legs, the *acceleration* arm is the leading tell: a still-moderate level that is sprinting upward fires the warning before the level itself crosses, which is the point — bubbles are made in the *rate of commitment*, not just the absolute number. The current read (level ~25.5% → WARN, acceleration ~+7.9 pp/yr → WARN) is the classic mid-bubble signature: not yet a confirmed top, but investment overshoot building fast, and — per the calibration's compound-flag suggestion — most dangerous precisely because an elevated level and a debt-financed acceleration past cash flow are occurring together, the exact combination that preceded the telecom, CLEC, and railroad busts. For positioning, sustained warn-on-both-legs argues for trimming the most capex-exposed AI longs and watching the companion fcf-yield indicator (does the buildout still self-fund?) for the moment acceleration tips into the >+10 pp/yr or >32% critical zone.

What it measures

The aggregate trailing-twelve-month free cash flow (operating cash flow minus capital expenditure) of the four mega-cap hyperscalers — MSFT, GOOGL, AMZN, META — divided by their combined market capitalization, expressed as a percent. It answers the single most important AI-bubble question on the cash side: after the AI buildout is paid for, how much actual owner-cash is the market getting for the price it pays? A high FCF yield (4–6%) means the franchise self-funds and the equity is cheap relative to the cash it throws off; a collapsing yield toward ~1% means capex is consuming nearly all operating cash and the stock has become a leveraged bet that future AI revenue will eventually justify today's spend — the classic late-cycle signature where price keeps rising while the cash backing each dollar of price evaporates.

Source & fetch

LIVE, computed from two upstream sources:

1. Numerator (FCF) — SEC EDGAR's free companyconcept XBRL API (no key; only a descriptive User-Agent is required by SEC, supplied via the SEC_EDGAR_USER_AGENT env var). Endpoint base: https://data.sec.gov/api/xbrl/companyconcept/CIK{cik10}/us-gaap/{concept}.json. CIKs are hard-coded, 10-digit zero-padded: MSFT 0000789019, GOOGL 0001652044, AMZN 0001018724, META 0001326801 (NVDA 0001045810 is fetched only for the separate margin indicator). The two us-gaap concept tags used here are: - Operating cash flow: NetCashProvidedByUsedInOperatingActivities - Capex: PaymentsToAcquirePropertyPlantAndEquipment, with a per-company override for AMZN, which since ~2017 files only PaymentsToAcquireProductiveAssets (CAPEX_CONCEPT_OVERRIDE["AMZN"]). The fetcher is fetch_concept() in edgar_fetch.py (rate-limited to ~6–7 req/s via a 0.15s inter-call sleep, 3 retries with exponential backoff 2^attempt, raises on 403/bad-UA, returns [] on 404 so a fallback tag can be tried). The TTM values are assembled by fetch_ttm(), and the whole indicator is assembled by compute_fcf_yield(), called from build_edgar_indicators().

2. Denominator (market cap) — yfinance, yf.Ticker(tk).info["marketCap"], per ticker, inside compute_fcf_yield(). If yfinance returns None for any ticker the function raises rather than fabricate a denominator (no silent drop).

Cadence & history depth: EDGAR data refreshes when each company files its 10-Q/10-K (quarterly); market cap is live/daily from yfinance. Filing history is pulled deep (back to the 2010s) but only used to reconstruct the most-recent four single-quarters for the TTM. Unlike the sibling capex/revenue indicator, fcf-yield emits NO rolling history series — build_edgar_tracker_indicators() stores a single history point {date: as_of, value: current}.

Feed / cache & fallback: the live payload is wrapped by load_edgar_cached(). There is also a stale placeholder in manual_readings.json — "fcf-yield": { "value": 2.1, "as_of": "2026-05-01" } (shape: a single {value, as_of} object). That manual entry is only a backstop; the normal path builds the LIVE EDGAR indicator and REPLACES the manual placeholder. If the entire EDGAR/yfinance fetch fails, the code does NOT fall back to that 2.1 — it emits an honest state: "unknown" stub with current: None. This is not a SentimenTrader-style feed and there is no local CSV.

Calculation

Per ticker, two TTM dollar figures are built by fetch_ttm():

1. Raw EDGAR entries are filtered to 10-Q/10-K forms and deduplicated per end date keeping the most-recently-filed row (_filter_and_dedup()). 2. YTD-to-single-quarter differencing (_to_quarter_series()): EDGAR cash-flow concepts are year-to-date cumulative within a fiscal year (Q1 = Q1; Q2_reported = Q1+Q2; Q3_reported = Q1+Q2+Q3; 10-K = full FY). The code groups entries by fiscal-year START year (derived from each entry's start date, not the noisy fy label, to avoid cross-year contamination from comparative-period restatements) and recovers single quarters: - Q1 = Q1_YTD - Q2 = Q2_YTD − Q1_YTD - Q3 = Q3_YTD − Q2_YTD - Q4 = FY − Q3_YTD Entries already filed as direct ~90-day quarters (span ≤ 100 days and fp ≠ FY) are detected and used as-is to avoid double-subtraction. 3. Rolling-annual exception (_is_rolling_annual() / _latest_rolling_annual()): AMZN files capex as a trailing-12-month value in every 10-Q (most entries span 340–380 days). When ≥70% of entries are annual-span, the most-recent entry IS the TTM and the quarter-summation path is skipped entirely. 4. TTM aggregation (_ttm()): sum the four most-recent single-quarter values; as_of = the last quarter's end. Staleness guard: requires ≥4 quarters with end ≥ 2023-01-01 AND the latest quarter ending within ~9 months (today − 274 days), else it tries the fallback tag or raises rather than computing a TTM on stale quarters.

Then in compute_fcf_yield():

• Per ticker: fcf_ttm = ocf_ttm − capex_ttm; yield_pct = fcf_ttm / mktcap * 100; as_of = max(ocf_asof, capex_asof).
• Aggregate (the published value): this is a market-cap-weighted (dollar-summed) yield, NOT an equal-weight average of the four yields:

value = (Σ fcf_ttm) / (Σ mktcap) * 100, rounded to 2 dp.

as_of = max of the four component as_of dates. Components (per-ticker fcf_ttm, mktcap, yield_pct, as_of) are returned for drill-down.

There is no normalization, no 200-DMA gate, no percentile-rank, and (unlike mag7-capex-rev) no level+acceleration or YoY rate-of-change leg for this indicator — it is a single levels reading.

Thresholds & statistical significance

State is assigned by an explicit, hard-coded two-band ladder inside build_edgar_tracker_indicators() (branch for id fcf-yield), recalibrated 2026-06-07:

`` FCF_WARN = 2.0 # warn if current <= 2.0 FCF_CRIT = 1.5 # critical if current <= 1.5 critical if current <= 1.5; warn if current <= 2.0; else normal ``

These explicit warn/critical values intentionally OVERRIDE the project's default ±10%-of-trigger band rule. The generic compute_state() would, for a trigger_type:"below" trigger of 1.5, place warn at trigger * 1.1 = 1.65 and critical at 1.5. This indicator does not route through compute_state() at all — it uses its own inline if current <= FCF_CRIT / <= FCF_WARN ladder — so the codified levels are warn 2.0 / critical 1.5, widening the old cramped 1.65→1.5 (15bp) band into a usable ~50bp graded zone (the INDICATORS_META trigger field still reads 1.5/"below" for legacy display, but the live state uses 2.0 and 1.5).

Why those levels, grounded in the dated comparables in calibration_data.json["fcf-yield"] (confidence: low-to-medium; bubbles are scarce, so the analogue set IS the justification):

• Calm baseline ~3–5%: the S&P 500 broad-market trailing FCF yield averaged 4.85% (1978–2018); Microsoft's own single-name yield peaked at 3.3% (Jun 2022) and bottomed at 1.9% (Jun 2025) — still above the line even at a 5-year low; the Mag-7 equal-weight FORWARD yield entered 2024 at 3.5%, falling to 2.6% by year-end 2024.
• Danger floor ~1%: the S&P 500 broad-market TOP in 2021-03-31 printed 1.1% trailing FCF yield (the most expensive whole-market read in the modern series; it then rose to 2.2% by Mar 2022 as the 2022 bear repriced equities, and reached 11.2% at the 2009 bottom — the buy extreme). Cisco at its 2000-03-27 dot-com peak implied ~0.57% FCF yield (price/FCF ~176×); the stock then fell ~85–90% and took ~25 years to reclaim its high. Today's average Mag-7 FCF multiple >95× implies ~1.0%.

So warn 2.0 sits clearly BELOW the 2.6–3.5% "elevated-but-normal" calm-tech zone (and below the Mag-7 late-2024 2.6% read) yet well ABOVE the ~1.1% 2021-top / ~0.57% dot-com danger floor — it flags "leaving normal" with lead time. Critical 1.5 sits inside one rate-shock of the validated 2021 broad-market top (1.1%) while preserving the ~50bp warn-to-critical buffer that restores graded escalation (the old 15bp band risked both states co-tripping on a single noisy capex-pull-forward quarter). The calibration explicitly cautions that the absolute level over-warns in a deliberate heavy-investment phase (compression is capex-by-choice, not earnings collapse) and recommends pairing the reading with a spread-to-10yr-Treasury overlay — with the 10yr near 4–4.5%, a 1.5–2% equity cash yield already implies a deeply negative equity-vs-bond cash spread, which was the lethal signal in 1989 Japan and 2000/2021.

How to read it

This is a Bucket-C valuation gauge (15% Current / 25% Future weight). Read it as the cash-coverage of the AI trade:

• NORMAL (> 2.0%): the hyperscaler basket is still self-funding its buildout and the equity has genuine cash backing. The closer to the 2.6–3.5% calm-tech baseline (or the 4–6% healthy-software zone), the more the AI capex is being absorbed without hollowing out owner returns — defensive properties intact.
• WARN (1.5%–2.0%): the basket has left the calm baseline; capex is now consuming most operating cash and the cushion above the historical ~1% danger floor is thinning. This is the "leaning warning" zone — it fires before the catastrophic level, by design, to give lead time. Treat a fresh cross below 2.0% (especially while market cap keeps climbing, i.e. the denominator is inflating the compression) as early distribution behavior.
• CRITICAL (≤ 1.5%): the aggregate is inside one rate-shock of the 2021 broad-market top (1.1%) and within sight of the ~0.57% Cisco-2000 analogue — the regime where the equity is a leveraged bet on unrealized future revenue and "defensive properties evaporate" (per the indicator's own danger note). Positioning read: pair it with the IG/HY credit and capex-acceleration indicators before acting, because a capex-driven dip can over-warn — but a sub-1.5% reading that holds, or one accompanied by a negative FCF-yield-minus-10yr spread, is the cash-side confirmation of a late-stage AI valuation top.

What it measures

EPS Revision Breadth (AI leaders) is the percentage of the ~23 AI-sector watchlist (LEADERSHIP_STOCKS) where the forward-year consensus EPS estimate has been revised upward over the past 30 days. It is a direction proxy (up/flat/down per name) not a magnitude-weighted FactSet/Yardeni breadth series. A high breadth = analysts becoming more constructive on AI earnings; falling breadth while multiples stay elevated = the 2000 analogue where expectations quietly deteriorate beneath a still-rising tape.

Source & fetch

LIVE — auto-fetched via eps_revisions_fetch.py (replaces the former manual placeholder).

Primary source: yfinance get_eps_trend() — for each ticker in LEADERSHIP_STOCKS, calls yf.Ticker(ticker).get_eps_trend() which returns a DataFrame with rows [0q, +1q, 0y, +1y] and columns [current, 7daysAgo, 30daysAgo, 60daysAgo, 90daysAgo, currency]. The module takes the +1y row (forward fiscal year) and compares current vs 30daysAgo. A ~1 second delay is inserted between yfinance calls to avoid hammering Yahoo's unofficial scrape endpoint.

Fallback: if yfinance returns an empty/None DataFrame for a given ticker, the module tries FMP /v3/analyst-estimates/{ticker} (Financial Modeling Prep; free key from .env FMP_API_KEY). If FMP also fails or the key is absent, the name is counted as invalid.

Minimum coverage: >= 12 of 23 names must return valid data; below that threshold the indicator scores unknown.

Cache / history: each run's breadth reading is appended to eps_revisions_cache.json (beside the script, gitignored) so the chart is a real weekly time-series rather than a flat synthetic line. The full cache history is used as the indicator's history list.

Scope note: scoped to LEADERSHIP_STOCKS (~23 AI leaders) not the S&P 500 — feasible and directly relevant. The former name "EPS Revision Breadth (S&P 500)" was incorrect; the indicator now uses the AI leaders watchlist.

Calculation

For each ticker in LEADERSHIP_STOCKS:

`` direction = True if current_+1y > 30daysAgo_+1y direction = False if current_+1y <= 30daysAgo_+1y direction = None if either value is missing / zero ``

`` valid_count = count of tickers where direction is not None up_count = count of tickers where direction is True breadth% = up_count / valid_count * 100 (requires valid_count >= 12) ``

State from explicit bands (trigger_type: "below"):

`` if breadth <= 10.0: state = "critical" elif breadth <= 11.0: state = "warn" else: state = "normal" ``

The reading is appended to eps_revisions_cache.json, giving the indicator a real weekly history. Bucket C_valuation, weighted 15% of Current-Health and 25% of Future-Projection.

Thresholds & how to read it

Bands: warn <= 11%, critical <= 10% (trigger_type "below"). These carry over from the former manual placeholder — recalibrate once several weekly runs have accumulated.

• Normal (> 11%): most AI leaders are getting EPS upgrades; no valuation divergence signal.
• Warn (10-11%): breadth is deteriorating near the danger zone; watch whether the multiple is still expanding.
• Critical (<= 10%): broad analyst downgrade cycle for AI leaders; if multiples are simultaneously elevated, this is a primary valuation-divergence trigger. Bucket C_valuation.

What it measures

The relative strength of the equal-weight S&P 500 (RSP) versus the cap-weight S&P 500 (SPY) — i.e. market breadth. A rising line means the average stock is keeping up with (or beating) the index; a falling line while SPY makes new highs means a handful of mega-caps are carrying the tape while the median name lags. This is the single cleanest read on concentration, and it matters to an AI bubble because the rally is being driven by a tiny cluster of AI mega-caps (top-10 weight ~41% of the index vs ~27% at the 2000 peak); when breadth narrows into new highs, distribution is underway beneath a still-rising headline index — the textbook signature of the 2000, 2007, and 2021 tops.

Source & fetch

LIVE from Yahoo Finance via yfinance. Two tickers are pulled: RSP (Invesco S&P 500 Equal Weight ETF) and SPY (SPDR S&P 500 ETF). In build_indicator() the "ratio" branch calls fetch_yahoo_close("RSP") and fetch_yahoo_close("SPY"), each with no start and no weekly flag — so each call runs yf.download(ticker, period="max", auto_adjust=True) and returns the FULL daily close history as [{date, value}, ...] (split/dividend-adjusted closes, rounded to 4 dp). Note: the human-authored FORMULAS["rsp-spy"] text says "Yahoo weekly closes," but the actual code path does NOT pass weekly=True, so the real cadence is daily closes over the maximum available history (RSP inception was 2003, so the ratio series effectively begins ~2003). Refresh cadence is the whole script's weekly scheduled run that rebuilds indicators_data.json. This is not a manual indicator — there is no entry in manual_readings.json and no flat synthetic series; it is a fully computed live ratio.

Calculation

Three deterministic steps from the code:

1. Align & divide — compute_ratio(sa, sb) inner-joins the two daily series on date and computes, per common date: value = RSP_close / SPY_close (rounded to 4 dp). 2. Index to 100 — because meta["id"] is in ("rsp-spy", "smh-spy"), the result is passed through normalize_to_first(): indexed_t = (ratio_t / ratio_0) * 100, where ratio_0 is the first aligned observation. The first bar is therefore 100 and every later bar is the cumulative relative-strength move of equal-weight vs cap-weight in points off that 100 base. The absolute ratio level is path-dependent and not comparable across eras, which is exactly why it is re-based rather than thresholded on a fixed number. 3. State — meta declares trigger: None and trigger_type: "roc" with no warn/crit bands. Unlike smh-spy (which shares the same ratio branch but then runs a 200-DMA-deviation + RS-rollover scored compute), rsp-spy has no forced-state branch at all. It falls through to compute_state(current, trigger=None, ...), and because trigger is None the very first guard returns "normal". So rsp-spy is a pure chart-watch: it always scores normal (100 points) and never moves the composite score. The intended human read — "SPY new high while the RSP/SPY ratio declines for 2+ weeks = distribution" — is a visual/trend rule, not an automated gate (the per-name lead-breadth indicator in leadership.py is the scored version that gives the Internals bucket teeth).

Thresholds & statistical significance

There is no hard numeric trigger and no warn/critical band — by deliberate design, documented in the calibration_data.json rationale: both legs are re-based to 100 in the fetcher, so the ratio level is path-dependent and a fixed cutoff on it would be spurious. The validated signal is the *divergence/trend*, not a number. The comparable set justifies keeping it trend-based while flagging that the structural backdrop is already in the historical-danger zone:

• 2000 dot-com peak (cleanest direct analogue, 2000-03): cap-weight outperformed equal-weight by ~31% on a rolling 3-year basis, top-10 weight ~23-27%. This marked THE top — the relationship then violently reversed, with equal-weight beating cap-weight for ~7 straight years (+65% vs -9% through 2010).
• 2007 cycle peak (breadth-divergence analogue, 2007-07→10): S&P made a higher high in Oct 2007 while the NYSE A-D line made a lower high — a "near-picture-perfect" narrowing divergence (structural equivalent of SPY-up/RSP-down). ~57% drawdown into March 2009 followed.
• 2023-2025 AI cycle (current record extreme, as of 2025-12-31): cap-weight beat equal-weight by ~30-32% over 3 years — the WIDEST 3-yr margin since 1971 — with top-10 weight ~41% (vs ~27% at the 2000 peak) and S&P +86% vs equal-weight +43%. This has surpassed the dot-com peak on both concentration and 3-yr relative outperformance; the metric is already past its prior historical-danger marker.
• 2026 YTD rotation (signal possibly firing, as of 2026-03-25): RSP ~+1% YTD vs SPY ~-4% YTD (~5pt equal-weight outperformance) — precisely the early reversal/broadening that historically follows a concentration peak.

The calibration's suggested_adjustment (NOT yet applied as code bands — it is advisory) is to keep it trend-based but make the rule more actionable: (a) WARN when SPY prints a new 4-week high while RSP/SPY falls 2+ consecutive weeks; (b) CRITICAL when that WARN persists and SPY rolls over with equal-weight leading on a down tape for 3+ weeks; (c) a static context flag — because top-10 weight (~41%) and 3-yr relative outperformance (~30-32%) already EXCEED their 2000 readings, the divergence rule should fire at WARN immediately on confirmation rather than waiting for corroboration, since the calm-baseline buffer is gone. Confidence is medium-high on the comparables (equal-vs-cap-weight 3-yr relative performance and top-10 concentration are cleanly measured back to 1971/1990; 2000/2007/2021 are textbook divergence tops) but medium on the precise trigger because the signal is a pattern, not a number, with only ~3 modern instances to fit — small sample, high false-positive risk in choppy ranges. Verification: solid.

How to read it

Read it as a slope-and-divergence chart, not a level:

• Rising line = broadening (healthy). The average stock is participating; the rally rests on a wide base. This is the normal/calm regime — 2003-2022, when equal-weight roughly matched or beat cap-weight (~+1.2-1.5%/yr to equal-weight) at top-10 weights near 19%.
• Flat or falling line while SPY makes new highs = narrowing / distribution (warn-equivalent). A shrinking group of leaders is holding the index up while the median name fades — the 2000/2007/2021 setup. Even though the indicator auto-scores normal, treat a 2+-week SPY-high/RSP-down divergence as a genuine yellow flag, because the structural concentration backdrop (top-10 ~41%, 3-yr spread ~30-32%) is already at or beyond every prior bubble peak.
• **Sharp drop in the line = leaders cracking; line *rising* while SPY *falls* = post-peak mean-reversion (critical-equivalent).** Equal-weight leading on a down tape (the line turning up as the index turns down) is exactly the broadening that followed the 2000 top and that began in 2026 YTD — the late/turning-point signature this metric exists to catch. Positioning implication: persistent narrowing into highs argues for trimming the most-concentrated mega-cap exposure before the divergence resolves, since by the time it resolves it has historically already marked the top.

What it measures

Semiconductors are the AI cycle's purest leadership group, so this indicator tracks the SMH (VanEck Semiconductor ETF) versus SPY relative-strength line *and* how stretched semis are above their own long-term trend. Chips lead market regime changes by 6-12 weeks: when semis are blowing off far above trend and/or their relative-strength line rolls over while the broad index still grinds higher, leadership is rotating out of the very group financing the AI buildout — the textbook late-cycle "the generals stop leading" tell.

Source & fetch

LIVE from Yahoo Finance via yfinance, with no manual entry (there is no smh-spy key in manual_readings.json). The "ratio" branch of build_indicator() in fetch_indicators.py calls fetch_yahoo_close("SMH") and fetch_yahoo_close("SPY") with no start argument, so each pulls yf.download(ticker, period="max", auto_adjust=True) — the full available daily-close history of both ETFs (split/dividend-adjusted), not a bounded window and not weekly-resampled (unlike the chart-only Yahoo indicators, this one runs on daily closes because the scored compute needs ≥200 daily points). The two daily series are aligned on date and divided by compute_ratio() (inner merge, SMH/SPY), then run through normalize_to_first() so the charted ratio is indexed to 100 at the first common date. Cadence: the whole script is designed to run weekly via a scheduled task and rewrite indicators_data.json (consumed by ai_cycle_dashboard.html). Because it is fully live there is no staleness flag and no manual fallback — if Yahoo returns no data the indicator is scored unknown and excluded from the bucket score rather than counted as healthy.

Calculation

The charted value is the indexed SMH/SPY ratio (normalize_to_first → 100 at series start). The state is computed in the smh-spy block of the "ratio" branch as the *worse of two independent sub-signals* (_worse_state_fn, where critical > warn > normal), and the whole compute is gated on having >=200 daily points for both smh_closes and the indexed ratio_vals (fewer → forced_state = "normal" with an explanatory note, so a too-short history can't manufacture a signal):

• Sub-signal A — SMH stretch above its own 200-DMA (absolute blow-off):

smh_sma200 = mean(smh_closes[-200:]); smh_dev = (smh_last / smh_sma200 - 1) * 100 (percent above/below the trailing 200-day mean of SMH's own price). - smh_dev >= 55 → critical - smh_dev >= 35 → warn - else → normal

• Sub-signal B — SMH/SPY relative-strength rollover vs its own 200-DMA:

ratio_sma200 = mean(ratio_vals[-200:]); rs_pct = ratio_last / ratio_sma200 - 1 (fractional deviation of the indexed ratio from its trailing 200-day mean). - rs_pct < -0.05 (ratio >5% below its 200-DMA) → critical - rs_pct < 0 (ratio below its 200-DMA) → warn - else (ratio at/above its 200-DMA) → normal

Final state = _worse_state_fn(state_a, state_b), and the run records smh_dev_pct, smh_sma200, ratio_sma200, plus a state_note spelling out A, B and the composite. Note these are simple trailing-200 *means of the stored series* (effectively a 200-period SMA on the daily data), not a calendar-200-day window. Because A and B are explicit per-sub-signal bands, they override the generic ±10% rule in compute_state() entirely — smh-spy carries trigger_type: "roc" with trigger: None, so the legacy band logic never runs for it; the branch sets forced_state directly.

Thresholds & statistical significance

The thresholds were recalibrated 2026-06-07 ([APPLIED 2026-06-07] in calibration_data.json), replacing the original bare qualitative "trend-watch" (no numeric cutoff) with the two-sub-signal scheme above. The dated comparables justify each line — and because true semi blow-offs are exceptionally rare, that comparable set *is* the statistical case:

• Sub-signal A (deviation above 200-DMA) is anchored on BofA/Hartnett's cross-bubble measurements of how far the semiconductor index runs above its 200-day trend: calm/normal bull-market deviation is single-digit to ~20%; the historical average across major bubble tops is ~35% (→ warn line); the 2000 dot-com SOX top was ~55% above its 200-DMA before an ~82% SOX crash / ~85% SMH decline / NVDA -90% (→ critical line). For scale, the only two comparable readings since 1700 are Nasdaq 2000 (~55%) and the Mississippi Bubble 1720 (~73%) — both ended in collapse. So warn ≥35% = "at the average bubble-top stretch," critical ≥55% = "into the rarest-since-1700, 2000-analogue blow-off zone."
• Sub-signal B (RS rollover) is anchored on relative-return episodes: 2021 semis ran +42.1% vs SPY +15.1% (~3x) and the relative line rolled over in Nov 2021, preceding the broad top by weeks; 2022 SMH then led the downside at -33.5% vs SPY -18%. The 2018 Q4 chip selloff (SOX -25%, recovered in <12 months on intact demand) is the cautionary false-positive — which is why B only escalates to critical once the ratio is decisively (>5%) below its own 200-DMA, i.e. a confirmed downtrend rather than a rotation dip.
• Current reading (June 2026, calibration context): SOXX ~78.9% above its 200-DMA (largest since its 2001 inception, beating 2020 and 2022), SOX ~62% per Hartnett, SOXX YTD +98% vs QQQ +21.7% (~4.5x); Michael Burry bought Jan-2027 SOXX $330 puts when chips were already 43% above the 200-DMA. Under the new cutoffs this prints critical on Sub-signal A (well past 55%), which was the explicit point of the recalibration — the old "watch" label under-weighted a top-3-since-1700 extreme. Confidence is rated Medium (verification: *mixed*): the deviation anchors (1720/2000/current) and the 2018/2021-22 RS episodes are well-sourced and consistently measured, but n is tiny and the absolute-level cutoff can fire long before a top in a genuinely longer-running boom.

How to read it

A normal reading (semis <35% above their 200-DMA *and* the SMH/SPY ratio at/above its own 200-DMA) is healthy leadership: chips are leading the market by an orderly, persistent margin — the buildout trade is intact and broad participation is being confirmed. A warn means one leg has cracked: either semis are 35-55% above trend (at the historical bubble-top average — froth building) *or* the relative-strength line has slipped below its 200-DMA (early leadership rollover, the Nov-2021 pattern); de-risk semis at the margin and watch for confirmation. Critical means a top-grade signal: semis ≥55% above trend (2000/Mississippi blow-off territory — extreme downside skew, history says wait years for recovery from these levels) *and/or* the relative line >5% below its 200-DMA (a confirmed leadership downtrend, semis flipping from market generals to laggards). Because the state is the *worse* of the two, you get the upside blow-off warning (A) and the leadership-reversal warning (B) on the same dial — and to avoid mistaking a 2018-style rotation dip for a true top, the strongest read is sustained extreme A combined with B confirming, ideally alongside a demand/fundamental tell from the B-bucket indicators.

What it measures

The VIX term structure — the ratio of the 30-day VIX to the 3-month VIX3M — measures whether the options market is pricing near-term risk *above* or *below* longer-dated risk. Below 1.0 the curve is in contango (calm: traders demand more for far-out protection); at/above 1.0 it inverts into backwardation (acute, right-now fear). It matters to an AI bubble because it is the cleanest fast-moving "regime" tell on the dashboard: in a euphoric, narrow, AI-led tape, the curve sits in deep contango for long stretches, so the moment it flattens and inverts is one of the earliest market-priced confirmations that the risk-on regime is breaking — typically 1–3 weeks ahead of the broad drawdown.

Source & fetch

LIVE from Yahoo Finance via yfinance, with no manual entry and no SentimenTrader feed file. The indicator is defined in INDICATORS_META (fetch_indicators.py) as {"id": "vix-term", "ratio": ("^VIX", "^VIX3M"), "trigger_type": "above"}. Because it carries a ratio key (and not fred/yahoo/compute/basket/manual), build_indicator() routes it into the elif "ratio" in meta: branch. There it unpacks a, b = meta["ratio"] and calls fetch_yahoo_close("^VIX") and fetch_yahoo_close("^VIX3M") separately. fetch_yahoo_close(ticker) is called with no start argument, so it issues yf.download(ticker, period="max", auto_adjust=True) and pulls the full available daily history of each index, takes the daily Close, drops NaNs, and returns [{date, value}, ...]. The two indices are the CBOE Volatility Index (^VIX, 30-day implied vol) and the CBOE 3-Month Volatility Index (^VIX3M, formerly VXV). Cadence: the whole script is designed to run weekly via a scheduled task (it writes indicators_data.json consumed by ai_cycle_dashboard.html), but the underlying series and the charted ratio are daily. Unlike the manual dials, there is no staleness flag — a failed/empty fetch yields no history, and build_indicator() then sets state = "unknown" (a dead feed is explicitly *not* scored as healthy).

Calculation

The ratio is computed by compute_ratio(sa, sb) where sa = ^VIX series and sb = ^VIX3M series:

`` df = df_VIX.merge(df_VIX3M, on="date", how="inner") # align on common trading days value = round(VIX / VIX3M, 4) # per-date ratio ``

So the charted value on each date is simply:

`` vix_term = VIX(30-day) / VIX3M(3-month) ``

Two implementation details matter. (1) The merge is an inner join on date, so the ratio only exists on days both indices traded — no forward-filling or interpolation. (2) This indicator is NOT re-indexed to 100. In the same ratio branch, only rsp-spy and smh-spy pass through normalize_to_first(); vix-term is explicitly excluded, so the stored/charted value is the *raw* ratio (e.g. 0.82, 0.97, 1.05), which is exactly what the threshold bands compare against. There is no smoothing, no percentile rank, no rate-of-change, and no moving-average gate — the metric is read at its raw daily level. out["current"] is the last value of that history, and the state is computed directly from it.

Thresholds & statistical significance

The applied bands (FORMULAS["vix-term"] and the meta) are warn ≥ 0.95, critical ≥ 1.0, with trigger_type = "above". These are passed as explicit warn/crit into compute_state(), which takes the explicit-band path — explicit bands *override* the legacy ±10% rule entirely. For an "above" indicator the logic is: critical if current >= 1.0, else warn if current >= 0.95, else normal.

The critical line is the structural anchor and is not arbitrary: 1.0 is the exact mathematical point where the market prices 30-day risk above 3-month risk (contango → backwardation = acute panic). The calibration_data.json comparables validate it across every modern crisis: the 2020 COVID crash is the cleanest dated series — VIX/VIX3M ran 0.82 on 2020-01-02 (deep contango) → 1.14 on 2020-02-24 → a 1.20 peak on 2020-03-03, and the 2020-02-24 cross above 1.0 led the ~34% S&P drawdown low by roughly four weeks; the 2008 GFC held >1.0 with a calendar-year mean ratio ~1.02 and the longest inversion on record (~161 days), ahead of another ~30% fall into March 2009; 2011 (US downgrade / EU crisis) saw the VIX:VXV ratio hit its highest since 2008 ahead of a ~16% drop; and 2018 "Volmageddon" flipped into backwardation on 2018-02-05 (VIX +116% in a day) ahead of a ~10% correction. The set shows duration discriminates severity — a sustained >1.0 marks systemic bears, a one-day spike can mark a sharp-but-brief correction — but in both cases the 1.0 cross was the trigger. Confidence on critical=1.0 is medium-high (a hard structural boundary corroborated by four dated episodes).

The warn line was recalibrated 2026-06-07: the calibration entry's suggested_adjustment is tagged [APPLIED 2026-06-07] and recommends raising warn from 0.90 to ~0.95 to cut false positives, and the code now carries warn: 0.95. The rationale: the calm-contango baseline runs ~0.92–0.96 (with deep-calm readings down to 0.80–0.85, e.g. 0.82 on 2020-01-02), so 0.90 overlapped the upper edge of ordinary contango and fired on routine vol upticks; the genuinely "curve-flattening-meaningfully / pre-top" zone is more like 0.95–1.0. Setting warn at 0.95 puts the first alert at the top edge of normal contango. The warn→critical gap is deliberately narrow (0.95→1.0) because this metric moves fast — it traveled 0.82 → 1.20 in nine weeks in 2020 — leaving little room for intermediate steps. Confidence on the precise warn level is medium (the calm-baseline band is well-sourced, but some peak-ratio values for 2008/2011 come from secondary commentary rather than a reconstructed daily series). The calibration also flags an unimplemented refinement worth noting: requiring critical to *persist* (2–3+ consecutive days >1.0) to separate a 2008/2011-style systemic inversion from a 2018-style one-day spike.

How to read it

• Normal (< 0.95, contango): the curve prices far-out risk above near-term risk — the textbook calm/risk-on regime. Readings in the 0.80–0.92 zone are deep complacency; in an AI-led tape this is the *expected* state and, on its own, says nothing about valuation excess (which is why this indicator's job is to confirm a *turn*, not measure froth). Cycle stage: mid-cycle / risk-on; no de-risking signaled by this gauge.
• Warn (0.95 – 1.0, curve flattening): the contango cushion is collapsing — the market is starting to bid up near-term protection toward parity with 3-month. This is the early heads-up that the regime is wobbling; positioning response is to tighten hedges and watch for confirmation, not yet a full risk-off. Because this leads drawdowns by 1–3 weeks, a warn reading appearing *while equities are still making highs* is the most informative case — a classic late-cycle divergence.
• Critical (≥ 1.0, backwardation): the curve has inverted — 30-day fear exceeds 3-month — the canonical "initiate hedges / risk-off" line confirmed by 2008, 2011, 2018 and 2020. A single-day cross flags a sharp correction (2018-style); a *sustained* hold above 1.0 historically accompanies 16–34% systemic drawdowns (2008/2011/2020). In an AI bubble context, a critical print is the fast-twitch confirmation that the slower leading buckets (credit spreads, breadth, leadership RS) have already been warning about a regime change that is now being priced in real time.

What it measures

The share of the AI-leadership watchlist that is trading *below* its own 200-day moving average — i.e., how broad the participation is underneath the headline AI indices. It matters in a bubble because a cap-weighted AI index can keep printing new highs while the majority of names quietly roll over; rising breadth-below (deteriorating internals) is the classic "the few mega-caps are masking a falling majority" tell that leads the index lower.

Source & fetch

LIVE / COMPUTED — there is no single upstream series; the metric is built bottom-up in leadership.py from individual stock prices.

• Universe: the 23-name AI watchlist hard-coded as LEADERSHIP_STOCKS in leadership.py (NVDA, AMD, AVGO, TSM, ASML, MU, ARM, INTC, QCOM, MRVL, CDNS, GLW, SNDK, ORCL, MSFT, CRWD, PANW, ADBE, GOOGL, AMZN, META, CRWV, PLTR). The three thematic ETFs in LEADERSHIP_ETFS (SMH, SOXX, IGV) are fetched and shown in the per-name table but are deliberately excluded from the breadth denominator (breadth is computed only over stock_rows).
• Price source: Yahoo Finance daily closes via yfinance, pulled by fetch_yahoo_close(ticker, start=...) in fetch_indicators.py — yf.download(ticker, start=start, auto_adjust=True), taking the adjusted Close, dropping NaNs, returning a [{date, value}] series.
• Cadence & history depth: refreshed on every dashboard build (a daily-cadence tool). To keep the per-name fan-out fast, the fetch is a bounded ~520-calendar-day window: in the main builder lead_start = today − 520 days is computed and passed to build_leadership_layer(fetch_yahoo_close, start=lead_start). 520 days (~358 trading days) is the minimum needed to compute a real 200-trading-day average plus headroom; a name needs ≥200 closes (ok = len(vals) >= 200) to count.
• Not manual, not feed: this indicator has no entry in manual_readings.json and no SentimenTrader CSV — it is wholly derived from live Yahoo prices. (Note: it is also not present in the legacy FORMULAS dict; its descriptive text lives in INDICATOR_GUIDE["lead-breadth"], and the formula string is attached inline in build_leadership_indicators().)

Calculation

Per name (in leadership_rows → pct_vs_sma):

1. sma_200 = mean(last 200 closes) (sma(values, 200)). 2. pct_vs_200dma = last_close / sma_200 − 1 — fractional distance from the 200-DMA; a name is "below" when this is < 0. Names with fewer than 200 closes (ok = False) are dropped.

Aggregate breadth (in leadership_aggregates), computed over the 23 stock rows only:

`` ok_stocks = [r for r in stock_rows if r.ok and r.pct_vs_200dma is not None] n = len(ok_stocks) below = count(r.pct_vs_200dma < 0 for r in ok_stocks) breadth_pct = round(below / n * 100, 1) # % of leaders BELOW their 200-DMA ``

So breadth_pct is a simple equal-weight headcount percentage (each name counts once, NVDA = PLTR), not a cap-weighted or RS-weighted figure. There is no smoothing, percentile-rank, or rate-of-change transform on the published value — it is the raw cross-sectional % below the 200-DMA on the latest common date. (The sibling lead-rs indicator is the equal-weight-basket-vs-SPX RS line; breadth itself is just the headcount.) A health gate applies upstream: if fewer than half the watchlist loads (n_ok < n_total // 2) the state is forced to unknown and the indicator is excluded from scoring.

Thresholds & statistical significance

Recalibrated 2026-06-07 (the calibration entry's suggested_adjustment is tagged [APPLIED 2026-06-07]). Explicit bands, "above" direction:

• < 35% below → NORMAL (100 pts)
• 35–55% below → WARN (50 pts)
• ≥ 55% below → CRITICAL (0 pts)

These are wired as warn = BREADTH_WARN = 35, crit = BREADTH_CRIT = 55, trigger = 55, trigger_type = "above" in build_leadership_indicators(). Because explicit warn/crit are supplied, compute_state() takes its explicit-band path and these values override the legacy ±10% rule — i.e., warn is the hard 35 line, not trigger × 0.9 = 49.5. (The state itself is also computed directly inline in leadership_aggregates/build_leadership_indicators with the identical ≥55 / ≥35 ladder.)

Grounding from calibration_data.json (confidence: Medium; verification: solid on the crisis anchors, lower on the top-divergence calibration). Bubbles are scarce, so the dated comparable set *is* the justification:

• Calm baseline: healthy uptrends run only ~20–40% of names below their 200-DMA. Today's broad-market read (~41–50% below per StreetStats/MacroMicro) already sits in the warn zone, so <35 NORMAL is a defensible calm-baseline anchor — and bands are set a touch tighter than the S&P 500 because a concentrated 23-name AI list is noisier and can mask deterioration.
• Crisis extremes were BOTTOMS, not tops: GFC bottom 2009-03-06 ≈ 99% below (the exact low), COVID 2020-03-23 ≈ 98% below (exact low, V-recovery), 2022 rate-shock trough 2022-09-30 ≈ 89% below (within ~3 weeks of the final low). Low breadth is overwhelmingly a wash-out/buy signal on the way down — which is *why* the critical line is set at 55, not 80+: 55% below is "off the complacency floor and into genuine distribution" (roughly halfway between the ~30% calm baseline and ~90% capitulation), not "crash imminent."
• The real top tell is DIVERGENCE, not an absolute level: at the 2000-03 dot-com top the % below 200-DMA was still modest (well under 50%) while the index made new highs and leadership narrowed — breadth had already peaked and rolled. The calibration explicitly notes the absolute bands will tend to fire "critical" *during/after* a selloff (often near bottoms) and may miss the early top, so the recommended companion rules (not encoded in this scalar) are a divergence flag and treating ≥80% below as a possible contrarian capitulation/oversold extreme, not "more critical."

How to read it

• Normal (<35% below, e.g. today's 17.4% with 26/26 names loaded): broad participation is intact — most AI leaders are above trend. Internals are confirming, not contradicting, the tape; no positioning change is warranted on this gauge alone.
• Warn (35–55% below): the majority is still up but a meaningful minority has broken trend — early distribution. This is the band the current broad market already sits in, so watch *direction*: breadth rising toward 55 while the AI index holds or makes new highs is the bearish-divergence setup that precedes index breakdowns by weeks. Tighten risk, lean on the lead-rs rollover and shock flags for confirmation.
• Critical (≥55% below): broad distribution — more than half the leaders are in their own downtrends while a few mega-caps prop up the index. This is the "the mask is off" reading; expect the cap-weighted index to follow. Caveat from the calibration: once readings push toward the 80–99% range seen in 2009/2020/2022, the signal flips contextually from "danger" to "capitulation/oversold" — those extremes marked *bottoms*, so a screaming-critical reading deep into a selloff is a wash-out, not a fresh top warning.

What it measures

Whether the AI-leadership cohort is still *out-leading* the broad market on a relative-strength (RS) basis — an equal-weight basket of ~23 AI-stack names divided by SPX, then judged against its own 200-day moving average. In every bubble unwind the leaders lose *relative* strength weeks-to-months before they lose *absolute* price and before the cap-weighted index rolls over, so a leadership RS rollover is one of the earliest, highest-value pre-top tells for an AI bubble.

Source & fetch

Live / computed (no manual entry, no external feed). The indicator is assembled in leadership.py (build_leadership_layer) and packaged into the dashboard dict by build_leadership_indicators() in fetch_indicators.py (the rs = {... "id": "lead-rs" ...} block).

• Upstream source: daily adjusted closes from yfinance (yf.download(..., auto_adjust=True)), pulled by fetch_yahoo_close(ticker, start=...) in fetch_indicators.py. That same function is *injected* into build_leadership_layer(fetch_yahoo_close, start=lead_start) so the layer is unit-testable without a network.
• Tickers: the 23-name LEADERSHIP_STOCKS watchlist in leadership.py — NVDA, AMD, AVGO, TSM, ASML, MU, ARM, INTC, QCOM, MRVL, CDNS, GLW, SNDK, ORCL, MSFT, CRWD, PANW, ADBE, GOOGL, AMZN, META, CRWV, PLTR — divided by the benchmark BENCHMARK = "SPY" (called "SPX" in the labels). Note: the three LEADERSHIP_ETFS (SMH, SOXX, IGV) are fetched and shown in the per-name table but are deliberately excluded from the RS basket and the breadth count.
• Cadence & history depth: run on each tracker build. History is a bounded ~520-calendar-day window — lead_start = today − 520 days (line 1523) — which is deliberately short for speed but still long enough to compute a 200-trading-day MA on the resulting RS series. Each leg needs ≥200 observations (ok = len(vals) >= 200) to count.
• Resilience: each ticker is fetched in a try/except; a name that fails to load is simply dropped from price_map. build_leadership_indicators() scores the whole indicator "unknown" (excluded from the composite) unless at least half the watchlist loaded: healthy = lead["n_ok"] >= max(1, lead["n_total"] // 2).

Calculation

Three stacked transforms, all in leadership.py:

1. Equal-weight leaders basket (equal_weight_index): inner-join all loaded leader series on common dates; normalize each leg to 100 at the common start (v / base * 100); then take the simple average across legs per date. This is a true equal-weight basket (each name 1/N), not cap-weighted, so a single mega-cap can't dominate. 2. Relative strength vs SPX (relative_strength): align the basket and SPY on date, form the ratio basket / SPY per common day, then index the *ratio* to 100 at the first common date: value = round(ratio / base * 100, 3). The charted "RS line" is this indexed ratio (e.g. a reading of ~290 means the basket has out-returned SPY ~2.9x since the window start). 3. 200-DMA gate + state (leadership_aggregates, lines 118-128): compute rs_sma = sma(rsv, 200) (mean of the last 200 RS values) and rs_last = rsv[-1], then: - rs_last < rs_sma * 0.95 → critical (RS more than 5% below its 200-DMA) - rs_last < rs_sma → warn (RS below its 200-DMA) - otherwise → normal - either value missing → unknown

The result surfaces as rs_last, rs_sma200, and rs_state. In build_leadership_indicators() this is wrapped with trigger: None, trigger_type: "below_200dma", and state = lead["rs_state"] if healthy else "unknown".

Important: because this indicator carries its own pre-computed state and a None trigger, the warn/critical assignment is the in-code 200-DMA gate above — it does not route through compute_state()'s generic ±10% band rule. The explicit "below 200-DMA = warn / >5% below = critical" logic deliberately overrides the default ±10% treatment used by simpler level indicators.

Thresholds & statistical significance

There is no fixed numeric level; the thresholds are *relative* (the RS line's own 200-DMA) with a 5%-below band for the critical tier. The calibration entry (calibration_data.json → lead-rs) leaves these essentially unchanged ("the levels are essentially right") and grounds them in four dated, cross-era analogues where narrow-leader RS loss preceded the top:

• 2000 dot-com: Tech-sector RS peaked March 2000 and rolled over while the S&P-ex-tech didn't peak for ~14 more months — by which point Tech was already down ~55%. The leaders' RS breakdown led the broad top by over a year (Nasdaq ultimately −78%).
• 2007 GFC: the prior leaders (financials/homebuilders) RS quietly rolled over before the S&P's 2007-10-09 peak of 1,565.15, leading a ~57% decline — a leader-RS-below-200-DMA gate would have warned ~3 months ahead.
• 2021-22 mega-cap/FANG: leaders broke below their 200-DMA in early January 2022 (S&P peaked 4,796 on 2022-01-03); the FANG basket later drew down 55.92%. Here the 200-DMA break essentially was the top, and the >5% RS undercut followed as the decline accelerated.
• 1972-73 Nifty Fifty (qualitative, pre-dates computed RS): leaders' RS broke early 1973; the group fell −19%/−38% (1973/74) vs the index's −14%/−26%, confirming the cross-era pattern that narrow leaders losing RS fall far more than the index.

The rationale is explicitly a calm-vs-danger framing: in a healthy cycle the leaders are, by definition, above their rising 200-DMA (calm baseline). The warn tier (RS below the 200-DMA) is placed exactly at the calm/danger boundary endorsed by standard technical practice and by all four analogues — it is the single most-repeated pre-top tell and is valuable *because* it is binary and early. The critical tier (>5% below) is a confirmation/acceleration tier: a 5% undercut of a slow-moving 200-DMA on a relative ratio is a decisive break, not the whipsaw chop that plagues a bare MA cross, and in the comparables it typically arrived *after* the index had already begun falling. Confidence is rated Medium: the direction and the 200-DMA-on-RS *design* are high-confidence (StockCharts methodology plus four independent 1973-2022 analogues), but the exact 5% critical cut is inferred rather than measured, because no AI-leaders RS series existed before ~2023 — the historical proxies are sector/leader-group RS, not an equal-weight AI basket. (The calibration also suggests, but the code has not applied, optional refinements: a ~10-15 day persistence filter on warn, and widening critical to ~7-8% or pairing it with a falling 200-DMA.)

How to read it

• Normal (RS above its 200-DMA): leadership intact — the AI cohort is still out-running SPX and making higher highs/higher lows in relative terms. This is the expected, healthy-cycle baseline (today's reading sits well above, e.g. RS ~290). It does *not* mean valuations are safe, only that the leaders are still leading.
• Warn (RS below its 200-DMA): the first crack — the leaders have stopped out-performing even though the index may still be at or near highs. This is the early-warning regime that historically appeared 6-12 weeks ahead of the broad tape (and ~14 months ahead in 2000). Treat it as a signal to reduce concentration risk and tighten exits on the AI complex, not as a confirmed top.
• Critical (RS >5% below its 200-DMA): leadership is actively breaking down and dragging — a decisive, regime-confirmed break that in past cycles coincided with the decline already accelerating (e.g. early 2022). At this stage the leaders are no longer a place to hide; the appropriate posture is defensive/late-cycle, expecting the relative weakness to bleed into absolute price and broad-index weakness.

What it measures

The price of IBIT (iShares Bitcoin Trust ETF) used as a real-time proxy for U.S. spot-Bitcoin-ETF flows and broad speculative risk appetite. The logic for an AI-bubble tracker is *capital-rotation*: when crypto and AI rip together, it is one giant single-theme risk-on trade, and when crypto bleeds while equities keep grinding higher you are watching capital crowd into one narrowing theme — a textbook late-cycle euphoria/distribution tell. It is the sentiment bucket's "is the speculative tide coming in or going out?" gauge.

Source & fetch

• Upstream source: Yahoo Finance, ticker IBIT (BlackRock iShares Bitcoin Trust), auto-adjusted daily closes.
• Fetcher: fetch_indicators.py → build_indicator() hits the direct-ticker Yahoo branch (elif "yahoo" in meta and "compute" not in meta:), which calls fetch_yahoo_close("IBIT"). The meta block is {"id": "btc-etf-flows", "bucket": "E_sentiment", "yahoo": "IBIT", "unit": "$", "trigger": None, "trigger_type": "roc"}.
• fetch_yahoo_close(ticker, start=None, weekly=False) calls yf.download(ticker, period="max", progress=False, auto_adjust=True), takes the Close column (.squeeze() to flatten yfinance's MultiIndex), drops NaNs, and returns a list of {"date": "YYYY-MM-DD", "value": round(close, 4)}.
• Cadence & history depth: pulled fresh on every dashboard refresh, full available history via period="max" — but IBIT only launched January 2024, so the real series is ~2.4 years long. Note: the FORMULAS text describes this as "Yahoo weekly closes," but the actual call passes no start and weekly=False, so the branch fetches full daily closes (the weekly resample-to-W-FRI path is *not* taken for this indicator).
• Not manual / not a feed: btc-etf-flows is absent from manual_readings.json and is not a SentimenTrader CSV — it is a 100% live yfinance pull. There is no XBRL/FRED dependency. The only thing it shares with the manual block is the conceptual *flow* data it proxies; the actual ETF net-flow dollars (CoinShares / Farside / the issuers' daily creation-redemption tapes) are not ingested — IBIT price is the standing proxy, with the calibration entry noting a planned future upgrade to real rolling-flow dollar series.

Calculation

Effectively none — this is a raw price chart, not a derived metric. The history is the IBIT close series straight from fetch_yahoo_close (rounded to 4 dp). There is no ratio, no normalization-to-100, no 200-DMA gate, no TTM/YTD differencing, no percentile rank, and no rate-of-change transform applied in code — despite trigger_type being labelled "roc".

The charted value is just the latest close: out["current"] = history[-1]["value"].

State assignment: because trigger is None, the build_indicator else-branch calls compute_state(current, trigger=None, trigger_type="roc", warn=None, crit=None), and the very first guard in compute_state is:

`` if current is None or trigger is None: return "normal" ``

So the indicator always resolves to normal (100 points). It is a pure chart-watch: it contributes a constant 100 to the E_sentiment bucket and never fires a warn/critical of its own. (The ±10% legacy band rule in compute_state is moot here — it is never reached because the None-trigger guard short-circuits first; and there are no explicit warn/crit keys in the meta to override it.)

Thresholds & statistical significance

There are no numeric warn/critical thresholds in the running code — trigger=None, so the only "threshold" is the implicit always-normal. This is deliberate and reflects the live calibration: the calibration_data.json entry's suggested_adjustment is *"Keep 'trend-watch' (do NOT impose a fixed numeric level — it would mislead)"*, and crucially it is not prefixed [APPLIED ...], so the operational warn/critical rules it proposes are documented intent, not yet wired into compute_state. The dollar anchors that justify staying trend-only come from the three dated comparables:

• 2021 full-year crypto-fund inflows (pre-ETF proxy, CoinShares, 2021-12-31): record $10.6B net annual inflows (up from $6.7B in 2020), GBTC premium up to ~297% before flipping to a discount. Record inflow *years* clustered at the top — BTC peaked ~$69k (Nov 2021), then a ~75% bear to ~$16k with Terra/3AC/FTX. Establishes that *record inflows mark euphoria peaks*.
• Post-election euphoria peak (2024-11-30): all-time monthly record ~$6.46–6.49B net inflow into U.S. spot BTC ETFs, IBIT ~$5.6B (~87% of the total), record single-day inflow $1.37B (2024-11-07), BTC +45% ($68k→$99k). This is the cycle's high-water demand impulse — the reference froth anchor (~$6.5B/month).
• Record outflow / regime break (2025-11→12): Nov 2025 −$3.48B and Dec 2025 −$1.09B, a two-month −$4.57B (worst since the Jan-2024 debut; prior worst −$4.32B in Feb–Mar 2025), IBIT's first-ever monthly outflow (−$2.3B), record single-day outflow $523M, BTC −20%; cohort avg cost basis ~$90.2k vs price $74–78k left holders ~15–16% underwater. This is the metric's only in-sample *actionable* signal — and it shows the outflow side, not the inflow side, is the warning.

The (un-applied) operational ladder these comparables imply: WATCH = inflows hit record territory (~$6.5B/mo) then stall; WARN = rolling-4-week net flows turn negative and IBIT posts a net monthly outflow (base rate was zero until Nov-2025, so one occurrence is the signal); CRITICAL = rolling-8-week net outflows breach ~−$4.3 to −$4.6B and price is below the cohort's ~$90k average cost basis (flows *and* positioning both stressed). Calibration confidence is "Low-to-moderate" (verification: "mixed"): the *direction* of the logic is well-supported, but the dollar anchors are soft because the series is only ~2.4 years long and the ETF complex's AUM is still structurally growing — hence the instruction to re-baseline the dollar anchors annually and the decision to keep it numeric-threshold-free for now.

How to read it

Because it scores a constant normal, this indicator never moves the composite by itself — read the chart shape, not the state badge:

• Normal / risk-on: IBIT trending up alongside AI equities → the speculative tide is broad and rising. Healthy, mid-cycle; no information edge against the AI trade.
• Watch (froth): IBIT pushing record-high *inflow*-driven prices then stalling/decelerating at the highs (the ~$6.5B/mo Nov-2024 analogue) → distribution risk building; single-theme leadership getting crowded.
• Warn: IBIT rolling over — a sustained price decline while equities are still rising → capital is concentrating into one narrowing theme and leaving the speculative complex; classic late-cycle divergence. The first-ever net monthly *outflow* is itself the tell.
• Critical: a deep, sustained drawdown that breaches the prior worst outflow stretch with holders underwater (the Nov–Dec 2025 −$4.57B / sub-cost-basis state) → the risk-appetite regime has broken; the speculative bid that underwrote the AI melt-up is gone. The actionable danger is always the outflow side: rising IBIT confirms risk-on, but a sustained decline against rallying equities is the late-cycle euphoria-unwind warning this gauge exists to flag.

What it measures

A 0-100 quantitative froth composite for primary-issuance market heat, replacing the former hand-scored dial. Higher = more froth. Two legs are combined: (A) IPO activity intensity — registered IPO count + proceeds from Finnhub, z-scored vs ~3 years of weekly history; (B) retail-investor euphoria — AAII % Bullish survey (with ARKK price momentum as fallback). The composite reflects the *registered* IPO market and retail sentiment; private mega-round froth (OpenAI/SpaceX/Anthropic) is NOT captured by IPO feeds and remains a manual override consideration.

Source & fetch

LIVE — auto-fetched via ipo_froth_fetch.py (replaces the former manual placeholder).

Leg A — IPO activity (Finnhub): GET https://finnhub.io/api/v1/calendar/ipo with from=~3yr_ago&to=today (key from .env FINNHUB_API_KEY; free tier). Returns an ipoCalendar list of IPO entries, each with date, totalSharesValue, status, etc. The module bins these into weekly buckets (count of IPOs + sum of totalSharesValue), then computes separate z-scores for trailing-4-week-average count and proceeds vs the full ~3yr weekly history. The two z-scores are averaged into the Leg A score.

Leg B — Retail froth:

• *Primary:* LOCAL SentimenTrader AAII survey CSVs — survey_aaii_bulls.csv (% bullish, column survey_aaii_bulls_close) and survey_aaii_bears.csv (% bearish, column survey_aaii_bears_close) from the sentimentdatadailyfeed/ folder. Loaded via sentiment_feed._read_feed_csv(), which merges each file with its _old companion for full history and handles mixed date formats (YYYY-MM-DD in primary, MM/DD/YYYY in _old files). Dates inner-joined on common weeks; Bull-Bear Spread = % bullish − % bearish. The spread is percentile-ranked over its full history (pctile_rank(spread_series, latest_spread)): high spread (bulls >> bears) = retail euphoria = high froth (0–100). AAII is weekly; freshness gate = 14 days (same FEED_STALE_DAYS as other feed indicators).
• *Fallback (if AAII local files are missing or stale >14d):* ARKK (ARK Innovation ETF) daily price via yfinance — z-score of the current price vs the trailing ~2yr daily series. legs_used and state_note record which source was actually used ("aaii-local" vs "arkk").

Calculation

For each leg:

`` z = (current - mean(history)) / std(history) z = clip(z, -3, +3) score_0_100 = (z + 3) / 6 * 100 ``

Scale: -3sigma -> 0, 0sigma -> 50, +2sigma -> ~83.3, +3sigma -> 100.

`` composite = mean(leg_A_score, leg_B_score) ``

State from explicit bands (trigger_type: "above"):

`` if composite >= 95: state = "critical" elif composite >= 85: state = "warn" else: state = "normal" ``

The composite is also a FROTH_INPUTS member (mode="raw"): its 0-100 value flows directly into the Froth Overlay as-is.

Thresholds & how to read it

Bands: warn >= 85, critical >= 95 (trigger_type "above"). The +2sigma composite ~= 83 sits just below the warn threshold: warn fires when both legs are simultaneously near +2sigma, consistent with late-cycle issuance peaks (Blackstone 2007, SPAC/crypto late 2020). Critical at 95 = both legs simultaneously at ~+2.7sigma, consistent with blow-off tops (Q1 2000, Q1 2021).

• Normal (< 85): IPO activity and retail sentiment are within historical norms.
• Warn (85-95): elevated froth; late-cycle issuance intensity and retail euphoria combining.
• Critical (>= 95): blow-off IPO frenzy and retail euphoria simultaneously at extremes. Private-deal froth (OpenAI/SpaceX rounds) would push this higher but is not captured; treat critical here as a floor. Bucket E_sentiment + Froth gauge.

What it measures

A single 0-100 contrarian gauge of crowd euphoria/complacency, built by averaging five SentimenTrader sentiment and positioning models (Smart/Dumb Money Confidence spread, CNN Fear & Greed, Panic/Euphoria model, total put/call, SPY Optix). It matters to an AI bubble because the classic top-of-cycle tell is *unanimous* complacency — smart money fading the rally, puts neglected, optimism maxed — appearing simultaneously while prices still rise. A high reading means the marginal buyer is exhausted; CONTRARIAN, so 100 = maximum danger.

Source & fetch

Kind: feed. Five daily CSVs that the user downloads from SentimenTrader into the local feed folder G:\My Drive\Trading\Build Alpha\data\sentimentdatadailyfeed (FEED_DIR in sentiment_feed.py). There is no API call — the files are hand-refreshed and the module reads whatever is on disk.

Each sub-input is loaded by _read_feed_csv(primary_name, value_col), which:

• reads the primary file and, if present, concatenates a companion <stem>_old.csv so the *full* history is available (e.g. smart_dumb_spread.csv + smart_dumb_spread_old.csv);
• finds the Date column case-insensitively and parses it with pd.to_datetime(..., dayfirst=False) to handle the mixed YYYY-MM-DD / MM/DD/YYYY formats SentimenTrader emits;
• coerces the value column to float, drops NaNs, sorts ascending, and drop_duplicates(subset=Date, keep="last") so the primary file's value wins on overlapping dates.

The five files, their exact value columns, and contrarian direction (set in _build_euphoria_subscores()): 1. smart_dumb_spread.csv → column model_smart_dumb_spread_close — Smart minus Dumb Money confidence. Inverted (a low/negative spread = dumb money euphoric). 2. model_cnn_fear_greed.csv → column model_cnn_fear_greed_close — 0-100, high = greed. Direct. 3. model_panic_euphoria.csv → column model_panic_euphoria_close — high = euphoria. Direct. 4. pc_total.csv → column pc_total_close — total put/call ratio. Inverted (low P/C = call-heavy = euphoria). 5. spy_optix.csv → column etf_spy_close (SentimenTrader names the column after the ticker, not "optix") — SPY Optimism Index 0-100, high = euphoria. Direct.

Freshness handling (two stages). A sub-input needs ≥5 rows to be considered at all. Then _accept() checks its latest date against FEED_STALE_DAYS = 14: any sub-input whose newest date is more than 14 days old is DROPPED entirely from the live composite, the sub-score list, and history (logged as DROPPED ) — this prevents a frozen feed (e.g. spy_optix stuck at 2024-07) from masquerading as a live signal. Separately, for *history* construction, _build_euphoria_history() skips any series whose last date is >90 days old so it doesn't collapse the date-overlap to zero. Cadence: daily, manually; depth: full available history (primary + _old), windowed to the last 60 common dates (HISTORY_WINDOW = 60) for the chart.

This indicator is built by build_senti_euphoria_indicator() and appended to the indicator list via build_sentiment_indicators() in fetch_indicators.py (~line 1527). It carries feed=True and ships its *own* formula, guide, warn, crit, and pre-computed state — it does NOT use the FORMULAS / INDICATOR_GUIDE dicts or the generic compute_state() path that the live/manual indicators use.

Calculation

Per-input percentile via pctile_rank(series, latest_value): the score is the fraction of all historical values strictly less than the latest value, ×100 ((series < latest_value).mean() * 100, rounded to 1 dp). Strict-less-than is used deliberately so the maximum value doesn't always pin to 100. If a series has <2 points it returns a neutral 50.

Per-input euphoria sub-score:

• Direct inputs (fear_greed, panic_euphoria, spy_optix): subscr = pctile_rank(series, latest).
• Inverted inputs (smart_dumb, pc_total): raw = pctile_rank(series, latest); subscr = 100 - raw — so a low spread or low put/call maps to a *high* euphoria score.

Composite (the indicator's current): the equal-weighted mean of the sub-scores of only the fresh (non-stale) inputs:

`` composite = round( sum(subscr for fresh inputs) / n_fresh , 1 ) ``

So with all five fresh it's a 5-input average; if one is dropped for staleness it becomes a 4-input average, etc. Honest-failure gate: if fewer than 2 fresh inputs survive (len(subscores) < 2), the indicator returns state="unknown", current=None, stale=True and is excluded from bucket scoring rather than scored on thin data.

The chart history (_build_euphoria_history) recomputes each fresh series into its own per-date percentile series (inverted ones flipped to 100 - pct), outer-joins them, keeps rows with at least max(1, n//2) non-NaN columns, takes the last 60 rows, and averages across columns to a composite line. If <5 common dates survive it falls back to a single point at today's composite. as_of is the max latest-date across the fresh inputs.

Thresholds & statistical significance

Explicit contrarian bands (defined in build_senti_euphoria_indicator() as WARN_BAND = 70.0, CRIT_BAND = 85.0, trigger_type="above"): <70 NORMAL · 70-85 WARN · ≥85 CRITICAL → 100/50/0 points. Because these are explicit warn/crit percentile bands, the generic ±10% warning band (trigger*0.9) in compute_state() does NOT apply — explicit bands always override the ±10% rule, and in any case this indicator computes its own state inline (if composite >= 85: critical elif >= 70: warn else normal) rather than calling compute_state().

Note on calibration grounding: calibration_data.json has no senti-euphoria entry (its keys cover credit, valuation, breadth, vix-term, etc.), so unlike the threshold-recalibrated indicators (hy-oas, ig-oas, vix-term, etc.) these bands have *not* been independently back-tested against dated bubble episodes — they are percentile cutoffs chosen on the gauge's own 0-100 scale. The justification is structural and inherited from the nearest sentiment comparable that *is* calibrated, vix-term (the other E-bucket-flavored fear gauge): there the panel found that genuine stress regimes (2008, 2011, 2018, 2020) cluster in the top decile of the metric's range and confirmed warn 0.95 / critical 1.0 as the "curve flattening" vs "regime break" divide — i.e. a top-quartile/top-decile split. The 70/85 design mirrors that logic on a percentile scale: 70 = the reading is more euphoric than 70% of its own history ("off the complacency floor," elevated), 85 = top-15% blow-off euphoria where multiple sentiment models are simultaneously stretched — the historically robust "everyone's bullish at once" topping signature this metric is built to catch. The 15-point warn→critical gap preserves an actionable escalation runway rather than firing warn and critical near-simultaneously.

How to read it

Read it CONTRARIAN — a *high* score is bad. Normal (<70): at least one or two of the five models still show some caution (smart money not fully faded, puts being bought, optimism not maxed) — sentiment is not yet a top-of-cycle constraint; treat AI-trade exposure as supportable on this axis. Warn (70-85): the crowd has moved well off the complacency floor — most models are in their upper range together. This is the "everyone has noticed the AI trade" zone; a heads-up to stop adding into strength and watch the credit/breadth buckets for confirmation. Critical (≥85): blow-off euphoria — smart-dumb spread near/below zero, put/call call-heavy, Fear & Greed and Optix both elevated, all at once. Historically the positioning configuration that precedes tops; in cycle-stage terms this is late-stage froth where the marginal buyer is exhausted, the contrarian signal for trimming/hedging. Unknown/stale: fewer than 2 fresh CSVs (the 14-day gate fired) — the gauge is dark, not bullish; re-download the SentimenTrader CSVs before trusting any "all clear." Always corroborate with the rest of bucket E_sentiment (10% of the Current score, 15% of the Future score) — a single sentiment gauge is a tell, not a trigger.