@acarmisc/backstage-plugin-litellm 0.19.0 → 0.20.0

package/dist/budget.d.ts

@@ -0,0 +1,45 @@
+import { UserInfo, TeamInfo, VirtualKey } from './types';
+import { Tone } from './components/ui';
+/** One concrete budget limit the signed-in user is subject to. */
+export interface BudgetLimit {
+    kind: 'key' | 'user' | 'team';
+    /** Display name: key_alias / "Personal budget" / team_alias. */
+    label: string;
+    /** Secondary identifier: masked key, team_id, etc. */
+    sublabel?: string;
+    /** Spend cap in USD (> 0 when a cap exists). */
+    budget: number;
+    /** Spend so far in the current window. */
+    spend: number;
+    /** Reset window, e.g. "30d". Missing means the budget never resets. */
+    budgetDuration?: string;
+    /** User-facing warning threshold (soft limit). */
+    softLimit?: number;
+    /** Share of the cap spent, 0..100+ (unclamped). */
+    pct: number;
+}
+/** The budgets that apply to the current user, grouped by enforcement level. */
+export interface BudgetSummary {
+    /** Budgeted keys, capped at `maxKeys`, closest to the cap first. */
+    keys: BudgetLimit[];
+    /** Budgeted keys hidden by the cap. */
+    hiddenBudgetedKeys: number;
+    /** Every key owned by the user (budgeted or not). */
+    totalKeyCount: number;
+    /** Personal budget, when one is set (undefined otherwise). */
+    user?: BudgetLimit;
+    /** Team budgets shared by the user's teams. */
+    teams: BudgetLimit[];
+}
+/**
+ * Collapses the current user's data into the budget limits that LiteLLM
+ * actually enforces for them: key budgets (top `maxKeys`, closest to the cap
+ * first), then the personal budget (when set), then each team budget. Team
+ * budgets are enforced for every key bound to that team; a key *without* a
+ * team falls back to the owner's personal budget.
+ */
+export declare function buildBudgetSummary(user: UserInfo | null, teams: TeamInfo[], keys: VirtualKey[], maxKeys?: number): BudgetSummary;
+/** "30d" → "every 30 days"; "1d" → "daily". Returns null when duration is unset. */
+export declare function fmtBudgetDuration(duration?: string): string | null;
+/** status pill tone + meter tone for a budget at `pct`. */
+export declare function budgetTone(pct: number): Tone;

package/dist/budget.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/LiteLLMBudgetWidget.d.ts

@@ -0,0 +1,22 @@
+/**
+ * LiteLLM budget-policy widget. Renders the enforcement hierarchy as a
+ * numbered flow — key → personal → team → global — and, against each level
+ * the signed-in user actually has a limit on, a live meter showing how close
+ * they are to the cap. Intended for at-a-glance use on a homepage card next
+ * to `LiteLLMHomeWidget`, but works anywhere.
+ *
+ * The policy text mirrors the LiteLLM proxy behaviour:
+ *   - every request is checked against stacked limits, in order;
+ *   - a key bound to a team is capped by the team budgets, not the owner's
+ *     personal budget;
+ *   - a limit with a `budget_duration` resets its spend when the window
+ *     closes; without one it never resets.
+ */
+import React from 'react';
+export interface LiteLLMBudgetWidgetProps {
+    /** Optional title override. Defaults to 'Budget Policy'. */
+    title?: string;
+    /** Max key budgets to show, closest to the cap first. Defaults to 3. */
+    maxKeys?: number;
+}
+export declare const LiteLLMBudgetWidget: React.FC<LiteLLMBudgetWidgetProps>;

package/dist/index.cjs.js

@@ -3873,6 +3873,7 @@ __export(index_exports, {
   DashboardHeader: () => DashboardHeader,
   GenerateKeyDialog: () => GenerateKeyDialog,
   KeysTable: () => KeysTable,
+  LiteLLMBudgetWidget: () => LiteLLMBudgetWidget,
   LiteLLMHomeWidget: () => LiteLLMHomeWidget,
   LiteLLMPage: () => LiteLLMPage,
   LiteLlmApi: () => LiteLlmApi,
@@ -4024,6 +4025,280 @@ var LiteLLMHomeWidget = ({
   ))))));
 };
 
