agentbnb 5.1.0 → 5.1.2

package/skills/deep-stock-analyst/src/analysis/signal.ts

@@ -0,0 +1,188 @@
+import type { AVDailyPrice } from '../api/types.js';
+import type { ValuationScore } from './valuation.js';
+import type { TechnicalScore } from './technicals.js';
+import type { FinancialHealth } from './financial-health.js';
+import type { SentimentScore } from './sentiment.js';
+import { sp } from './utils.js';
+
+export type InvestmentStyle = 'growth' | 'value' | 'momentum' | 'hybrid';
+export type SignalVerdict = 'strong_buy' | 'buy' | 'hold' | 'sell' | 'strong_sell';
+
+interface StyleWeights {
+  valuation: number;
+  technicals: number;
+  financials: number;
+  sentiment: number;
+}
+
+function getStyleWeights(style: InvestmentStyle): StyleWeights {
+  const presets: Record<InvestmentStyle, StyleWeights> = {
+    growth: { valuation: 0.15, technicals: 0.25, financials: 0.40, sentiment: 0.20 },
+    value: { valuation: 0.40, technicals: 0.15, financials: 0.30, sentiment: 0.15 },
+    momentum: { valuation: 0.10, technicals: 0.45, financials: 0.15, sentiment: 0.30 },
+    hybrid: { valuation: 0.25, technicals: 0.30, financials: 0.25, sentiment: 0.20 },
+  };
+  return presets[style];
+}
+
+/** Find local support levels from price data */
+function findSupportLevels(daily: AVDailyPrice[], count: number): number[] {
+  const prices = daily.slice(0, 90).map((d) => sp(d.low));
+  const levels: number[] = [];
+
+  for (let i = 2; i < prices.length - 2; i++) {
+    const p = prices[i] ?? 0;
+    if (
+      p <= (prices[i - 1] ?? 0) &&
+      p <= (prices[i - 2] ?? 0) &&
+      p <= (prices[i + 1] ?? 0) &&
+      p <= (prices[i + 2] ?? 0)
+    ) {
+      levels.push(parseFloat(p.toFixed(2)));
+    }
+  }
+
+  // Cluster nearby levels (within 1%)
+  const clustered: number[] = [];
+  for (const lvl of levels.sort((a, b) => b - a)) {
+    const isDuplicate = clustered.some((c) => Math.abs(c - lvl) / lvl < 0.01);
+    if (!isDuplicate) clustered.push(lvl);
+    if (clustered.length >= count) break;
+  }
+  return clustered;
+}
+
+/** Find local resistance levels from price data */
+function findResistanceLevels(daily: AVDailyPrice[], count: number): number[] {
+  const prices = daily.slice(0, 90).map((d) => sp(d.high));
+  const levels: number[] = [];
+
+  for (let i = 2; i < prices.length - 2; i++) {
+    const p = prices[i] ?? 0;
+    if (
+      p >= (prices[i - 1] ?? 0) &&
+      p >= (prices[i - 2] ?? 0) &&
+      p >= (prices[i + 1] ?? 0) &&
+      p >= (prices[i + 2] ?? 0)
+    ) {
+      levels.push(parseFloat(p.toFixed(2)));
+    }
+  }
+
+  const clustered: number[] = [];
+  for (const lvl of levels.sort((a, b) => b - a)) {
+    const isDuplicate = clustered.some((c) => Math.abs(c - lvl) / lvl < 0.01);
+    if (!isDuplicate) clustered.push(lvl);
+    if (clustered.length >= count) break;
+  }
+  return clustered;
+}
+
+/** How much do the four sub-scores agree? 0–1 */
+function calculateAgreement(
+  valuation: ValuationScore,
+  technicals: TechnicalScore,
+  financials: FinancialHealth,
+  sentiment: SentimentScore,
+): number {
+  const scores = [
+    valuation.composite,
+    technicals.composite,
+    financials.composite,
+    sentiment.composite,
+  ];
+  const mean = scores.reduce((a, b) => a + b, 0) / scores.length;
+  const variance = scores.reduce((acc, s) => acc + (s - mean) ** 2, 0) / scores.length;
+  const stdDev = Math.sqrt(variance);
+  // Low stdDev = high agreement → high confidence
+  return Math.max(0, 1 - stdDev / 30);
+}
+
+/** Data completeness: 0–1 based on whether modules have real data */
+function calculateCompleteness(
+  valuation: ValuationScore,
+  technicals: TechnicalScore,
+  financials: FinancialHealth,
+  sentiment: SentimentScore,
+): number {
+  let score = 0;
+  if (valuation.raw.pe > 0) score += 0.25;
+  if (technicals.raw.price > 0) score += 0.25;
+  if (financials.raw.revenueGrowthPct !== 0) score += 0.25;
+  if (sentiment.news_volume > 3) score += 0.25;
+  return score;
+}
+
+export interface CompositeSignal {
+  signal: SignalVerdict;
+  confidence: number; // 0–1
+  composite_score: number; // 0–100
+  support_levels: number[];
+  resistance_levels: number[];
+  key_factors: string[];
+  risk_factors: string[];
+  data_completeness: number; // 0–1
+}
+
+export function generateCompositeSignal(
+  valuation: ValuationScore,
+  technicals: TechnicalScore,
+  financials: FinancialHealth,
+  sentiment: SentimentScore,
+  daily: AVDailyPrice[],
+  style: InvestmentStyle,
+): CompositeSignal {
+  const w = getStyleWeights(style);
+
+  const composite_score =
+    valuation.composite * w.valuation +
+    technicals.composite * w.technicals +
+    financials.composite * w.financials +
+    sentiment.composite * w.sentiment;
+
+  const signal: SignalVerdict =
+    composite_score > 80 ? 'strong_buy'
+      : composite_score > 62 ? 'buy'
+        : composite_score > 42 ? 'hold'
+          : composite_score > 25 ? 'sell'
+            : 'strong_sell';
+
+  const agreementScore = calculateAgreement(valuation, technicals, financials, sentiment);
+  const data_completeness = calculateCompleteness(valuation, technicals, financials, sentiment);
+  const confidence = parseFloat((agreementScore * 0.6 + data_completeness * 0.4).toFixed(2));
+
+  const support_levels = findSupportLevels(daily, 3);
+  const resistance_levels = findResistanceLevels(daily, 3);
+
+  // Key positive factors
+  const key_factors: string[] = [];
+  if (valuation.verdict === 'undervalued') key_factors.push(`Undervalued: composite valuation ${valuation.composite.toFixed(0)}/100`);
+  if (financials.growth_score > 70) key_factors.push(`Strong growth: revenue +${financials.raw.revenueGrowthPct.toFixed(1)}% YoY`);
+  if (technicals.signals.some((s) => s.type === 'bullish' && s.strength >= 4)) {
+    const sig = technicals.signals.find((s) => s.type === 'bullish' && s.strength >= 4);
+    if (sig) key_factors.push(`Technical: ${sig.name}`);
+  }
+  if (sentiment.bullish_ratio > 0.7) key_factors.push(`Bullish sentiment: ${(sentiment.bullish_ratio * 100).toFixed(0)}% positive coverage`);
+  for (const flag of financials.green_flags.slice(0, 2)) key_factors.push(flag);
+
+  // Key risk factors
+  const risk_factors: string[] = [];
+  if (valuation.verdict === 'expensive') risk_factors.push(`Expensive valuation: composite ${valuation.composite.toFixed(0)}/100`);
+  if (technicals.signals.some((s) => s.type === 'bearish' && s.strength >= 4)) {
+    const sig = technicals.signals.find((s) => s.type === 'bearish' && s.strength >= 4);
+    if (sig) risk_factors.push(`Technical: ${sig.name}`);
+  }
+  for (const flag of financials.red_flags.slice(0, 2)) risk_factors.push(flag);
+  if (sentiment.bullish_ratio < 0.3) risk_factors.push(`Negative sentiment: only ${(sentiment.bullish_ratio * 100).toFixed(0)}% positive coverage`);
+
+  return {
+    signal,
+    confidence,
+    composite_score: parseFloat(composite_score.toFixed(1)),
+    support_levels,
+    resistance_levels,
+    key_factors: key_factors.slice(0, 3),
+    risk_factors: risk_factors.slice(0, 3),
+    data_completeness,
+  };
+}

package/skills/deep-stock-analyst/src/analysis/technicals.ts

@@ -0,0 +1,318 @@
+import type {
+  AVDailyPrice,
+  AVRSIEntry,
+  AVMACDEntry,
+  AVBBandsEntry,
+  AVStochEntry,
+  AVADXEntry,
+} from '../api/types.js';
+import { calcSMA, calcAvgVolume, formatNumber, mapRange, weightedAvg, sp } from './utils.js';
+
+export interface TechnicalSignal {
+  type: 'bullish' | 'bearish' | 'neutral';
+  name: string;
+  strength: number; // 1–5
+  description: string;
+  detected_at: string;
+}
+
+export interface TechnicalScore {
+  trend_score: number;
+  momentum_score: number;
+  volatility_score: number;
+  strength_score: number;
+  composite: number;
+  regime: 'strong_uptrend' | 'uptrend' | 'consolidation' | 'downtrend' | 'strong_downtrend';
+  signals: TechnicalSignal[];
+  raw: {
+    rsi: number;
+    macdHist: number;
+    adx: number;
+    bbPosition: number;
+    bandWidth: number;
+    price: number;
+    sma20: number;
+    sma50: number;
+    sma200: number;
+  };
+}
+
+function calcSMAAlignment(
+  price: number,
+  sma20: number,
+  sma50: number,
+  sma100: number,
+  sma200: number,
+): number {
+  let score = 0;
+  // Perfect bull: price > SMA20 > SMA50 > SMA100 > SMA200 = 100
+  if (price > sma20) score += 25;
+  if (sma20 > sma50) score += 25;
+  if (sma50 > sma100) score += 25;
+  if (sma100 > sma200) score += 25;
+  return score;
+}
+
+function detectRSIDivergence(
+  daily: AVDailyPrice[],
+  rsi: AVRSIEntry[],
+  lookback: number,
+): TechnicalSignal | null {
+  if (daily.length < lookback || rsi.length < lookback) return null;
+
+  // Check last `lookback` bars for price making new high but RSI declining (bearish divergence)
+  // or price making new low but RSI rising (bullish divergence)
+  const prices = daily.slice(0, lookback).map((d) => sp(d.close));
+  const rsiVals = rsi.slice(0, lookback).map((r) => sp(r.RSI));
+
+  const priceMin = Math.min(...prices);
+  const priceMax = Math.max(...prices);
+  const rsiMin = Math.min(...rsiVals);
+  const rsiMax = Math.max(...rsiVals);
+
+  const latestPrice = prices[0] ?? 0;
+  const latestRSI = rsiVals[0] ?? 50;
+
+  // Bullish divergence: price near low but RSI well above its low
+  if (
+    latestPrice <= priceMin * 1.02 &&
+    latestRSI >= rsiMin * 1.15 &&
+    latestRSI < 50
+  ) {
+    return {
+      type: 'bullish',
+      name: 'RSI Bullish Divergence',
+      strength: 4,
+      description: `Price near ${lookback}-day low but RSI (${latestRSI.toFixed(1)}) is diverging upward`,
+      detected_at: daily[0]?.date ?? '',
+    };
+  }
+
+  // Bearish divergence: price near high but RSI well below its high
+  if (
+    latestPrice >= priceMax * 0.98 &&
+    latestRSI <= rsiMax * 0.85 &&
+    latestRSI > 50
+  ) {
+    return {
+      type: 'bearish',
+      name: 'RSI Bearish Divergence',
+      strength: 4,
+      description: `Price near ${lookback}-day high but RSI (${latestRSI.toFixed(1)}) is diverging downward`,
+      detected_at: daily[0]?.date ?? '',
+    };
+  }
+
+  return null;
+}
+
+function crossedAbove(
+  daily: AVDailyPrice[],
+  fastPeriod: number,
+  slowPeriod: number,
+  withinDays: number,
+): boolean {
+  for (let i = 0; i < withinDays; i++) {
+    const slice = daily.slice(i);
+    const fastNow = calcSMA(slice, fastPeriod);
+    const slowNow = calcSMA(slice, slowPeriod);
+    const fastPrev = calcSMA(daily.slice(i + 1), fastPeriod);
+    const slowPrev = calcSMA(daily.slice(i + 1), slowPeriod);
+    if (fastNow > slowNow && fastPrev <= slowPrev) return true;
+  }
+  return false;
+}
+
+function crossedBelow(
+  daily: AVDailyPrice[],
+  fastPeriod: number,
+  slowPeriod: number,
+  withinDays: number,
+): boolean {
+  for (let i = 0; i < withinDays; i++) {
+    const slice = daily.slice(i);
+    const fastNow = calcSMA(slice, fastPeriod);
+    const slowNow = calcSMA(slice, slowPeriod);
+    const fastPrev = calcSMA(daily.slice(i + 1), fastPeriod);
+    const slowPrev = calcSMA(daily.slice(i + 1), slowPeriod);
+    if (fastNow < slowNow && fastPrev >= slowPrev) return true;
+  }
+  return false;
+}
+
+function determineRegime(
+  composite: number,
+  trendScore: number,
+  strengthScore: number,
+): TechnicalScore['regime'] {
+  if (composite > 80 && strengthScore > 70) return 'strong_uptrend';
+  if (composite > 60) return 'uptrend';
+  if (composite > 40) return 'consolidation';
+  if (composite > 20 && strengthScore > 70) return 'strong_downtrend';
+  return 'downtrend';
+}
+
+export function analyzeTechnicals(
+  daily: AVDailyPrice[],
+  rsi: AVRSIEntry[],
+  macd: AVMACDEntry[],
+  bbands: AVBBandsEntry[],
+  stoch: AVStochEntry[],
+  adx: AVADXEntry[],
+): TechnicalScore {
+  if (daily.length === 0) {
+    return {
+      trend_score: 50, momentum_score: 50, volatility_score: 50, strength_score: 50,
+      composite: 50, regime: 'consolidation', signals: [],
+      raw: { rsi: 50, macdHist: 0, adx: 20, bbPosition: 0.5, bandWidth: 0.05, price: 0, sma20: 0, sma50: 0, sma200: 0 },
+    };
+  }
+
+  const price = sp(daily[0]?.close);
+
+  // === Trend Score: SMA alignment ===
+  const sma20 = calcSMA(daily, 20);
+  const sma50 = calcSMA(daily, 50);
+  const sma100 = calcSMA(daily, 100);
+  const sma200 = calcSMA(daily, 200);
+  const trend_score = calcSMAAlignment(price, sma20, sma50, sma100, sma200);
+
+  // === Momentum Score: RSI + MACD ===
+  const latestRSI = sp(rsi[0]?.RSI ?? '50');
+  const macdHist = sp(macd[0]?.MACD_Hist ?? '0');
+
+  // RSI: oversold (<30) = bullish setup; overbought (>70) = bearish
+  const rsi_component =
+    latestRSI < 30 ? 80
+      : latestRSI > 70 ? 30
+        : mapRange(latestRSI, 30, 70, 40, 70);
+
+  // MACD histogram positive and growing = bullish momentum
+  const macd_component =
+    macdHist > 0
+      ? mapRange(macdHist, 0, 2, 50, 90)
+      : mapRange(macdHist, -2, 0, 10, 50);
+
+  const momentum_score = rsi_component * 0.5 + macd_component * 0.5;
+
+  // === Volatility Score: Bollinger position ===
+  const upperBand = sp(bbands[0]?.['Real Upper Band'] ?? '0');
+  const lowerBand = sp(bbands[0]?.['Real Lower Band'] ?? '0');
+  const middleBand = sp(bbands[0]?.['Real Middle Band'] ?? '0');
+  const bandRange = upperBand - lowerBand;
+  const bandWidth = middleBand > 0 ? bandRange / middleBand : 0;
+  const bbPosition = bandRange > 0 ? (price - lowerBand) / bandRange : 0.5;
+  const volatility_score = bbPosition * 100;
+
+  // === Strength Score: ADX ===
+  const latestADX = sp(adx[0]?.ADX ?? '20');
+  const strength_score = mapRange(latestADX, 10, 50, 0, 100);
+
+  // === Signal Detection ===
+  const signals: TechnicalSignal[] = [];
+  const today = daily[0]?.date ?? '';
+
+  // Golden Cross / Death Cross (SMA50 vs SMA200)
+  if (crossedAbove(daily, 50, 200, 5)) {
+    signals.push({
+      type: 'bullish', name: 'Golden Cross', strength: 5,
+      description: 'SMA50 crossed above SMA200 within last 5 trading days',
+      detected_at: today,
+    });
+  }
+  if (crossedBelow(daily, 50, 200, 5)) {
+    signals.push({
+      type: 'bearish', name: 'Death Cross', strength: 5,
+      description: 'SMA50 crossed below SMA200 within last 5 trading days',
+      detected_at: today,
+    });
+  }
+
+  // RSI Divergence
+  const rsiDiv = detectRSIDivergence(daily, rsi, 20);
+  if (rsiDiv) signals.push(rsiDiv);
+
+  // MACD Bullish Crossover (hist went positive)
+  const prevMacdHist = sp(macd[1]?.MACD_Hist ?? '0');
+  if (macdHist > 0 && prevMacdHist < 0) {
+    signals.push({
+      type: 'bullish', name: 'MACD Bullish Crossover', strength: 3,
+      description: 'MACD crossed above signal line',
+      detected_at: today,
+    });
+  }
+  if (macdHist < 0 && prevMacdHist > 0) {
+    signals.push({
+      type: 'bearish', name: 'MACD Bearish Crossover', strength: 3,
+      description: 'MACD crossed below signal line',
+      detected_at: today,
+    });
+  }
+
+  // Bollinger Squeeze (very narrow band → major move incoming)
+  if (bandWidth < 0.05) {
+    signals.push({
+      type: 'neutral', name: 'Bollinger Squeeze', strength: 4,
+      description: `Band width at ${(bandWidth * 100).toFixed(1)}% — extremely compressed. Major move incoming.`,
+      detected_at: today,
+    });
+  }
+
+  // Stochastic oversold reversal
+  const stochK = sp(stoch[0]?.SlowK ?? '50');
+  const stochD = sp(stoch[0]?.SlowD ?? '50');
+  const prevStochK = sp(stoch[1]?.SlowK ?? '50');
+  if (stochK < 20 && stochK > stochD && prevStochK <= stochD) {
+    signals.push({
+      type: 'bullish', name: 'Stochastic Oversold Reversal', strength: 3,
+      description: `Stoch K(${stochK.toFixed(1)}) crossing above D(${stochD.toFixed(1)}) in oversold territory`,
+      detected_at: today,
+    });
+  }
+
+  // Volume Spike (2x 20-day average)
+  const avgVol20 = calcAvgVolume(daily, 20);
+  const todayVol = sp(daily[0]?.volume ?? '0');
+  if (avgVol20 > 0 && todayVol > avgVol20 * 2) {
+    signals.push({
+      type: 'neutral', name: 'Volume Spike', strength: 4,
+      description: `Volume ${formatNumber(todayVol)} is ${(todayVol / avgVol20).toFixed(1)}x the 20-day average`,
+      detected_at: today,
+    });
+  }
+
+  // Price above/below 200 SMA
+  if (sma200 > 0) {
+    if (price > sma200 * 1.10) {
+      signals.push({
+        type: 'bullish', name: 'Strong Uptrend', strength: 2,
+        description: `Price is ${(((price / sma200) - 1) * 100).toFixed(1)}% above 200-day SMA`,
+        detected_at: today,
+      });
+    } else if (price < sma200 * 0.90) {
+      signals.push({
+        type: 'bearish', name: 'Strong Downtrend', strength: 2,
+        description: `Price is ${(((sma200 / price) - 1) * 100).toFixed(1)}% below 200-day SMA`,
+        detected_at: today,
+      });
+    }
+  }
+
+  const composite = weightedAvg([
+    [trend_score, 0.30],
+    [momentum_score, 0.30],
+    [volatility_score, 0.15],
+    [strength_score, 0.25],
+  ]);
+
+  return {
+    trend_score,
+    momentum_score,
+    volatility_score,
+    strength_score,
+    composite,
+    regime: determineRegime(composite, trend_score, strength_score),
+    signals,
+    raw: { rsi: latestRSI, macdHist, adx: latestADX, bbPosition, bandWidth, price, sma20, sma50, sma200 },
+  };
+}

