Skip to content

armgit / dspy

Public Imported from GitHub
0

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.py
index 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, Type
from 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_json
from dspy.clients.base_lm import BaseLM
from 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, LMResponse
from dspy.experimental import Citations
+from dspy.signatures.field import InputField
from dspy.signatures.signature import Signature
from dspy.utils.callback import BaseCallback, with_callbacks
from dspy.utils.exceptions import AdapterParseError
@@ -26,6 +28,7 @@ from dspy.utils.exceptions import AdapterParseError
logger = 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 than
adapter 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_calls
self.native_response_types = native_response_types or _DEFAULT_NATIVE_RESPONSE_TYPES
def __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] = None
elif 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 input
content = 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 input
content = 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 inputs
del 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.py
index 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 using
JSONAdapter. 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.py
index 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.py
index 662b1d286..306c2afcc 100644
--- a/dspy/adapters/xml_adapter.py
+++ b/dspy/adapters/xml_adapter.py
@@ -6,13 +6,10 @@ from pydantic.fields import FieldInfo
from dspy.adapters.chat_adapter import ChatAdapter, FieldInfoWithName
from dspy.adapters.utils import format_field_value, translate_field_type
from dspy.signatures.signature import Signature
-from dspy.utils.callback import BaseCallback
class 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.py
index 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 output
diff --git a/tests/adapters/test_chat_adapter.py b/tests/adapters/test_chat_adapter.py
index 8828345be..8fcdeb4f9 100644
--- a/tests/adapters/test_chat_adapter.py
+++ b/tests/adapters/test_chat_adapter.py
@@ -1,3 +1,4 @@
+import json
import re
from typing import Literal
from 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.py
index 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.py
index 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()