+// src/components/LiteLLMBudgetWidget.tsx
+var import_react13 = __toESM(require("react"));
+var import_Paper8 = __toESM(require("@mui/material/Paper"));
+var import_Box12 = __toESM(require("@mui/material/Box"));
+var import_Typography12 = __toESM(require("@mui/material/Typography"));
+var import_CircularProgress7 = __toESM(require("@mui/material/CircularProgress"));
+var import_Alert7 = __toESM(require("@mui/material/Alert"));
+var import_styles7 = require("@mui/material/styles");
+var import_core_plugin_api5 = require("@backstage/core-plugin-api");
+init_api();
+init_format();
+init_ui();
+
+// src/budget.ts
+function limitPct(spend, budget) {
+  if (budget <= 0) return 0;
+  return spend / budget * 100;
+}
+function buildBudgetSummary(user, teams, keys, maxKeys = 3) {
+  const budgeted = keys.filter((k) => (k.max_budget ?? 0) > 0).map((k) => {
+    const spend = k.spend ?? 0;
+    return {
+      kind: "key",
+      label: k.key_alias || k.key || "Untitled key",
+      sublabel: k.key,
+      budget: k.max_budget,
+      spend,
+      budgetDuration: k.budget_duration,
+      pct: limitPct(spend, k.max_budget)
+    };
+  }).sort((a, b) => b.pct - a.pct);
+  const userBudget = user && (user.max_budget ?? user.hard_limit ?? 0) > 0 ? (() => {
+    const budget = user.max_budget ?? user.hard_limit ?? 0;
+    const spend = user.current_spend ?? user.spend ?? 0;
+    return {
+      kind: "user",
+      label: "Personal budget",
+      sublabel: user.user_email || user.user_id,
+      budget,
+      spend,
+      budgetDuration: user.budget_duration,
+      softLimit: user.soft_limit,
+      pct: limitPct(spend, budget)
+    };
+  })() : void 0;
+  const teamLimits = teams.filter((t) => (t.max_budget ?? 0) > 0).map((t) => {
+    const spend = t.spend ?? 0;
+    return {
+      kind: "team",
+      label: t.team_alias || "Untitled team",
+      sublabel: t.team_id,
+      budget: t.max_budget,
+      spend,
+      budgetDuration: t.budget_duration,
+      pct: limitPct(spend, t.max_budget)
+    };
+  }).sort((a, b) => b.pct - a.pct);
+  return {
+    keys: budgeted.slice(0, maxKeys),
+    hiddenBudgetedKeys: Math.max(0, budgeted.length - maxKeys),
+    totalKeyCount: keys.length,
+    user: userBudget,
+    teams: teamLimits
+  };
+}
+function fmtBudgetDuration(duration) {
+  if (!duration) return null;
+  const m = /^(\d+)(s|m|h|d)$/.exec(duration);
+  if (!m) return duration;
+  const n = Number(m[1]);
+  const unit = m[2];
+  if (unit === "d") return n === 1 ? "daily" : `every ${n} days`;
+  if (unit === "h") return n === 1 ? "hourly" : `every ${n} hours`;
+  if (unit === "m") return n === 1 ? "every minute" : `every ${n} minutes`;
+  return n === 1 ? "every second" : `every ${n} seconds`;
+}
+function budgetTone3(pct) {
+  if (pct >= 100) return "danger";
+  if (pct >= 80) return "warning";
+  return "accent";
+}
+
+// src/components/LiteLLMBudgetWidget.tsx
+function levelToneColor(tone, theme) {
+  switch (tone) {
+    case "success":
+      return theme.palette.success.main;
+    case "warning":
+      return theme.palette.warning.main;
+    case "danger":
+      return theme.palette.error.main;
+    case "info":
+      return theme.palette.info.main;
+    default:
+      return theme.palette.primary.main;
+  }
+}
+var LevelFrame = ({
+  rank,
+  name,
+  tagline,
+  note,
+  tone,
+  isLast,
+  children
+}) => /* @__PURE__ */ import_react13.default.createElement(import_Box12.default, { sx: { display: "flex", gap: 1.5 } }, /* @__PURE__ */ import_react13.default.createElement(import_Box12.default, { sx: { display: "flex", flexDirection: "column", alignItems: "center", width: 26, flexShrink: 0 } }, /* @__PURE__ */ import_react13.default.createElement(
+  import_Box12.default,
+  {
+    sx: (theme) => ({
+      width: 26,
+      height: 26,
+      borderRadius: "50%",
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "center",
+      bgcolor: (0, import_styles7.alpha)(levelToneColor(tone, theme), 0.14),
+      color: levelToneColor(tone, theme),
+      fontSize: 12,
+      fontWeight: 700,
+      flexShrink: 0
+    })
+  },
+  rank
+), /* @__PURE__ */ import_react13.default.createElement(
+  import_Box12.default,
+  {
+    sx: (theme) => ({
+      flex: 1,
+      width: 2,
+      minHeight: 14,
+      bgcolor: isLast ? "transparent" : (0, import_styles7.alpha)(theme.palette.text.primary, 0.12)
+    })
+  }
+)), /* @__PURE__ */ import_react13.default.createElement(import_Box12.default, { sx: { flex: 1, minWidth: 0, pb: isLast ? 0 : 2 } }, /* @__PURE__ */ import_react13.default.createElement(import_Box12.default, { sx: { display: "flex", alignItems: "baseline", gap: 1, flexWrap: "wrap", mb: 0.75 } }, /* @__PURE__ */ import_react13.default.createElement(
+  import_Typography12.default,
+  {
+    sx: (theme) => ({
+      fontSize: 12.5,
+      fontWeight: 700,
+      letterSpacing: "0.08em",
+      textTransform: "uppercase",
+      color: levelToneColor(tone, theme)
+    })
+  },
+  name
+), /* @__PURE__ */ import_react13.default.createElement(import_Typography12.default, { variant: "caption", color: "text.secondary", sx: { fontSize: 11.5 } }, tagline), note && /* @__PURE__ */ import_react13.default.createElement(StatusPill, { label: note, tone: "neutral", dot: false, sx: { ml: "auto" } })), /* @__PURE__ */ import_react13.default.createElement(import_Box12.default, { sx: { display: "flex", flexDirection: "column", gap: 1 } }, children)));
+var EmptyLimitCard = ({ children }) => /* @__PURE__ */ import_react13.default.createElement(
+  import_Paper8.default,
+  {
+    variant: "outlined",
+    sx: (theme) => ({
+      px: 1.5,
+      py: 1.25,
+      borderRadius: 1.5,
+      bgcolor: (0, import_styles7.alpha)(theme.palette.text.primary, theme.palette.mode === "dark" ? 0.03 : 0.015)
+    })
+  },
+  /* @__PURE__ */ import_react13.default.createElement(import_Typography12.default, { variant: "body2", color: "text.secondary", sx: { fontSize: 13 } }, children)
+);
+var LimitCard = ({ limit }) => {
+  const tone = budgetTone3(limit.pct);
+  const pct = Math.round(limit.pct);
+  const closeTo = limit.softLimit !== void 0 && limit.spend >= limit.softLimit;
+  return /* @__PURE__ */ import_react13.default.createElement(import_Paper8.default, { variant: "outlined", sx: { px: 1.5, py: 1.25, borderRadius: 1.5 } }, /* @__PURE__ */ import_react13.default.createElement(import_Box12.default, { sx: { display: "flex", alignItems: "baseline", justifyContent: "space-between", gap: 1.5 } }, /* @__PURE__ */ import_react13.default.createElement(import_Box12.default, { sx: { minWidth: 0, flex: 1 } }, /* @__PURE__ */ import_react13.default.createElement(
+    import_Typography12.default,
+    {
+      variant: "body2",
+      sx: { fontWeight: 600, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" },
+      title: limit.sublabel ? `${limit.label} \xB7 ${limit.sublabel}` : limit.label
+    },
+    limit.label
+  ), limit.sublabel && /* @__PURE__ */ import_react13.default.createElement(
+    import_Typography12.default,
+    {
+      variant: "caption",
+      color: "text.secondary",
+      sx: {
+        fontSize: 10.5,
+        fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+        display: "block",
+        overflow: "hidden",
+        textOverflow: "ellipsis",
+        whiteSpace: "nowrap"
+      }
+    },
+    limit.sublabel
+  )), /* @__PURE__ */ import_react13.default.createElement(import_Typography12.default, { variant: "body2", sx: { fontWeight: 600, fontVariantNumeric: "tabular-nums", whiteSpace: "nowrap" } }, fmtUsd(limit.spend), /* @__PURE__ */ import_react13.default.createElement(import_Box12.default, { component: "span", color: "text.secondary", sx: { fontWeight: 400 } }, " / ", fmtUsd(limit.budget)))), /* @__PURE__ */ import_react13.default.createElement(import_Box12.default, { sx: { mt: 1 } }, /* @__PURE__ */ import_react13.default.createElement(Meter, { value: limit.pct, tone, height: 6 })), /* @__PURE__ */ import_react13.default.createElement(
+    import_Box12.default,
+    {
+      sx: {
+        display: "flex",
+        justifyContent: "space-between",
+        alignItems: "center",
+        gap: 1,
+        mt: 0.75
+      }
+    },
+    /* @__PURE__ */ import_react13.default.createElement(import_Typography12.default, { variant: "caption", color: "text.secondary", sx: { fontVariantNumeric: "tabular-nums" } }, pct, "% of budget", closeTo && ` \xB7 soft-limit warning`),
+    /* @__PURE__ */ import_react13.default.createElement(import_Typography12.default, { variant: "caption", color: "text.secondary" }, fmtBudgetDuration(limit.budgetDuration) ? `resets ${fmtBudgetDuration(limit.budgetDuration)}` : "never resets")
+  ));
+};
+var LiteLLMBudgetWidget = ({
+  title = "Budget Policy",
+  maxKeys = 3
+}) => {
+  const api = (0, import_core_plugin_api5.useApi)(liteLlmApiRef);
+  const [loading, setLoading] = (0, import_react13.useState)(true);
+  const [error, setError] = (0, import_react13.useState)(null);
+  const [user, setUser] = (0, import_react13.useState)(null);
+  const [teams, setTeams] = (0, import_react13.useState)([]);
+  const [keys, setKeys] = (0, import_react13.useState)([]);
+  (0, import_react13.useEffect)(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    Promise.allSettled([api.getUserInfo(), api.getTeams(), api.listKeys()]).then(
+      ([userResult, teamsResult, keysResult]) => {
+        if (cancelled) return;
+        if (userResult.status === "fulfilled") {
+          setUser(userResult.value);
+        } else {
+          setUser(null);
+          setError(
+            userResult.reason?.message ?? "Failed to load your LiteLLM profile"
+          );
+        }
+        setTeams(teamsResult.status === "fulfilled" ? teamsResult.value : []);
+        setKeys(keysResult.status === "fulfilled" ? keysResult.value : []);
+        setLoading(false);
+      }
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [api]);
+  const hasAnyLimit = !!user && (user.max_budget ?? user.hard_limit ?? 0) > 0;
+  const summary = (0, import_react13.useMemo)(() => buildBudgetSummary(user, teams, keys, maxKeys), [user, teams, keys, maxKeys]);
+  const hasBudgetedKeys = keys.some((k) => (k.max_budget ?? 0) > 0);
+  return /* @__PURE__ */ import_react13.default.createElement(import_Paper8.default, { sx: { p: 2 } }, /* @__PURE__ */ import_react13.default.createElement(import_Box12.default, { sx: { mb: 1.5 } }, /* @__PURE__ */ import_react13.default.createElement(import_Typography12.default, { variant: "h6", lineHeight: 1.2 }, title), /* @__PURE__ */ import_react13.default.createElement(import_Typography12.default, { variant: "caption", color: "text.secondary" }, "How LiteLLM caps spend \u2014 and where you stand right now")), loading && /* @__PURE__ */ import_react13.default.createElement(import_Box12.default, { display: "flex", justifyContent: "center", alignItems: "center", minHeight: 140 }, /* @__PURE__ */ import_react13.default.createElement(import_CircularProgress7.default, { size: 32 })), !loading && error && /* @__PURE__ */ import_react13.default.createElement(import_Alert7.default, { severity: "error", sx: { mt: 0.5 } }, error), !loading && !error && /* @__PURE__ */ import_react13.default.createElement(import_react13.default.Fragment, null, /* @__PURE__ */ import_react13.default.createElement(
+    LevelFrame,
+    {
+      rank: 1,
+      name: "Key",
+      tagline: "per-key cap \xB7 highest priority",
+      note: hasBudgetedKeys ? void 0 : "no key budgets set"
+    },
+    !hasBudgetedKeys && /* @__PURE__ */ import_react13.default.createElement(EmptyLimitCard, null, "No key has a budget, so no key-level cap applies."),
+    summary.keys.map((k) => /* @__PURE__ */ import_react13.default.createElement(LimitCard, { key: k.sublabel ?? k.label, limit: k })),
+    summary.hiddenBudgetedKeys > 0 && /* @__PURE__ */ import_react13.default.createElement(import_Typography12.default, { variant: "caption", color: "text.secondary" }, "+", summary.hiddenBudgetedKeys, " more budgeted key", summary.hiddenBudgetedKeys > 1 ? "s" : "", " further from the cap")
+  ), /* @__PURE__ */ import_react13.default.createElement(
+    LevelFrame,
+    {
+      rank: 2,
+      name: "User",
+      tagline: "cap on everything you spend with your own keys",
+      note: "skipped for team-bound keys"
+    },
+    hasAnyLimit && summary.user ? /* @__PURE__ */ import_react13.default.createElement(LimitCard, { limit: summary.user }) : /* @__PURE__ */ import_react13.default.createElement(EmptyLimitCard, null, "No personal budget is set on your account.")
+  ), /* @__PURE__ */ import_react13.default.createElement(LevelFrame, { rank: 3, name: "Team", tagline: "shared cap for all keys in a team (if any)" }, summary.teams.length > 0 ? summary.teams.map((t) => /* @__PURE__ */ import_react13.default.createElement(LimitCard, { key: t.sublabel ?? t.label, limit: t })) : /* @__PURE__ */ import_react13.default.createElement(EmptyLimitCard, null, "No team you belong to has a budget.")), /* @__PURE__ */ import_react13.default.createElement(LevelFrame, { rank: 4, name: "Global", tagline: "proxy-wide cap set by your admin", isLast: true }, /* @__PURE__ */ import_react13.default.createElement(EmptyLimitCard, null, "Configured by your admin in the proxy config \u2014 it isn't visible from this page. When set, it limits spend across every request on the proxy.")), /* @__PURE__ */ import_react13.default.createElement(
+    import_Box12.default,
+    {
+      sx: (theme) => ({
+        mt: 2,
+        px: 1.5,
+        py: 1.25,
+        borderRadius: 1.5,
+        border: "1px dashed",
+        borderColor: (0, import_styles7.alpha)(theme.palette.text.primary, 0.18)
+      })
+    },
+    /* @__PURE__ */ import_react13.default.createElement(import_Typography12.default, { variant: "caption", color: "text.secondary", display: "block" }, "The first cap a request runs into is the one that stops it. A limit with a reset window (e.g. daily or every 30 days) clears its spend to $0 when the window closes; without a window it never resets.")
+  )));
+};
+
 // src/index.ts
 init_GenerateKeyDialog();
 init_ManageTeamDialog();