package/skills/deep-stock-analyst/src/analysis/utils.ts

@@ -0,0 +1,137 @@
+/** Shared math utilities — all pure functions, no LLM. */
+
+export interface ScoreThresholds {
+  excellent: number;
+  good: number;
+  fair: number;
+  poor: number;
+}
+
+/**
+ * Score a metric where lower is better (e.g. P/E ratio, debt/equity).
+ * Returns 0–100, where 100 = excellent (very cheap / low risk).
+ */
+export function scoreMetric(value: number, t: ScoreThresholds): number {
+  if (isNaN(value) || !isFinite(value)) return 50;
+  if (value <= t.excellent) return 100;
+  if (value <= t.good) return mapRange(value, t.excellent, t.good, 100, 75);
+  if (value <= t.fair) return mapRange(value, t.good, t.fair, 75, 50);
+  if (value <= t.poor) return mapRange(value, t.fair, t.poor, 50, 25);
+  return Math.max(0, 25 - ((value - t.poor) / t.poor) * 25);
+}
+
+/**
+ * Score a metric where higher is better (e.g. gross margin, ROE, FCF yield).
+ * Returns 0–100, where 100 = excellent (high margin / high return).
+ */
+export function scoreMetricInverse(value: number, t: ScoreThresholds): number {
+  if (isNaN(value) || !isFinite(value)) return 50;
+  if (value >= t.excellent) return 100;
+  if (value >= t.good) return mapRange(value, t.good, t.excellent, 75, 100);
+  if (value >= t.fair) return mapRange(value, t.fair, t.good, 50, 75);
+  if (value >= t.poor) return mapRange(value, t.poor, t.fair, 25, 50);
+  return Math.max(0, ((value - t.poor) / t.poor) * 25);
+}
+
+/** Weighted average: [[value, weight], ...] → number */
+export function weightedAvg(pairs: [number, number][]): number {
+  let totalWeight = 0;
+  let totalValue = 0;
+  for (const [val, w] of pairs) {
+    if (!isNaN(val) && isFinite(val)) {
+      totalValue += val * w;
+      totalWeight += w;
+    }
+  }
+  return totalWeight > 0 ? totalValue / totalWeight : 50;
+}
+
+/** Linear interpolation: map x from [inMin,inMax] to [outMin,outMax] */
+export function mapRange(
+  x: number,
+  inMin: number,
+  inMax: number,
+  outMin: number,
+  outMax: number,
+): number {
+  if (inMax === inMin) return (outMin + outMax) / 2;
+  const clamped = Math.max(inMin, Math.min(inMax, x));
+  return outMin + ((clamped - inMin) / (inMax - inMin)) * (outMax - outMin);
+}
+
+/** Simple Moving Average over the last `period` closing prices */
+export function calcSMA(prices: { close: string }[], period: number): number {
+  const slice = prices.slice(0, period);
+  if (slice.length === 0) return 0;
+  const sum = slice.reduce((acc, p) => acc + parseFloat(p.close), 0);
+  return sum / slice.length;
+}
+
+/** Average volume over `period` days */
+export function calcAvgVolume(prices: { volume: string }[], period: number): number {
+  const slice = prices.slice(0, period);
+  if (slice.length === 0) return 0;
+  const sum = slice.reduce((acc, p) => acc + parseFloat(p.volume), 0);
+  return sum / slice.length;
+}
+
+/** Format large numbers: 1234567 → "1.23M" */
+export function formatNumber(n: number): string {
+  if (n >= 1e9) return `${(n / 1e9).toFixed(2)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(2)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}K`;
+  return n.toFixed(0);
+}
+
+/** Safe parse: returns NaN-safe float */
+export function sp(v: unknown): number {
+  const n = parseFloat(String(v ?? 'NaN'));
+  return isFinite(n) ? n : 0;
+}
+
+/** YoY growth rate from quarterly reports (Q0 vs Q4) */
+export function calcYoYGrowth(
+  reports: Array<Record<string, string>>,
+  field: string,
+): number {
+  const current = sp(reports[0]?.[field]);
+  const prior = sp(reports[4]?.[field]);
+  if (prior === 0) return 0;
+  return ((current - prior) / Math.abs(prior)) * 100;
+}
+
+/** Score growth rate: 0–100 */
+export function scoreGrowth(pct: number): number {
+  if (pct >= 30) return 100;
+  if (pct >= 15) return mapRange(pct, 15, 30, 70, 100);
+  if (pct >= 5) return mapRange(pct, 5, 15, 50, 70);
+  if (pct >= 0) return mapRange(pct, 0, 5, 40, 50);
+  if (pct >= -10) return mapRange(pct, -10, 0, 20, 40);
+  return Math.max(0, 20 + pct * 2);
+}
+
+/** Score earnings surprise percentage: 0–100 */
+export function scoreSurprise(pct: number): number {
+  if (pct >= 10) return 100;
+  if (pct >= 5) return 80;
+  if (pct >= 0) return 60;
+  if (pct >= -5) return 40;
+  return 20;
+}
+
+/** Count consecutive earnings beats from quarterly earnings array */
+export function countConsecutiveBeats(
+  earnings: Array<{ surprisePercentage: string }>,
+): number {
+  let count = 0;
+  for (const e of earnings) {
+    if (sp(e.surprisePercentage) > 0) count++;
+    else break;
+  }
+  return count;
+}
+
+/** Clamp to [0, 100] */
+export function clamp100(n: number): number {
+  return Math.max(0, Math.min(100, n));
+}