From f94c79290caae025a02e1955177c1cf4e6ccdd58 Mon Sep 17 00:00:00 2001 From: joshua-berri Date: Mon, 16 Nov 2026 16:00:20 -0800 Subject: [PATCH] feat(ui): show an optional currency estimate on the Usage spend card (#51979) * feat(ui): show the usage spend total in another currency at ECB reference rates Adds GET /get/reference_exchange_rates, which returns the current ECB reference rates as USD per unit for every feed currency. It refreshes at most once a day under a lock, keeps fresh rates when a refresh fails and answers 503 instead of serving rates older than seven days. The usage overview's spend card gets a Spend display selector. It asks for rates only once opened and then shows an estimated amount with the rate date under the unchanged USD total. Every other figure stays in USD. * fix(ui): fall back to USD when spend display rates stop being usable The selector now shows USD whenever no estimate can be shown, so a failed refetch never leaves EUR selected beside a USD-only notice, and an opened selector refreshes its rates hourly. The endpoint gets its HTTP client inside the async fetch so the client belongs to the serving event loop. * fix(proxy): import the ECB rates endpoint HTTP client helper at module level Binds get_async_httpx_client at import so its type is known. The client is still built inside the awaited fetch on the serving event loop. * fix(proxy): fetch display rates with a short-lived handler closed after each refresh Builds an AsyncHTTPHandler inside the refresh fetch and closes it when the fetch ends, and drops the descriptive comment on the spend display component. * chore(ui): regenerate API types for the reference exchange rates endpoint * fix(proxy): use the cached async client factory for display rate refreshes Direct AsyncHTTPHandler construction fails the async client check, so the refresh fetch goes back to get_async_httpx_client, called inside the awaited fetch, with a named type suppression for the factory's untyped params. * fix(ui): tidy spend display helper, hook options and fallback test Groups the rate snapshot into one estimatedSpend argument, names the rates query options, names the missing-estimate condition, and waits for the unavailable notice before asserting the USD fallback. * chore(ui): drop a restating comment on the spend estimate helper * test(proxy): prove concurrent first rate requests share one ECB fetch * fix(proxy): wait a minute before retrying a failed display rate refresh A failed ECB refresh left rates due, so every request after it waited on the lock and fetched again, and N queued callers paid N timeouts during an outage. The endpoint now skips refreshing for 60 seconds after a failed attempt, serving held rates or a 503, and retries on the first request after that. Concurrent waiters share the failed attempt. Also drops the usd_rates docstring. * fix(ui): retry unavailable currency estimates on reopen * refactor(ui): name the currency selector open handler * style(ui): format currency selector props --------- Co-authored-by: Joshua Valluru <326636767+joshua-berri@users.noreply.github.com> --- .../litellm_core_utils/ecb_reference_rates.py | 6 + litellm/proxy/_types.py | 1 + litellm/proxy/proxy_server.py | 4 + .../reference_rates_endpoints.py | 105 ++++++++ .../hooks/referenceRates/useReferenceRates.ts | 28 ++ .../SpendDisplayCurrency.integration.test.tsx | 160 ++++++++++++ .../overview/SpendDisplayCurrency.tsx | 69 +++++ .../components/overview/UsageOverview.tsx | 2 + .../components/overview/spendDisplay.test.ts | 29 +++ .../components/overview/spendDisplay.ts | 20 ++ .../src/i18n/locales/en.json | 8 +- .../src/lib/http/schema.d.ts | 65 +++++ .../test_ecb_reference_rates.py | 19 ++ tests/unit/proxy/auth/test_route_checks.py | 18 ++ .../test_reference_rates_endpoints.py | 242 ++++++++++++++++++ 15 files changed, 775 insertions(+), 1 deletion(-) create mode 100644 litellm/proxy/ui_crud_endpoints/reference_rates_endpoints.py create mode 100644 litellm/ui/litellm-dashboard/src/app/(dashboard)/hooks/referenceRates/useReferenceRates.ts create mode 100644 litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/SpendDisplayCurrency.integration.test.tsx create mode 100644 litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/SpendDisplayCurrency.tsx create mode 100644 litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/spendDisplay.test.ts create mode 100644 litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/spendDisplay.ts create mode 100644 tests/unit/proxy/ui_crud_endpoints/test_reference_rates_endpoints.py diff --git a/litellm/litellm_core_utils/ecb_reference_rates.py b/litellm/litellm_core_utils/ecb_reference_rates.py index 4c75b1a8010..04e8701274d 100644 --- a/litellm/litellm_core_utils/ecb_reference_rates.py +++ b/litellm/litellm_core_utils/ecb_reference_rates.py @@ -237,3 +237,9 @@ class EcbReferenceRates: rate_date=snapshot.rate_date, source="ecb", ) + + def usd_rates(self) -> Mapping[str, UsdRate]: + state: Final = self._state + currencies: Final = () if state is None else tuple(c for c in state.snapshot.units_per_eur if c != "USD") + lookups: Final = tuple(self.usd_per_unit(currency) for currency in currencies) + return MappingProxyType({rate.currency: rate for rate in lookups if isinstance(rate, UsdRate)}) diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py index 90e2ad2009c..73989398186 100644 --- a/litellm/proxy/_types.py +++ b/litellm/proxy/_types.py @@ -631,6 +631,7 @@ class LiteLLMRoutes(enum.Enum): "/sso/get/ui_settings", "/get/user_banner", "/get/latest_release_info", + "/get/reference_exchange_rates", ] # NOTE: ROUTES ONLY FOR MASTER KEY - only the Master Key should be able to Reset Spend diff --git a/litellm/proxy/proxy_server.py b/litellm/proxy/proxy_server.py index df0a92212fc..bfd5f4458bf 100644 --- a/litellm/proxy/proxy_server.py +++ b/litellm/proxy/proxy_server.py @@ -1058,6 +1058,9 @@ from litellm.proxy.ui_crud_endpoints.proxy_setting_endpoints import ( from litellm.proxy.ui_crud_endpoints.proxy_setting_endpoints import ( sync_ui_settings_to_general_settings, ) +from litellm.proxy.ui_crud_endpoints.reference_rates_endpoints import ( + router as reference_rates_endpoints_router, +) from litellm.proxy.ui_crud_endpoints.user_banner_endpoints import ( router as user_banner_endpoints_router, ) @@ -23160,6 +23163,7 @@ app.include_router(ui_crud_endpoints_router) app.include_router(moyai_router) app.include_router(user_banner_endpoints_router) app.include_router(latest_release_endpoints_router) +app.include_router(reference_rates_endpoints_router) app.include_router(team_callback_router) app.include_router(budget_management_router) app.include_router(model_management_router) diff --git a/litellm/proxy/ui_crud_endpoints/reference_rates_endpoints.py b/litellm/proxy/ui_crud_endpoints/reference_rates_endpoints.py new file mode 100644 index 00000000000..dbb2f790ba8 --- /dev/null +++ b/litellm/proxy/ui_crud_endpoints/reference_rates_endpoints.py @@ -0,0 +1,105 @@ +import asyncio +import time +from collections.abc import Awaitable, Callable, Mapping +from datetime import date, datetime, timezone +from typing import Annotated, Final, Literal, TypeAlias + +from fastapi import APIRouter, Depends, HTTPException, status +from pydantic import ConfigDict + +from litellm.litellm_core_utils.ecb_reference_rates import ( + EcbFeedRejected, + EcbFetchFailed, + EcbReferenceRates, + EcbRefreshResult, + fetch_ecb_daily_feed, +) +from litellm.llms.custom_httpx.http_handler import ( + get_async_httpx_client, # pyright: ignore[reportUnknownVariableType] # shared HTTP factory has an untyped params argument +) +from litellm.proxy.auth.user_api_key_auth import user_api_key_auth +from litellm.types.llms.base import LiteLLMBaseModel +from litellm.types.llms.custom_http import httpxSpecialProvider + +router: Final = APIRouter() + +EcbFeedFetch: TypeAlias = Callable[[], Awaitable[bytes | EcbFetchFailed]] +_FAILED_REFRESH_COOLDOWN_SECONDS: Final = 60.0 + + +class _FailedRefreshCooldown: + def __init__(self, monotonic: Callable[[], float] = time.monotonic) -> None: + self._monotonic: Final = monotonic + self._failed_at: float | None = None + + def active(self) -> bool: + failed_at: Final = self._failed_at + return failed_at is not None and self._monotonic() - failed_at < _FAILED_REFRESH_COOLDOWN_SECONDS + + def record(self, result: EcbRefreshResult) -> None: + self._failed_at = self._monotonic() if isinstance(result, EcbFetchFailed | EcbFeedRejected) else None + + +class ReferenceExchangeRates(LiteLLMBaseModel): + model_config = ConfigDict(frozen=True) + + source: Literal["ecb"] + rate_date: date + usd_per_unit: Mapping[str, float] + + +_reference_rates: Final = EcbReferenceRates(clock=lambda: datetime.now(timezone.utc)) +_refresh_lock: Final = asyncio.Lock() +_refresh_cooldown: Final = _FailedRefreshCooldown() + + +def _default_rates() -> EcbReferenceRates: + return _reference_rates + + +def _default_refresh_lock() -> asyncio.Lock: + return _refresh_lock + + +def _default_refresh_cooldown() -> _FailedRefreshCooldown: + return _refresh_cooldown + + +async def _fetch_on_serving_loop() -> bytes | EcbFetchFailed: + return await fetch_ecb_daily_feed(get_async_httpx_client(llm_provider=httpxSpecialProvider.UI)) + + +def _default_fetch() -> EcbFeedFetch: + return _fetch_on_serving_loop + + +@router.get( + "/get/reference_exchange_rates", + tags=["Budget & Spend Tracking"], + dependencies=[Depends(user_api_key_auth)], + response_model=ReferenceExchangeRates, + responses={503: {"description": "No ECB reference rate published in the last 7 days is available"}}, +) +async def reference_exchange_rates( + rates: Annotated[EcbReferenceRates, Depends(_default_rates)], + refresh_lock: Annotated[asyncio.Lock, Depends(_default_refresh_lock)], + fetch: Annotated[EcbFeedFetch, Depends(_default_fetch)], + cooldown: Annotated[_FailedRefreshCooldown, Depends(_default_refresh_cooldown)], +) -> ReferenceExchangeRates: + """ + ECB euro foreign exchange reference rates as USD per unit of each currency, with USD at 1. They estimate a USD + total in another currency for display and are not settlement quotes. Refreshes from the ECB feed when due. + """ + if rates.refresh_due() and not cooldown.active(): + async with refresh_lock: + if rates.refresh_due() and not cooldown.active(): + cooldown.record(await rates.arefresh(fetch)) + usd_rates: Final = rates.usd_rates() + rate_date: Final = next((rate.rate_date for rate in usd_rates.values() if rate.rate_date is not None), None) + if rate_date is None: + raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="ECB reference rates unavailable") + return ReferenceExchangeRates( + source="ecb", + rate_date=rate_date, + usd_per_unit={"USD": 1.0, **{currency: rate.usd_per_unit for currency, rate in usd_rates.items()}}, + ) diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/hooks/referenceRates/useReferenceRates.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/hooks/referenceRates/useReferenceRates.ts new file mode 100644 index 00000000000..196f5bb41ad --- /dev/null +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/hooks/referenceRates/useReferenceRates.ts @@ -0,0 +1,28 @@ +import { useQuery, type UseQueryOptions } from "@tanstack/react-query"; +import { backgroundFetchClient } from "@/lib/http/api"; +import type { components } from "@/lib/http/schema"; +import { createQueryKeys } from "../common/queryKeysFactory"; + +export type ReferenceExchangeRates = components["schemas"]["ReferenceExchangeRates"]; + +export const REFERENCE_RATES_STALE_MS = 60 * 60 * 1000; + +export const referenceRatesKeys = createQueryKeys("referenceRates"); + +export const fetchReferenceRates = async (signal: AbortSignal): Promise => { + const { data } = await backgroundFetchClient.GET("/get/reference_exchange_rates", { signal }); + if (data === undefined) throw new Error("The proxy returned no reference exchange rates"); + return data; +}; + +export const useReferenceRates = (enabled: boolean) => { + const options: UseQueryOptions = { + queryKey: referenceRatesKeys.all, + queryFn: ({ signal }) => fetchReferenceRates(signal), + enabled, + staleTime: REFERENCE_RATES_STALE_MS, + refetchInterval: REFERENCE_RATES_STALE_MS, + retry: false, + }; + return useQuery(options); +}; diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/SpendDisplayCurrency.integration.test.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/SpendDisplayCurrency.integration.test.tsx new file mode 100644 index 00000000000..6f9ba804e90 --- /dev/null +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/SpendDisplayCurrency.integration.test.tsx @@ -0,0 +1,160 @@ +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { act, render, screen, waitFor } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import type { ReactElement } from "react"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { chooseSelectOption } from "@/../tests/test-utils"; +import { referenceRatesKeys } from "@/app/(dashboard)/hooks/referenceRates/useReferenceRates"; +import { registerErrorHandler } from "@/lib/http/runtime"; +import SpendDisplayCurrency from "./SpendDisplayCurrency"; + +const RATES = { source: "ecb", rate_date: "2026-11-13", usd_per_unit: { USD: 1, EUR: 1.25, JPY: 0.01 } }; + +const json = (body: unknown, status = 200) => + new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }); + +const newClient = () => new QueryClient({ defaultOptions: { queries: { retry: false } } }); + +const renderFresh = (ui: ReactElement, client = newClient()) => { + const wrap = (node: ReactElement) => {node}; + const rendered = render(wrap(ui)); + return { ...rendered, client, rerender: (next: ReactElement) => rendered.rerender(wrap(next)) }; +}; + +const trigger = () => screen.getByRole("combobox", { name: "Spend display" }); + +const UNAVAILABLE = "Reference rates are unavailable, spend is shown in USD"; + +beforeEach(() => { + vi.useFakeTimers({ toFake: ["Date"] }); + vi.setSystemTime(new Date("2026-11-14T12:00:00Z")); +}); + +afterEach(() => { + vi.useRealTimers(); + vi.unstubAllGlobals(); + registerErrorHandler(() => {}); +}); + +describe("SpendDisplayCurrency", () => { + it("stays on USD without asking for rates until the selector is opened", () => { + const fetch = vi.fn(); + vi.stubGlobal("fetch", fetch); + + renderFresh(); + + expect(trigger()).toHaveTextContent("USD"); + expect(screen.queryByText(/estimated/)).not.toBeInTheDocument(); + expect(fetch).not.toHaveBeenCalled(); + }); + + it("estimates the current range total in the chosen currency and follows later totals", async () => { + const user = userEvent.setup(); + const fetch = vi.fn().mockResolvedValue(json(RATES)); + vi.stubGlobal("fetch", fetch); + const { rerender } = renderFresh(); + + await chooseSelectOption(user, trigger(), /^EUR/); + expect(await screen.findByText("≈ EUR 34.00 estimated at the ECB reference rate of 2026-11-13")).toBeVisible(); + + rerender(); + expect(screen.getByText("≈ EUR 40.00 estimated at the ECB reference rate of 2026-11-13")).toBeVisible(); + + await chooseSelectOption(user, trigger(), /^JPY/); + expect(screen.getByText("≈ JPY 5,000 estimated at the ECB reference rate of 2026-11-13")).toBeVisible(); + + await chooseSelectOption(user, trigger(), /^USD/); + expect(screen.queryByText(/estimated/)).not.toBeInTheDocument(); + expect(fetch).toHaveBeenCalledTimes(1); + }); + + it("keeps USD with a notice and no dashboard error when rates are unavailable", async () => { + const user = userEvent.setup(); + const onError = vi.fn(); + registerErrorHandler(onError); + vi.stubGlobal("fetch", vi.fn().mockResolvedValue(json({ detail: "ECB reference rates unavailable" }, 503))); + renderFresh(); + + await user.click(trigger()); + + expect(await screen.findByText("Reference rates are unavailable, spend is shown in USD")).toBeVisible(); + expect(screen.getAllByRole("option").map((option) => option.textContent)).toEqual(["USD · US Dollar"]); + expect(onError).not.toHaveBeenCalled(); + }); + + it("falls back to USD when a refetch fails after another currency was chosen", async () => { + const user = userEvent.setup(); + const fetch = vi + .fn() + .mockResolvedValueOnce(json(RATES)) + .mockResolvedValue(json({ detail: "unavailable" }, 503)); + vi.stubGlobal("fetch", fetch); + const { client } = renderFresh(); + await chooseSelectOption(user, trigger(), /^EUR/); + expect(await screen.findByText(/≈ EUR 34\.00 estimated/)).toBeVisible(); + + await act(() => client.invalidateQueries({ queryKey: referenceRatesKeys.all })); + + expect(await screen.findByText("Reference rates are unavailable, spend is shown in USD")).toBeVisible(); + expect(screen.queryByText(/estimated/)).not.toBeInTheDocument(); + expect(trigger()).toHaveTextContent("USD"); + expect(fetch).toHaveBeenCalledTimes(2); + }); + + it("asks for rates again when the selector is reopened after they failed", async () => { + const user = userEvent.setup(); + const fetch = vi + .fn() + .mockResolvedValueOnce(json({ detail: "unavailable" }, 503)) + .mockResolvedValue(json(RATES)); + vi.stubGlobal("fetch", fetch); + renderFresh(); + await user.click(trigger()); + expect(await screen.findByText(UNAVAILABLE)).toBeVisible(); + await user.keyboard("{Escape}"); + + await chooseSelectOption(user, trigger(), /^EUR/); + + expect(await screen.findByText(/≈ EUR 34\.00 estimated/)).toBeVisible(); + expect(screen.queryByText(UNAVAILABLE)).not.toBeInTheDocument(); + expect(fetch).toHaveBeenCalledTimes(2); + }); + + it("keeps a failure cached by another card hidden until this card is opened", async () => { + const user = userEvent.setup(); + const fetch = vi.fn().mockResolvedValue(json({ detail: "unavailable" }, 503)); + vi.stubGlobal("fetch", fetch); + const client = newClient(); + const first = renderFresh(, client); + await user.click(trigger()); + expect(await screen.findByText(UNAVAILABLE)).toBeVisible(); + first.unmount(); + + renderFresh(, client); + + expect(screen.queryByText(UNAVAILABLE)).not.toBeInTheDocument(); + expect(fetch).toHaveBeenCalledTimes(1); + await user.click(trigger()); + expect(await screen.findByText(UNAVAILABLE)).toBeVisible(); + await waitFor(() => expect(fetch).toHaveBeenCalledTimes(2)); + }); + + it("cancels the rate request when the overview goes away before it answers", async () => { + const user = userEvent.setup(); + const requests: Request[] = []; + vi.stubGlobal( + "fetch", + vi.fn((request: Request) => { + requests.push(request); + return new Promise(() => {}); + }), + ); + const { unmount } = renderFresh(); + + await user.click(trigger()); + await waitFor(() => expect(requests).toHaveLength(1)); + unmount(); + + expect(requests[0].signal.aborted).toBe(true); + }); +}); diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/SpendDisplayCurrency.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/SpendDisplayCurrency.tsx new file mode 100644 index 00000000000..d673646d7ef --- /dev/null +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/SpendDisplayCurrency.tsx @@ -0,0 +1,69 @@ +"use client"; + +import { useMemo, useState } from "react"; +import { useTranslation } from "react-i18next"; +import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"; +import { useReferenceRates } from "@/app/(dashboard)/hooks/referenceRates/useReferenceRates"; +import { estimatedSpend } from "./spendDisplay"; + +interface SpendDisplayCurrencyProps { + usdSpend: number; + loading: boolean; +} + +export default function SpendDisplayCurrency({ usdSpend, loading }: SpendDisplayCurrencyProps) { + const { t, i18n } = useTranslation(); + const [requested, setRequested] = useState(false); + const [currency, setCurrency] = useState("USD"); + const rates = useReferenceRates(requested); + const usable = rates.isError ? undefined : rates.data; + const names = useMemo( + () => new Intl.DisplayNames([i18n.language], { type: "currency", fallback: "code" }), + [i18n.language], + ); + const codes = Object.keys(usable?.usd_per_unit ?? { USD: 1 }).sort(); + const estimate = + usable === undefined || currency === "USD" ? null : estimatedSpend(usdSpend, usable, currency, new Date()); + const shown = estimate === null ? "USD" : currency; + const estimateMissing = currency !== "USD" && estimate === null; + const ratesUnusable = rates.isError || (estimateMissing && !rates.isFetching); + const unavailable = requested && ratesUnusable; + const retryable = requested && rates.isError && !rates.isFetching; + const handleOpenChange = (open: boolean) => { + if (!open) return; + if (retryable) void rates.refetch(); + setRequested(true); + }; + return ( +
+
+ {t("usage.statStrip.spendDisplay.label")} + +
+ {estimate !== null && !loading && ( +

+ {t("usage.statStrip.spendDisplay.estimate", { + amount: new Intl.NumberFormat(i18n.language, { + style: "currency", + currency, + currencyDisplay: "code", + }).format(estimate.amount), + date: estimate.rateDate, + })} +

+ )} + {unavailable &&

{t("usage.statStrip.spendDisplay.unavailable")}

} +
+ ); +} diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageOverview.tsx b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageOverview.tsx index ec8bbeb80aa..26fc5f980d3 100644 --- a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageOverview.tsx +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/UsageOverview.tsx @@ -8,6 +8,7 @@ import type { OverviewTotals } from "./overviewData"; import { Panel } from "./Primitives"; import UsageStatStrip from "./UsageStatStrip"; import UsageBreakdownChart from "./UsageBreakdownChart"; +import SpendDisplayCurrency from "./SpendDisplayCurrency"; interface UsageOverviewProps { results: readonly DailyData[]; @@ -45,6 +46,7 @@ export default function UsageOverview({ loading={loading} requestCountsPending={requestCountsPending} budget={budget} + spendDetails={} /> {subscriptionCosts} diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/spendDisplay.test.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/spendDisplay.test.ts new file mode 100644 index 00000000000..1bd42692470 --- /dev/null +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/spendDisplay.test.ts @@ -0,0 +1,29 @@ +import { describe, expect, it } from "vitest"; +import { estimatedSpend } from "./spendDisplay"; + +const USD_PER_UNIT = { USD: 1, EUR: 1.25, JPY: 0.01 }; +const NOW = new Date("2026-11-14T12:00:00Z"); +const ratesOn = (rate_date: string) => ({ usd_per_unit: USD_PER_UNIT, rate_date }); + +describe("estimatedSpend", () => { + it.each([ + [42.5, "EUR", 34], + [0, "EUR", 0], + [-2.5, "EUR", -2], + [42.5, "JPY", 4250], + ])("converts %d USD to %s at the reference rate", (usd, currency, amount) => { + expect(estimatedSpend(usd, ratesOn("2026-11-13"), currency, NOW)).toEqual({ amount, rateDate: "2026-11-13" }); + }); + + it("offers no estimate for a currency the rates do not list", () => { + expect(estimatedSpend(42.5, ratesOn("2026-11-13"), "XYZ", NOW)).toBeNull(); + }); + + it.each([ + ["2026-11-07", true], + ["2026-11-06", false], + ["2026-11-15", false], + ])("uses a rate dated %s only while it is at most seven days old: %s", (rateDate, usable) => { + expect(estimatedSpend(42.5, ratesOn(rateDate), "EUR", NOW) !== null).toBe(usable); + }); +}); diff --git a/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/spendDisplay.ts b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/spendDisplay.ts new file mode 100644 index 00000000000..52313f8c81a --- /dev/null +++ b/litellm/ui/litellm-dashboard/src/app/(dashboard)/usage/_components/components/overview/spendDisplay.ts @@ -0,0 +1,20 @@ +import type { ReferenceExchangeRates } from "@/app/(dashboard)/hooks/referenceRates/useReferenceRates"; + +export const MAX_RATE_AGE_DAYS = 7; + +const DAY_MS = 24 * 60 * 60 * 1000; + +export type SpendEstimate = { readonly amount: number; readonly rateDate: string }; + +export const estimatedSpend = ( + usdSpend: number, + rates: Pick, + currency: string, + now: Date, +): SpendEstimate | null => { + const rate = new Map(Object.entries(rates.usd_per_unit)).get(currency); + const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()); + const ageDays = (today - Date.parse(`${rates.rate_date}T00:00:00Z`)) / DAY_MS; + if (rate === undefined || !(rate > 0) || !(ageDays >= 0 && ageDays <= MAX_RATE_AGE_DAYS)) return null; + return { amount: usdSpend / rate, rateDate: rates.rate_date }; +}; diff --git a/litellm/ui/litellm-dashboard/src/i18n/locales/en.json b/litellm/ui/litellm-dashboard/src/i18n/locales/en.json index 2942e00fea8..6ddfb5c9530 100644 --- a/litellm/ui/litellm-dashboard/src/i18n/locales/en.json +++ b/litellm/ui/litellm-dashboard/src/i18n/locales/en.json @@ -15518,7 +15518,13 @@ }, "avgCostPerRequest": "Avg cost / request", "avgLatency": "Avg latency", - "successRateHint": "{{rate}}% success rate" + "successRateHint": "{{rate}}% success rate", + "spendDisplay": { + "label": "Spend display", + "option": "{{code}} · {{name}}", + "estimate": "≈ {{amount}} estimated at the ECB reference rate of {{date}}", + "unavailable": "Reference rates are unavailable, spend is shown in USD" + } }, "overview": { "topVirtualKeys": "Top Virtual Keys", 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 5acfacd2dfc..402a9c838bc 100644 --- a/litellm/ui/litellm-dashboard/src/lib/http/schema.d.ts +++ b/litellm/ui/litellm-dashboard/src/lib/http/schema.d.ts @@ -6209,6 +6209,27 @@ export interface paths { patch?: never; trace?: never; }; + "/get/reference_exchange_rates": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Reference Exchange Rates + * @description ECB euro foreign exchange reference rates as USD per unit of each currency, with USD at 1. They estimate a USD + * total in another currency for display and are not settlement quotes. Refreshes from the ECB feed when due. + */ + get: operations["reference_exchange_rates_get_reference_exchange_rates_get"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/get/sso_settings": { parameters: { query?: never; @@ -45316,6 +45337,23 @@ export interface components { /** Summary */ summary?: ("auto" | "concise" | "detailed") | null; }; + /** ReferenceExchangeRates */ + ReferenceExchangeRates: { + /** + * Rate Date + * Format: date + */ + rate_date: string; + /** + * Source + * @constant + */ + source: "ecb"; + /** Usd Per Unit */ + usd_per_unit: { + [key: string]: number; + }; + }; /** RegenerateKeyRequest */ RegenerateKeyRequest: { /** Access Group Ids */ @@ -65221,6 +65259,33 @@ export interface operations { }; }; }; + reference_exchange_rates_get_reference_exchange_rates_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ReferenceExchangeRates"]; + }; + }; + /** @description No ECB reference rate published in the last 7 days is available */ + 503: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; get_sso_settings_get_sso_settings_get: { parameters: { query?: never; diff --git a/tests/unit/litellm_core_utils/test_ecb_reference_rates.py b/tests/unit/litellm_core_utils/test_ecb_reference_rates.py index 23cbb698d91..08e5341fafd 100644 --- a/tests/unit/litellm_core_utils/test_ecb_reference_rates.py +++ b/tests/unit/litellm_core_utils/test_ecb_reference_rates.py @@ -424,3 +424,22 @@ async def test_held_rates_survive_a_later_refresh() -> None: assert dict(first.snapshot.units_per_eur) == {"EUR": 1.0, "USD": 1.25, "GBP": 0.5, "JPY": 125.0} with pytest.raises(TypeError): first.snapshot.units_per_eur["GBP"] = 9.0 + + +def test_all_usd_rates_are_empty_without_a_feed() -> None: + assert EcbReferenceRates(clock=_Clock(_at(DAY))).usd_rates() == {} + + +async def test_all_usd_rates_list_every_held_currency_except_usd_until_they_go_stale() -> None: + clock: Final = _Clock(_at(DAY)) + rates: Final = await _rates_holding(_feed(), clock) + + fresh: Final = rates.usd_rates() + clock.now = _at(DAY + timedelta(days=8)) + + assert fresh == { + "EUR": UsdRate(currency="EUR", usd_per_unit=1.25, rate_date=DAY, source="ecb"), + "GBP": HELD_GBP, + "JPY": UsdRate(currency="JPY", usd_per_unit=0.01, rate_date=DAY, source="ecb"), + } + assert rates.usd_rates() == {} diff --git a/tests/unit/proxy/auth/test_route_checks.py b/tests/unit/proxy/auth/test_route_checks.py index 56b7501dd1c..9202702c4f7 100644 --- a/tests/unit/proxy/auth/test_route_checks.py +++ b/tests/unit/proxy/auth/test_route_checks.py @@ -235,6 +235,24 @@ def test_latest_release_info_read_open_to_non_admin_roles(role): # test-quality ) +@pytest.mark.parametrize( + "role", + [ + LitellmUserRoles.INTERNAL_USER.value, + LitellmUserRoles.INTERNAL_USER_VIEW_ONLY.value, + ], +) +def test_reference_exchange_rates_read_open_to_non_admin_roles(role: str) -> None: # test-quality-ok: allowed path returns None, not raising is the observable + RouteChecks.non_proxy_admin_allowed_routes_check( + user_obj=LiteLLM_UserTable(user_id="test_user", user_email="test@example.com", user_role=role), + _user_role=role, + route="/get/reference_exchange_rates", + request=MagicMock(spec=Request), + valid_token=UserAPIKeyAuth(user_id="test_user", user_role=role), + request_data={}, + ) + + def test_user_banner_update_rejected_for_non_admin(): """Publishing the banner stays admin-only at the route layer.""" user_obj = LiteLLM_UserTable( diff --git a/tests/unit/proxy/ui_crud_endpoints/test_reference_rates_endpoints.py b/tests/unit/proxy/ui_crud_endpoints/test_reference_rates_endpoints.py new file mode 100644 index 00000000000..3c55666fc73 --- /dev/null +++ b/tests/unit/proxy/ui_crud_endpoints/test_reference_rates_endpoints.py @@ -0,0 +1,242 @@ +import asyncio +from collections.abc import AsyncIterator +from contextlib import asynccontextmanager +from datetime import datetime, timezone +from typing import Final, Literal + +import httpx +from fastapi import FastAPI + +from litellm.litellm_core_utils.ecb_reference_rates import EcbFetchFailed, EcbReferenceRates +from litellm.proxy._types import UserAPIKeyAuth +from litellm.proxy.auth.user_api_key_auth import user_api_key_auth +from litellm.proxy.ui_crud_endpoints.reference_rates_endpoints import ( + EcbFeedFetch, + _default_fetch, + _default_rates, + _default_refresh_cooldown, + _default_refresh_lock, + _FailedRefreshCooldown, + router, +) + +ROUTE: Final = "/get/reference_exchange_rates" +DEADLOCK_GUARD_SECONDS: Final = 30.0 +FEED: Final = ( + "" + "" + "" +).encode() +RATES_BODY: Final = { + "source": "ecb", + "rate_date": "2026-11-13", + "usd_per_unit": {"USD": 1.0, "EUR": 1.25, "GBP": 2.5, "JPY": 0.01}, +} + + +class _Clock: + def __init__(self, now: datetime) -> None: + self.now = now + + def __call__(self) -> datetime: + return self.now + + +class _Feed: + def __init__(self, *bodies: bytes | EcbFetchFailed) -> None: + self.bodies = bodies + self.fetches = 0 + + async def __call__(self) -> bytes | EcbFetchFailed: + self.fetches += 1 + return self.bodies[self.fetches - 1] + + +class _GatedFeed: + def __init__(self, body: bytes | EcbFetchFailed = FEED) -> None: + self.body = body + self.fetches = 0 + self.entered = asyncio.Event() + self.release = asyncio.Event() + + async def __call__(self) -> bytes | EcbFetchFailed: + self.fetches += 1 + self.entered.set() + await self.release.wait() + return self.body + + +class _WaitSignallingLock(asyncio.Lock): + def __init__(self) -> None: + super().__init__() + self.contended = asyncio.Event() + + async def acquire(self) -> Literal[True]: + if self.locked(): + self.contended.set() + return await super().acquire() + + +class _Seconds: + def __init__(self) -> None: + self.now = 0.0 + + def __call__(self) -> float: + return self.now + + +async def _caller() -> UserAPIKeyAuth: + return UserAPIKeyAuth(api_key="sk-test", user_id="viewer") + + +def _app( + rates: EcbReferenceRates, + feed: EcbFeedFetch, + refresh_lock: asyncio.Lock | None = None, + cooldown: _FailedRefreshCooldown | None = None, +) -> FastAPI: + app: Final = FastAPI() + app.include_router(router) + lock: Final = refresh_lock or asyncio.Lock() + refresh_cooldown: Final = cooldown or _FailedRefreshCooldown() + app.dependency_overrides[_default_refresh_cooldown] = lambda: refresh_cooldown + app.dependency_overrides[user_api_key_auth] = _caller + app.dependency_overrides[_default_rates] = lambda: rates + app.dependency_overrides[_default_refresh_lock] = lambda: lock + app.dependency_overrides[_default_fetch] = lambda: feed + return app + + +@asynccontextmanager +async def _client(app: FastAPI) -> AsyncIterator[httpx.AsyncClient]: + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://proxy") as client: + yield client + + +def _clock() -> _Clock: + return _Clock(datetime(2026, 11, 13, 16, tzinfo=timezone.utc)) + + +async def test_first_request_fetches_and_returns_usd_per_unit_for_every_feed_currency() -> None: + clock: Final = _clock() + feed: Final = _Feed(FEED) + async with _client(_app(EcbReferenceRates(clock=clock), feed)) as client: + first: Final = await client.get(ROUTE) + again: Final = await client.get(ROUTE) + + assert first.status_code == 200, first.text + assert first.json() == RATES_BODY + assert again.json() == RATES_BODY + assert feed.fetches == 1 + + +async def test_failed_refresh_answers_with_the_fresh_held_rates() -> None: + clock: Final = _clock() + feed: Final = _Feed(FEED, EcbFetchFailed("HTTP 503")) + async with _client(_app(EcbReferenceRates(clock=clock), feed)) as client: + assert (await client.get(ROUTE)).status_code == 200 + clock.now = datetime(2026, 11, 14, 16, tzinfo=timezone.utc) + response: Final = await client.get(ROUTE) + + assert response.json() == RATES_BODY + assert feed.fetches == 2 + + +async def test_never_fetched_rates_answer_503() -> None: + clock: Final = _clock() + async with _client(_app(EcbReferenceRates(clock=clock), _Feed(EcbFetchFailed("HTTP 503")))) as client: + response: Final = await client.get(ROUTE) + + assert response.status_code == 503, response.text + + +async def test_stale_rates_with_a_failed_refresh_answer_503_instead_of_stale_rates() -> None: + clock: Final = _clock() + async with _client(_app(EcbReferenceRates(clock=clock), _Feed(FEED, EcbFetchFailed("HTTP 503")))) as client: + assert (await client.get(ROUTE)).status_code == 200 + clock.now = datetime(2026, 11, 21, 16, tzinfo=timezone.utc) + response: Final = await client.get(ROUTE) + + assert response.status_code == 503, response.text + + +async def test_concurrent_first_requests_share_one_fetch() -> None: + feed: Final = _GatedFeed() + lock: Final = _WaitSignallingLock() + async with _client(_app(EcbReferenceRates(clock=_clock()), feed, lock)) as client: + first: Final = asyncio.create_task(client.get(ROUTE)) + second: Final = asyncio.create_task(client.get(ROUTE)) + try: + await asyncio.wait_for(feed.entered.wait(), DEADLOCK_GUARD_SECONDS) + await asyncio.wait_for(lock.contended.wait(), DEADLOCK_GUARD_SECONDS) + feed.release.set() + responses: Final = await asyncio.wait_for(asyncio.gather(first, second), DEADLOCK_GUARD_SECONDS) + finally: + feed.release.set() + first.cancel() + second.cancel() + await asyncio.gather(first, second, return_exceptions=True) + + assert [response.json() for response in responses] == [RATES_BODY, RATES_BODY] + assert feed.fetches == 1 + + +async def test_a_failed_cold_refresh_is_not_retried_until_its_cooldown_ends() -> None: + seconds: Final = _Seconds() + feed: Final = _Feed(EcbFetchFailed("HTTP 503"), FEED) + async with _client( + _app(EcbReferenceRates(clock=_clock()), feed, cooldown=_FailedRefreshCooldown(seconds)) + ) as client: + during_outage: Final = [(await client.get(ROUTE)).status_code for _ in range(3)] + seconds.now = 59.9 + before_cooldown_ends: Final = (await client.get(ROUTE)).status_code + fetches_before: Final = feed.fetches + seconds.now = 60.0 + recovered: Final = await client.get(ROUTE) + + assert during_outage == [503, 503, 503] + assert before_cooldown_ends == 503 + assert fetches_before == 1 + assert recovered.json() == RATES_BODY + assert feed.fetches == 2 + + +async def test_a_failed_refresh_keeps_serving_held_rates_without_refetching_until_its_cooldown_ends() -> None: + clock: Final = _clock() + seconds: Final = _Seconds() + feed: Final = _Feed(FEED, EcbFetchFailed("HTTP 503"), FEED) + async with _client(_app(EcbReferenceRates(clock=clock), feed, cooldown=_FailedRefreshCooldown(seconds))) as client: + assert (await client.get(ROUTE)).status_code == 200 + clock.now = datetime(2026, 11, 14, 16, tzinfo=timezone.utc) + during_outage: Final = [(await client.get(ROUTE)).json() for _ in range(3)] + fetches_during_outage: Final = feed.fetches + seconds.now = 60.0 + recovered: Final = await client.get(ROUTE) + + assert during_outage == [RATES_BODY] * 3 + assert fetches_during_outage == 2 + assert recovered.json() == RATES_BODY + assert feed.fetches == 3 + + +async def test_concurrent_cold_requests_share_one_failed_fetch() -> None: + feed: Final = _GatedFeed(EcbFetchFailed("HTTP 503")) + lock: Final = _WaitSignallingLock() + cooldown: Final = _FailedRefreshCooldown(_Seconds()) + async with _client(_app(EcbReferenceRates(clock=_clock()), feed, lock, cooldown)) as client: + first: Final = asyncio.create_task(client.get(ROUTE)) + second: Final = asyncio.create_task(client.get(ROUTE)) + try: + await asyncio.wait_for(feed.entered.wait(), DEADLOCK_GUARD_SECONDS) + await asyncio.wait_for(lock.contended.wait(), DEADLOCK_GUARD_SECONDS) + feed.release.set() + responses: Final = await asyncio.wait_for(asyncio.gather(first, second), DEADLOCK_GUARD_SECONDS) + finally: + feed.release.set() + first.cancel() + second.cancel() + await asyncio.gather(first, second, return_exceptions=True) + + assert [response.status_code for response in responses] == [503, 503] + assert feed.fetches == 1