Exclude '*mini' models from prompt_cache_retention (#1345)

Co-authored-by: openhands <openhands@all-hands.dev>

Author: enyst

openhands-sdk/openhands/sdk/llm/utils/model_features.py

@@ -15,6 +15,28 @@ def model_matches(model: str, patterns: list[str]) -> bool:
     return False
 
 
+def apply_ordered_model_rules(model: str, rules: list[str]) -> bool:
+    """Apply ordered include/exclude model rules to determine final support.
+
+    Rules semantics:
+    - Each entry is a substring token. '!' prefix marks an exclude rule.
+    - Case-insensitive substring matching against the raw model string.
+    - Evaluated in order; the last matching rule wins.
+    - If no rule matches, returns False.
+    """
+    raw = (model or "").strip().lower()
+    decided: bool | None = None
+    for rule in rules:
+        token = rule.strip().lower()
+        if not token:
+            continue
+        is_exclude = token.startswith("!")
+        core = token[1:] if is_exclude else token
+        if core and core in raw:
+            decided = not is_exclude
+    return bool(decided)
+
+
 @dataclass(frozen=True)
 class ModelFeatures:
     supports_reasoning_effort: bool
@@ -27,9 +49,9 @@ class ModelFeatures:
     supports_prompt_cache_retention: bool
 
 
-# Pattern tables capturing current behavior. Keep patterns lowercase.
+# Model lists capturing current behavior. Keep entries lowercase.
 
-REASONING_EFFORT_PATTERNS: list[str] = [
+REASONING_EFFORT_MODELS: list[str] = [
     # Mirror main behavior exactly (no unintended expansion)
     "o1-2024-12-17",
     "o1",
@@ -47,15 +69,15 @@ class ModelFeatures:
     "claude-opus-4-5",
 ]
 
-EXTENDED_THINKING_PATTERNS: list[str] = [
+EXTENDED_THINKING_MODELS: list[str] = [
     # Anthropic model family
     # We did not include sonnet 3.7 and 4 here as they don't brings
     # significant performance improvements for agents
     "claude-sonnet-4-5",
     "claude-haiku-4-5",
 ]
 
-PROMPT_CACHE_PATTERNS: list[str] = [
+PROMPT_CACHE_MODELS: list[str] = [
     "claude-3-7-sonnet",
     "claude-sonnet-3-7-latest",
     "claude-3-5-sonnet",
@@ -70,14 +92,27 @@ class ModelFeatures:
 ]
 
 # Models that support a top-level prompt_cache_retention parameter
-PROMPT_CACHE_RETENTION_PATTERNS: list[str] = [
-    # OpenAI GPT-5+ family
+# Source: OpenAI Prompt Caching docs (extended retention), which list:
+#   - gpt-5.2
+#   - gpt-5.1
+#   - gpt-5.1-codex
+#   - gpt-5.1-codex-mini
+#   - gpt-5.1-chat-latest
+#   - gpt-5
+#   - gpt-5-codex
+#   - gpt-4.1
+# Use ordered include/exclude rules (last wins) to naturally express exceptions.
+PROMPT_CACHE_RETENTION_MODELS: list[str] = [
+    # Broad allow for GPT-5 family and GPT-4.1 (covers gpt-5.2 and variants)
     "gpt-5",
-    # GPT-4.1 too
     "gpt-4.1",
+    # Exclude all mini variants by default
+    "!mini",
+    # Re-allow the explicitly documented supported mini variant
+    "gpt-5.1-codex-mini",
 ]
 
-SUPPORTS_STOP_WORDS_FALSE_PATTERNS: list[str] = [
+SUPPORTS_STOP_WORDS_FALSE_MODELS: list[str] = [
     # o-series families don't support stop words
     "o1",
     "o3",
@@ -89,7 +124,7 @@ class ModelFeatures:
 ]
 
 # Models that should use the OpenAI Responses API path by default
-RESPONSES_API_PATTERNS: list[str] = [
+RESPONSES_API_MODELS: list[str] = [
     # OpenAI GPT-5 family (includes mini variants)
     "gpt-5",
     # OpenAI Codex (uses Responses API)
@@ -101,7 +136,7 @@ class ModelFeatures:
 # and need plain strings instead
 # NOTE: model_matches uses case-insensitive substring matching, not globbing.
 #       Keep these entries as bare substrings without wildcards.
-FORCE_STRING_SERIALIZER_PATTERNS: list[str] = [
+FORCE_STRING_SERIALIZER_MODELS: list[str] = [
     "deepseek",  # e.g., DeepSeek-V3.2-Exp
     "glm",  # e.g., GLM-4.5 / GLM-4.6
     # Kimi K2-Instruct requires string serialization only on Groq
@@ -110,32 +145,31 @@ class ModelFeatures:
 
 # Models that we should send full reasoning content
 # in the message input
-SEND_REASONING_CONTENT_PATTERNS: list[str] = [
+SEND_REASONING_CONTENT_MODELS: list[str] = [
     "kimi-k2-thinking",
 ]
 
 
 def get_features(model: str) -> ModelFeatures:
     """Get model features."""
     return ModelFeatures(
-        supports_reasoning_effort=model_matches(model, REASONING_EFFORT_PATTERNS),
-        supports_extended_thinking=model_matches(model, EXTENDED_THINKING_PATTERNS),
-        supports_prompt_cache=model_matches(model, PROMPT_CACHE_PATTERNS),
-        supports_stop_words=not model_matches(
-            model, SUPPORTS_STOP_WORDS_FALSE_PATTERNS
-        ),
-        supports_responses_api=model_matches(model, RESPONSES_API_PATTERNS),
-        force_string_serializer=model_matches(model, FORCE_STRING_SERIALIZER_PATTERNS),
-        send_reasoning_content=model_matches(model, SEND_REASONING_CONTENT_PATTERNS),
-        supports_prompt_cache_retention=model_matches(
-            model, PROMPT_CACHE_RETENTION_PATTERNS
+        supports_reasoning_effort=model_matches(model, REASONING_EFFORT_MODELS),
+        supports_extended_thinking=model_matches(model, EXTENDED_THINKING_MODELS),
+        supports_prompt_cache=model_matches(model, PROMPT_CACHE_MODELS),
+        supports_stop_words=not model_matches(model, SUPPORTS_STOP_WORDS_FALSE_MODELS),
+        supports_responses_api=model_matches(model, RESPONSES_API_MODELS),
+        force_string_serializer=model_matches(model, FORCE_STRING_SERIALIZER_MODELS),
+        send_reasoning_content=model_matches(model, SEND_REASONING_CONTENT_MODELS),
+        # Extended prompt_cache_retention support follows ordered include/exclude rules.
+        supports_prompt_cache_retention=apply_ordered_model_rules(
+            model, PROMPT_CACHE_RETENTION_MODELS
         ),
     )
 
 
 # Default temperature mapping.
 # Each entry: (pattern, default_temperature)
-DEFAULT_TEMPERATURE_PATTERNS: list[tuple[str, float]] = [
+DEFAULT_TEMPERATURE_MODELS: list[tuple[str, float]] = [
     ("kimi-k2-thinking", 1.0),
 ]
 
@@ -145,7 +179,7 @@ def get_default_temperature(model: str) -> float:
 
     Uses case-insensitive substring matching via model_matches.
     """
-    for pattern, value in DEFAULT_TEMPERATURE_PATTERNS:
+    for pattern, value in DEFAULT_TEMPERATURE_MODELS:
         if model_matches(model, [pattern]):
             return value
     return 0.0

tests/sdk/llm/test_model_features.py

@@ -250,13 +250,19 @@ def test_force_string_serializer_full_model_names():
         ("gpt-5.1", True),
         ("openai/gpt-5.1-codex-mini", True),
         ("gpt-5", True),
-        ("openai/gpt-5-mini", True),
+        # New GPT-5.2 family should support extended retention
+        ("gpt-5.2", True),
+        ("openai/gpt-5.2-chat-latest", True),
+        ("openai/gpt-5.2-pro", True),
+        ("openai/gpt-5-mini", False),
         ("gpt-4o", False),
         ("openai/gpt-4.1", True),
         ("litellm_proxy/gpt-4.1", True),
         ("litellm_proxy/openai/gpt-4.1", True),
         ("litellm_proxy/openai/gpt-5", True),
-        ("litellm_proxy/openai/gpt-5-mini", True),
+        ("litellm_proxy/openai/gpt-5-mini", False),
+        ("openai/gpt-5.1-mini", False),
+        ("openai/gpt-5-mini-2025-08-07", False),
     ],
 )
 def test_prompt_cache_retention_support(model, expected_retention):

tests/sdk/llm/test_responses_parsing_and_kwargs.py

@@ -167,20 +167,52 @@ def test_responses_reasoning_effort_none_not_sent_for_gpt_5_1(model):
 
 
 def test_chat_and_responses_options_prompt_cache_retention_gpt_5_plus_and_non_gpt():
-    # GPT-5+ should include prompt_cache_retention as a top-level arg
-    llm_51 = LLM(model="openai/gpt-5.1-codex-mini")
-    opts_51_chat = select_chat_options(llm_51, {}, has_tools=False)
-    assert opts_51_chat.get("prompt_cache_retention") == "24h"
+    # Confirm allowed: 5.1 codex mini supports extended retention per docs
+    llm_51_codex_mini = LLM(model="openai/gpt-5.1-codex-mini")
+    opts_51_codex_mini_resp = select_responses_options(
+        llm_51_codex_mini, {}, include=None, store=None
+    )
+    assert opts_51_codex_mini_resp.get("prompt_cache_retention") == "24h"
 
-    opts_51_resp = select_responses_options(llm_51, {}, include=None, store=None)
-    assert opts_51_resp.get("prompt_cache_retention") == "24h"
+    # New GPT-5.2 variants should include prompt_cache_retention
+    llm_52 = LLM(model="openai/gpt-5.2")
+    assert (
+        select_chat_options(llm_52, {}, has_tools=False).get("prompt_cache_retention")
+        == "24h"
+    )
+    assert (
+        select_responses_options(llm_52, {}, include=None, store=None).get(
+            "prompt_cache_retention"
+        )
+        == "24h"
+    )
+
+    llm_52_chat_latest = LLM(model="openai/gpt-5.2-chat-latest")
+    assert (
+        select_chat_options(llm_52_chat_latest, {}, has_tools=False).get(
+            "prompt_cache_retention"
+        )
+        == "24h"
+    )
 
-    llm_5 = LLM(model="openai/gpt-5-mini")
-    opts_5_chat = select_chat_options(llm_5, {}, has_tools=False)
-    assert opts_5_chat.get("prompt_cache_retention") == "24h"
+    # GPT-5.1 (non-mini) should include prompt_cache_retention; mini variants should not
+    llm_51_mini = LLM(model="openai/gpt-5.1-mini")
+    opts_51_mini_chat = select_chat_options(llm_51_mini, {}, has_tools=False)
+    assert "prompt_cache_retention" not in opts_51_mini_chat
 
-    opts_5_resp = select_responses_options(llm_5, {}, include=None, store=None)
-    assert opts_5_resp.get("prompt_cache_retention") == "24h"
+    opts_51_mini_resp = select_responses_options(
+        llm_51_mini, {}, include=None, store=None
+    )
+    assert "prompt_cache_retention" not in opts_51_mini_resp
+
+    llm_5_mini = LLM(model="openai/gpt-5-mini")
+    opts_5_mini_chat = select_chat_options(llm_5_mini, {}, has_tools=False)
+    assert "prompt_cache_retention" not in opts_5_mini_chat
+
+    opts_5_mini_resp = select_responses_options(
+        llm_5_mini, {}, include=None, store=None
+    )
+    assert "prompt_cache_retention" not in opts_5_mini_resp
 
     # Non-GPT-5.1 should not include it at all
     llm_other = LLM(model="gpt-4o")