DSPy: The framework for programming—not prompting—language models
Python
Add interpreter execution instructions (#10136)
Isaac Miller0b93fb148e23
diff --git a/docs/docs/api/modules/RLM.md b/docs/docs/api/modules/RLM.mdindex 81bd276e4..1998e9864 100644--- a/docs/docs/api/modules/RLM.md+++ b/docs/docs/api/modules/RLM.md@@ -111,7 +111,7 @@ $20,000,000| `verbose` | `bool` | `False` | Log detailed execution info || `tools` | `list[Union[Callable, dspy.Tool]]` | `None` | Additional tool functions callable from interpreter code || `sub_lm` | `dspy.LM` | `None` | LM for sub-queries. Defaults to `dspy.settings.lm`. Use a cheaper model here. |-| `interpreter_factory` | `Callable[[], CodeInterpreter]` | `PythonInterpreter` | Creates one interpreter per invocation. RLM shuts down each returned interpreter. |+| `interpreter_factory` | `Callable[[], CodeInterpreter]` | `PythonInterpreter` | Creates one interpreter per invocation. RLM shuts down each returned interpreter. May expose an optional `execution_instructions` string for the action prompt. |## Built-in Tools@@ -201,6 +201,11 @@ rlm = dspy.RLM(RLM creates and shuts down one interpreter from this factory per invocation. It adds invocation-scoped tools to the returned interpreter's mutable `tools` dictionary, so remote sandboxes need a `CodeInterpreter` adapter that supports that protocol. To reuse a caller-owned interpreter, pass it as the first positional argument when calling the module: `rlm(interpreter, context=data, query=query)`. RLM updates its tools and output metadata but does not shut down or restore it. Reuse is supported only for sequential calls to the same RLM instance; use the factory path for concurrency.+If the factory exposes an `execution_instructions` string, RLM adds it to the action predictor's task instructions,+which DSPy adapters place in the system prompt. Optimizers such as GEPA may therefore adapt the execution guidance+along with the rest of the action policy. Factory classes and configured callable provider objects can expose this+metadata; anonymous factories without it continue to use the generic action prompt.+### Custom Sandbox-Serializable InputsFor inputs that should be loaded into the sandbox differently from normal Python values, subclass `dspy.SandboxSerializable`. RLM detects these inputs, sends their serialized payload into the interpreter, runs their setup code, and exposes the reconstructed value under the original input name.diff --git a/docs/docs/api/tools/PythonInterpreter.md b/docs/docs/api/tools/PythonInterpreter.mdindex fdf964760..be4ec2264 100644--- a/docs/docs/api/tools/PythonInterpreter.md+++ b/docs/docs/api/tools/PythonInterpreter.md@@ -23,6 +23,15 @@ DSPy disables ambient `deno.json`, lockfile, `package.json`, and local `node_modrunner. A `package.json` in the current directory or an ancestor therefore cannot redirect the sandbox's pinnedPyodide dependency. No `DENO_NO_PACKAGE_JSON` environment variable is required.+## Execution Instructions++`PythonInterpreter.execution_instructions` describes stable constraints of its Pyodide execution environment. It+is class metadata, so code-generating modules can inspect it without starting Deno or allocating an interpreter.+`RLM` includes these instructions in its action prompt, which adapters render in the model's system prompt.++Custom interpreter factories may expose their own `execution_instructions` string. This metadata is optional; a+factory without it remains valid and uses RLM's generic action prompt.+<!-- START_API_REF -->::: dspy.PythonInterpreterhandler: pythondiff --git a/dspy/predict/rlm.py b/dspy/predict/rlm.pyindex 066b3593b..eb547d1ad 100644--- a/dspy/predict/rlm.py+++ b/dspy/predict/rlm.py@@ -56,7 +56,7 @@ ACTION_INSTRUCTIONS_TEMPLATE = """You are tasked with producing the following ou{output_fields}You have access to a Python REPL environment. Write Python code and it will be executed. You will see the output, then write more code based on what you learned. This is an iterative process.-+{interpreter_rules}Available:- Variables: {inputs} (your input data)- `llm_query(prompt)` - query a sub-LLM (~500K char capacity) for semantic analysis@@ -162,7 +162,8 @@ class RLM(Module):Allows using a different (e.g., cheaper) model for sub-queries.interpreter_factory: Zero-argument callable that creates an interpreter for each forward pass. Thecallable may be invoked concurrently, and DSPy shuts down each interpreter it returns. RLM updates- the returned interpreter's mutable ``tools`` dictionary before execution.+ the returned interpreter's mutable ``tools`` dictionary before execution. The callable may expose+ an ``execution_instructions`` string describing its runtime for the action prompt."""super().__init__()_validate_interpreter_factory(interpreter_factory)@@ -351,10 +352,15 @@ class RLM(Module):# Format tool documentation for user-provided toolstool_docs = self._format_tool_docs(self._user_tools)+ execution_instructions = getattr(self._interpreter_factory, "execution_instructions", "")+ if not isinstance(execution_instructions, str):+ raise TypeError("interpreter_factory.execution_instructions must be a string")+ interpreter_rules = f"\nExecution environment:\n{execution_instructions}\n" if execution_instructions else ""+action_sig = (dspy.Signature({}, task_instructions + ACTION_INSTRUCTIONS_TEMPLATE.format(inputs=inputs_str, final_output_names=final_output_names, output_fields=output_fields,- max_llm_calls=self.max_llm_calls,+ max_llm_calls=self.max_llm_calls, interpreter_rules=interpreter_rules,) + tool_docs).append("variables_info", dspy.InputField(desc="Metadata about the variables available in the REPL"), type_=str).append("repl_history", dspy.InputField(desc="Previous REPL code executions and their outputs"), type_=REPLHistory)diff --git a/dspy/primitives/python_interpreter.py b/dspy/primitives/python_interpreter.pyindex 9c9e671de..815c80b2a 100644--- a/dspy/primitives/python_interpreter.py+++ b/dspy/primitives/python_interpreter.py@@ -343,6 +343,11 @@ class PythonInterpreter:self._pending_large_vars = {}self._session_ended = False+ execution_instructions = (+ "Python runs in Pyodide/WebAssembly. State persists across executions, but subprocesses and native "+ "extensions are unavailable. Host filesystem, environment, and network access require explicit permission."+ )+def _check_session_active(self) -> None:if self._session_ended:raise CodeInterpreterError(diff --git a/tests/predict/snapshots/rlm_python_interpreter_lm_request.json b/tests/predict/snapshots/rlm_python_interpreter_lm_request.jsonnew file mode 100644index 000000000..8dfbe5572--- /dev/null+++ b/tests/predict/snapshots/rlm_python_interpreter_lm_request.json@@ -0,0 +1,48 @@+{+ "model": "snapshot-model",+ "messages": [+ {+ "role": "system",+ "parts": [+ {+ "type": "text",+ "metadata": {},+ "text": "Your input fields are:\n1. `variables_info` (str): Metadata about the variables available in the REPL\n2. `repl_history` (REPLHistory): Previous REPL code executions and their outputs\n3. `iteration` (str): Current iteration number (1-indexed) out of max_iters\nYour output fields are:\n1. `reasoning` (str): Think step-by-step: what do you know? What remains? Plan your next action.\n2. `code` (str): Python code to execute. Use markdown code block format: ```python\\n<code>\\n```\nAll interactions will be structured in the following way, with the appropriate values filled in.\n\n[[ ## variables_info ## ]]\n{variables_info}\n\n[[ ## repl_history ## ]]\n{repl_history}\n\n[[ ## iteration ## ]]\n{iteration}\n\n[[ ## reasoning ## ]]\n{reasoning}\n\n[[ ## code ## ]]\n{code}\n\n[[ ## completed ## ]]\nIn adhering to this structure, your objective is: \n Given the fields `query`, produce the fields `answer`.\n \n You are tasked with producing the following outputs given the inputs `query`:\n - {answer}\n \n You have access to a Python REPL environment. Write Python code and it will be executed. You will see the output, then write more code based on what you learned. This is an iterative process.\n \n Execution environment:\n Python runs in Pyodide/WebAssembly. State persists across executions, but subprocesses and native extensions are unavailable. Host filesystem, environment, and network access require explicit permission.\n \n Available:\n - Variables: `query` (your input data)\n - `llm_query(prompt)` - query a sub-LLM (~500K char capacity) for semantic analysis\n - `llm_query_batched(prompts)` - query multiple prompts concurrently (much faster for multiple queries)\n - `print()` - ALWAYS print to see results\n - `SUBMIT(answer)` - submit final output when done\n - Standard libraries: re, json, collections, math, etc.\n \n IMPORTANT: This is ITERATIVE. Each code block you write will execute, you'll see the output, then you decide what to do next. Do NOT try to solve everything in one step.\n \n 1. EXPLORE FIRST - Look at your data before processing it. Print samples, check types/lengths, understand the structure.\n 2. ITERATE - Write small code snippets, observe outputs, then decide next steps. State persists between iterations.\n 3. VERIFY BEFORE SUBMITTING - If results seem wrong (zeros, empty, unexpected), reconsider your approach.\n 4. USE llm_query FOR SEMANTICS - String matching finds WHERE things are; llm_query understands WHAT things mean.\n 5. MINIMIZE RETYPING (INPUTS & OUTPUTS) - When values are long, precise, or error-prone (IDs, numbers, code, quotes), re-access them via variables and parse/compute in code instead of retyping. Use small, targeted prints to sanity-check, but avoid manual copying when variables can carry the exact value.\n 6. SUBMIT ONLY AFTER SEEING OUTPUTS - SUBMIT ends the current run immediately. If you need to inspect printed output, run it in one step, review the result, then call SUBMIT in a later step.\n \n You have max 50 sub-LLM calls. When done, call SUBMIT() with your output."+ }+ ],+ "name": null,+ "metadata": {}+ },+ {+ "role": "user",+ "parts": [+ {+ "type": "text",+ "metadata": {},+ "text": "[[ ## variables_info ## ]]\n«query: str»\n\n[[ ## repl_history ## ]]\nYou have not interacted with the REPL environment yet.\n\n[[ ## iteration ## ]]\n1/20\n\nRespond with the corresponding output fields, starting with the field `[[ ## reasoning ## ]]`, then `[[ ## code ## ]]`, and then ending with the marker for `[[ ## completed ## ]]`."+ }+ ],+ "name": null,+ "metadata": {}+ }+ ],+ "tools": [],+ "config": {+ "temperature": 0.0,+ "max_tokens": 1000,+ "top_p": null,+ "stop": null,+ "n": null,+ "logprobs": null,+ "response_format": null,+ "reasoning": null,+ "tool_choice": null,+ "cache": {+ "enabled": false,+ "rollout_id": null+ },+ "prompt_cache": null,+ "extensions": {}+ },+ "metadata": {}+}diff --git a/tests/predict/test_rlm.py b/tests/predict/test_rlm.pyindex 09c0ef8ac..405325c92 100644--- a/tests/predict/test_rlm.py+++ b/tests/predict/test_rlm.py@@ -8,9 +8,11 @@ Test organization:import base64from contextlib import contextmanager+from pathlib import Pathimport pytest+import dspyfrom dspy.adapters.types.tool import Toolfrom dspy.predict.rlm import RLM, _strip_code_fencesfrom dspy.primitives.code_interpreter import CodeExecutionError, CodeInterpreterError, FinalOutput@@ -426,6 +428,46 @@ class TestRLMInitialization:class TestRLMInterpreterLifecycle:+ def test_execution_instructions_are_part_of_action_prompt(self):+ class Factory(MockInterpreterFactory):+ execution_instructions = "Use this runtime."++ signature = RLM("query -> answer", interpreter_factory=Factory()).generate_action.signature+ optimized = signature.with_instructions("Optimized instructions")++ assert "Use this runtime." in signature.instructions+ assert optimized.instructions == "Optimized instructions"++ def test_python_interpreter_lm_request_bytes(self):+ class StopLMCall(BaseException):+ pass++ class CapturingLM(dspy.BaseLM):+ forward_contract = "typed_lm"++ def __init__(self):+ super().__init__("snapshot-model", temperature=0.0, max_tokens=1000, cache=False)+ self.request = None++ def forward(self, request):+ self.request = request+ raise StopLMCall++ lm = CapturingLM()+ rlm = RLM("query -> answer", interpreter_factory=PythonInterpreter)++ with pytest.raises(StopLMCall), dspy.context(lm=lm, adapter=dspy.ChatAdapter()):+ rlm.generate_action(+ variables_info=["query: str"],+ repl_history=REPLHistory(),+ iteration="1/20",+ )++ request = lm.request.model_dump_json(indent=2).encode()+ snapshot = Path(__file__).with_name("snapshots") / "rlm_python_interpreter_lm_request.json"++ assert request == snapshot.read_bytes().removesuffix(b"\n")+def test_interpreter_remains_available_as_signature_input(self):factory = MockInterpreterFactory(responses=[FinalOutput({"answer": "CPython"})])rlm = RLM("interpreter -> answer", max_iters=1, interpreter_factory=factory)diff --git a/tests/primitives/test_python_interpreter.py b/tests/primitives/test_python_interpreter.pyindex 2cd28ec95..7f15fca03 100644--- a/tests/primitives/test_python_interpreter.py+++ b/tests/primitives/test_python_interpreter.py@@ -1623,3 +1623,10 @@ def test_base_exceptions_do_not_desync_interpreter():with pytest.raises(CodeExecutionError, match=error_type):interpreter.execute(code)assert interpreter.execute("print('still alive')") == "still alive\n"+++def test_execution_instructions_are_class_metadata():+ interpreter = PythonInterpreter(deno_command=["deno", "run"])++ assert interpreter.execution_instructions == PythonInterpreter.execution_instructions+ assert "Pyodide" in interpreter.execution_instructions