Merge d2a649afc4 into 86365263aa

litellm/litellm_core_utils/llm_cost_calc/utils.py

@@ -1,8 +1,9 @@
 # What is this?
 ## Helper utilities for cost_per_token()
 
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
+from datetime import datetime, timezone
 from types import MappingProxyType
 from typing import Any, Final, Literal, TypedDict, cast
 
@@ -276,10 +277,96 @@ def _get_tiered_base_costs(model_info: ModelInfo, usage: Usage) -> tuple[float,
     )
 
 
+def _is_within_off_peak_window(off_peak_hours_utc: str | Sequence[str], current_time: datetime | None = None) -> bool:
+    """Return True if current_time (UTC, defaulting to now) falls inside any off-peak window.
+
+    off_peak_hours_utc is a "HH:MM-HH:MM" string in UTC, or a list of such strings for providers
+    with multiple daily windows (e.g. ["16:30-00:30", "04:00-06:00"]). A window may wrap past
+    midnight, and a window whose start equals its end covers the whole day. The start is
+    inclusive and the end is exclusive; malformed windows are ignored.
+
+    An aware current_time is converted to UTC. A naive one is taken to already be UTC rather
+    than being localised, so callers must pass datetime.now(timezone.utc), never datetime.now(),
+    or every window shifts by the host's offset.
+    """
+    reference: Final = current_time if current_time is not None else datetime.now(timezone.utc)
+    now: Final = (reference.astimezone(timezone.utc) if reference.tzinfo is not None else reference).time()
+    windows: Final = (off_peak_hours_utc,) if isinstance(off_peak_hours_utc, str) else off_peak_hours_utc
+    for window in windows:
+        try:
+            start_str, end_str = window.split("-")
+            start = datetime.strptime(start_str.strip(), "%H:%M").replace(tzinfo=timezone.utc).time()
+            end = datetime.strptime(end_str.strip(), "%H:%M").replace(tzinfo=timezone.utc).time()
+        except (ValueError, AttributeError):
+            continue
+        if start < end:
+            if start <= now < end:
+                return True
+        elif now >= start or now < end:
+            return True
+    return False
+
+
+def _coerce_off_peak_rate(value: object, default: float) -> float:
+    if isinstance(value, bool):
+        return default
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        try:
+            return float(value)
+        except ValueError:
+            return default
+    return default
+
+
+def _apply_off_peak_pricing(
+    model_info: ModelInfo,
+    current_time: datetime | None,
+    prompt_base_cost: float,
+    completion_base_cost: float,
+    cache_read_cost: float,
+) -> tuple[float, float, float]:
+    """Swap in off-peak per-token rates when the current UTC time is inside one of the model's
+    off_peak_pricing windows. An off-peak rate replaces the rate that would otherwise apply
+    rather than discounting it, so a model that also has tiered or above-threshold pricing bills
+    the flat off-peak rate for the whole request while the window is open. Any rate left unset in
+    off_peak_pricing falls back to the standard rate.
+    """
+    off_peak: Final = model_info.get("off_peak_pricing")
+    if not off_peak:
+        return prompt_base_cost, completion_base_cost, cache_read_cost
+    hours_utc: Final = off_peak.get("hours_utc")
+    if not hours_utc or not _is_within_off_peak_window(hours_utc, current_time):
+        return prompt_base_cost, completion_base_cost, cache_read_cost
+    return (
+        _coerce_off_peak_rate(off_peak.get("input_cost_per_token"), prompt_base_cost),
+        _coerce_off_peak_rate(off_peak.get("output_cost_per_token"), completion_base_cost),
+        _coerce_off_peak_rate(off_peak.get("cache_read_input_token_cost"), cache_read_cost),
+    )
+
+
+def _apply_off_peak_to_base_costs(
+    model_info: ModelInfo,
+    current_time: datetime | None,
+    base_costs: tuple[float, float, float, float, float],
+) -> tuple[float, float, float, float, float]:
+    """Apply off-peak rates to an already-resolved set of base costs, whichever pricing path
+    produced them. Cache-creation rates are passed through untouched, since off_peak_pricing
+    has no field for them.
+    """
+    prompt, completion, cache_creation, cache_creation_above_1hr, cache_read = base_costs
+    off_peak_prompt, off_peak_completion, off_peak_cache_read = _apply_off_peak_pricing(
+        model_info, current_time, prompt, completion, cache_read
+    )
+    return (off_peak_prompt, off_peak_completion, cache_creation, cache_creation_above_1hr, off_peak_cache_read)
+
+
 def _get_token_base_cost(
     model_info: ModelInfo,
     usage: Usage,
     service_tier: str | None = None,
+    current_time: datetime | None = None,
     *,
     threshold_is_inclusive: bool = False,
 ) -> tuple[float, float, float, float, float]:
