Merge pull request #14570 from timelfrink/feat/issue-14562-bedrock-converse-request-metadata

krrishdholakia · web-flow · commit 52a56bd5fe43 · 2025-09-21T21:26:49.000-07:00
feat: Support requestMetadata in Bedrock Converse API
diff --git a/docs/my-website/docs/completion/provider_specific_params.md b/docs/my-website/docs/completion/provider_specific_params.md
@@ -433,4 +433,54 @@ curl -X POST 'http://0.0.0.0:4000/chat/completions' \
   ],
   "adapater_id": "my-special-adapter-id" # 👈 PROVIDER-SPECIFIC PARAM
   }'
+
+## Provider-Specific Metadata Parameters
+
+| Provider | Parameter | Use Case |
+|----------|-----------|----------|
+| **AWS Bedrock** | `requestMetadata` | Cost attribution, logging |
+| **Gemini/Vertex AI** | `labels` | Resource labeling |
+| **Anthropic** | `metadata` | User identification |
+
+<Tabs>
+<TabItem value="bedrock" label="AWS Bedrock">
+
+```python
+import litellm
+
+response = litellm.completion(
+    model="bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0",
+    messages=[{"role": "user", "content": "Hello!"}],
+    requestMetadata={"cost_center": "engineering"}
+)
+```
+
+</TabItem>
+<TabItem value="gemini" label="Gemini/Vertex AI">
+
+```python
+import litellm
+
+response = litellm.completion(
+    model="vertex_ai/gemini-pro",
+    messages=[{"role": "user", "content": "Hello!"}],
+    labels={"environment": "production"}
+)
+```
+
+</TabItem>
+<TabItem value="anthropic" label="Anthropic">
+
+```python
+import litellm
+
+response = litellm.completion(
+    model="anthropic/claude-3-sonnet-20240229",
+    messages=[{"role": "user", "content": "Hello!"}],
+    metadata={"user_id": "user123"}
+)
+```
+
+</TabItem>
+</Tabs>
 ```
diff --git a/docs/my-website/docs/providers/bedrock.md b/docs/my-website/docs/providers/bedrock.md
@@ -308,6 +308,65 @@ print(response)
 </TabItem>
 </Tabs>
 
+## Usage - Request Metadata
+
+Attach metadata to Bedrock requests for logging and cost attribution.
+
+<Tabs>
+<TabItem value="sdk" label="SDK">
+
+```python
+import os
+from litellm import completion
+
+os.environ["AWS_ACCESS_KEY_ID"] = ""
+os.environ["AWS_SECRET_ACCESS_KEY"] = ""
+os.environ["AWS_REGION_NAME"] = ""
+
+response = completion(
+    model="bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0",
+    messages=[{"role": "user", "content": "Hello, how are you?"}],
+    requestMetadata={
+        "cost_center": "engineering",
+        "user_id": "user123"
+    }
+)
+```
+</TabItem>
+<TabItem value="proxy" label="PROXY">
+
+**Set on yaml**
+
+```yaml
+model_list:
+  - model_name: bedrock-claude-v1
+    litellm_params:
+      model: bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0
+      requestMetadata:
+        cost_center: "engineering"
+```
+
+**Set on request**
+
+```python
+import openai
+client = openai.OpenAI(
+    api_key="anything",
+    base_url="http://0.0.0.0:4000"
+)
+
+response = client.chat.completions.create(
+    model="bedrock-claude-v1",
+    messages=[{"role": "user", "content": "Hello"}],
+    extra_body={
+        "requestMetadata": {"cost_center": "engineering"}
+    }
+)
+```
+
+</TabItem>
+</Tabs>
+
 ## Usage - Function Calling / Tool calling
 
 LiteLLM supports tool calling via Bedrock's Converse and Invoke API's.
diff --git a/litellm/llms/bedrock/chat/converse_transformation.py b/litellm/llms/bedrock/chat/converse_transformation.py
@@ -175,6 +175,77 @@ def get_config(cls):
             and v is not None
         }
 
+    def _validate_request_metadata(self, metadata: dict) -> None:
+        """
+        Validate requestMetadata according to AWS Bedrock Converse API constraints.
+
+        Constraints:
+        - Maximum of 16 items
+        - Keys: 1-256 characters, pattern [a-zA-Z0-9\\s:_@$#=/+,-.]{1,256}
+        - Values: 0-256 characters, pattern [a-zA-Z0-9\\s:_@$#=/+,-.]{0,256}
+        """
+        import re
+
+        if not isinstance(metadata, dict):
+            raise litellm.exceptions.BadRequestError(
+                message="requestMetadata must be a dictionary",
+                model="bedrock",
+                llm_provider="bedrock",
+            )
+
+        if len(metadata) > 16:
+            raise litellm.exceptions.BadRequestError(
+                message="requestMetadata can contain a maximum of 16 items",
+                model="bedrock",
+                llm_provider="bedrock",
+            )
+
+        key_pattern = re.compile(r'^[a-zA-Z0-9\s:_@$#=/+,.-]{1,256}$')
+        value_pattern = re.compile(r'^[a-zA-Z0-9\s:_@$#=/+,.-]{0,256}$')
+
+        for key, value in metadata.items():
+            if not isinstance(key, str):
+                raise litellm.exceptions.BadRequestError(
+                    message="requestMetadata keys must be strings",
+                    model="bedrock",
+                    llm_provider="bedrock",
+                )
+
+            if not isinstance(value, str):
+                raise litellm.exceptions.BadRequestError(
+                    message="requestMetadata values must be strings",
+                    model="bedrock",
+                    llm_provider="bedrock",
+                )
+
+            if len(key) == 0 or len(key) > 256:
+                raise litellm.exceptions.BadRequestError(
+                    message="requestMetadata key length must be 1-256 characters",
+                    model="bedrock",
+                    llm_provider="bedrock",
+                )
+
+            if len(value) > 256:
+                raise litellm.exceptions.BadRequestError(
+                    message="requestMetadata value length must be 0-256 characters",
+                    model="bedrock",
+                    llm_provider="bedrock",
+                )
+
+            if not key_pattern.match(key):
+                raise litellm.exceptions.BadRequestError(
+                    message=f"requestMetadata key '{key}' contains invalid characters. Allowed: [a-zA-Z0-9\\s:_@$#=/+,.-]",
+                    model="bedrock",
+                    llm_provider="bedrock",
+                )
+
+            if not value_pattern.match(value):
+                raise litellm.exceptions.BadRequestError(
+                    message=f"requestMetadata value '{value}' contains invalid characters. Allowed: [a-zA-Z0-9\\s:_@$#=/+,.-]",
+                    model="bedrock",
+                    llm_provider="bedrock",
+                )
+
     def get_supported_openai_params(self, model: str) -> List[str]:
         from litellm.utils import supports_function_calling
 
@@ -188,6 +259,7 @@ def get_supported_openai_params(self, model: str) -> List[str]:
             "top_p",
             "extra_headers",
             "response_format",
+            "requestMetadata",
         ]
 
         if (
@@ -497,6 +569,10 @@ def map_openai_params(
                     optional_params["thinking"] = AnthropicConfig._map_reasoning_effort(
                         value
                     )
+            if param == "requestMetadata":
+                if value is not None and isinstance(value, dict):
+                    self._validate_request_metadata(value)  # type: ignore
+                    optional_params["requestMetadata"] = value
 
         # Only update thinking tokens for non-GPT-OSS models
         if "gpt-oss" not in model:
@@ -686,34 +762,8 @@ def _handle_top_k_value(self, model: str, inference_params: dict) -> dict:
 
         return {}
 
-    def _transform_request_helper(
-        self,
-        model: str,
-        system_content_blocks: List[SystemContentBlock],
-        optional_params: dict,
-        messages: Optional[List[AllMessageValues]] = None,
-        headers: Optional[dict] = None,
-    ) -> CommonRequestObject:
-        ## VALIDATE REQUEST
-        """
-        Bedrock doesn't support tool calling without `tools=` param specified.
-        """
-        if (
-            "tools" not in optional_params
-            and messages is not None
-            and has_tool_call_blocks(messages)
-        ):
-            if litellm.modify_params:
-                optional_params["tools"] = add_dummy_tool(
-                    custom_llm_provider="bedrock_converse"
-                )
-            else:
-                raise litellm.UnsupportedParamsError(
-                    message="Bedrock doesn't support tool calling without `tools=` param specified. Pass `tools=` param OR set `litellm.modify_params = True` // `litellm_settings::modify_params: True` to add dummy tool to the request.",
-                    model="",
-                    llm_provider="bedrock",
-                )
-
+    def _prepare_request_params(self, optional_params: dict, model: str) -> tuple[dict, dict, dict]:
+        """Prepare and separate request parameters."""
         inference_params = copy.deepcopy(optional_params)
         supported_converse_params = list(
             AmazonConverseConfig.__annotations__.keys()
@@ -727,6 +777,11 @@ def _transform_request_helper(
         )
         inference_params.pop("json_mode", None)  # used for handling json_schema
 
+        # Extract requestMetadata before processing other parameters
+        request_metadata = inference_params.pop("requestMetadata", None)
+        if request_metadata is not None:
+            self._validate_request_metadata(request_metadata)
+
         # keep supported params in 'inference_params', and set all model-specific params in 'additional_request_params'
         additional_request_params = {
             k: v for k, v in inference_params.items() if k not in total_supported_params
@@ -740,9 +795,10 @@ def _transform_request_helper(
             self._handle_top_k_value(model, inference_params)
         )
 
-        original_tools = inference_params.pop("tools", [])
+        return inference_params, additional_request_params, request_metadata
 
-        # Initialize bedrock_tools
+    def _process_tools_and_beta(self, original_tools: list, model: str, headers: Optional[dict], additional_request_params: dict) -> tuple[List[ToolBlock], list]:
+        """Process tools and collect anthropic_beta values."""
         bedrock_tools: List[ToolBlock] = []
 
         # Collect anthropic_beta values from user headers
@@ -784,6 +840,44 @@ def _transform_request_helper(
                     seen.add(beta)
             additional_request_params["anthropic_beta"] = unique_betas
 
+        return bedrock_tools, anthropic_beta_list
+
+    def _transform_request_helper(
+        self,
+        model: str,
+        system_content_blocks: List[SystemContentBlock],
+        optional_params: dict,
+        messages: Optional[List[AllMessageValues]] = None,
+        headers: Optional[dict] = None,
+    ) -> CommonRequestObject:
+        ## VALIDATE REQUEST
+        """
+        Bedrock doesn't support tool calling without `tools=` param specified.
+        """
+        if (
+            "tools" not in optional_params
+            and messages is not None
+            and has_tool_call_blocks(messages)
+        ):
+            if litellm.modify_params:
+                optional_params["tools"] = add_dummy_tool(
+                    custom_llm_provider="bedrock_converse"
+                )
+            else:
+                raise litellm.UnsupportedParamsError(
+                    message="Bedrock doesn't support tool calling without `tools=` param specified. Pass `tools=` param OR set `litellm.modify_params = True` // `litellm_settings::modify_params: True` to add dummy tool to the request.",
+                    model="",
+                    llm_provider="bedrock",
+                )
+
+        # Prepare and separate parameters
+        inference_params, additional_request_params, request_metadata = self._prepare_request_params(optional_params, model)
+
+        original_tools = inference_params.pop("tools", [])
+
+        # Process tools and collect beta values
+        bedrock_tools, anthropic_beta_list = self._process_tools_and_beta(original_tools, model, headers, additional_request_params)
+
         bedrock_tool_config: Optional[ToolConfigBlock] = None
         if len(bedrock_tools) > 0:
             tool_choice_values: ToolChoiceValuesBlock = inference_params.pop(
@@ -813,6 +907,10 @@ def _transform_request_helper(
         if bedrock_tool_config is not None:
             data["toolConfig"] = bedrock_tool_config
 
+        # Request Metadata (top-level field)
+        if request_metadata is not None:
+            data["requestMetadata"] = request_metadata
+
         return data
 
     async def _async_transform_request(
diff --git a/litellm/types/llms/bedrock.py b/litellm/types/llms/bedrock.py
@@ -1,5 +1,5 @@
 import json
-from typing import Any, List, Literal, Optional, Union
+from typing import Any, Dict, List, Literal, Optional, Union
 
 from typing_extensions import (
     TYPE_CHECKING,
@@ -231,6 +231,7 @@ class CommonRequestObject(
     toolConfig: ToolConfigBlock
     guardrailConfig: Optional[GuardrailConfigBlock]
     performanceConfig: Optional[PerformanceConfigBlock]
+    requestMetadata: Optional[Dict[str, str]]
 
 
 class RequestObject(CommonRequestObject, total=False):
diff --git a/tests/test_litellm/llms/bedrock/chat/test_converse_transformation.py b/tests/test_litellm/llms/bedrock/chat/test_converse_transformation.py
