diff --git a/litellm/proxy/management_endpoints/management_v1/customers.py b/litellm/proxy/management_endpoints/management_v1/customers.py index c1fce25f443..1df89e60ea1 100644 --- a/litellm/proxy/management_endpoints/management_v1/customers.py +++ b/litellm/proxy/management_endpoints/management_v1/customers.py @@ -17,6 +17,7 @@ from litellm.proxy.list_api.common import ( ) from litellm.proxy.management_endpoints.management_v1.common import MANAGEMENT_V1_PREFIX from litellm.proxy.management_helpers.customer_hierarchy import ( + BudgetSort, CustomerHierarchy, CustomerPortalLimits, ErrorCode, @@ -408,9 +409,12 @@ async def list_customer_teams( page: Annotated[int, Query(ge=1)] = 1, page_size: Annotated[int, Query(ge=1)] = 50, parent_org_id: str | None = None, + sort: Annotated[ + BudgetSort | None, Query(description="Sort by displayed budget limit, with uncapped rows last.") + ] = None, ) -> ListResponse[Team]: size: Final = min(page_size, 100) - result: Final = resolve(await hierarchy.list_teams(parent_org_id, page, size)) + result: Final = resolve(await hierarchy.list_teams(parent_org_id, page, size, sort)) return list_response(result, request, page, size) @@ -522,10 +526,15 @@ async def list_customer_members( parent_team_id: str | None = None, parent_org_id: str | None = None, search: Annotated[str, Query(description="Case-insensitive substring of the customer member ID or alias")] = "", + sort: Annotated[ + BudgetSort | None, Query(description="Sort by displayed budget limit, with uncapped rows last.") + ] = None, ) -> ListResponse[CustomerMember]: size: Final = min(page_size, 100) result: Final = resolve( - await hierarchy.list_members(parent_team_id, page, size, parent_org_id=parent_org_id, search=search.strip()) + await hierarchy.list_members( + parent_team_id, page, size, parent_org_id=parent_org_id, search=search.strip(), sort=sort + ) ) return list_response(result, request, page, size) diff --git a/litellm/proxy/management_helpers/customer_hierarchy.py b/litellm/proxy/management_helpers/customer_hierarchy.py index 01a9a62b380..31ff0d65ac9 100644 --- a/litellm/proxy/management_helpers/customer_hierarchy.py +++ b/litellm/proxy/management_helpers/customer_hierarchy.py @@ -4,7 +4,7 @@ from dataclasses import dataclass from datetime import datetime, timezone from enum import Enum from itertools import chain -from typing import TYPE_CHECKING, Final, Generic, Protocol, TypeVar +from typing import TYPE_CHECKING, Final, Generic, Literal, Protocol, TypeAlias, TypeVar from uuid import uuid4 from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, model_validator @@ -20,7 +20,7 @@ from litellm.proxy.db.exception_handler import PrismaDBExceptionHandler 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 count_in, delete_many_in, find_many_in +from litellm.repositories.chunked_in import IN_LIST_CHUNK_SIZE, count_in, delete_many_in, find_many_in from litellm.repositories.prisma_protocols import TableActions from litellm.types.proxy.management_endpoints.customer_hierarchy import ( Budget, @@ -46,6 +46,49 @@ if TYPE_CHECKING: from prisma.models import LiteLLM_BudgetWindowSpend +BudgetSort: TypeAlias = Literal["budget_asc", "budget_desc"] + + +def customer_budget_limit(budget: Budget | None) -> float | None: + if budget is None: + return None + limits: Final = budget.budget_limits or () + monthly: Final = next( + ( + limit.max_budget + for limit in limits + if limit.budget_duration.strip().lower() in ("1mo", "1month", "1months", "30d", "30days", "monthly") + ), + None, + ) + if monthly is not None: + return monthly + if budget.max_budget is not None: + return budget.max_budget + return next( + ( + limit.max_budget + for limit in limits + if limit.budget_duration.strip().lower() in ("12mo", "12month", "12months") + ), + None, + ) + + +def _budget_sort_key(budget: Budget | None, sort: BudgetSort) -> tuple[bool, float]: + limit: Final = customer_budget_limit(budget) + return limit is None, (limit or 0) * (-1 if sort == "budget_desc" else 1) + + +class _BudgetSortRow(BaseModel): + model_config = ConfigDict(frozen=True) + + entity_id: str + budget_id: str | None + budget_override_id: str | None + budget_override_expires_at: datetime | None + + class ErrorCode(str, Enum): FREE_TIER_LIMIT = "free_tier_limit" CAPACITY_BUSY = "capacity_busy" @@ -1058,9 +1101,49 @@ class CustomerHierarchyStore: ) return Page(await self.organization_responses(rows), count) - async def list_teams(self, parent_org_id: str | None, page: int, page_size: int) -> Page[Team]: + async def list_teams( + self, parent_org_id: str | None, page: int, page_size: int, sort: BudgetSort | None = None + ) -> Page[Team]: where: Final = {"parent_org_id": parent_org_id} if parent_org_id is not None else {} count: Final = await self.teams.count(where=where) + if sort is not None: + ids: Final = await self._budget_sort_ids( + await self.db.query_raw( + "SELECT customer_team_id AS entity_id, budget_id, budget_override_id, budget_override_expires_at " + 'FROM "LiteLLM_CustomerTeamTable" WHERE ($1::text IS NULL OR parent_org_id = $1) ' + "ORDER BY created_at ASC, customer_team_id ASC", + parent_org_id, + ), + sort, + page, + page_size, + ) + chunks: Final = tuple( + [ + await self.teams.find_many( + # bounded-ok: Each slice has at most IN_LIST_CHUNK_SIZE ids. + where={"customer_team_id": {"in": list(ids[start : start + IN_LIST_CHUNK_SIZE])}}, + include=_MEMBER_INCLUDE, + ) + for start in range(0, len(ids), IN_LIST_CHUNK_SIZE) + ] + ) + rows_by_id: Final = { + _ID.validate_python(row.model_dump()["customer_team_id"]): row for row in chain.from_iterable(chunks) + } + return Page( + await customer_budget_usage( + tuple( + team_response(rows_by_id[identifier], self.now) + for identifier in ids + if identifier in rows_by_id + ), + self.window_spend, + self.now, + self.settings, + ), + count, + ) rows: Final = await self.teams.find_many( where=where, skip=(page - 1) * page_size, @@ -1070,7 +1153,10 @@ class CustomerHierarchyStore: ) return Page( await customer_budget_usage( - tuple(team_response(row, self.now) for row in rows), self.window_spend, self.now, self.settings + tuple(team_response(row, self.now) for row in rows), + self.window_spend, + self.now, + self.settings, ), count, ) @@ -1083,6 +1169,7 @@ class CustomerHierarchyStore: *, parent_org_id: str | None = None, search: str = "", + sort: BudgetSort | None = None, ) -> Page[CustomerMember]: where: Final[Mapping[str, object]] = { **({"parent_team_ids": {"has": parent_team_id}} if parent_team_id is not None else {}), @@ -1090,6 +1177,48 @@ class CustomerHierarchyStore: **_search_filter(search, ("alias", "customer_member_id")), } count: Final = await self.members.count(where=where) + if sort is not None: + ids: Final = await self._budget_sort_ids( + await self.db.query_raw( + "SELECT customer_member_id AS entity_id, budget_id, budget_override_id, budget_override_expires_at " + 'FROM "LiteLLM_CustomerMemberTable" WHERE ($1::text IS NULL OR parent_org_id = $1) ' + "AND ($2::text IS NULL OR parent_team_ids @> ARRAY[$2]::text[]) " + "AND ($3 = '' OR alias ILIKE $3 OR customer_member_id ILIKE $3) " + "ORDER BY created_at ASC, customer_member_id ASC", + parent_org_id, + parent_team_id, + f"%{escape_like(search)}%" if search else "", + ), + sort, + page, + page_size, + ) + chunks: Final = tuple( + [ + await self.members.find_many( + # bounded-ok: Each slice has at most IN_LIST_CHUNK_SIZE ids. + where={"customer_member_id": {"in": list(ids[start : start + IN_LIST_CHUNK_SIZE])}}, + include=_MEMBER_INCLUDE, + ) + for start in range(0, len(ids), IN_LIST_CHUNK_SIZE) + ] + ) + rows_by_id: Final = { + _ID.validate_python(row.model_dump()["customer_member_id"]): row for row in chain.from_iterable(chunks) + } + return Page( + await customer_budget_usage( + tuple( + member_response(rows_by_id[identifier], self.now) + for identifier in ids + if identifier in rows_by_id + ), + self.window_spend, + self.now, + self.settings, + ), + count, + ) rows: Final = await self.members.find_many( where=where, skip=(page - 1) * page_size, @@ -1099,11 +1228,36 @@ class CustomerHierarchyStore: ) return Page( await customer_budget_usage( - tuple(member_response(row, self.now) for row in rows), self.window_spend, self.now, self.settings + tuple(member_response(row, self.now) for row in rows), + self.window_spend, + self.now, + self.settings, ), count, ) + async def _budget_sort_ids(self, rows: object, sort: BudgetSort, page: int, page_size: int) -> tuple[str, ...]: + candidates: Final = TypeAdapter(tuple[_BudgetSortRow, ...]).validate_python(rows) + references: Final = chain.from_iterable((row.budget_id, row.budget_override_id) for row in candidates) + budgets: Final = { + _ID.validate_python(row.model_dump()["budget_id"]): row.model_dump() + for row in await find_many_in(self.budgets, "budget_id", (ref for ref in references if ref is not None)) + } + + def key(row: _BudgetSortRow) -> tuple[bool, float]: + template: Final = related_budget(budgets.get(row.budget_id or ""), self.now) + override: Final = related_budget( + budgets.get(row.budget_override_id or ""), + self.now, + template.max_budget if template is not None else None, + ) + return _budget_sort_key( + effective_member_budget(template, override, row.budget_override_expires_at, self.now), sort + ) + + ordered: Final = sorted(candidates, key=key) + return tuple(row.entity_id for row in ordered[(page - 1) * page_size : page * page_size]) + async def _delete_unused_budgets(self, budget_ids: Sequence[str]) -> None: where: Final[Mapping[str, object]] = {field: {"none": {}} for field in _BUDGET_REFERENCE_FIELDS} await delete_many_in( @@ -1297,9 +1451,9 @@ class CustomerHierarchy: return await self.transaction(lambda store: store.list_organizations(page, page_size, search)) async def list_teams( - self, parent_org_id: str | None = None, page: int = 1, page_size: int = 50 + self, parent_org_id: str | None = None, page: int = 1, page_size: int = 50, sort: BudgetSort | None = None ) -> Page[Team] | Failure: - return await self.transaction(lambda store: store.list_teams(parent_org_id, page, page_size)) + return await self.transaction(lambda store: store.list_teams(parent_org_id, page, page_size, sort)) async def list_members( self, @@ -1309,10 +1463,11 @@ class CustomerHierarchy: *, parent_org_id: str | None = None, search: str = "", + sort: BudgetSort | None = None, ) -> Page[CustomerMember] | Failure: return await self.transaction( lambda store: store.list_members( - parent_team_id, page, page_size, parent_org_id=parent_org_id, search=search + parent_team_id, page, page_size, parent_org_id=parent_org_id, search=search, sort=sort ) ) diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetColumn.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetColumn.tsx new file mode 100644 index 00000000000..b388b14f139 --- /dev/null +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerBudgetColumn.tsx @@ -0,0 +1,35 @@ +import { ArrowDown, ArrowUp, ArrowUpDown } from "lucide-react"; +import { useTranslation } from "react-i18next"; +import { formatUsd } from "@/app/(dashboard)/usage/_components/components/overview/overviewData"; +import { Button } from "@/components/ui/button"; +import { TableCell, TableHead } from "@/components/ui/table"; + +export function CustomerBudgetSortHeader({ + sort, + onSort, +}: { + sort: "budget_asc" | "budget_desc" | null; + onSort: () => void; +}) { + const { t } = useTranslation(); + const SortIcon = sort === "budget_desc" ? ArrowDown : ArrowUp; + const Icon = sort ? SortIcon : ArrowUpDown; + const direction = sort === "budget_desc" ? "descending" : "ascending"; + return ( + + + + ); +} + +export function CustomerBudgetLimitCell({ limit }: { limit: number | null }) { + const { t } = useTranslation(); + return ( + + {limit === null ? t("customerPortal.analytics.noLimit") : formatUsd(limit)} + + ); +} 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 d76cffe64e7..8a642f39de5 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 @@ -27,6 +27,8 @@ import CreateCustomerHierarchyDialog from "./CreateCustomerHierarchyDialog"; import { customerEntityId, customerEntityLabel, type CreatedCustomerHierarchyEntity } from "./customerHierarchyForms"; import useCustomerHierarchy, { type CustomerHierarchyContext } from "./useCustomerHierarchy"; import type { CustomerHierarchyScope } from "./customerHierarchyApi"; +import { customerBudgetLimit } from "./customerBudgetUsage"; +import { CustomerBudgetLimitCell, CustomerBudgetSortHeader } from "./CustomerBudgetColumn"; type Hierarchy = ReturnType; const CHILD_HINTS = { @@ -230,6 +232,7 @@ function HierarchyChildRows(props: ScopeProps & { childLabel: string; showTeam: {t("customerPortal.hierarchy.name")} {showTeam && {t("customerPortal.hierarchy.team")}} + {t("customerPortal.hierarchy.settings")} @@ -269,6 +272,7 @@ function HierarchyChildRows(props: ScopeProps & { childLabel: string; showTeam: )} )} +
- + {t(childTab === "teams" ? "customerPortal.hierarchy.emptyTeams" : emptyMembers)} diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerMemberSpend.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerMemberSpend.tsx index 0d87b4dc646..fe8c83dc8bd 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerMemberSpend.tsx +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerMemberSpend.tsx @@ -9,8 +9,14 @@ import { Input } from "@/components/ui/input"; import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"; import type { CustomerHierarchyUsage } from "./customerUsageApi"; import { CustomerSpendCells, CustomerSpendHeaders, CustomerSpendIdentity } from "./CustomerSpendCells"; +import { compareCustomerBudgets, customerBudgetLimit, customerBudgetSortParser } from "./customerBudgetUsage"; +import { CustomerBudgetLimitCell, CustomerBudgetSortHeader } from "./CustomerBudgetColumn"; -const MEMBER_TABLE_PARSERS = { memberSearch: parseAsString.withDefault(""), memberPage: parseAsInteger.withDefault(1) }; +const MEMBER_TABLE_PARSERS = { + memberSearch: parseAsString.withDefault(""), + memberPage: parseAsInteger.withDefault(1), + budgetSort: customerBudgetSortParser, +}; const PAGE_SIZE = 20; export default function CustomerMemberSpend({ data, @@ -32,8 +38,12 @@ export default function CustomerMemberSpend({ data.memberBudgets .filter((member) => member.label.toLocaleLowerCase().includes(search.toLocaleLowerCase())) .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], + .sort((a, b) => + table.budgetSort + ? compareCustomerBudgets(a, b, table.budgetSort === "budget_desc") + : (b.monthlyUsage?.spend ?? 0) - (a.monthlyUsage?.spend ?? 0) || a.label.localeCompare(b.label), + ), + [data.memberBudgets, search, usage, table.budgetSort], ); const lastPage = Math.max(1, Math.ceil(members.length / PAGE_SIZE)); @@ -62,6 +72,15 @@ export default function CustomerMemberSpend({ {t("customerPortal.analytics.member")} + + void setTable( + { budgetSort: table.budgetSort === "budget_asc" ? "budget_desc" : "budget_asc", memberPage: null }, + { history: "push" }, + ) + } + /> @@ -77,11 +96,12 @@ export default function CustomerMemberSpend({ tokens={member.monthlyUsage?.tokens ?? 0} organizationSpend={data.monthlyOrganizationSpend} /> + ))} {members.length === 0 && ( - + {t(search ? "customerPortal.analytics.noMatches" : "customerPortal.analytics.noMembers")} diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerOrganizationsTable.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerOrganizationsTable.tsx index 16ef69f5fb7..825d97c04ec 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerOrganizationsTable.tsx +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/CustomerOrganizationsTable.tsx @@ -8,12 +8,14 @@ import { cn } from "@/lib/cva.config"; import { uiHref } from "@/utils/uiHref"; import CustomerBudgetSpend, { CustomerBudgetWindow } from "./CustomerBudgetSpend"; import type { CustomerOrganizationRow } from "./customerOrganizations"; +import { CustomerBudgetLimitCell } from "./CustomerBudgetColumn"; const usageHref = createSerializer({ org: parseAsString, from: parseAsString, to: parseAsString }); const SORT_DIRECTIONS = ["ascending", "descending"] as const; const COLUMNS = [ { id: "customer", label: "customerPortal.list.columns.customer" }, { id: "spend", label: "customerPortal.analytics.monthlySpend" }, + { id: "budget", label: "customerPortal.hierarchy.maxBudget" }, { id: "share", label: "customerPortal.list.columns.overallSpendShare" }, { id: "status", label: "customerPortal.list.columns.status" }, ] as const; @@ -56,7 +58,7 @@ export default function CustomerOrganizationsTable({ variant="ghost" size="sm" className="-mx-2 gap-2" - onClick={() => onSort([{ id, desc: active ? !descending : id !== "customer" }])} + onClick={() => onSort([{ id, desc: active ? !descending : id !== "customer" && id !== "budget" }])} > {t(label)}
+
{ + it.each([false, true])("keeps tied member budgets stable and no budget last, descending %s", (desc) => { + const members = [ + { ...entity, id: "none", budgetLimit: null, budgetLimits: [] }, + { ...entity, id: "twenty", budgetLimit: 20, budgetLimits: [] }, + { ...entity, id: "first", budgetLimit: 7, budgetLimits: [] }, + { ...entity, id: "second", budgetLimit: 7, budgetLimits: [] }, + ]; + const expected = desc ? ["twenty", "first", "second", "none"] : ["first", "second", "twenty", "none"]; + expect([...members].sort((a, b) => compareCustomerBudgets(a, b, desc)).map((member) => member.id)).toEqual( + expected, + ); + }); + + it.each<[number | null, CustomerUsageEntity["budgetLimits"], number | null]>([ + [50, [{ budget_duration: "1mo", max_budget: 7 }], 7], + [50, [{ budget_duration: "1mo", max_budget: 0 }], 0], + [20, [{ budget_duration: "12mo", max_budget: 100 }], 20], + [0, [{ budget_duration: "12mo", max_budget: 100 }], 0], + [null, [{ budget_duration: "12mo", max_budget: 100 }], 100], + [null, [], null], + ])("selects the displayed budget limit over scalar %s and windows %j", (budgetLimit, budgetLimits, expected) => { + const row = { ...entity, budgetLimit, budgetLimits }; + expect(customerBudgetLimit(row)).toBe(expected); + }); + 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 }, 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 index c651a75454e..22e8f1e5024 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerBudgetUsage.ts +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerBudgetUsage.ts @@ -1,8 +1,10 @@ import type { components } from "@/lib/http/schema"; +import { parseAsStringLiteral } from "nuqs"; import type { CustomerUsageEntity } from "./customerUsageApi"; export type CustomerBudgetUsage = components["schemas"]["CustomerBudgetUsage"]; export type CustomerBudgetPeriod = "monthly" | "yearly" | "other"; +export const customerBudgetSortParser = parseAsStringLiteral(["budget_asc", "budget_desc"] as const); export const CUSTOMER_BUDGET_LABELS = { monthly: "customerPortal.analytics.monthlySpend", @@ -39,6 +41,21 @@ export const customerBudgetUsage = (entity: CustomerUsageEntity): CustomerBudget })), ]; +export const customerBudgetLimit = (entity: CustomerUsageEntity): number | null => + entity.budgetLimits.find((limit) => customerBudgetPeriod(limit.budget_duration) === "monthly")?.max_budget ?? + entity.budgetLimit ?? + entity.budgetLimits.find((limit) => customerBudgetPeriod(limit.budget_duration) === "yearly")?.max_budget ?? + null; + +export const compareCustomerBudgets = (left: CustomerUsageEntity, right: CustomerUsageEntity, descending: boolean) => { + const a = customerBudgetLimit(left); + const b = customerBudgetLimit(right); + if (a === null && b === null) return 0; + if (a === null) return 1; + if (b === null) return -1; + return (a - b) * (descending ? -1 : 1); +}; + export const customerBudgetStatus = (usage: CustomerBudgetUsage[]) => { if (usage.some((budget) => budget.spend !== null && budget.spend >= budget.max_budget)) return "customerPortal.analytics.reachedLimit" as const; diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerOrganizations.test.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerOrganizations.test.ts index 60f8a914734..a997249a02c 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerOrganizations.test.ts +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerOrganizations.test.ts @@ -138,6 +138,25 @@ describe("complete customer organization usage", () => { }); describe("customer organization sorting and budgets", () => { + it.each([false, true])("sorts by displayed budget with stable ties and uncapped rows last, descending %s", (desc) => { + const organizations = [ + org("none"), + org("twenty", { budget: { max_budget: 20 } }), + org("z-first-tie", { budget: { max_budget: 7 } }), + org("a-second-tie", { budget: { max_budget: 90, budget_limits: [{ budget_duration: "1mo", max_budget: 7 }] } }), + org("annual", { budget: { budget_limits: [{ budget_duration: "12mo", max_budget: 100 }] } }), + org("zero", { budget: { max_budget: 0 } }), + ]; + const rows = customerOrganizationRows(organizations, mergeCustomerActivityPages([])); + const expected = desc + ? ["annual", "twenty", "z-first-tie", "a-second-tie", "zero", "none"] + : ["zero", "z-first-tie", "a-second-tie", "twenty", "annual", "none"]; + expect( + sortCustomerOrganizations(rows, "", [{ id: "budget", desc }]).map((row) => row.organization.customer_org_id), + ).toEqual(expected); + expect(sortCustomerOrganizations(rows, "absent", [{ id: "budget", desc }])).toEqual([]); + }); + it("sorts the full list before pagination with newest customers first by default", () => { const organizations = Array.from({ length: 30 }, (_, index) => org(`org-${String(index).padStart(2, "0")}`, { diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerOrganizations.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerOrganizations.ts index 387c32f9e0f..34f0ce72047 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerOrganizations.ts +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/customerOrganizations.ts @@ -3,7 +3,12 @@ import { apiClient } from "@/components/networking"; import type { DailyActivityAggregatedResponse } from "@/components/UsagePage/dailyActivityApi"; import type { components } from "@/lib/http/schema"; import i18n from "@/i18n/i18n"; -import { customerBudgetPeriod, customerBudgetStatus, customerBudgetUsage } from "./customerBudgetUsage"; +import { + customerBudgetLimit, + customerBudgetPeriod, + customerBudgetStatus, + customerBudgetUsage, +} from "./customerBudgetUsage"; import { mergeCustomerActivityPages } from "./customerUsageData"; import { customerUsageTotals } from "./customerUsageTotals"; @@ -12,7 +17,7 @@ type OrganizationList = components["schemas"]["ListResponse_Organization_"]; type Activity = ReturnType; export const CUSTOMER_ORGANIZATION_TABLE = { - sortFields: ["created_at", "customer", "spend", "share", "status"], + sortFields: ["created_at", "customer", "spend", "budget", "share", "status"], defaultSort: { id: "created_at", desc: true }, defaultPageSize: 25, filterColumns: [], @@ -99,6 +104,7 @@ export const customerOrganizationRows = (organizations: readonly CustomerOrganiz organization, monthlySpend, monthlyBudgets, + budgetLimit: customerBudgetLimit(budgetEntity), displaySpend: monthlyBudgets.length > 0 ? monthlyBudgets[0].spend : monthlySpend, share: monthlyUsage.metadata.total_spend > 0 ? monthlySpend / monthlyUsage.metadata.total_spend : 0, status: customerBudgetStatus(budgets), @@ -123,6 +129,8 @@ const sortValue = (row: CustomerOrganizationRow, field: string): string | number return row.displaySpend; case "share": return row.share; + case "budget": + return row.budgetLimit; case "status": return STATUS_ORDER[row.status]; default: @@ -152,7 +160,9 @@ export function sortCustomerOrganizations( const comparison = typeof a === "string" && typeof b === "string" ? a.localeCompare(b) : Number(a) - Number(b); return ( comparison * (active.desc ? -1 : 1) || - left.organization.customer_org_id.localeCompare(right.organization.customer_org_id) + (active.id === "budget" + ? 0 + : left.organization.customer_org_id.localeCompare(right.organization.customer_org_id)) ); }); } diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/useCustomerHierarchy.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/useCustomerHierarchy.ts index eaa034ad00d..9df9671e61c 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/useCustomerHierarchy.ts +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/customers/_components/useCustomerHierarchy.ts @@ -9,6 +9,7 @@ import type { components } from "@/lib/http/schema"; import { resolveCustomerHierarchy, type CustomerHierarchyScope } from "./customerHierarchyApi"; import { customerChildSpendCall, customerUsageEntity } from "./customerUsageApi"; import { calendarDate, customerPresetRange } from "./customerUsageRange"; +import { customerBudgetSortParser } from "./customerBudgetUsage"; import type { CreatedCustomerHierarchyEntity, CustomerHierarchyEntity, @@ -24,6 +25,7 @@ const MANAGE_PARSERS = { tab: parseAsStringLiteral(["teams", "members", "budget_groups", "settings"] as const), hierarchyPage: parseAsInteger.withDefault(1), memberSearch: parseAsString.withDefault(""), + budgetSort: customerBudgetSortParser, }; export interface CustomerHierarchyContext { @@ -57,14 +59,14 @@ export async function customerHierarchyContext( async function customerHierarchyChildren( context: CustomerHierarchyContext, kind: ChildList["kind"], - { page, search }: { page: number; search: string }, + { page, search, sort }: { page: number; search: string; sort: "budget_asc" | "budget_desc" | null }, signal?: AbortSignal, ): Promise { if (kind === "members") { const parent = context.team ? { parent_team_id: context.team.customer_team_id } : { parent_org_id: context.organization.customer_org_id }; - const query = { ...parent, page, page_size: 20, ...(search ? { search } : {}) }; + const query = { ...parent, page, page_size: 20, ...(search ? { search } : {}), ...(sort ? { sort } : {}) }; const response = await fetchClient.GET("/management/v1/customer_members", { params: { query }, signal, @@ -79,7 +81,9 @@ async function customerHierarchyChildren( return { kind: "members", ...response.data }; } const response = await fetchClient.GET("/management/v1/customer_teams", { - params: { query: { parent_org_id: context.organization.customer_org_id, page, page_size: 20 } }, + params: { + query: { parent_org_id: context.organization.customer_org_id, page, page_size: 20, ...(sort ? { sort } : {}) }, + }, signal, }); if ( @@ -194,10 +198,17 @@ export default function useCustomerHierarchy() { selected?.team?.customer_team_id, page, memberSearch, + params.budgetSort, ], queryFn: enabled && childContext && showChildren - ? ({ signal }) => customerHierarchyChildren(childContext, childTab, { page, search: memberSearch }, signal) + ? ({ signal }) => + customerHierarchyChildren( + childContext, + childTab, + { page, search: memberSearch, sort: params.budgetSort }, + signal, + ) : skipToken, }); const childUsage = useChildSpend(children.data, scope, accessToken, enabled && showChildren); @@ -264,6 +275,7 @@ export default function useCustomerHierarchy() { childTab, page, memberSearch, + budgetSort: params.budgetSort, canManage, isLoading, openOrganization, @@ -273,6 +285,11 @@ export default function useCustomerHierarchy() { refresh, organizationSaved, setPage: (hierarchyPage: number) => void setParams({ hierarchyPage }), + toggleBudgetSort: () => + void setParams( + { budgetSort: params.budgetSort === "budget_asc" ? "budget_desc" : "budget_asc", hierarchyPage: null }, + { history: "push" }, + ), setMemberSearch: (search: string) => void setParams({ memberSearch: search || null, hierarchyPage: null }, { history: "push" }), }; 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 52b7dea01d4..9b488508dec 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 @@ -117,6 +117,29 @@ function BrowserNavigationProbe() { } describe("customer hierarchy management", () => { + it.each(["teams", "members"])( + "requests %s budget sorting before pagination and stores it in the URL", + async (kind) => { + const onUrlUpdate = vi.fn(); + const options = { searchParams: `?org=org-1&tab=${kind}&hierarchyPage=2&source=portal`, onUrlUpdate }; + renderWithProviders(, options); + await screen.findByRole("button", { name: kind === "teams" ? "Operations" : "Member Two" }, { timeout: 10_000 }); + const table = screen.getByRole("table", { name: kind === "teams" ? "Customer teams" : "Customer members" }); + const sort = within(table).getByRole("button", { name: "Spend limit (USD)" }); + fireEvent.click(sort); + await waitFor(() => + expect(onUrlUpdate).toHaveBeenLastCalledWith( + expect.objectContaining({ queryString: `?org=org-1&tab=${kind}&source=portal&budgetSort=budget_asc` }), + ), + ); + const listRequests = () => requestedUrls().filter((url) => url.pathname === `/management/v1/customer_${kind}`); + await waitFor(() => expect(listRequests().at(-1)?.searchParams.get("sort")).toBe("budget_asc")); + expect(listRequests().at(-1)?.searchParams.get("page")).toBe("1"); + fireEvent.click(within(screen.getByRole("table")).getByRole("button", { name: "Spend limit (USD)" })); + await waitFor(() => expect(listRequests().at(-1)?.searchParams.get("sort")).toBe("budget_desc")); + }, + ); + it.each(["", "Member One"])( "moves a member through its row menu with search %j without editing budgets", async (search) => { diff --git a/litellm/ui/litellm-dashboard/src/lib/http/schema.d.ts b/litellm/ui/litellm-dashboard/src/lib/http/schema.d.ts index 0f105311a7c..d9f86e32438 100644 --- a/litellm/ui/litellm-dashboard/src/lib/http/schema.d.ts +++ b/litellm/ui/litellm-dashboard/src/lib/http/schema.d.ts @@ -68946,6 +68946,8 @@ export interface operations { parent_org_id?: string | null; /** @description Case-insensitive substring of the customer member ID or alias */ search?: string; + /** @description Sort by displayed budget limit, with uncapped rows last. */ + sort?: ("budget_asc" | "budget_desc") | null; }; header?: never; path?: never; @@ -69610,6 +69612,8 @@ export interface operations { page?: number; page_size?: number; parent_org_id?: string | null; + /** @description Sort by displayed budget limit, with uncapped rows last. */ + sort?: ("budget_asc" | "budget_desc") | null; }; header?: never; path?: never; diff --git a/tests/unit/proxy/management_endpoints/management_v1/test_customers.py b/tests/unit/proxy/management_endpoints/management_v1/test_customers.py index 5051315e3ff..110b11ef1b3 100644 --- a/tests/unit/proxy/management_endpoints/management_v1/test_customers.py +++ b/tests/unit/proxy/management_endpoints/management_v1/test_customers.py @@ -978,7 +978,8 @@ def test_organization_list_counts_all_members_and_searches_before_paginating() - assert literal.json()["meta"]["total_count"] == 1 -def test_member_list_searches_id_and_alias_within_its_parent_before_paginating() -> None: +@pytest.mark.parametrize("sort", (None, "budget_asc", "budget_desc")) +def test_member_list_searches_id_and_alias_within_its_parent_before_paginating(sort: str | None) -> None: http: Final = client() family(http) parents: Final = ( @@ -1014,7 +1015,9 @@ def test_member_list_searches_id_and_alias_within_its_parent_before_paginating() assert created.status_code == 201, created.text def found(params: Mapping[str, str | int]) -> tuple[tuple[str, ...], int]: - response: Final = http.get("/management/v1/customer_members", params=params) + response: Final = http.get( + "/management/v1/customer_members", params={**params, **({"sort": sort} if sort is not None else {})} + ) assert response.status_code == 200, response.text ids: Final = tuple(row["customer_member_id"] for row in response.json()["data"]) return ids, response.json()["meta"]["total_count"] @@ -1029,6 +1032,82 @@ def test_member_list_searches_id_and_alias_within_its_parent_before_paginating() assert found({"parent_team_id": "team", "search": "nobody"}) == ((), 0) +@pytest.mark.parametrize("collection", ("customer_teams", "customer_members")) +@pytest.mark.parametrize("sort", ("budget_asc", "budget_desc")) +def test_list_sorts_effective_budget_before_pagination_with_uncapped_last(collection: str, sort: str) -> None: + database: Final = Database(hydration_limit=2) + http: Final = client(database=database) + org: Final = http.post("/management/v1/customer_organizations", json={"customer_org_id": "sort-org"}) + assert org.status_code == 201, org.text + parent: Final = http.post( + "/management/v1/customer_teams", json={"customer_team_id": "parent", "parent_org_id": "sort-org"} + ) + assert parent.status_code == 201, parent.text + budgets: Final = ( + ("empty", {}), + ("expensive", {"max_budget": 20}), + ("cheap", {"max_budget": 80, "budget_limits": [{"budget_duration": "1mo", "max_budget": 7}]}), + ("same", {"max_budget": 7}), + ("annual", {"budget_limits": [{"budget_duration": "12mo", "max_budget": 100}]}), + ("zero", {"max_budget": 0}), + ) + id_field: Final = "customer_team_id" if collection == "customer_teams" else "customer_member_id" + for identifier, budget in budgets: + ownership: Final = ( + {"parent_org_id": "sort-org", "budget_override": budget} + if collection == "customer_teams" + else {"parent_team_ids": ["parent"], "budget_override": budget} + ) + created: Final = http.post(f"/management/v1/{collection}", json={id_field: identifier, **ownership}) + assert created.status_code == 201, created.text + scope: Final = {"parent_org_id": "sort-org"} if collection == "customer_teams" else {"parent_team_id": "parent"} + budget_order: Final = ( + ("zero", "cheap", "same", "expensive", "annual", "empty") + if sort == "budget_asc" + else ("annual", "expensive", "cheap", "same", "zero", "empty") + ) + expected: Final = (*budget_order, "parent") if collection == "customer_teams" else budget_order + for page in range(1, (len(expected) + 1) // 2 + 1): + response: Final = http.get( + f"/management/v1/{collection}", params={**scope, "sort": sort, "page_size": 2, "page": page} + ) + assert response.status_code == 200, response.text + assert tuple(row[id_field] for row in response.json()["data"]) == expected[(page - 1) * 2 : page * 2] + assert response.json()["meta"]["total_count"] == len(expected) + empty: Final = http.get(f"/management/v1/{collection}", params={"parent_org_id": "missing", "sort": sort}) + assert empty.status_code == 200, empty.text + assert empty.json()["data"] == [] + invalid: Final = http.get(f"/management/v1/{collection}", params={"sort": "budget; DROP TABLE budgets"}) + assert invalid.status_code == 422, invalid.text + + +@pytest.mark.parametrize("collection", ("customer_teams", "customer_members")) +def test_budget_sort_uses_inherited_cap_after_override_expiry(collection: str) -> None: + http: Final = client() + family(http) + default_budget: Final = family_default_budget_id(http) + id_field: Final = "customer_team_id" if collection == "customer_teams" else "customer_member_id" + for identifier, cap in (("low", 7), ("expired", 20)): + template: Final = ( + {"budget": {"max_budget": cap}} if collection == "customer_teams" else {"budget_id": default_budget} + ) + parent: Final = {"parent_org_id": "org"} if collection == "customer_teams" else {"parent_team_ids": ["team"]} + overrides: Final = ( + {"budget_override": {"max_budget": 1}, "budget_override_expires_at": (NOW - timedelta(days=1)).isoformat()} + if identifier == "expired" + else {"budget_override": {"max_budget": 7}} + ) + created: Final = http.post( + f"/management/v1/{collection}", json={id_field: identifier, **template, **parent, **overrides} + ) + assert created.status_code == 201, created.text + response: Final = http.get( + f"/management/v1/{collection}", params={"parent_org_id": "org", "sort": "budget_asc", "page_size": 1} + ) + assert response.status_code == 200, response.text + assert tuple(row[id_field] for row in response.json()["data"]) == ("low",) + + def created_member(http: TestClient, member_id: str, team_id: str, *, override: bool = False) -> CustomerMember: response: Final = http.post( "/management/v1/customer_members", @@ -1988,6 +2067,7 @@ def test_list_and_detail_expose_each_effective_budget_with_its_own_recorded_spen 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)] + def test_member_team_replacement_retains_identity_budgets_and_spend() -> None: database: Final = Database() cache: Final = UserApiKeyCache() diff --git a/tests/unit/proxy/management_helpers/test_customer_hierarchy.py b/tests/unit/proxy/management_helpers/test_customer_hierarchy.py index cb36781e9cb..ff2c2bfc85d 100644 --- a/tests/unit/proxy/management_helpers/test_customer_hierarchy.py +++ b/tests/unit/proxy/management_helpers/test_customer_hierarchy.py @@ -89,11 +89,19 @@ def matches_where(row: Mapping[str, object], where: Mapping[str, object]) -> boo class Table: - def __init__(self, id_field: str, database: "Database", *, create_error: DataError | None = None) -> None: + def __init__( + self, + id_field: str, + database: "Database", + *, + create_error: DataError | None = None, + hydration_limit: int | None = None, + ) -> None: self.id_field = id_field self.database = database self.create_error = create_error self.rows: Mapping[str, Record] = {} + self.hydration_limit = hydration_limit async def include(self, row: Record, include: Mapping[str, object] | None) -> Record: if not include: @@ -190,6 +198,8 @@ class Table: matches, ) selected: Final = ordered[skip : skip + take] if take is not None else ordered[skip:] + if include and self.hydration_limit is not None: + assert len(selected) <= self.hydration_limit return tuple([await self.include(row, include) for row in selected]) async def count(self, where: Mapping[str, object] | None = None) -> int: @@ -279,17 +289,20 @@ class Database: source: "Database | None" = None, *, team_create_error: DataError | None = None, + hydration_limit: int | None = None, ) -> None: self.litellm_customerorganizationtable = ( Table("customer_org_id", self) if source is None else source.litellm_customerorganizationtable ) self.litellm_customerteamtable = ( - Table("customer_team_id", self, create_error=team_create_error) + Table("customer_team_id", self, create_error=team_create_error, hydration_limit=hydration_limit) if source is None else source.litellm_customerteamtable ) self.litellm_customermembertable = ( - Table("customer_member_id", self) if source is None else source.litellm_customermembertable + Table("customer_member_id", self, hydration_limit=hydration_limit) + if source is None + else source.litellm_customermembertable ) self.litellm_budgettable = Table("budget_id", self) if source is None else source.litellm_budgettable self.litellm_budgetwindowspend = ( @@ -330,7 +343,58 @@ class Database: self.held_locks = (*self.held_locks, lock) return () + def budget_sort_rows(self, query: str, args: Sequence[object]) -> Sequence[Mapping[str, object]]: + table: Final = ( + self.litellm_customerteamtable + if '"LiteLLM_CustomerTeamTable"' in query + else self.litellm_customermembertable + ) + fields: Final = ( + table.id_field, + "parent_org_id", + "alias", + "created_at", + "budget_id", + "budget_override_id", + "budget_override_expires_at", + "parent_team_ids", + ) + with sqlite3.connect(":memory:") as connection: + connection.row_factory = sqlite3.Row + name: Final = ( + "LiteLLM_CustomerTeamTable" + if table is self.litellm_customerteamtable + else "LiteLLM_CustomerMemberTable" + ) + connection.execute(f'CREATE TABLE "{name}" ({", ".join(fields)})') + connection.executemany( + f'INSERT INTO "{name}" VALUES ({", ".join("?" for _ in fields)})', + tuple( + tuple( + json.dumps(row.model_dump().get(field)) + if field == "parent_team_ids" + else None + if row.model_dump().get(field) is None + else str(row.model_dump()[field]) + for field in fields + ) + for row in table.rows.values() + ), + ) + sql: Final = ( + query.replace( + "parent_team_ids @> ARRAY[$2]::text[]", + "EXISTS (SELECT 1 FROM json_each(parent_team_ids) WHERE value = $2)", + ) + .replace("::text", "") + .replace("ILIKE $3", "LIKE $3 ESCAPE '\\' COLLATE NOCASE") + ) + parameters: Final = {str(index): None if arg is None else str(arg) for index, arg in enumerate(args, 1)} + return tuple(dict(row) for row in connection.execute(sql, parameters)) + async def query_raw(self, query: str, *args: object) -> Sequence[Mapping[str, object]]: + if " AS entity_id" in query: + return self.budget_sort_rows(query, args) if "set_config('lock_timeout'" in query: return () if "pg_advisory_xact_lock" in query: