44from __future__ import annotations
55
66import asyncio
7+ import copy
78import json
89import logging
910import sys
3637from boto3 .session import Session as Boto3Session
3738from botocore .client import BaseClient
3839from botocore .config import Config as BotoConfig
40+ from botocore .exceptions import ClientError
3941from pydantic import BaseModel
4042
4143if sys .version_info >= (3 , 13 ):
@@ -115,13 +117,20 @@ class BedrockChatOptions(ChatOptions[ResponseModelT], Generic[ResponseModelT], t
115117 translates to ``toolConfig.tools``.
116118 tool_choice: How the model should use tools,
117119 translates to ``toolConfig.toolChoice``.
120+ response_format: Structured output format. Accepts a Pydantic BaseModel
121+ subclass or an OpenAI-style dict schema
122+ (``{"json_schema": {"name": ..., "schema": ...}}``).
123+ When provided, the Converse API request includes
124+ ``outputConfig.textFormat`` with the schema serialized as a JSON
125+ string. ``ChatResponse.value`` will be populated with the parsed
126+ model instance. Only supported on models that support
127+ ``outputConfig.textFormat``. Unsupported models raise a ValueError.
118128
119129 # Options not supported in Bedrock Converse API:
120130 seed: Not supported.
121131 frequency_penalty: Not supported.
122132 presence_penalty: Not supported.
123133 allow_multiple_tool_calls: Not supported (models handle parallel calls automatically).
124- response_format: Not directly supported (use model-specific prompting).
125134 user: Not supported.
126135 store: Not supported.
127136 logit_bias: Not supported.
@@ -161,9 +170,6 @@ class BedrockChatOptions(ChatOptions[ResponseModelT], Generic[ResponseModelT], t
161170 allow_multiple_tool_calls : None # type: ignore[misc]
162171 """Not supported. Bedrock models handle parallel tool calls automatically."""
163172
164- response_format : None # type: ignore[misc]
165- """Not directly supported. Use model-specific prompting for JSON output."""
166-
167173 user : None # type: ignore[misc]
168174 """Not supported in Bedrock Converse API."""
169175
@@ -324,10 +330,28 @@ def _create_session(settings: BedrockSettings) -> Boto3Session:
324330 return Boto3Session (** session_kwargs )
325331
326332 def _invoke_converse (self , request : Mapping [str , Any ]) -> dict [str , Any ]:
327- response = self ._bedrock_client .converse (** request )
328- if not isinstance (response , Mapping ):
329- raise ChatClientInvalidResponseException ("Bedrock converse response must be a mapping." )
330- return response
333+ try :
334+ response = self ._bedrock_client .converse (** request )
335+ if not isinstance (response , Mapping ):
336+ raise ChatClientInvalidResponseException ("Bedrock converse response must be a mapping." )
337+ return response
338+ except ClientError as e :
339+ error_details = e .response .get ("Error" , {})
340+ error_code = error_details .get ("Code" , "" )
341+ error_message = error_details .get ("Message" , "" )
342+ # "outputConfig" in error_message catches cases where Bedrock explicitly
343+ # rejects the outputConfig field (unsupported model). Other ValidationExceptions
344+ # (e.g. malformed schema shape, invalid property values) will not mention
345+ # "outputConfig" and will bubble up as raw ClientError without being misdiagnosed.
346+ if error_code == "ValidationException" and (
347+ "outputconfig" in error_message .lower () or "outputconfig" in str (e ).lower ()
348+ ):
349+ raise ValueError (
350+ f"Model '{ self .model } ' does not support structured output via outputConfig.textFormat. "
351+ "Check the model's Bedrock Converse outputConfig/textFormat support. "
352+ f"AWS error Code: { error_code } . AWS error Message: { error_message } "
353+ ) from e
354+ raise
331355
332356 @override
333357 def _inner_get_response (
@@ -344,7 +368,7 @@ def _inner_get_response(
344368 # Streaming mode - simulate streaming by yielding a single update
345369 async def _stream () -> AsyncIterable [ChatResponseUpdate ]:
346370 response = await asyncio .to_thread (self ._invoke_converse , request )
347- parsed_response = self ._process_converse_response (response )
371+ parsed_response = self ._process_converse_response (response , options )
348372 contents = list (parsed_response .messages [0 ].contents if parsed_response .messages else [])
349373 if parsed_response .usage_details :
350374 contents .append (Content .from_usage (usage_details = parsed_response .usage_details )) # type: ignore[arg-type]
@@ -360,12 +384,12 @@ async def _stream() -> AsyncIterable[ChatResponseUpdate]:
360384 raw_representation = parsed_response .raw_representation ,
361385 )
362386
363- return self ._build_response_stream (_stream ())
387+ return self ._build_response_stream (_stream (), response_format = options . get ( "response_format" ) )
364388
365389 # Non-streaming mode
366390 async def _get_response () -> ChatResponse :
367391 raw_response = await asyncio .to_thread (self ._invoke_converse , request )
368- return self ._process_converse_response (raw_response )
392+ return self ._process_converse_response (raw_response , options )
369393
370394 return _get_response ()
371395
@@ -430,6 +454,9 @@ def _prepare_options(
430454 if tool_config :
431455 run_options ["toolConfig" ] = tool_config
432456
457+ if output_config := self ._prepare_output_config (options .get ("response_format" )):
458+ run_options ["outputConfig" ] = output_config
459+
433460 return run_options
434461
435462 def _prepare_bedrock_messages (
@@ -628,7 +655,9 @@ def _prepare_tools(self, tools: list[FunctionTool | MutableMapping[str, Any]] |
628655 def _generate_tool_call_id () -> str :
629656 return f"tool-call-{ uuid4 ().hex } "
630657
631- def _process_converse_response (self , response : dict [str , Any ]) -> ChatResponse :
658+ def _process_converse_response (
659+ self , response : dict [str , Any ], options : Mapping [str , Any ] | None = None
660+ ) -> ChatResponse :
632661 """Convert Bedrock Converse API response to ChatResponse."""
633662 output = response .get ("output" ) or {}
634663 message = output .get ("message" ) or {}
@@ -646,6 +675,7 @@ def _process_converse_response(self, response: dict[str, Any]) -> ChatResponse:
646675 usage_details = usage_details ,
647676 model = model ,
648677 finish_reason = finish_reason ,
678+ response_format = options .get ("response_format" ) if options else None ,
649679 raw_representation = response ,
650680 )
651681
@@ -728,6 +758,108 @@ def _map_finish_reason(self, reason: str | None) -> FinishReasonLiteral | None:
728758 return None
729759 return FINISH_REASON_MAP .get (reason .lower ())
730760
761+ def _prepare_output_config (self , response_format : Any | None ) -> dict [str , Any ] | None :
762+ """Convert response_format into the AWS Bedrock outputConfig wire format.
763+
764+ Args:
765+ response_format: A Pydantic model class or a dict schema, or None.
766+
767+ Returns:
768+ A dict for the Converse API ``outputConfig`` parameter, or None if
769+ response_format is not set.
770+ """
771+ if response_format is None :
772+ return None
773+
774+ if isinstance (response_format , Mapping ):
775+ if "json_schema" in response_format :
776+ # Shape A — OpenAI-style wrapper
777+ json_schema_config = response_format ["json_schema" ]
778+ schema_src = json_schema_config .get ("schema" , {})
779+ name = json_schema_config .get ("name" , "output_schema" )
780+ elif "schema" in response_format :
781+ # Shape B — inner shape directly {"name": ..., "schema": ...}
782+ schema_src = response_format ["schema" ]
783+ name = response_format .get ("name" , "output_schema" )
784+ else :
785+ # Shape C — assume entire dict is the raw schema
786+ logger .warning (
787+ "response_format dict has no 'json_schema' or 'schema' key; "
788+ "treating entire dict as raw JSON schema."
789+ )
790+ schema_src = dict (response_format )
791+ name = "output_schema"
792+
793+ if isinstance (schema_src , str ):
794+ schema_src = json .loads (schema_src )
795+ schema = copy .deepcopy (schema_src )
796+ else :
797+ if not isinstance (response_format , type ) or not issubclass (response_format , BaseModel ):
798+ raise TypeError (
799+ "response_format must be None, a dict JSON schema, "
800+ "or a Pydantic BaseModel subclass."
801+ )
802+ # response_format is a Pydantic model class
803+ schema = response_format .model_json_schema ()
804+ name = response_format .__name__
805+
806+ self ._set_additional_properties_false (schema )
807+
808+ json_schema : dict [str , Any ] = {
809+ "name" : name ,
810+ "schema" : json .dumps (schema ),
811+ }
812+
813+ description = getattr (response_format , "__doc__" , None ) if not isinstance (response_format , Mapping ) else None
814+ if description and isinstance (description , str ) and description .strip ():
815+ json_schema ["description" ] = description .strip ()
816+
817+ return {
818+ "textFormat" : {
819+ "type" : "json_schema" ,
820+ "structure" : {
821+ "jsonSchema" : json_schema
822+ },
823+ }
824+ }
825+
826+ def _set_additional_properties_false (self , schema : dict [str , Any ]) -> None :
827+ """Recursively set additionalProperties: false on all object types in a JSON schema.
828+
829+ AWS requires strict schema enforcement. This mirrors the approach used by
830+ AnthropicChatClient._prepare_response_format().
831+
832+ Args:
833+ schema: The JSON schema dict to modify in-place.
834+ """
835+ visited : set [int ] = set ()
836+
837+ def walk (node : Any ) -> None :
838+ if isinstance (node , dict ):
839+ node_id = id (node )
840+ if node_id in visited :
841+ return
842+ visited .add (node_id )
843+ if node .get ("type" ) == "object" or (
844+ "properties" in node and "type" not in node
845+ ):
846+ existing = node .get ("additionalProperties" )
847+ if existing is None or existing is True :
848+ node ["additionalProperties" ] = False
849+ for value in node .values ():
850+ if isinstance (value , (dict , list )):
851+ walk (value )
852+ elif isinstance (node , list ):
853+ node_id = id (node )
854+ if node_id in visited :
855+ return
856+ visited .add (node_id )
857+ for item in node :
858+ if isinstance (item , (dict , list )):
859+ walk (item )
860+
861+ walk (schema )
862+
731863 def service_url (self ) -> str :
732864 """Returns the service URL for the Bedrock runtime in the configured AWS region.
733865
0 commit comments