DSPy: The framework for programming—not prompting—language models
Python
feat(adapter): replay native tool call history (#9824)
Isaac Millera0fcc1e37244
diff --git a/dspy/adapters/base.py b/dspy/adapters/base.pyindex cad73e3b0..d69ae43ee 100644--- a/dspy/adapters/base.py+++ b/dspy/adapters/base.py@@ -10,7 +10,8 @@ from dspy.adapters._legacy_type_markers import ()from dspy.adapters.types import History, Typefrom dspy.adapters.types.reasoning import Reasoning-from dspy.adapters.types.tool import Tool, ToolCalls+from dspy.adapters.types.tool import Tool, ToolCallResults, ToolCalls+from dspy.adapters.utils import serialize_for_jsonfrom dspy.clients.base_lm import BaseLMfrom dspy.clients.openai_format import (legacy_outputs_from_lm_response,@@ -19,6 +20,7 @@ from dspy.clients.openai_format import ()from dspy.core.types import LMMessage, LMRequest, LMResponsefrom dspy.experimental import Citations+from dspy.signatures.field import InputFieldfrom dspy.signatures.signature import Signaturefrom dspy.utils.callback import BaseCallback, with_callbacksfrom dspy.utils.exceptions import AdapterParseError@@ -26,6 +28,7 @@ from dspy.utils.exceptions import AdapterParseErrorlogger = logging.getLogger(__name__)_DEFAULT_NATIVE_RESPONSE_TYPES = [Citations, Reasoning]+_TOOL_CALL_RESULTS_SIGNATURE = Signature({"tool_call_results": (ToolCallResults, InputField())})class Adapter:@@ -50,6 +53,7 @@ class Adapter:callbacks: list[BaseCallback] | None = None,use_native_function_calling: bool = False,native_response_types: list[type[Type]] | None = None,+ parallel_tool_calls: bool | None = None,):"""Args:@@ -61,9 +65,12 @@ class Adapter:native_response_types: List of output field types that should be handled by native LM features rather thanadapter parsing. For example, `dspy.Citations` can be populated directly by citation APIs(e.g., Anthropic's citation feature). Defaults to `[Citations]`.+ parallel_tool_calls: Whether to request provider-side parallel tool-call generation when native function+ calling is active. If None, the adapter does not set the provider option. Defaults to None."""self.callbacks = callbacks or []self.use_native_function_calling = use_native_function_calling+ self.parallel_tool_calls = parallel_tool_callsself.native_response_types = native_response_types or _DEFAULT_NATIVE_RESPONSE_TYPESdef __init_subclass__(cls, **kwargs) -> None:@@ -86,7 +93,10 @@ class Adapter:# stacked PR should replace this with an explicit `_AdapterPlan` that# records deleted fields, native tools, native output fields, inserted# messages/parts, and LM config patches.- if self.use_native_function_calling:+ if not self.use_native_function_calling:+ for key in ("tools", "tool_choice", "parallel_tool_calls"):+ lm_kwargs.pop(key, None)+ else:tool_call_input_field_name = self._get_tool_call_input_field_name(signature)tool_call_output_field_name = self._get_tool_call_output_field_name(signature)@@ -104,13 +114,11 @@ class Adapter:lm_tools = [tool.format_as_litellm_function_call() for tool in tools]lm_kwargs["tools"] = lm_tools+ if self.parallel_tool_calls is not None and lm_kwargs.get("parallel_tool_calls") is None:+ lm_kwargs["parallel_tool_calls"] = self.parallel_tool_calls- signature_for_native_function_calling = signature.delete(tool_call_output_field_name)- signature_for_native_function_calling = signature_for_native_function_calling.delete(- tool_call_input_field_name- )-- return signature_for_native_function_calling+ signature = signature.delete(tool_call_output_field_name)+ signature = signature.delete(tool_call_input_field_name)# TODO(adapters-plan): Built-in/native response planning should move out# of `Type.adapt_to_native_lm_feature()` and into adapter-owned planning@@ -153,16 +161,13 @@ class Adapter:output_logprobs = output.get("logprobs")tool_calls = output.get("tool_calls")- if text:+ if text and not (tool_calls and tool_call_output_field_name):value = self.parse(processed_signature, text)- for field_name in original_signature.output_fields.keys():- if field_name not in value:- # We need to set the field not present in the processed signature to None for consistency.- value[field_name] = Noneelif tool_calls and tool_call_output_field_name:- value = {}- for field_name in original_signature.output_fields.keys():- value[field_name] = None+ try:+ value = self.parse(processed_signature, text) if text and processed_signature.output_fields else {}+ except AdapterParseError:+ value = {}else:raise AdapterParseError(adapter_name=type(self).__name__,@@ -171,6 +176,10 @@ class Adapter:message="The LM returned an empty or null response.",)+ # Fields removed for native features are absent from the processed parse.+ for field_name in original_signature.output_fields:+ value.setdefault(field_name, None)+if tool_calls and tool_call_output_field_name:tool_calls = [_provider_tool_call_to_tool_call_dict(tool_call) for tool_call in tool_calls]value[tool_call_output_field_name] = ToolCalls.from_dict_list(tool_calls)@@ -421,11 +430,13 @@ class Adapter:# Conversation history and current inputcontent = self.format_user_message_content(signature_without_history, inputs_copy, main_request=True)messages.extend(conversation_history)- messages.append({"role": "user", "content": content})+ if content:+ messages.append({"role": "user", "content": content})else:# Only current inputcontent = self.format_user_message_content(signature, inputs_copy, main_request=True)- messages.append({"role": "user", "content": content})+ if content:+ messages.append({"role": "user", "content": content})return [_expand_legacy_custom_type_markers_in_chat_message(message) for message in messages]@@ -627,7 +638,7 @@ class Adapter:inputs: The input arguments to the DSPy module.Returns:- A list of multiturn messages.+ A list of multiturn messages as expected by the LM."""conversation_history = inputs[history_field_name].messages if history_field_name in inputs else None@@ -636,19 +647,64 @@ class Adapter:messages = []for message in conversation_history:- messages.append(- {- "role": "user",- "content": self.format_user_message_content(signature, message),- }- )- messages.append(- {- "role": "assistant",- "content": self.format_assistant_message_content(signature, message),- }+ tool_call_field_name, tool_calls = _tool_calls_from_message(message)+ tool_call_results = (+ ToolCallResults.model_validate(tool_calls.tool_call_results)+ if tool_calls is not None and tool_calls.tool_call_results is not None+ else None)+ user_content = self.format_user_message_content(signature, message)+ if user_content:+ messages.append({"role": "user", "content": user_content})++ if self.use_native_function_calling and tool_calls is not None:+ content_signature = signature+ for name, field in signature.output_fields.items():+ if field.annotation == ToolCalls or message.get(name) is None:+ content_signature = content_signature.delete(name)++ content = (+ self.format_assistant_message_content(content_signature, message)+ if content_signature.output_fields+ else ""+ )++ if tool_call_results is not None:+ tool_call_ids = [tool_call.id for tool_call in tool_calls.tool_calls]+ result_ids = [result.call_id for result in tool_call_results.tool_call_results]+ if tool_call_ids != result_ids or not all(tool_call_ids):+ tool_call_results = None++ if content or tool_call_results is not None:+ assistant_message: dict[str, Any] = {"role": "assistant", "content": content or None}+ if tool_call_results is not None:+ assistant_message["tool_calls"] = [+ _tool_call_as_openai_message_tool_call(tool_call) for tool_call in tool_calls.tool_calls+ ]+ messages.append(assistant_message)++ if tool_call_results is not None:+ for result in tool_call_results.tool_call_results:+ content = _tool_result_content(result.value)+ messages.append(+ {"role": "tool", "tool_call_id": result.call_id, "name": result.name, "content": content}+ )+ continue++ assistant_values = message+ if tool_call_field_name is not None and tool_call_results is not None:+ assistant_values = dict(message)+ assistant_values[tool_call_field_name] = tool_calls.model_copy(update={"tool_call_results": None})++ assistant_content = self.format_assistant_message_content(signature, assistant_values)+ if assistant_content:+ messages.append({"role": "assistant", "content": assistant_content})+ if tool_call_results is not None:+ result_input = {"tool_call_results": tool_call_results}+ content = self.format_user_message_content(_TOOL_CALL_RESULTS_SIGNATURE, result_input)+ messages.append({"role": "user", "content": content})+# Remove the history field from the inputsdel inputs[history_field_name]@@ -690,3 +746,28 @@ def _provider_tool_call_to_tool_call_dict(tool_call: Any) -> dict[str, Any]:"name": _provider_value(function, "name") or _provider_value(tool_call, "name"),"args": parsed_arguments,}+++def _tool_calls_from_message(message: dict[str, Any]) -> tuple[str | None, ToolCalls | None]:+ for name, value in message.items():+ if isinstance(value, ToolCalls) or (isinstance(value, dict) and "tool_calls" in value):+ return name, ToolCalls.model_validate(value)+ return None, None+++def _tool_result_content(value: Any) -> str:+ if isinstance(value, str):+ return value++ return json.dumps(serialize_for_json(value), ensure_ascii=False)+++def _tool_call_as_openai_message_tool_call(tool_call: ToolCalls.ToolCall) -> dict[str, Any]:+ return {+ "id": tool_call.id,+ "type": "function",+ "function": {+ "name": tool_call.name,+ "arguments": json.dumps(serialize_for_json(tool_call.args), ensure_ascii=False),+ },+ }diff --git a/dspy/adapters/chat_adapter.py b/dspy/adapters/chat_adapter.pyindex 6f82932db..6992ff9ce 100644--- a/dspy/adapters/chat_adapter.py+++ b/dspy/adapters/chat_adapter.py@@ -44,6 +44,7 @@ class ChatAdapter(Adapter):use_native_function_calling: bool = False,native_response_types: list[type[type]] | None = None,use_json_adapter_fallback: bool = True,+ parallel_tool_calls: bool | None = None,):"""Args:@@ -53,14 +54,25 @@ class ChatAdapter(Adapter):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 usingJSONAdapter. Defaults to True.+ parallel_tool_calls: Whether to request provider-side parallel tool-call generation when native function+ calling is active. If None, the adapter does not set the provider option."""super().__init__(callbacks=callbacks,use_native_function_calling=use_native_function_calling,+ parallel_tool_calls=parallel_tool_calls,native_response_types=native_response_types,)self.use_json_adapter_fallback = use_json_adapter_fallback+ def _make_json_adapter_fallback(self):+ from dspy.adapters.json_adapter import JSONAdapter++ return JSONAdapter(+ use_native_function_calling=self.use_native_function_calling,+ parallel_tool_calls=self.parallel_tool_calls,+ )+def __call__(self,lm: BaseLM,@@ -79,7 +91,7 @@ class ChatAdapter(Adapter):# On LM errors, already using JSONAdapter, or use_json_adapter_fallback is False, we don't want to# retry with a different adapter. Raise the original error instead of the fallback error.raise- return JSONAdapter()(lm, lm_kwargs, signature, demos, inputs)+ return self._make_json_adapter_fallback()(lm, lm_kwargs, signature, demos, inputs)async def acall(self,@@ -99,7 +111,7 @@ class ChatAdapter(Adapter):# On LM errors, already using JSONAdapter, or use_json_adapter_fallback is False, we don't want to# retry with a different adapter. Raise the original error instead of the fallback error.raise- return await JSONAdapter().acall(lm, lm_kwargs, signature, demos, inputs)+ return await self._make_json_adapter_fallback().acall(lm, lm_kwargs, signature, demos, inputs)def format_field_description(self, signature: type[Signature]) -> str:return (diff --git a/dspy/adapters/json_adapter.py b/dspy/adapters/json_adapter.pyindex 1eec5d843..fcc8d3e52 100644--- a/dspy/adapters/json_adapter.py+++ b/dspy/adapters/json_adapter.py@@ -38,9 +38,18 @@ def _has_open_ended_mapping(signature: SignatureMeta) -> bool:class JSONAdapter(ChatAdapter):- def __init__(self, callbacks: list[BaseCallback] | None = None, use_native_function_calling: bool = True):+ def __init__(+ self,+ callbacks: list[BaseCallback] | None = None,+ use_native_function_calling: bool = True,+ parallel_tool_calls: bool | None = None,+ ):# JSONAdapter uses native function calling by default.- super().__init__(callbacks=callbacks, use_native_function_calling=use_native_function_calling)+ super().__init__(+ callbacks=callbacks,+ use_native_function_calling=use_native_function_calling,+ parallel_tool_calls=parallel_tool_calls,+ )def _json_adapter_call_common(self, lm, lm_kwargs, signature, demos, inputs, call_fn):"""Common call logic to be used for both sync and async calls."""diff --git a/dspy/adapters/xml_adapter.py b/dspy/adapters/xml_adapter.pyindex 662b1d286..306c2afcc 100644--- a/dspy/adapters/xml_adapter.py+++ b/dspy/adapters/xml_adapter.py@@ -6,13 +6,10 @@ from pydantic.fields import FieldInfofrom dspy.adapters.chat_adapter import ChatAdapter, FieldInfoWithNamefrom dspy.adapters.utils import format_field_value, translate_field_typefrom dspy.signatures.signature import Signature-from dspy.utils.callback import BaseCallbackclass XMLAdapter(ChatAdapter):- def __init__(self, callbacks: list[BaseCallback] | None = None):- super().__init__(callbacks)- self.field_pattern = re.compile(r"<(?P<name>\w+)>((?P<content>.*?))</\1>", re.DOTALL)+ field_pattern = re.compile(r"<(?P<name>\w+)>((?P<content>.*?))</\1>", re.DOTALL)def format_field_with_value(self, fields_with_values: dict[FieldInfoWithName, Any]) -> str:output = []diff --git a/dspy/clients/openai_format.py b/dspy/clients/openai_format.pyindex 1141aa4df..b6e13e21b 100644--- a/dspy/clients/openai_format.py+++ b/dspy/clients/openai_format.py@@ -93,7 +93,7 @@ def message_to_openai_chat(message: LMMessage) -> dict[str, Any]:if message.role == "assistant":tool_calls = [part for part in message.parts if isinstance(part, LMToolCallPart)]content_parts = [part for part in message.parts if not isinstance(part, LMToolCallPart)]- output["content"] = parts_to_openai_content(content_parts)+ output["content"] = None if tool_calls and not content_parts else parts_to_openai_content(content_parts)if tool_calls:output["tool_calls"] = [assistant_tool_call_to_openai(part) for part in tool_calls]return outputdiff --git a/tests/adapters/test_chat_adapter.py b/tests/adapters/test_chat_adapter.pyindex 8828345be..8fcdeb4f9 100644--- a/tests/adapters/test_chat_adapter.py+++ b/tests/adapters/test_chat_adapter.py@@ -1,3 +1,4 @@+import jsonimport refrom typing import Literalfrom unittest import mock@@ -990,6 +991,64 @@ def test_chat_adapter_format_exact_messages_and_lm_kwargs_with_native_reasoning(expected_lm_kwargs = {"reasoning_effort": "low"}assert lm_kwargs == expected_lm_kwargs++def test_chat_adapter_native_tool_calling_still_enables_native_reasoning():+ class NativeToolReasoningLM(dspy.utils.DummyLM):+ @property+ def supports_function_calling(self):+ return True++ @property+ def supports_reasoning(self):+ return True++ def search(query: str) -> str:+ return query++ class NativeToolReasoningSignature(dspy.Signature):+ question: str = dspy.InputField()+ tools: list[dspy.Tool] = dspy.InputField()+ next_thought: dspy.Reasoning = dspy.OutputField()+ tool_calls: dspy.ToolCalls = dspy.OutputField()++ _, lm_kwargs = format_messages_and_lm_kwargs(+ dspy.ChatAdapter(use_native_function_calling=True),+ NativeToolReasoningSignature,+ [],+ {"question": "Q?", "tools": [dspy.Tool(search)]},+ lm=NativeToolReasoningLM([{}]),+ )++ assert "tools" in lm_kwargs+ assert lm_kwargs["reasoning_effort"] == "low"+++def test_chat_adapter_nonnative_strips_native_tool_kwargs():+ def search(query: str) -> str:+ return query++ class NonNativeToolSignature(dspy.Signature):+ question: str = dspy.InputField()+ tools: list[dspy.Tool] = dspy.InputField()+ tool_calls: dspy.ToolCalls = dspy.OutputField()++ _, lm_kwargs = format_messages_and_lm_kwargs(+ dspy.ChatAdapter(use_native_function_calling=False),+ NonNativeToolSignature,+ [],+ {"question": "Q?", "tools": [dspy.Tool(search)]},+ lm_kwargs={+ "tools": [{"type": "function", "function": {"name": "submit"}}],+ "tool_choice": {"type": "function", "function": {"name": "submit"}},+ "parallel_tool_calls": True,+ },+ )++ assert "tools" not in lm_kwargs+ assert "tool_choice" not in lm_kwargs+ assert "parallel_tool_calls" not in lm_kwargs++def test_chat_adapter_format_exact_messages_with_reasoning_and_code_outputs():python_code = dspy.Code["python"]@@ -1109,6 +1168,465 @@ def test_chat_adapter_format_exact_messages_and_lm_kwargs_with_native_tool_calli"required": ["query", "k"]}}}]}assert lm_kwargs == expected_lm_kwargs++ "adapter",+ [+ dspy.ChatAdapter(use_native_function_calling=True, parallel_tool_calls=True),+ dspy.JSONAdapter(use_native_function_calling=True, parallel_tool_calls=True),+ dspy.XMLAdapter(use_native_function_calling=True, parallel_tool_calls=True),+ ],+)+def test_adapter_native_tool_calling_can_request_parallel_tool_calls(adapter):+ class FunctionCallingLM(dspy.utils.DummyLM):+ @property+ def supports_function_calling(self):+ return True++ def search(query: str) -> str:+ return query++ class NativeToolSignature(dspy.Signature):+ question: str = dspy.InputField()+ tools: list[dspy.Tool] = dspy.InputField()+ tool_calls: dspy.ToolCalls = dspy.OutputField()++ _messages, lm_kwargs = format_messages_and_lm_kwargs(+ adapter,+ NativeToolSignature,+ [],+ {"question": "Q?", "tools": [dspy.Tool(search)]},+ lm=FunctionCallingLM([{}]),+ )++ assert lm_kwargs["tool_choice"] == "auto"+ assert lm_kwargs["parallel_tool_calls"] is True+++def test_adapter_native_tool_calling_respects_lm_kwargs_parallel_tool_call_override():+ class FunctionCallingLM(dspy.utils.DummyLM):+ @property+ def supports_function_calling(self):+ return True++ def search(query: str) -> str:+ return query++ class NativeToolSignature(dspy.Signature):+ question: str = dspy.InputField()+ tools: list[dspy.Tool] = dspy.InputField()+ tool_calls: dspy.ToolCalls = dspy.OutputField()++ _messages, lm_kwargs = format_messages_and_lm_kwargs(+ dspy.ChatAdapter(use_native_function_calling=True, parallel_tool_calls=True),+ NativeToolSignature,+ [],+ {"question": "Q?", "tools": [dspy.Tool(search)]},+ lm_kwargs={"parallel_tool_calls": False},+ lm=FunctionCallingLM([{}]),+ )++ assert lm_kwargs["tool_choice"] == "auto"+ assert lm_kwargs["parallel_tool_calls"] is False+++def test_chat_adapter_native_tool_history_replay():+ class FunctionCallingLM(dspy.utils.DummyLM):+ @property+ def supports_function_calling(self):+ return True++ def search(query: str) -> str:+ """Search for documents."""+ return query++ class NativeToolHistorySignature(dspy.Signature):+ question: str = dspy.InputField()+ history: dspy.History = dspy.InputField()+ tools: list[dspy.Tool] = dspy.InputField()+ next_thought: dspy.Reasoning = dspy.OutputField()+ tool_calls: dspy.ToolCalls = dspy.OutputField()++ tool_call = dspy.ToolCalls.ToolCall(id="call_1", name="search", args={"query": "cats"})+ tool_call_results = dspy.ToolCallResults.from_tool_calls_and_values([tool_call], [{"items": ["cat"]}])+ history = dspy.History(+ messages=[+ {+ "question": "Q1",+ "next_thought": dspy.Reasoning(content="I should search."),+ "tool_calls": dspy.ToolCalls(tool_calls=[tool_call], tool_call_results=tool_call_results),+ }+ ]+ )++ messages, lm_kwargs = format_messages_and_lm_kwargs(+ dspy.ChatAdapter(use_native_function_calling=True),+ NativeToolHistorySignature,+ [],+ {"question": "Q2", "history": history, "tools": [dspy.Tool(search)]},+ lm=FunctionCallingLM([{}]),+ )++ assert messages[1]["role"] == "user"+ assert "Q1" in messages[1]["content"]+ assert messages[2] == {+ "role": "assistant",+ "content": "[[ ## next_thought ## ]]\nI should search.\n\n[[ ## completed ## ]]\n",+ "tool_calls": [+ {+ "type": "function",+ "function": {"name": "search", "arguments": '{"query": "cats"}'},+ "id": "call_1",+ }+ ],+ }+ assert json.loads(messages[2]["tool_calls"][0]["function"]["arguments"]) == {"query": "cats"}+ assert messages[3] == {+ "role": "tool",+ "content": '{"items": ["cat"]}',+ "tool_call_id": "call_1",+ "name": "search",+ }+ assert messages[4]["role"] == "user"+ assert "Q2" in messages[4]["content"]+ assert "history" not in messages[4]["content"]+ assert "tools" not in messages[4]["content"]+ assert "tool_call_results" not in messages[4]["content"]+ assert "None" not in messages[4]["content"]+ assert "tools" in lm_kwargs+++def test_chat_adapter_native_tool_history_replays_parallel_tool_results():+ class FunctionCallingLM(dspy.utils.DummyLM):+ @property+ def supports_function_calling(self):+ return True++ def search(query: str) -> str:+ return query++ class NativeToolHistorySignature(dspy.Signature):+ question: str = dspy.InputField()+ history: dspy.History = dspy.InputField()+ tools: list[dspy.Tool] = dspy.InputField()+ next_thought: dspy.Reasoning = dspy.OutputField()+ tool_calls: dspy.ToolCalls = dspy.OutputField()++ tool_calls = dspy.ToolCalls(+ tool_calls=[+ dspy.ToolCalls.ToolCall(id="call_1", name="search", args={"query": "cats"}),+ dspy.ToolCalls.ToolCall(id="call_2", name="search", args={"query": "dogs"}),+ ]+ )+ tool_call_results = dspy.ToolCallResults.from_tool_calls_and_values(+ tool_calls,+ [{"items": ["cat"]}, {"items": ["dog"]}],+ )+ history = dspy.History(+ messages=[+ {+ "question": "Q1",+ "next_thought": dspy.Reasoning(content="I should search twice."),+ "tool_calls": tool_calls.model_copy(update={"tool_call_results": tool_call_results}),+ }+ ]+ )++ messages, _lm_kwargs = format_messages_and_lm_kwargs(+ dspy.ChatAdapter(use_native_function_calling=True),+ NativeToolHistorySignature,+ [],+ {"question": "Q2", "history": history, "tools": [dspy.Tool(search)]},+ lm=FunctionCallingLM([{}]),+ )++ assert [tool_call["id"] for tool_call in messages[2]["tool_calls"]] == ["call_1", "call_2"]+ assert [+ (message["role"], message["tool_call_id"], message["content"])+ for message in messages[3:5]+ ] == [+ ("tool", "call_1", '{"items": ["cat"]}'),+ ("tool", "call_2", '{"items": ["dog"]}'),+ ]+++def test_chat_adapter_native_tool_history_skips_empty_user_message():+ class FunctionCallingLM(dspy.utils.DummyLM):+ @property+ def supports_function_calling(self):+ return True++ def search(query: str) -> str:+ return query++ class NativeToolHistorySignature(dspy.Signature):+ history: dspy.History = dspy.InputField()+ tools: list[dspy.Tool] = dspy.InputField()+ next_thought: dspy.Reasoning = dspy.OutputField()+ tool_calls: dspy.ToolCalls = dspy.OutputField()++ tool_call = dspy.ToolCalls.ToolCall(id="call_1", name="search", args={"query": "cats"})+ tool_call_results = dspy.ToolCallResults.from_tool_calls_and_values([tool_call], ["cat result"])+ history = dspy.History(+ messages=[+ {+ "tool_calls": dspy.ToolCalls(tool_calls=[tool_call], tool_call_results=tool_call_results),+ }+ ]+ )++ messages, _ = format_messages_and_lm_kwargs(+ dspy.ChatAdapter(use_native_function_calling=True),+ NativeToolHistorySignature,+ [],+ {"history": history, "tools": [dspy.Tool(search)]},+ lm=FunctionCallingLM([{}]),+ )++ assert messages[1]["role"] == "assistant"+ assert messages[1]["content"] is None+ assert messages[2]["role"] == "tool"+++ "tool_call_id, tool_call_results",+ [+ ("call_1", None),+ (+ "call_1",+ dspy.ToolCallResults(+ tool_call_results=[+ dspy.ToolCallResults.ToolCallResult(call_id="other_call", name="search", value="cat result")+ ]+ ),+ ),+ (+ None,+ dspy.ToolCallResults(+ tool_call_results=[+ dspy.ToolCallResults.ToolCallResult(call_id=None, name="search", value="cat result")+ ]+ ),+ ),+ ],+)+def test_chat_adapter_native_tool_history_skips_unmatched_tool_calls(tool_call_id, tool_call_results):+ class FunctionCallingLM(dspy.utils.DummyLM):+ @property+ def supports_function_calling(self):+ return True++ def search(query: str) -> str:+ return query++ class NativeToolHistorySignature(dspy.Signature):+ question: str = dspy.InputField()+ history: dspy.History = dspy.InputField()+ tools: list[dspy.Tool] = dspy.InputField()+ next_thought: dspy.Reasoning = dspy.OutputField()+ tool_calls: dspy.ToolCalls = dspy.OutputField()++ tool_call = dspy.ToolCalls.ToolCall(id=tool_call_id, name="search", args={"query": "cats"})+ tool_calls = dspy.ToolCalls(tool_calls=[tool_call], tool_call_results=tool_call_results)+ history = dspy.History(+ messages=[+ {+ "question": "Q1",+ "next_thought": dspy.Reasoning(content="I should search."),+ "tool_calls": tool_calls,+ }+ ]+ )++ messages, _ = format_messages_and_lm_kwargs(+ dspy.ChatAdapter(use_native_function_calling=True),+ NativeToolHistorySignature,+ [],+ {"question": "Q2", "history": history, "tools": [dspy.Tool(search)]},+ lm=FunctionCallingLM([{}]),+ )++ assert all("tool_calls" not in message for message in messages)+ assert all(message["role"] != "tool" for message in messages)+ assert messages[2]["role"] == "assistant"+ assert "I should search." in messages[2]["content"]+++def test_chat_adapter_format_exact_messages_with_non_native_tool_history():+ def search(query: str) -> str:+ return query++ class ToolHistorySignature(dspy.Signature):+ question: str = dspy.InputField()+ history: dspy.History = dspy.InputField()+ tools: list[dspy.Tool] = dspy.InputField()+ next_thought: str = dspy.OutputField()+ tool_calls: dspy.ToolCalls = dspy.OutputField()++ tool_call = dspy.ToolCalls.ToolCall(id="call_1", name="search", args={"query": "cats"})+ tool_call_results = dspy.ToolCallResults.from_tool_calls_and_values([tool_call], ["cat"])+ history = dspy.History(+ messages=[+ {+ "question": "Q1",+ "next_thought": "I should search.",+ "tool_calls": dspy.ToolCalls(tool_calls=[tool_call], tool_call_results=tool_call_results),+ }+ ]+ )++ messages, lm_kwargs = format_messages_and_lm_kwargs(+ dspy.ChatAdapter(use_native_function_calling=False),+ ToolHistorySignature,+ [],+ {"question": "Q2", "history": history, "tools": [dspy.Tool(search)]},+ )++ expected_messages = [+ {+ "role": "system",+ "content": "Your input fields are:\n"+ "1. `question` (str): \n"+ "2. `history` (History): \n"+ "3. `tools` (list[Tool]):\n"+ "Your output fields are:\n"+ "1. `next_thought` (str): \n"+ "2. `tool_calls` (ToolCalls): \n"+ " Type description of ToolCalls: Tool calls must be a JSON object with `tool_calls`, a list of "+ 'calls. Each call must include `name` and `args`. Example: {"tool_calls": [{"name": "search", '+ '"args": {"query": "cats"}}]}\n'+ "All interactions will be structured in the following way, with the appropriate values filled in.\n"+ "\n"+ "[[ ## question ## ]]\n"+ "{question}\n"+ "\n"+ "[[ ## history ## ]]\n"+ "{history}\n"+ "\n"+ "[[ ## tools ## ]]\n"+ "{tools}\n"+ "\n"+ "[[ ## next_thought ## ]]\n"+ "{next_thought}\n"+ "\n"+ "[[ ## tool_calls ## ]]\n"+ '{tool_calls} # note: the value you produce must adhere to the JSON schema: {"type": "object", '+ '"$defs": {"ToolCall": {"type": "object", "properties": {"args": {"type": "object", '+ '"additionalProperties": true, "title": "Args"}, "name": {"type": "string", "title": "Name"}}, '+ '"required": ["name", "args"], "title": "ToolCall"}}, "properties": {"tool_calls": {"type": "array", '+ '"items": {"$ref": "#/$defs/ToolCall"}, "title": "Tool Calls"}}, "required": ["tool_calls"], "title": '+ '"ToolCalls"}\n'+ "\n"+ "[[ ## completed ## ]]\n"+ "In adhering to this structure, your objective is: \n"+ " Given the fields `question`, `history`, `tools`, produce the fields `next_thought`, "+ "`tool_calls`.",+ },+ {"role": "user", "content": "[[ ## question ## ]]\nQ1"},+ {+ "role": "assistant",+ "content": "[[ ## next_thought ## ]]\n"+ "I should search.\n"+ "\n"+ "[[ ## tool_calls ## ]]\n"+ '{"tool_calls": [{"name": "search", "args": {"query": "cats"}}]}\n'+ "\n"+ "[[ ## completed ## ]]\n",+ },+ {+ "role": "user",+ "content": "[[ ## tool_call_results ## ]]\n"+ '{"tool_call_results": [{"call_id": "call_1", "name": "search", "value": "cat", "is_error": false}]}',+ },+ {+ "role": "user",+ "content": "[[ ## question ## ]]\n"+ "Q2\n"+ "\n"+ "[[ ## tools ## ]]\n"+ '["search. It takes arguments {\'query\': {\'type\': \'string\'}}."]\n'+ "\n"+ "Respond with the corresponding output fields, starting with the field `[[ ## next_thought ## ]]`, then "+ '`[[ ## tool_calls ## ]]` (must be a JSON object like {"tool_calls": [{"name": "...", "args": {...}}]}), and then ending with the '+ "marker for `[[ ## completed ## ]]`.",+ },+ ]+ assert messages == expected_messages+ assert lm_kwargs == {}+++ "adapter",+ [dspy.ChatAdapter(use_native_function_calling=False), dspy.JSONAdapter(use_native_function_calling=False)],+)+def test_non_native_tool_history_remains_text_based(adapter):+ def search(query: str) -> str:+ return query++ class ToolHistorySignature(dspy.Signature):+ question: str = dspy.InputField()+ history: dspy.History = dspy.InputField()+ tools: list[dspy.Tool] = dspy.InputField()+ next_thought: str = dspy.OutputField()+ tool_calls: dspy.ToolCalls = dspy.OutputField()++ tool_call = dspy.ToolCalls.ToolCall(id="call_1", name="search", args={"query": "cats"})+ tool_call_results = dspy.ToolCallResults.from_tool_calls_and_values([tool_call], ["cat"])+ messages = adapter.format(+ ToolHistorySignature,+ [],+ {+ "question": "Q2",+ "history": dspy.History(+ messages=[+ {+ "question": "Q1",+ "next_thought": "I should search.",+ "tool_calls": dspy.ToolCalls(tool_calls=[tool_call], tool_call_results=tool_call_results),+ }+ ]+ ),+ "tools": [dspy.Tool(search)],+ },+ )++ assert all(message["role"] != "tool" for message in messages)+ assert [message["role"] for message in messages[1:]] == ["user", "assistant", "user", "user"]+ assert "Q1" in messages[1]["content"]+ assert "tool_call_results" not in messages[1]["content"]+ assert "tool_calls" in messages[2]["content"]+ assert "[[ ## tool_call_results ## ]]" in messages[3]["content"]+ assert "cat" in messages[3]["content"]+ assert "Q2" not in messages[3]["content"]+ assert "Q2" in messages[4]["content"]+ assert "None" not in messages[3]["content"]+++def test_chat_adapter_format_accepts_custom_history_formatter_returning_messages_only():+ class CustomHistoryAdapter(dspy.ChatAdapter):+ def format_conversation_history(self, signature, history_field_name, inputs):+ del inputs[history_field_name]+ return [{"role": "user", "content": "custom history"}]++ class HistorySignature(dspy.Signature):+ question: str = dspy.InputField()+ history: dspy.History = dspy.InputField()+ answer: str = dspy.OutputField()++ messages = CustomHistoryAdapter().format(+ HistorySignature,+ [],+ {+ "question": "Q2",+ "history": dspy.History(messages=[{"question": "Q1"}]),+ },+ )++ assert messages[1] == {"role": "user", "content": "custom history"}+ assert messages[2]["role"] == "user"+ assert "Q2" in messages[2]["content"]++def test_chat_adapter_format_exact_messages_with_tool_input():def search(query: str, k: int = 3) -> str:"""Search for documents."""@@ -1840,6 +2358,29 @@ def test_chat_adapter_fallback_to_json_adapter_on_exception():assert result == [{"answer": "Paris"}]+def test_chat_adapter_fallback_preserves_native_function_calling_flag():+ signature = dspy.make_signature("question->answer")+ adapter = dspy.ChatAdapter(use_native_function_calling=False)+ seen = {}++ def fake_json_adapter_call(self, lm, lm_kwargs, signature, demos, inputs):+ seen["use_native_function_calling"] = self.use_native_function_calling+ return [{"answer": "Paris"}]++ with mock.patch("litellm.completion") as mock_completion:+ mock_completion.return_value = ModelResponse(+ choices=[Choices(message=Message(content="nonsense"))],+ model="openai/gpt-4o-mini",+ )+ lm = dspy.LM("openai/gpt-4o-mini", cache=False)++ with mock.patch("dspy.adapters.json_adapter.JSONAdapter.__call__", new=fake_json_adapter_call):+ result = adapter(lm, {}, signature, [], {"question": "What is the capital of France?"})++ assert result == [{"answer": "Paris"}]+ assert seen["use_native_function_calling"] is False++def test_chat_adapter_respects_use_json_adapter_fallback_flag():signature = dspy.make_signature("question->answer")adapter = dspy.ChatAdapter(use_json_adapter_fallback=False)@@ -1881,6 +2422,30 @@ async def test_chat_adapter_fallback_to_json_adapter_on_exception_async():assert result == [{"answer": "Paris"}]+async def test_chat_adapter_async_fallback_preserves_native_function_calling_flag():+ signature = dspy.make_signature("question->answer")+ adapter = dspy.ChatAdapter(use_native_function_calling=False)+ seen = {}++ async def fake_json_adapter_acall(self, lm, lm_kwargs, signature, demos, inputs):+ seen["use_native_function_calling"] = self.use_native_function_calling+ return [{"answer": "Paris"}]++ with mock.patch("litellm.acompletion") as mock_completion:+ mock_completion.return_value = ModelResponse(+ choices=[Choices(message=Message(content="nonsense"))],+ model="openai/gpt-4o-mini",+ )+ lm = dspy.LM("openai/gpt-4o-mini", cache=False)++ with mock.patch("dspy.adapters.json_adapter.JSONAdapter.acall", new=fake_json_adapter_acall):+ result = await adapter.acall(lm, {}, signature, [], {"question": "What is the capital of France?"})++ assert result == [{"answer": "Paris"}]+ assert seen["use_native_function_calling"] is False++def test_chat_adapter_toolcalls_native_function_calling():class MySignature(dspy.Signature):question: str = dspy.InputField()@@ -2166,6 +2731,48 @@ def test_tool_call_with_null_content_does_not_raise():assert result[0]["tool_calls"].tool_calls[0].id == "call_1"+def test_tool_call_with_unstructured_content_does_not_raise():+ """Provider tool calls are authoritative even when content is not adapter-formatted."""+ adapter = dspy.ChatAdapter(use_native_function_calling=True)+ original_sig = dspy.Signature(+ "question, tools: list[dspy.Tool] -> next_thought: dspy.Reasoning, tool_calls: dspy.ToolCalls"+ )+ processed_sig = original_sig.delete("tools").delete("tool_calls").delete("next_thought")+ outputs = [+ {+ "text": "I'll search for that now.",+ "tool_calls": [+ {"function": {"name": "search", "arguments": '{"query": "test"}'}, "id": "call_1", "type": "function"}+ ],+ "reasoning_content": "I need a search result.",+ }+ ]++ result = adapter._call_postprocess(processed_sig, original_sig, outputs, None, {})++ assert result[0]["tool_calls"].tool_calls[0].id == "call_1"+ assert result[0]["next_thought"] == dspy.Reasoning(content="I need a search result.")+++def test_tool_call_with_structured_content_preserves_other_outputs():+ adapter = dspy.ChatAdapter(use_native_function_calling=True)+ original_sig = dspy.Signature("question, tools: list[dspy.Tool] -> answer, tool_calls: dspy.ToolCalls")+ processed_sig = original_sig.delete("tools").delete("tool_calls")+ outputs = [+ {+ "text": "[[ ## answer ## ]]\nI should use a tool.\n\n[[ ## completed ## ]]",+ "tool_calls": [+ {"function": {"name": "search", "arguments": '{"query": "test"}'}, "id": "call_1", "type": "function"}+ ],+ }+ ]++ result = adapter._call_postprocess(processed_sig, original_sig, outputs, None, {})++ assert result[0]["answer"] == "I should use a tool."+ assert result[0]["tool_calls"].tool_calls[0].id == "call_1"++def test_provider_tool_calls_preserve_id_and_repair_arguments():adapter = dspy.ChatAdapter(use_native_function_calling=True)sig_cls = dspy.Signature("question, tools: list[dspy.Tool] -> tool_calls: dspy.ToolCalls")diff --git a/tests/adapters/test_json_adapter.py b/tests/adapters/test_json_adapter.pyindex c6769d9e8..c778537bc 100644--- a/tests/adapters/test_json_adapter.py+++ b/tests/adapters/test_json_adapter.py@@ -673,6 +673,55 @@ def test_json_adapter_format_exact_messages_with_tool_calls_output_demo():assert lm_kwargs == expected_lm_kwargs+def test_json_adapter_format_exact_non_native_tool_result_history_field():+ def search(query: str) -> str:+ return query++ class ToolHistorySignature(dspy.Signature):+ question: str = dspy.InputField()+ history: dspy.History = dspy.InputField()+ tools: list[dspy.Tool] = dspy.InputField()+ next_thought: str = dspy.OutputField()+ tool_calls: dspy.ToolCalls = dspy.OutputField()++ tool_call = dspy.ToolCalls.ToolCall(id="call_1", name="search", args={"query": "cats"})+ tool_call_results = dspy.ToolCallResults.from_tool_calls_and_values([tool_call], ["cat"])++ messages, _lm_kwargs = format_messages_and_lm_kwargs(+ dspy.JSONAdapter(use_native_function_calling=False),+ ToolHistorySignature,+ [],+ {+ "question": "Q2",+ "history": dspy.History(+ messages=[+ {+ "question": "Q1",+ "next_thought": "I should search.",+ "tool_calls": dspy.ToolCalls(tool_calls=[tool_call], tool_call_results=tool_call_results),+ }+ ]+ ),+ "tools": [dspy.Tool(search)],+ },+ )++ assert messages[3]["content"] == (+ "[[ ## tool_call_results ## ]]\n"+ '{"tool_call_results": [{"call_id": "call_1", "name": "search", "value": "cat", "is_error": false}]}'+ )+ assert messages[4]["content"] == (+ "[[ ## question ## ]]\n"+ "Q2\n"+ "\n"+ "[[ ## tools ## ]]\n"+ '["search. It takes arguments {\'query\': {\'type\': \'string\'}}."]\n'+ "\n"+ "Respond with a JSON object in the following order of fields: `next_thought`, then "+ '`tool_calls` (must be a JSON object like {"tool_calls": [{"name": "...", "args": {...}}]}).'+ )++def test_json_adapter_passes_structured_output_when_supported_by_model():class OutputField3(pydantic.BaseModel):subfield1: int = pydantic.Field(description="Int subfield 1", ge=0, le=10)diff --git a/tests/adapters/test_xml_adapter.py b/tests/adapters/test_xml_adapter.pyindex ee300ba3c..b0f04f118 100644--- a/tests/adapters/test_xml_adapter.py+++ b/tests/adapters/test_xml_adapter.py@@ -347,6 +347,57 @@ Respond with the corresponding output fields wrapped in XML tags `<answer>`.""",]+def test_xml_adapter_format_exact_non_native_tool_result_history_field():+ def search(query: str) -> str:+ return query++ class ToolHistorySignature(dspy.Signature):+ question: str = dspy.InputField()+ history: dspy.History = dspy.InputField()+ tools: list[dspy.Tool] = dspy.InputField()+ next_thought: str = dspy.OutputField()+ tool_calls: dspy.ToolCalls = dspy.OutputField()++ tool_call = dspy.ToolCalls.ToolCall(id="call_1", name="search", args={"query": "cats"})+ tool_call_results = dspy.ToolCallResults.from_tool_calls_and_values([tool_call], ["cat"])++ messages, _lm_kwargs = format_messages_and_lm_kwargs(+ dspy.XMLAdapter(use_native_function_calling=False),+ ToolHistorySignature,+ [],+ {+ "question": "Q2",+ "history": dspy.History(+ messages=[+ {+ "question": "Q1",+ "next_thought": "I should search.",+ "tool_calls": dspy.ToolCalls(tool_calls=[tool_call], tool_call_results=tool_call_results),+ }+ ]+ ),+ "tools": [dspy.Tool(search)],+ },+ )++ assert messages[3]["content"] == (+ "<tool_call_results>\n"+ '{"tool_call_results": [{"call_id": "call_1", "name": "search", "value": "cat", "is_error": false}]}\n'+ "</tool_call_results>"+ )+ assert messages[4]["content"] == (+ "<question>\n"+ "Q2\n"+ "</question>\n"+ "\n"+ "<tools>\n"+ '["search. It takes arguments {\'query\': {\'type\': \'string\'}}."]\n'+ "</tools>\n"+ "\n"+ "Respond with the corresponding output fields wrapped in XML tags `<next_thought>`, then `<tool_calls>`."+ )++def test_xml_adapter_format_exact_messages_for_two_input_signature():class StringSignature(dspy.Signature):question: str = dspy.InputField()