feat: per-metric historical exploration with click-to-select context

- Click any metric card to see historical periods where it was at a similar level - Purple dot highlighting on chart shows matching periods - Metric overlay line plotted on chart (dashed purple) - Metric Context panel shows percentile, comparable days, avg forward returns, and historical examples from different market cycles - New /api/metric-context endpoint for per-metric similarity analysis - Backtest chart_data now includes per-metric raw values - score_day() returns raw metric values alongside scores - Fixed JS SyntaxError from broken inline onclick escaping (uses addEventListener) Co-Authored-By: Claude Opus 4.6 <<EMAIL>>
2026-06-28 22:49:15 +00:00
parent 4647c596b3
commit 8fca6181d5
4 changed files with 873 additions and 48 deletions
@@ -165,7 +165,9 @@ def run_scrape(force_full=False):
        # 3. On-chain metrics — use cached values (historical data is permanent)
        onchain_keys = ["puell_multiple", "mvrv_zscore", "reserve_risk", "rhodl_ratio",
                        "nupl", "200w_sma", "lth_realized_price", "hash_ribbons",
-                        "pi_cycle_bottom", "lth_supply"]
+                        "pi_cycle_bottom", "lth_supply", "sopr", "sellside_risk",
+                        "active_address_momentum", "txcount_momentum", "nvt_price",
+                        "vdd_multiple"]
        
        has_cached_onchain = any(existing_cache.get(k, {}).get("value") is not None for k in onchain_keys)
        
@@ -176,6 +178,12 @@ def run_scrape(force_full=False):
                from scrapers import lookintobitcoin
                onchain = lookintobitcoin.scrape_all()
                metrics.update(onchain)
+                try:
+                    from scrapers import checkonchain
+                    metrics.update(checkonchain.scrape_all())
+                except Exception as e:
+                    log.error("CheckOnChain scraping failed: %s\n%s", e, traceback.format_exc())
+                    _last_error = f"CheckOnChain scraping failed: {e}"
                metrics["_onchain_timestamp"] = datetime.now(timezone.utc).isoformat()
            except Exception as e:
                log.error("LookIntoBitcoin scraping failed: %s\n%s", e, traceback.format_exc())
@@ -341,6 +349,46 @@ def _fetch_models(provider, providers):

 # ── API Routes ────────────────────────────────────────────────────────────

+def _with_informational_onchain_metrics(scored, cache):
+    """Add non-scored on-chain data cards without changing composite scoring."""
+    if not isinstance(scored, dict):
+        return scored
+
+    enriched = dict(scored)
+    metrics = [dict(m) for m in scored.get("metrics", [])]
+    existing_keys = {m.get("key") for m in metrics}
+
+    lth_supply = cache.get("lth_supply", {})
+    lth_value = lth_supply.get("value")
+    if lth_value is not None and "lth_supply" not in existing_keys:
+        trend = lth_supply.get("trend")
+        trend_text = f" — {trend}" if trend else ""
+        metrics.append({
+            "name": "Long-Term Holder Supply",
+            "key": "lth_supply",
+            "value": lth_value,
+            "display_value": f"{lth_value:,.0f} BTC",
+            "score": None,
+            "description": "Informational on-chain metric; not included in the composite score" + trend_text,
+            "recent": lth_supply.get("recent", []),
+        })
+
+    pi_cycle = cache.get("pi_cycle_bottom", {})
+    pi_value = pi_cycle.get("value")
+    if pi_value is not None and "pi_cycle_bottom" not in existing_keys:
+        metrics.append({
+            "name": "Pi Cycle Bottom",
+            "key": "pi_cycle_bottom",
+            "value": pi_value,
+            "display_value": f"{pi_value:,.2f}" if isinstance(pi_value, (int, float)) else str(pi_value),
+            "score": None,
+            "description": "Informational on-chain cycle metric; not included in the composite score",
+            "recent": pi_cycle.get("recent", []),
+        })
+
+    enriched["metrics"] = metrics
+    return enriched
+
@app.get("/api/data")
 def api_data(mode: str = "classic"):
    """Return current cached metrics + scores.
@@ -351,6 +399,7 @@ def api_data(mode: str = "classic"):
        scored = cache.get("_scored_ml", cache.get("_scored", {}))
    else:
        scored = cache.get("_scored", {})
+    scored = _with_informational_onchain_metrics(scored, cache)
    price_data = cache.get("price", {})
    drawdown_data = cache.get("drawdown", {})
    extras = cache.get("price_extras", {})
@@ -503,8 +552,17 @@ DASHBOARD_HTML = """<!DOCTYPE html>
 .meta-row{display:flex;gap:16px;flex-wrap:wrap;margin-top:8px;font-size:.8rem;color:var(--text-dim)}
 .meta-row span{display:flex;align-items:center;gap:4px}
 .metrics-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(300px,1fr));gap:12px;margin-bottom:20px}
