LLM Spend TripwireChecklistCodeHosted waitlist

src/detect.js

Commit 01f96e7. All files · Download the tarball.

// Pure detection logic. No I/O: takes the previous state plus fetched usage rows, returns the new state and alerts.
import { priceFor, estimateUsd } from "./prices.js";

export const STATE_VERSION = 1;
const BUCKET = 10; // baseline history is kept as 10-minute sums per key
const COOLDOWN_KEEP_MINUTES = 7 * 1440;

export function newState() {
  return { v: STATE_VERSION, initialized: false, historyStart: 0, storedThrough: 0, buckets: {}, seenKeys: {}, seenModels: {}, cooldowns: {} };
}

export const totalTokens = (t) => (t.uncached_input || 0) + (t.cache_write_5m || 0) + (t.cache_write_1h || 0) + (t.cache_read || 0) + (t.output || 0);

function addBucket(s, key, start, n) {
  if (!n) return;
  const k = s.buckets[key] || (s.buckets[key] = {});
  k[start] = (k[start] || 0) + n;
}

// Average tokens per minute for one key over [start, end), counting idle minutes as zero.
// Edges are aligned to whole stored buckets (hourly from the first-run backfill, 10-minute after that) so a
// partly covered bucket is never counted as if its tokens were spread over fewer minutes.
export function baselineAvg(s, key, start, end) {
  end = Math.floor(end / BUCKET) * BUCKET;
  const from = Math.max(Math.floor(start / 60) * 60, s.historyStart || 0);
  const minutes = end - from;
  if (minutes <= 0) return { avg: 0, minutes: 0 };
  let sum = 0;
  const b = s.buckets[key] || {};
  for (const [m, n] of Object.entries(b)) { const mm = Number(m); if (mm >= from && mm < end) sum += n; }
  return { avg: sum / minutes, minutes };
}

const fmtCache = new Map();
function partsFormatter(tz) {
  let f = fmtCache.get(tz);
  if (!f) {
    f = new Intl.DateTimeFormat("en-US", { timeZone: tz, weekday: "short", hour: "2-digit", minute: "2-digit", hourCycle: "h23" });
    fmtCache.set(tz, f);
  }
  return f;
}
const WEEKDAY = { Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6, Sun: 7 };

export function localParts(minute, tz) {
  const p = {};
  for (const x of partsFormatter(tz).formatToParts(new Date(minute * 60000))) p[x.type] = x.value;
  return { day: WEEKDAY[p.weekday], minuteOfDay: (Number(p.hour) % 24) * 60 + Number(p.minute), hhmm: `${p.hour}:${p.minute}`, weekday: p.weekday };
}

// Working time = a configured weekday AND inside WORK_HOURS (a window that crosses midnight is allowed).
export function isWorkTime(minute, cfg) {
  if (!cfg.workHours) return true;
  const { day, minuteOfDay } = localParts(minute, cfg.timezone);
  if (!cfg.workDays.has(day)) return false;
  const { start, end } = cfg.workHours;
  return start < end ? minuteOfDay >= start && minuteOfDay < end : minuteOfDay >= start || minuteOfDay < end;
}

/**
 * One check.
 * input: { recentRows, recentStart, backfillRows, backfillStart, backfillEnd, keyList, prices }
 *   recentRows: 1-minute rows from recentStart to now; backfillRows: 1-hour rows (first run only).
 * Returns { state, alerts, initialized } where initialized is true when this call seeded a fresh state.
 */
export function step(prev, input, cfg, nowMin) {
  const { recentRows = [], recentStart = nowMin - cfg.lookbackMinutes, backfillRows = [], backfillStart, backfillEnd, keyList = null, prices } = input;
  const initializing = !(prev && prev.initialized);
  // A not-yet-initialized saved state can still hold error cooldowns; keep them.
  const s = initializing ? { ...newState(), cooldowns: { ...((prev && prev.cooldowns) || {}) } } : structuredClone(prev);
  const settledThrough = nowMin - cfg.settleMinutes;

  if (initializing) {
    s.historyStart = backfillStart ?? nowMin - cfg.baselineMinutes;
    s.storedThrough = (backfillEnd ?? recentStart) - 1;
    for (const r of backfillRows) addBucket(s, r.key, r.minute, totalTokens(r.t));
  }

  // Move settled minutes into the baseline history, once each.
  const from = Math.max(s.storedThrough, recentStart - 1);
  for (const r of recentRows) {
    if (r.minute > from && r.minute <= settledThrough) addBucket(s, r.key, r.minute - (((r.minute % BUCKET) + BUCKET) % BUCKET), totalTokens(r.t));
  }
  s.storedThrough = Math.max(s.storedThrough, settledThrough);

  // Everything seen in this fetch (any minute), and the recent window per key.
  const windowStart = nowMin - cfg.lookbackMinutes; // window = (windowStart, nowMin]
  const usedKeys = new Map(); // key -> Set(models)
  const usedModels = new Map(); // model -> Set(keys)
  const win = new Map(); // key -> Map(minute -> { tokens, usd, unknownPrice })
  for (const r of [...backfillRows, ...recentRows]) {
    if (!usedKeys.has(r.key)) usedKeys.set(r.key, new Set());
    usedKeys.get(r.key).add(r.model);
    if (!usedModels.has(r.model)) usedModels.set(r.model, new Set());
    usedModels.get(r.model).add(r.key);
  }
  for (const r of recentRows) {
    if (r.minute <= windowStart || r.minute > nowMin) continue;
    const { price, known } = priceFor(r.model, prices);
    const m = win.get(r.key) || new Map();
    win.set(r.key, m);
    const cur = m.get(r.minute) || { tokens: 0, usd: 0, unknownPrice: false };
    cur.tokens += totalTokens(r.t);
    cur.usd += estimateUsd(r.t, price);
    cur.unknownPrice = cur.unknownPrice || !known;
    m.set(r.minute, cur);
  }

  const alerts = [];
  if (initializing) {
    for (const k of usedKeys.keys()) s.seenKeys[k] = nowMin;
    for (const k of keyList || []) s.seenKeys[k.id] = nowMin;
    for (const m of usedModels.keys()) s.seenModels[m] = nowMin;
    s.initialized = true;
    alerts.push({ type: "started", keys: Object.keys(s.seenKeys).length, models: Object.keys(s.seenModels).length, baselineMinutes: cfg.baselineMinutes });
    prune(s, cfg, nowMin);
    return { state: s, alerts, initialized: true };
  }

  // (2a) Keys that appeared in the active key list.
  for (const k of keyList || []) {
    if (s.seenKeys[k.id]) continue;
    s.seenKeys[k.id] = nowMin;
    if (cfg.alertNewKeys) alerts.push({ type: "new_key_created", key: k.id, name: k.name, hint: k.hint, created_at: k.created_at, created_by: k.created_by });
  }
  // (2b) Keys and models with usage that were not seen before.
  for (const [key, models] of usedKeys) {
    if (s.seenKeys[key]) continue;
    s.seenKeys[key] = nowMin;
    if (cfg.alertNewKeys) alerts.push({ type: "new_key_usage", key, models: [...models].sort(), ...windowTotals(win.get(key)) });
  }
  for (const [model, keys] of usedModels) {
    if (s.seenModels[model]) continue;
    s.seenModels[model] = nowMin;
    if (cfg.alertNewModels) alerts.push({ type: "new_model", model, keys: [...keys].sort() });
  }

  // (1) Per-key spike: peak minute in the window vs average tokens/minute over the baseline window before it.
  const candidates = [];
  for (const [key, minutes] of win) {
    let peak = null;
    for (const [minute, v] of minutes) if (!peak || v.tokens > peak.tokens) peak = { minute, ...v };
    if (!peak) continue;
    // Baseline ends one bucket before the window so the minutes being judged don't count toward their own baseline.
    const base = baselineAvg(s, key, windowStart - cfg.baselineMinutes, windowStart - BUCKET + 1);
    if (peak.tokens >= cfg.minTokensPerMinute && peak.tokens > cfg.spikeMultiplier * base.avg) {
      candidates.push({ type: "spike", dedupe: `spike:${key}`, key, minute: peak.minute, tokens: peak.tokens, usd: peak.usd, unknownPrice: peak.unknownPrice,
        baselineAvg: Math.round(base.avg), baselineMinutes: base.minutes, ratio: base.avg > 0 ? peak.tokens / base.avg : null, ...windowTotals(minutes) });
    }
  }

  // (3) Off-hours activity.
  if (cfg.workHours) {
    for (const [key, minutes] of win) {
      let first = null, tokens = 0, usd = 0;
      for (const [minute, v] of [...minutes].sort((a, b) => a[0] - b[0])) {
        if (v.tokens < cfg.offHoursMinTokens || isWorkTime(minute, cfg)) continue;
        if (first === null) first = minute;
        tokens += v.tokens; usd += v.usd;
      }
      if (first !== null) candidates.push({ type: "off_hours", dedupe: `offhours:${key}`, key, minute: first, tokens, usd, local: localParts(first, cfg.timezone) });
    }
  }

  for (const c of candidates) {
    const last = s.cooldowns[c.dedupe];
    if (last !== undefined && nowMin - last < cfg.cooldownMinutes) continue;
    s.cooldowns[c.dedupe] = nowMin;
    alerts.push(c);
  }

  prune(s, cfg, nowMin);
  return { state: s, alerts, initialized: false };
}

function windowTotals(minutes) {
  let tokens = 0, usd = 0;
  if (minutes) for (const v of minutes.values()) { tokens += v.tokens; usd += v.usd; }
  return { windowTokens: tokens, windowUsd: usd };
}

function prune(s, cfg, nowMin) {
  const keepFrom = nowMin - cfg.lookbackMinutes - cfg.baselineMinutes - 60;
  for (const [key, b] of Object.entries(s.buckets)) {
    for (const m of Object.keys(b)) if (Number(m) < keepFrom) delete b[m];
    if (!Object.keys(b).length) delete s.buckets[key];
  }
  if (s.historyStart < keepFrom) s.historyStart = keepFrom;
  for (const [d, t] of Object.entries(s.cooldowns)) if (nowMin - t > COOLDOWN_KEEP_MINUTES) delete s.cooldowns[d];
}

// Recorded when the Admin API can't be read, so a broken setup doesn't fail silently. Returns null while cooling down.
export function errorAlert(prev, err, nowMin, cooldownMinutes = 360) {
  const s = prev ? structuredClone(prev) : newState();
  const d = "error:api";
  if (s.cooldowns[d] !== undefined && nowMin - s.cooldowns[d] < cooldownMinutes) return { state: s, alert: null };
  s.cooldowns[d] = nowMin;
  return { state: s, alert: { type: "error", status: err && err.status ? err.status : null, message: String((err && err.message) || err).slice(0, 200) } };
}