@@ -297,7 +384,7 @@ def _get_token_base_cost(
     """
     tiered_base_costs: Final = _get_tiered_base_costs(model_info=model_info, usage=usage)
     if tiered_base_costs is not None:
-        return tiered_base_costs
+        return _apply_off_peak_to_base_costs(model_info, current_time, tiered_base_costs)
 
     # Get service tier aware cost keys
     input_cost_key: Final = _get_service_tier_cost_key("input_cost_per_token", service_tier)
@@ -331,12 +418,16 @@ def _get_token_base_cost(
         k for k in model_info if k.startswith("input_cost_per_token_above_") and not k.endswith(_SERVICE_TIER_SUFFIXES)
     ]
     if not threshold_keys:
-        return (
-            prompt_base_cost,
-            completion_base_cost,
-            cache_creation_cost,
-            cache_creation_cost_above_1hr,
-            cache_read_cost,
+        return _apply_off_peak_to_base_costs(
+            model_info,
+            current_time,
+            (
+                prompt_base_cost,
+                completion_base_cost,
+                cache_creation_cost,
+                cache_creation_cost_above_1hr,
+                cache_read_cost,
+            ),
         )
 
     # Only sort the threshold keys (typically 1-2 keys instead of 66+)
@@ -437,12 +528,16 @@ def _get_token_base_cost(
             except Exception:
                 continue
 
-    return (
-        prompt_base_cost,
-        completion_base_cost,
-        cache_creation_cost,
-        cache_creation_cost_above_1hr,
-        cache_read_cost,
+    return _apply_off_peak_to_base_costs(
+        model_info,
+        current_time,
+        (
+            prompt_base_cost,
+            completion_base_cost,
+            cache_creation_cost,
+            cache_creation_cost_above_1hr,
+            cache_read_cost,
+        ),
     )
 
 

litellm/types/utils.py

@@ -191,6 +191,19 @@ class AgenticLoopParams(TypedDict, total=False):
     """The LLM provider name (e.g., 'bedrock', 'anthropic')"""
 
 
+class OffPeakPricing(TypedDict, total=False):
+    """Time-windowed off-peak rates for providers that discount by time of day (e.g. DeepSeek).
+
+    hours_utc is a "HH:MM-HH:MM" string in UTC, or a list of them for multiple daily windows;
+    a window may wrap past midnight. Any rate left unset falls back to the standard rate.
+    """
+
+    hours_utc: ReadOnly[str | Sequence[str]]
+    input_cost_per_token: ReadOnly[float]
+    output_cost_per_token: ReadOnly[float]
+    cache_read_input_token_cost: ReadOnly[float]
+
+
 class ModelInfoBase(ProviderSpecificModelInfo, total=False):
     key: Required[str]  # the key in litellm.model_cost which is returned
 
@@ -223,6 +236,7 @@ class ModelInfoBase(ProviderSpecificModelInfo, total=False):
     # Smallest prefix this model will actually cache, whatever caching mechanism its provider uses.
     # Absent means the provider-agnostic default applies; see MINIMUM_PROMPT_CACHE_TOKEN_COUNT.
     prompt_cache_min_tokens: int | None
+    off_peak_pricing: ReadOnly[OffPeakPricing | None]  # time-windowed off-peak rates
     input_cost_per_character: float | None  # only for vertex ai models
     input_cost_per_audio_token: float | None
     input_cost_per_token_above_128k_tokens: float | None  # only for vertex ai models

litellm/utils.py

@@ -5769,6 +5769,7 @@ def _get_model_info_helper(
                 cache_creation_input_token_cost_above_1hr=_model_info.get(
                     "cache_creation_input_token_cost_above_1hr", None
                 ),
+                off_peak_pricing=_model_info.get("off_peak_pricing", None),
                 input_cost_per_character=_model_info.get("input_cost_per_character", None),
                 input_cost_per_token_above_128k_tokens=_model_info.get("input_cost_per_token_above_128k_tokens", None),
                 input_cost_per_token_above_200k_tokens=_model_info.get("input_cost_per_token_above_200k_tokens", None),

tests/test_litellm/litellm_core_utils/llm_cost_calc/test_llm_cost_calc_utils.py

@@ -31,6 +31,7 @@ from litellm.litellm_core_utils.llm_cost_calc.utils import (
     TokenTypeCostBreakdown,
     _calculate_input_cost,
     _get_token_base_cost,
+    _is_within_off_peak_window,
     calculate_cache_writing_cost,
     generic_cost_per_token,
     get_token_type_cost_breakdown,
@@ -408,6 +409,215 @@ def test_get_token_base_cost_picks_highest_crossed_tier():
     assert prompt_base_cost == 9e-6
 
 
+def test_is_within_off_peak_window_same_day():
+    from datetime import datetime, timezone
+
+    window = "09:00-17:00"
+    assert _is_within_off_peak_window(window, datetime(2026, 1, 1, 12, 0, tzinfo=timezone.utc)) is True
+    assert _is_within_off_peak_window(window, datetime(2026, 1, 1, 8, 59, tzinfo=timezone.utc)) is False
+    assert _is_within_off_peak_window(window, datetime(2026, 1, 1, 9, 0, tzinfo=timezone.utc)) is True
+    assert _is_within_off_peak_window(window, datetime(2026, 1, 1, 17, 0, tzinfo=timezone.utc)) is False
+
+
+def test_is_within_off_peak_window_wraps_midnight():
+    from datetime import datetime, timezone
+
+    window = "16:30-00:30"
+    assert _is_within_off_peak_window(window, datetime(2026, 1, 1, 18, 0, tzinfo=timezone.utc)) is True
+    assert _is_within_off_peak_window(window, datetime(2026, 1, 1, 0, 15, tzinfo=timezone.utc)) is True
+    assert _is_within_off_peak_window(window, datetime(2026, 1, 1, 16, 30, tzinfo=timezone.utc)) is True
+    assert _is_within_off_peak_window(window, datetime(2026, 1, 1, 0, 30, tzinfo=timezone.utc)) is False
+    assert _is_within_off_peak_window(window, datetime(2026, 1, 1, 12, 0, tzinfo=timezone.utc)) is False
+
+
+def test_is_within_off_peak_window_equal_start_and_end_covers_whole_day():
+    """An equal start and end is the natural way to spell off-peak all day. It used to take the
+    non-wrap branch, where start <= now < end can never hold, so it matched nothing and billed at
+    standard rates around the clock without raising or logging anything."""
+    from datetime import datetime, timezone
+
+    for window in ("00:00-00:00", "10:00-10:00"):
+        for hour in range(24):
+            assert (
+                _is_within_off_peak_window(window, datetime(2026, 1, 1, hour, 0, tzinfo=timezone.utc)) is True
+            ), f"{window} should cover {hour:02d}:00"
+
+
+def test_is_within_off_peak_window_multiple_windows():
+    from datetime import datetime, timezone
+
+    # Providers like DeepSeek V4 have more than one daily peak/off-peak window.
+    windows = ["01:00-05:00", "13:00-16:00"]
+    assert _is_within_off_peak_window(windows, datetime(2026, 1, 1, 3, 0, tzinfo=timezone.utc)) is True
+    assert _is_within_off_peak_window(windows, datetime(2026, 1, 1, 14, 30, tzinfo=timezone.utc)) is True
+    assert _is_within_off_peak_window(windows, datetime(2026, 1, 1, 9, 0, tzinfo=timezone.utc)) is False
+    # a malformed entry in the list is ignored, valid entries still match
+    assert _is_within_off_peak_window(["bad", "13:00-16:00"], datetime(2026, 1, 1, 14, 0, tzinfo=timezone.utc)) is True
+    assert _is_within_off_peak_window([], datetime(2026, 1, 1, 14, 0, tzinfo=timezone.utc)) is False
+
+
+def test_is_within_off_peak_window_normalizes_timezone_aware_input():
+    from datetime import datetime, timedelta, timezone
+
+    # A caller may pass a non-UTC aware datetime; the window is UTC and must be
+    # evaluated in UTC, not against the caller's wall-clock. 09:00 at UTC+8 is
+    # 01:00 UTC, inside the 01:00-05:00 window.
+    tz_plus_8 = timezone(timedelta(hours=8))
+    assert _is_within_off_peak_window("01:00-05:00", datetime(2026, 1, 1, 9, 0, tzinfo=tz_plus_8)) is True
+    assert _is_within_off_peak_window("01:00-05:00", datetime(2026, 1, 1, 12, 0, tzinfo=tz_plus_8)) is True
+    # 06:00 at UTC+8 is 22:00 UTC the previous day, outside the window
+    assert _is_within_off_peak_window("01:00-05:00", datetime(2026, 1, 1, 6, 0, tzinfo=tz_plus_8)) is False
+
+
+def test_is_within_off_peak_window_malformed_returns_false():
+    from datetime import datetime, timezone
+
+    now = datetime(2026, 1, 1, 18, 0, tzinfo=timezone.utc)
+    assert _is_within_off_peak_window("not-a-window", now) is False
+    assert _is_within_off_peak_window("16:30", now) is False
+    assert _is_within_off_peak_window("25:00-26:00", now) is False
+
+
+def test_get_token_base_cost_applies_off_peak_pricing():
+    from datetime import datetime, timezone
+    from typing import cast
+
+    from litellm.types.utils import ModelInfo
+
+    model_info = cast(
+        ModelInfo,
+        {
+            "input_cost_per_token": 1e-6,
+            "output_cost_per_token": 2e-6,
+            "cache_read_input_token_cost": 1e-7,
+            "off_peak_pricing": {
+                "hours_utc": "16:30-00:30",
+                "input_cost_per_token": 5e-7,
+                "output_cost_per_token": 1e-6,
+                "cache_read_input_token_cost": 5e-8,
+            },
+        },
+    )
+    usage = Usage(prompt_tokens=100, completion_tokens=50, total_tokens=150)
+
+    off_peak = _get_token_base_cost(model_info, usage, current_time=datetime(2026, 1, 1, 18, 0, tzinfo=timezone.utc))
+    assert off_peak[0] == 5e-7
+    assert off_peak[1] == 1e-6
+    assert off_peak[4] == 5e-8
+
+    peak = _get_token_base_cost(model_info, usage, current_time=datetime(2026, 1, 1, 12, 0, tzinfo=timezone.utc))
+    assert peak[0] == 1e-6
+    assert peak[1] == 2e-6
+    assert peak[4] == 1e-7
+
+
+def test_get_token_base_cost_off_peak_falls_back_to_standard_when_unset():
+    from datetime import datetime, timezone
+    from typing import cast
+
+    from litellm.types.utils import ModelInfo
+
+    model_info = cast(
+        ModelInfo,
+        {
+            "input_cost_per_token": 1e-6,
+            "output_cost_per_token": 2e-6,
+            "off_peak_pricing": {"hours_utc": "16:30-00:30", "input_cost_per_token": 5e-7},
+        },
+    )
+    usage = Usage(prompt_tokens=100, completion_tokens=50, total_tokens=150)
+
+    result = _get_token_base_cost(model_info, usage, current_time=datetime(2026, 1, 1, 18, 0, tzinfo=timezone.utc))
+    assert result[0] == 5e-7
+    assert result[1] == 2e-6
+
+
+def test_get_token_base_cost_off_peak_wins_over_threshold():
+    from datetime import datetime, timezone
+    from typing import cast
+
+    from litellm.types.utils import ModelInfo
+
+    model_info = cast(
+        ModelInfo,
+        {
+            "input_cost_per_token": 1e-6,
+            "output_cost_per_token": 2e-6,
+            "input_cost_per_token_above_200k_tokens": 3e-6,
+            "output_cost_per_token_above_200k_tokens": 4e-6,
+            "off_peak_pricing": {
+                "hours_utc": "16:30-00:30",
+                "input_cost_per_token": 5e-7,
+                "output_cost_per_token": 1e-6,
+            },
+        },
+    )
+    usage = Usage(prompt_tokens=250000, completion_tokens=250000, total_tokens=500000)
+
+    off_peak = _get_token_base_cost(model_info, usage, current_time=datetime(2026, 1, 1, 18, 0, tzinfo=timezone.utc))
+    assert off_peak[0] == 5e-7
+    assert off_peak[1] == 1e-6
+
+    peak = _get_token_base_cost(model_info, usage, current_time=datetime(2026, 1, 1, 12, 0, tzinfo=timezone.utc))
+    assert peak[0] == 3e-6
+    assert peak[1] == 4e-6
+
+
+def test_get_model_info_propagates_off_peak_fields():
+    model_name = "test-off-peak-model"
+    off_peak_pricing = {
+        "hours_utc": "16:30-00:30",
+        "input_cost_per_token": 5e-7,
+        "output_cost_per_token": 1e-6,
+        "cache_read_input_token_cost": 5e-8,
+    }
+    litellm.register_model(
+        {
+            model_name: {
+                "litellm_provider": "openai",
+                "mode": "chat",
+                "input_cost_per_token": 1e-6,
+                "output_cost_per_token": 2e-6,
+                "off_peak_pricing": off_peak_pricing,
+            }
+        }
+    )
+    info = litellm.get_model_info(model=model_name)
+    assert info["off_peak_pricing"] == off_peak_pricing
+
+
+def test_get_token_base_cost_off_peak_wins_over_tiered_pricing():
+    """Tiered pricing resolves base rates on its own path and returns early, so off-peak has to
+    be applied there too or a model carrying both would silently bill the tier rate all day."""
+    from datetime import datetime, timezone
+
+    model_name = "litellm-test-off-peak-tiered"
+    litellm.register_model(
+        {
+            model_name: {
+                "litellm_provider": "openai",
+                "mode": "chat",
+                "tiered_pricing": [
+                    {"range": [0, 128000], "input_cost_per_token": 3e-6, "output_cost_per_token": 6e-6},
+                ],
+                "off_peak_pricing": {
+                    "hours_utc": "16:30-00:30",
+                    "input_cost_per_token": 5e-7,
+                    "output_cost_per_token": 1e-6,
+                },
+            }
+        }
+    )
+    info = litellm.get_model_info(model=model_name)
+    usage = Usage(prompt_tokens=1_000, completion_tokens=100, total_tokens=1_100)
+
+    inside = _get_token_base_cost(info, usage, current_time=datetime(2026, 1, 1, 18, 0, tzinfo=timezone.utc))
+    assert inside[:2] == (5e-7, 1e-6)
+
+    outside = _get_token_base_cost(info, usage, current_time=datetime(2026, 1, 1, 12, 0, tzinfo=timezone.utc))
+    assert outside[:2] == (3e-6, 6e-6)
+
+
 def test_generic_cost_per_token_gpt54_above_272k_tokens(_local_model_cost_map):
     """GPT-5.4/5.4-pro: prompts >272K input tokens priced at 2x input, 1.5x output."""
     model = "gpt-5.4"