SAP · yamaceay · Sep 10, 2026 · Sep 10, 2026 · Sep 10, 2026 · Sep 10, 2026
@@ -3,6 +3,9 @@
 from .exceptions import OrchestrationError, OrchestrationErrorList
 
 __all__ = [
+    # cache_control
+    "CacheControl",
+
     # azure_content_filter
     "AzureContentFilter", "AzureContentSafetyInput", "AzureContentSafetyOutput", "AzureThreshold",
 
@@ -46,7 +49,7 @@
     "ImageDetailLevel", "TextPart", "ImageUrl", "ImagePart", "ContentPart", "ImageItem",
 
     # response
-    "PromptTokensDetails", "CompletionTokensDetails", "TokenUsage", "GenericModuleResult", "TopLogprob",
+    "CacheCreationTokenDetails", "PromptTokensDetails", "CompletionTokensDetails", "TokenUsage", "GenericModuleResult", "TopLogprob",
     "ChatCompletionTokenLogprob", "ChoiceLogprobs", "LLMChoice", "StreamFunctionObject", "StreamToolCall",
     "StreamDelta", "StreamLLMChoice", "Citation", "LLMModuleResult", "StreamLLMModuleResult", "ModuleResults",
     "StreamModuleResults", "SAPAPIError", "SAPAPIErrorStreaming", "CompletionPostResponse",

@@ -1,4 +1,5 @@
 from .azure_content_filter import AzureContentSafetyInput, AzureContentSafetyOutput, AzureContentFilter, AzureThreshold
+from .cache_control import CacheControl
 from .config import (ModuleConfig, OrchestrationConfig, OrchestrationConfigReference,
                      CompletionRequestConfigurationReferenceByIdConfigRef,
                      CompletionRequestConfigurationReferenceByNameScenarioVersionConfigRef)
@@ -20,7 +21,7 @@
 from .message import (SystemMessage, UserMessage, AssistantMessage, ToolChatMessage, DeveloperChatMessage, ChatMessage,
                      ResponseChatMessage, FunctionCall, MessageToolCall)
 from .multimodal_items import ImageDetailLevel, TextPart, ImageUrl, ImagePart, ContentPart, ImageItem
-from .response import (PromptTokensDetails, CompletionTokensDetails, TokenUsage, GenericModuleResult, TopLogprob,
+from .response import (CacheCreationTokenDetails, PromptTokensDetails, CompletionTokensDetails, TokenUsage, GenericModuleResult, TopLogprob,
                       ChatCompletionTokenLogprob, ChoiceLogprobs, LLMChoice, StreamFunctionObject, StreamToolCall,
                       StreamDelta, StreamLLMChoice, Citation, LLMModuleResult, StreamLLMModuleResult, ModuleResults,
                       StreamModuleResults, SAPAPIError, SAPAPIErrorStreaming, CompletionPostResponse, 
@@ -36,6 +37,9 @@
 
 
 __all__ = [
+    # cache_control
+    "CacheControl",
+
     # azure_content_filter
     "AzureContentFilter", "AzureContentSafetyInput", "AzureContentSafetyOutput", "AzureThreshold",
 
@@ -79,7 +83,7 @@
     "ImageDetailLevel", "TextPart", "ImageUrl", "ImagePart", "ContentPart", "ImageItem",
 
     # response
-    "PromptTokensDetails", "CompletionTokensDetails", "TokenUsage", "GenericModuleResult", "TopLogprob",
+    "CacheCreationTokenDetails", "PromptTokensDetails", "CompletionTokensDetails", "TokenUsage", "GenericModuleResult", "TopLogprob",
     "ChatCompletionTokenLogprob", "ChoiceLogprobs", "LLMChoice", "StreamFunctionObject", "StreamToolCall",
     "StreamDelta", "StreamLLMChoice", "Citation", "LLMModuleResult", "StreamLLMModuleResult", "ModuleResults",
     "StreamModuleResults", "SAPAPIError", "SAPAPIErrorStreaming", "CompletionPostResponse",

@@ -0,0 +1,38 @@
+"""Cache control for prompt caching on supported models."""
+from typing import Any, Dict, Literal, Optional
+
+from pydantic import model_serializer
+
+from gen_ai_hub.orchestration_v2.models.base import ABCBaseModel as BaseModel
+
+
+class CacheControl(BaseModel):
+    """Marks a message content block or tool definition for prompt caching.
+
+    When attached to a content block, the model stores intermediate computation
+    results for that content and reuses them on subsequent requests within the
+    TTL window, reducing both latency and token costs.
+
+    Attach ``CacheControl`` directly to a content block (``TextPart``, ``ImagePart``) or
+    to a ``ChatCompletionTool``.
+
+    Args:
+        type: ``"ephemeral"``
+        ttl: Cache duration. ``"5m"`` (default) or ``"1h"`` (select Anthropic
+             models only). Omit for Amazon Nova or when the default is sufficient.
+    """
+
+    type: Literal["ephemeral"]
+    ttl: Optional[Literal["5m", "1h"]] = None
+
+    @model_serializer(mode="wrap")
+    def serialize_wire_format(self, handler: Any) -> Dict[str, Any]:
+        """Serialize to the wire format, omitting ``ttl`` when not set.
+
+        :return: ``{"type": "ephemeral"}`` or ``{"type": "ephemeral", "ttl": "<value>"}``
+        :rtype: dict
+        """
+        data: Dict[str, Any] = handler(self)
+        if data.get("ttl") is None:
+            data.pop("ttl", None)
+        return data
@@ -12,6 +12,7 @@
 from pydantic.main import IncEx
 
 from gen_ai_hub.orchestration_v2.models.base import ABCBaseModel as BaseModel
+from gen_ai_hub.orchestration_v2.models.cache_control import CacheControl
 
 
 class ImageDetailLevel(Enum):
@@ -38,9 +39,12 @@ class TextPart(BaseModel):
         text: The string content of the text part.
 
         type: The type identifier, defaulting to "text".
+
+        cache_control: Optional cache control settings for prompt caching.
     """
     text: str
     type_: Literal["text"] = Field(default="text", alias="type")
+    cache_control: Optional[CacheControl] = None
 
 
 class ImageUrl(BaseModel):
@@ -56,7 +60,6 @@ class ImageUrl(BaseModel):
     detail: Optional[ImageDetailLevel] = None
 
 
-# @dataclass
 class ImagePart(BaseModel):
     """
     Represents an image segment within a multimodal content block.
@@ -65,9 +68,12 @@ class ImagePart(BaseModel):
         image_url: An `ImageUrl` object containing the image's location and detail level.
 
         type: The type identifier, defaulting to "image_url".
+
+        cache_control: Optional cache control settings for prompt caching.
     """
     image_url: ImageUrl
     type_: Literal["image_url"] = Field(default="image_url", alias="type")
+    cache_control: Optional[CacheControl] = None
 
 
 ContentPart = Union[TextPart, ImagePart]

@@ -27,16 +27,35 @@ class ResponseBaseModel(BaseModel):
     )
 
 
+class CacheCreationTokenDetails(ResponseBaseModel):
+    """
+    Per-TTL breakdown of tokens written to the prompt cache.
+
+    Present only when cache_control includes an explicit ttl value.
+
+    Attributes:
+        ephemeral_5m_input_tokens: Tokens cached with a 5-minute TTL.
+        ephemeral_1h_input_tokens: Tokens cached with a 1-hour TTL.
+    """
+    ephemeral_5m_input_tokens: Optional[int] = None
+    ephemeral_1h_input_tokens: Optional[int] = None
+
+
 class PromptTokensDetails(ResponseBaseModel):
     """
     Represents the details of prompt tokens used in a specific operation.
 
     Attributes:
         audio_tokens (Optional[int]): Audio input tokens present in the prompt.
-        cached_tokens (Optional[int]): Cached tokens present in the prompt.
+        cached_tokens (Optional[int]): Tokens read from the prompt cache (cache hit).
+        cache_creation_tokens (Optional[int]): Tokens written to the prompt cache (cache miss).
+        cache_creation_token_details (Optional[CacheCreationTokenDetails]): Per-TTL
+            breakdown of cache writes. Present only when an explicit ttl was used.
     """
     audio_tokens: Optional[int] = None
     cached_tokens: Optional[int] = None
+    cache_creation_tokens: Optional[int] = None
+    cache_creation_token_details: Optional[CacheCreationTokenDetails] = None
 
 class CompletionTokensDetails(ResponseBaseModel):
     """
@@ -385,7 +404,8 @@ class OrchestrationResponseWithRetries(CompletionPostResponse):
     """
     retries: int = 0
 
-__all__ = ["PromptTokensDetails",
+__all__ = ["CacheCreationTokenDetails",
+    "PromptTokensDetails",
     "CompletionTokensDetails",
     "TokenUsage",
     "GenericModuleResult",

@@ -11,6 +11,7 @@
 from pydantic import Field
 
 from gen_ai_hub.orchestration_v2.models.base import ABCBaseModel as BaseModel
+from gen_ai_hub.orchestration_v2.models.cache_control import CacheControl
 
 
 def python_type_to_json_type(py_type):
@@ -66,33 +67,24 @@ def python_type_to_json_type(py_type):
 
 
 class ChatCompletionTool(BaseModel):
-    """
-    Base class for all chat completion tools.
+    """A tool the model may call, identified by type ``"function"``.
 
     Args:
-            type (Literal["function"]): The type of the tool. Currently, only function is supported.
+        type (Literal["function"]): The type of the tool. Currently, only function is supported.
+        cache_control: Prompt-caching directive.
     """
-    type_: Literal["function"] = Field(default="function",
-                                       alias="type",
-                                       description="The type of the tool. Currently, only function is supported.")
+    type_: Literal["function"] = Field(default="function", alias="type")
+    cache_control: Optional[CacheControl] = None
 
 
 class FunctionObject(BaseModel):
-    """
-    Represents a function.
-    Args:
-            name (str): The name of the function to be called. Must be a-z, A-Z, 0-9,
-                        or contain underscores and dashes, with a maximum length of 64.
-
-            description (str): A description of what the function does, used by the model
-                        to choose when and how to call the function.
-
-            parameters (dict): The parameters the functions accepts, described as a JSON Schema object.
-                        Omitting parameters defines a function with an empty parameter list.
+    """A function definition used inside a ``FunctionTool``.
 
-            strict (bool, optional): Whether to enable strict schema adherence when generating the function call.
-                        If set to true, the model will follow the exact schema defined in the parameters field.
-                        Only a subset of JSON Schema is supported when strict is true. Defaults to False.
+    Args:
+        name: Function name. Must match ``^[a-zA-Z0-9_-]+$``, max 64 chars.
+        description: What the function does; used by the model to decide when to call it.
+        parameters: JSON Schema object describing accepted parameters.
+        strict: When ``True``, the model follows the schema exactly. Defaults to ``False``.
     """
     description: Optional[str] = None
     name: str
@@ -102,15 +94,19 @@ class FunctionObject(BaseModel):
 
 
 class FunctionTool(ChatCompletionTool):
-    """
-    Represents a function tool for OpenAI-like function calling.
+    """A callable function tool for OpenAI-style function calling.
+
+    Inherits all fields from :class:`ChatCompletionTool`:
 
     Args:
-            type (Literal["function"]): The type of the tool. Currently, only function is supported.
+        type: Always ``"function"``. Serialized via the ``type`` alias.
+        cache_control: Prompt-caching directive.
 
-            function (FunctionObject): The function to be called.
+    Additional args:
+
+        function: The function definition — name, description, parameters schema,
+            and optional strict flag. See :class:`FunctionObject`.
     """
-    type_: Literal["function"] = Field(default="function", alias="type")
     function: FunctionObject
 
     def execute(self, **kwargs: Any) -> Any: