Skip to content

armgit / dspy

Public Imported from GitHub
0

DSPy: The framework for programming—not prompting—language models

Python

feat(predict): add ReActV2 (#9825)

Isaac Miller86826b01f71f
diff --git a/dspy/predict/__init__.py b/dspy/predict/__init__.py
index 906ef90ae..eb2115183 100644
--- a/dspy/predict/__init__.py
+++ b/dspy/predict/__init__.py
@@ -8,6 +8,7 @@ from dspy.predict.parallel import Parallel
from dspy.predict.predict import Predict
from dspy.predict.program_of_thought import ProgramOfThought
from dspy.predict.react import ReAct, Tool
+from dspy.predict.react_v2 import ReActV2
from dspy.predict.refine import Refine
from dspy.predict.rlm import RLM
@@ -21,6 +22,7 @@ __all__ = [
"Predict",
"ProgramOfThought",
"ReAct",
+ "ReActV2",
"Refine",
"RLM",
"Tool",
diff --git a/dspy/predict/react_v2.py b/dspy/predict/react_v2.py
new file mode 100644
index 000000000..c5f4dfecd
--- /dev/null
+++ b/dspy/predict/react_v2.py
@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Callable, get_args
+
+import pydantic
+
+import dspy
+from dspy.adapters.types.tool import Tool, ToolCallResults, ToolCalls
+from dspy.primitives.module import Module
+from dspy.primitives.prediction import Prediction
+from dspy.signatures.signature import ensure_signature
+from dspy.utils.exceptions import AdapterParseError, ContextWindowExceededError
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+ from dspy.signatures.signature import Signature
+
+
+class ReActV2(Module):
+ def __init__(self, signature: type[Signature], tools: list[Callable | Tool], max_iters: int = 20):
+ super().__init__()
+ self.signature = ensure_signature(signature)
+ self.max_iters = max_iters
+
+ user_tools = [tool if isinstance(tool, Tool) else Tool(tool) for tool in tools]
+ self.tools = {tool.name: tool for tool in user_tools}
+ if "submit" in self.tools:
+ raise ValueError("`submit` is reserved by ReActV2 as the final-output tool.")
+ self.tools["submit"] = self._make_submit_tool()
+
+ self.react = dspy.Predict(self._make_react_signature())
+
+ def _make_submit_tool(self) -> Tool:
+ output_fields = self.signature.output_fields
+ output_names = list(output_fields)
+
+ def submit(**kwargs):
+ missing = [name for name in output_names if name not in kwargs]
+ if missing:
+ raise ValueError(f"Missing required final output field(s): {', '.join(missing)}")
+ return {name: kwargs[name] for name in output_names}
+
+ args = {
+ name: _json_schema_for_annotation(field.annotation)
+ for name, field in output_fields.items()
+ }
+ arg_types = {name: field.annotation for name, field in output_fields.items()}
+ return Tool(
+ submit,
+ name="submit",
+ desc="Submit the final outputs for the task.",
+ args=args,
+ arg_types=arg_types,
+ )
+
+ def _make_react_signature(self) -> type[Signature]:
+ fields = {}
+ for name, field in self.signature.input_fields.items():
+ fields[name] = (
+ _optional_annotation(field.annotation),
+ dspy.InputField(desc=field.json_schema_extra.get("desc")),
+ )
+
+ fields["history"] = (dspy.History, dspy.InputField())
+ fields["tools"] = (list[dspy.Tool], dspy.InputField())
+ fields["next_thought"] = (dspy.Reasoning, dspy.OutputField())
+ fields["tool_calls"] = (dspy.ToolCalls, dspy.OutputField())
+
+ inputs = ", ".join(f"`{name}`" for name in self.signature.input_fields)
+ outputs = ", ".join(f"`{name}`" for name in self.signature.output_fields)
+ tool_names = ", ".join(f"`{name}`" for name in self.tools)
+ instructions = "\n".join(
+ [
+ self.signature.instructions,
+ f"You are an Agent. Use the supplied tools to produce {outputs} from {inputs}.",
+ "Call tools when more information is needed.",
+ f"When the final answer is ready, call `submit` with {outputs}.",
+ f"The available tools are: {tool_names}.",
+ ]
+ ).strip()
+
+ return dspy.Signature(fields, instructions)
+
+ def forward(self, **input_args):
+ max_iters = input_args.pop("max_iters", self.max_iters)
+ history = _coerce_history(input_args.pop("history", None))
+ pending_inputs = {name: input_args[name] for name in self.signature.input_fields if name in input_args}
+
+ break_reason = "max_iters"
+ for turn_index in range(max_iters):
+ try:
+ pred = self.react(
+ history=history,
+ tools=list(self.tools.values()),
+ **pending_inputs,
+ )
+ tool_calls = _coerce_tool_calls(getattr(pred, "tool_calls", None))
+ except (AdapterParseError, ValueError) as err:
+ logger.warning("Ending ReActV2 loop after parse failure: %s", _fmt_exc(err))
+ break_reason = "parse_error"
+ break
+ except ContextWindowExceededError:
+ logger.warning("Ending ReActV2 loop after context window exceeded.")
+ break_reason = "context_window_exceeded"
+ break
+
+ if not tool_calls.tool_calls:
+ break_reason = "empty_tool_calls"
+ break
+
+ tool_calls = _ensure_tool_call_ids(tool_calls, turn_index)
+ tool_call_results, final_outputs = self._execute_tool_calls(tool_calls)
+ event = self._history_event(pending_inputs, pred, tool_calls, tool_call_results)
+ if final_outputs is not None:
+ event.update(final_outputs)
+ _append_history_event(history, event)
+ pending_inputs = {}
+
+ if final_outputs is not None:
+ return Prediction(**final_outputs, history=history, termination_reason="submit")
+
+ return self._forced_submit(history, pending_inputs, break_reason, max_iters)
+
+ def _execute_tool_calls(self, tool_calls: ToolCalls) -> tuple[ToolCallResults, dict[str, Any] | None]:
+ values = []
+ is_errors = []
+ final_outputs = None
+
+ for tool_call in tool_calls.tool_calls:
+ if tool_call.name not in self.tools:
+ values.append(f"Unknown tool: {tool_call.name}")
+ is_errors.append(True)
+ continue
+
+ try:
+ value = self.tools[tool_call.name](**(tool_call.args or {}))
+ values.append(value)
+ is_errors.append(False)
+ if tool_call.name == "submit" and isinstance(value, dict):
+ final_outputs = value
+ except Exception as err:
+ values.append(f"Execution error in {tool_call.name}: {_fmt_exc(err)}")
+ is_errors.append(True)
+
+ return ToolCallResults.from_tool_calls_and_values(tool_calls, values, is_errors), final_outputs
+
+ def _history_event(
+ self,
+ pending_inputs: dict[str, Any],
+ pred: Prediction,
+ tool_calls: ToolCalls,
+ tool_call_results: ToolCallResults,
+ ) -> dict[str, Any]:
+ event = dict(pending_inputs)
+ if hasattr(pred, "next_thought") and pred.next_thought is not None:
+ event["next_thought"] = pred.next_thought
+ if tool_calls.tool_calls:
+ if tool_call_results.tool_call_results:
+ tool_calls = tool_calls.model_copy(update={"tool_call_results": tool_call_results})
+ event["tool_calls"] = tool_calls
+ return event
+
+ def _forced_submit(
+ self,
+ history: dspy.History,
+ pending_inputs: dict[str, Any],
+ break_reason: str,
+ turn_index: int,
+ ) -> Prediction:
+ try:
+ pred = self.react(
+ history=history,
+ tools=list(self.tools.values()),
+ config={
+ "tool_choice": {"type": "function", "function": {"name": "submit"}},
+ "reasoning_effort": None,
+ },
+ **pending_inputs,
+ )
+ tool_calls = _ensure_tool_call_ids(_coerce_tool_calls(getattr(pred, "tool_calls", None)), turn_index)
+ except (AdapterParseError, ValueError, ContextWindowExceededError) as err:
+ logger.warning("Forced submit failed: %s", _fmt_exc(err))
+ return Prediction(history=history, termination_reason=break_reason or "failed")
+
+ submit_calls = ToolCalls(tool_calls=[call for call in tool_calls.tool_calls if call.name == "submit"])
+ if not submit_calls.tool_calls:
+ return Prediction(history=history, termination_reason=break_reason or "failed")
+
+ tool_call_results, final_outputs = self._execute_tool_calls(submit_calls)
+ event = self._history_event(pending_inputs, pred, submit_calls, tool_call_results)
+ if final_outputs is not None:
+ event.update(final_outputs)
+ _append_history_event(history, event)
+
+ if final_outputs is not None:
+ return Prediction(**final_outputs, history=history, termination_reason="forced_submit")
+
+ return Prediction(history=history, termination_reason=break_reason or "failed")
+
+
+def _json_schema_for_annotation(annotation: Any) -> dict[str, Any]:
+ try:
+ return pydantic.TypeAdapter(annotation).json_schema()
+ except Exception:
+ return {"type": "string"}
+
+
+def _optional_annotation(annotation: Any) -> Any:
+ if type(None) in get_args(annotation):
+ return annotation
+ try:
+ return annotation | None
+ except TypeError:
+ return annotation
+
+
+def _coerce_history(history: Any) -> dspy.History:
+ if history is None:
+ return dspy.History(messages=[])
+ if isinstance(history, dspy.History):
+ return history
+ return dspy.History.model_validate(history)
+
+
+def _coerce_tool_calls(tool_calls: Any) -> ToolCalls:
+ if tool_calls is None:
+ return ToolCalls(tool_calls=[])
+ return ToolCalls.model_validate(tool_calls)
+
+
+def _ensure_tool_call_ids(tool_calls: ToolCalls, turn_index: int) -> ToolCalls:
+ ensured = []
+ for call_index, tool_call in enumerate(tool_calls.tool_calls):
+ if tool_call.id is None:
+ tool_call = tool_call.model_copy(update={"id": f"call_{turn_index}_{call_index}"})
+ ensured.append(tool_call)
+ return ToolCalls(tool_calls=ensured)
+
+
+def _append_history_event(history: dspy.History, event: dict[str, Any]) -> None:
+ if event:
+ history.messages.append(event)
+
+
+def _fmt_exc(err: BaseException, *, limit: int = 5) -> str:
+ import traceback
+
+ return "\n" + "".join(traceback.format_exception(type(err), err, err.__traceback__, limit=limit)).strip()
diff --git a/tests/predict/test_react_v2.py b/tests/predict/test_react_v2.py
new file mode 100644
index 000000000..6f9bf3dbc
--- /dev/null
+++ b/tests/predict/test_react_v2.py
@@ -0,0 +1,326 @@
+import dspy
+from dspy.dsp.utils.utils import dotdict
+
+
+class ReasoningDummyLM(dspy.utils.DummyLM):
+ @property
+ def supports_reasoning(self):
+ return True
+
+
+def test_react_v2_submit_tool_returns_original_output_fields():
+ react = dspy.ReActV2("question -> answer", tools=[])
+
+ assert react.tools["submit"](answer="Paris") == {"answer": "Paris"}
+ assert "tool_call_results" not in react.react.signature.input_fields
+
+
+def test_react_v2_text_mock_lm_loop_records_inputs_once():
+ def lookup(query: str) -> str:
+ return f"found {query}"
+
+ lm = dspy.utils.DummyLM(
+ [
+ {
+ "next_thought": "I should look this up.",
+ "tool_calls": dspy.ToolCalls.from_dict_list(
+ [{"name": "lookup", "args": {"query": "cats"}}]
+ ),
+ },
+ {
+ "next_thought": "I can answer now.",
+ "tool_calls": dspy.ToolCalls.from_dict_list(
+ [{"name": "submit", "args": {"answer": "found cats"}}]
+ ),
+ },
+ ]
+ )
+
+ with dspy.context(lm=lm, adapter=dspy.ChatAdapter()):
+ pred = dspy.ReActV2("question -> answer", tools=[lookup])(question="cats")
+
+ assert pred.answer == "found cats"
+ assert pred.termination_reason == "submit"
+ assert sum("question" in event for event in pred.history.messages) == 1
+ assert pred.history.messages[0]["tool_calls"].tool_calls[0].id == "call_0_0"
+ assert "tool_call_results" not in pred.history.messages[0]
+ assert pred.history.messages[0]["tool_calls"].tool_call_results.tool_call_results[0].call_id == "call_0_0"
+
+
+def test_react_v2_continuation_omits_missing_original_inputs():
+ def lookup(query: str) -> str:
+ return f"found {query}"
+
+ lm = dspy.utils.DummyLM(
+ [
+ {
+ "next_thought": "I should look this up.",
+ "tool_calls": dspy.ToolCalls.from_dict_list(
+ [{"name": "lookup", "args": {"query": "cats"}}]
+ ),
+ },
+ {
+ "next_thought": "I can answer now.",
+ "tool_calls": dspy.ToolCalls.from_dict_list(
+ [{"name": "submit", "args": {"answer": "found cats"}}]
+ ),
+ },
+ ]
+ )
+
+ with dspy.context(lm=lm, adapter=dspy.ChatAdapter()):
+ pred = dspy.ReActV2("question -> answer", tools=[lookup])(question="cats")
+
+ assert pred.answer == "found cats"
+ second_call_messages = lm.history[1]["messages"]
+ second_current_user_message = second_call_messages[-1]["content"]
+ assert "[[ ## question ## ]]\nNone" not in second_current_user_message
+ assert "[[ ## question ## ]]" not in second_current_user_message
+ assert any("[[ ## question ## ]]\ncats" in message["content"] for message in second_call_messages)
+
+
+def test_react_v2_text_mode_accepts_top_level_tool_arguments():
+ def lookup(query: str) -> str:
+ return f"found {query}"
+
+ lm = dspy.utils.DummyLM(
+ [
+ {
+ "next_thought": "I should look this up.",
+ "tool_calls": {"name": "lookup", "arguments": {"query": "cats"}},
+ },
+ {
+ "next_thought": "I can answer now.",
+ "tool_calls": dspy.ToolCalls.from_dict_list(
+ [{"name": "submit", "args": {"answer": "found cats"}}]
+ ),
+ },
+ ]
+ )
+
+ with dspy.context(lm=lm, adapter=dspy.ChatAdapter(use_native_function_calling=False)):
+ pred = dspy.ReActV2("question -> answer", tools=[lookup])(question="cats")
+
+ assert pred.answer == "found cats"
+ assert pred.termination_reason == "submit"
+ assert pred.history.messages[0]["tool_calls"].tool_calls[0].args == {"query": "cats"}
+
+
+def test_react_v2_text_mode_accepts_wrapped_submit_arguments():
+ lm = dspy.utils.DummyLM(
+ [
+ {
+ "next_thought": "I can answer now.",
+ "tool_calls": {"tool_calls": [{"name": "submit", "arguments": {"answer": "done"}}]},
+ },
+ ]
+ )
+
+ with dspy.context(lm=lm, adapter=dspy.ChatAdapter(use_native_function_calling=False)):
+ pred = dspy.ReActV2("question -> answer", tools=[])(question="cats")
+
+ assert pred.answer == "done"
+ assert pred.termination_reason == "submit"
+
+
+def test_react_v2_unknown_tool_observation_can_continue():
+ lm = dspy.utils.DummyLM(
+ [
+ {
+ "next_thought": "Try a missing tool.",
+ "tool_calls": dspy.ToolCalls.from_dict_list(
+ [{"name": "missing_tool", "args": {"query": "cats"}}]
+ ),
+ },
+ {
+ "next_thought": "Recover with a final answer.",
+ "tool_calls": dspy.ToolCalls.from_dict_list(
+ [{"name": "submit", "args": {"answer": "done"}}]
+ ),
+ },
+ ]
+ )
+
+ with dspy.context(lm=lm, adapter=dspy.ChatAdapter()):
+ pred = dspy.ReActV2("question -> answer", tools=[])(question="cats")
+
+ first_result = pred.history.messages[0]["tool_calls"].tool_call_results.tool_call_results[0]
+ assert first_result.is_error is True
+ assert first_result.call_id == "call_0_0"
+ assert "Unknown tool" in first_result.value
+ assert pred.answer == "done"
+
+
+def test_react_v2_accepts_serialized_history_input():
+ lm = dspy.utils.DummyLM(
+ [
+ {
+ "next_thought": "I can answer.",
+ "tool_calls": dspy.ToolCalls.from_dict_list(
+ [{"name": "submit", "args": {"answer": "done"}}]
+ ),
+ }
+ ]
+ )
+
+ with dspy.context(lm=lm, adapter=dspy.ChatAdapter()):
+ pred = dspy.ReActV2("question -> answer", tools=[])(history={"messages": [{"question": "old"}]})
+
+ assert pred.answer == "done"
+ assert pred.history.messages[0] == {"question": "old"}
+ assert all(event for event in pred.history.messages)
+
+
+def test_react_v2_forced_submit_on_empty_tool_calls():
+ lm = ReasoningDummyLM(
+ [
+ {"next_thought": "No action.", "tool_calls": dspy.ToolCalls(tool_calls=[])},
+ {
+ "next_thought": "Forced final.",
+ "tool_calls": dspy.ToolCalls.from_dict_list(
+ [{"name": "submit", "args": {"answer": "forced"}}]
+ ),
+ },
+ ]
+ )
+
+ with dspy.context(lm=lm, adapter=dspy.ChatAdapter()):
+ pred = dspy.ReActV2("question -> answer", tools=[])(question="cats")
+
+ assert pred.answer == "forced"
+ assert pred.termination_reason == "forced_submit"
+ assert lm.history[0]["kwargs"]["reasoning_effort"] == "low"
+ assert "tool_choice" not in lm.history[1]["kwargs"]
+ assert lm.history[1]["kwargs"].get("reasoning_effort") is None
+
+
+class NativeToolLM(dspy.BaseLM):
+ def __init__(self):
+ super().__init__("native-tool-lm", "chat", 0.0, 1000, True)
+ self.calls = []
+
+ @property
+ def supports_function_calling(self):
+ return True
+
+ def forward(self, prompt=None, messages=None, **kwargs):
+ self.calls.append({"messages": messages, "kwargs": kwargs})
+ if len(self.calls) == 1:
+ tool_call = dotdict(
+ id="call_provider_1",
+ type="function",
+ function=dotdict(name="lookup", arguments='{"query":"cats"}'),
+ )
+ else:
+ tool_call = dotdict(
+ id="call_submit",
+ type="function",
+ function=dotdict(name="submit", arguments='{"answer":"found cats"}'),
+ )
+
+ return dotdict(
+ choices=[
+ dotdict(
+ message=dotdict(content=None, tool_calls=[tool_call]),
+ finish_reason="tool_calls",
+ )
+ ],
+ usage=dotdict(prompt_tokens=0, completion_tokens=0, total_tokens=0),
+ model="native-tool-lm",
+ )
+
+
+class ParallelNativeToolLM(dspy.BaseLM):
+ def __init__(self):
+ super().__init__("parallel-native-tool-lm", "chat", 0.0, 1000, True)
+ self.calls = []
+
+ @property
+ def supports_function_calling(self):
+ return True
+
+ def forward(self, prompt=None, messages=None, **kwargs):
+ self.calls.append({"messages": messages, "kwargs": kwargs})
+ if len(self.calls) == 1:
+ tool_calls = [
+ dotdict(
+ id="call_provider_1",
+ type="function",
+ function=dotdict(name="lookup", arguments='{"query":"cats"}'),
+ ),
+ dotdict(
+ id="call_provider_2",
+ type="function",
+ function=dotdict(name="lookup", arguments='{"query":"dogs"}'),
+ ),
+ ]
+ else:
+ tool_calls = [
+ dotdict(
+ id="call_submit",
+ type="function",
+ function=dotdict(name="submit", arguments='{"answer":"found cats and found dogs"}'),
+ )
+ ]
+
+ return dotdict(
+ choices=[
+ dotdict(
+ message=dotdict(content=None, tool_calls=tool_calls),
+ finish_reason="tool_calls",
+ )
+ ],
+ usage=dotdict(prompt_tokens=0, completion_tokens=0, total_tokens=0),
+ model="parallel-native-tool-lm",
+ )
+
+
+def test_react_v2_native_tool_loop_replays_tool_result_with_provider_id():
+ def lookup(query: str) -> str:
+ return f"found {query}"
+
+ lm = NativeToolLM()
+
+ with dspy.context(lm=lm, adapter=dspy.ChatAdapter(use_native_function_calling=True)):
+ pred = dspy.ReActV2("question -> answer", tools=[lookup])(question="cats")
+
+ assert pred.answer == "found cats"
+ assert pred.history.messages[0]["tool_calls"].tool_calls[0].id == "call_provider_1"
+ assert "tool_call_results" not in pred.history.messages[0]
+ assert pred.history.messages[0]["tool_calls"].tool_call_results.tool_call_results[0].call_id == "call_provider_1"
+ assert any(
+ message["role"] == "tool" and message["tool_call_id"] == "call_provider_1"
+ for message in lm.calls[1]["messages"]
+ )
+
+
+def test_react_v2_native_parallel_tool_calls_are_requested_and_replayed():
+ def lookup(query: str) -> str:
+ return f"found {query}"
+
+ lm = ParallelNativeToolLM()
+
+ with dspy.context(lm=lm, adapter=dspy.ChatAdapter(use_native_function_calling=True, parallel_tool_calls=True)):
+ pred = dspy.ReActV2("question -> answer", tools=[lookup])(question="cats and dogs")
+
+ assert pred.answer == "found cats and found dogs"
+ assert lm.calls[0]["kwargs"]["parallel_tool_calls"] is True
+ assert [call.id for call in pred.history.messages[0]["tool_calls"].tool_calls] == [
+ "call_provider_1",
+ "call_provider_2",
+ ]
+ assert [
+ result.call_id
+ for result in pred.history.messages[0]["tool_calls"].tool_call_results.tool_call_results
+ ] == [
+ "call_provider_1",
+ "call_provider_2",
+ ]
+ assert [
+ message["tool_call_id"]
+ for message in lm.calls[1]["messages"]
+ if message["role"] == "tool"
+ ] == [
+ "call_provider_1",
+ "call_provider_2",
+ ]