DSPy: The framework for programming—not prompting—language models
Python
fix(RLM): Refactor tools to take list instead of dict and properly serialize None/null values (#9247)
Isaac Miller586156eb9269
diff --git a/dspy/predict/rlm.py b/dspy/predict/rlm.pyindex 3e43e74bc..90b1e16fd 100644--- a/dspy/predict/rlm.py+++ b/dspy/predict/rlm.py@@ -10,7 +10,6 @@ Reference: "Recursive Language Models" (Zhang, Kraska, Khattab, 2025)from __future__ import annotations-import inspectimport loggingimport reimport threading@@ -21,6 +20,7 @@ from typing import TYPE_CHECKING, Any, Callable, Iteratorimport pydanticimport dspy+from dspy.adapters.types.tool import Toolfrom dspy.adapters.utils import parse_value, translate_field_typefrom dspy.primitives.code_interpreter import SIMPLE_TYPES, CodeInterpreter, CodeInterpreterError, FinalOutputfrom dspy.primitives.module import Module@@ -105,7 +105,7 @@ class RLM(Module):max_llm_calls: int = 50,max_output_chars: int = 100_000,verbose: bool = False,- tools: dict[str, Callable[..., str]] | None = None,+ tools: list[Callable] | None = None,sub_lm: dspy.LM | None = None,interpreter: CodeInterpreter | None = None,):@@ -117,7 +117,7 @@ class RLM(Module):max_llm_calls: Maximum sub-LLM calls (llm_query/llm_query_batched) per execution.max_output_chars: Maximum characters to include from REPL output.verbose: Whether to log detailed execution info.- tools: Additional tool functions callable from interpreter code.+ tools: List of tool functions or dspy.Tool objects callable from interpreter code.Built-in tools: llm_query(prompt), llm_query_batched(prompts).sub_lm: LM for llm_query/llm_query_batched. Defaults to dspy.settings.lm.Allows using a different (e.g., cheaper) model for sub-queries.@@ -131,7 +131,7 @@ class RLM(Module):self.verbose = verboseself.sub_lm = sub_lmself._interpreter = interpreter- self._user_tools = tools or {}+ self._user_tools = self._normalize_tools(tools)self._validate_tools(self._user_tools)# Build the action and extract signatures@@ -146,47 +146,55 @@ class RLM(Module):# Reserved tool names that conflict with built-in sandbox functions_RESERVED_TOOL_NAMES = frozenset({"llm_query", "llm_query_batched", "SUBMIT", "print"})- def _validate_tools(self, tools: dict[str, Callable]) -> None:- """Validate user-provided tools have valid names and are callable."""- for name, func in tools.items():+ def _normalize_tools(self, tools: list[Callable] | None) -> dict[str, Tool]:+ """Normalize tools list to a dict of Tool objects keyed by name."""+ if not tools:+ return {}++ if isinstance(tools, dict):+ raise TypeError(+ "tools must be a list, not a dict. "+ "Change tools={'name': func} to tools=[func] "+ "(tool names are inferred from function names, or use dspy.Tool(func, name='custom_name'))"+ )++ def to_tool(func: Callable | Tool) -> Tool:+ if isinstance(func, Tool):+ return func+ if not callable(func):+ raise TypeError(f"Tool {func!r} must be callable, got {type(func).__name__}")+ return Tool(func)++ # List of callables/Tools -> normalize to Tool objects+ tool_list = [to_tool(t) for t in tools]+ return {tool.name: tool for tool in tool_list}++ def _validate_tools(self, tools: dict[str, Tool]) -> None:+ """Validate user-provided tools have valid names."""+ for name, tool in tools.items():if not name.isidentifier():raise ValueError(f"Invalid tool name '{name}': must be a valid Python identifier")if name in self._RESERVED_TOOL_NAMES:raise ValueError(f"Tool name '{name}' conflicts with built-in sandbox function")- if not callable(func):- raise TypeError(f"Tool '{name}' must be callable, got {type(func).__name__}")- def _format_tool_docs(self, tools: dict[str, Callable]) -> str:+ def _format_tool_docs(self, tools: dict[str, Tool]) -> str:"""Format user-provided tools for inclusion in instructions."""if not tools:return ""lines = ["\nAdditional tools available (use these instead of standard library equivalents):"]- for name, func in tools.items():- # Get function signature with return type- try:- sig = inspect.signature(func)- params = []- for p in sig.parameters.values():- if p.annotation != inspect.Parameter.empty:- type_name = getattr(p.annotation, "__name__", str(p.annotation))- params.append(f"{p.name}: {type_name}")- else:- params.append(p.name)- params_str = ", ".join(params)-- # Get return type- if sig.return_annotation != inspect.Parameter.empty:- ret_type = getattr(sig.return_annotation, "__name__", str(sig.return_annotation))- sig_str = f"{name}({params_str}) -> {ret_type}"- else:- sig_str = f"{name}({params_str})"- except (ValueError, TypeError):- sig_str = f"{name}(...)"-- # Get first line of docstring- doc = func.__doc__.strip().split("\n")[0] if func.__doc__ else "No description"- lines.append(f"- `{sig_str}` - {doc}")+ for tool in tools.values():+ # Build signature string from Tool's args+ params = []+ for arg_name, arg_schema in (tool.args or {}).items():+ arg_type = arg_schema.get("type", "Any")+ params.append(f"{arg_name}: {arg_type}")+ params_str = ", ".join(params)+ sig_str = f"{tool.name}({params_str})"++ # Get description with newlines escaped+ desc = (tool.desc or "No description").replace("\n", " ")+ lines.append(f"- `{sig_str}` - {desc}")return "\n".join(lines)@@ -244,7 +252,7 @@ class RLM(Module):return {"llm_query": llm_query, "llm_query_batched": llm_query_batched}@property- def tools(self) -> dict[str, Callable]:+ def tools(self) -> dict[str, Tool]:"""User-provided tools (excludes internal llm_query/llm_query_batched)."""return dict(self._user_tools)@@ -348,7 +356,8 @@ class RLM(Module):def _prepare_execution_tools(self) -> dict[str, Callable]:"""Create fresh LLM tools and merge with user-provided tools."""execution_tools = self._make_llm_tools()- execution_tools.update(self._user_tools)+ # Extract underlying functions from Tool objects for the interpreter+ execution_tools.update({name: tool.func for name, tool in self._user_tools.items()})return execution_toolsdef _inject_execution_context(self, interpreter: CodeInterpreter, execution_tools: dict[str, Callable]) -> None:diff --git a/dspy/primitives/python_interpreter.py b/dspy/primitives/python_interpreter.pyindex a49c99f69..76b685ad5 100644--- a/dspy/primitives/python_interpreter.py+++ b/dspy/primitives/python_interpreter.py@@ -416,17 +416,38 @@ class PythonInterpreter:return "\n".join(assignments) + "\n" + code if assignments else codedef _serialize_value(self, value: Any) -> str:- """Serialize a Python value to a string representation for injection."""+ """Serialize a Python value to a Python literal string for injection.++ Sets and tuples are converted to lists for JSON round-trip compatibility,+ since the sandbox returns values via JSON which doesn't support these types.+ """if value is None:return "None"elif isinstance(value, str):return repr(value)elif isinstance(value, bool):- return str(value)+ # Must check bool before int since bool is a subclass of int+ return "True" if value else "False"elif isinstance(value, (int, float)):return str(value)- elif isinstance(value, (list, dict, tuple, set)):- return json.dumps(self._to_json_compatible(value))+ elif isinstance(value, (list, tuple)):+ # Tuples become lists for JSON compatibility+ items = ", ".join(self._serialize_value(item) for item in value)+ return f"[{items}]"+ elif isinstance(value, dict):+ items = ", ".join(+ f"{self._serialize_value(k)}: {self._serialize_value(v)}"+ for k, v in value.items()+ )+ return f"{{{items}}}"+ elif isinstance(value, set):+ # Sets become sorted lists (or unsorted if mixed types) for JSON compatibility+ try:+ sorted_items = sorted(value)+ except TypeError:+ sorted_items = list(value)+ items = ", ".join(self._serialize_value(item) for item in sorted_items)+ return f"[{items}]"else:raise CodeInterpreterError(f"Unsupported value type: {type(value).__name__}")diff --git a/tests/predict/test_rlm.py b/tests/predict/test_rlm.pyindex 54327c1af..f2f25940c 100644--- a/tests/predict/test_rlm.py+++ b/tests/predict/test_rlm.py@@ -10,6 +10,7 @@ from contextlib import contextmanagerimport pytest+from dspy.adapters.types.tool import Toolfrom dspy.predict.rlm import RLMfrom dspy.primitives.code_interpreter import CodeInterpreterError, FinalOutputfrom dspy.primitives.prediction import Prediction@@ -143,7 +144,7 @@ class TestRLMInitialization:def custom_tool(x: str = "") -> str:return x.upper()- rlm = RLM("context -> answer", max_iterations=5, tools={"custom_tool": custom_tool})+ rlm = RLM("context -> answer", max_iterations=5, tools=[custom_tool])assert "custom_tool" in rlm.toolsassert len(rlm.tools) == 1 # Only user tools, not internal llm_query/llm_query_batched@@ -153,8 +154,9 @@ class TestRLMInitialization:def my_tool() -> str:return "result"+ tool = Tool(my_tool, name=tool_name)with pytest.raises(ValueError, match="must be a valid Python identifier"):- RLM("context -> answer", tools={tool_name: my_tool})+ RLM("context -> answer", tools=[tool])@pytest.mark.parametrize("tool_name", ["llm_query", "SUBMIT", "print"])def test_tool_validation_reserved_names(self, tool_name):@@ -162,14 +164,23 @@ class TestRLMInitialization:def my_tool() -> str:return "result"+ tool = Tool(my_tool, name=tool_name)with pytest.raises(ValueError, match="conflicts with built-in"):- RLM("context -> answer", tools={tool_name: my_tool})+ RLM("context -> answer", tools=[tool])@pytest.mark.parametrize("invalid_value", ["not a function", 123])def test_tool_validation_not_callable(self, invalid_value):"""Test RLM rejects tools that aren't callable."""with pytest.raises(TypeError, match="must be callable"):- RLM("context -> answer", tools={"my_tool": invalid_value})+ RLM("context -> answer", tools=[invalid_value])++ def test_tools_dict_rejected(self):+ """Test RLM rejects dict format for tools with helpful error."""+ def my_tool() -> str:+ return "result"++ with pytest.raises(TypeError, match="tools must be a list, not a dict"):+ RLM("context -> answer", tools={"my_tool": my_tool})def test_optional_parameters(self):"""Test RLM optional parameters and their defaults."""@@ -488,7 +499,7 @@ class TestRLMToolExceptions:CodeInterpreterError("RuntimeError: Tool failed!"),FinalOutput({"answer": "recovered"}),])- rlm = RLM("query -> answer", max_iterations=5, interpreter=mock, tools={"failing_tool": failing_tool})+ rlm = RLM("query -> answer", max_iterations=5, interpreter=mock, tools=[failing_tool])rlm.generate_action = make_mock_predictor([{"reasoning": "Call tool", "code": "failing_tool()"},{"reasoning": "Recover", "code": 'SUBMIT("recovered")'},@@ -584,6 +595,30 @@ class TestPythonInterpreter:)assert "15" in result+ def test_variable_injection_with_none_values(self):+ """Test variable injection with None values in dicts/lists (JSON null -> Python None)."""+ with PythonInterpreter(tools={}) as interp:+ # Test None in dict+ result = interp.execute(+ "print(data['key'] is None)",+ variables={"data": {"key": None, "other": "value"}}+ )+ assert "True" in result++ # Test None in list+ result = interp.execute(+ "print(items[1] is None)",+ variables={"items": [1, None, 3]}+ )+ assert "True" in result++ # Test nested None+ result = interp.execute(+ "print(nested['inner']['value'] is None)",+ variables={"nested": {"inner": {"value": None}}}+ )+ assert "True" in result+def test_tool_call_kwargs(self):"""Test tool call with keyword arguments."""def echo(message: str = "") -> str:@@ -973,7 +1008,7 @@ class TestRLMWithDummyLM:with dummy_lm_context([{"reasoning": "Look up the color of apple", "code": 'color = lookup(key="apple")\nSUBMIT(color)'},]):- rlm = RLM("fruit -> color: str", max_iterations=3, tools={"lookup": lookup})+ rlm = RLM("fruit -> color: str", max_iterations=3, tools=[lookup])result = rlm.forward(fruit="apple")assert result.color == "red"