diff --git a/litellm/proxy/db/spend_counter_reseed.py b/litellm/proxy/db/spend_counter_reseed.py index 95fef0e7820..00cb35866f8 100644 --- a/litellm/proxy/db/spend_counter_reseed.py +++ b/litellm/proxy/db/spend_counter_reseed.py @@ -51,6 +51,7 @@ from litellm.repositories.verification_token_repository import ( ) if TYPE_CHECKING: + from prisma.models import LiteLLM_BudgetWindowSpend from prisma.types import LiteLLM_EndUserTableWhereUniqueInput from litellm.proxy.utils import PrismaClient @@ -78,6 +79,16 @@ def _as_utc(value: datetime) -> datetime: return value if value.tzinfo is not None else value.replace(tzinfo=timezone.utc) +def recorded_window_spend( + row: "LiteLLM_BudgetWindowSpend | None", entity_type: str, expected_window_start: datetime | None +) -> float | None: + if expected_window_start is None: + return None + if row is None or _as_utc(row.window_start) < _as_utc(expected_window_start): + return 0.0 if entity_type.startswith("customer_") else None + return float(row.spend or 0.0) + + _CUSTOMER_OVERRIDE_INCLUDE: Final = MappingProxyType({"budget": True, "budget_override": True}) _CUSTOMER_COUNTER: Final = re.compile( r"spend:(customer_org|customer_team|customer_member):(.+):" @@ -369,11 +380,7 @@ class SpendCounterReseed: ) return None - if row is None or _as_utc(row.window_start) < _as_utc(expected_window_start): - # Customer windows are new maintained balances, with no historical - # SpendLogs aggregate. A missing period starts at zero, a failed read above does not. - return 0.0 if entity_type.startswith("customer_") else None - return float(row.spend or 0.0) + return recorded_window_spend(row, entity_type, expected_window_start) @staticmethod async def window_from_db( diff --git a/litellm/proxy/management_helpers/customer_budget_usage.py b/litellm/proxy/management_helpers/customer_budget_usage.py new file mode 100644 index 00000000000..2802149f18c --- /dev/null +++ b/litellm/proxy/management_helpers/customer_budget_usage.py @@ -0,0 +1,103 @@ +from collections.abc import Mapping, Sequence +from datetime import datetime +from itertools import chain +from typing import TYPE_CHECKING, Final, TypeVar + +from litellm.proxy.common_utils.timezone_utils import BudgetResetSettings +from litellm.repositories.chunked_in import find_many_in +from litellm.repositories.prisma_protocols import TableActions +from litellm.types.proxy.auth.customer_hierarchy import CustomerScopeKey +from litellm.types.proxy.management_endpoints.customer_hierarchy import ( + Budget, + CustomerBudgetUsage, + CustomerMember, + Organization, + Team, +) + +if TYPE_CHECKING: + from prisma.models import LiteLLM_BudgetWindowSpend + + from litellm.proxy.spend_tracking.budget_reservation import BudgetCounter + +Entity: Final = TypeVar("Entity", Organization, Team, CustomerMember) + + +def _identity(entity: Organization | Team | CustomerMember) -> tuple[CustomerScopeKey, str, Budget | None]: + if isinstance(entity, Organization): + return "customer_org", entity.customer_org_id, entity.budget + if isinstance(entity, Team): + return "customer_team", entity.customer_team_id, entity.effective_budget + return "customer_member", entity.customer_member_id, entity.effective_budget + + +def _scalar_usage( + entity: Organization | Team | CustomerMember, budget: Budget | None +) -> tuple[CustomerBudgetUsage, ...]: + if budget is None or budget.max_budget is None: + return () + return ( + CustomerBudgetUsage( + source="scalar", + budget_duration=budget.budget_duration, + max_budget=budget.max_budget, + spend=entity.spend, + reset_at=entity.budget_reset_at, + ), + ) + + +def _usage( + counters: Sequence["BudgetCounter"], + rows: Mapping[tuple[str, str, str], "LiteLLM_BudgetWindowSpend"], +) -> tuple[CustomerBudgetUsage, ...]: + from litellm.proxy.db.spend_counter_reseed import recorded_window_spend + + return tuple( + CustomerBudgetUsage( + source="window", + budget_duration=counter.window_duration, + max_budget=counter.max_budget, + spend=recorded_window_spend( + rows.get((counter.entity_type, counter.entity_id, counter.window_duration or "")), + counter.entity_type, + counter.window_start, + ), + window_start=counter.window_start, + reset_at=counter.reset_at, + ) + for counter in counters + ) + + +async def customer_budget_usage( + entities: Sequence[Entity], + table: TableActions["LiteLLM_BudgetWindowSpend"], + now: datetime, + settings: BudgetResetSettings, +) -> tuple[Entity, ...]: + from litellm.proxy.spend_tracking.budget_reservation import customer_window_counters + + if not entities: + return () + identities: Final = tuple(_identity(entity) for entity in entities) + counters: Final = tuple( + customer_window_counters(scope, entity_id, budget.budget_limits or (), now=now, reset_settings=settings) + if budget is not None + else () + for scope, entity_id, budget in identities + ) + windows: Final = tuple(chain.from_iterable(counters)) + rows: Final = await find_many_in( + table, + "entity_id", + tuple(counter.entity_id for counter in windows), + where={"entity_type": identities[0][0]}, + ) + by_window: Final = {(row.entity_type, row.entity_id, row.window_duration): row for row in rows} + return tuple( + entity.model_copy( + update={"budget_usage": _scalar_usage(entity, identity[2]) + _usage(entity_windows, by_window)} + ) + for entity, identity, entity_windows in zip(entities, identities, counters, strict=True) + ) diff --git a/litellm/proxy/management_helpers/customer_hierarchy.py b/litellm/proxy/management_helpers/customer_hierarchy.py index 631f338c32f..a65e3505715 100644 --- a/litellm/proxy/management_helpers/customer_hierarchy.py +++ b/litellm/proxy/management_helpers/customer_hierarchy.py @@ -17,6 +17,7 @@ from litellm.proxy.common_utils.timezone_utils import ( ) from litellm.proxy.db.db_span import db_span from litellm.proxy.list_api.common import escape_like +from litellm.proxy.management_helpers.customer_budget_usage import customer_budget_usage from litellm.repositories.budget_repository import create_budget_row, update_budget_row from litellm.repositories.chunked_in import delete_many_in, find_many_in from litellm.repositories.prisma_protocols import TableActions @@ -38,6 +39,7 @@ from litellm.types.proxy.management_endpoints.customer_hierarchy import ( if TYPE_CHECKING: from prisma import Json, Prisma + from prisma.models import LiteLLM_BudgetWindowSpend class ErrorCode(str, Enum): @@ -472,6 +474,7 @@ class CustomerHierarchyStore: self.teams: TableActions[PrismaRecord] = db.litellm_customerteamtable # pyright: ignore[reportAttributeAccessIssue] # protocol accepts immutable query mappings self.members: TableActions[PrismaRecord] = db.litellm_customermembertable # pyright: ignore[reportAttributeAccessIssue] # protocol accepts immutable query mappings self.budgets: TableActions[PrismaRecord] = db.litellm_budgettable # pyright: ignore[reportAttributeAccessIssue] # protocol accepts immutable query mappings + self.window_spend: TableActions[LiteLLM_BudgetWindowSpend] = db.litellm_budgetwindowspend # pyright: ignore[reportAttributeAccessIssue] # protocol accepts immutable query mappings async def lock_free_capacity(self) -> None: await self.db.query_raw("SELECT 1 AS locked FROM pg_advisory_xact_lock($1)", FREE_CAPACITY_ADVISORY_LOCK) @@ -525,9 +528,10 @@ class CustomerHierarchyStore: budgets: Final = {budget.budget_id: budget for budget in resolved} counts: Final = await self.organization_member_counts(tuple(record.customer_org_id for record in records)) - return tuple( + responses: Final = tuple( organization_response(record, budgets, counts.get(record.customer_org_id, 0)) for record in records ) + return await customer_budget_usage(responses, self.window_spend, self.now, self.settings) async def organization_member_counts(self, organization_ids: tuple[str, ...]) -> Mapping[str, int]: if not organization_ids: @@ -554,11 +558,21 @@ class CustomerHierarchyStore: async def get_team(self, team_id: str) -> Team | Failure: row: Final = await self.teams.find_unique(where={"customer_team_id": team_id}, include=_MEMBER_INCLUDE) - return team_response(row, self.now) if row is not None else Failure(ErrorCode.NOT_FOUND) + if row is None: + return Failure(ErrorCode.NOT_FOUND) + responses: Final = await customer_budget_usage( + (team_response(row, self.now),), self.window_spend, self.now, self.settings + ) + return responses[0] async def get_member(self, member_id: str) -> CustomerMember | Failure: row: Final = await self.members.find_unique(where={"customer_member_id": member_id}, include=_MEMBER_INCLUDE) - return member_response(row, self.now) if row is not None else Failure(ErrorCode.NOT_FOUND) + if row is None: + return Failure(ErrorCode.NOT_FOUND) + responses: Final = await customer_budget_usage( + (member_response(row, self.now),), self.window_spend, self.now, self.settings + ) + return responses[0] async def create_budget(self, budget: Budget, actor: str, name: str | None = None) -> str: budget_id: Final = str(uuid4()) @@ -959,7 +973,12 @@ class CustomerHierarchyStore: order=[{"created_at": "asc"}, {"customer_team_id": "asc"}], include=_MEMBER_INCLUDE, ) - return Page(tuple(team_response(row, self.now) for row in rows), count) + return Page( + await customer_budget_usage( + tuple(team_response(row, self.now) for row in rows), self.window_spend, self.now, self.settings + ), + count, + ) async def list_members( self, parent_team_id: str | None, page: int, page_size: int, *, parent_org_id: str | None = None @@ -976,7 +995,12 @@ class CustomerHierarchyStore: order=[{"created_at": "asc"}, {"customer_member_id": "asc"}], include=_MEMBER_INCLUDE, ) - return Page(tuple(member_response(row, self.now) for row in rows), count) + return Page( + await customer_budget_usage( + tuple(member_response(row, self.now) for row in rows), self.window_spend, self.now, self.settings + ), + count, + ) async def _delete_unused_budgets(self, budget_ids: Sequence[str]) -> None: where: Final[Mapping[str, object]] = {field: {"none": {}} for field in _BUDGET_REFERENCE_FIELDS} diff --git a/litellm/types/proxy/management_endpoints/customer_hierarchy.py b/litellm/types/proxy/management_endpoints/customer_hierarchy.py index aa977174bec..06300affb76 100644 --- a/litellm/types/proxy/management_endpoints/customer_hierarchy.py +++ b/litellm/types/proxy/management_endpoints/customer_hierarchy.py @@ -119,12 +119,28 @@ class MemberUpsert(MemberPatch): return self +class CustomerBudgetUsage(BaseModel): + model_config = ConfigDict(frozen=True) + + source: Literal["scalar", "window"] + budget_duration: str | None + max_budget: float + spend: float | None + window_start: datetime | None = None + reset_at: datetime | None = None + + class AuditFields(BaseModel): model_config = ConfigDict(frozen=True) alias: str | None = None spend: float = 0.0 budget_reset_at: datetime | None = None + budget_usage: tuple[CustomerBudgetUsage, ...] | None = Field( + default=None, + description="Recorded spend for each independent effective budget. Excludes pending reservations and updates " + "after accounting flushes. Window boundaries follow the configured reset timezone and time.", + ) created_at: datetime created_by: str updated_at: datetime diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetSpend.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetSpend.tsx new file mode 100644 index 00000000000..2ba9b20418b --- /dev/null +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetSpend.tsx @@ -0,0 +1,94 @@ +import { useTranslation } from "react-i18next"; +import { formatUsd } from "@/app/(dashboard)/usage/_components/components/overview/overviewData"; +import { cn } from "@/lib/cva.config"; +import { CUSTOMER_BUDGET_LABELS, customerBudgetPeriod, type CustomerBudgetUsage } from "./customerBudgetUsage"; + +function budgetPercentage(spend: number, limit: number | null): number { + if (limit === null) return 0; + if (limit === 0) return 100; + return Math.max(0, Math.min(100, (spend / limit) * 100)); +} + +export function CustomerBudgetWindow({ + budget, + showReset = false, +}: { + budget: CustomerBudgetUsage; + showReset?: boolean; +}) { + const { t, i18n } = useTranslation(); + const period = customerBudgetPeriod(budget.budget_duration); + const label = t(CUSTOMER_BUDGET_LABELS[period]); + const reset = budget.reset_at + ? t("customerPortal.analytics.budgetResets", { + date: new Date(budget.reset_at).toLocaleString(i18n.resolvedLanguage, { timeZone: "UTC" }), + }) + : null; + return ( +
+ + {showReset && reset &&

{reset}

} +
+ ); +} + +export default function CustomerBudgetSpend({ + spend, + limit, + label, + noLimitLabel, + compact = false, +}: { + spend: number | null; + limit: number | null; + label: string; + noLimitLabel?: string; + compact?: boolean; +}) { + const { t } = useTranslation(); + const value = `${spend === null ? t("customerPortal.analytics.unknownSpend") : formatUsd(spend)} / ${limit === null ? noLimitLabel ?? t("customerPortal.analytics.noLimit") : formatUsd(limit)}`; + const atLimit = limit !== null && spend !== null && spend >= limit; + const percentage = budgetPercentage(spend ?? 0, limit); + const balance = + limit === null || spend === null + ? null + : t(spend > limit ? "customerPortal.analytics.budgetOver" : "customerPortal.analytics.budgetRemaining", { + amount: formatUsd(Math.abs(limit - spend)), + }); + if (compact) return {value}; + return ( +
+
+ {value} + {balance !== null && ( + + {balance} + + )} +
+ {limit !== null && spend !== null && ( +
+
+
+ )} +
+ ); +} diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetSummary.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetSummary.tsx index 26adc7a3cbc..69c98d614ec 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetSummary.tsx +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetSummary.tsx @@ -1,13 +1,7 @@ import { useTranslation } from "react-i18next"; -import { formatUsd } from "@/app/(dashboard)/usage/_components/components/overview/overviewData"; -import { cn } from "@/lib/cva.config"; import type { CustomerUsageEntity } from "./customerUsageApi"; - -function budgetPercentage(spend: number, limit: number | null): number { - if (limit === null) return 0; - if (limit === 0) return 100; - return Math.max(0, Math.min(100, (spend / limit) * 100)); -} +import CustomerBudgetSpend, { CustomerBudgetWindow } from "./CustomerBudgetSpend"; +import { CUSTOMER_BUDGET_LABELS, customerBudgetPeriod, customerBudgetUsage } from "./customerBudgetUsage"; export default function CustomerBudgetSummary({ entity, @@ -16,41 +10,35 @@ export default function CustomerBudgetSummary({ entity: CustomerUsageEntity; settingsHref: string; }) { - const { t, i18n } = useTranslation(); - const limit = entity.budgetLimit; - const atLimit = limit !== null && entity.spend >= limit; - const percentage = budgetPercentage(entity.spend, limit); - const cap = limit === null ? t("customerPortal.analytics.noCap") : formatUsd(limit); - const value = `${formatUsd(entity.spend)} / ${cap}`; + const { t } = useTranslation(); + const budgets = customerBudgetUsage(entity); return ( -
+
{t("customerPortal.analytics.budgetSummary")} - {t(limit === null ? "customerPortal.analytics.setBudget" : "customerPortal.analytics.editBudget")} + {t(budgets.length > 0 ? "customerPortal.analytics.editBudget" : "customerPortal.analytics.setBudget")}
-

{value}

- {limit !== null && ( -
-
-
+ {budgets.map((budget) => { + const period = customerBudgetPeriod(budget.budget_duration); + return ( +
+

+ {t(CUSTOMER_BUDGET_LABELS[period])} + {period === "other" && budget.budget_duration && ` (${budget.budget_duration})`} +

+ customerBudgetPeriod(item.budget_duration) === period).length > 1} + /> +
+ ); + })} + {budgets.length === 0 && ( + )} -

- {t("customerPortal.analytics.budgetPeriod")} - {entity.budgetResetAt && - ` · ${t("customerPortal.analytics.budgetResets", { - date: new Date(entity.budgetResetAt).toLocaleDateString(i18n.resolvedLanguage, { timeZone: "UTC" }), - })}`} -

+

{t("customerPortal.analytics.budgetUsageHint")}

); } diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerHierarchyManager.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerHierarchyManager.tsx index 5e90b329b27..0a72578a7c7 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerHierarchyManager.tsx +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerHierarchyManager.tsx @@ -41,13 +41,16 @@ function HierarchyHeader({ hierarchy, selected }: Pick { - if (member.budgetLimit === null) return "customerPortal.analytics.noCap" as const; - if (member.spend > member.budgetLimit) return "customerPortal.analytics.overBudget" as const; - if (member.spend === member.budgetLimit) return "customerPortal.analytics.atBudget" as const; - return "customerPortal.analytics.withinBudget" as const; -}; - export default function CustomerMemberSpend({ data, onMemberClick, @@ -30,13 +25,17 @@ export default function CustomerMemberSpend({ const { t } = useTranslation(); const [table, setTable] = useQueryStates(MEMBER_TABLE_PARSERS); const search = table.memberSearch; - const usage = useMemo(() => new Map(data.members.map((member) => [member.id, member])), [data.members]); + const usage = useMemo(() => new Map(data.monthlyMembers.map((member) => [member.id, member])), [data.monthlyMembers]); + const yearlyUsage = useMemo( + () => new Map(data.yearlyMembers.map((member) => [member.id, member.spend])), + [data.yearlyMembers], + ); const members = useMemo( () => data.memberBudgets .filter((member) => member.label.toLocaleLowerCase().includes(search.toLocaleLowerCase())) - .map((member) => ({ ...member, rangeUsage: usage.get(member.id) })) - .sort((a, b) => (b.rangeUsage?.spend ?? 0) - (a.rangeUsage?.spend ?? 0) || a.label.localeCompare(b.label)), + .map((member) => ({ ...member, monthlyUsage: usage.get(member.id) })) + .sort((a, b) => (b.monthlyUsage?.spend ?? 0) - (a.monthlyUsage?.spend ?? 0) || a.label.localeCompare(b.label)), [data.memberBudgets, search, usage], ); @@ -65,15 +64,33 @@ export default function CustomerMemberSpend({ {t("customerPortal.analytics.member")} - {t("customerPortal.analytics.spend")} + {t("customerPortal.analytics.monthlySpend")} + {t("customerPortal.analytics.yearlySpend")} + {t("customerPortal.analytics.customerSpendShare")} {t("customerPortal.analytics.tokens")} - {t("customerPortal.analytics.currentBudget")} {t("customerPortal.analytics.status")} {members.slice(start, start + PAGE_SIZE).map((member) => { - const atLimit = member.budgetLimit !== null && member.spend >= member.budgetLimit; + const monthlySpend = member.monthlyUsage?.spend ?? 0; + const budgets = customerBudgetUsage(member); + const monthlyBudgets = budgets.filter( + (budget) => customerBudgetPeriod(budget.budget_duration) === "monthly", + ); + const yearlyBudgets = budgets.filter((budget) => customerBudgetPeriod(budget.budget_duration) === "yearly"); + const otherBudgets = budgets.filter((budget) => customerBudgetPeriod(budget.budget_duration) === "other"); + const yearlySpend = yearlyUsage.get(member.id) ?? 0; + const spendShare = + data.monthlyOrganizationSpend > 0 ? (monthlySpend / data.monthlyOrganizationSpend) * 100 : 0; + const sharePercentage = Math.max(0, Math.min(100, spendShare)); + const shareLabel = t("format.number", { + val: spendShare / 100, + style: "percent", + maximumFractionDigits: 1, + }); + const status = customerBudgetStatus(budgets); + const atLimit = status === "customerPortal.analytics.reachedLimit"; return ( @@ -101,14 +118,58 @@ export default function CustomerMemberSpend({
- {formatUsd(member.rangeUsage?.spend ?? 0)} - - {formatCompact(member.rangeUsage?.tokens ?? 0)} + +
+ {monthlyBudgets.map((budget) => ( + 1} /> + ))} + {monthlyBudgets.length === 0 && ( + + )} + {otherBudgets.map((budget) => ( +
+ + {t("customerPortal.analytics.budgetPeriod")} + {budget.budget_duration && ` (${budget.budget_duration})`} + + +
+ ))} +
- - {member.budgetLimit === null - ? t("customerPortal.analytics.noBudget") - : `${formatUsd(member.spend)} / ${formatUsd(member.budgetLimit)}`} + +
+ {yearlyBudgets.map((budget) => ( + 1} /> + ))} + {yearlyBudgets.length === 0 && + `${formatUsd(yearlySpend)} / ${t("customerPortal.analytics.noYearlyLimit")}`} +
+
+ +
+
+
+ + + {formatCompact(member.monthlyUsage?.tokens ?? 0)} - {t(memberStatus(member))} + {t(status)} @@ -125,7 +186,7 @@ export default function CustomerMemberSpend({ })} {members.length === 0 && ( - + {t(search ? "customerPortal.analytics.noMatches" : "customerPortal.analytics.noMembers")} diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerBudgetUsage.test.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerBudgetUsage.test.ts new file mode 100644 index 00000000000..eb943d83380 --- /dev/null +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerBudgetUsage.test.ts @@ -0,0 +1,60 @@ +import { describe, expect, it } from "vitest"; +import { customerBudgetPeriod, customerBudgetStatus, customerBudgetUsage } from "./customerBudgetUsage"; +import type { CustomerUsageEntity } from "./customerUsageApi"; + +const entity: CustomerUsageEntity = { + id: "member", + label: "Member", + spend: 40, + budgetLimit: 50, + budgetDuration: "1mo", + budgetResetAt: null, + budgetLimits: [ + { budget_duration: "1mo", max_budget: 10 }, + { budget_duration: "12mo", max_budget: 100 }, + ], +}; + +describe("customer budget usage", () => { + it("keeps independent counters and their limits paired, even with the same duration", () => { + const budgetUsage = [ + { source: "scalar" as const, budget_duration: "1mo", max_budget: 50, spend: 40 }, + { source: "window" as const, budget_duration: "1mo", max_budget: 10, spend: 8 }, + { source: "window" as const, budget_duration: "12mo", max_budget: 100, spend: 62 }, + ]; + expect(customerBudgetUsage({ ...entity, budgetUsage })).toEqual(budgetUsage); + expect(customerBudgetStatus(budgetUsage)).toBe("customerPortal.analytics.withinBudget"); + }); + + it.each([0, 10, 100])("marks a recorded exhausted limit including zero (%s)", (limit) => { + expect(customerBudgetStatus([{ source: "window", budget_duration: "12mo", max_budget: limit, spend: limit }])).toBe( + "customerPortal.analytics.reachedLimit", + ); + }); + + it("distinguishes unavailable window usage from no budget and zero spend", () => { + const usage = customerBudgetUsage(entity); + expect(usage.map((budget) => [budget.max_budget, budget.spend])).toEqual([ + [50, 40], + [10, null], + [100, null], + ]); + expect(customerBudgetStatus(usage)).toBe("customerPortal.analytics.budgetUsageUnavailable"); + expect(customerBudgetStatus([])).toBe("customerPortal.analytics.noLimit"); + expect(customerBudgetStatus([{ source: "window", budget_duration: "1mo", max_budget: 10, spend: 0 }])).toBe( + "customerPortal.analytics.withinBudget", + ); + }); + + it.each([ + ["1mo", "monthly"], + ["monthly", "monthly"], + ["30days", "monthly"], + ["12mo", "yearly"], + ["12months", "yearly"], + ["365d", "other"], + [null, "other"], + ] as const)("labels the configured duration %s without computing its reset", (duration, period) => { + expect(customerBudgetPeriod(duration)).toBe(period); + }); +}); diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerBudgetUsage.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerBudgetUsage.ts new file mode 100644 index 00000000000..c651a75454e --- /dev/null +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerBudgetUsage.ts @@ -0,0 +1,48 @@ +import type { components } from "@/lib/http/schema"; +import type { CustomerUsageEntity } from "./customerUsageApi"; + +export type CustomerBudgetUsage = components["schemas"]["CustomerBudgetUsage"]; +export type CustomerBudgetPeriod = "monthly" | "yearly" | "other"; + +export const CUSTOMER_BUDGET_LABELS = { + monthly: "customerPortal.analytics.monthlySpend", + yearly: "customerPortal.analytics.yearlySpend", + other: "customerPortal.analytics.budgetPeriod", +} as const; + +export const customerBudgetPeriod = (duration: string | null): CustomerBudgetPeriod => { + const normalized = duration?.trim().toLowerCase() ?? ""; + if (["1mo", "1month", "1months", "30d", "30days", "monthly"].includes(normalized)) return "monthly"; + if (["12mo", "12month", "12months"].includes(normalized)) return "yearly"; + return "other"; +}; + +export const customerBudgetUsage = (entity: CustomerUsageEntity): CustomerBudgetUsage[] => + entity.budgetUsage ?? [ + ...(entity.budgetLimit === null + ? [] + : [ + { + source: "scalar" as const, + budget_duration: entity.budgetDuration, + max_budget: entity.budgetLimit, + spend: entity.spend, + reset_at: entity.budgetResetAt, + }, + ]), + ...entity.budgetLimits.map((limit) => ({ + source: "window" as const, + budget_duration: limit.budget_duration, + max_budget: limit.max_budget, + spend: null, + reset_at: limit.reset_at, + })), + ]; + +export const customerBudgetStatus = (usage: CustomerBudgetUsage[]) => { + if (usage.some((budget) => budget.spend !== null && budget.spend >= budget.max_budget)) + return "customerPortal.analytics.reachedLimit" as const; + if (usage.some((budget) => budget.spend === null)) return "customerPortal.analytics.budgetUsageUnavailable" as const; + if (usage.length === 0) return "customerPortal.analytics.noLimit" as const; + return "customerPortal.analytics.withinBudget" as const; +}; diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.test.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.test.ts index cb4d2b738b2..cd13a5c3d6f 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.test.ts +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.test.ts @@ -99,6 +99,10 @@ const request = { accessToken: "test-session", startDate: "2026-11-01", endDate: "2026-11-03", + monthStartDate: "2026-11-01", + monthEndDate: "2026-11-03", + yearStartDate: "2026-01-01", + yearEndDate: "2026-11-03", }; const list = (data: T[], page = 1, totalPages = 1) => ({ data, @@ -167,6 +171,37 @@ beforeEach(() => { afterEach(() => vi.unstubAllGlobals()); describe("customerHierarchyUsageCall", () => { + it("should preserve scalar and concurrent effective caps without treating recorded spend as window spend", async () => { + const budget = { + max_budget: 25, + budget_duration: "1mo", + budget_limits: [ + { budget_duration: "1mo", max_budget: 0, reset_at: "2026-12-01T00:00:00Z" }, + { budget_duration: "12mo", max_budget: 100, reset_at: "2027-01-01T00:00:00Z" }, + ], + }; + fetchMock.mockImplementation((input) => + Promise.resolve( + requestUrl(input).pathname.endsWith("/customer_members/member-a") + ? json({ ...members[0], effective_budget: budget }) + : serve(input), + ), + ); + const result = await customerHierarchyUsageCall({ + ...request, + scope: { org: "org-1", team: null, member: "member-a" }, + }); + const expected = { + spend: 40, + budgetLimit: 25, + budgetDuration: "1mo", + budgetLimits: budget.budget_limits, + }; + expect(result.member).toMatchObject(expected); + expect(result.memberBudgets[0]).toEqual(result.member); + expect(result.organization.budgetLimits).toEqual([]); + }); + it("should read exact daily activity routes, all pages, and scoped descendant lists", async () => { fetchMock.mockImplementation((input) => { const url = requestUrl(input); @@ -202,9 +237,14 @@ describe("customerHierarchyUsageCall", () => { expect(result.memberResults).toHaveLength(1); expect(result.memberResults[0].breakdown.entities["member-b"].metrics.total_tokens).toBe(500); expect(result.memberBudgets[0]).toMatchObject({ id: "member-a", spend: 40, budgetLimit: 10 }); + expect(result.yearlyMembers.map((member) => member.spend)).toEqual([3, 1]); for (const url of dailyUrls()) { expect(url.pathname).toMatch(/^\/management\/v1\/customer_(organizations|teams|members)\/daily\/activity$/); - expect(url.searchParams.get("start_date")).toBe(request.startDate); + expect(url.searchParams.get("start_date")).toBe( + url.pathname.includes("customer_members") && url.searchParams.get("start_date") === request.yearStartDate + ? request.yearStartDate + : request.startDate, + ); expect(url.searchParams.get("end_date")).toBe(request.endDate); expect(url.searchParams.get("page_size")).toBe("100"); expect([...url.searchParams.keys()].filter((name) => name.endsWith("_ids"))).toHaveLength(1); @@ -252,11 +292,35 @@ describe("customerHierarchyUsageCall", () => { expect(Object.keys(result.teamResults[0].breakdown.entities)).toEqual(["team-a"]); expect(result.teamResults[0].breakdown.entities["team-a"].metrics.spend).toBe(3); expect(result.memberResults[0].breakdown.entities["member-a"].metrics.total_tokens).toBe(100); - expect(dailyUrls()).toHaveLength(1); - expect(dailyUrls()[0].searchParams.get("customer_member_ids")).toBe("member-a"); + const memberReads = dailyUrls().filter((url) => url.searchParams.has("customer_member_ids")); + expect(memberReads.map((url) => url.searchParams.get("start_date"))).toEqual([ + request.startDate, + request.yearStartDate, + ]); + expect(memberReads[0].searchParams.get("customer_member_ids")).toBe("member-a"); + expect(result.monthlyOrganizationSpend).toBe(4); + expect(result.monthlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3); + expect(result.yearlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3); expect(urls().some((url) => url.pathname === "/management/v1/customer_members")).toBe(false); }); + it("should retain both periods when the selected chart range is the current year", async () => { + const yearRequest = { + ...request, + scope: { org: "org-1", team: null, member: "member-a" }, + startDate: request.yearStartDate, + endDate: request.yearEndDate, + }; + const result = await customerHierarchyUsageCall(yearRequest); + expect(result.yearlyMembers).toEqual(result.members); + expect(result.monthlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3); + expect( + dailyUrls() + .filter((url) => url.searchParams.has("customer_member_ids")) + .map((url) => url.searchParams.get("start_date")), + ).toEqual([request.yearStartDate, request.monthStartDate]); + }); + it("should reject mismatched ancestry before requesting any usage", async () => { fetchMock.mockImplementation((input) => Promise.resolve( @@ -271,6 +335,29 @@ describe("customerHierarchyUsageCall", () => { expect(dailyUrls()).toHaveLength(0); }); + it("should read monthly member totals and the whole organization independently of a team's selected chart dates", async () => { + fetchMock.mockImplementation((input) => { + const url = requestUrl(input); + if (url.pathname.endsWith("/daily/activity") && url.searchParams.get("start_date") === "2026-10-01") + return Promise.resolve(json({ results: [], metadata: EMPTY_DAILY_ACTIVITY_METADATA })); + return Promise.resolve(serve(input)); + }); + const teamRequest = { + ...request, + scope: { org: "org-1", team: "team-a", member: null }, + startDate: "2026-10-01", + endDate: "2026-10-31", + }; + const result = await customerHierarchyUsageCall(teamRequest); + expect(result.metadata.total_spend).toBe(0); + expect(result.monthlyOrganizationSpend).toBe(4); + expect(result.monthlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3); + expect(result.yearlyMembers.find((member) => member.id === "member-a")?.spend).toBe(3); + const organizationReads = dailyUrls().filter((url) => url.searchParams.has("customer_org_ids")); + expect(organizationReads.map((url) => url.searchParams.get("page"))).toEqual(["1", "2"]); + expect(organizationReads.every((url) => url.searchParams.get("start_date") === request.monthStartDate)).toBe(true); + }); + it("should never send an empty descendant filter and should retain unassigned usage", async () => { fetchMock.mockImplementation((input) => Promise.resolve(requestUrl(input).pathname === "/management/v1/customer_teams" ? json(list([])) : serve(input)), diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.ts index aedd12d5aa9..4852af7540b 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.ts +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageApi.ts @@ -27,7 +27,10 @@ export interface CustomerUsageEntity { label: string; spend: number; budgetLimit: number | null; + budgetDuration: string | null; + budgetLimits: components["schemas"]["BudgetLimit"][]; budgetResetAt: string | null; + budgetUsage?: components["schemas"]["CustomerBudgetUsage"][] | null; } export interface CustomerHierarchyUsage extends ReturnType { @@ -40,6 +43,9 @@ export interface CustomerHierarchyUsage extends ReturnType["results"]; memberResults: ReturnType["results"]; memberBudgets: CustomerUsageEntity[]; + monthlyOrganizationSpend: number; + monthlyMembers: UsageRow[]; + yearlyMembers: UsageRow[]; } interface CustomerUsageRequest { @@ -47,6 +53,10 @@ interface CustomerUsageRequest { accessToken: string; startDate: string; endDate: string; + monthStartDate: string; + monthEndDate: string; + yearStartDate: string; + yearEndDate: string; signal?: AbortSignal; } @@ -136,7 +146,7 @@ const activityPages = async (resource: Collection, ids: readonly string[], reque }; interface ActivityJob { - dimension: "scope" | "teams" | "members"; + dimension: "scope" | "teams" | "members" | "monthlyOrganization" | "monthlyMembers" | "yearlyMembers"; resource: Collection; ids: readonly string[]; } @@ -148,13 +158,19 @@ const chunkJobs = (resource: Collection, dimension: ActivityJob["dimension"], id ids: ids.slice(index * PAGE_SIZE, (index + 1) * PAGE_SIZE), })); -const entity = (id: string, record: Organization | Team | Member): CustomerUsageEntity => ({ - id, - label: record.alias || id, - spend: record.spend, - budgetLimit: ("effective_budget" in record ? record.effective_budget : record.budget)?.max_budget ?? null, - budgetResetAt: record.budget_reset_at ?? null, -}); +const entity = (id: string, record: Organization | Team | Member): CustomerUsageEntity => { + const budget = "effective_budget" in record ? record.effective_budget : record.budget; + return { + id, + label: record.alias || id, + spend: record.spend, + budgetLimit: budget?.max_budget ?? null, + budgetDuration: budget?.budget_duration ?? null, + budgetLimits: budget?.budget_limits ?? [], + budgetResetAt: record.budget_reset_at ?? null, + budgetUsage: record.budget_usage, + }; +}; const selectedResource = (scope: ResolvedScope): Collection => { if (scope.member) return "customer_members"; @@ -162,6 +178,21 @@ const selectedResource = (scope: ResolvedScope): Collection => { return "customer_organizations"; }; +const monthlyJobs = ( + isCurrentMonth: boolean, + resource: Collection, + organizationId: string, + memberIds: readonly string[], +): ActivityJob[] => [ + ...(!isCurrentMonth || resource !== "customer_organizations" + ? chunkJobs("customer_organizations", "monthlyOrganization", [organizationId]) + : []), + ...(!isCurrentMonth ? chunkJobs("customer_members", "monthlyMembers", memberIds) : []), +]; + +const isSelectedRange = (request: CustomerUsageRequest, startDate: string, endDate: string): boolean => + request.startDate === startDate && request.endDate === endDate; + export const customerHierarchyUsageCall = async (request: CustomerUsageRequest): Promise => { assertIdentifiers([ request.scope.org, @@ -171,6 +202,8 @@ export const customerHierarchyUsageCall = async (request: CustomerUsageRequest): const children = await descendants(selected, request); const resource = selectedResource(selected); const selectedId = selected.member?.customer_member_id ?? selected.team?.customer_team_id ?? request.scope.org; + const isCurrentMonth = isSelectedRange(request, request.monthStartDate, request.monthEndDate); + const isCurrentYear = isSelectedRange(request, request.yearStartDate, request.yearEndDate); const jobs: ActivityJob[] = [ { dimension: "scope", resource, ids: [selectedId] }, ...(!selected.team @@ -187,10 +220,33 @@ export const customerHierarchyUsageCall = async (request: CustomerUsageRequest): children.members.map((member) => member.customer_member_id), ) : []), + ...monthlyJobs( + isCurrentMonth, + resource, + request.scope.org, + children.members.map((member) => member.customer_member_id), + ), + ...(!isCurrentYear + ? chunkJobs( + "customer_members", + "yearlyMembers", + children.members.map((member) => member.customer_member_id), + ) + : []), ]; + const monthRequest = { ...request, startDate: request.monthStartDate, endDate: request.monthEndDate }; + const yearRequest = { ...request, startDate: request.yearStartDate, endDate: request.yearEndDate }; + const requests: Record = { + scope: request, + teams: request, + members: request, + monthlyOrganization: monthRequest, + monthlyMembers: monthRequest, + yearlyMembers: yearRequest, + }; const activity = await batches(jobs, async (job) => ({ dimension: job.dimension, - pages: await activityPages(job.resource, job.ids, request), + pages: await activityPages(job.resource, job.ids, requests[job.dimension]), })); const primary = mergeCustomerActivityPages( activity.filter((result) => result.dimension === "scope").flatMap((result) => result.pages), @@ -205,6 +261,22 @@ export const customerHierarchyUsageCall = async (request: CustomerUsageRequest): : mergeCustomerActivityPages( activity.filter((result) => result.dimension === "members").flatMap((result) => result.pages), ).results; + const monthlyOrganization = + isCurrentMonth && resource === "customer_organizations" + ? primary + : mergeCustomerActivityPages( + activity.filter((result) => result.dimension === "monthlyOrganization").flatMap((result) => result.pages), + ); + const monthlyMemberDays = isCurrentMonth + ? memberDays + : mergeCustomerActivityPages( + activity.filter((result) => result.dimension === "monthlyMembers").flatMap((result) => result.pages), + ).results; + const yearlyMemberActivity = isCurrentYear + ? { results: memberDays, metadata: primary.metadata } + : mergeCustomerActivityPages( + activity.filter((result) => result.dimension === "yearlyMembers").flatMap((result) => result.pages), + ); const teamLabels = new Map( children.teams.map((team) => [team.customer_team_id, team.alias || team.customer_team_id]), ); @@ -232,5 +304,12 @@ export const customerHierarchyUsageCall = async (request: CustomerUsageRequest): ), memberResults: customerEntityDailyData(primary.results, memberDays, memberLabels), memberBudgets: children.members.map((member) => entity(member.customer_member_id, member)), + monthlyOrganizationSpend: monthlyOrganization.metadata.total_spend, + monthlyMembers: customerEntityRankings(monthlyMemberDays, memberLabels, monthlyOrganization.metadata, { + unassignedLabel: i18n.t("customerPortal.analytics.unassignedMember"), + }), + yearlyMembers: customerEntityRankings(yearlyMemberActivity.results, memberLabels, yearlyMemberActivity.metadata, { + unassignedLabel: i18n.t("customerPortal.analytics.unassignedMember"), + }), }; }; diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageChartData.test.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageChartData.test.ts index 2d2a46178e4..adf9e33fb22 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageChartData.test.ts +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageChartData.test.ts @@ -38,10 +38,21 @@ const day = (date: string, total: SpendMetrics, breakdown: Partial ({ - organization: { id: "org", label: "Organization", spend: 0, budgetLimit: null, budgetResetAt: null }, + organization: { + id: "org", + label: "Organization", + spend: 0, + budgetLimit: null, + budgetDuration: null, + budgetLimits: [], + budgetResetAt: null, + }, team: null, member: null, memberBudgets: [], + monthlyOrganizationSpend: 0, + monthlyMembers: [], + yearlyMembers: [], metadata: { ...EMPTY_DAILY_ACTIVITY_METADATA }, results: [ day("2026-11-01", metrics(100, 1_000, 100), { diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.test.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.test.ts index c8e6d638c79..e9cf6809f42 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.test.ts +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.test.ts @@ -1,7 +1,6 @@ import { describe, expect, it } from "vitest"; import type { DailyData, MetricWithMetadata, SpendMetrics } from "@/components/UsagePage/types"; import { rankCustomerModels, rankCustomerUsage, type CustomerUsageRow } from "./customerUsageData"; - const metrics = (spend: number, tokens: number, requests: number): SpendMetrics => ({ spend, prompt_tokens: tokens, diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.ts index afa0d3c7767..6d66b92dfbb 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.ts +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerUsageData.ts @@ -9,7 +9,6 @@ import { rollUpBreakdown, type UsageMetric, } from "@/app/(dashboard)/usage/_components/components/overview/overviewData"; - export interface CustomerUsageTotals { spend: number; tokens: number; diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/useCustomerHierarchyUsage.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/useCustomerHierarchyUsage.ts index 05fa467d0e5..67640a52240 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/useCustomerHierarchyUsage.ts +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/useCustomerHierarchyUsage.ts @@ -21,6 +21,7 @@ import type { DailyData } from "@/components/UsagePage/types"; import { customerHierarchyUsageCall, type CustomerUsageScope } from "./customerUsageApi"; import { rankCustomerModels, rankCustomerUsage } from "./customerUsageData"; import { CUSTOMER_USAGE_DIMENSIONS, type CustomerUsageDimension } from "./CustomerUsageRankings"; +import { calendarDate, customerPresetRange } from "./customerUsageRange"; const usageParsers = { org: parseAsString, @@ -60,9 +61,30 @@ export default function useCustomerHierarchyUsage() { const endDate = dateValue.to ? formatDate(dateValue.to) : undefined; const scope = params.org ? { org: params.org, team: params.team, member: params.member } : null; const request = usageRequest(scope, accessToken, startDate, endDate); + const month = customerPresetRange("month"); + const monthStartDate = calendarDate(month.from); + const monthEndDate = calendarDate(month.to); + const year = customerPresetRange("YTD"); + const yearStartDate = calendarDate(year.from); + const yearEndDate = calendarDate(year.to); const usage = useQuery({ - queryKey: ["customer-hierarchy", "usage", params.org, params.team, params.member, startDate, endDate], - queryFn: request ? ({ signal }) => customerHierarchyUsageCall({ ...request, signal }) : skipToken, + queryKey: [ + "customer-hierarchy", + "usage", + params.org, + params.team, + params.member, + startDate, + endDate, + monthStartDate, + yearEndDate, + ], + queryFn: request + ? ({ signal }) => { + const periodRequest = { ...request, monthStartDate, monthEndDate, yearStartDate, yearEndDate, signal }; + return customerHierarchyUsageCall(periodRequest); + } + : skipToken, }); const data = usage.data; const results = data?.results ?? EMPTY_RESULTS; diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/manage/page.integration.test.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/manage/page.integration.test.tsx index 269513b3045..e9c51fec78b 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/manage/page.integration.test.tsx +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/manage/page.integration.test.tsx @@ -134,7 +134,7 @@ describe("customer hierarchy management", () => { const table = await screen.findByRole("table", { name: "Customer teams" }); expect(within(table).getByRole("button", { name: "Product" })).toBeInTheDocument(); expect(screen.getByRole("heading", { name: "Example customer" })).toBeInTheDocument(); - expect(screen.getByRole("progressbar", { name: "Current budget" })).toHaveAttribute("aria-valuenow", "12"); + expect(screen.getByRole("progressbar", { name: "Recorded budget spend" })).toHaveAttribute("aria-valuenow", "12"); expect( requestedUrls() .find((url) => url.pathname === "/management/v1/customer_teams") @@ -152,6 +152,33 @@ describe("customer hierarchy management", () => { ]); }); + it("should show effective member window limits without treating them as an absent budget", async () => { + fetchMock.mockImplementation(async (input) => + requestUrl(input).pathname === "/management/v1/customer_members/member-a" + ? json({ + ...member, + effective_budget: { + max_budget: null, + budget_limits: [ + { budget_duration: "1mo", max_budget: 10 }, + { budget_duration: "12mo", max_budget: 100 }, + ], + }, + }) + : serve(input), + ); + renderWithProviders(, { searchParams: "?org=org-1&team=team-a&member=member-a" }); + const summary = await screen.findByRole("region", { name: "Current budget" }); + expect(within(summary).getByText("Unavailable / $10.00")).toBeInTheDocument(); + expect(within(summary).getByText("Unavailable / $100.00")).toBeInTheDocument(); + expect(within(summary).getByRole("link", { name: "Edit budget" })).toHaveAttribute( + "href", + `${uiHref("customers/manage")}?org=org-1&team=team-a&member=member-a&tab=settings`, + ); + expect(within(summary).queryByText(/No limit/)).not.toBeInTheDocument(); + expect(within(summary).queryByRole("progressbar")).not.toBeInTheDocument(); + }); + it("should list customer members across an organization and open their customer team context", async () => { const user = userEvent.setup(); const onUrlUpdate = vi.fn(); diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/usage/page.integration.test.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/usage/page.integration.test.tsx index a3472a36fb1..4eca6b81bb9 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/usage/page.integration.test.tsx +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/usage/page.integration.test.tsx @@ -61,6 +61,19 @@ const members = [ }, ]; const records = [ + ...[ + { date: "2026-03-01", spend: 42 }, + { date: "2025-12-31", spend: 100 }, + ].map(({ date, spend }) => ({ + organization: "org-1", + team: "team-a", + member: "member-a", + model: "model-a", + key: "hash-a", + alias: "Assistant key", + metrics: metrics(spend, 50, 1), + date, + })), { organization: "org-1", team: "team-a", @@ -81,6 +94,26 @@ const records = [ metrics: metrics(3, 600, 5), date: "2026-11-02", }, + { + organization: "org-1", + team: "team-a", + member: "member-a", + model: "model-a", + key: "hash-a", + alias: "Assistant key", + metrics: metrics(8, 300, 1), + date: "2026-11-10", + }, + { + organization: "org-1", + team: "", + member: "", + model: "model-a", + key: "hash-c", + alias: "Organization key", + metrics: metrics(7, 200, 1), + date: "2026-11-10", + }, ]; const fetchMock = vi.fn(); const json = (body: unknown, status = 200) => @@ -104,10 +137,13 @@ const filterFor = (resource: string | undefined) => team: "customer_team_ids", member: "customer_member_ids", })[activityDimension(resource)]; -const activityUrl = (resource: string, id: string) => { +const activityUrl = (resource: string, id: string, endDate = "2026-11-03") => { const filter = filterFor(resource); return requestedUrls().findLast( - (url) => url.pathname === `/management/v1/${resource}/daily/activity` && url.searchParams.get(filter) === id, + (url) => + url.pathname === `/management/v1/${resource}/daily/activity` && + url.searchParams.get(filter) === id && + url.searchParams.get("end_date") === endDate, ); }; const serve = (input: Parameters[0]): Response => { @@ -117,7 +153,13 @@ const serve = (input: Parameters[0]): Response => { const dimension = activityDimension(resource); const filter = filterFor(resource); const ids = url.searchParams.get(filter)?.split(",") ?? []; - const selected = records.filter((record) => ids.includes(record[dimension])); + const selected = records + .filter((record) => ids.includes(record[dimension])) + .filter( + (record) => + record.date >= (url.searchParams.get("start_date") ?? "") && + record.date <= (url.searchParams.get("end_date") ?? ""), + ); const results = selected.map((record) => { const key = { metrics: record.metrics, metadata: { key_alias: record.alias, team_id: null } }; const entry = { metrics: record.metrics, metadata: {}, api_key_breakdown: { [record.key]: key } }; @@ -148,6 +190,8 @@ const serve = (input: Parameters[0]): Response => { describe("CustomerHierarchyUsagePage", () => { beforeEach(() => { + vi.useFakeTimers({ toFake: ["Date"] }); + vi.setSystemTime(new Date("2026-11-13T12:00:00Z")); testQueryClient.clear(); registerBaseUrlGetter(() => "http://localhost"); fetchMock.mockReset(); @@ -160,6 +204,7 @@ describe("CustomerHierarchyUsagePage", () => { }); afterEach(() => { + vi.useRealTimers(); testQueryClient.clear(); vi.unstubAllGlobals(); }); @@ -231,7 +276,7 @@ describe("CustomerHierarchyUsagePage", () => { expect(activityUrl("customer_teams", "team-a")?.pathname).toBe("/management/v1/customer_teams/daily/activity"); expect(activityUrl("customer_teams", "team-a")?.searchParams.get("customer_team_ids")).toBe("team-a"); const teamBudget = screen.getByRole("region", { name: "Current budget" }); - expect(within(teamBudget).getByText("$40.00 / No cap")).toBeInTheDocument(); + expect(within(teamBudget).getByText("$40.00 / No limit")).toBeInTheDocument(); expect(within(teamBudget).getByRole("link", { name: "Set budget" })).toHaveAttribute( "href", "/ui/customers/manage?org=org-1&team=team-a&tab=settings", @@ -280,16 +325,20 @@ describe("CustomerHierarchyUsagePage", () => { ]); }); - it("should retain a separate member spend table with range usage and current budget status across chart breakdowns", async () => { + it("should retain monthly member usage and whole-customer shares across chart breakdowns", async () => { const user = userEvent.setup(); const onUrlUpdate = vi.fn(); renderWithProviders(, { searchParams: initialUrl, onUrlUpdate }); const table = await screen.findByRole("table", { name: "Customer member spend" }); const firstMember = within(table).getAllByRole("row")[1]; expect(firstMember).toHaveTextContent("Member One"); - expect(within(firstMember).getByText("$12.00")).toBeInTheDocument(); - expect(within(firstMember).getByText("$40.00 / $10.00")).toBeInTheDocument(); - expect(within(firstMember).getByText("Over budget")).toBeInTheDocument(); + expect(within(firstMember).getByText("$20.00 / No monthly limit")).toBeInTheDocument(); + expect(within(firstMember).getByRole("meter", { name: "Share of customer spend" })).toHaveAttribute( + "aria-valuetext", + "66.7%", + ); + expect(firstMember).toHaveTextContent("Recorded budget spend$40.00 / $10.00"); + expect(within(firstMember).getByText("Reached limit")).toBeInTheDocument(); await selectBreakdown(user, "Customer teams"); await user.click(screen.getByRole("radio", { name: "Tokens" })); @@ -335,6 +384,105 @@ describe("CustomerHierarchyUsagePage", () => { ); }); + it.each([ + { monthlySpend: 8, yearlySpend: 62, status: "Within budget" }, + { monthlySpend: 10, yearlySpend: 62, status: "Reached limit" }, + { monthlySpend: 8, yearlySpend: 100, status: "Reached limit" }, + ])( + "should use each recorded budget window consistently across the table and summary (%#)", + async ({ monthlySpend, yearlySpend, status }) => { + const user = userEvent.setup(); + const budgetUsage = [ + { source: "scalar", budget_duration: "1mo", max_budget: 50, spend: 40, reset_at: "2026-12-01T00:00:00Z" }, + { + source: "window", + budget_duration: "1mo", + max_budget: 10, + spend: monthlySpend, + window_start: "2026-11-01T17:00:00Z", + reset_at: "2026-12-01T17:00:00Z", + }, + { + source: "window", + budget_duration: "12mo", + max_budget: 100, + spend: yearlySpend, + window_start: "2026-01-01T17:00:00Z", + reset_at: "2027-01-01T17:00:00Z", + }, + ]; + fetchMock.mockImplementation((input) => { + const url = requestUrl(input); + const member = { + ...members[0], + budget_usage: budgetUsage, + effective_budget: { + max_budget: 50, + budget_duration: "1mo", + budget_limits: [ + { budget_duration: "1mo", max_budget: 10 }, + { budget_duration: "12mo", max_budget: 100 }, + ], + }, + }; + if (url.pathname === "/management/v1/customer_members") + return Promise.resolve(json(list(url.searchParams.get("parent_team_id") === "team-a" ? [member] : []))); + if (url.pathname.endsWith("/customer_members/member-a")) return Promise.resolve(json(member)); + return Promise.resolve(serve(input)); + }); + renderWithProviders(, { searchParams: initialUrl }); + const table = await screen.findByRole("table", { name: "Customer member spend" }); + const row = within(table).getAllByRole("row")[1]; + expect(within(row).getByText("$40.00 / $50.00")).toBeInTheDocument(); + expect(within(row).getByText(`$${monthlySpend.toFixed(2)} / $10.00`)).toBeInTheDocument(); + expect(within(row).getByText(`$${yearlySpend.toFixed(2)} / $100.00`)).toBeInTheDocument(); + expect( + within(row) + .getAllByRole("progressbar") + .map((bar) => bar.getAttribute("aria-valuenow")), + ).toEqual(["80", String(monthlySpend * 10)]); + expect(within(row).getByRole("meter", { name: "Share of customer spend" })).toHaveAttribute( + "aria-valuetext", + "66.7%", + ); + expect(within(row).getAllByRole("cell")[5]).toHaveTextContent(status); + await user.click(within(row).getByRole("button", { name: "Member One" })); + expect(await screen.findByRole("heading", { name: "Member One" })).toBeInTheDocument(); + const summary = screen.getByRole("region", { name: "Current budget" }); + expect(within(summary).getByText("$40.00 / $50.00")).toBeInTheDocument(); + expect(within(summary).getByText(`$${monthlySpend.toFixed(2)} / $10.00`)).toBeInTheDocument(); + expect(within(summary).getByText(`$${yearlySpend.toFixed(2)} / $100.00`)).toBeInTheDocument(); + expect( + within(summary) + .getAllByRole("progressbar") + .map((bar) => bar.getAttribute("aria-valuenow")), + ).toEqual(["80", String(monthlySpend * 10)]); + }, + ); + + it("should retain limits but not invent window spend when an older backend omits usage", async () => { + fetchMock.mockImplementation((input) => { + const url = requestUrl(input); + if (url.pathname === "/management/v1/customer_members") + return Promise.resolve( + json( + list( + url.searchParams.get("parent_team_id") === "team-a" + ? [{ ...members[0], effective_budget: { budget_limits: [{ budget_duration: "1mo", max_budget: 10 }] } }] + : [], + ), + ), + ); + return Promise.resolve(serve(input)); + }); + renderWithProviders(, { searchParams: initialUrl }); + const table = await screen.findByRole("table", { name: "Customer member spend" }); + const row = within(table).getAllByRole("row")[1]; + expect(within(row).getByText("Unavailable / $10.00")).toBeInTheDocument(); + expect(within(row).getByText("Budget usage unavailable")).toBeInTheDocument(); + expect(within(row).queryByRole("progressbar")).not.toBeInTheDocument(); + }); + it("should request a changed date range without showing stale totals or losing the customer scope", async () => { const user = userEvent.setup(); const onUrlUpdate = vi.fn(); @@ -355,10 +503,14 @@ describe("CustomerHierarchyUsagePage", () => { await user.click(screen.getByRole("button", { name: "Apply" })); await waitFor(() => - expect(activityUrl("customer_organizations", "org-1")?.searchParams.get("start_date")).toBe("2026-10-01"), + expect(activityUrl("customer_organizations", "org-1", "2026-10-07")?.searchParams.get("start_date")).toBe( + "2026-10-01", + ), ); - expect(activityUrl("customer_organizations", "org-1")?.searchParams.get("end_date")).toBe("2026-10-07"); - expect(activityUrl("customer_organizations", "org-1")?.pathname).toBe( + expect(activityUrl("customer_organizations", "org-1", "2026-10-07")?.searchParams.get("end_date")).toBe( + "2026-10-07", + ); + expect(activityUrl("customer_organizations", "org-1", "2026-10-07")?.pathname).toBe( "/management/v1/customer_organizations/daily/activity", ); expect(screen.getByRole("status", { name: "Loading customer usage" })).toBeInTheDocument(); @@ -425,7 +577,7 @@ describe("CustomerHierarchyUsagePage", () => { const budget = await screen.findByRole("region", { name: "Current budget" }); expect(within(budget).getByText("$40.00 / $0.00")).toBeInTheDocument(); expect(within(budget).getByRole("progressbar")).toHaveAttribute("aria-valuenow", "100"); - expect(within(budget).getByText(/Configured reset:.*UTC/)).toBeInTheDocument(); + expect(within(budget).getByTitle(/Configured reset:.*UTC/)).toBeInTheDocument(); expect(within(budget).queryByRole("link", { name: "Set budget" })).not.toBeInTheDocument(); }); }); diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageStatStrip.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageStatStrip.tsx index 7e7ccf5aa8b..da8e85a05d2 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageStatStrip.tsx +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageStatStrip.tsx @@ -42,7 +42,9 @@ export default function UsageStatStrip({ : t("usage.statStrip.noBudget"); return (
- }> + 1 ? : undefined} + > {spendDetails} - }> + 1 ? : undefined + } + > )} - }> + 1 ? : undefined + } + > None: + database: Final = Database() + http: Final = client(database=database) + family(http) + created: Final = http.post( + "/management/v1/customer_members", + json={ + "customer_member_id": "window-member", "parent_team_ids": ["team"], + "budget_override": { + "max_budget": 50, "budget_duration": "1mo", + "budget_limits": [{"budget_duration": "1mo", "max_budget": 10}], + }, + }, + ) + assert created.status_code == 201, created.text + database.litellm_budgetwindowspend.rows = { + "window-member": Record( + entity_type="customer_member", entity_id="window-member", window_duration="1mo", + window_start=NOW, spend=8, + ), + } + detail: Final = http.get("/management/v1/customer_members/window-member") + listing: Final = http.get("/management/v1/customer_members?parent_team_id=team") + assert detail.status_code == listing.status_code == 200 + assert listing.json()["data"][0]["budget_usage"] == detail.json()["budget_usage"] + assert [(item["spend"], item["max_budget"]) for item in detail.json()["budget_usage"]] == [(0, 50), (8, 10)] diff --git a/tests/unit/proxy/management_helpers/test_customer_budget_usage.py b/tests/unit/proxy/management_helpers/test_customer_budget_usage.py new file mode 100644 index 00000000000..910cd23d406 --- /dev/null +++ b/tests/unit/proxy/management_helpers/test_customer_budget_usage.py @@ -0,0 +1,80 @@ +from datetime import datetime, time, timezone +from typing import Final, cast + +import pytest +from prisma.models import LiteLLM_BudgetWindowSpend + +from litellm.models.budget import BudgetLimit + +from litellm.proxy.common_utils.timezone_utils import BudgetResetSettings +from litellm.proxy.management_helpers.customer_budget_usage import customer_budget_usage +from litellm.proxy.spend_tracking.budget_reservation import customer_window_counters +from litellm.repositories.prisma_protocols import TableActions +from litellm.types.proxy.management_endpoints.customer_hierarchy import Budget, CustomerMember +from tests.unit.proxy.management_helpers.test_customer_hierarchy import Database, Record + +NOW: Final = datetime(2026, 11, 13, 12, tzinfo=timezone.utc) +SETTINGS: Final = BudgetResetSettings(timezone="America/Los_Angeles", reset_time_of_day=time(9)) + + +def member(member_id: str) -> CustomerMember: + return CustomerMember( + customer_member_id=member_id, + parent_org_id="org", + parent_team_ids=("team",), + spend=40, + effective_budget=Budget( + max_budget=50, + budget_duration="1mo", + budget_limits=( + BudgetLimit(budget_duration="1mo", max_budget=10), + BudgetLimit(budget_duration="12mo", max_budget=100), + ), + ), + created_at=NOW, + created_by="admin", + updated_at=NOW, + updated_by="admin", + ) + + +@pytest.mark.asyncio +async def test_recorded_usage_matches_enforced_windows_and_keeps_shared_members_independent() -> None: + database: Final = Database() + first: Final = member("member-a") + second: Final = member("member-b") + counters: Final = customer_window_counters( + "customer_member", "member-a", first.effective_budget.budget_limits or (), now=NOW, reset_settings=SETTINGS + ) + assert counters[0].window_start == datetime(2026, 11, 1, 17, tzinfo=timezone.utc) + database.litellm_budgetwindowspend.rows = { + "monthly": Record( + entity_type="customer_member", entity_id="member-a", window_duration="1mo", + window_start=counters[0].window_start, spend=8, + ), + "yearly": Record( + entity_type="customer_member", entity_id="member-a", window_duration="12mo", + window_start=counters[1].window_start, spend=62, + ), + "another-scope": Record( + entity_type="customer_team", entity_id="member-b", window_duration="1mo", + window_start=counters[0].window_start, spend=999, + ), + "expired": Record( + entity_type="customer_member", entity_id="member-b", window_duration="1mo", + window_start=datetime(2026, 10, 1, 16, tzinfo=timezone.utc), spend=100, + ), + } + result: Final = await customer_budget_usage( + (first, second), + cast(TableActions[LiteLLM_BudgetWindowSpend], database.litellm_budgetwindowspend), + NOW, + SETTINGS, + ) + assert result[0].budget_usage is not None + assert tuple((item.spend, item.max_budget) for item in result[0].budget_usage) == ((40, 50), (8, 10), (62, 100)) + assert tuple((item.window_start, item.reset_at) for item in result[0].budget_usage[1:]) == tuple( + (counter.window_start, counter.reset_at) for counter in counters + ) + assert result[1].budget_usage is not None + assert tuple(item.spend for item in result[1].budget_usage) == (40, 0, 0) diff --git a/tests/unit/proxy/management_helpers/test_customer_hierarchy.py b/tests/unit/proxy/management_helpers/test_customer_hierarchy.py index 8d9be312ac9..da73d4617bf 100644 --- a/tests/unit/proxy/management_helpers/test_customer_hierarchy.py +++ b/tests/unit/proxy/management_helpers/test_customer_hierarchy.py @@ -243,6 +243,7 @@ class Database: self.litellm_customerteamtable = Table("customer_team_id", self) self.litellm_customermembertable = Table("customer_member_id", self) self.litellm_budgettable = Table("budget_id", self) + self.litellm_budgetwindowspend = Table("entity_id", self) self.litellm_verificationtoken = Table("token", self) self.litellm_projecttable = Table("project_id", self) self.litellm_customerbudgetincreaserequest = Table("request_id", self)