-.metric-card{background:var(--card);border-radius:10px;padding:14px;border:1px solid var(--border);transition:border-color .15s}
+.metric-card{background:var(--card);border-radius:10px;padding:14px;border:1px solid var(--border);transition:border-color .15s;cursor:pointer}
 .metric-card:hover{border-color:var(--text-dim)}
+.metric-card.selected{border-color:#a78bfa;box-shadow:0 0 0 1px #a78bfa,0 0 12px rgba(167,139,250,0.15)}
+.metric-click-hint{font-size:.6rem;margin-left:4px;opacity:0;transition:opacity .15s}
+.metric-card:hover .metric-click-hint{opacity:.5}
+.metric-card.selected .metric-click-hint{opacity:1}
+.mc-examples-title{font-size:.75rem;color:#94a3b8;text-transform:uppercase;letter-spacing:.06em;margin-bottom:6px}
+.mc-example{font-size:.8rem;font-family:var(--mono);padding:4px 0;border-bottom:1px solid rgba(255,255,255,0.03)}
+.mc-ex-date{color:#e2e8f0}
+.mc-ex-cycle{color:#a78bfa;font-size:.7rem}
+.mc-ex-price{color:#94a3b8}
 .metric-header{display:flex;justify-content:space-between;align-items:flex-start;margin-bottom:8px}
 .metric-name{font-size:.85rem;font-weight:600}
 .metric-score{display:flex;align-items:center;gap:6px}
@@ -588,6 +646,20 @@ DASHBOARD_HTML = """<!DOCTYPE html>
  <a href="/backtest" style="font-size:.8rem;color:#22d3ee;text-decoration:none;margin-top:8px;display:inline-block">View full backtest &rarr;</a>
 </div>

+<!-- Metric Context Panel (shown when a metric is selected) -->
+<div class="card" id="metricContextPanel" style="margin-bottom:20px;display:none;border-color:#a78bfa">
+  <div style="display:flex;justify-content:space-between;align-items:center;margin-bottom:8px">
+    <h2 style="color:#a78bfa" id="mcTitle">Metric Context</h2>
+    <button onclick="if(selectedMetric) selectMetric(selectedMetric, '')" style="background:none;border:1px solid #a78bfa;color:#a78bfa;padding:4px 10px;border-radius:4px;cursor:pointer;font-family:var(--mono);font-size:.75rem">✕ Clear</button>
+  </div>
+  <div id="mcCurrent" style="font-size:1rem;font-family:var(--mono);margin-bottom:4px"></div>
+  <div id="mcPercentile" style="font-size:.8rem;color:#94a3b8;font-family:var(--mono);margin-bottom:4px"></div>
+  <div id="mcComparable" style="font-size:.8rem;color:#94a3b8;font-family:var(--mono);margin-bottom:8px"></div>
+  <div id="mcReturns" style="font-size:.9rem;font-family:var(--mono);line-height:1.6;margin-bottom:8px"></div>
+  <div id="mcExamples" style="display:none"></div>
+  <a href="/backtest" style="font-size:.8rem;color:#a78bfa;text-decoration:none;margin-top:8px;display:inline-block">View full backtest &rarr;</a>
+</div>
+
 <!-- Metrics Grid -->
 <h2>On-Chain Metrics</h2>
 <div class="metrics-grid" id="metricsGrid">
@@ -690,6 +762,8 @@ function drawSparkline(canvasId, data, color) {
  ctx.stroke();
 }

+let selectedMetric = null;
+
 function renderMetrics(metrics) {
  const grid = document.getElementById('metricsGrid');
  if (!metrics || !metrics.length) {
@@ -703,10 +777,11 @@ function renderMetrics(metrics) {
    const color = m.score != null ? scoreColor(m.score, 10) : '#64748b';
    const fillPct = m.score != null ? (m.score / 10 * 100) : 0;
    const hasSparkline = m.recent && m.recent.length > 2;
+    const isSelected = selectedMetric === m.key ? ' selected' : '';

-    html += '<div class="metric-card">';
+    html += '<div class="metric-card' + isSelected + '" data-key="' + m.key + '" data-name="' + m.name.replace('"', '&quot;') + '">';
    html += '<div class="metric-header">';
-    html += '<div class="metric-name">' + m.name + '</div>';
+    html += '<div class="metric-name">' + m.name + '<span class="metric-click-hint">👆</span></div>';
    html += '<div class="metric-score">';
    html += '<div class="metric-score-bar"><div class="metric-score-fill" style="width:' + fillPct + '%;background:' + color + '"></div></div>';
    html += '<div class="metric-score-num" style="color:' + color + '">' + score + '</div>';
@@ -733,11 +808,112 @@ function renderMetrics(metrics) {
      }
    });
  });
+
+  // Attach click handlers to metric cards
+  document.querySelectorAll('.metric-card').forEach(card => {
+    card.addEventListener('click', function() {
+      const key = this.getAttribute('data-key');
+      const name = this.getAttribute('data-name');
+      if (key) selectMetric(key, name);
+    });
+  });
+}
+
+// Metric selection + context panel
+function selectMetric(metricKey, metricName) {
+  if (selectedMetric === metricKey) {
+    // Deselect if clicking the same one
+    selectedMetric = null;
+    window._highlightMetric = null;
+    document.getElementById('metricContextPanel').style.display = 'none';
+    const panel = document.getElementById('histContext');
+    if (panel) panel.style.display = 'block';
+    applyChartRange(currentRange); // Re-render chart without highlight
+  } else {
+    selectedMetric = metricKey;
+    loadMetricContext(metricKey, metricName);
+  }
+  poll(); // Re-render metric cards with highlight
+}
+
+async function loadMetricContext(metricKey, metricName) {
+  try {
+    const r = await fetch('/api/metric-context?metric=' + encodeURIComponent(metricKey) + '&mode=' + currentMode);
+    const ctx = await r.json();
+    if (ctx.error) {
+      showToast(ctx.error, 'error');
+      return;
+    }
+
+    // Show metric context panel, hide composite context
+    const panel = document.getElementById('histContext');
+    if (panel) panel.style.display = 'none';
+
+    const mcp = document.getElementById('metricContextPanel');
+    mcp.style.display = 'block';
+
+    document.getElementById('mcTitle').textContent = metricName;
+    document.getElementById('mcCurrent').textContent = 'Current: ' + (ctx.current_raw != null ? ctx.current_raw : 'N/A');
+    document.getElementById('mcPercentile').textContent = 'Metric value in top ' + (100 - ctx.percentile).toFixed(1) + '% historically';
+    document.getElementById('mcComparable').textContent = ctx.comparable_days + ' comparable days found';
+
+    const fmtR = (v) => v == null ? '--' : (v >= 0 ? '+' : '') + v.toFixed(1) + '%';
+    const cR = v => v != null && v >= 0 ? '#22c55e' : '#ef4444';
+    const periods = [['30d', ctx.avg_30d_return], ['90d', ctx.avg_90d_return], ['180d', ctx.avg_180d_return], ['1yr', ctx.avg_1yr_return]];
+    let retHtml = '';
+    for (const [label, val] of periods) {
+      if (val != null) retHtml += '<strong style="color:' + cR(val) + '">' + label + ': ' + fmtR(val) + '</strong> · ';
+    }
+    document.getElementById('mcReturns').innerHTML = retHtml ? 'Avg returns when ' + metricName + ' was similar: ' + retHtml : 'No forward return data available';
+
+    // Examples
+    const exEl = document.getElementById('mcExamples');
+    if (ctx.examples && ctx.examples.length) {
+      let exHtml = '<div class="mc-examples-title">Historical examples:</div>';
+      ctx.examples.forEach(ex => {
+        const fwd30 = ex.forward_returns['30d'];
+        const fwd365 = ex.forward_returns['365d'];
+        exHtml += '<div class="mc-example">';
+        exHtml += '<span class="mc-ex-date">' + ex.date + '</span> ';
+        exHtml += '<span class="mc-ex-cycle">' + ex.cycle + '</span> ';
+        exHtml += '<span class="mc-ex-price">$' + (ex.price ? ex.price.toLocaleString() : 'N/A') + '</span>';
+        if (fwd30 != null) exHtml += ' <span style="color:' + cR(fwd30) + '">30d: ' + fmtR(fwd30) + '</span>';
+        if (fwd365 != null) exHtml += ' <span style="color:' + cR(fwd365) + '">1yr: ' + fmtR(fwd365) + '</span>';
+        exHtml += '</div>';
+      });
+      exEl.innerHTML = exHtml;
+      exEl.style.display = 'block';
+    } else {
+      exEl.innerHTML = '';
+      exEl.style.display = 'none';
+    }
+
+    // Highlight matching periods on the chart
+    highlightMetricPeriods(metricKey, ctx.current_raw, ctx.margin);
+  } catch(e) {
+    console.error('Metric context load failed:', e);
+  }
+}
+
+function highlightMetricPeriods(metricKey, currentRaw, margin) {
+  if (!fullDailyScores || !currentRaw || margin == null) return;
+
+  // Build an array of {date, rawValue} for the selected metric
+  const metricSeries = fullDailyScores
+    .filter(d => d.metrics && d.metrics[metricKey] != null)
+    .map(d => ({ date: d.date, value: d.metrics[metricKey], isSimilar: Math.abs(d.metrics[metricKey] - currentRaw) <= margin }));
+
+  // Store for use in chart rendering
+  window._highlightMetric = { key: metricKey, series: metricSeries, currentRaw, margin };
+
+  // Re-render chart with highlight
+  applyChartRange(currentRange);
 }

 let histChart = null;
 let fullDailyScores = null;
 let currentRange = 0; // 0 = ALL
+let currentMode = 'classic';

 function renderHistory(history) {
  // Legacy: still called by loadData but we'll use backtest data instead
@@ -784,7 +960,61 @@ function renderHistoryFromData(history) {
    });
  }

-  // Accumulation zone backgrounds
+  // If a metric is selected, add its overlay + highlight similar periods
+  const highlight = window._highlightMetric;
+  let metricColor = '#a78bfa';
+  if (highlight && highlight.series && highlight.series.length) {
+    // Build a sparse array aligned to current chart labels
+    const metricByDate = {};
+    highlight.series.forEach(s => { metricByDate[s.date] = s; });
+    const metricData = labels.map(l => {
+      const entry = metricByDate[l];
+      return entry ? entry.value : null;
+    });
+    const hasMetricData = metricData.some(v => v != null);
+
+    if (hasMetricData) {
+      datasets.push({
+        label: 'Selected Metric',
+        data: metricData,
+        borderColor: metricColor,
+        borderWidth: 1.5,
+        borderDash: [2, 2],
+        fill: false,
+        tension: 0.2,
+        pointRadius: 0,
+        yAxisID: 'y2',
+      });
+    }
+
+    // Highlight similar periods with point dots on the score line
+    const similarIndices = [];
+    labels.forEach((l, i) => {
+      const entry = metricByDate[l];
+      if (entry && entry.isSimilar) similarIndices.push(i);
+    });
+
+    if (similarIndices.length) {
+      const highlightData = labels.map((l, i) =>
+        similarIndices.includes(i) ? scores[i] : null
+      );
+      datasets.push({
+        label: 'Similar Periods',
+        data: highlightData,
+        borderColor: 'rgba(167,139,250,0)',
+        backgroundColor: '#a78bfa',
+        pointRadius: 3,
+        pointHoverRadius: 5,
+        showLine: false,
+        yAxisID: 'y',
+      });
+    }
+  }
+
+  // Determine y2 scale for the metric overlay
+  const hasMetricDataset = datasets.some(d => d.yAxisID === 'y2');
+
+  // Accumulation zone backgrounds + metric highlight bands
  const zonePlugin = {
    id: 'zones',
    beforeDraw(chart) {
@@ -812,9 +1042,55 @@ function renderHistoryFromData(history) {
        ctx.stroke();
        ctx.setLineDash([]);
      });
+
+      // Draw vertical highlight bands for similar periods
+      if (highlight && highlight.series) {
+        const metricByDate = {};
+        highlight.series.forEach(s => { metricByDate[s.date] = s; });
+        const xScale = chart.scales.x;
+        labels.forEach((l, i) => {
+          const entry = metricByDate[l];
+          if (entry && entry.isSimilar) {
+            const x = xScale.getPixelForValue(i);
+            ctx.fillStyle = 'rgba(167,139,250,0.08)';
+            ctx.fillRect(x - 3, top, 6, bottom - top);
+          }
+        });
+      }
    }
  };

+  const scales = {
+    x: {
+      ticks: { color: '#64748b', maxTicksLimit: 12, font: { family: 'monospace', size: 10 } },
+      grid: { color: 'rgba(255,255,255,0.03)' }
+    },
+    y: {
+      min: 0, max: 100,
+      ticks: { color: '#22d3ee', font: { family: 'monospace', size: 10 } },
+      grid: { color: 'rgba(255,255,255,0.03)' },
+      title: { display: true, text: 'Score', color: '#22d3ee', font: { family: 'monospace', size: 11 } }
+    },
+    y1: {
+      position: 'right',
+      ticks: {
+        color: '#f7931a',
+        font: { family: 'monospace', size: 10 },
+        callback: v => '$' + (v >= 1000 ? (v/1000).toFixed(0) + 'k' : v)
+      },
+      grid: { drawOnChartArea: false },
+      title: { display: true, text: 'BTC Price', color: '#f7931a', font: { family: 'monospace', size: 11 } }
+    },
+  };
+
+  if (hasMetricDataset) {
+    scales['y2'] = {
+      position: 'right',
+      display: false,
+      grid: { drawOnChartArea: false },
+    };
+  }
+
  histChart = new Chart(ctx, {
    type: 'line',
    plugins: [zonePlugin],
@@ -834,6 +1110,8 @@ function renderHistoryFromData(history) {
          callbacks: {
            label: function(ctx) {
              if (ctx.dataset.yAxisID === 'y1') return 'BTC: $' + ctx.raw.toLocaleString();
+              if (ctx.dataset.yAxisID === 'y2') return 'Metric: ' + (ctx.raw != null ? ctx.raw.toFixed(4) : 'N/A');
+              if (ctx.dataset.label === 'Similar Periods') return '★ Similar period (Score: ' + ctx.raw.toFixed(1) + ')';
              const s = ctx.raw;
              let zone = s >= 80 ? 'Extreme Accum' : s >= 65 ? 'Strong Accum' : s >= 50 ? 'Moderate' : s >= 35 ? 'Neutral' : 'Caution';
              return 'Score: ' + s.toFixed(1) + ' (' + zone + ')';
@@ -841,28 +1119,7 @@ function renderHistoryFromData(history) {
          }
        }
      },
-      scales: {
-        x: {
-          ticks: { color: '#64748b', maxTicksLimit: 12, font: { family: 'monospace', size: 10 } },
-          grid: { color: 'rgba(255,255,255,0.03)' }
-        },
-        y: {
-          min: 0, max: 100,
-          ticks: { color: '#22d3ee', font: { family: 'monospace', size: 10 } },
-          grid: { color: 'rgba(255,255,255,0.03)' },
-          title: { display: true, text: 'Score', color: '#22d3ee', font: { family: 'monospace', size: 11 } }
-        },
-        y1: {
-          position: 'right',
-          ticks: {
-            color: '#f7931a',
-            font: { family: 'monospace', size: 10 },
-            callback: v => '$' + (v >= 1000 ? (v/1000).toFixed(0) + 'k' : v)
-          },
-          grid: { drawOnChartArea: false },
-          title: { display: true, text: 'BTC Price', color: '#f7931a', font: { family: 'monospace', size: 11 } }
-        }
-      }
+      scales,
    }
  });
 }
@@ -992,8 +1249,6 @@ async function doRefresh(full) {
  setTimeout(() => { btn.disabled = false; btn.textContent = origText; }, delay);
 }

-let currentMode = 'classic';
-
 function setMode(mode) {
  currentMode = mode;
  document.querySelectorAll('.mode-btn').forEach(b => {
@@ -1286,6 +1541,245 @@ def api_backtest_status():
    return status


+@app.get("/api/metric-context")
+def api_metric_context(metric: str, margin: float = 0.0, mode: str = "classic"):
+    """Find historical periods where a specific metric was at a similar level.
+
+    Returns forward returns for those periods, analogous to the composite-score
+    current_context but filtered to a single metric's historical similarity.
+
+    margin: absolute tolerance for "similar" (auto-computed from metric scale if 0).
+    """
+    try:
+        from backtesting.engine import run_backtest, HISTORY_PATH, _build_daily_index, _get_all_dates, _last_known_value, METRIC_SCORERS, RATIO_SCORERS, DRAWDOWN_RANGES, _score_range
+        import os as _os
+
+        if not _os.path.exists(HISTORY_PATH):
+            return JSONResponse({"error": "No historical data. Run history collector first."}, status_code=404)
+
+        with open(HISTORY_PATH) as f:
+            history = json.load(f)
+
+        index = _build_daily_index(history)
+        all_dates = _get_all_dates(index)
+
+        # Get current metric value from cache
+        cache = {}
+        if _os.path.exists(CACHE_PATH):
+            with open(CACHE_PATH) as f:
+                cache = json.load(f)
+
+        current_raw = _get_current_metric_raw(metric, cache)
+        if current_raw is None:
+            return JSONResponse({"error": f"No current value for metric '{metric}'"}, status_code=404)
+
+        # Auto-compute margin from metric scale
+        if margin <= 0:
+            margin = _auto_metric_margin(metric, current_raw)
+
+        # Build price lookup
+        price_lookup = {}
+        for pk in ["btc_price_coingecko", "btc_price", "btc_price_sma", "btc_price_lth"]:
+            if pk in index:
+                for d, v in index[pk].items():
+                    if d not in price_lookup:
+                        price_lookup[d] = v
+
+        # Find historical days where this metric was similar
+        comparable = []
+        for d in all_dates:
+            raw_val = _get_historical_metric_raw(metric, index, d)
+            if raw_val is not None and abs(raw_val - current_raw) <= margin:
+                price = price_lookup.get(d)
+                fwd = _compute_day_forward_returns(price_lookup, d)
+                if fwd:
+                    comparable.append({
+                        "date": d,
+                        "raw_value": round(raw_val, 6) if isinstance(raw_val, float) else raw_val,
+                        "price": price,
+                        "forward_returns": fwd,
+                    })
+
+        # Compute average returns across comparable periods
+        avg_returns = {}
+        for period in ["30d", "90d", "180d", "365d"]:
+            vals = [c["forward_returns"][period] for c in comparable if period in c["forward_returns"]]
+            if vals:
+                avg_returns[period] = round(sum(vals) / len(vals), 2)
+
+        # Pick best examples (one per market cycle)
+        cycle_bins = [
+            ("pre-2016", "2010-01-01", "2015-12-31"),
+            ("2016-17 Bull", "2016-01-01", "2017-12-31"),
+            ("2018-19 Bear", "2018-01-01", "2019-12-31"),
+            ("2020-21 Bull", "2020-01-01", "2021-12-31"),
+            ("2022-23 Bear", "2022-01-01", "2023-12-31"),
+            ("2024+", "2024-01-01", "2099-12-31"),
+        ]
+        examples = []
+        used_cycles = set()
+        sorted_comp = sorted(comparable, key=lambda c: abs(c["raw_value"] - current_raw))
+        for c in sorted_comp:
+            for label, start, end in cycle_bins:
+                if start <= c["date"] <= end and label not in used_cycles:
+                    used_cycles.add(label)
+                    examples.append({
+                        "date": c["date"],
+                        "raw_value": c["raw_value"],
+                        "price": c["price"],
+                        "forward_returns": c["forward_returns"],
+                        "cycle": label,
+                    })
+                    break
+            if len(examples) >= 6:
+                break
+        examples.sort(key=lambda e: e["date"])
+
+        # Percentile: what % of all days had this metric at or below current value
+        all_raw_vals = []
+        for d in all_dates:
+            rv = _get_historical_metric_raw(metric, index, d)
+            if rv is not None:
+                all_raw_vals.append(rv)
+        all_raw_vals.sort()
+        below = len([v for v in all_raw_vals if v <= current_raw])
+        percentile = round(below / len(all_raw_vals) * 100, 1) if all_raw_vals else 50.0
+
+        return {
+            "metric": metric,
+            "current_raw": current_raw,
+            "margin": margin,
+            "comparable_days": len(comparable),
+            "percentile": percentile,
+            "avg_30d_return": avg_returns.get("30d"),
+            "avg_90d_return": avg_returns.get("90d"),
+            "avg_180d_return": avg_returns.get("180d"),
+            "avg_1yr_return": avg_returns.get("365d"),
+            "examples": examples,
+        }
+    except Exception as e:
+        log.error("Metric context error: %s", traceback.format_exc())
+        return JSONResponse({"error": str(e)}, status_code=500)
+
+
+def _get_current_metric_raw(metric, cache):
+    """Get the current raw value for a metric from the cache."""
+    # Direct cache keys
+    direct_keys = {
+        "fear_greed": ("fear_greed", "value"),
+        "puell_multiple": ("puell_multiple", "value"),
+        "mvrv_zscore": ("mvrv_zscore", "value"),
+        "reserve_risk": ("reserve_risk", "value"),
+        "rhodl_ratio": ("rhodl_ratio", "value"),
+        "nupl": ("nupl", "value"),
+        "drawdown": ("drawdown", "value"),
+        "hash_ribbons": ("hash_ribbons", "value"),
+        "sopr": ("sopr", "value"),
+        "sellside_risk": ("sellside_risk", "value"),
+        "active_address_momentum": ("active_address_momentum", "value"),
+        "txcount_momentum": ("txcount_momentum", "value"),
+        "nvt_price": ("nvt_price", "value"),
+        "vdd_multiple": ("vdd_multiple", "value"),
+        "lth_supply": ("lth_supply", "value"),
+    }
+    # Ratio-based metrics: compute from price vs reference
+    ratio_metrics = {
+        "price_vs_200w_sma": ("price", "200w_sma"),
+        "lth_realized_price": ("price", "lth_realized_price"),
+    }
+
+    if metric in direct_keys:
+        k, sub = direct_keys[metric]
+        val = cache.get(k, {})
+        if isinstance(val, dict):
+            return val.get(sub)
+        return val
+    elif metric in ratio_metrics:
+        price_key, ref_key = ratio_metrics[metric]
+        price_val = cache.get(price_key, {}).get("price") or cache.get(price_key, {}).get("value")
+        ref_val = cache.get(ref_key, {}).get("value")
+        if price_val and ref_val and ref_val > 0:
+            return ((price_val - ref_val) / ref_val) * 100
+    return None
+
+
+def _get_historical_metric_raw(metric, index, date):
+    """Get the raw value for a metric on a specific historical date."""
+    from backtesting.engine import _last_known_value
+    direct_keys = {
+        "fear_greed": "fear_greed",
+        "puell_multiple": "puell_multiple",
+        "mvrv_zscore": "mvrv_zscore",
+        "reserve_risk": "reserve_risk",
+        "rhodl_ratio": "rhodl_ratio",
+        "nupl": "nupl",
+        "drawdown": "drawdown",
+        "hash_ribbons": "hash_ribbons",
+        "sopr": "sopr",
+        "sellside_risk": "sellside_risk",
+        "active_address_momentum": "active_address_momentum",
+        "txcount_momentum": "txcount_momentum",
+        "nvt_price": "nvt_price",
+        "vdd_multiple": "vdd_multiple",
+        "lth_supply": "lth_supply",
+    }
+    if metric in direct_keys:
+        return _last_known_value(index.get(direct_keys[metric], {}), date)
+    # Ratio-based
+    if metric == "price_vs_200w_sma":
+        price_val = _last_known_value(index.get("btc_price", {}), date)
+        ref_val = _last_known_value(index.get("200w_sma", {}), date)
+        if price_val and ref_val and ref_val > 0:
+            return ((price_val - ref_val) / ref_val) * 100
+    if metric == "lth_realized_price":
+        price_val = _last_known_value(index.get("btc_price", {}), date)
+        ref_val = _last_known_value(index.get("lth_realized_price", {}), date)
+        if price_val and ref_val and ref_val > 0:
+            return ((price_val - ref_val) / ref_val) * 100
+    return None
+
+
+def _auto_metric_margin(metric, current_val):
+    """Compute a reasonable similarity margin based on metric type and scale."""
+    margins = {
+        "fear_greed": 5.0,
+        "puell_multiple": 0.15,
+        "mvrv_zscore": 0.5,
+        "reserve_risk": 0.002,
+        "rhodl_ratio": 300,
+        "nupl": 0.1,
+        "drawdown": 8.0,
+        "sopr": 0.02,
+        "sellside_risk": 0.001,
+        "active_address_momentum": 0.05,
+        "txcount_momentum": 0.05,
+        "nvt_price": 5000,
+        "vdd_multiple": 0.15,
+        "price_vs_200w_sma": 10.0,
+        "lth_realized_price": 10.0,
+    }
+    if metric in margins:
+        return margins[metric]
+    # Fallback: 15% of current value
+    return abs(current_val) * 0.15 if current_val != 0 else 1.0
+
+
+def _compute_day_forward_returns(price_lookup, date):
+    """Compute forward returns for a single date."""
+    from datetime import datetime as _dt, timedelta as _td
+    p0 = price_lookup.get(date)
+    if p0 is None or p0 <= 0:
+        return {}
+    r = {}
+    dt = _dt.strptime(date, "%Y-%m-%d")
+    for days in [30, 90, 180, 365]:
+        future = (dt + _td(days=days)).strftime("%Y-%m-%d")
+        pf = price_lookup.get(future)
+        if pf is not None:
+            r[f"{days}d"] = round(((pf - p0) / p0) * 100, 2)
+    return r
+
+
 # ── Backtest HTML Page ─────────────────────────────────────────────────

 BACKTEST_HTML = """<!DOCTYPE html>