From 11fd4d02ebdf946d820e3d8f3f5ab1848f455ccd Mon Sep 17 00:00:00 2001 From: Alex Zai Date: Tue, 18 Nov 2025 08:55:53 -0800 Subject: [PATCH 1/6] add chat adapter docs --- dspy/adapters/chat_adapter.py | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/dspy/adapters/chat_adapter.py b/dspy/adapters/chat_adapter.py index 8d92fa34b6..54f47ca891 100644 --- a/dspy/adapters/chat_adapter.py +++ b/dspy/adapters/chat_adapter.py @@ -26,6 +26,22 @@ class FieldInfoWithName(NamedTuple): class ChatAdapter(Adapter): + """Chat-based Adapter for LM interactions. + + The ChatAdapter formats DSPy signatures into a conversational chat format with structured field markers. + It uses delimiter patterns like `[[ ## field_name ## ]]` to clearly separate input and output fields in + the message content, making it suitable for chat-based language models. + + Key features: + - Structures inputs and outputs using field header markers for clear field delineation. + - Provides automatic fallback to JSONAdapter on parsing errors (configurable). + - Supports conversation history, few-shot examples, and custom type processing. + - Includes a completion marker `[[ ## completed ## ]]` to signal the end of output fields. + + This adapter is particularly effective for chat-based models that benefit from explicit field boundaries + in the conversation flow. + """ + def __init__( self, callbacks=None, @@ -33,6 +49,21 @@ def __init__( native_response_types=None, use_json_adapter_fallback: bool = True, ): + """ + Args: + callbacks: List of callback functions to execute during `format()` and `parse()` methods. Callbacks can be + used for logging, monitoring, or custom processing. Defaults to None (empty list). + use_native_function_calling: Whether to enable native function calling capabilities when the LM supports it. + If True, the adapter will automatically configure function calling when input fields contain `dspy.Tool` + or `list[dspy.Tool]` types. Defaults to False. + native_response_types: List of output field types that should be handled by native LM features rather than + adapter parsing. For example, `dspy.Citations` can be populated directly by citation APIs + (e.g., Anthropic's citation feature). Defaults to `[Citations, Reasoning]`. + use_json_adapter_fallback: Whether to automatically fall back to JSONAdapter if ChatAdapter encounters + parsing errors or other exceptions (except ContextWindowExceededError). This provides robustness by + retrying with a different format when the chat format fails. Defaults to True. + """ + super().__init__( callbacks=callbacks, use_native_function_calling=use_native_function_calling, From bc444b3d12d385c5ad0dab05ffd9fa6e1f4a9bd5 Mon Sep 17 00:00:00 2001 From: Alex Zai Date: Tue, 18 Nov 2025 15:12:01 -0800 Subject: [PATCH 2/6] udpate chat adapter docs to not be overly specfic to chat --- dspy/adapters/chat_adapter.py | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/dspy/adapters/chat_adapter.py b/dspy/adapters/chat_adapter.py index 54f47ca891..387a72e036 100644 --- a/dspy/adapters/chat_adapter.py +++ b/dspy/adapters/chat_adapter.py @@ -26,20 +26,15 @@ class FieldInfoWithName(NamedTuple): class ChatAdapter(Adapter): - """Chat-based Adapter for LM interactions. + """Default Adapter for most language models. - The ChatAdapter formats DSPy signatures into a conversational chat format with structured field markers. + The ChatAdapter formats DSPy signatures into a format compatible with most language models. It uses delimiter patterns like `[[ ## field_name ## ]]` to clearly separate input and output fields in - the message content, making it suitable for chat-based language models. + the message content. Key features: - Structures inputs and outputs using field header markers for clear field delineation. - Provides automatic fallback to JSONAdapter on parsing errors (configurable). - - Supports conversation history, few-shot examples, and custom type processing. - - Includes a completion marker `[[ ## completed ## ]]` to signal the end of output fields. - - This adapter is particularly effective for chat-based models that benefit from explicit field boundaries - in the conversation flow. """ def __init__( @@ -63,7 +58,7 @@ def __init__( parsing errors or other exceptions (except ContextWindowExceededError). This provides robustness by retrying with a different format when the chat format fails. Defaults to True. """ - + super().__init__( callbacks=callbacks, use_native_function_calling=use_native_function_calling, From 2bdfc1801c4ef093f0a80c842b271799fa589532 Mon Sep 17 00:00:00 2001 From: Alex Zai Date: Tue, 18 Nov 2025 15:15:36 -0800 Subject: [PATCH 3/6] inherit docs from parent class --- dspy/adapters/chat_adapter.py | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/dspy/adapters/chat_adapter.py b/dspy/adapters/chat_adapter.py index 387a72e036..4f67ff4a82 100644 --- a/dspy/adapters/chat_adapter.py +++ b/dspy/adapters/chat_adapter.py @@ -44,20 +44,6 @@ def __init__( native_response_types=None, use_json_adapter_fallback: bool = True, ): - """ - Args: - callbacks: List of callback functions to execute during `format()` and `parse()` methods. Callbacks can be - used for logging, monitoring, or custom processing. Defaults to None (empty list). - use_native_function_calling: Whether to enable native function calling capabilities when the LM supports it. - If True, the adapter will automatically configure function calling when input fields contain `dspy.Tool` - or `list[dspy.Tool]` types. Defaults to False. - native_response_types: List of output field types that should be handled by native LM features rather than - adapter parsing. For example, `dspy.Citations` can be populated directly by citation APIs - (e.g., Anthropic's citation feature). Defaults to `[Citations, Reasoning]`. - use_json_adapter_fallback: Whether to automatically fall back to JSONAdapter if ChatAdapter encounters - parsing errors or other exceptions (except ContextWindowExceededError). This provides robustness by - retrying with a different format when the chat format fails. Defaults to True. - """ super().__init__( callbacks=callbacks, @@ -66,6 +52,8 @@ def __init__( ) self.use_json_adapter_fallback = use_json_adapter_fallback + __init__.__doc__ = Adapter.__init__.__doc__ + def __call__( self, lm: LM, From 330246e46672058b5c602c5fcc58466d242cc282 Mon Sep 17 00:00:00 2001 From: Alex Zai Date: Tue, 18 Nov 2025 15:18:39 -0800 Subject: [PATCH 4/6] update fallback docs --- dspy/adapters/chat_adapter.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dspy/adapters/chat_adapter.py b/dspy/adapters/chat_adapter.py index 4f67ff4a82..07fa37841c 100644 --- a/dspy/adapters/chat_adapter.py +++ b/dspy/adapters/chat_adapter.py @@ -34,7 +34,7 @@ class ChatAdapter(Adapter): Key features: - Structures inputs and outputs using field header markers for clear field delineation. - - Provides automatic fallback to JSONAdapter on parsing errors (configurable). + - Provides automatic fallback to JSONAdapter if the chat format fails. """ def __init__( From 7e0394d851b8989093a1ec0cf3d5f880d8380eea Mon Sep 17 00:00:00 2001 From: Alex Zai Date: Thu, 20 Nov 2025 08:17:25 -0800 Subject: [PATCH 5/6] move docs to bottom, add extra args --- dspy/adapters/chat_adapter.py | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/dspy/adapters/chat_adapter.py b/dspy/adapters/chat_adapter.py index 07fa37841c..3c6c08bd7f 100644 --- a/dspy/adapters/chat_adapter.py +++ b/dspy/adapters/chat_adapter.py @@ -52,8 +52,6 @@ def __init__( ) self.use_json_adapter_fallback = use_json_adapter_fallback - __init__.__doc__ = Adapter.__init__.__doc__ - def __call__( self, lm: LM, @@ -282,3 +280,12 @@ def format_finetune_data( assistant_message = {"role": "assistant", "content": assistant_message_content} messages = system_user_messages + [assistant_message] return {"messages": messages} + + +ChatAdapter.__init__.__doc__ = ( + Adapter.__init__.__doc__ + + """ use_json_adapter_fallback: Whether to automatically fallback to JSONAdapter if the ChatAdapter fails. + If True, when an error occurs (except ContextWindowExceededError), the adapter will retry using + JSONAdapter. Defaults to True. +""" +) From 6c9ff5081868d4876098999c7a0633a0e3f35126 Mon Sep 17 00:00:00 2001 From: chenmoneygithub Date: Fri, 21 Nov 2025 16:21:29 -0800 Subject: [PATCH 6/6] fix mkdocs issue --- dspy/adapters/chat_adapter.py | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/dspy/adapters/chat_adapter.py b/dspy/adapters/chat_adapter.py index 3c6c08bd7f..7cd7c9e818 100644 --- a/dspy/adapters/chat_adapter.py +++ b/dspy/adapters/chat_adapter.py @@ -15,6 +15,7 @@ ) from dspy.clients.lm import LM from dspy.signatures.signature import Signature +from dspy.utils.callback import BaseCallback from dspy.utils.exceptions import AdapterParseError field_header_pattern = re.compile(r"\[\[ ## (\w+) ## \]\]") @@ -39,12 +40,20 @@ class ChatAdapter(Adapter): def __init__( self, - callbacks=None, + callbacks: list[BaseCallback] | None = None, use_native_function_calling: bool = False, - native_response_types=None, + native_response_types: list[type[type]] | None = None, use_json_adapter_fallback: bool = True, ): - + """ + Args: + callbacks: List of callback functions to execute during adapter methods. + use_native_function_calling: Whether to enable native function calling capabilities. + native_response_types: List of output field types handled by native LM features. + use_json_adapter_fallback: Whether to automatically fallback to JSONAdapter if the ChatAdapter fails. + If True, when an error occurs (except ContextWindowExceededError), the adapter will retry using + JSONAdapter. Defaults to True. + """ super().__init__( callbacks=callbacks, use_native_function_calling=use_native_function_calling, @@ -280,12 +289,3 @@ def format_finetune_data( assistant_message = {"role": "assistant", "content": assistant_message_content} messages = system_user_messages + [assistant_message] return {"messages": messages} - - -ChatAdapter.__init__.__doc__ = ( - Adapter.__init__.__doc__ - + """ use_json_adapter_fallback: Whether to automatically fallback to JSONAdapter if the ChatAdapter fails. - If True, when an error occurs (except ContextWindowExceededError), the adapter will retry using - JSONAdapter. Defaults to True. -""" -)