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__.pyindex 906ef90ae..eb2115183 100644--- a/dspy/predict/__init__.py+++ b/dspy/predict/__init__.py@@ -8,6 +8,7 @@ from dspy.predict.parallel import Parallelfrom dspy.predict.predict import Predictfrom dspy.predict.program_of_thought import ProgramOfThoughtfrom dspy.predict.react import ReAct, Tool+from dspy.predict.react_v2 import ReActV2from dspy.predict.refine import Refinefrom 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.pynew file mode 100644index 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.pynew file mode 100644index 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",+ ]