DSPy: The framework for programming—not prompting—language models
Python
feat(flex): recommend dspy.ReActV2 in optimizer-authored module guidance (#10265)
Michael I.573cfe707d98
diff --git a/dspy/predict/flex/ctx.py b/dspy/predict/flex/ctx.pyindex d998967f0..e5bc3120e 100644--- a/dspy/predict/flex/ctx.py+++ b/dspy/predict/flex/ctx.py@@ -93,7 +93,7 @@ class FlexContext:if sandboxed:parts.append("This module runs in a sandbox: only the tools listed above may be passed to "- "dspy.ReAct/dspy.RLM (their functions live on the host). A function you define inside "+ "dspy.ReActV2/dspy.RLM (their functions live on the host). A function you define inside ""the module can be called directly in forward, but cannot be handed to those predictors.")return "\n\n".join(parts) if parts else "(no extra context)"diff --git a/dspy/predict/flex/primitives_doc.py b/dspy/predict/flex/primitives_doc.pyindex 7d9dde778..9d37c09c2 100644--- a/dspy/predict/flex/primitives_doc.py+++ b/dspy/predict/flex/primitives_doc.py@@ -5,7 +5,7 @@ implements the user's signature. It has exactly two methods:1) `def __init__(self):` — calls `super().__init__()` and assigns each predictor itneeds to an attribute, e.g. `self.classify = dspy.Predict("text -> label")`.Each predictor is a constructed `dspy.Predict` / `dspy.ChainOfThought` /- `dspy.ReAct` / `dspy.RLM` over a sub-signature string. Define a predictor ONLY+ `dspy.ReActV2` / `dspy.RLM` over a sub-signature string. Define a predictor ONLYfor a step that genuinely needs a language model. If the task needs no LM atall, define no predictors (an `__init__` with just `super().__init__()`).@@ -55,7 +55,7 @@ Available DSPy primitives:- `dspy.ChainOfThought("a -> b")`, like Predict but adds an implicit `reasoning`output field; useful when the answer benefits from explicit step-by-step thought.-- `dspy.ReAct(signature_str, tools=[tool1, tool2])`, multi-step reasoning + tool+- `dspy.ReActV2(signature_str, tools=[tool1, tool2])`, multi-step reasoning + tooluse. `tools` is a list of plain Python callables or `dspy.Tool` instances.- `dspy.RLM("context, query -> output")`, Recursive Language Model: the LLM writes@@ -67,16 +67,16 @@ Available DSPy primitives:calls, default 50), `sub_lm` (cheaper LM for sub-queries), `tools` (extra callablesfor the REPL).-- Tools for `dspy.ReAct` / `dspy.RLM` come from two places:+- Tools for `dspy.ReActV2` / `dspy.RLM` come from two places:(1) any tools listed in the available context, in scope by name — ONLY these provided tools may- be handed to a sub-predictor via `dspy.ReAct(..., tools=[...])` / `dspy.RLM(..., tools=[...])`;+ be handed to a sub-predictor via `dspy.ReActV2(..., tools=[...])` / `dspy.RLM(..., tools=[...])`;and (2) helpers you AUTHOR yourself — when a sub-step needs a capability the provided tools don'tcover (deterministic lookups, parsing/formatting, calculators, validators, retrieval helpers,etc.), define a plain function (with a docstring and type hints) nested inside `forward` and CALLIT DIRECTLY. This code runs in a sandbox, so an authored helper cannot be handed to a bridgedsub-predictor — keep authored helpers to direct calls in `forward`.-- `dspy.Tool(func)`, wraps a callable as a tool (for `ReAct`/`RLM`); usually you can pass the+- `dspy.Tool(func)`, wraps a callable as a tool (for `ReActV2`/`RLM`); usually you can pass thebare function and it is wrapped for you.- `dspy.Prediction(field_a=value_a, field_b=value_b)`, construct the final return@@ -135,7 +135,7 @@ Rules you MUST follow:* `dspy.Predict` for direct, single-call transformations.* `dspy.ChainOfThought` when the answer benefits from explicit step-by-stepreasoning.- * `dspy.ReAct` when external tools must be called during reasoning.+ * `dspy.ReActV2` when external tools must be called during reasoning.* `dspy.RLM` when an input field is a large blob (long document, big JSON,multi-table data) that doesn't fit naturally in a single prompt — RLMlets the LLM explore it iteratively via a sandboxed REPL.diff --git a/dspy/teleprompt/gepa/gepa_flex_utils.py b/dspy/teleprompt/gepa/gepa_flex_utils.pyindex 202559cb2..d3ce5d245 100644--- a/dspy/teleprompt/gepa/gepa_flex_utils.py+++ b/dspy/teleprompt/gepa/gepa_flex_utils.py@@ -74,7 +74,7 @@ class CodeProposalSignature(dspy.Signature):1. ``def __init__(self):`` calling ``super().__init__()`` and assigning the predictors itneeds. Pick the simplest primitive that fits each step: ``dspy.Predict("...")`` for adirect call (the common default), ``dspy.ChainOfThought("...")`` when explicit reasoning- helps, and ``dspy.RLM`` / ``dspy.ReAct`` when the step must call tools or explore a+ helps, and ``dspy.RLM`` / ``dspy.ReActV2`` when the step must call tools or explore alarge/structured input. Assign no predictors at all if the task needs no LM.2. ``def forward(self, **inputs):`` that calls those predictors as ``self.<name>`` andreturns ``dspy.Prediction(<output fields>=...)``.@@ -84,14 +84,14 @@ class CodeProposalSignature(dspy.Signature):Tools are OPTIONAL — use them only when a step genuinely needs one; many good modules are justa ``dspy.Predict`` or two plus plain Python. When you do use tools, they come from two places.(1) Any listed in ``available_context`` are in scope by name — wire the useful ones into- ``dspy.RLM(..., tools=[...])`` / ``dspy.ReAct(..., tools=[...])`` or call them directly+ ``dspy.RLM(..., tools=[...])`` / ``dspy.ReActV2(..., tools=[...])`` or call them directly(reference them by the exact names; do not import or redefine them). If ``available_context``is '(no extra context)', no tools were provided — don't reference any.(2) AUTHOR your own: when a sub-step needs a capability the provided tools don't cover, define adocumented helper nested inside ``forward`` and call it directly. Authored helpers live in thissource, so they are optimized and persisted exactly like the rest of the code. They run in thesandbox and cannot be handed to a bridged sub-predictor, so only the provided tools may be wired- into ``dspy.RLM``/``dspy.ReAct`` via ``tools=[...]``.+ into ``dspy.RLM``/``dspy.ReActV2`` via ``tools=[...]``.Optimize the predictors' INSTRUCTIONS, not just the code structure. Each predictor'snatural-language instructions live in this source — construct a predictor overdiff --git a/tests/flex/test_flex_interpreter.py b/tests/flex/test_flex_interpreter.pyindex 0aa6a1b60..1ed0848f8 100644--- a/tests/flex/test_flex_interpreter.py+++ b/tests/flex/test_flex_interpreter.py@@ -174,6 +174,43 @@ def test_react_kinds_are_bridgeable_and_construct_on_host() -> None:assert not hasattr(agent, "interpreter")+def test_reactv2_constructs_and_runs_through_the_bridge() -> None:+ # primitives_doc recommends dspy.ReActV2 for tool-use steps, so the whole bridged path must+ # work: a shim-style construct payload builds the real agent on the host with the resolved+ # tool, the host LM drives the loop, and the prediction (incl. history) crosses the JSON+ # boundary back to the sandbox.+ def lookup(query: str) -> str:+ """Look things up."""+ return f"found {query}"++ flex = Flex(ShoutSig, tools=[lookup], interpreter_factory=lambda: MockInterpreter())+ inv = bridge._Invocation(flex._bridge, {})+ inv.construct("ReActV2", "question: str -> answer: str", "agent", {"tools": [{bridge.TOOL_MARKER: "lookup"}]})+ agent = inv._predictors["agent"]+ assert isinstance(agent, dspy.ReActV2)+ assert not hasattr(agent, "interpreter") # not a code-executing predictor++ lm = DummyLM([+ {+ "next_thought": "look it up",+ "tool_calls": dspy.ToolCalls.from_dict_list([{"name": "lookup", "args": {"query": "cats"}}]),+ },+ {+ "next_thought": "answer now",+ "tool_calls": dspy.ToolCalls.from_dict_list([{"name": "submit", "args": {"answer": "found cats"}}]),+ },+ ])+ with dspy.context(lm=lm, adapter=dspy.ChatAdapter()):+ fields = inv.call("agent", {"question": "cats"})+ assert fields["answer"] == "found cats"+ assert fields["termination_reason"] == "submit"+ # The agent trace itself round-trips: both loop steps with the tool-call sequence intact.+ tool_sequence = [+ call["name"] for message in fields["history"]["messages"] for call in message["tool_calls"]["tool_calls"]+ ]+ assert tool_sequence == ["lookup", "submit"]++def test_call_runs_predictor_via_host_lm() -> None:flex = _bridged_flex()inv = bridge._Invocation(flex._bridge, {})